Skip to navigation

Unitree G1 WBC

View as Markdown

Runs Agile whole-body control on the Unitree G1 with Holoscan SDK 5. For camera-driven arm and hand control, use GR00T + WBC.

ModeExecutablePurpose
mock (default)mock_wbc_g1Deterministic inputs without a robot or simulator
simsim_ucx_wbc_g1Isaac Sim over UCX with simulation time
realunitree_g1_wbcPhysical G1 over DDS; deployment instructions incomplete
unitree_simunitree_g1_wbcUnitree MuJoCo over DDS domain 1; run procedure not documented

See application modes for clock and I/O differences.

Architecture

Real, Isaac Sim, and mock modes share the same WBC control path. AgileWbcOp consumes joint state and IMU samples with matching capture timestamps and produces joint commands. Optional keyboard/gamepad input supplies locomotion velocity in real and Isaac Sim modes.

velocity joint commands Joint state + IMU AgileWbcOp Keyboard / gamepadoptional in real and sim Command output

Note: StartUpOp is not shown. Real mode connects WBC → StartUpOp → DDS publisher; the startup operator also receives measured joint state and handles waypoints and enable gating. Sim and mock connect WBC directly to their command output without a startup operator.

ResponsibilityRealIsaac Sim (sim)Mock
Entry pointreal/main.ccsim/main.ccmock/main.cc
State and IMUDDS subscriberUCX interface with paired sensor samplesDeterministic state and IMU source
Command outputDDS publisherUCX senderValidation sink
Startup processingStartUpOp between WBC and publisher; measured-pose input, waypoints and enable gateWBC active from the first tick; no StartUpOpNo startup gate
ClockWall timeSimulator-driven synthetic timeWall time

Run

Run from the repository root on a CUDA-capable system:

./isaac_os build wbc_g1

Choose one mode and launch one controller. In real and Isaac Sim modes, add --gamepad to enable keyboard/gamepad input; a keyboard connected to the app host is sufficient. Complete device setup before launching with that flag, then use the shared controls. Without --gamepad, WBC uses the configured static locomotion velocity (zero by default).

Mock

Deterministic 50 Hz joint state and IMU feed AgileWbcOp with the configured static velocity command. The sink checks each command’s size, finite values and nonzero content.

./isaac_os run wbc_g1 mock

Stop the default run with Ctrl+C. Use --message-count for a short validation run:

./isaac_os run wbc_g1 mock -- --message-count=4

Simulation configuration

sim/main.cc uses the shared UCX interface subgraph, also used by N1.7 + WBC, for transport, clock advancement, and UnitreeSimStateOp. The adapter publishes IMU before matching joint state; depth-two, drop-oldest input queues bound pending history. Both sensors must carry the same capture timestamp for each control step. A missing or mismatched partner produces no control update. The app connects the paired outputs to AgileWbcOp and its commands to the UCX sender, keeping all three on the control partition.

Without --holoviz, MessageDropSinkOp drains camera messages directly from the image receiver. With --holoviz, RGB camera images feed HoloViz directly in a separate visualization partition, using a depth-one drop-oldest connection. Visualization does not feed the control loop.

Physics runs at 200 Hz and control at 50 Hz with --substeps 4. Sensor capture timestamps are preserved. The connection opens after all operators finish startup, so models initialize before simulation begins.

The run mode loads config/wbc_g1_sim_ucx_config.yaml. This launcher reads gr00t_wbc and, with --gamepad, gamepad; the other sections in that file are not used by this launcher. Static motion commands are velocity_command_lin_x, velocity_command_lin_y, and velocity_command_ang_z. With --gamepad, the top-level gamepad section selects devices, speeds, and mappings. Teleop polls every gamepad.emit_period simulation seconds on its own partition, and WBC selects the latest velocity without waiting for input. Without --gamepad, the configured static velocities remain in effect. See the shared controls.

OptionDefault / purpose
--hostname127.0.0.1; simulator host
--port50008; must match simulator
--config-pathWBC configuration selected by the run mode
--compile-onlyCompile the graph without connecting or running operators; CUDA is still required
--gamepadEnable keyboard/gamepad velocity input; off by default
--holovizDisplay the simulator camera in a 640 by 480 window; off by default

For another port, change both ends:

./isaac_sim run -y --scene operators/unitree_g1/assets/g1_ucx.usda \
-- --substeps 4 --port 50019
./isaac_os run wbc_g1 sim -- --port 50019

Run those commands in separate terminals. Add --hostname <sim-host> to the controller for a remote simulator.

Simulation troubleshooting

⚠️ Connection, motion and resource problems
  • Connection failure: check simulator readiness, matching ports, and whether another controller already owns the endpoint. Restart the app after the simulator is ready.
  • Unexpected motion: confirm the scene, --substeps 4, joint order, scene-authored drive gains, and velocity command. Mock-test success alone does not validate physical behavior in simulation.
  • Runtime failure or repeated scene resets: inspect both logs. The simulator resets after a controller disconnect or a simulation-step error; the logs identify which occurred.
  • Missing resources: allow model downloads and engine creation to finish. When reusing build directories across worktrees, preserve their configured shared-cache mounts.

Benchmark capture

See Profile an Application to measure this application with its native trace markers.

Current WBC-under-GR00T measurements are in the benchmark results.