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. uptimeS) or Ms for milliseconds. Durations are not auto-converted.
  • Optional fields: Cap'n Proto has no nullable primitives, so an optional field 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 target can be given in either frame (for example a navigateTo target or 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 / levelId Float64 / Int32 Optional vertical extent and map level.

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;
}

Field rules

A field rule is a persistent zone: a Feature plus timing, parameters, and capabilities 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);  # what services or features to apply in or on this zone
  spatial @7 :Feature;
}

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 capabilities. 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.

Value Meaning
unknown Unset / not reported.
ready Accepted, ready to run.
starting Transient start state; do not stay here.
running Actively executing.
paused Paused, resumable.
blocked Cannot proceed (waiting on a condition).
aborted Stopped before completion.
complete Finished successfully.
error Failed.

complete, aborted, and error are terminal; all other states (including paused and blocked) are non-terminal.

GpsFixType

GNSS satellite fix status. A fix is valid when the type is gps or better; higher-precision types (dgps, floatRtk, fixedRtk) indicate differential/augmented fixes.

Value Meaning
unknown Not reported.
invalid No valid fix.
gps Unaugmented fix.
dgps Differential.
sbas Satellite-based augmentation.
floatRtk RTK, float solution.
fixedRtk RTK, fixed solution (highest precision).
pps Precise positioning service.
gbas Ground-based augmentation.

GpsSource

Origin of the GPS fix carried on GlobalMotionTelemetry.

Value Meaning
real Actual hardware fix.
simulated Running in a simulator, no real hardware.
estimated Hardware lost lock; using dead-reckoning / IMU.

FaultSeverity

Severity bucket carried on Fault.severity.

Value Meaning
info Informational.
minor Minor issue.
major Major issue.
critical Critical; likely blocks operation.

MessageLevel

Value Meaning
info Informational.
warn Warning.
error Error.

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).

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 Area the robot should do work in.
target intent Goal the robot should go to.
queue intent Staging / waiting / charging / queue area.
controlZone intent Enforce a setting here.
triggerZone intent Trigger something on entry / exit.
coverage state Area the robot worked on (e.g. harvested field).
occupied state Used by the reporting robot directly.
reserved state Robot will use this space; do not assign.
consumed state Permanently/semi-permanently no longer available.
hazard state Unsafe area.
blocked state Impassible.
plannedPath state Where the robot will go (path and target).

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.

CapabilityTiming

When a MissionCapability should fire or be active during a mission step.

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

UI display enums

Used by Capabilities to tell the operator UI how to render services, 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 CapabilityType {
  trigger @0;      # button, one-shot
  setBool @1;      # two linked buttons (on / off)
  missionType @2;  # no button; expresses a mission type the robot can do
}

# 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 use a service (otherwise greyed out).
enum Role { viewer @0; operator @1; admin @2; owner @3; }