The rc_dynamics interface

The rc_dynamics interface offers continuous, real-time data-stream access to rc_visard’s several dynamic state estimates as continuous, real-time data streams. It allows state estimates of all offered types to be configured to be streamed to any host in the network. The Data-stream protocol used is agnostic w.r.t. operating system and programming language.

Starting/stopping dynamic-state estimation

The rc_visard’s dynamic-state estimates are only available if the respective module, i.e., the sensor dynamics module, is turned on. This can be done either in the Web GUI - a respective switch is offered on the Dynamics page - or via the REST-API by using the module’s service calls. A sample curl request to start dynamic-state estimation would look like:

curl -X PUT --header 'Content-Type: application/json' -d '{}' 'http://<host>/api/v1/nodes/rc_dynamics/services/start'

Note

To save computational resources, it is recommended to stop dynamic-state estimation when not needed any longer.

Configuring data streams

Availabe data streams, i.e., dynamic-state estimates, can be listed and configured by the rc_visard’s REST-API, e.g., a list of all available data streams can be requested with GET /datastreams. For a detailed description of the following data streams, please refer to Available state estimates.

Table 62 Available data streams via the rc_dynamics interface

Name	Protocol	Protobuf	Description
dynamics	UDP	Dynamics	Dynamics of sensor (pose, velocity, acceleration) from INS or SLAM (best effort depending on availability) at realtime frequency (IMU rate)
dynamics_ins	UDP	Dynamics	Dynamics of sensor (pose, velocity, acceleration) from stereo INS at realtime frequency (IMU rate)
imu	UDP	Imu	Raw IMU (Inertial Measurement Unit) values at realtime frequency (IMU rate)
pose	UDP	Frame	Pose of left camera from INS or SLAM (best effort depending on availability) at maximum camera frequency (fps)
pose_ins	UDP	Frame	Pose of left camera from stereo INS at maximum camera frequency (fps)
pose_rt	UDP	Frame	Pose of left camera from INS or SLAM (best effort depending on availability) at realtime frequency (IMU rate)
pose_rt_ins	UDP	Frame	Pose of left camera from stereo INS at realtime frequency (IMU rate)

The general procedure for working with the rc_dynamics interface is the following:

1. Request a data stream via REST-API.

   The following sample curl command issues a PUT /datastreams/{stream} request to initiate a stream of type pose_rt from the rc_visard to client host 10.0.1.14 at port 30000:

   curl -X PUT --header 'Content-Type: application/x-www-form-urlencoded' --header 'Accept: application/json' -d 'destination=10.0.1.14:30000' 'http://<host>/api/v1/datastreams/pose_rt'
   

2. Receive and deserialize data.

   With a successful request, the stream is initiated and data of the specified stream type is continuously sent to the client host. According to the Data-stream protocol, the client needs to receive, deserialize and process the data.

3. Stop a requested data stream via REST-API.

   The following sample curl command issues a DELETE /datastreams/{stream} request to delete, i.e., stop, the previously requested stream of type pose_rt with destination 10.0.1.14:30000:

   curl -X DELETE --header 'Accept: application/json' 'http://<host>/api/v1/datastreams/pose_rt?destination=10.0.1.14:30000'
   

   To remove all destinations for a stream, simply omit the destination parameter.

Warning

Data streams can not be deleted automatically, i.e., the rc_visard keeps streaming data even if the client-side is disconnected or has stopped consuming the sent datagrams. A maximum of 10 destinations per stream are allowed. It is therefore strongly recommended to stop data streams via the REST-API when they are or no longer used.

Data-stream protocol

Once a data stream is established, data is continuously sent to the specified client host and port (destination) via the following protocol:

Network protocol:

The only currently supported network protocol is UDP, i.e., data is sent as UDP datagrams.

Data serialization:

The data being sent is serialized via Google protocol buffers. The following message type definitions are used.

• The camera-pose streams and real-time camera-pose streams are serialized using the Frame message type:

  message Frame
  {
    optional PoseStamped pose  = 1;
    optional string parent     = 2; // Name of the parent frame
    optional string name       = 3; // Name of the frame
    optional string producer   = 4; // Name of the producer of this data
  }
  

  The producer field can take the values ins, slam, rt_ins, and rt_slam, indicating whether the data was computed by SLAM or Stereo INS, and is real-time (rt) or not.

• The real-time dynamics stream is serialized using the Dynamics message type:

  message Dynamics
  {
    optional Time timestamp                     = 1; // Time when the data was captured
    optional Pose pose                          = 2;
    optional string pose_frame                  = 3; // Name of the frame that the pose is given in
    optional Vector3d linear_velocity           = 4; // Linear velocity in m/s
    optional string linear_velocity_frame       = 5; // Name of the frame that the linear_velocity is given in
    optional Vector3d angular_velocity          = 6; // Angular velocity in rad/s
    optional string angular_velocity_frame      = 7; // Name of the frame that the angular_velocity is given in
    optional Vector3d linear_acceleration       = 8; // Gravity compensated linear acceleration in m/s²
    optional string linear_acceleration_frame   = 9; // Name of the frame that the acceleration is given in
    repeated double covariance                  = 10 [packed=true]; // Row-major representation of the 15x15 covariance matrix
    optional Frame cam2imu_transform            = 11; // pose of the left camera wrt. the IMU frame
    optional bool possible_jump                 = 12; // True if there possibly was a jump in the pose estimation
    optional string producer                    = 13; // Name of the producer of this data
  }
  

  The producer field can take the values rt_ins and rt_slam, indicating whether the data was computed by SLAM or Stereo INS.

• The IMU stream is serialized using the Imu message type:

  message Imu
  {
    optional Time timestamp                     = 1; // Time when the data was captured
    optional Vector3d linear_acceleration       = 2; // Linear acceleration in m/s² measured by the IMU
    optional Vector3d angular_velocity          = 3; // Angular velocity in rad/s measured by the IMU
  }
  

• The nested types PoseStamped, Pose, Time, Quaternion, and Vector3D are defined as follows:

  message PoseStamped
  {
    optional Time timestamp  = 1; // Time when the data was captured
    optional Pose pose       = 2;
  }
  

  message Pose
  {
    optional Vector3d position      = 1; // Position in meters
    optional Quaternion orientation = 2; // Orientation as unit quaternion
    repeated double covariance      = 3 [packed=true]; // Row-major representation of the 6x6 covariance matrix (x, y, z, rotation about X axis, rotation about Y axis, rotation about Z axis)
  }
  

  message Time
  {
    /// \brief Seconds
    optional int64 sec = 1;
  
    /// \brief Nanoseconds
    optional int32 nsec = 2;
  }
  

  message Quaternion
  {
    optional double x = 2;
    optional double y = 3;
    optional double z = 4;
    optional double w = 5;
  }
  

  message Vector3d
  {
    optional double x = 1;
    optional double y = 2;
    optional double z = 3;
  }
  

rc_dynamics_api

The open-source rc_dynamics_api package provides a simple, convenient C++ wrapper to request and parse rc_dynamics streams, see http://www.roboception.com/download.