Part I: The ROS 2 stack · §15 of 43
| Symptom | Cause / fix |
|---|---|
Only body_link0 / link0 render; “No transform to world” for arm links | No /joint_states, so joint_state_broadcaster isn’t running. Check ros2 control list_controllers. |
| Spawner: “Failed to acquire lock in 20 seconds” | Another spawner is holding /tmp/ros2-control-controller-spawner.lock because it’s stuck or left over. Ctrl+C everything, pkill -f controller_manager/spawner; pkill -f ros2_control_node, relaunch. On zeus this was stale state in the old container session and disappeared after the container restarted. (A leftover lock file on its own does no harm; only a live process holds the lock.) |
| ”Waiting for an action server to become available…” forever | Wrong action name, e.g. single-arm /joint_trajectory_controller/…. Use /left_… or /right_… (ros2 action list). |
| Goal rejected / aborted immediately | Joint names wrong or not all 7 included, or a position is outside the limits. |
RViz: Authorization required… could not connect to display :1 | On the host: xhost +SI:localuser:root (needed again after each login). |
| RViz: MESA/iris errors, black window | Missing PRIME env vars (__NV_PRIME_RENDER_OFFLOAD=1, __GLX_VENDOR_LIBRARY_NAME=nvidia, NVIDIA_DRIVER_CAPABILITIES=all, --gpus all). |
| Container gone after logout | Its main process was your shell. docker start openarm. |
| Arm model looks wrong / v2.0 meshes | Forgot arm_type:=v10. |
OpenArmHW init fails / socket error | can0/can1 doesn’t exist or is down in the host namespace; the container isn’t on --network host; or FD mismatch (interface FD on but can_fd:=false, or vice versa). |
| Motors don’t respond / timeouts | Wrong bitrate (check discover, which scans 1/5/8/10 Mbit/s), motor errors (diagnose, clear_error), missing termination, no motor power. |
| Interface went down by itself | Bus-off (errors). Check wiring/termination; ip -s -d link show can0; reconfigure; optionally can_configure --rm 100. |
| Arm jerks / buzzes | CM overruns (no RT priority, loaded laptop), or gains too high for the load. Add the RT flags (§12.5). |
| MoveIt gripper execution fails | GripperCommand vs JTC mismatch (§9). |
move_group dies with −11 on Ctrl+C | Known MoveIt shutdown crash; harmless. |
Real launch: no arms in RViz, list_controllers empty, for ~25 s | Normal with the patched driver: two 10 s start-up ramps run before the controllers can start. Wait for Configured and activated joint_state_broadcaster (§12.2). |
Spawner: Failed to acquire lock in 20 seconds. Attempt 1 of 5 failed. Retrying… during a real start-up | Normal: the spawners wait for the start-up ramps and retry. Only a problem if all 5 attempts fail. |
jointN: no reply, not enabled, or error / Not moving at start-up | That arm isn’t powered or isn’t answering (or a motor reports an error). Power both arms before launching; check discover / diagnose. |
jointN is … rad from zero (limit 0.50 rad) | The arm isn’t hanging near zero, or that motor’s zero is wrong. Re-hang it; check with monitor (§11). |
All jointN start: values exactly +0.000 (unpatched or patch 0001 only) | The motors never replied: arm not powered. Patch 0002 refuses to start in this case. |
| The other arm moves | CAN mapping swapped: the launch was typed without left_can_interface:=can0 right_can_interface:=can1. Stop; use openarm_launch.sh real. |
Segmentation fault in JointTrajectoryController::update after Ctrl+C | Shutdown race in ros2_control_node; the motors may still be on. Cut the power; stop with openarm_stop.sh in future (§12.4). |
| After Ctrl+C the prompt returns at once, no shutdown messages | The launch was piped through tee without -i; ROS is still shutting down out of sight. Check ps; use tee -i. |
Overrun detected all the time on the real robot | CAN I/O over USB (docking station) slightly over the 1.33 ms budget (§12.5). |
ros2: command not found | You’re in a laptop shell; ROS only exists in the container (docker exec -it openarm bash). |
A bash script stops at once with …/setup.bash: … unbound variable | The script uses set -u; ROS’s setup files rely on unset variables. Wrap the source lines in set +u … set -u. |