rosmac

ROS 2 on your Mac in one command — native rclpy/colcon on macOS, Tier-1 Ubuntu for the heavy stuff, one TCP port between them.

한국어 문서 (Korean)

_{A user's own Franka workspace: colcon build on macOS (RoboStack, no Docker), then ros2 launch with RViz on the Mac. ▶ full clip · ▶ Mac↔VM bridge (teleop over one TCP port)}

ROS 2 does not really support macOS (Tier 3; Apple Silicon isn't even listed). Existing workarounds each hit a wall: Docker on macOS has no --network=host, so host↔container DDS discovery is broken by design; plain VMs give up on Mac-side tooling entirely; and while RoboStack ships surprisingly many osx-arm64 packages, the heavy stack (MoveIt, Gazebo) is present but not dependable there — dylib breakage and runtime crashes are field-measured, not hypothetical.

rosmac splits the problem instead of fighting it:

develop natively on the Mac (RoboStack: rclpy, colcon, ros2 CLI)
        ↕  zenoh bridge — a single TCP port (7447), no DDS multicast at the boundary
run the heavy stack where it's Tier 1 (Lima VM, Ubuntu 22.04 arm64: MoveIt, Gazebo)
        →  visualize on the Mac (Foxglove, ws:8765)
        ⇢  optional: a real robot on your LAN — one more TCP endpoint, same model
           (beta, [docs/robot-setup.md](docs/robot-setup.md))

What makes it more than an install script:

• rosmac doctor — 16 checks for known failure modes, --fix auto-repairs the safe ones (hung ros2 daemon, orphan bridges, broken lima port rules). Built from a database of 29 field-measured macOS/ROS pitfalls, not a wiki of hope.
• rosmac deps — maps your workspace's package.xml dependencies to RoboStack conda packages (a rosdep substitute that actually knows about conda).
• rosmac push --build — anything Linux-only gets copied to the VM and built there.
• rosmac report — one tar.gz diagnostic bundle for issue reports (collects only from ~/.rosmac).

Support matrix

Versioning: SemVer. While 0.y.z, minor versions may break. See CHANGELOG.md.

Requirements

• Homebrew, ≥ 40 GB free disk
• Foxglove app (optional, for visualization)

Quickstart (~6 min measured; +10 min without download caches)

brew install lima micromamba
git clone https://github.com/PythonToGo/rosmac && cd rosmac
python3.12 -m venv .venv && .venv/bin/pip install -e .
export PATH="$PWD/.venv/bin:$PATH"

rosmac init      # conda env + bridge binary + VM provisioning (idempotent)
rosmac up        # start VM + both zenoh bridges
rosmac doctor    # 16 checks — C8 self-verifies a full topic round-trip

Smoke test:

rosmac shell --vm -c 'nohup ros2 run demo_nodes_cpp talker >/dev/null 2>&1 & echo ok'
rosmac shell -c 'ros2 topic echo /chatter --once'   # VM topic received on the Mac

Simulation presets

rosmac sim panda-moveit     # MoveIt (Panda arm) — /move_action usable from the Mac
rosmac sim gazebo-diffbot   # Gazebo Fortress headless + front camera
rosmac sim nav2-diffbot     # Nav2 mobile navigation — /navigate_to_pose from the Mac
rosmac sim list / status / stop / --attach
rosmac viz --layout nav2    # Foxglove connection (+ layout import guide)

nav2-diffbot runs SLAM + Nav2 on a lidar diffbot in a walled arena; drive it with /cmd_vel to build the map, then send /navigate_to_pose goals from the Mac. The full Nav2 stack works over the default bridge — rosmac sim resets the bridge session on start so a new stack gets fresh routes (KI-17).

The native dev loop and a worked example (pick_demo) live in docs/workflow.md.

Bring your own workspace

rosmac deps ~/my_ws --install   # package.xml deps → RoboStack packages (rosdep substitute)
rosmac shell                    # colcon build inside — legacy-CMake pitfalls auto-bypassed
rosmac ps                       # stuck? Mac+VM processes & publishers on one screen
rosmac push ~/my_ws --build     # Linux-only packages (libfranka, …) build in the VM

Commands

Exit codes:

Errors are shown as a cause + fix panel; only unexpected errors show a traceback (attach a rosmac report bundle when filing those).

Measured performance (M3 Pro, 2026-07)

• Bridge throughput: 10.3 MB/s (1 MB @ 10 Hz, no drops)
• MoveGroup action round-trip: plan+execute, 3 consecutive goals SUCCEEDED
• Nav2 /navigate_to_pose from the Mac: 3 consecutive goals SUCCEEDED (default bridge)
• Gazebo Fortress headless RTF: physics-only 1.00 / with camera (320×240 @ 15 Hz) 0.99
• Camera stream: VM 14.4 fps → Mac 14.4 fps (lossless)

Bridge capability matrix (measured 2026-07)

What works across the Mac ↔ VM zenoh bridge:

Structural limits (by design, not bugs):

• A stale bridge silently breaks a fresh stack (KI-17). Restarting the VM sim stack while the bridge keeps running leaves stale routes behind, so the new stack's action sub-services fail to discover from the Mac (measured: 0/6, then 4/4 after a bridge restart). rosmac sim resets the bridge session on start to avoid this — the full Nav2 stack then works over the default bridge, no scoping.
• Every Mac↔VM message crosses one bridge hop. Fine for dev, teleop and visualization; high-rate closed control loops belong inside the VM (or on the robot).
• macOS-local DDS discovery can be silently degraded by other lima VMs that lack UDP ignore rules (KI-28). rosmac's own VM ships the rules; see known-issues KI-28 for the remedy.
• The VM is headless (D2) — no RViz2/GUI inside; Foxglove on the Mac is the visualization path (rosmac viz).

Architecture & design decisions

• Why not just use Docker / a full VM / RoboStack alone: docs/why-rosmac.md
• Decision log and risk register: PLAN.md
• When stuck: docs/troubleshooting.md (common failure modes + fix commands), backed by the field-measured known-issues database (30 pitfalls)

Contributing

Bug reports (with a rosmac report bundle), pitfall contributions, and PRs within scope are welcome — see CONTRIBUTING.md and the Code of Conduct. Security issues: SECURITY.md.

License

MIT. Bundled simulation presets are adapted from Apache-2.0 / BSD-3-Clause upstream ROS and Gazebo examples — see THIRD-PARTY-NOTICES.md.