Subscribing to a telemetry message - Blueye SDK

Skip to content

# Subscribing to a telemetry message

The drone publishes all of its telemetry data as protobuf encoded messages transmitted via a ZeroMQ socket. You can find the protobuf message definitions in the Protocol Definitions repository, and the generated python definitions are located in the blueye.protocol repository.

Upon connection the Drone object will instantiate an instance of the Telemetry class as the `telemetry` attribute. Using this attribute one can control various telemetry function and add/remove new callbacks.

## Adding a callback

To add a callback we need to use the `add_msg_callback` function, and provide it with a list of telemetry messages types we want it to trigger on, as well as a function handle to call. All available telemetry messages can be found in telemetry.proto

## Removing a callback

A callback is removed with `remove_msg_callback` using the ID returned when creating the callback.

## Adjusting the publishing frequency of a telemetry message

By using the `set_msg_publish_frequency` function we can alter how often the drone should publish the specified telemetry message. The valid frequency range is 0 to 100 Hz.

## Example

The following example illustrates how can use a callback to print the depth reported by the drone.

    """print_depth.py

    This example program demonstrates how one can add a callback function to a telemetry message, as
    well as how to adjust the frequency of that telemetry message, and how to remove the callback.
    """

    import time

    import blueye.protocol as bp

    from blueye.sdk import Drone

    def callback_depth(msg_type: str, msg: bp.DepthTel):
        """Callback for the depth telemetry message

        This function is called once for every DepthTel message received by the telemetry watcher
        """
        print(f"Got a {msg_type} message with depth: {msg.depth.value:.3f}")

    if __name__ == "__main__":
        # Instantiate a drone object
        my_drone = Drone()

        # Add a callback for the DepthTel message, storing the ID for later use
        callback_id = my_drone.telemetry.add_msg_callback([bp.DepthTel], callback_depth)

        # Adjust the publishing frequency to 5 Hz
        my_drone.telemetry.set_msg_publish_frequency(bp.DepthTel, 5)

        # Callback is triggered by a separate thread while we sleep here
        time.sleep(5)

        # Remove the callback using the ID we stored when it was created (not really necessary here
        # since the my_drone object goes out of scope immediately afterwards)
        my_drone.telemetry.remove_msg_callback(callback_id)