Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
19 changes: 14 additions & 5 deletions CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -33,7 +33,9 @@ configured per robot, and start from one bringup package, `golem_bringup`. Each
against its sim and the real robot, so code moves between them unchanged. The
G1 runs in Unitree's debug mode: Unitree's own controller is released, and the
stack drives every motor on `rt/lowcmd`, as on the H1-2. The stack runs on one
platform, x86 Linux with an NVIDIA GPU.
platform, x86 Linux with an NVIDIA GPU. An Apple Silicon Mac runs a reduced
RoboCasa sim of either robot at real time (no model servers or Isaac; the lidar
cast on the CPU, with fewer points): `docs/MAC.md`.

The H1-2 is the default everywhere. `GOLEM_ROBOT=g1` or `--g1` on a simulator or
stack wrapper selects the G1 where the attached robot matters: the sim and
Expand All @@ -45,7 +47,7 @@ pages are in `docs/g1/` (start at `docs/g1/index.md`).

| Path | What it is |
|---|---|
| `docker/` | the images and containers (Dockerfiles, `docker-compose.yml`, the G1 overlay `docker-compose.g1.yml`, `scripts/`) |
| `docker/` | the images and containers (Dockerfiles, `docker-compose.yml`, the G1 overlay `docker-compose.g1.yml`, `scripts/`; the Mac's arm64 images in `docker/mac/` with the overlay `docker-compose.mac.yml`, `docs/MAC.md`) |
| `core_ws/` | the ROS 2 workspace — where the bulk of development happens (see §4); the G1's own package is `core_ws/src/dex_3/`, the safety layer, arm controller, leg controller, SLAM/navigation and skills both robots run in `core_ws/src/golem_safety/`, `core_ws/src/golem_upper_ik/`, `core_ws/src/golem_lowerbody_rl/`, `core_ws/src/golem_slam/` and `core_ws/src/golem_skills/` |
| `golem_robocasa/` | RoboCasa/MuJoCo simulator entry point for both robots (`h12_mujoco.py`; `--g1` hands over to the G1 sim package `golem_robocasa/g1/`) and the ROS/DDS bridges |
| `CL_isaaclab_sim/` | Isaac Lab simulator, H1-2 only (`sim_main.py`, DDS bridges, tasks) |
Expand Down Expand Up @@ -89,7 +91,11 @@ launch bringup**.

### Robot selection

`docker/scripts/docker_common.sh` owns this. On simulator and stack wrappers,
`docker/scripts/docker_common.sh` owns this, and the platform too: on Darwin
arm64 (or `GOLEM_PLATFORM=mac`) every wrapper adds `docker-compose.mac.yml`
(the arm64 images of `docker/mac/`, no NVIDIA runtime, `GOLEM_RENDER=cpu`,
`GOLEM_LIDAR_POINTS` 6000 for the H1-2 and 10000 for the G1 unless set), refuses Isaac, and `docker_stack.sh` starts `h12_mac_sim` or
`g1_mac_sim`; on Linux nothing changes (`docs/MAC.md`). On simulator and stack wrappers,
the robot is `--g1`/`--h12` on the wrapper, else `GOLEM_ROBOT` from the shell,
else from `docker/.env`, else `h12`. The selection means "which robot is
attached" and matters only where that is inherent: which robot the RoboCasa sim
Expand Down Expand Up @@ -519,7 +525,10 @@ H1-2 imports and hands the G1 over to `golem_robocasa/g1/g1_mujoco.py`. Both
sims render their cameras and the MID-360's rays through EGL on an NVIDIA GPU:
without one (MuJoCo not on EGL, no EGL device, a software renderer) the sim
stops at start, once its command line is parsed and before it builds a scene or
starts ROS or DDS, with one message (`sim_common.require_gpu`). The H1-2
starts ROS or DDS, with one message (`sim_common.require_gpu`). The one way past
it is the Mac images' opt-in `GOLEM_RENDER=cpu` (OSMesa for the cameras, the
MID-360 cast exactly on the CPU by `mid360.CpuCaster`; `sim_common.require_renderer`,
`mid360.make_caster`). The H1-2
stays the default, and nothing on the G1 path may change its behaviour. The robots share
`sim_common.py`, `measurement_bridge.py`, the pacer in `sim_timing.py` (its
`--timing` report is the H1-2's only) and the `mujoco_sensors` node in
Expand Down Expand Up @@ -550,7 +559,7 @@ with a valid CRC, `mode_machine` 6, `mode_pr` 0 and finite values (other frames
are dropped); after that, `GOLEM_CMD_TIMEOUT` of silence turns every motor off
until frames return. Its MID-360 is the model both robots share
(`golem_robocasa/mid360.py`): the real scan pattern, 20,000 points a 10 Hz
frame on lines 0-3, each point's `offset_time` the time of the pose it was cast
frame (`GOLEM_LIDAR_POINTS`, which only the Mac's compose file passes to it) on lines 0-3, each point's `offset_time` the time of the pose it was cast
from, and each ray without a return a point at (0, 0, 0), as the real driver
publishes it; `/livox/lidar` and `/livox/pointcloud` carry the same frame. Its rays are
read from depth images rendered on the GPU (`mid360.GpuCaster`, as on the G1),
Expand Down
38 changes: 38 additions & 0 deletions core_ws/src/golem_bringup/launch/g1/g1_mac_sim.launch.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,38 @@
"""
Start the G1 against the Mac's RoboCasa sim: g1_sim without skills or the hand driver.

ros2 launch golem_bringup g1_mac_sim.launch.py [use_hands:=true] [use_rviz:=true]

The Mac sim (docker/docker-compose.mac.yml, docs/MAC.md) renders on the CPU and casts its
MID-360 on the CPU, and an 8-core Mac holds real time only without the Dex3-1 hand
driver, so this includes g1_sim.launch.py with use_skills false and use_hands false by
default. Everything else is g1_sim's: g1_core with sim:=true (golem_safety and the
controller on sim_split, the leg node running HOMIE, which releases the sim's elastic band
once the policy runs), navigation (golem_slam on FAST-LIO) and, with use_rviz, RViz.

Start the simulator first; every node joins the launching shell's ROS_DOMAIN_ID, which
must be a sim domain (safety_node refuses sim:=true on domain 0).
"""

from golem_bringup.include import include
from launch import LaunchDescription
from launch.actions import DeclareLaunchArgument
from launch.substitutions import LaunchConfiguration


def generate_launch_description():
"""Declare the Mac bringup's arguments and include g1_sim without skills."""
return LaunchDescription([
DeclareLaunchArgument('use_rviz', default_value='false',
description='true: start RViz (needs a display in golem_ros)'),
DeclareLaunchArgument('use_hands', default_value='false',
description='true: start dex3_hands, the Dex3-1 hand driver '
'(about a quarter of a core: the stack then falls '
'below real time on an 8-core Mac)'),
# The whole G1 sim bringup, without the parts the Mac cannot run.
include('golem_bringup', 'g1/g1_sim.launch.py', {
'use_rviz': LaunchConfiguration('use_rviz'),
'use_hands': LaunchConfiguration('use_hands'),
'use_skills': 'false',
}),
])
43 changes: 43 additions & 0 deletions core_ws/src/golem_bringup/launch/h12/h12_mac_sim.launch.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,43 @@
"""
Start the H1-2 against the Mac's RoboCasa sim: h12_sim without model servers or skills.

ros2 launch golem_bringup h12_mac_sim.launch.py [policy:=almi] [use_rviz:=false]

The Mac's golem_ros image has no model-server stack (docker/mac/RosDockerfile,
docs/MAC.md), so this includes h12_sim.launch.py with use_vision and use_skills false.
Everything else is h12_sim's, in its order: the leg node's check first, then the state
publishers, the command path (estop_node on the sim's estop box, safety_node,
frame_task_server), the legs, navigation (golem_slam on FAST-LIO, on the MID-360 the Mac
sim casts on the CPU) and, with use_rviz, RViz.

SAFETY: the operator gates are h12_sim's: the sim's estop box (ENTER on the sim's
terminal; golem_safety then latches until restart), and the leg policy holds its
pre-pose until
ros2 service call /lowerbody/confirm_engage std_srvs/srv/Trigger

Start the simulator first; every node joins the launching shell's ROS_DOMAIN_ID, which
must be a sim domain (safety_node refuses sim:=true on domain 0).
"""

from golem_bringup.include import include
from launch import LaunchDescription
from launch.actions import DeclareLaunchArgument
from launch.substitutions import LaunchConfiguration


def generate_launch_description():
"""Declare the Mac bringup's arguments and include h12_sim without vision."""
return LaunchDescription([
DeclareLaunchArgument('use_rviz', default_value='false',
description='true: start RViz (needs a display in golem_ros)'),
DeclareLaunchArgument('policy', default_value='almi',
description='The policy golem_lowerbody_rl runs on the legs: '
'almi, fame or walk; any other is refused'),
# The whole H1-2 sim bringup, without the parts the Mac cannot run.
include('golem_bringup', 'h12/h12_sim.launch.py', {
'use_rviz': LaunchConfiguration('use_rviz'),
'policy': LaunchConfiguration('policy'),
'use_vision': 'false',
'use_skills': 'false',
}),
])
11 changes: 8 additions & 3 deletions core_ws/src/golem_bringup/launch/h12/h12_sim.launch.py
Original file line number Diff line number Diff line change
Expand Up @@ -9,8 +9,9 @@
(h12_control as on the real robot: the safety/controller pairing check before any node,
then estop_node on the sim's estop box, safety_node and frame_task_server with the real
robot's configs and delays), the leg controller (h12_lowerbody, with the start pose taken
as verified), the model servers and golem_skills (golem_vision_models), navigation, the
static camera_link -> camera_color_optical_frame TF and RViz (use_rviz).
as verified), the model servers and golem_skills (golem_vision_models; use_vision,
default true, which h12_mac_sim.launch.py turns off: the Mac has no GPU for them),
navigation, the static camera_link -> camera_color_optical_frame TF and RViz (use_rviz).

SAFETY: the sim runs the real robot's operator gates: the estop box the sim serves (ENTER
on the sim's terminal or viewer presses it; golem_safety then latches until restart), and
Expand Down Expand Up @@ -75,6 +76,10 @@ def generate_launch_description():
'start-up (clear_logs)'),
DeclareLaunchArgument('rviz_config', default_value=default_rviz,
description='RViz config file (path)'),
DeclareLaunchArgument('use_vision', default_value='true',
description='true: start the model servers (gemini, sam, and '
'with use_skills graspgen and golem_skills); '
'false: none of them, use_skills included'),

# SAFETY: first, so a refused policy or run config starts no node: the leg
# block, which checks them too, is included after the others.
Expand Down Expand Up @@ -102,7 +107,7 @@ def generate_launch_description():
'model_visualization': LaunchConfiguration('model_visualization'),
'model_clear_logs': LaunchConfiguration('model_clear_logs'),
'record_runs': LaunchConfiguration('record_runs'),
}),
}, condition=IfCondition(LaunchConfiguration('use_vision'))),
# SLAM and Nav2, driving the legs on /cmd_vel.
include('golem_slam', 'navigation.launch.py', {**sim_time, 'robot': 'h12'}),

Expand Down
4 changes: 2 additions & 2 deletions core_ws/src/golem_bringup/test/test_launch_layout.py
Original file line number Diff line number Diff line change
Expand Up @@ -16,9 +16,9 @@
PACKAGE = Path(__file__).resolve().parents[1]

TOP_LEVEL = {
'h12': ('h12_sim', 'h12_real_robot', 'h12_real_desktop',
'h12': ('h12_sim', 'h12_mac_sim', 'h12_real_robot', 'h12_real_desktop',
'h12_safety_grippers', 'lmg_sim', 'lmg_real'),
'g1': ('g1_sim', 'g1_real_robot'),
'g1': ('g1_sim', 'g1_mac_sim', 'g1_real_robot'),
}

INSTALLED = ('launch/**/*.launch.py', 'rviz/**/*.rviz')
Expand Down
42 changes: 42 additions & 0 deletions core_ws/src/golem_bringup/test/test_sim_time.py
Original file line number Diff line number Diff line change
Expand Up @@ -32,6 +32,8 @@
('lmg_sim.launch.py', {'start_position_verified': 'true', 'use_slam': 'true',
'use_skills': 'true'}, True),
('g1_sim.launch.py', {'use_skills': 'true', 'use_nav': 'true', 'use_rviz': 'true'}, True),
('h12_mac_sim.launch.py', {'use_rviz': 'true'}, True),
('g1_mac_sim.launch.py', {'use_rviz': 'true', 'use_hands': 'true'}, True),
('h12_real_robot.launch.py', {'start_position_verified': 'true'}, False),
('lmg_real.launch.py', {'start_position_verified': 'true'}, False),
('h12_real_desktop.launch.py', {'use_hand_cameras': 'true'}, False),
Expand Down Expand Up @@ -132,3 +134,43 @@ def test_every_node_runs_on_its_bringups_clock(launch_file, args, sim_time, monk
wrong = [(package, executable, name, value) for package, executable, name, value in nodes
if value not in allowed]
assert wrong == [], f'{launch_file}: nodes not on use_sim_time {sim_time}: {wrong}'


# Packages of the nodes the Mac sim bringups leave out: the model servers and skills (no
# GPU stack in the Mac's golem_ros).
VISION = ('model_server', 'golem_skills')


def _packages(launch_file, args):
"""Return the packages of the nodes launch_file starts with args, on a sim domain."""
return {package for package, _, _, _ in _nodes(launch_file, args)}


@pytest.mark.parametrize('mac_file, sim_file, sim_args, core', [
('h12_mac_sim.launch.py', 'h12_sim.launch.py', {'use_rviz': 'false'},
{'golem_safety', 'golem_upper_ik', 'golem_lowerbody_rl', 'estop', 'fast_lio', 'golem_slam'}),
('g1_mac_sim.launch.py', 'g1_sim.launch.py', {'use_rviz': 'false'},
{'golem_safety', 'golem_upper_ik', 'golem_lowerbody_rl', 'fast_lio', 'golem_slam'}),
])
def test_mac_sim_is_the_sim_bringup_without_vision(mac_file, sim_file, sim_args, core,
monkeypatch):
"""A Mac sim bringup starts the command path, legs and navigation, but no model server."""
monkeypatch.setenv('ROS_DOMAIN_ID', SIM_DOMAIN)
mac = _packages(mac_file, {})
assert core <= mac, mac
assert mac.isdisjoint(VISION), mac & set(VISION)
assert mac <= _packages(sim_file, sim_args), mac


def test_g1_mac_sim_leaves_the_hand_driver_out(monkeypatch):
"""g1_mac_sim starts no dex3_hands by default, and does with use_hands:=true."""
monkeypatch.setenv('ROS_DOMAIN_ID', SIM_DOMAIN)
assert 'dex_3' not in _packages('g1_mac_sim.launch.py', {})
assert 'dex_3' in _packages('g1_mac_sim.launch.py', {'use_hands': 'true'})


def test_h12_sim_defaults_keep_vision(monkeypatch):
"""h12_sim.launch.py with its defaults still starts the model servers and skills."""
monkeypatch.setenv('ROS_DOMAIN_ID', SIM_DOMAIN)
packages = _packages('h12_sim.launch.py', {})
assert {'fast_lio', 'model_server', 'golem_skills'} <= packages, packages
7 changes: 7 additions & 0 deletions docker/BUILD.md
Original file line number Diff line number Diff line change
Expand Up @@ -72,6 +72,13 @@ nvcr.io/nvidia/isaac-sim:5.1.0
Its bundled interpreter and ROS bridge are separate from the Humble/Python 3.10
stack in `golem_base`. The Dockerfile also installs ROS Jazzy tooling.

On an Apple Silicon Mac the wrappers build the same graph's arm64 twins
instead, `golem_base:arm64`, `golem_ros:arm64` and `golem_sim_robocasa:arm64`,
from `docker/mac/*Dockerfile` on `ubuntu:jammy` with the `*-arm64*` locks (no
CUDA, no Isaac, no model-server stack; `docs/MAC.md`). Keep their commits and
pins in step with the x86 Dockerfiles: `tests/docker/test_source_pins.py`
checks it.

All containers interoperate over **CycloneDDS on one ROS domain** (default
`ROS_DOMAIN_ID=1`; domain `0` is reserved for the real robots), one robot
stack per domain.
Expand Down
45 changes: 45 additions & 0 deletions docker/docker-compose.mac.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,45 @@
# The Mac (Apple Silicon) overlay on docker-compose.yml. docker_common.sh's
# configure_platform adds it when the platform is mac (Darwin on arm64, or
# GOLEM_PLATFORM=mac), never on Linux, so the x86 / NVIDIA services are as the
# base file declares them. It swaps the images for the arm64 builds of
# docker/mac/, drops the NVIDIA runtime, and sets the sims' CPU rendering.
# Container names, mounts and the host network are the base file's: on
# OrbStack or Docker Desktop (host networking on) both containers share the
# Linux VM's network, so DDS between them works; the macOS host is not on it,
# so ros2 and RViz run inside golem_ros. docs/MAC.md has the flow and what the
# Mac leaves out (the GPU vision models, Isaac).
services:
robocasa:
build:
dockerfile: docker/mac/RobocasaDockerfile
image: golem_sim_robocasa:arm64
platform: linux/arm64
# No NVIDIA GPU: the base file's runtime is removed (Compose >= 2.24).
runtime: !reset null
# 2 GB of /dev/shm: the base file's 16 GB exceeds a laptop VM's memory.
shm_size: 2g
environment:
# gpu (the sims' default, an NVIDIA GPU over EGL) or cpu (OSMesa, the
# MID-360 cast exactly on the CPU): golem_robocasa/sim_common.py. The
# Mac has only cpu.
GOLEM_RENDER: cpu
# Both robots' MID-360 points per frame. configure_robot exports the
# Mac's default per robot (6000 for the H1-2, 10000 for the G1: the
# most each holds real time with on an 8-core M3, docs/MAC.md).
GOLEM_LIDAR_POINTS: ${GOLEM_LIDAR_POINTS:-}
# Software-rendered cameras cost the most per step: off unless asked for.
GOLEM_CAMERAS: ${GOLEM_CAMERAS:-0}
ros:
build:
dockerfile: docker/mac/RosDockerfile
image: golem_ros:arm64
platform: linux/arm64
runtime: !reset null
shm_size: 2g
environment:
# core_ws/cyclonedds.xml, then an override of its 16 MB minimum UDP
# receive buffer: the minimum makes every ROS node fail to create its
# domain unless the kernel's net.core.rmem_max allows it, which the
# OrbStack / Docker Desktop VM does not by default (docs/DDS_TUNING.md
# raises it on Linux hosts).
CYCLONEDDS_URI: "file:///home/code/cyclonedds.xml,<CycloneDDS><Domain><Internal><SocketReceiveBufferSize min=\"default\"/></Internal></Domain></CycloneDDS>"
11 changes: 11 additions & 0 deletions docker/locks/SOURCES.md
Original file line number Diff line number Diff line change
Expand Up @@ -107,3 +107,14 @@ under `/opt/robocasa/robocasa/models/assets` (123,434 files at capture). This
catches changed contents, additions and removals without committing a large
file manifest. Updating assets requires explicit review and regenerating the
digest from the approved tree, not accepting a mismatch during a normal build.

## The Mac's arm64 locks

`*-arm64*.txt` are the Mac images' locks (`docker/mac/`, `docs/MAC.md`), derived
from their `*-amd64*.txt` twins by `docker/mac/derive_arm64_locks.sh`: the CUDA
wheels dropped, torch and torchvision on their `+cpu` builds, open3d 0.18.0
(0.19.0 has no linux/aarch64 wheel). Rerun the script after any amd64 lock
change; `tests/docker/test_source_pins.py` checks they match. The Mac base image
is `ubuntu:jammy-20260901.2`, pinned by digest, and installs `ca-certificates`
from the image's live `ports.ubuntu.com` lists before switching to the snapshot,
the one package not resolved against it.
6 changes: 6 additions & 0 deletions docker/locks/base-arm64-01.txt
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
# Generated by docker/mac/derive_arm64_locks.sh from
# base-amd64-01.txt; edit the amd64 lock and rerun the script.
-c base-arm64.txt
mujoco==3.13.0
numpy==2.2.6
psutil==5.9.0
6 changes: 6 additions & 0 deletions docker/locks/base-arm64-02.txt
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
# Generated by docker/mac/derive_arm64_locks.sh from
# base-amd64-02.txt; edit the amd64 lock and rerun the script.
-c base-arm64.txt
mujoco==3.13.0
numpy==2.2.6
psutil==5.9.0
6 changes: 6 additions & 0 deletions docker/locks/base-arm64-03.txt
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
# Generated by docker/mac/derive_arm64_locks.sh from
# base-amd64-03.txt; edit the amd64 lock and rerun the script.
-c base-arm64.txt
mujoco==3.13.0
numpy==2.2.6
psutil==5.9.0
Loading
Loading