Data
Data makes it easy to configure streams and collect telemetry data (data points) from ROS in realtime.
How it works
- Create a data stream and provide the robot, the ROS topic (e.g.
my_bot/cmd_vel), the ROS message type (e.g.geometry_msgs/msg/Twist) and the frequency (eg.5hz). - As soon as the robot is online it will start streaming data points that correspond to the data stream.
- Use the the API to query and filter the collected data points.
- Stop the data stream by updating its
enabledstatus or modify the frequency of the data stream with thehzparameter. - Export the data points from the data stream and then delete then data stream and its corresponding data points.
Data streams
All data points belong to a data stream. Data streams are defined by the following:
| Attribute | Description | Example |
|---|---|---|
robot_id | The robot ID the stream is associated with. | my_bot |
source | The ROS topic the data points are collected from. | my_bot/cmd_vel |
type | The ROS message type of the source topic. | geometry_msgs/msg/Twist |
hz | The max frequency that the data points will be streamed at. | 5 |
enabled | Is the data stream currently enabled (ie streaming data points). | true |
Once a data stream is created the robot will immediately begin to start streaming corresponding data points if it is online. If it is not online it will receive the message as soon as it reconnects.
The hz and enabled parameters can be updated after a data stream has been created. Deleting a data stream will automatically delete all of its data points.
Data points
Each data point in a data stream contains a timestamp and payload with a type that matches its stream type.
| Attribute | Example |
|---|---|
timestamp | my_bot/cmd_vel |
payload | {"linear": { "x":1.0, "y":1.0, "z":1.0 }, "angular": { "x":1.0, "y":1.0, "z":1.5 }} |
Querying data
Data points can be queried through the REST API and can be filtered based on the following query params.
| Attribute | Description | Example |
|---|---|---|
robot_id | The robot ID the stream is associated with. | my_bot |
latest_only | Only return the most recently collected data point | true |
from | An ISO timestamp with the lower bound of when a data point was recorded | 2023-08-04T09:00:00.00Z |
to | An ISO timestamp with the upper bound of when a data point was recorded | 2023-08-04T09:15:00.00Z |
limit | Limit the number of data points returned, will truncate oldest messages first. | 200 |
Buffering
The Airbotics agent implements a buffer so that when a robot losses network connectivity it will help prevent data points being dropped. The buffer size is set to 65555 but there may be some slight variation of this depending on if there are other messages waiting to be sent.
As soon as a robot reconnects will send any data points in the buffer. If a buffer overflows the 65555 limit, oldest data points are overwritten by newer data points in a FIFO process.
If you need a 100% guarantee for no data loss we recommend using a ROS bag.
Throttling
Data streams are configured with a hz field which can be used to throttle the rate at which data points are sent. It is important to note that this can lead to dropped data points.
When the agent receives a new data point it will check that at least 1/hz seconds has past before it sends the data point. This means if you have a data stream configured at hz=1 and the agent receives 5 data points per second, it will be dropping 4/5 data points.
On the other hand if your data stream is configured at hz=5 but the agent only receives 1 data point per second, it will be sending the datapoint at 1hz. The hz parameter can be thought of as the maximum frequency.
Remember hz for a data stream can be changed at any time with an API call.