Skip to content

Spatial Directives

Spatial directives define zones and rules — geometry plus timing, parameters, and capabilities — that govern where and how the robot operates.

  • Direction: Downlink (cloud → robot) for delivery; queryable locally
  • Command topic: the command key on the local Zenoh session (or command/** with per-type subtopics)
  • Encoding: Cap'n Proto over Zenoh

The agent persists directives and features it receives and serves them to robot software via local queryables.

Concepts

Concept Meaning
Spatial feature Geometry only: a Shape or a Route.
Spatial directive A zone with rules: a spatial feature plus timing, parameters, and capabilities.

A directive references geometry; a bare feature is geometry alone.

Spatial directive fields

Known fields:

Field Notes
directive_id Directive identifier.
name Display name.
start_time_ms Epoch-ms activation time.
expire_time_ms Epoch-ms expiry time.
zone_parameters Rule/zone parameters.
capabilities Capabilities the directive applies to/scopes.
spatial_feature The associated Shape or Route geometry.

For the complete SpatialDirective schema and the spatialDirective / feature command operations (upsert/delete), see Command Messages → spatialDirective and Common Types → Spatial directives.

Feature (Shape / Route)

Field Notes
feature_id Feature identifier.
name Display name.
kind Shape or Route.
geometry Shape/route geometry.

See Common Types → Spatial features for the full Shape / Route geometry (ShapeData, RouteData, coordinate representation, and the LayerRole / scope fields).

Features are delivered as feature operations (upsert/delete) on the command topic and are persisted by the agent.

Fetching directives and features locally

Robot software can fetch directives and features on demand via Zenoh queryables — see Zenoh queryables for the full list and request/response types. The directive- and feature-specific requests are:

  • Features (agent/features/get_bulk): the request carries feature refs of {id, kind}; an empty request returns all features (Shape | Route geometry).
  • Spatial directives (agent/spatial_directives/get_bulk): the request carries directive ids; an empty request returns all directives.

Detailed request/response field schemas are coming soon.