| # H2 ROS 2 LowCmd bridge |
|
|
| This C++17 package connects Unitree `unitree_hg` ROS 2 messages to the Python controller through H2BR shared memory. It receives ROS `/lowstate` (native DDS `rt/lowstate`), mirrors `/wbc_racket_command`, and publishes ROS `/lowcmd` (native DDS `rt/lowcmd`) at 1000 Hz. |
|
|
| Read [setup](../docs/SETUP.md) and complete site-specific hardware commissioning before a live launch. The bridge executable is a hardware control component; compilation or a passing contract check does not authorize robot operation. |
|
|
| ## Build and inspect on Linux |
|
|
| From the repository root, with ROS 2 Humble, the installed `unitree_hg` workspace, and the selected network interface configured: |
|
|
| ```bash |
| export H2_IF=enp4s0f0 |
| export UNITREE_ROS2_ROOT="$HOME/unitree_ros2" |
| source scripts/source_unitree_env.sh "$H2_IF" |
| colcon build --packages-select cpp_lowcmd_bridge \ |
| --cmake-args -DCMAKE_BUILD_TYPE=Release |
| source install/setup.bash |
| ros2 run cpp_lowcmd_bridge h2_lowcmd_shm_bridge --print-contract |
| ros2 run cpp_lowcmd_bridge h2_lowcmd_shm_bridge \ |
| --validate-network-only --network-interface "$H2_IF" |
| ``` |
|
|
| The expected contract is: |
|
|
| ```text |
| H2BR magic=0x48324252 version=7 bytes=1544 state_dof=31 lowcmd_slots=35 mode_pr=0 joint_map=unitree_sdk2@e02dc701-h2-cpp cmd_q=raw_learned_desired ros_lowstate=/lowstate ros_lowcmd=/lowcmd publish_hz=1000 |
| ``` |
|
|
| Network validation checks the local RMW/interface/CycloneDDS configuration only. The native LowState inspector and physical identity check are separate commissioning gates. Build outputs belong in `build/`, `install/`, and `log/` and are not release source. |
|
|
| ## Admission and shared memory |
|
|
| Live startup requires `--network-interface`. The interface must be UP and match `CYCLONEDDS_URI` generated by the environment script. The bridge publishes no command until it has valid H2 LowState in PR mode, no discovered competing LowCmd publisher, and a finite Python H2BR command carrying the validated MotionSwitcher attestation bit. It never changes AB mode into PR mode. |
|
|
| The 1544-byte H2BR v7 interface uses 31 state/command slots and the audited C++ motor map. Waist IDs 12/13/14 are yaw/roll/pitch; wrist IDs are roll/pitch/yaw. Policy ordering is different and is mapped by name in the Python H2 contract. Shared-memory locks protect coherent snapshots and allow only one Python command writer. |
|
|
| The production shared-memory name is `h2_pingpong_bridge`. The simulator uses a separate name and ownership contract; it must not attach to production memory. Before a runner starts, the [no-runner validation script](../scripts/validate_bridge_no_runner.sh) checks healthy/disarmed state, LowState update rate, exclusive ROS endpoint ownership, and absence of actual LowCmd samples. |
|
|
| ## Command and stop semantics |
|
|
| `cmd_q` contains the raw learned desired joint target. Immediately before each 1000 Hz publication, the bridge projects that target into the PD-effort interval computed from the latest valid joint position/velocity and actuator effort limits. This allows an out-of-range desired target to request saturated effort without first rewriting it to a mechanical angle boundary. Measured state and captured stop-hold poses remain subject to mechanical limits. |
|
|
| Python supplies zero desired velocity and zero feed-forward torque. It also sets both raw head targets to zero; the effort-projected target can differ from zero when required by the actuator limit. Do not independently change action scaling, motor ordering, gains, or projection semantics. |
|
|
| L1 latches the policy-start request. R1 latches stop and captures the last legal measured pose. The 100 ms watchdog, motor faults, invalid commands, competing publishers, and non-PR/invalid state also latch faults. Stale or invalid LowState inhibits LowCmd output; the bridge does not compute a hold from stale state. A recovered input does not clear a latch. Exit and restart through the full admission procedure. |
|
|
| The bridge must stop last among the control processes during normal shutdown. Stale production shared memory is handled only with the guarded `--replace-stale-shm` path after verifying that no bridge process owns it. Software stop is not a substitute for an independent hardware emergency stop. |
|
|
