RealBench

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

Every check returns PASS, FAIL, UNVERIFIABLE, or NOT_APPLICABLE — and UNVERIFIABLE never yields READY. If RealBench cannot see something, it says so instead of assuming the best. That is what makes it safe to gate a run on.

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

Install

pip install realbench-robotics

Install into the same Python that can already import rclpy — normally the system Python you use for ROS. A virtualenv must be created with --system-site-packages, or RealBench installs fine and then reports "ROS 2 not found".

Run

With your ROS 2 environment sourced and the robot stack up:

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

It prints a URL. Open it from any machine on the network.

No configuration. RealBench reads your robot model from /robot_description, and infers your joint states, diagnostics and controller manager from the ROS graph. Namespaced robots are handled — a ClearPath robot under /JK3 resolves /JK3/platform/joint_states and /JK3/diagnostics on its own. No files, no flags, no config.

In the browser, open Components, tick the sensors and nodes you care about, and save. That is the only setup step. After that it records continuously, whether or not the page is open.

What it catches

• A sensor or node that stops mid-run — named, with the second it happened
• A sensor that is alive but frozen — still publishing, identical payload
• A joint that disappears from /joint_states
• Loss of contact with the robot, with history preserved on screen

The important one: the record survives the restart that fixes it. A fault that heals itself on reboot still leaves a timestamped trace.

What it does not catch

• Anything at boot. RealBench needs the ROS graph to exist before it can see anything. If DDS never comes up, it is blind by the same mechanism that broke the robot.
• A sensor publishing plausible-looking nonsense. It catches stopped and frozen, not wrong-but-varying.
• Pose, on robots with only continuous joints. A differential-drive base has no home pose to verify, so both pose checks correctly report not-applicable.

CLI

realbench doctor  --source ros2      # diagnose setup; never returns a verdict
realbench check   --source ros2      # one readiness verdict, then exit
realbench analyze --urdf robot.urdf  # inspect a model, no robot needed

--urdf accepts URDF or MJCF. Pass --urdf to check only if your robot does not publish /robot_description.

Exit codes

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

Gating a test run

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

Requirements

Python 3.10+, ROS 2 (validated on Humble). rclpy comes from your ROS installation, not from pip.

Status and known limits

Early. Honest about it:

• Validated against a Dockerised ROS 2 Humble robot, not physical hardware. First real-robot pilots are in progress.
• Reset execution is stubbed. RealBench reports readiness; it does not yet restore it.
• ROS 1 support is experimental. --source ros1 exists and is unit-tested, but has not yet been validated against a live ROS 1 master. Treat it as a preview. Note that ROS 1 Noetic reached end-of-life in May 2025.

If RealBench flags something while your robot is genuinely healthy, that is the bug I most want to hear about — a false alarm is worse than a miss.

License

MIT