open-rmf / open-rmf/rmf_api_msgs
Write the `status` / `issues` / `commission` boundary into `robot_state.json` descriptions
@mxgrey is already working on this.
Since Aug 25, 2026.
- Dominant language
- Rust
- Stars
- 2
- Forks
- 12
- Avg merge
- 22h 56m
- Merged PRs (30d)
- 2
Description
I'd like to open a description-only PR against robot_state.json, in the same shape as #54, writing down the division of labour between status, issues and commission. Everything I'd propose is already a maintainer answer — I'm not asking anyone to decide anything new, only to confirm I've transcribed it correctly.
The reason for asking first is that the answers are spread across five Discourse threads and one closed issue, 2022 to 2026, and none of them reached the schema.
| Where | Who | What it settles |
|---|---|---|
| 44854 (2022-08) | mxgrey | issues: "It gets added to the issues data inside the robot state. This state information will be visible to the human operators from the dashboard." … "It has no effect on any execution flow. The expectation is that the human operators can decide what kind of manual intervention is appropriate …" |
| 44879 (2022-09) | mxgrey | status: asked whether offline/shutdown stop task assignment — "Presently no. The override status is put into the robot state so it can be viewed by human operators, and that is all." |
| 44853 (2022-11) | mxgrey | "you need to hold onto the IssueTicket … If you don't hold onto the issue ticket, then the issue will be "dropped" so it won't show up in the state, but it should still show up in the event log." |
| 44689 (2024-07) | mxgrey | A robot that lost wifi: "you can use the create_issue to add issue information to the robot state" and, separately, "To prevent tasks from being sent to a robot you'll need to turn off its commissioning" — immediately hedged: "But that's a pretty extreme measure to take for a robot if it has temporarily lost wifi. I would only do that if you expect the robot to be unusable for a prolonged period of time." |
| 55245 (2026-06) | grey | "We don't have very strict definitions of these statuses … I think any of the three could make sense, depending on the exact details of your system." Recommends override_status("uninitialized") plus set_commission(decommission) and reassign_dispatched_tasks |
| free_fleet#221 (2026-03) | aaronchongth | An integrator's create_issue didn't reach the dashboard: "for alerting the users via the rmf-web dashboard, you'll need to use the Alert mechansim … that was added to rolling after Jazzy's release" — with the caveat that Alert "will not help the user resolve anything, rather it is just a prompting mechanism" |
Read together these are consistent: commission is the only one of the three that changes what RMF does. status and issues are both operator-facing, with issues carrying the detail and a resolve lifecycle.
Two things make writing that down worth more than the usual documentation tidy-up.
Part of the answer has changed, and only the forum records it. issues used to be rendered. rmf-web#601 (2022-04) added a pending-issues section, and rmf-web#694 (2023-05) describes robot alerts as deriving from an error status with "the issues under the robot state will be displayed". Both of those packages have since been removed, and rmf-dashboard-framework has no reader for the field today. None of that history is recoverable from the schema, so an integrator reading it now sees a field with no indication of what consumes it — which is roughly the position the reporter in #221 was in.
The IssueTicket retention rule governs whether the field is populated at all, and it is only half written down. RobotUpdateHandle.hpp:384-386 says a ticket destroyed without resolve() leaves the issue "dropped", which issues a warning to the log; the consequence an integrator needs — that the entry disappears from the robot state while remaining in the log — appears only in 44853. It is a rule about how this field behaves, so the schema seems like the place for it.
What I'd propose, concretely:
status(this schema's, nottask_state's) — core computes onlyidle/charging/working; the other four values requireoverride_status; RMF does not branch on any of them.issues— entries are for operator attention and have no effect on execution flow; dropping theIssueTicketremoves the entry from state while leaving it in the fleet log.commission— this is the field that governs task assignment. It arrived in #48 as a bare$refwith nodescriptionof its own, which is probably how the asymmetry started.
I'd stop there. I'm deliberately not proposing text for anything not already stated on the record — in particular no rule for which channel a lost-contact robot should use, since 55245 is explicit that there is no strict definition, and that reads like next-generation work rather than something to freeze into the current schema.
I'd rather put exact wording up as a PR than argue the phrasing here, so say the word and I'll draft it. If you'd rather leave the current-generation schema alone and specify it in the next generation, that's a fine answer and I'll drop it — though the Discourse threads would still be worth linking from somewhere more durable than a forum archive.
For context, I raised a separate question about the next-generation participant model in a comment on next_gen_prototype#31; this one is only about the current schema's wording.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Assessment
This issue has not been assessed yet.