Set up your robot¶
Quatern needs a description of your robot: its joints and limits (a URDF) and its sensors and connection (a Quatern config). Start from the catalog, from your own URDF, or by answering a few questions. Then run quatern doctor to check it.
Robots live in ~/.quatern/robots/ as <name>.urdf and <name>.quatern.json. In the REPL, /robots lists the robots installed here and the catalog, and /robot <name> selects one.
Catalog robots¶
The catalog has ready-made descriptions, a simulator setup, and a sample recording for each robot, so quatern verify works offline right after install.
$ quatern init --list
Robots in the catalog (quatern init --robot <name>):
c101 Quatern's own test rover: ELEGOO 4WD chassis, Arduino + L298N, RealSense depth camera. [built-in sim]
jetson_rover A typical Jetson Nano/Orin rover kit: skid-steer base, 2D lidar, depth camera, IMU. [built-in sim]
sim_arm Quatern's test arm: six joints and a gripper, encoders plus a wrist tracker; sim only. [mock sim]
sim_diffbot A round 32 cm diff-drive robot with lidar, depth camera, visual odometry and IMU; sim only. [built-in sim]
turtlebot3_burger ROBOTIS's small diff-drive classroom robot: LDS 360° lidar, IMU, wheel odometry. [built-in sim]
turtlebot3_waffle The larger TurtleBot 3: wider diff-drive base, LDS 360° lidar, IMU, wheel odometry. [built-in sim]
turtlebot4 Clearpath/iRobot TurtleBot 4 on a Create 3 base: RPLIDAR A1, IMU, wheel odometry. [built-in sim]
ur5e 6-DOF collaborative arm, 5 kg payload, 850 mm reach; joint encoders. [mock sim]
Install one:
wrote ~/.quatern/robots/turtlebot4.urdf
wrote ~/.quatern/robots/turtlebot4.quatern.json
Robot turtlebot4 (instance default): 3 DOF — base/x (unbounded) m, base/y (unbounded) m, base/yaw (unbounded) rad. Sensors: wheel_odom (odometry, estimates base), imu (imu), scan (laserscan). Plans in grid2d over group 'base'.
what you need: For the sim: nothing. For the robot: a TurtleBot 4 (standard or lite) with the Create 3 and the Raspberry Pi on the same ROS 2 network, publishing /odom, /imu and /scan and accepting /cmd_vel. The OAK-D runs RGB-only in the default bringup, so it is not used.
license: Apache-2.0 (turtlebot4) and BSD-3-Clause (create3_sim) upstream; this simplified description is a derivative work
imported the bundled sample capture turtlebot4.default_2026-10-02_sample_v1: `quatern verify` works offline right away
next: quatern quickstart --robot turtlebot4 (or: quatern verify --robot turtlebot4 --goal "Navigate around the island to reach (1.2, 2.0)")
The what you need line lists what the real robot needs. For example, the TurtleBot 3 needs turtlebot3_bringup on ROS 2 Humble or newer, on the same ROS_DOMAIN_ID. The UR5e needs the Universal_Robots_ROS2_Driver with the External Control URCap.
Catalog configs come with several targets: sim (the built-in simulator, the default) and hardware (ROS 2). Some also have mock or gazebo. /backend in the REPL lists them and switches between them.
More than one of the same robot
Give each unit an instance name, like --instance lab2. Instances share a type, so a stack verified on one unit can be pinned for all of them. If the catalog files are already installed, add --force (or write to another folder with --dir).
Your own URDF¶
Quatern uses your URDF as it is and reads the sensors from its <sensor> elements (cameras, depth cameras, lidars, IMUs). It then asks only what a URDF can't say:
Which of these estimate the robot's motion and should be cross-checked?These are the sensors verification compares against each other.Is this a mobile robot? Give its base link, or 'no'Do the joints report their positions (encoders)?Does the robot publish odometry for its base?Backend for the primary target(mock,sim2dorros2)
Each question has a flag (--cross-check, --mobile-base, --encoders, --odometry, --backend), so you can script it with --yes. With --backend ros2, Quatern adds a hardware target that uses the conventional topics: /cmd_vel, /joint_states, /odom, /scan, /imu/data and /emergency_stop. Edit the config if yours differ.
Answer a few questions¶
No URDF? The wizard writes one:
It asks for a name, wheeled or arm, which sensors it has (odometry, camera, pointcloud, laserscan, imu), the wheel count and size or the joint count and gripper, and roughly how heavy it is. The mass only sizes the e-stop recommendation.
Leave a measurement blank and Quatern marks it TODO(measure) in the URDF:
6 value(s) still to measure; `quatern doctor --robot mybot` lists them
next: quatern doctor --robot mybot
Measure before hardware
TODO placeholders are fine in the simulator. On a hardware target, doctor reports them as failures and the deploy gate refuses to open until they're measured.
Check it with doctor¶
quatern doctor checks the description, the config and the connection, and tells you how to fix each problem.
quatern doctor — turtlebot3_burger (instance default, target sim)
ok config turtlebot3_burger.default: 3 DOF, 3 sensor(s), plans in grid2d
ok urdf no TODO placeholders
ok backend target 'sim' uses the sim2d backend
ok streams wheel_odom (odometry) at 30.0 Hz, last sample 0.03s ago
ok streams scan (laserscan) at 5.0 Hz, last sample 0.20s ago
ok calibration cal_turtlebot3_burger.default_... is 5 min old
WARN sandbox isolation tier none: resource limits only, no filesystem or network namespace
-> install bubblewrap on Linux for a hard tier
WARN silence stop-on-silence not verified on target 'sim'
-> run `quatern doctor --robot turtlebot3_burger --target sim --check-silence` with the robot free to move safely
WARN agent agent off: not signed in and no API key
-> run `quatern login`, or set ANTHROPIC_API_KEY to use your own key
ready: no blocking problems
What it checks, in order: the config, whether ROS 2 is visible, URDF placeholders, the backend and a short probe of every sensor stream (rate, staleness, timestamps), calibration age, the sandbox, toolchains for compiled modules, the stop-on-silence check, and the agent sign-in.
ok,WARNandFAILlines; a->line under a problem says how to fix it.- Exit code 0 means no failures (
ready: no blocking problems), 1 means at least one (N thing(s) to fix before this robot can be used:). --target hardwarechecks the real robot. Placeholders and a missing silence check are failures there and warnings elsewhere.--probe-secondssets how long it watches the streams (default 2).doctoralso lists any keys missing from your~/.quatern/config.jsonand the defaults it used. Other commands only show these with--verbose.
The stop-on-silence check¶
Every robot must stop by itself when commands stop arriving: within 0.5 s, enforced on the robot (firmware or controller), not in Quatern. This is the layer that protects you if your computer, the network or Quatern itself fails. Verify it with:
The robot moves
The check drives one joint or the base at 20% of its limit for about a second, then goes silent and measures how fast the robot stops. Make sure it can move safely. It asks Run the silence check? THE ROBOT MOVES. [y/N].
A hardware deploy refuses without a passing check from the last hour.
Calibrate¶
quatern calibrate sweeps every actuated joint through its range and measures how it responds. Verification and deploys need a valid calibration less than an hour old.
THE ROBOT WILL MOVE: every one of its 4 joint(s) sweeps its full range (...). Clear the workspace.
Start calibration? [y/N] y
joint R² tracking err lag verdict note
wheel_front_left_joint 1.000 0.0379 rad/s 0.12 s ok nominal
calibration cal_mybot.default_...: VALID — all joints nominal
From the simulator to the real robot¶
quatern hardware walks you through the move to a real robot one step at a time: connection, live sensor readouts, a guided recording, calibration and the silence check, verification, and the deploy gate.
Every motion is confirmed by a person at the terminal; no flag can answer for you. If a step fails, it prints the most likely fix and how to resume:
FAILED: ...
most likely fix: ...
then resume: quatern hardware --robot turtlebot4.default --from connect
Steps for --from: connect, sensors, capture, calibrate, verify, deploy.