Skip to content

Common Types

This page is the shared reference for the structs and enums used by both Uplink Messages (robot → cloud) and Command Messages (cloud → robot). The definitions below are taken directly from the Cap'n Proto schema that defines the wire format (messages.capnp), including its inline comments. That schema is bundled with the client libraries (Rust, Python, C++).

If you are looking for a specific message envelope, start with Uplink Messages or Command Messages and follow the links back here for the shared building blocks.

Conventions

These conventions apply to every message on the wire.

  • Encoding: all messages are Cap'n Proto. Generate bindings from the schema with capnpc, or use a client library (Rust, Python, or C++) directly.
  • Field naming: the schema uses camelCase (e.g. unixTimeMs). Generated Rust bindings use snake_case (unix_time_ms); the serde JSON form uses camelCase. The examples on these pages use the schema's camelCase names.
  • Prose names vs wire identifiers: docs use the product term Field Rules, but the wire schema keeps the original identifiers (SpatialDirective, spatialDirective, the spatial_directives topic segment). Match the schema identifiers exactly in code; only the human-facing term was renamed.
  • Wall-clock time: Int64 milliseconds since the Unix epoch, suffixed Ms (e.g. unixTimeMs, scheduledStartMs). There is no nanosecond form.
  • Durations: suffixed S for seconds (e.g. runtimeRemainingS) or Ms for milliseconds. Durations are not auto-converted.
  • Optional fields: how optionality is signalled depends on the field kind.
    • Pointer fields (Text, Data, List, and struct fields) are natively nullable. An unset pointer is the absent value, and generated readers expose a hasX() accessor for it. There is no separate hasX field. Note the distinction between absent (pointer unset) and present-but-empty ("" or a zero-length list): writing an empty string or list sets the pointer, so it reads back as present.
    • Scalar fields (numbers, Bool, enums) have no null, so an optional scalar foo is paired with a hasFoo : Bool. Only read foo when hasFoo is true, and set hasFoo when you populate foo.
  • Unions: a union is a tagged one-of. Set (and read) exactly one variant.

Geometric primitives

Coordinates come in two frames. WGS84 types (GeoPoint, GeoPose) carry longitude/latitude in decimal degrees; local-frame types (LocalPoint, LocalPose) carry x/y in meters relative to the robot's local datum. Most spatial payloads can use either frame.

# WGS84 2D point: longitude and latitude in decimal degrees.
struct GeoPoint {
  lon @0 :Float64;
  lat @1 :Float64;
}

# Local-frame 2D point: x and y in meters.
struct LocalPoint {
  x @0 :Float64;
  y @1 :Float64;
}

# WGS84 pose: lon/lat in decimal degrees, altitude above ellipsoid, heading.
struct GeoPose {
  lonDeg @0 :Float64;     # decimal degrees
  latDeg @1 :Float64;     # decimal degrees
  altitudeM @2 :Float64;  # HAE: meters above ellipsoid, roughly sea level
  headingDeg @3 :Float64; # 0 = north, clockwise
}

# Local-frame pose: x/y in meters, altitude up from datum, heading in radians.
struct LocalPose {
  x @0 :Float64;          # meters
  y @1 :Float64;          # meters
  altitudeM @2 :Float64;  # meters up from datum
  headingRad @3 :Float64; # 0 = east, counter-clockwise
}

# Pose - a WGS84 (GeoPose) or local-frame (LocalPose) pose.
struct Pose {
  union {
    geoPose @0 :GeoPose;
    localPose @1 :LocalPose;
  }
}

# Body-frame velocity.
struct VelTwist {
  forwardMps @0 :Float32;    # meters / second
  angularRadps @1 :Float32;  # radians / second
}

# Course-over-ground velocity vector (used for tracked objects).
struct Trajectory {
  speedMps @0 :Float64;        # scalar, meters / second
  courseDeg @1 :Float64;       # degrees, 0 = north (direction of travel, not heading)
  verticalRateMps @2 :Float64; # m/s, positive = ascending (drones only)
}

Pose is the union type used where a location can be given in either frame (for example a tracked Object). Note the two heading conventions: GeoPose.headingDeg is 0 at north and increases clockwise, while LocalPose.headingRad is 0 at east and increases counter-clockwise.

Values and settings

Value is a tagged scalar used wherever a setting or sensor reading can be one of several types. SettingUpdate is a single key/value patch.

struct Value {
  union {
    string @0 :Text;
    int @1 :Int32;
    number @2 :Float64;
    bool @3 :Bool;
    enum @4 :Text;   # the selected option, as a bare string
  }
}

# UI <-> Robot: user changing a setting. This is always a patch message.
struct SettingUpdate {
  key @0 :Text;
  value @1 :Value;
}

Asset identity

Every reusable spatial asset (a feature or a tracked object) carries an AssetIdentity.

struct AssetIdentity {
  id @0 :Text;      # persistent id of the shape or route
  name @1 :Text;    # display/debug only
  rev @2 :UInt32;   # 0 means not provided
  hash @3 :Text;    # empty string means not provided
}

Spatial features (shapes and routes)

A spatial feature is geometry plus identity and classification. The geometry itself is a SpatialData union: a shape (areas / points / lines) or a route (waypoints / paths), in either a WGS84 or a local frame. A Feature is used inline in mission commands, in the updateFeature command, and inside field rules.

# Feature - user-defined / server-to-robot spatial feature (shape or route).
struct Feature {
  identity @0 :AssetIdentity;
  layerRole @1 :LayerRole;
  scope @2 :ScopeType;
  data @3 :SpatialData;
  expiresAtMs @4 :Int64;  # Unix time (ms) to discard the feature
  # Height rules (optional): treat the area as an extruded prism for bridges,
  # parking decks, ramps, etc.
  minZM @5 :Float64;
  maxZM @6 :Float64;
  levelId @7 :Int32;  # for multi-storey sites; default 0
}
Field Type Notes
identity AssetIdentity Persistent id, name, revision, hash.
layerRole LayerRole What the feature means (keepout, target, work area, …).
scope ScopeType Who the feature is for.
data SpatialData The geometry (shape or route, WGS84 or local).
expiresAtMs Int64 Epoch ms after which to discard the feature.
minZM / maxZM Float64 Vertical extent, meters, for treating the area as an extruded prism. Always present. There is no hasMinZM / hasMaxZM on a server-sent Feature.
levelId Int32 Map level for multi-storey sites. Always present. Defaults to 0.

SpatialData

SpatialData is the geometry union. It selects a frame (WGS84 or local) and a kind (shape or route); each of those is itself a union of geometry variants.

# SpatialData - shape or route geometry in either a WGS84 or local frame.
struct SpatialData {
  union {
    wgs84Shape @0 :Wgs84Shape;
    wgs84Route @1 :Wgs84Route;
    localShape @2 :LocalShape;
    localRoute @3 :LocalRoute;
  }
}

# WGS84 shape geometry (2D, lon/lat).
struct Wgs84Shape {
  union {
    point @0 :GeoPoint;
    multiPoint @1 :List(GeoPoint);
    lineString @2 :List(GeoPoint);
    multiLineString @3 :List(List(GeoPoint));
    polygon @4 :Wgs84PolygonData;
    multiPolygon @5 :List(Wgs84PolygonData);
  }
}

# WGS84 route geometry (poses with heading/altitude).
struct Wgs84Route {
  union {
    waypoint @0 :GeoPose;
    multiWaypoint @1 :List(GeoPose);
    path @2 :List(GeoPose);
    multiPath @3 :List(List(GeoPose));
  }
}

# Local-frame shape geometry (2D, x/y meters).
struct LocalShape {
  union {
    point @0 :LocalPoint;
    multiPoint @1 :List(LocalPoint);
    lineString @2 :List(LocalPoint);
    multiLineString @3 :List(List(LocalPoint));
    polygon @4 :LocalPolygonData;
    multiPolygon @5 :List(LocalPolygonData);
  }
}

# Local-frame route geometry (poses with heading/altitude).
struct LocalRoute {
  union {
    waypoint @0 :LocalPose;
    multiWaypoint @1 :List(LocalPose);
    path @2 :List(LocalPose);
    multiPath @3 :List(List(LocalPose));
  }
}

struct Wgs84PolygonData {
  exterior @0 :List(GeoPoint);
  holes @1 :List(List(GeoPoint));
}

struct LocalPolygonData {
  exterior @0 :List(LocalPoint);
  holes @1 :List(List(LocalPoint));
}

Shape vs route. A shape (Wgs84Shape / LocalShape) is bare 2D geometry (points, lines, polygons). A route (Wgs84Route / LocalRoute) is a sequence of poses (waypoints / paths) that carry heading and altitude. Polygons carry an exterior ring plus optional holes.

Robot-reported features

When the robot reports a feature back to the cloud (for example an area it covered or a hazard it found), it uses ReportedFeature. It carries the same SpatialData geometry as a Feature, plus a LayerRole, a scope, and an expiry, but is keyed by a human-readable name rather than a full AssetIdentity. Robot-reported features are delivered inside a ReportedFeatureUpdate on the feature uplink.

# ReportedFeature - robot-reported spatial feature. If the scope is world or
# fleet, it is forwarded to all robots in the fleet.
struct ReportedFeature {
  name @0 :Text;  # human readable, display only
  layerRole @1 :LayerRole;
  scope @2 :ScopeType;  # Rover Nexus gates this and can override
  data @3 :SpatialData;
  expiresAtMs @4 :Int64;  # Unix time (ms) to discard the feature
  # Height rules (optional): treat the area as an extruded prism for bridges,
  # parking decks, ramps, etc.
  minZM @5 :Float64;
  hasMinZM @6 :Bool;
  maxZM @7 :Float64;
  hasMaxZM @8 :Bool;
  levelId @9 :Int32;  # for multi-storey sites
  hasLevelId @10 :Bool;
}

On a robot-reported feature the same three height values are optional scalars: read minZM, maxZM, and levelId only when the matching has* flag is true. A server-sent Feature always carries the three values and has no presence flags.

Field rules

A field rule is a persistent zone: a Feature plus timing, parameters, and the actions to apply while inside or at the zone. It is distinct from a bare Feature (geometry only) and from a MissionCommand (a one-shot mission order). See Command Messages → spatialDirective.

# SpatialDirective - a persistent zone (geometry + active rules) sent from
# fleet to robot.
struct SpatialDirective {
  directiveId @0 :Text;  # UUID, given by fleet manager
  name @1 :Text;         # display name
  startTimeMs @2 :Int64; # when it should start being applied
  expireTimeMs @3 :Int64;  # when it should expire
  hasExpireTimeMs @4 :Bool;
  zoneParameters @5 :List(SettingUpdate);
  capabilities @6 :List(Text);  # action names to apply in or on this zone
  spatial @7 :Feature;
  revision @8 :UInt64;  # monotonically increases for each update
  enabled @9 :Bool = true;  # whether the directive should be evaluated and applied
  entryAllowed @10 :Bool = true;  # whether the robot may enter the area
}
Field Type Notes
directiveId Text Field rule id, assigned by the fleet manager.
name Text Display name.
startTimeMs Int64 Epoch ms when the rule starts being applied.
expireTimeMs / hasExpireTimeMs Int64 Optional epoch ms when the rule expires.
zoneParameters List(SettingUpdate) Settings applied while the robot is in the zone.
capabilities List(Text) Action names to apply in or on the zone.
spatial Feature The zone geometry.
revision UInt64 Increases with each update of this id. Defaults to 0 when omitted. The agent ignores an upsert whose revision is older than the one it already accepted. An equal or newer revision replaces it.
enabled Bool Whether the agent should evaluate and apply the rule. Defaults to true, including on payloads written before this field existed. false is not evaluated. Turning it off while the robot is inside runs the exit path once.
entryAllowed Bool Whether the robot may enter the area. Defaults to true. false closes the zone: the agent can pause the robot as it approaches and report entryRequested until the robot leaves. Setting it back to true releases that pause when no other closed zone is still holding the robot. A robot already inside is not paused for that zone. A server resume also clears the hold.

The capabilities list holds action names: entries matching the name of an ActionDescriptor the robot advertises. The field kept its original name on the wire.

The agent evaluates enabled polygon and multipolygon rules. On entry it applies zoneParameters and invokes the named actions. On exit it restores the settings it changed and turns setBool actions off. Robot software can still publish its own spatialDirectiveStatus.

Tracked objects

An Object is a tracked entity in the world (a person, vehicle, obstacle, etc.) with a location, motion, and radius. Objects flow both directions: the robot can report what it detects, and the cloud can push objects to the robot.

# Object - uses milliseconds for time fields. Specifically for object tracking.
struct Object {
  identity @0 :AssetIdentity;
  unixTimeMs @1 :Int64;   # time of most recent detection
  expiresAtMs @2 :Int64;  # Unix time (ms) to discard the object
  scope @3 :ScopeType;  # robot/user send to fleet manager; fleet/world send to all robots in fleet
  objectType @4 :ObjectType;
  pose @5 :Pose;
  trajectory @6 :Trajectory;  # 3D velocity vector
  radiusM @7 :Float64;  # meters
}

Operation wrappers (upsert / delete)

Spatial assets and objects are delivered as operations. Most are an upsert (create-or-replace by id) or a delete (remove by id); upserts are idempotent, so re-sending the same id overwrites the previous value. Robot-reported features are the exception: they upsert or clear (there is one feature per producer channel, so there is no id to delete).

# Server -> robot: a bare Feature (geometry only).
struct FeatureOp {
  union {
    upsert @0 :Feature;
    delete @1 :Text;  # id to delete
  }
}

# Server -> robot: a SpatialDirective (persistent zone with rules).
struct SpatialDirectiveOp {
  union {
    upsert @0 :SpatialDirective;
    delete @1 :Text;  # id to delete
  }
}

# Both directions: a tracked Object.
struct ObjectOp {
  union {
    upsert @0 :Object;
    delete @1 :Text;  # id to delete
  }
}

# Robot -> server: report or clear a feature for one producer channel.
struct ReportedFeatureOp {
  union {
    upsert @0 :ReportedFeature;  # replace the whole feature for this producer/resource
    clear @1 :Void;              # clear/delete the whole feature for this producer/resource
  }
}

# Robot -> server feature/resource update for a producer channel.
struct ReportedFeatureUpdate {
  resourceProducerId @0 :Text;  # the producer channel this update belongs to
  timestampMs @1 :Int64;
  op @2 :ReportedFeatureOp;
}

A ReportedFeatureUpdate ties a ReportedFeatureOp to the resourceProducerId channel the robot declared in its capabilities manifest. Each producer channel holds at most one feature at a time.

Enumerations

ScopeType

Determines how a message is propagated through the fleet, that is, who the intended recipient is.

Value Meaning
robot This robot only.
fleet All robots in the fleet.
world Global.
user A specific user.

For robot-reported features and objects, robot/user are sent only to the fleet manager, while fleet/world are forwarded to all robots in the fleet.

RobotMode

Operational mode of the robot. E-stop is reported separately on StatusTelemetry.estop; fault conditions are reported separately as the fault uplink. RobotMode covers only the active operating mode.

Value Meaning
manual Operated locally / by hand.
auto Running autonomously.
teleop Driven remotely (teleoperation).
disabled Powered but not operating.
maintenance Out of service for maintenance.

MissionStatus

Lifecycle state of a mission run, reported on missionRunStatus.

Value Meaning
accepted The robot took the mission and will run it.
rejected The robot refused the mission. Terminal.
running Actively executing.
paused Paused, resumable.
blocked Cannot proceed (waiting on a condition).
aborted Stopped before completion. Terminal.
failed Failed. Terminal.
completed Finished successfully. Terminal.
lost Contact with the run was lost; its outcome is unknown.

completed, aborted, rejected, and failed are terminal: the run has finished and will not progress further. All other states (including paused, blocked, and lost) are non-terminal, so a run can still advance out of them.

Report the terminal state on missionRunStatus.status. Timing on that message is elapsed and remaining duration, not a completion timestamp.

GnssSource

Origin of the position on GlobalMotionTelemetry. The field is optional. Leave hasGnssSource false when you did not measure a source. That absence is unreported, and it is not real.

Value Meaning
real Actual hardware fix.
simulated Running in a simulator, no real hardware.
estimated Hardware lost lock, using dead reckoning or an IMU. The agent sets this when it converts local odometry to WGS84.

GnssSource replaces the older GpsSource enum. The three values are the same. What changed is that the field is now optional.

GnssFixType

How the GNSS position was computed for this epoch. It lives on GnssQuality, not directly on the motion message. unknown means the value was not provided. The parentheticals are the usual source mappings (NMEA GGA quality, MAVLink GPS_FIX_TYPE, u-blox NAV-PVT).

Value Meaning
unknown Not provided.
noFix Receiver present, no usable position (NMEA 0).
autonomous Unaugmented single-point, meter-class (NMEA 1, MAV 3D).
dgnss Code differential or SBAS/WAAS (NMEA 2, MAV DGPS).
ppp Precise Point Positioning.
rtkFloat Carrier phase, ambiguities not integer-fixed (NMEA 5).
rtkFixed Carrier phase, integer ambiguities fixed (NMEA 4).

The older GpsFixType enum (invalid, gps, dgps, sbas, floatRtk, fixedRtk, pps, gbas) was removed. There is no ordinal-compatible replacement. Fix quality is now this enum inside an optional GnssQuality.

FixDimension

Whether altitude was solved for this epoch. Carried on GnssQuality.

Value Meaning
unknown Not provided.
twoD Altitude held, or not solved.
threeD Altitude solved.

HeadingSource

Where the heading on a motion sample came from. Required on both globalMotionTelemetry and localMotionTelemetry. There is no hasHeadingSource flag. Use unknown when you have not classified it.

Value Meaning
unknown Not classified.
courseOverGround GNSS velocity direction. Poor when the robot is nearly stopped.
dualAntenna GNSS compass. Valid at zero speed.
imuFused INS or EKF yaw.
magnetometer Magnetic heading.

GnssQuality

Optional quality block on GlobalMotionTelemetry. Leave the struct pointer unset when you have no quality to report. A present struct whose satellitesUsed, hdop, or diffAgeS scalars are unset is not the same as an absent block: fix and dimension are still present (use unknown).

struct GnssQuality {
  fix @0 :GnssFixType;
  dimension @1 :FixDimension;
  satellitesUsed @2 :UInt8;
  hasSatellitesUsed @3 :Bool;
  hdop @4 :Float32;
  hasHdop @5 :Bool;
  diffAgeS @6 :Float32;  # age of RTCM/SBAS corrections, seconds
  hasDiffAgeS @7 :Bool;
}

Severity

One severity scale, shared by Fault.severity, Message.level, and ApplicationEvent.severity.

Value Meaning
info Informational.
minor Minor issue.
major Major issue.
critical Critical; likely blocks operation.
enum Severity { info @0; minor @1; major @2; critical @3; }

Robot messages previously used a separate three-value level (info / warn / error). That enum is gone: Message.level is a Severity like everything else.

Power supply enums

Carried on BatteryStatus.

enum PowerSupplyStatus { unknown @0; charging @1; discharging @2; notCharging @3; full @4; }

enum PowerSupplyHealth {
  unknown @0; good @1; overheat @2; dead @3; overvoltage @4;
  unspecifiedFailure @5; cold @6; watchdogTimerExpire @7; safetyTimerExpire @8;
}

# Battery chemistry
enum PowerSupplyTechnology { unknown @0; niMH @1; liIon @2; liPo @3; liFe @4; niCd @5; liMn @6; }

ObjectType

Group Values
Living things person, animal
Vehicles / mobile equipment vehicle, robot
Infrastructure / static structure, equipment
Obstacles / terrain obstacle, debris
Safety / operational hazard, marker, pointOfInterest
— unknown

LayerRole

Combined intent + state roles for a Feature. Intent roles (0–8) are user-defined and flow server → robot; state roles (10–16) are system-generated and flow robot → server (on a ReportedFeature). Ordinal 9 (unused9) is a placeholder so the state roles stay numbered 10–16. Do not emit it.

Role Intent Meaning
allowedArea intent Geofence: the robot must stay inside.
preferred intent Preferred area to drive, for planning.
keepout intent Do not go here.
softExclusion intent Prefer not to go here.
workArea intent A resource the robot should do work on.
target intent Goal the robot should go to.
queue intent Staging, waiting, charging, or queue area.
controlZone intent Enforce a setting here, or trigger something on entry or exit.
trafficZone intent Shared traffic-control zone: intersections, crossings, and other shared passages.
coverage state Area the robot worked on (for example a harvested field).
occupied state Used by the reporting robot directly.
reserved state Robot will use this space; do not assign.
consumed state Permanently or semi-permanently no longer available.
hazard state Unsafe area.
blocked state Impassible.
plannedPath state Where the robot will go (path and target).

triggerZone is a retired name. The wire value is trafficZone. A robot.toml resource that still says triggerZone loads as trafficZone. New files should say trafficZone. Entry and exit triggers belong on controlZone.

GeometryType

The geometry kind a resource producer emits.

Value Meaning
point Single point.
lineString Connected line.
polygon Filled area.
multiPoint Several points.
multiLineString Several lines.
multiPolygon Several areas.

ActionTiming

When a MissionAction should fire or be active during a mission.

Value Meaning
immediateTrigger Fire once now at step start.
atTargetTrigger Fire once after reaching the target / starting the path.
duringMission Enable during the mission, then disable when the mission ends (if bool).
duringFeature Enable while traversing the feature, disable at end (if bool).
finalTrigger Fire at end of navigation.

UI display enums

Used by the capabilities manifest to tell the operator UI how to render actions, sensors, and settings.

# How a value is entered/displayed.
enum ValueType { string @0; int @1; number @2; bool @3; enum @4; }

# How to display a control (and what message it sends).
enum ActionType {
  trigger @0;      # button, one-shot
  setBool @1;      # two linked buttons (on / off)
}

# Confirmation styling for a control.
enum DangerLevel {
  normal @0;    # regular styling
  warning @1;   # yellow, requires confirmation
  critical @2;  # red, may require typing "CONFIRM"
}

# How to render a sensor reading.
enum DisplayHint {
  none @0;          # likely text
  onOff @1;         # "On"/"Off" with a little style
  gauge @2;
  text @3;
  online @4;        # green "light"
  warningLight @5;  # amber "light"
  temperature @6;
  progress @7;      # health bar filled left to right
}

# Minimum role required to invoke an action (otherwise greyed out).
enum Role { viewer @0; operator @1; admin @2; owner @3; }

The missionType action type is gone. It declared a mission type rather than an invokable control, and has no replacement in the action vocabulary. A capabilityType = "missiontype" entry left in robot.toml still parses, but the agent drops it from the manifest and logs a warning.