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, runtimeRemainingS) 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

struct Point2 {
  x @0 :Float64;
  y @1 :Float64;
}

struct GeoPoint2 {
  lon @0 :Float64;   # decimal degrees
  lat @1 :Float64;   # decimal degrees
}

struct Point3 {
  x @0 :Float64;
  y @1 :Float64;
  z @2 :Float64;
}

struct Quat {
  qx @0 :Float64;
  qy @1 :Float64;
  qz @2 :Float64;
  qw @3 :Float64;
}

# Geodetic pose: where the robot (or a target) is, in world coordinates.
struct Pose {
  latDeg @0 :Float64;     # decimal degrees
  lonDeg @1 :Float64;     # decimal degrees
  altitudeM @2 :Float64;  # HAE: meters above ellipsoid, roughly sea level
  headingDeg @3 :Float64; # 0 = north, clockwise
}

struct Pose3 {
  x @0 :Float64;
  y @1 :Float64;
  z @2 :Float64;
  qx @3 :Float64;
  qy @4 :Float64;
  qz @5 :Float64;
  qw @6 :Float64;
}

# Body-frame velocity.
struct VelTwist {
  linearMps @0 :Float32;   # meters / second
  angularRps @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 primary world-coordinate type used across telemetry, goTo targets, routes, and mission feedback. Note the heading convention: 0 degrees is north, increasing 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 (shape or route) 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 — either a Shape (areas/points/lines) or a Route (waypoints/paths). It is used inline in mission commands, in the feature command, and inside field rules.

# ShapeData - union of geometry types
struct ShapeData {
  union {
    point @0 :GeoPoint2;
    multiPoint @1 :List(GeoPoint2);
    lineString @2 :List(GeoPoint2);
    multiLineString @3 :List(List(GeoPoint2));
    polygon @4 :PolygonData;
    multiPolygon @5 :List(PolygonData);
  }
}

struct PolygonData {
  exterior @0 :List(GeoPoint2);
  holes @1 :List(List(GeoPoint2));
}

# Shape - user-defined / server-to-robot spatial area
struct Shape {
  identity @0 :AssetIdentity;
  data @1 :ShapeData;
  areaType @2 :LayerRole;
  scope @3 :ScopeType;
  # Height rules (optional): treat the area as an extruded prism for bridges,
  # parking decks, ramps, etc.
  minZM @4 :Float64;
  maxZM @5 :Float64;
  levelId @6 :Int32;  # for multi-storey sites
}

# RouteData - union of route types
struct RouteData {
  union {
    waypoint @0 :Pose;
    multiWaypoint @1 :List(Pose);
    path @2 :List(Pose);
    multiPath @3 :List(List(Pose));
  }
}

# Route - uses RouteData union
struct Route {
  identity @0 :AssetIdentity;
  data @1 :RouteData;
  areaType @2 :LayerRole;
  scope @3 :ScopeType;
  featureType @4 :Text;
  hasFeatureType @5 :Bool;
}

# SpatialFeature - a Shape or Route, used inline in MissionCommand and Feature
struct SpatialFeature {
  union {
    shape @0 :Shape;
    route @1 :Route;
  }
}

Robot-reported shapes

When the robot reports a shape back to the cloud (e.g. an area it covered or a hazard it found), it uses ReportedShape. It is the same geometry as Shape but uses the state-only ReportedLayerRole and carries an expiry.

# ReportedShape - robot-reported spatial area (uses ReportedLayerRole, has expiry).
# If the scope is world or fleet, it is forwarded to all robots in the fleet.
struct ReportedShape {
  identity @0 :AssetIdentity;
  data @1 :ShapeData;
  areaType @2 :ReportedLayerRole;
  scope @3 :ScopeType;
  expireTimeMs @4 :Int64;
  minZM @5 :Float64;
  maxZM @6 :Float64;
  levelId @7 :Int32;  # for multi-storey sites
}

Field rules

A field rule is a persistent zone: a SpatialFeature plus timing, parameters, and capabilities to apply while inside or at the zone. It is distinct from a bare SpatialFeature (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 :SpatialFeature;
}

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 {
  id @0 :Text;
  name @1 :Text;
  unixTimeMs @2 :Int64;
  expiresUnixTimeMs @3 :Int64;
  scope @4 :ScopeType;  # robot/user send to fleet manager; fleet/world send to all robots in fleet
  objectType @5 :ObjectType;
  location @6 :Pose;
  trajectory @7 :Trajectory;  # 3D velocity vector
  radiusM @8 :Float64;  # meters
}

Operation wrappers (upsert / delete)

Spatial assets and objects are delivered as operations: either an upsert (create-or-replace by id) or a delete (remove by id). Upserts are idempotent — re-sending the same id overwrites the previous value.

# Server -> robot: a bare spatial primitive (Shape or Route), geometry only.
struct FeatureOp {
  union {
    upsert @0 :SpatialFeature;
    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: a reported shape / geographic feature.
struct ReportedShapeOp {
  union {
    upsert @0 :ReportedShape;
    delete @1 :Text;  # id to delete
  }
}

Enumerations

ScopeType

Determines how a message is propagated through the fleet — 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 shapes 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).
idle Powered but not operating.

MissionStatus

Lifecycle state of a mission run.

Value Meaning
unknown Unset / not reported.
ready 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.

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.

GpsSource

Origin of the GPS fix carried on MotionTelemetry.

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 Shape/Route. Intent roles (0–8) are user-defined and flow server → robot; state roles (10–16) are system-generated and flow robot → server.

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

ReportedLayerRole

The state-only subset of LayerRole, used by ReportedShape (robot → server): coverage, occupied, reserved, consumed, hazard, blocked, plannedPath.

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.

TriggerSource

Who is responsible for a trigger / schedule.

Value Meaning
server The server enqueues the trigger.
agent The rover-agent self-schedules.
robot The robot self-schedules.

UI display enums

Used by UiCapabilities 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; }