RealBench

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

Install

pip install realbench-robotics

The import package and CLI remain realbench. pip install realbench-robotics[ros2] does not install rclpy; that comes from your ROS2 distro.

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:

realbench check --urdf robot.urdf --source ros2 \
  --ros2-topic /joint_states \
  --diagnostics-topic /diagnostics \
  --controller-manager /controller_manager

Run realbench doctor --urdf robot.urdf --source ros2 first if anything is missing.

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 --urdf robot.urdf --source ros2
realbench capture-home --urdf robot.urdf --source ros2 --repo .
realbench check --urdf robot.urdf --source ros2 \
  --diagnostics-topic /diagnostics \
  --controller-manager /controller_manager

--urdf accepts a URDF or MJCF file. analyze needs only the model. doctor diagnoses setup and never produces a readiness verdict. capture-home writes <repo>/.realbench/home.json. check and cycle look for that file when --home is omitted.

Serve

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

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. 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.

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.

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.

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 --urdf robot.urdf --source ros2 --diagnostics-topic /diagnostics --controller-manager /controller_manager || { 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.
• Sensor and firmware checks are not implemented.
• The ROS2 path is validated against a Dockerised Jazzy node, not physical hardware.