.. _streaming_trajectories:

Trajectory streaming
====================

This guide will cover the necessary steps to stream a trajectory of poses (in joint or Cartesian space) to the robot. 
For specifics of the different modes, please also refer to :ref:`Streaming Modes <streaming_modes>`.

Gather robot state as initial condition
---------------------------------------

Prior to starting streaming, you'll need to get the current robot pose to set as an initial condition for the trajectory to be streamed. Please refer to the section :ref:`Streaming Feedback <streaming_feedback>` for detailed instructions.


Implement a trajectory generation algorithm
-------------------------------------------

This piece of software will be the center piece of any streaming application. A program has to be implemented, that receives or defines a target position to move to, and calculate a trajectory, i.e. a timestamped sequence of poses, to get to that position.

Within the examples section, there is:

- a :ref:`joint streaming example <example_joint_streaming>`, that calculates an offline joint trajectory satisfying the joint limitations
- a :ref:`Cartesian streaming example <example_cartesian_streaming>`, that tracks the live position of a mouse in a GUI window

The following sub-sections, will provide general notes for the different streaming modes.

Streaming trajectory generation: Joint space
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

For both the `Joint Position` and the `Joint Position and Velocity` mode, we expect the underlying trajectories to be feasible, i.e. the jerk, acceleration, velocity and position limits are not exceeded for any joints. 
Please refer to the mode documentation for :ref:`position <mode_joint_pos>` and :ref:`position/velocity <mode_joint_pos_vel>` modes for the respective limits.

Based on these limits, a trajectory needs to be calculated that realizes a smooth transition from the current joint state (position, velocity, acceleration) to the desired state.

Within the examples, we provide a wrapper around the Ruckig library, which calculates smooth joint trajectories.


Streaming trajectory generation: Cartesian space
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

In the Cartesian streaming modes `Cartesian Pose (absolute)` and `Cartesian Pose (relative)`, there are no direct limits in terms of the velocity and acceleration - the controller tries to track the streamed positions as quickly as possible.

However, for safety reasons, if the position or orientation error exceeds the safety margin (see mode documentation 
:ref:`absolute <mode_cartesian_absolute>` / :ref:`relative <mode_cartesian_relative>`)
, the streaming mode is left and the robot stops. 
Therefore, a custom Cartesian trajectory generator should keep track of the current pose and ensure the robot is able to follow the desired trajectory and stays within the error bounds.