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
Feature Geometry plus identity and classification: a shape or a route, in a WGS84 or local frame.
Field rule A zone with rules: a feature plus timing, parameters, and capabilities.

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

Field rule fields

Known fields:

Field Notes
directiveId Field rule identifier.
name Display name.
startTimeMs Epoch-ms activation time.
expireTimeMs Epoch-ms expiry time.
zoneParameters Rule/zone parameters.
capabilities Capabilities the field rule applies to/scopes.
spatial The associated Feature geometry.

For the complete SpatialDirective schema and the spatialDirective / updateFeature command operations (upsert/delete), see Command Messages → spatialDirective and Common Types → Field rules.

Feature (shape / route)

Field Notes
identity Feature id, name, revision, and hash.
layerRole Role classification (keepout, target, work area, …).
scope Who the feature is for.
data The geometry: a shape or route, in a WGS84 or local frame.

See Common Types → Spatial features for the full Feature and SpatialData geometry (Wgs84Shape / Wgs84Route / LocalShape / LocalRoute, 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} (kind is route or shape); an empty request returns all features. The response carries full Feature objects (geometry plus identity, layer role, scope, expiry, and height rules).
  • Field rules (agent/spatial_directives/get_bulk): the request carries field rule ids; an empty request returns all field rules, each a full SpatialDirective.

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.

Field-rule and feature geometry, whether pushed as a command or fetched via a query, follows the coordinate-frame contract: WGS84 by default, or your local ENU frame when convert_commands_to_local is set.