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 theRDYN_STATE_DIRenvironment 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.tomlholds no keys, certificates, CA roots, or tokens; those live in separate files referenced by path fromagent.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 intoagent.tomlduring 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]usesnake_case. The capability-array fields under[[services]],[[sensors]],[[settings]], and[[resources]]usecamelCase(for examplecapabilityType,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.modeofAuto. 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.
[zenoh_topics] (uplink ingest)
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.
[zenoh_command_topics] (downlink)
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_servicekeeps its original name here even though the wire field it maps to is nowinvoke_action, so existing files keep working.go_towas dropped with theNavigateTocommand; 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.