Skip to content

Robot Configuration

robot.toml is the per-robot configuration the agent reads at startup. It declares the robot's transport, uplink topic, command topics, command policy, motion, and the capabilities (actions, sensors, settings, resource producers, and events) the robot advertises to the fleet manager. This page documents every key the agent parses. Robot Agent Configuration in Rover Nexus writes this file from the same fields.

File location and loading

  • Path: {state_dir}/robot.toml, where the state directory defaults to /var/lib/rdyn/robot (override with the RDYN_STATE_DIR environment variable). So the default path is /var/lib/rdyn/robot/robot.toml.
  • Read once at startup. The agent loads the file a single time when it starts. Changes take effect on the next agent restart.
  • Format: TOML. All config access goes through the agent's central loader; do not parse config files elsewhere in your own on-host tooling.
  • Unknown keys are ignored silently, so a typo in a key name is dropped rather than reported.
  • No secrets. robot.toml holds no keys, certificates, CA roots, or tokens; those live in separate files referenced by path from agent.toml.

Every section below is optional. A minimal (even empty) robot.toml is valid: the agent then uses local Zenoh with the robot/** uplink wildcard, the command base topic, all commands allowed, and no advertised UI capabilities.

What lives in agent.toml instead

Some settings that relate to the robot are not part of robot.toml. The agent reads them from agent.toml, and keys for them placed in robot.toml are ignored:

  • The robot's identity (robot_id), written into agent.toml during enrollment.
  • Server and signaling URLs.
  • TLS paths (ca_root, device_cert, key_private) and Zenoh router endpoints.

See the agent Configuration reference for those. The local coordinate origin is also not a robot.toml key: it is delivered as onboard settings from the cloud and persisted by the agent. See Coordinate Frames.

Naming convention. The top-level flags and the keys under [zenoh_topics], [zenoh_command_topics], [local_transport], and [allowed_commands] use snake_case. The capability-array fields under [[services]], [[sensors]], [[settings]], and [[resources]] use camelCase (for example capabilityType, displayHint, geometryType). Enum-valued fields are case-insensitive.

System flags (top-level keys)

These keys sit at the top of the file, outside any section. A copy of one of these keys written below a [section] header belongs to that section and is ignored, and the agent uses the default. Keep them above the first table header.

Key Default What it controls
mission_catch_up_window_sec 3600 Mission catch-up window, in seconds. At startup the scheduler deletes any persisted mission whose scheduled end time is older than now - window. Default is one hour.
enforce_spatial_directives true Enables the agent-side field rule evaluator. See below.
calculate_usage true The agent integrates distance, drive time, auto time, completed missions, and charging cycles, and publishes UsageTelemetry every 5 seconds. See below.
interpret_mission_actions false The agent also applies a mission's settings and actions locally. See below. The Robot Agent Configuration page does not include this flag.
convert_commands_to_local false Delivers downlink geometry in your local ENU frame instead of WGS84. See below.
allow_remote_config_read false Lets Rover Nexus fetch this file. See below.
allow_remote_config_write false Lets Rover Nexus replace this file. See below.
robot_link (unset) Optional URL to the robot's local user interface or OEM UI. Reported to the fleet server at startup and shown in the fleet UI. See below.

enforce_spatial_directives. When true, the agent compares the robot's WGS84 position against stored polygon field rules and, on zone enter/exit, reports status to the server and applies the zone's settings and services to your robot software. Set it to false to disable only the agent-side evaluator: field rules are still persisted and queryable, and any status your robot software publishes itself is still forwarded. (The key name mirrors the wire identifier; the customer-facing concept is "field rules.") See Field Rules.

calculate_usage. Default true (the key may be omitted). When true, the agent builds UsageTelemetry from motion, status, and mission completions, stores the totals in its local database, and publishes them every 5 seconds. The totals are loaded again on the next start.

  • Distance is the horizontal WGS84 step between motion samples. When both samples have a finite, non-zero altitude, the altitude change is included. The first sample, a non-positive time step, a step longer than 50 m, a gap longer than 5 s, and a sample slower than 0.05 m/s add no distance and no drive time.
  • Auto distance and auto time follow StatusTelemetry.mode of Auto. Auto time includes time stopped in Auto. Any other known mode adds to manual distance. A missing mode adds only to total distance.
  • Uptime is the time the agent process has been running, added to the stored total.
  • A charging cycle is counted once each time the battery status enters Charging. The first sample after startup does not count.
  • A mission is counted once, the first time robot software reports that run as Completed.

A UsageTelemetry message from robot software replaces those totals, is stored, and is forwarded. The agent then stops its own integration until the next start. Set the flag to false to skip the agent's integration and publish. A usage message from robot software is still stored and forwarded.

interpret_mission_actions. Default false (the key may be omitted). The assigned mission command is always forwarded unchanged. When this flag is true, the agent also applies that mission's settings and actions locally at the moment the mission is submitted to the robot software. Leave it false to keep the direct command path. Set the key in the file. Robot Agent Configuration does not show a control for it.

convert_commands_to_local. When true and a local origin is configured, the agent converts geometry-bearing commands and query replies from WGS84 into your robot's local ENU frame before delivering them. The default passes WGS84 through unchanged. Inbound telemetry is always normalized to WGS84 regardless of this flag. See Coordinate Frames.

Remote config access. allow_remote_config_read lets Rover Nexus fetch this file. allow_remote_config_write lets it replace the file. Both default to false when the key is absent. A new file from Robot Agent Configuration, and the agent installer, set both to true so that page can load and save the robot. A remote overwrite replaces the whole file and takes effect on the next agent restart, unless you restart the agent from that page when you save. With read off, Robot Agent Configuration cannot load the file. With write off, a save from that page is refused. You can still generate a file and install it on the device. The file holds no secrets.

robot_link. An optional URL pointing at the robot's on-device user interface or OEM UI: a page an operator can open to reach the robot directly. When set, the agent reports it to the fleet server at startup (over the control plane); the server records it against the robot so the fleet UI can link to it. Leave it unset (the default) to report no link. Unlike the flags above, this is a string, not a boolean, and blank/whitespace-only values are treated as unset.

# robot.toml system flags (agent defaults; a matching line may be omitted)
# mission_catch_up_window_sec = 3600
# enforce_spatial_directives = true
# calculate_usage = true
# interpret_mission_actions = false
# convert_commands_to_local = false
# allow_remote_config_read  = false
# allow_remote_config_write = false
# robot_link = "https://192.168.1.50/ui"   # optional; unset by default

use_ros2 is ignored. ROS 2 systems run rover_ros2_bridge on the Unix domain socket hop. See ROS 2 Bridge.

Motion

Turning radius, brake rate, and footprint are top-level keys. Write them above the first [section] header. Robot Agent Configuration does that. +X is the robot's right, +Y is forward, and the origin is the position the robot reports. There is no separate heading. Vertex order is the order the points were drawn.

Key When absent What it controls
turning_radius_m 0.0 Minimum turning radius in meters. 0.0 means no minimum is configured. The editor omits the key when the field is blank. A negative value is rejected on the page.
brake_rate_mps2 -0.5 Deceleration in m/s², stored as a negative number. Blank or zero becomes −0.5. A positive entry is saved as its negative. The field-rule approach check uses the magnitude as the stopping deceleration.
footprint omitted Body outline: an open ring of [x, y] pairs in meters. At least three points, edges that do not cross, and not collinear. Do not repeat the first point. A ring that fails those checks is ignored and the rest of the file still loads.

When the agent evaluates a closed field-rule zone, the approach starts at the largest Y of the footprint while the robot is moving forward, and at the smallest Y while it is reversing.

turning_radius_m = 2.5
brake_rate_mps2 = -0.5
footprint = [[-0.5, -0.5], [0.5, -0.5], [0.5, 0.5], [-0.5, 0.5]]

On Add Robot, a set turning radius or footprint replaces that key in the profile file delivered at enrollment. Brake rate always replaces the profile's brake rate. A blank turning radius or an invalid footprint leaves the profile key. Clearing the footprint drawing saves a 1 m × 1 m square, and that square replaces the profile key. See Configuration.

[local_transport]

Selects the transport for the robot-software to agent hop on the same host. Absent (the default) means local Zenoh. kind = "uds" switches to a Unix domain socket carrying the same Cap'n Proto payloads.

[local_transport]
kind = "uds"                                    # "zenoh" (default) | "uds"
uds_socket_path = "/run/rover-agent/agent.sock" # optional; this is the default

kind = "uds" requires the agent's local-uds build feature (on by default); otherwise the agent logs a warning and falls back to Zenoh. See Unix Domain Socket.

Your robot software publishes Cap'n Proto ApplicationToAgent messages, and the agent subscribes to one key expression. The key carries no robot id; the agent adds identity when it relays to the cloud. The ROS 2 Bridge (rover_ros2_bridge) uses the Unix domain socket hop instead of this Zenoh key. The Copper Bridge (rovernexus-cu-components) publishes on this Zenoh key for you.

Key Default What it controls
wildcard_topic robot/** The only uplink subscription. Every ApplicationToAgent is published here, or on any key this expression matches. An absent or blank value uses robot/**.

The payload selects the message type. The agent dispatches on the ApplicationToAgent union discriminant, so the topic name does not.

Robot Agent Configuration offers this one topic. Older per-message keys under [zenoh_topics] are ignored: motion_telemetry_topic, status_telemetry_topic, extras_topic, sensor_telemetry_topic, fault_topic, mission_topic, geometry_topic, path_topic, object_topic, system_health_topic, usage_telemetry_topic, and consumable_status_topic. Publishing on a key that robot/** matches, such as robot/fault, still arrives, because that key is inside the one subscription. The agent logs a warning at startup when a file still sets one of those keys.

Host health is not an uplink. The agent collects and reports it. See Health Monitoring.

[zenoh_topics]
wildcard_topic = "robot/**"

For the full uplink message catalog, see Uplink Messages and Telemetry Mappings.

The agent publishes each downlink command as a Cap'n Proto AgentToApplication. A command goes to the base command_topic unless a per-command subtopic is set, in which case it goes to {command_topic}/{subtopic} with leading slashes removed. Every subtopic is optional. An empty subtopic uses the base topic.

Robot Agent Configuration writes the current key names. An older file's legacy key fills that field on load when the current key is absent or empty. When both are set, the current key wins. Saving writes the current name.

Current key Legacy key still read Command
command_topic — Base topic. Default command. Every command with no subtopic set.
set_robot_mode_topic set_mode_topic SetRobotMode
pause_topic stop_topic Pause
resume_topic — Resume
assign_mission_topic mission_command_topic AssignMission
control_mission_run_topic mission_topic ControlMissionRun
invoke_action_topic service_topic InvokeAction
update_settings_topic setting_topic UpdateSettings
update_feature_topic geometry_topic UpdateFeature
spatial_directive_topic — SpatialDirective (field rules)
object_topic — Object
velocity_cmd_topic velocity_topic VelocityCmd
teleop_joy_topic — TeleopJoy
agent_text_request_topic agent_text_topic AgentTextRequest
say_text_topic — SayText
message_confirmation_topic — MessageConfirmation

goto_topic and path_topic are ignored. Send a destination as a feature with layerRole = target, or as a mission.

[zenoh_command_topics]
command_topic = "command"        # base (default)
velocity_cmd_topic = "velocity"  # VelocityCmd -> "command/velocity"
pause_topic = "pause"            # Pause       -> "command/pause"
# keys not listed fall through to the base "command" topic

Subscribe to the base command key (or command/** when you split by subtopic) to receive all commands. See Command Messages.

[allowed_commands]

Gates which commands the fleet manager may send to this robot. Every command defaults to allowed, so you list only the ones you want to restrict by setting them to false. Omitting the section (or restricting nothing) leaves every command allowed and sends no AllowedCommands message at startup. Pause and Resume cannot be restricted.

Recognized keys, all defaulting to true:

set_mode, assign_mission, control_mission_run, invoke_service, update_settings, update_feature, spatial_directive, object, velocity_cmd, teleop_joy, agent_text_request, say_text_request, message_confirmation.

Two keys to note. invoke_service keeps its original name here even though the wire field it maps to is now invoke_action, so existing files keep working. go_to was dropped with the NavigateTo command; a file that still sets it parses and the key is ignored.

# A robot that forbids manual teleop and raw velocity commands.
[allowed_commands]
teleop_joy   = false
velocity_cmd = false

UI capabilities

The [[services]], [[sensors]], [[settings]], and [[resources]] arrays describe what the fleet manager UI renders for this robot. They are bundled into a CapabilitiesManifest sent to the server at startup. Each is a TOML array of tables, so repeat the header to add entries. For the concept and how the cloud matches work to robots, see Capabilities.

Robot software can add to this manifest at runtime by publishing runtimeCapabilities; the runtime manifest is layered on top of what this file declares.

[[services]]

The actions the robot advertises. Each entry becomes an ActionDescriptor in the manifest, invokable with invokeAction. The TOML section and field names are unchanged from earlier versions.

Field Required Purpose
name yes Unique identifier passed back in the invoke-action command.
description yes Human-readable description shown in the UI.
capabilityType yes trigger (one-shot button) or setbool (on/off toggle; alias switch).
requiresRole no Minimum role to invoke: viewer, operator, admin, or owner. Default operator.
confirmationMessage no If set, the UI shows a confirmation dialog with this text before invoking.
dangerLevel no normal, warning, or critical. Default normal. Warning and critical ask for confirmation before the action runs. Critical requires holding the confirm button for 3 seconds.
stateKey no Links a toggle to a sensor key whose current bool value reflects the action's state.
[[services]]
name = "start_mowing"
description = "Begin autonomous mowing routine"
capabilityType = "trigger"
requiresRole = "operator"
confirmationMessage = "This will start the blades. Proceed?"
dangerLevel = "warning"

[[services]]
name = "lights"
description = "Toggle work lights"
capabilityType = "setbool"
requiresRole = "viewer"
stateKey = "lights_on"

capabilityType = "missiontype" is retired. It declared a mission type rather than an invokable control and has no replacement. An entry that still uses it parses, but the agent drops it from the manifest and logs a warning, so it will not appear in the UI. Remove those entries.

Event names are a separate [[events]] array, below. Robot software can still add names at runtime by publishing a runtimeCapabilities manifest. That runtime list is layered on top of the names in this file.

[[sensors]]

Read-only values shown in the UI.

Field Required Purpose
key yes Unique identifier; matches the key the robot publishes in telemetry extras.
label yes Human-readable label shown in the UI.
valueType yes Simple type string, int, number, or bool; or an enumerated type { enum = { options = ["A", "B"] } }.
unit no Unit string displayed after the value (for example %, V).
range no [min, max] used for gauge bounds and validation.
displayHint no UI rendering hint: none, onOff, gauge, text, online, warningLight, temperature, or progress. Default none.
description no Human-readable description shown in the UI. Omit it to leave the field unset.
[[sensors]]
key = "batteryPct"
label = "Battery"
valueType = "number"
unit = "%"
range = [0.0, 100.0]
displayHint = "gauge"

[[sensors]]
key = "mode"
label = "Mode"
valueType = { enum = { options = ["IDLE", "AUTO", "MANUAL"] } }
displayHint = "text"

[[settings]]

Configurable parameters the operator can edit from the UI. The agent seeds each default into its local settings store the first time it sees the key (insert-if-not-exists), then tracks updates from either the fleet manager or your robot software and persists them across restarts. Settings are queryable locally and remotely (see Zenoh queryables).

Field Required Purpose
key yes Unique identifier used in settings-update messages.
label yes Human-readable label shown in the UI.
default yes Default value, tagged with its type (see below).
range no [min, max] bounds for numeric values.
step no Step increment for numeric sliders in the UI.
description no Human-readable description shown in the UI. Omit it to leave the field unset.

The default is a tagged value. Use the form that matches the type:

default = { type = "string", data = "value" }
default = { type = "int",    data = 42 }
default = { type = "number", data = 1.5 }
default = { type = "bool",   data = true }
default = { type = "enum",   data = { value = "MED", options = ["LOW", "MED", "HIGH"] } }
[[settings]]
key = "maxSpeedMps"
label = "Max speed"
default = { type = "number", data = 1.2 }
range = [0.0, 3.0]
step = 0.1

[[settings]]
key = "cutHeight"
label = "Cut height"
default = { type = "enum", data = { value = "MED", options = ["LOW", "MED", "HIGH"] } }

[[resources]]

Feature/resource channels this robot can produce: geographic features of a given type that Rover Nexus can then use in operations and missions (for example detected pallet locations, or mowed-area coverage).

Field Required Purpose
id yes Stable resource-producer id. The robot references this id when reporting features for the channel.
label no Human-readable label shown in the UI. Defaults to id.
description no Human-readable description shown in the UI.
geometryType yes Geometry the producer emits: point, lineString, polygon, multiPoint, multiLineString, or multiPolygon.
layerRole yes Role of the produced features. One of: allowedArea, preferred, keepout, softExclusion, workArea, target, queue, controlZone, trafficZone, coverage, occupied, reserved, consumed, hazard, blocked, plannedPath. The retired token triggerZone still loads and is read as trafficZone.

geometryType and layerRole are case-insensitive and ignore separators, so workArea, work_area, and WorkArea are equivalent.

[[resources]]
id = "pallet_locations"
label = "pallet locations"
description = "Location of detected pallets"
geometryType = "point"
layerRole = "target"

[[resources]]
id = "coverage"
label = "Mowed area"
geometryType = "multiPolygon"
layerRole = "coverage"

[[events]]

Names the robot software may emit as an event. The manifest stores a list of strings, so each entry has only name. The server processes an event whose name is declared here. An undeclared name is ignored. Blank names are dropped. A repeated name is kept once, at its first occurrence.

[[events]]
name = "low_fuel"

[[events]]
name = "row_finished"

Robot Agent Configuration writes one [[events]] table per name. A runtime capabilities manifest can add names on top of this list.