Skip to content

Field Rules

Field rules 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 field rules 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.
Field rule A zone with rules: a spatial feature plus timing, parameters, and capabilities.

A field rule references geometry; a bare feature is geometry alone.

Field rule fields

Known fields:

Field Notes
directive_id Field rule 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 field rule 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 → Field rules.

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 field rules and features locally

Robot software can fetch field rules and features on demand via Zenoh queryables — see Zenoh queryables for the full list and request/response types. The field rule- 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).
  • Field rules (agent/spatial_directives/get_bulk): the request carries field rule ids; an empty request returns all field rules.

The request/response field schemas are defined in the Cap'n Proto schema (features_query.capnp and spatial_directives_query.capnp); get it and language bindings from the client libraries.