.. _streaming_feedback:

Receiving streaming feedback messages
=========================================

Generally, a streaming application requires the current state and pose of the robot to determine which actions or motions should be commanded. We offer different feedback messages, which are sent via UDP:

- Streaming status
- Cartesian pose
- Joint positions

The following sections define the required steps to receive the desired feedback messages on the host device.

.. _configure_streaming_feedback:

Configure streaming feedback
----------------------------------

To define the type and frequency of messages to be sent, we provide an HTTP API function that forwards the desired settings to the controller.

For details on the payload, refer to :ref:`API - Set Streaming Feedback Properties <set_streaming_feedback_properties>`.

The JSON formatted payload needs to be sent to the following address:
``http://{robot ip}/api/v3.0/set-streaming-feedback-properties`` where ``robot_IP`` depends on the connection mode and configuration chosen when :ref:`connecting the Streaming PC to the CU <connect_to_CU>`.

For an example using the RobFlow SDK, please refer to the :ref:`feedback receiver example <example_receiver>`.

.. dropdown:: Python Example: Set streaming feedback properties

    The following code shows the required API call to define the desired frequency and endpoint for streaming feedback messages.
    
    .. code-block:: python
        :linenos:
        
        def set_streaming_feedback_properties(robot_IP: str, f_status: int, f_cartesian_pose: int, f_joint_pose: int, host_IP: str, host_port: int) -> bool:
            """
                Enables the streaming mode on the robot found at the given IP and defines the settings as desired.
            """

            # URL to the HTTP API
            url = f'http://{robot_IP}/api/v3.0/set-streaming-feedback-properties'

            # Fill the payload of the "start-streaming" message with the desired values
            payload = {
                "frequency_status": f_status,
                "frequency_cartesian_pose": f_cartesian_pose,
                "frequency_joint_pose": f_joint_pose,
                "desired_remote_address": {
                    "address": host_IP
                },
                "desired_remote_port": host_port
            }

            headers = {
                "Content-Type": "application/json",
                "accept": "application/json"
            }

            SUCCESS_RESPONSE_CODE = 200
            TIMEOUT = 10
            try:
                response = requests.put(url, headers=headers, json=payload, timeout=TIMEOUT)
                
                if response.status_code == SUCCESS_RESPONSE_CODE:
                    return True
                else:
                    print(f"Request failed with status code {response.status_code}: {response.text}")
            except Exception as e:
                print("An error occurred:", str(e))

            return False


.. tip::
    For all API messages, you can also view the interactive documentation via RobFlow by opening RobFlow, clicking the menu at the top right corner and selecting "API Documentation".
 

You may verify that the feedback properties were set successfully by accessing the controller logs via ``http://{robot ip}/logs/``.

Receiving streaming feedback
----------------------------------

Once the streaming feedback properties were set, the configured messages will be sent to the specified endpoint.

For information on the message format, refer to the :ref:`feedback messages documentation <feedback_messages>`.

The streaming SDK contains a helper to decode streaming messages in the correct format in `streaming_feedback_messages.py <https://gitlab.com/robco-public/robflow/robflow-sdk/-/blob/main/streaming/streaming_types/streaming_feedback_messages.py?ref_type=heads>`_.

The is also an :ref:`example receiver <example_receiver>` using this and further existing tooling that may be used as reference for custom implementations.