NUSim

A self-contained, docker-based MuJoCo simulator for the Booster Robotics K1 humanoid, used by NUbots for RoboCup development. It replaces both Booster's gated Webots build and their closed-source mck motion runner with one inspectable, NUClear-based simulator that speaks the Booster SDK over FastDDS — the same wire protocol as the real robot — so NUbots_K1 binaries drive it unchanged.

sim/soccer  (docker container, NUClear)
   MuJoCo physics + RL locomotion policy + head camera + GLFW viewer + GameController supervisor
        │  Booster SDK over FastDDS (domain 0)            │  camera frames → shared memory
        ▼                                                 ▼
 NUbots_K1  (walk / behaviour / robocup roles)     input::K1Camera → ImageCompressor → NUsight
        ▲
        │  RoboCup GameController (UDP, direct)

• One process simulates the K1 body and owns its locomotion (a trained velocity-tracking RL policy), so NUbots' high-level Move/RotateHead/GetUp commands produce real dynamic motion — no Booster downloads, no separate runner.
• Vision is rendered by MuJoCo and handed to NUbots' unchanged input::K1Camera over shared memory, so CompressedImage reaches NUsight exactly as on the real robot.
• GameController is heard directly by NUbots over the network; the sim additionally runs a supervisor that places the ball/robots per game phase.

Quick start

Requirements: Docker (everything else is baked into the image). Full setup, config reference, and troubleshooting are in docs/K1_MUJOCO_SETUP.md.

./b configure                   # configure the sim build
./b build                       # build the sim in docker (first run builds the image)
./b run sim/soccer              # launch the soccer sim (viewer + DDS + camera + supervisor)

Then drive it from NUbots_K1 exactly as against the real robot:

cd ~/NUbots_K1
./b run keyboardwalk
# e = walk on/off, w/s/a/d = velocity (0.01 m/s per press — tap ~10x), z/x = turn, arrows = head

The Booster SDK requires a FastDDS profiles file (participant profile booster_dds) or it refuses to create its DDS participant (Failed to create participant). ./b run now defaults FASTRTPS_DEFAULT_PROFILES_FILE to the repo's copy, so no flag is needed. If you pass --environment yourself, note it takes ONE comma-separated argument and replaces the default — include the FastDDS var yourself or all DDS dies.

The full autonomous stack works too — ./b run nusim/behaviour has the robot find the ball by vision and dribble it goalward. See docs/K1_MUJOCO_SETUP.md for the end-to-end walkthrough and the NUbots_K1-side requirements (skill::K1WalkPolicy + skill::K1GetUpPolicy in the role, VisualMesh.yaml camera entry).

Older revisions of this README told you to mount an OpenVINO overlay over the image, because the NUbots_K1 image was built with ENABLE_INTEL_CPU=OFF and had no CPU inference device at all (Device with "CPU" name is not registered). Fixed upstream — the image now ships libopenvino_intel_cpu_plugin.so, and inference prefers TensorRT on the GPU anyway. No overlay, no --volume, no LD_LIBRARY_PATH.

Locomotion policy

NUSim does one thing: simulate. It neither trains nor runs locomotion policies: the sim is a servo-command listener (CUSTOM mode + rt/joint_ctrl LowCmd, PD-tracked at 1 kHz), and inference runs on the NUbots side (NUbots_K1 module/skill/K1WalkPolicy and module/skill/K1GetUpPolicy, OpenVINO, 50 Hz). Policies are trained in the NUbots mujoco_playground fork (branch feat/k1-training, K1JoystickFlatTerrain / K1Getup tasks) and exported to ONNX with learning/export_k1_onnx.py. The walk observation/action interface is pinned in docs/OBS_ACTION_CONTRACT.md — anything that trains a walk policy for the K1 must match it.

Layout

Path	Description
b, mujoco/b.py, mujoco/tools/	NUbots-style ./b command dispatcher (run, build, configure, image).
mujoco/roles/	Role files (sim/soccer.role) → bin/<role> binaries.
mujoco/module/	NUClear modules: Simulation, SdkBridge (DDS), Locomotion, Camera, Supervisor, Viewer.
mujoco/models/k1/	Vendored MuJoCo K1 model (BSD-3, booster_assets) + RoboCup/flat scenes.
mujoco/docker/	Toolchain image + k1sim.sh (the container workflow ./b wraps).
docs/K1_MUJOCO_SETUP.md	Setup, config reference, end-to-end with NUbots_K1, and troubleshooting.
docs/OBS_ACTION_CONTRACT.md	ONNX policy interface contract (obs/action layout the sim expects).

Forked from NUWebots; the Webots/NUgus simulation has been removed in favour of the MuJoCo path (see git history if you need it).