hakoniwa-mujoco-robots

English | 日本語

TL;DR

• This repository provides MuJoCo-based robot simulation assets for Hakoniwa.
• It supports ROS/URDF-derived robot models, including TurtleBot3 Burger.
• It connects C++ MuJoCo simulators and Python controllers / visualizers through Hakoniwa PDU.
• It includes a TurtleBot3 sample with gamepad control and 2D LiDAR LaserScan-compatible PDU output.
• It includes configurable LiDAR noise profiles such as LDS-01-like and URG-04LX-UG01-equivalent settings.
• It includes forklift samples with context save/restore and RD-light handoff as advanced examples.
• Compact JSON is the default for both C++ and Python (hakoniwa-pdu >= 1.6.1).

Start Here

Use these entry points first. The rest of this README includes advanced notes and experimental background.

Goal	Read / Run
Build the repository	Prerequisites, then Setup
Diagnose the local environment	./doctor.bash
Run TurtleBot3 with gamepad and LiDAR	Quick Start: TurtleBot3 + 2D LiDAR
Run the forklift sample	Quick Start: Forklift
Browse documentation by category	docs/README.md
Try small sensor examples	examples/sensors/README.md
Try color-camera PNG capture	examples/sensors/color_camera/README.md
Try MJCF position / velocity actuators	examples/actuators/joint/README.md
Try Unitree Go1 MJCF joint I/O	examples/actuators/unitree_go1/README.md
Learn the sensor/actuator workflow	docs/guide/sensor-actuator-user.md
Understand JSON config structure	docs/guide/json-config.md
Learn MJCF XML / JSON authoring and standalone checks	docs/guide/mjcf-json-authoring.md
Understand sensor/actuator PDU design	docs/spec/sensor-actuator-design.md
Understand sensor/actuator config schemas	docs/spec/sensor-actuator-config-schema.md
Read RD-light / context save-restore notes	docs/guide/forklift-context-rd.md

Current standalone examples:

examples/sensors/ultrasonic/        ultrasonic range sensor + viewer ray
examples/sensors/color_camera/      RGB camera sensor + PNG capture
examples/actuators/joint/           MuJoCo position / velocity joint actuators
examples/actuators/unitree_go1/     Unitree Go1 MJCF joint I/O smoke

Demo Videos

• TurtleBot3 + 2D LiDAR / sensor noise demo:
  • 
• Runtime handoff demo (RD-light, dual forklift assets):
  • 

TurtleBot3 + 2D LiDAR Demo Notes

This demo shows a TurtleBot3 Burger running on MuJoCo with a 2D LiDAR simulation connected through Hakoniwa PDU.

The point is not only to visualize LiDAR point clouds, but also to reproduce differences in sensor noise characteristics.

• With TurtleBot3's standard LDS-01, the point cloud is visibly noisier
• With the URG-04LX-UG01-like profile, obstacle contours appear much clearer

One important Sim2Real theme in Hakoniwa is to represent the practical difference users experience when changing sensors, not just robot motion alone.

Configuration:

• ROS-derived TurtleBot3 model executed on MuJoCo
• 2D LiDAR simulated by raycast using the selected sensor profile
• Scan frequency, angular range, angular resolution, and noise model are loaded from JSON
• Output published as LaserScan PDU on Hakoniwa
• Point cloud visualized by a Python visualizer
• Noise differences reproduced for LDS-01 and URG-04LX-UG01-equivalent settings

Forklift RD-light Handoff Demo

This is an advanced experimental demo.
It runs two MuJoCo forklift assets and performs single-node ownership handoff with context save/restore.

• RD-light is an advanced / experimental handoff demo
• It is not RD-full
• See docs/guide/forklift-context-rd.md and rd-design.md for details

---

What This Repository Provides

Included:

• MuJoCo robot models
• Hakoniwa-integrated C++ simulators
• Python controllers
• Python visualizers
• PDU configs
• sensor configs
• reusable sensor components under src/sensors/
• reusable actuator components under src/actuator/
• standalone feature examples under examples/
• forklift context save/restore
• RD-light as an advanced demo

Directory map:

• models/: MuJoCo XML models
• config/: PDU JSON configs
• config/sensors/: LiDAR / sensor spec JSON
• config/actuator/: actuator binding JSON
• src/: C++ simulator implementation
• src/sensors/: sensor implementations
• src/actuator/: joint actuator implementation
• include/hakoniwa/pdu/: PDU converters and adapters
• python/: Python controllers / visualizers
• examples/: small standalone examples for individual features
• tests/sensors/: focused sensor unit / smoke tests
• docker/: Docker scripts
• logs/: generated logs
• tmp/: generated state files

---

Architecture

Hakoniwa PDU is the hub, and MuJoCo (C++) communicates with Python controllers / visualizers over that contract.

• Hakoniwa: synchronization and PDU runtime
• MuJoCo C++ Asset: physics stepping + PDU read/write
• Python Controller / Visualizer: input and inspection tools
• PDU JSON: contract of channels/types/sizes

+-----------------------------+      PDU (shared contract)      +----------------------+
| Python Controller / Viewer  |  <----------------------------> | MuJoCo C++ Simulator |
| (gamepad / visualizer)      |                                  | (tb3_sim / forklift) |
+--------------+--------------+                                  +----------+-----------+
               |                                                            |
               |                        Hakoniwa runtime                     |
               +------------------------(sync / mmap / PDU)-----------------+

---

Quick Start: TurtleBot3 + 2D LiDAR

This is the shortest path to verify MuJoCo + Hakoniwa + TurtleBot3 + gamepad + LiDAR.

Demo choices:

• Interactive: tb3-demo.bash or the manual tb3_sim + tb3_gamepad.py flow. Use this when a gamepad is available.
• Automated: tb3-mbody-demo.bash. Use this for scripted route demos, CI-like checks, or AI-agent execution where no joystick is available.
• Multi-process mirror: tb3-dual-mirror-demo.bash. Use this to run two independently simulated TurtleBot3 processes where each process owns one real robot and mirrors the other robot through pose PDU.
• MBody-generated models: tb3-mbody-demo.bash with HAKO_TB3_MODEL=burger, waffle, or waffle_pi.

Prepare 4 terminals.

1. simulator

./src/cmake-build/main_for_sample/tb3/tb3_sim

2. gamepad controller

python python/tb3_gamepad.py

For a joystick-free scripted route demo, use:

python python/tb3_route_demo.py --pattern square

To run the same TB3 runtime against the minimal world generated by hakoniwa-mbody-registry, use the launcher-based MBody demo:

bash tb3-mbody-demo.bash

This uses hakoniwa-pdu's launcher to start the simulator, issue hako-cmd start, and run a joystick-free scripted route demo. It defaults to Burger with the MuJoCo viewer, LiDAR plot, trajectory trail, and a figure8 route.

Useful variants:

HAKO_TB3_MODEL=waffle HAKO_TB3_ROUTE_PATTERN=figure8 bash tb3-mbody-demo.bash
HAKO_TB3_MODEL=waffle_pi HAKO_TB3_ROUTE_PATTERN=figure8 bash tb3-mbody-demo.bash
HAKO_TB3_ENABLE_VIEWER=0 HAKO_TB3_ROUTE_PATTERN=showcase bash tb3-mbody-demo.bash
HAKO_TB3_ROUTE_PATTERN=dance HAKO_TB3_ENABLE_VIEWER=1 bash tb3-mbody-demo.bash
HAKO_TB3_HOLD_SEC=15 bash tb3-mbody-demo.bash
ACTIVATE_MODE=activate-only bash tb3-mbody-demo.bash

For a multi-process mirror demo, use:

bash tb3-dual-mirror-demo.bash

This launcher starts four processes:

• Process A: real Burger + mirrored Waffle, Conductor owner, Viewer enabled.
• Process B: real Waffle + mirrored Burger, Conductor disabled, Viewer disabled.
• Controller A: drives TB3_BURGER/hako_cmd_game.
• Controller B: drives TB3_WAFFLE/hako_cmd_game.
• LiDAR visualizers: show TB3_BURGER/laser_scan and TB3_WAFFLE/laser_scan.

Process A's viewer is the intended observation point. It shows the local real Burger and the remote Waffle mirrored from TB3_WAFFLE/base_link_pos. Process B still runs real Waffle physics and publishes TB3_WAFFLE/base_link_pos, but it does not open a viewer. Two LiDAR plot windows are opened side by side, one for each real robot's laser_scan PDU. Only one simulator process should own Conductor startup.

Use the manual commands below when debugging each process separately.

./src/cmake-build/main_for_sample/tb3/tb3_sim_burger

tb3_sim_burger defaults to config/assets/tb3-mbody-burger-asset.json, runs without the viewer, omits the camera component, and maps the generated wheel <velocity> actuators through config/actuator/joint/tb3_mbody_*.json. Set HAKO_TB3_ENABLE_VIEWER=1 to show the viewer.

For a visual Burger demo, run:

HAKO_TB3_ENABLE_VIEWER=1 ./src/cmake-build/main_for_sample/tb3/tb3_sim_burger
/usr/local/hakoniwa/bin/hako-cmd start
python3.12 python/tb3_lidar_visualizer.py
python3.12 python/tb3_route_demo.py --pattern figure8 --forward-sec 5.0 --linear-axis 0.6 --yaw-axis 0.85 --hold-sec 6

For the MBody-generated TurtleBot3 Waffle runtime demo, use:

./src/cmake-build/main_for_sample/tb3/tb3_sim_waffle
/usr/local/hakoniwa/bin/hako-cmd start
python3.12 python/tb3_route_demo.py --pattern figure8 --linear-axis 0.6 --yaw-axis 0.7

tb3_sim_waffle defaults to config/assets/tb3-mbody-waffle-asset.json, runs without the viewer, and uses a Waffle wheel separation default of 0.288. Set HAKO_TB3_ENABLE_VIEWER=1 to show the viewer.

For the MBody-generated TurtleBot3 Waffle Pi runtime demo, use:

./src/cmake-build/main_for_sample/tb3/tb3_sim_waffle_pi
/usr/local/hakoniwa/bin/hako-cmd start
python3.12 python/tb3_route_demo.py --pattern figure8 --linear-axis 0.6 --yaw-axis 0.7

tb3_sim_waffle_pi defaults to config/assets/tb3-mbody-waffle-pi-asset.json, runs without the viewer, and uses a Waffle-compatible wheel separation default of 0.288. Set HAKO_TB3_ENABLE_VIEWER=1 to show the viewer.

3. LiDAR visualizer

python python/lidar_visualizer.py

4. start trigger

hako-cmd start

To switch LiDAR spec:

./src/cmake-build/main_for_sample/tb3/tb3_sim config/sensors/lidar/lds-01.json
./src/cmake-build/main_for_sample/tb3/tb3_sim config/sensors/lidar/lds-02.json
./src/cmake-build/main_for_sample/tb3/tb3_sim config/sensors/lidar/urg-04lx-ug01.json

Quick Start: Forklift

This is the shortest path for the forklift unit sample.

Prepare 3 terminals.

1. simulator

./src/cmake-build/main_for_sample/forklift/forklift_unit_sim

2. Python controller

python -m python.forklift_simple_auto config/forklift-unit-compact.json \
  --forward-distance 2.0 --backward-distance 2.0 --move-speed 0.7

3. start trigger

hako-cmd start

For compatibility, controll.bash is temporarily kept and internally calls control.bash.

---

Prerequisites

1) Clone this repository with its pinned dependencies

The normal standalone build uses the Hakoniwa Core and PDU Endpoint submodules pinned by this repository.

git clone https://github.com/hakoniwalab/hakoniwa-mujoco-robots.git
cd hakoniwa-mujoco-robots
git submodule update --init --recursive

Choose one writable install prefix and use it consistently for Core and Endpoint:

export HAKONIWA_INSTALL_PREFIX="${HAKONIWA_INSTALL_PREFIX:-$HOME/.local/hakoniwa}"
export HAKONIWA_CORE_ROOT="$HAKONIWA_INSTALL_PREFIX"
export HAKONIWA_PDU_ENDPOINT_ROOT="$HAKONIWA_INSTALL_PREFIX"

2) Build and install Core + Core-enabled Endpoint through hako.py

Build and install Hakoniwa Core first:

python thirdparty/hakoniwa-core-pro/tools/hako.py doctor \
  --config config/build/hakoniwa-core-runtime.yaml
python thirdparty/hakoniwa-core-pro/tools/hako.py build \
  --config config/build/hakoniwa-core-runtime.yaml \
  --install-dir "$HAKONIWA_INSTALL_PREFIX"
python thirdparty/hakoniwa-core-pro/tools/hako.py install \
  --config config/build/hakoniwa-core-runtime.yaml \
  --install-dir "$HAKONIWA_INSTALL_PREFIX"

The Core profile config/build/hakoniwa-core-runtime.yaml keeps the pinned runtime capacity while disabling Core component tests that are not required by this consumer build.

This repository's runtime configs use Hakoniwa shared memory. Therefore hakoniwa-pdu-endpoint must be built with Hakoniwa Core support enabled. Use the repository-owned build profile:

config/build/hakoniwa-pdu-endpoint-core.yaml

Then build and install Endpoint:

python thirdparty/hakoniwa-pdu-endpoint/tools/hako.py doctor \
  --config config/build/hakoniwa-pdu-endpoint-core.yaml

python thirdparty/hakoniwa-pdu-endpoint/tools/hako.py build \
  --config config/build/hakoniwa-pdu-endpoint-core.yaml

python thirdparty/hakoniwa-pdu-endpoint/tools/hako.py install \
  --config config/build/hakoniwa-pdu-endpoint-core.yaml \
  --install-dir "$HAKONIWA_INSTALL_PREFIX"

The Endpoint repository's default hakoniwa-build.yaml intentionally keeps features.hakoniwa_core: false because TCP/UDP/WebSocket/Storage and similar Core-free uses do not require Hakoniwa Core. Do not change that default for this repository. The MuJoCo Robots profile explicitly requests features.hakoniwa_core: true and disables Endpoint benchmarks that are not part of this runtime dependency.

3) Install Python runtime packages (required for Python tools)

Python controllers and visualizers under python/ are intended to run with Python 3.12. They use two Python-side Hakoniwa pieces:

• hakopy: Hakoniwa core Python binding installed by hakoniwa-core-pro.
• hakoniwa-pdu: PDU message types, serializers, and PduManager installed with pip.

Install hakoniwa-core-pro first, following its README. The core install step installs the hakopy Python binding. Newer installer flows may also write a Hakoniwa environment file; source it when it exists:

test -f ${HAKONIWA_INSTALL_PREFIX}/env.bash && source ${HAKONIWA_INSTALL_PREFIX}/env.bash

If that file does not exist, set the equivalent environment variables manually when needed:

export HAKONIWA_HOME="${HAKONIWA_INSTALL_PREFIX}"
export PATH="${HAKONIWA_HOME}/bin:${PATH}"
export CMAKE_PREFIX_PATH="${HAKONIWA_HOME}:${CMAKE_PREFIX_PATH:-}"
export PKG_CONFIG_PATH="${HAKONIWA_HOME}/lib/pkgconfig:${PKG_CONFIG_PATH:-}"

Then use the same Python 3.12 executable for checks, installs, and scripts:

python3.12 -c "import hakopy; print(hakopy)"
python3.12 -m pip install --upgrade "hakoniwa-pdu>=1.6.1"

If Python 3.12 is managed by a version manager such as pyenv, use the same resolved executable consistently:

PYTHON_CMD="$(command -v python3.12)" ./doctor.bash
"$(command -v python3.12)" python/tb3_route_demo.py --pattern square

Check the installed version:

python3.12 -m pip show hakoniwa-pdu

This is required for commands such as:

python3.12 python/tb3_gamepad.py
python3.12 python/tb3_route_demo.py --pattern square
python3.12 -m python.forklift_simple_auto config/forklift-unit-compact.json
python3.12 python/lidar_visualizer.py

4) OS notes

• macOS: brew install glfw
• Ubuntu:

sudo apt-get update
sudo apt-get install -y libgl1 libgl1-mesa-dri libglx-mesa0 mesa-utils libglfw3-dev

---

Setup

After the Core and Core-enabled Endpoint packages above are installed:

python tools/hako.py doctor
python tools/hako.py build

• MuJoCo version is managed by MUJOCO_VERSION.txt.
• tools/hako.py is the normal user-facing build entry point. The legacy build.bash / build-win.ps1 drivers remain underneath for platform-specific compatibility.
• doctor.bash also verifies that the installed Endpoint package exports hakoniwa_pdu_endpoint::core_callback; a Core-free Endpoint install is reported before runtime.

TurtleBot3 SHM smoke check

TurtleBot3 is a convenient end-to-end check because its Endpoint configuration uses protocol: "shm".

./src/cmake-build/main_for_sample/tb3/tb3_sim

A Core-enabled Endpoint should allow the simulator to pass Endpoint creation. In particular, it must not fail with:

protocol 'shm' requested but Hakoniwa core support is disabled

The same Core-enabled Endpoint contract is used by the other Hakoniwa SHM examples in this repository.

Environment Diagnostics

Run this before ./build.bash when setting up a new machine:

./doctor.bash

The doctor command checks local prerequisites without building:

• CMake and Git
• hakoniwa-core-pro package config
• hakoniwa-pdu-endpoint package config
• hakoniwa-pdu >= 1.6.1 for Python tools
• glfw3
• MUJOCO_VERSION.txt

Fix reported failures first, then run ./build.bash.

Windows (MSVC + PowerShell)

The Windows build is intended to run after hakoniwa-core-pro and hakoniwa-pdu-endpoint have already been built and installed on Windows.

Prerequisites:

• hakoniwa-core-pro is installed under a prefix such as C:\project\hakoniwa-core-pro\install
• hakoniwa-pdu-endpoint is installed under a prefix such as C:\project\hakoniwa-pdu-endpoint\install
• vcpkg packages for Windows are available under C:\project\vcpkg\installed\x64-windows
• Run the build from Windows PowerShell when possible

PowerShell:

.\build-win.ps1 -Clean `
  -HakoniwaCoreRoot C:\project\hakoniwa-core-pro\install `
  -HakoniwaPduEndpointRoot C:\project\hakoniwa-pdu-endpoint\install `
  -ExtraPrefixPaths C:\project\vcpkg\installed\x64-windows

WSL / Git Bash wrapper:

./build-win.bash

Notes:

• build-win.ps1 runs a preflight check before CMake and reports missing install roots, missing package config files, and missing glfw3 / vcpkg prefix information.
• The script configures with -S src, matching the existing Unix build layout.
• HakoniwaCoreRoot is forwarded to HAKONIWA_INSTALL_PREFIX.
• HakoniwaPduEndpointRoot is forwarded to HAKONIWA_PDU_ENDPOINT_PREFIX.
• ExtraPrefixPaths is used to resolve Windows packages such as glfw3 and transitive dependencies required by hakoniwa_pdu_endpoint.
• HakoniwaPduEndpointRoot must point to an installed prefix created by cmake --install, not a build directory such as build-win or build-shared. The hakoniwa_pdu_endpointConfig.cmake generated in the build tree is not directly consumable by this project.
• If you build hakoniwa-pdu-endpoint yourself, install it first:

cmake --install C:\project\hakoniwa-pdu-endpoint\build-win --config Release --prefix C:\project\hakoniwa-pdu-endpoint\install

• Successful outputs are generated under build-win/Release/mujoco-common.lib.
• Successful outputs are generated under build-win/sensors/Release/msensors.lib.
• Successful outputs are generated under build-win/main_for_sample/forklift/Release/forklift_sim.exe.
• Successful outputs are generated under build-win/main_for_sample/forklift/Release/forklift_unit_sim.exe.
• Successful outputs are generated under build-win/main_for_sample/tb3/Release/tb3_sim.exe.
• On Windows, runtime DLLs such as hakoniwa_pdu_endpoint.dll are copied next to each .exe after build.
• If Windows reports forklift_simulation_loop.obj: Permission denied, that is a file lock issue, not a source code issue. Close MSBuild.exe, cl.exe, or devenv.exe and rebuild.
• The Python endpoint binding is built separately from the C++ samples. For python/tb3_gamepad.py, build the vendored thirdparty/hakoniwa-pdu-endpoint Python runtime with Hakoniwa core support enabled:

cd .\thirdparty\hakoniwa-pdu-endpoint
.\build-python-win.ps1 `
  -Clean `
  -BuildNative `
  -BuildFfi `
  -EnableHakoniwaCore `
  -HakoniwaCoreRoot C:\project\hakoniwa-core-pro\install `
  -BuildDirName build-win `
  -Configuration Release `
  -PythonCommand python `
  -ToolchainFile C:\project\vcpkg\scripts\buildsystems\vcpkg.cmake `
  -VcpkgTriplet x64-windows `
  -Platform x64

• python/tb3_gamepad.py prefers the vendored Python package under thirdparty/hakoniwa-pdu-endpoint/python, so it will use the locally built runtime instead of a stale site-packages installation when both are present.

Detailed Run Commands

C++ samples

• Forklift:

./src/cmake-build/main_for_sample/forklift/forklift_sim

• Forklift unit (no cargo, useful for auto-control tests):

./src/cmake-build/main_for_sample/forklift/forklift_unit_sim

• TurtleBot3 (Hakoniwa asset + endpoint gamepad + 2D LiDAR):

./src/cmake-build/main_for_sample/tb3/tb3_sim

• TurtleBot3 (switch LiDAR spec):

./src/cmake-build/main_for_sample/tb3/tb3_sim config/sensors/lidar/lds-01.json
./src/cmake-build/main_for_sample/tb3/tb3_sim config/sensors/lidar/lds-02.json
./src/cmake-build/main_for_sample/tb3/tb3_sim config/sensors/lidar/urg-04lx-ug01.json

Python samples

• Minimal auto control:

python -m python.forklift_simple_auto config/custom-compact.json

• For unit model:

python -m python.forklift_simple_auto config/forklift-unit-compact.json --forward-distance 1.5 --backward-distance 1.5 --move-speed 0.7

• API control sample:

python -m python.forklift_api_control config/safety-forklift-pdu-compact.json config/monitor_camera_config.json

• Gamepad sample:

python -m python.forklift_gamepad config/custom-compact.json

• TurtleBot3 gamepad control:

python python/tb3_gamepad.py

• TurtleBot3 scripted route demo without a joystick:

python python/tb3_route_demo.py --pattern square

• LiDAR visualizer:

python python/lidar_visualizer.py

Standalone examples

• Ultrasonic sensor example:

./src/cmake-build/examples/sensors/ultrasonic/ultrasonic-example

• Color camera sensor example (i/k/j/l moves the camera, s writes a PNG from the viewer or terminal):

./src/cmake-build/examples/sensors/color_camera/color-camera-example

• Joint actuator example (a/d changes position target, j/l changes velocity target in the MuJoCo viewer):

./src/cmake-build/examples/actuators/joint/joint-actuator-example

See examples/README.md for the current example index.

---

TurtleBot3 2D LiDAR

The TurtleBot3 Burger sample includes a MuJoCo-based 2D LiDAR implementation.

Note:

• models/tb3/turtlebot3_burger_world.xml currently uses primitive geoms for the body, wheels, and LiDAR housing instead of external mesh files.

• This avoids runtime failures caused by machine-specific absolute mesh paths when running on Windows.

• The wheel actuators are MuJoCo <velocity> actuators. Gamepad input is converted to left / right wheel angular velocity targets before being written through JointActuatorImpl.

• Linear velocity and yaw-rate targets are rate-limited before conversion to wheel angular velocities. Defaults include HAKO_TB3_MAX_YAW_RATE=1.2, HAKO_TB3_MAX_LINEAR_ACCELERATION=0.1, HAKO_TB3_MAX_YAW_ACCELERATION=0.5, and HAKO_TB3_COMMAND_DEADZONE=0.1.

• The rear caster uses low friction so it does not dominate the drive-wheel behavior.

• 360-degree raycast

• scan-frame generation based on the selected sensor profile

  • e.g. 10 Hz / 100 ms for urg-04lx-ug01.json
  • e.g. 5 Hz / 200 ms for lds-01.json and lds-02.json

• LaserScan-compatible PDU published on Hakoniwa

• Point cloud inspection via Python visualizer

To avoid MuJoCo ray self / near-body interference around the LiDAR mount, the implementation detects self-geometry hits and retries raycasting just beyond the hit point. This avoids relying on a large fixed origin offset and keeps close obstacle perception more natural.

Sensor Noise Profiles

LiDAR behavior can be switched by sensor config JSON.

• config/sensors/lidar/lds-01.json

  • noisy profile close to TurtleBot3 standard LDS-01
  • range: 0.12-3.5 m
  • scan: 5 Hz, 1.0 deg resolution
  • spec: https://emanual.robotis.com/docs/en/platform/turtlebot3/appendix_lds_01/

• config/sensors/lidar/lds-02.json

  • longer-range profile close to TurtleBot3 LDS-02
  • range: 0.16-8.0 m
  • scan: 5 Hz, 1.0 deg resolution
  • spec: https://emanual.robotis.com/docs/en/platform/turtlebot3/appendix_lds_02/

• config/sensors/lidar/urg-04lx-ug01.json

  • cleaner profile based on Hokuyo URG-04LX-UG01
  • range: 0.02-5.56 m
  • scan: 10 Hz, 0.3515625 deg resolution
  • useful for comparing clearer obstacle contours against LDS-style profiles

Switch example:

./src/cmake-build/main_for_sample/tb3/tb3_sim config/sensors/lidar/lds-01.json
./src/cmake-build/main_for_sample/tb3/tb3_sim config/sensors/lidar/lds-02.json
./src/cmake-build/main_for_sample/tb3/tb3_sim config/sensors/lidar/urg-04lx-ug01.json

This is intended to capture a practical Sim2Real point: changing sensors changes perception quality.

Camera Depth Status

Camera / depth / RGBD sensor components are available under include/sensors/camera/ and src/sensors/camera/.

• Depth conversion currently assumes the MuJoCo offscreen path where mjr_readPixels returns an OpenGL-style depth buffer.
• Camera rendering temporarily applies each sensor JSON clip.near/far to MuJoCo's effective clip planes before reading RGB/depth pixels.
• Camera / depth / RGBD / multicamera profiles under config/sensors/camera/*.json can be loaded into C++ configs.
• The profile structure is documented in config/sensors/schema/, and the JSON loader reuses the existing LoadConfig(config) validation path.
• Camera unit tests live under tests/sensors/camera/unit/ and cover config loader, PDU converter, and local depth encoding.
• These unit tests do not require an OpenGL render context and are intended to run in CI.
• This path has been smoke-tested with fixed-camera box scenes at 0.2, 0.5, 1.0, 2.0, 5.0, and 9.0 meters.
• The smoke test also checks several image positions, multiple horizontal FOV settings, and clip-range NaN masking.
• Render smoke tests live under tests/sensors/camera/smoke/ and require MuJoCo + OpenGL, so they are intended for local/manual runs or dedicated CI.
• It is still not claimed to be fully validated for arbitrary scenes such as oblique geometry, extreme camera setups, or alternative depth-map conventions.

Sensor Components And Examples

Reusable sensor components live under src/sensors/, with JSON profiles under config/sensors/ and schemas under config/sensors/schema/. PDU converters and adapters live under include/hakoniwa/pdu/.

Design and schema references:

• Sensor/Actuator User Guide
• JSON Config Guide
• MJCF / JSON Authoring Guide
• Sensor/Actuator PDU Design
• Sensor/Actuator Config Schemas

Current sensor areas:

• camera / depth / RGBD / multicamera
• color camera PNG example
• 2D LiDAR
• ultrasonic range
• IMU
• joint state
• odometry
• TF
• noise helpers
• debug ray visualization

The standalone examples are intentionally smaller than the TurtleBot3 and forklift demos. They are useful for checking one feature at a time:

• examples/README.md
• examples/sensors/README.md
• examples/sensors/ultrasonic/README.md
• examples/sensors/color_camera/README.md
• examples/actuators/README.md
• examples/actuators/joint/README.md

Sensor unit tests are optional build targets:

cmake -S src -B src/cmake-build -DHAKO_BUILD_SENSOR_TESTS=ON
cmake --build src/cmake-build --target run_sensor_unit_tests

Camera render smoke tests require a MuJoCo / OpenGL runtime:

cmake -S src -B src/cmake-build -DHAKO_BUILD_CAMERA_SMOKE_TESTS=ON
cmake --build src/cmake-build --target camera_smoke_tests

Docker (Ubuntu 24.04)

Create image:

bash docker/create-image.bash

Run:

bash docker/run.bash

Build in container:

bash build.bash

Notes:

• Ubuntu + Docker: GUI supported
• macOS + Docker: treat as headless recommended

HAKO_DOCKER_GUI=off bash docker/run.bash

---

FAQ

Q1. What should I run first?

Run the environment doctor first:

./doctor.bash

Fix any FAIL lines, then run:

./build.bash

Q2. Python tools fail even after installing hakoniwa-pdu. Why?

hakoniwa-pdu does not provide hakopy. hakopy is the Python binding built and installed by hakoniwa-core-pro, and this repository expects Python 3.12 for Python-side Hakoniwa tools.

The most common cause is a Python environment mismatch. These must all refer to the same Python 3.12 environment:

• the Python used when hakoniwa-core-pro installed hakopy
• the Python used to run python3.12 -m pip install hakoniwa-pdu
• the Python used to run scripts such as python/tb3_route_demo.py

First install hakoniwa-core-pro following its README, then check that hakopy is visible to Python 3.12:

test -f ${HAKONIWA_INSTALL_PREFIX}/env.bash && source ${HAKONIWA_INSTALL_PREFIX}/env.bash
python3.12 -c "import hakopy; print(hakopy)"

Then install hakoniwa-pdu into that same Python:

python3.12 -m pip show hakoniwa-pdu
python3.12 -m pip install --upgrade "hakoniwa-pdu>=1.6.1"

If import hakopy fails, reinstall or rebuild hakoniwa-core-pro with Python 3.12 available, then re-run the install step. ./doctor.bash prints the Python executable it checks.

If you want to check a specific Python environment, pass PYTHON_CMD:

PYTHON_CMD=/path/to/python3.12 ./doctor.bash
/path/to/python3.12 -m pip install --upgrade "hakoniwa-pdu>=1.6.1"

Q3. CMake cannot find hakoniwa-core-pro or hakoniwa-pdu-endpoint.

Build/install both dependencies through the manifest-driven hako.py flow in Prerequisites, then re-run python tools/hako.py doctor.

The Endpoint install must export hakoniwa_pdu_endpoint::core_callback; the Core-free Endpoint default is not sufficient for this repository's SHM configs. Use config/build/hakoniwa-pdu-endpoint-core.yaml.

If the packages are installed under a custom prefix, set:

export HAKONIWA_CORE_ROOT=/path/to/hakoniwa/install
export HAKONIWA_PDU_ENDPOINT_ROOT=/path/to/hakoniwa/install

Q4. CMake cannot find glfw3.

Install GLFW:

brew install glfw

Ubuntu:

sudo apt-get install -y libglfw3-dev

Q5. Where does the color-camera example write PNG files?

By default, it writes ./camera_color_sample.png relative to the directory where you run the command. You can pass an explicit output path as the third argument.

Q6. Do I need the MuJoCo viewer for every example?

No. The main robot demos use the viewer by default, and the standalone sensor / actuator examples are designed for interactive viewer use. Some tests and config checks do not need a viewer.

For Docker on macOS, use headless mode:

HAKO_DOCKER_GUI=off bash docker/run.bash

Advanced Topics

Advanced forklift context save/restore and RD-light notes are split out of the top-level README.

• Forklift Context Save/Restore And RD-light
• RD design notes
• Sensor/Actuator PDU Design
• Sensor/Actuator Config Schemas

The top-level README keeps only the entry points, setup, and sample commands. Use the advanced documents when you need restore evidence, RD-light handoff details, or continuity evaluation workflow.

Samples

• src/main_for_sample/forklift/main.cpp: forklift basic integration
• src/main_for_sample/forklift/main_unit.cpp: unit model verification
• src/main_for_sample/tb3/main.cpp: TurtleBot3 sample (Hakoniwa asset / endpoint / 2D LiDAR)
• python/tb3_gamepad.py: TurtleBot3 Python controller asset (PS4/DualSense)
• python/tb3_route_demo.py: TurtleBot3 scripted route controller for joystick-free demos
• python/lidar_visualizer.py: generic LiDAR visualizer (world view)
• examples/README.md: standalone example index
• examples/sensors/ultrasonic/README.md: ultrasonic sensor example
• examples/sensors/color_camera/README.md: color camera PNG example
• examples/actuators/joint/README.md: MJCF-native position / velocity joint actuator example
• src/sensors/: reusable sensor components
• include/hakoniwa/pdu/: PDU conversion and endpoint adapter helpers
• docs/spec/sensor-actuator-design.md: sensor/actuator PDU design notes
• docs/spec/sensor-actuator-config-schema.md: sensor/actuator config schema guide
• config/sensors/lidar/lds-01.json: TurtleBot3 LDS-01-like noisy LiDAR profile
• config/sensors/lidar/lds-02.json: TurtleBot3 LDS-02-like longer-range LiDAR profile
• config/sensors/lidar/urg-04lx-ug01.json: Hokuyo URG-04LX-UG01-like cleaner LiDAR profile
• config/sensors/ultrasonic/lego-spike-distance-sensor.json: ultrasonic range sensor profile used by the standalone example
• config/sensors/color_camera/simple-color-camera.json: color camera profile used by the PNG example

---

Contributing

• Read CONTRIBUTING.md before opening an issue or pull request.
• Coding agents should also read AGENTS.md.
• For setup failures, include ./doctor.bash output in the issue.
• For viewer examples, mention whether the behavior was manually checked.

---

Roadmap

• Windows run flow (build/run/log)
• Keep compact-only runtime checks and diagnostics (hakoniwa-pdu version / PDU resolution)
• Operational hardening of Python controller asset mode (tick-synchronized path)
• Expand saved scope (cargo/shelf/etc.)
• Automated restore consistency checks (log verification scripts)
• Safe handoff diagnosability (optional logs: reason=contact_active / near_collision / constraint_active)
• RD integration for context handoff design

---

License

MIT License

Separate native build directory

python tools/hako.py build --build-dir /path/to/environment/mujoco-build selects an external build directory on POSIX and Windows. The CLI option overrides build.dir in the manifest. Relative CLI paths use the current directory; ~ and symlinks are resolved. Without this option, the existing manifest/native defaults remain in effect. POSIX builds use HAKONIWA_CORE_ROOT, then HAKONIWA_HOME, then /usr/local/hakoniwa for the Core prefix.

Concrete Ackermann vehicle applications, Recipes, and PS5 frontends are owned by hakoniwa-urban-mobility. This repository provides the shared MuJoCo physics, Viewer, mirror-body, and contact/impulse backend used by those applications.