Skip to content

Coordinate Frames

Geometry on the wire uses two coordinate frames, and the agent bridges between them for you. This page explains which frame each message uses, when the agent converts, and the one setting you need so local-frame data works. It applies to both local transports (Zenoh and the Unix domain socket) and to every geometry-bearing message.

The two frames

Frame Types Meaning
WGS84 (global) GeoPose, GeoPoint, Wgs84Shape, Wgs84Route Longitude/latitude in decimal degrees, altitude in meters above the ellipsoid, heading in degrees.
Local ENU LocalPose, LocalPoint, LocalShape, LocalRoute A metric tangent plane: x = East, y = North, altitude up in meters, heading in radians (0 at East, counter-clockwise).

The Rover Nexus cloud always speaks WGS84. Your robot software may speak either frame. The agent converts between them using a local origin you configure for the robot (see below), so you can integrate a GPS robot, a locally-localized robot, or one that reports both.

See Common Types → Geometric primitives for the full geometric type definitions.

The local origin

The agent bridges local ENU and WGS84 using a surveyed local origin: a latitude, longitude, and ellipsoid height configured for the robot. This is the datum your local x/y/altitude are measured from.

  • The origin is set by an operator/administrator for the robot, not on the wire, and applies to the whole robot.
  • The agent reads it once at startup. Set it before publishing local-frame data, and restart the agent after changing it.
  • Configuring it is only required if you use the local ENU frame. A robot that reports WGS84 pose and receives WGS84 commands needs no origin.

Note. If you publish local-frame telemetry with no origin configured, the agent drops it (and logs a warning at startup). WGS84 telemetry is never affected. So: if your robot localizes in a local frame, configure the origin first.

You may publish geometry in either frame. Before relaying to the cloud, the agent normalizes everything to WGS84:

  • localMotionTelemetry is converted to a WGS84 globalMotionTelemetry fix (reported with an estimated GPS source). Publish whichever frame you have; you do not need to also send a global fix.
  • Local-frame feature and object geometry is converted to WGS84 in place.
  • WGS84 payloads pass through unchanged.

This is why the messaging reference lists both a global and a local motion message: send whichever your robot produces.

By default the agent delivers command and query-reply geometry in WGS84, exactly as the cloud sent it. If your robot software prefers to receive geometry already in its local frame, set one flag in the robot configuration:

# robot.toml
convert_commands_to_local = true   # default false

When convert_commands_to_local = true and a local origin is configured, the agent converts geometry into your local ENU frame for:

With the flag off (the default), or with no origin configured, downlink geometry stays WGS84. Either way, Pose- and geometry-carrying payloads can arrive in whichever frame you selected, so your handler should read the active union variant rather than assume a frame.

Never converted

These are always passed through as-is, regardless of frame settings:

  • Body-relative commands: velocityCmd and teleopJoy are relative to the robot body, not a map frame, so there is nothing to convert.
  • Non-geometry messages: status, settings, faults, capabilities, and the like carry no coordinates.

Summary

Direction Default With convert_commands_to_local = true + origin
Uplink (you → cloud) Local-frame geometry is converted to WGS84; WGS84 passes through. Local telemetry is dropped if no origin is set. Same (uplink is always normalized to WGS84).
Downlink (cloud → you) Geometry delivered as WGS84. Geometry delivered in your local ENU frame.
velocityCmd / teleopJoy Passed through (body-relative). Passed through (body-relative).