RealBench

Fail-closed readiness checks that answer: is this robot verifiably ready for the next run?

Install

pip install realbench-robotics

Needs Python 3.10 or newer (python3 --version). The import package and CLI remain realbench. pip install realbench-robotics[ros2] does not install rclpy; that comes from your ROS2 distro.

Run realbench in the same shell where you sourced /opt/ros/<distro>/setup.bash. Match ROS_DOMAIN_ID to the robot.

ROS2 warning

A positions-only ROS2 connection cannot reach READY. Faults and actuator state stay unverifiable, and the run quarantines by design.

This is the command that can reach READY once the graph infers diagnostics and the controller manager (or you pass them):

realbench check --source ros2

Run realbench doctor --source ros2 first if anything is missing. Pass --urdf only when there is no latched */robot_description on the graph.

realbench check --source ros2 with no sensors or nodes declared exits 3 (usage error) and does not print a readiness verdict. Open the Components tab and save, or run realbench capture-components.

Quickstart

realbench analyze --urdf robot.urdf
realbench doctor --source ros2
realbench capture-home --source ros2 --repo .
realbench check --source ros2

--urdf accepts a URDF or MJCF file and is optional on doctor/check/serve when */robot_description is latched. analyze needs only the model. doctor diagnoses setup and never produces a readiness verdict. capture-home writes <repo>/.realbench/home.json when the robot has a home pose. Continuous-joint robots skip home. check and cycle look for that file when --home is omitted.

Serve

realbench serve --source ros2 --host 0.0.0.0 --no-browser

cd first to the directory where .realbench/ should be written. It prints ROS_DOMAIN_ID=<n> and a URL. The default bind is 127.0.0.1 (this machine only); --host 0.0.0.0 is required to open the URL from a laptop. The printed address may not be the one your laptop can route to — use the robot's LAN IP and port.

No --urdf. The model is read from the latched */robot_description topic (TRANSIENT_LOCAL std_msgs/String). Joint states, diagnostics, and controller manager are inferred from the graph, including namespaced paths such as /JK3/platform/joint_states. Continuous-joint robots skip home pose.

Until at least one sensor or node is declared, the stored verdict is SETUP INCOMPLETE, not QUARANTINE. The Components tab pre-ticks discoverable sensors and nodes so save is one click. Wait a few seconds after save for the next evaluation. Saving a LaserScan or Imu also writes a default value_field and plausible range so those checks evaluate (PASS or FAIL), not NOT_APPLICABLE.

A failing diagnostic, sensor, or node can be marked a known issue with a required note. Acknowledged rows stay recorded and visible; they do not drive classify() until the reason string changes.

Host wall-clock is stored next to robot time. If they disagree by more than 5 seconds, check_clock_sane fails at HEALTH and the UI shows both clocks.

check_state_stream_fresh uses 3× the observed joint_states period and 3× the recorder sample interval, floored at 2.0s.

Recording continues if you close the browser tab. Ctrl-C stops serve. Recording is saved in .realbench/records.db. Nothing is lost. To hand it over, run realbench export.

Export

Do not copy .realbench/ while serve is running. The recording database is WAL-mode; a folder copy drops the -wal file.

History lives in <repo>/.realbench/records.db (serve recorder). One-shot /api/check History also writes runs.db; realbench export includes it as <stem>-runs.db when present. Settings in the UI has the same Export recording button.

realbench export
realbench export --out capture.db --repo .

SQLite's backup API writes one consistent file, prints path and size, and only reports success if integrity_check passes. Safe while serve is up. Open the .db in DB Browser for SQLite (or sqlite3).

Exit codes

doctor uses 0 (no blocking setup problems), 1 (problems that would block a useful verdict), and 3 (could not run).

CI

realbench check --source ros2 || { echo "robot not ready, aborting run"; exit 1; }

Read-only

Read-only. RealBench never commands motion, never writes firmware, and never modifies your robot.

Known limits

• Reset execution is stubbed.
• Plausible-but-varying sensor nonsense is not caught; frozen and stopped sensors are.
• The ROS2 path is validated against a Dockerised Humble Jackal, not physical hardware.