Message catalogue

Every message a robot and the XPARO server exchange, read from the server and xparo_ros source. Each message is a JSON object keyed by the names below (see Connection protocol). A client only needs the ones for the features it supports: a robot that ignores GET_WIFI_NETWORKS simply has no Wi-Fi tools on the dashboard.

“Server → robot” messages that come from a dashboard button are sent only to the robot chosen on the dashboard, and only over its WebSocket.

All messages

Key	Direction	What it is
ADD_robots_info	robot → server	Registers the robot (hardware fields in Connection protocol). The reply carries ROBOT_CREDENTIAL (first time only) and REST_API_TOKEN.
ROBOT_CREDENTIAL	server → robot	The robot’s own key; use it instead of the secret key from now on.
REST_API_TOKEN	server → robot	Token for file uploads (ROS bags).
ROBOT_HEARTBEAT	robot → server	{"device_id": ..., "diagnostics_level": ...} every 30 seconds (diagnostics_level optional). Keeps the robot online for 90 seconds.
title, disc, goal, rules	server → robot	Project text, part of the project sync.
aiml	server → robot	The project’s main behaviour tree (XML body).
custom_aiml	server → robot	{tree name: XML body} for every tree in the Behaviour editor.
maps, local_env	server → robot	The project’s main environment file and the Environment Map.
custom_maps	server → robot	{name: text} for every environment file.
Sets, custom_Sets	server → robot	The main data file and {file name: text} for every other file.
properties	server → robot	Project properties file.
custom_tasks	server → robot	{task id: {behaviour_tree_name, blackboard_mapping, params, save_task_history}}, so /xparo/run_task works without the dashboard.
custom_node_files	server → robot	{file name: {"language": ..., "source": ...}}: code nodes from the Behaviour editor. The robot loads them and answers with CUSTOM_NODE_SYNC_RESULT.
CUSTOM_NODE_SYNC_RESULT	robot → server	{"registered_tags": [...], "failures": [...]}. Failures appear as a red message on the dashboard.
custom_bt_node_plugins, custom_bt_node_inline_code	server → robot	Python behaviour tree node plugins to load, and inline Python nodes.
sync_local_database	server → robot	Asks for the state of the robot’s synced files. The robot answers with LOCAL_FILE_STATE (names and hashes).
LOCAL_FILE_STATE	robot → server	What the robot has. The server pushes newer files, adopts new ones and asks for the content of the rest.
REQUEST_LOCAL_FILE_CONTENT	server → robot	Asks for some files’ content; answered with LOCAL_FILE_CONTENT.
LOCAL_FILE_CONTENT	robot → server	The content asked for. See Synced files and folders.
rosbag_config	server → robot	Recording settings from Database → Sensors (topics, start mode, delay).
RUN_TASK	server → robot	Run a task (fields below). Answered with TASK_STARTED and later TASK_RESULT.
TASK_STARTED	robot → server	The run began: task_id, run_id, timeout_s, started_at, task_title, tree_name, trigger, attempt.
TASK_RESULT	robot → server	How the run ended (fields below). Kept and resent if the connection was down.
CANCEL_TASK	server → robot	{"task_id", "run_id", "reason"}; answered with TASK_CANCEL_ACK (run_ids, found, message).
GET_RUNNING_TASKS	server → robot	Answered with RUNNING_TASKS: {"runs": [{run_id, task_id, running_s}]}.
ADD_Task_history_database	robot → server	One task history record (when the task has Save task history on, or from /xparo/task_updates).
ADD_live_update_bt	robot → server	One behaviour tree node changed state (node_name, node_type, prev, curr, run_id, task_id…). Drives the live view in the Behaviour editor.
ADD_Logs_history_database, UPDATE_Logs_history_database	robot → server	Session log: new ROS 2 log lines and average CPU, RAM and disk use.
ADD_robots_maps	robot → server	{"device_id", "maps"}: the robot’s environment file.
ask_bot_api	robot → server	{"question": ..., "data": {...}}: ask the project’s AI assistant. The answer comes back as {"message": {"bot_response": ..., "responded_by": ...}}, and the question and answer are saved in the Database page’s chat prompts.
RUN_COMMAND	server → robot	Terminal: {"command", "request_id", "timeout", "max_lines"}. Answered with COMMAND_RESULT (success, exit_code, timed_out, output, truncated). Default 30 s and 50 lines; at most 300 s and 1000 lines.
TELEOP	server → robot	{"axes": [...], "buttons": [...]}. xparo_ros publishes it on /joy (axes limited to -1..1, at least 4 axes and 3 buttons) and answers TELEOP_ACK {"success": true}.
LIST_FILES	server → robot	Answered with FILE_LIST: {"tree": [...], "base_dir": ...}, the robot’s transfer folder.
DELETE_FILE	server → robot	{"path": ...} inside the transfer folder; answered with DELETE_ACK (success, path or message).
FILE_REQ, FILE_CHUNK, FILE_COMPLETE	both	File upload and download: FILE_REQ {"filename", "direction": "upload"|"download", "size"}, then base64 FILE_CHUNK {"data"} messages, then FILE_COMPLETE.
REBOOT_ROBOT	server → robot	{"password": ...} (the robot user’s sudo password, if needed). There is no reply when the reboot starts; REBOOT_RESULT {"success": false, "message", "needs_password"} only if it fails.
GET_ROS2_TOPICS	server → robot	Answered with ROS2_TOPICS {"topics": [...]}.
GET_ROS2_PARAMS	server → robot	Answered with ROS2_PARAMS {"params": [...], "errors": [...]}.
SET_ROS2_PARAM	server → robot	{"node", "name", "value", "request_id"}; answered with SET_ROS2_PARAM_RESULT.
GET_ROSBAG_STATUS	server → robot	Answered with ROSBAG_STATUS {"state", "recorder_alive", "process_detected"}.
START_ROSBAG, STOP_ROSBAG, SAVE_ROSBAG	server → robot	Control recording; answered with ROSBAG_ACTION_RESULT (the action plus the status above).
GET_LIVE_STATUS	server → robot	Answered with LIVE_STATUS: cpu_percent, ram_percent, disk_percent, gpu_percent, temp_c, uptime_seconds.
GET_DIAGNOSTICS_SNAPSHOT	server → robot	Answered with DIAGNOSTICS_SNAPSHOT: every /diagnostics component and the overall level.
WATCH_ERROR_LOGS, UNWATCH_ERROR_LOGS	server → robot	The Health & Errors window is open with Watch live: the robot sends DIAGNOSTICS_SNAPSHOT and PROBLEMS_REPORT updates every few seconds until UNWATCH (or a time limit).
PROBLEMS_REPORT	robot → server	New and recurring problems from /diagnostics and /rosout, sent in batches.
GET_XPARO_VERSION	server → robot	Answered with XPARO_VERSION {"xparo_git_commit", "ros_distro"}.
GET_WIFI_NETWORKS	server → robot	{"rescan": bool}; answered with WIFI_NETWORKS.
WIFI_CONNECT	server → robot	{"request_id", "ssid", "password", "ifname", "hidden", "auto_revert", "sudo_password"}; answered with WIFI_CONNECT_RESULT, resent after reconnecting if switching networks dropped the connection.
WIFI_FORGET, WIFI_RADIO	server → robot	Forget a saved network (uuid) or turn Wi-Fi on or off; answered with WIFI_ACTION_RESULT.
GET_BLUETOOTH_DEVICES	server → robot	{"scan": bool}; answered with BLUETOOTH_DEVICES.
BLUETOOTH_ACTION	server → robot	{"request_id", "action", "address", "sudo_password"}; answered with BLUETOOTH_ACTION_RESULT.
GET_ads_schedule	robot → server	{"utc_offset_min": ...}, sent on connect. Answered with ads_schedule.
ads_schedule	server → robot	The approved ads and when to play them. Also pushed whenever they change.
ADS_PLAYS	robot → server	{"plays": [...], "utc_offset_min"}: plays recorded on the robot. Answered with ads_plays_ack.
ads_plays_ack	server → robot	Which uploaded plays were stored, so the robot stops resending them.

RUN_TASK

What the server sends when a task runs (Run now, Auto Launch on Start or Restart on Failure):

{"RUN_TASK": {
  "task_id": "3dffb995-298e-4335-a0a9-b38aecc396fa",
  "run_id": "5f1c0e2a9b7d",
  "tree_xml": "<Sequence>...</Sequence>",
  "blackboard": {"destination": "ward_3"},
  "subtrees": {"go_to_room": "<Sequence>...</Sequence>"},
  "stage": "development",
  "timeout_s": 600,
  "save_task_history": true,
  "task_title": "Deliver medicine",
  "tree_name": "deliver_medicine",
  "trigger": "run_now",
  "attempt": 1
}}

subtrees is present only when the tree uses <SubTree>, and start_delay_s only when a restart waits before running again. timeout_s 0 means no time limit.

TASK_RESULT

A real result from the tree in Test trees offline, run with battery at 10 so its first check fails:

{"TASK_RESULT": {
  "task_id": "3dffb995-298e-4335-a0a9-b38aecc396fa",
  "run_id": "5f1c0e2a9b7d",
  "success": false,
  "duration_s": 0.0047,
  "error": "",
  "outcome": "failed",
  "retryable": true,
  "explanation": "The tree finished with FAILURE at battery_ok (ScriptCondition): 'battery > 20' is False.",
  "failed_node": {
    "name": "battery_ok",
    "tag": "ScriptCondition",
    "path": "Sequence(deliver_medicine) > ScriptCondition(battery_ok)",
    "reason": "'battery > 20' is False"
  },
  "stats": {"nodes_total": 4, "nodes_ticked": 2, "nodes_skipped": 0,
            "nodes_never_reached": 2, "node_ticks": 2, "tree_ticks": 1,
            "by_status": {"FAILURE": 2, "IDLE": 2}},
  "task_title": "Deliver medicine",
  "tree_name": "deliver_medicine",
  "trigger": "run_now",
  "attempt": 1
}}

outcome is one of the values in Run results. error is empty when the tree itself decided the result (success or failed) and explains the problem otherwise. retryable false means running it again unchanged would fail the same way (a stage mismatch or an invalid tree, for example), so Restart on Failure does not retry it.