Streaming Telemetry Data

Data Stream Types

The DroneDeploy Robotics Portal provides two different types of telemetry stream, each with different Quality of Service characteristics. Understanding the difference between these two mechanisms is key to effective use of the platform:

1. Live Telemetry are used to stream telemetry in real-time 'on demand'. When a client device, such as a web-browser, or another robot, requests a particular item of telemetry, the Agent begins streaming that data immediately. Once the client stops consuming the data, (e.g. when the browser page is closed), the Agent stops streaming the data. Network bandwidth is thus minimised when idle. The transfer is optimised for high frequency and low latency teleoperation, however the data is not persisted: once the data has been received by the client and displayed, it is discarded.
2. Storage Streams are used to define, capture and store specific telemetry from the robot in the background on an ongoing basis. The data is collected continuously, and stored for up to 30 days in the DroneDeploy Robotics Portal to allow later analysis. Storage Stream data is cached locally on the robot; when a connection to the platform is unavailable, the data is retained and is the uploaded to the platform once a connection is re-established. This type of stream focuses on ensuring capture of all data, regardless of connection quality. For more information, refer to Storage Streams.

Data URIs

The Agent makes telemetry data from your robot available, curated as a collection of Message Topics. Each Message Topic is uniquely identified by a Data URI (Uniform Resource Identifier). Data URIs are used to tell the DroneDeploy Robotics Portal which specific piece of telemetry you are interested in.

A Data URI can contain fields to identify a particular robot callsign and project, but you will usually see the URI expressed in its 'local' form, which looks like:

/plugin/topic

The topic's name may itself have slashes in it (very common in ROS), in which case an example might be /ros/odom/pose/pose/orientation. When you view such topics in the Portal UI, the data picker groups these into 'folders' based on the slashes in order to make organisation easier: in the image below, node how the topic /rocos/agent/clock/offset is shown nested inside a series of folders. This behaviour is simply cosmetic, and has no impact on how you make use of the topic in question.

Each Data URI describes a single Message Topic, and the data associated with that Message Topic is conveyed as a series of Telemetry Messages. Each Telemetry Message is associated with a single Message Topic, and contains a payload which is usually a JSON object. The schema of the JSON payload will be consistent between all the Messages belonging to one Topic.

An example Telemetry Message payload is shown below:

// Value of Data URI "/ros/turtle1/pose"
{
  "y": 5.88,
  "x": 7.24,
  "linear_velocity": 0,
  "angular_velocity": 0,
  "theta": 2.044667959213257
}

Binding to Data URIs

A common activity in the DroneDeploy Robotics Portal is to 'bind' a particular UI object to the value of a particular piece of telemetry. For instance, to create a dashboard with a graph showing the linear velocity of a virtual Turtlebot robot, you would first create a 'line graph' dashboard widget, the 'bind' this widget to the Telemetry Message topic named /ros/turtlebot/pose (as seen in the example above).

When you add a new widget to a dashboard screen, the dialogue which appears contains a section which allows the selection of a Telemetry Message to bind against:

In addition to binding to the particular Telemetry Message topic which contains the data of interest, you also need to specify how the data contained in each Telemetry Message should be used. In the case of our example, we specifically want the linear_velocity field of the JSON payload to drive the line in our graph.

The DroneDeploy Robotics Portal uses the concept of a 'value expression' to allow selection and manipulation of a particular piece of data from within a Telemetry Message. Having selected a particular Telemetry Message of interest, that message is available as $msg within the corresponding value expression, and the fields of the message payload are available using dot notation. In our example, we would thus set the value expression to be $msg.linear_velocity, as shown here:

Shaping Telemetry Streams

When binding a URI for a Telemetry stream, you can add a query string on the URI to alter how it sends data. If you do not use a query string, then the Agent will send data using default options, which may be configured in settings (refer to the settings of the telemetry-sender plugin for instance).

Valid query options are listed below:

Parameter	Usage	Example
ttl (Time to Live)	The amount of time a message is allowed to be queued before it is considered expired and is discarded.	ttl=10s
dl (Deadline)	The amount of time the agent will allow a single attempt at sending a message to take. This should be a shorter duration than the the TTL.	dl=100ms
int (Interval)	The minimum desired time between messages, i.e. the sample interval.	int=300ms
txp (Transmission Policy)	The mechanism by which telemetry should be transferred: UNARY - Each message is sent one at a time, with the server confirming successful receipt of each message before the next is sent. This ensures messages are transferred from the robot to the DroneDeploy Robotics Portal reliably, but limits the frequency at which messages may be transferred. FF - 'Fire and Forget' - Messages are sent one after another without waiting for confirmation from the server of each message. This allows for significantly greater messaging frequency, but means it is possible for some messages to be lost in transit before the agent is able to realise the connection has been disrupted.	txp=UNARY
dqp (Dequeuing Policy)	When the agent has accumulated a backlog of telemetry messages waiting to be sent, this determines which message from the backlog should be sent next: FIFO - Messages are always sent in the order they are created; this causes messages to arrive in order, but sometimes lagging behind the newest data. FILO - Newest messages are sent first, then older messages are sent later; this causes message to arrive out of order and sp is only useful in rather specific use cases where you are consuming the telemetry via SDK. LATEST - Messages are sent strictly in order, with priority given to the most recently created; this means you only ever receive the most up to date message for a given topic.	dqp=FIFO

These parameters can be appended to the URI as a query string. For example:

/rosbridge/odom?int=1s&dl=300ms&ttl=2s