Streaming data from your Rokoko device

This guide will show you how to stream live motion data off your Rokoko device using the RGMP protocol. The rgmp_stream.py example connects to the driver, reads the stream definition, and prints each value as a delimited row you can pipe into other tools.

Normally this data is consumed inside an application that links the SDK, but running the example script is the quickest way to confirm data is flowing and to inspect what the device is sending.

Stream data from your device

1. Connect the device and make sure it is sending data (over USB, or over Wi-Fi after following the Wi-Fi setup guide).

   Note

   If you are streaming data over USB, make sure to start the driver with the --auto-stream-usb argument, as described in the Quick Start guide.

2. Start the SDK driver, as described here:

   rokoko-sdk

3. In another terminal, navigate to the $ROKOKO_SDK_HOME/examples/python folder and run the following command:

   python3 rgmp_stream.py --host 127.0.0.1 --port 12276

This script will connect to the driver and start printing one row per stream value as data arrives. If it cannot connect, it prints an error message and terminates. The script accepts various arguments on the command line; run it with the --help argument to see all available options.

The --host and --port arguments point the script at the RGMP server. The defaults (127.0.0.1 and 12276) match the driver running on the same machine, so you can usually omit them. To read from a driver on another machine, pass its address explicitly.

Reading the output

Status and banner lines are written to stderr, each prefixed with #, so they stay out of the way. The actual data goes to stdout as a #-prefixed header line followed by one row per matched value:

timestamp_us  group  target_frame  reference_frame  measure_type  custom_label  data_type  values

Because the status lines go to stderr and the data to stdout, you can pipe the data straight into standard tools without the banners getting in the way — for example, to grab just the timestamp and values columns:

python3 rgmp_stream.py | cut -f1,8

By default columns are separated by a TAB. Use --separator/--sep to choose another delimiter; it accepts escapes like \t, ,, or |. The values column can hold several numbers, so it uses its own inner separator (a comma, or a semicolon when the column separator is already a comma) to stay a single field.

python3 rgmp_stream.py --sep ,

Filtering the streams

A stream definition usually describes far more data than you want to watch. Three optional filters narrow it down, and they combine — a stream must match all the filters you give:

• --group-name NAME — only streams from this group (exact match).
• --measure-type TYPE — only streams with this measure_type (e.g. POSITION, TRANSFORM, ORIENTATION).
• --target-frame FRAME — only streams for this target_frame (e.g. pelvis).

For example, to watch only the pelvis position:

python3 rgmp_stream.py --measure-type POSITION --target-frame pelvis

Press Ctrl+C to stop streaming. The script prints a status line and closes the socket cleanly.

Tip

Run the script with no filters first to see the full set of streams the device is sending, then add filters to home in on the data you care about.

Epoch motion stamps (experimental)

By default, the timestamp_us field on each data frame is measured from the moment the device started up, so it depends on when that particular device was powered on and timestamps from two devices cannot be compared directly. Starting the driver with the experimental feature flag -ef 1024 stamps data frames against a shared epoch instead, putting all connected devices on the same timeline:

rokoko-sdk -ef 1024

This flag is available from Rokoko driver v1.5.2 and later. You can check the version you have installed with rokoko doctor.

Clients do not have to assume which epoch is in use — it is reported in the stream definition frame. See timestamp_epoch in the RGMP specification.

What this does and does not solve

The stamping is approximate. It does not currently compensate for clock drift or for the latency of the link the data arrives over. That latency is roughly the same for every device on the same kind of physical link — all devices over Wi-Fi, say — so relative timing between Rokoko devices should be good enough to work with. External equipment such as cameras is not covered by this, and will likely still need syncing up by other means.

Note

Timing accuracy is something we are actively working on improving. Treat the current behavior as a first step towards synchronization rather than a finished solution.

Timestamps are not guaranteed to be monotonic

With -ef 1024 the timestamp originates from the host computer’s clock, which is usually kept in sync by NTP. An NTP correction can step that clock, including backwards, so successive frames are not guaranteed to have increasing timestamps. It is your application’s responsibility to account for this — for example by clamping or discarding frames that go back in time.

This breaks the monotonicity requirement of the protocol, which is a known limitation that we are working on a solution for, and the reason the feature is still behind an experimental flag.

Next steps

• Browse the rgmp_stream.py example for the full, annotated source.
• Read the RGMP specification to understand the wire format.
• Review the SDK API Overview.