Skip to content
Draft
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
26 changes: 13 additions & 13 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Lucy ROS 2 workspace (Humble)

Workspace bringup for the Lucy / InMoov humanoid. Everything (ROS 2 Humble, Gazebo, RViz, the web control panel) runs inside a single Docker container — you only need **Docker**, **Git** and **Python 3** on the host (plus **`xhost`** on Linux for GUI forwarding; on macOS the GUI is viewed over VNC with no extra software see [GUI: RViz and Gazebo](#gui-rviz-and-gazebo)).
Workspace bringup for the Lucy / InMoov humanoid. Everything (ROS 2 Humble, Gazebo, RViz, the web control panel) runs inside a single Docker container — you only need **Docker**, **Git** and **Python 3** on the host. GUI apps (RViz, Gazebo) render on a VNC desktop you view from your browser, with no extra software (see [GUI: RViz and Gazebo](#gui-rviz-and-gazebo)).

## Requirements

Expand Down Expand Up @@ -109,22 +109,22 @@ This setting is stored in a `.env` file.

RViz, Gazebo and rqt are native OpenGL apps. The container can show them two ways:

- **Native X11** — Linux/amd64 hosts with a working GPU. Needs `xhost` on the host for display forwarding.
- **VNC virtual desktop** — a self-contained desktop inside the container: `Xvfb` rendered by
Mesa `llvmpipe` (software OpenGL), a small window manager, and VNC + noVNC servers (see
[`docker/gui_desktop.sh`](docker/gui_desktop.sh)). It is the default on Apple Silicon (arm64),
where the container gets no native GL context, and can be enabled on any host on demand.
- **VNC virtual desktop** *(default)* — a self-contained desktop inside the container: `Xvfb`
rendered by Mesa `llvmpipe` (software OpenGL), a small window manager, and VNC + noVNC servers
(see [`docker/gui_desktop.sh`](docker/gui_desktop.sh)). You view it from a browser or a VNC
client; no host-side setup.
- **Native X11** — host display forwarding (needs `xhost`). Opt in by disabling VNC with
`LUCY_FORCE_VNC=0` (see below).

### Choosing VNC vs native X11 (`LUCY_FORCE_VNC`)

By default the mode is picked from your architecture. Set `LUCY_FORCE_VNC` in a root `.env`
(or the environment) to override — e.g. an amd64 Linux box can opt into the VNC desktop:
The VNC desktop is enabled by default. Set `LUCY_FORCE_VNC` in a root `.env` (or the
environment) to change it:

| `LUCY_FORCE_VNC` | Behaviour |
| :-- | :-- |
| unset *(default)* | Auto: VNC on arm64, native X11 on amd64 |
| `1` / `yes` / `true` | Force the VNC desktop on any architecture (e.g. an amd64 host without working GLX) |
| `0` / `no` / `false` | Force VNC off even on arm64 (fall back to native X11 / headless) |
| unset / `1` / `yes` / `true` *(default)* | VNC virtual desktop |
| `0` / `no` / `false` | VNC off — native X11 / headless |

### Connecting to the VNC desktop

Expand All @@ -149,8 +149,8 @@ the address it shows. Defaults:

### macOS notes

- On Apple Silicon, XQuartz can't give the container an OpenGL context, so the VNC desktop is
used by default — no setup required.
- macOS can't give the container a native OpenGL context over XQuartz, so keep the default VNC
desktop (don't set `LUCY_FORCE_VNC=0`).
- **Port 5000** is taken by the macOS AirPlay Receiver, and the control panel defaults to it.
The launcher auto-shifts to the next free port, but for a stable URL you can disable
**System Settings → General → AirDrop & Handoff → AirPlay Receiver**, or set
Expand Down
14 changes: 6 additions & 8 deletions docker/ensure_image.sh
Original file line number Diff line number Diff line change
Expand Up @@ -86,14 +86,12 @@ ensure_lucy_docker_image() {
;;
esac

# VNC virtual-desktop tooling: installed on arm64, or forced on any arch with
# LUCY_FORCE_VNC=1 (lets an amd64 host try the VNC path). Folded into want_id and
# the image label below so toggling it forces a rebuild even though the
# Dockerfile text — the only other rebuild trigger — is unchanged.
install_vnc=0
[ "$target_platform" = "linux/arm64" ] && install_vnc=1
case "$(echo "${LUCY_FORCE_VNC:-}" | tr '[:upper:]' '[:lower:]')" in
1|true|yes) install_vnc=1 ;;
# VNC virtual-desktop tooling: installed by default; disable with LUCY_FORCE_VNC=0.
# Folded into want_id and the image label below so toggling it forces a rebuild even
# though the Dockerfile text — the only other rebuild trigger — is unchanged.
install_vnc=1
case "$(echo "${LUCY_FORCE_VNC:-1}" | tr '[:upper:]' '[:lower:]')" in
0|false|no) install_vnc=0 ;;
esac

hash=$(dockerfile_build_hash "$dockerfile")
Expand Down
16 changes: 6 additions & 10 deletions launch_lucy.sh
Original file line number Diff line number Diff line change
Expand Up @@ -74,15 +74,11 @@ ensure_docker_image() {

X11_ARGS=()
GUI_PORT_ARGS=()
ARCH="$(uname -m)"
# LUCY_FORCE_VNC selects the in-container VNC desktop:
# unset -> auto: VNC on arm64 (no working native GL), native X11 on amd64
# 1/yes -> force VNC on any arch (also set it for ./install.sh so the image
# is built with the VNC tooling)
# 0/no -> force VNC off even on arm64 (falls back to native X11 / headless)
USE_VNC=0
case "$ARCH" in arm64|aarch64) USE_VNC=1 ;; esac
case "$(echo "${LUCY_FORCE_VNC:-}" | tr '[:upper:]' '[:lower:]')" in
# LUCY_FORCE_VNC selects the in-container VNC desktop (on by default):
# unset/1/yes -> VNC desktop (software GL via llvmpipe)
# 0/no -> VNC off (native X11 / headless)
USE_VNC=1
case "$(echo "${LUCY_FORCE_VNC:-1}" | tr '[:upper:]' '[:lower:]')" in
1|true|yes) USE_VNC=1 ;;
0|false|no) USE_VNC=0 ;;
esac
Expand Down Expand Up @@ -113,7 +109,7 @@ elif [ "$USE_VNC" = 1 ]; then
echo " Browser (noVNC): http://localhost:${GUI_NOVNC_PORT}/vnc.html (no password)"
echo " VNC Viewer: localhost:${GUI_VNC_PORT} (password: ${GUI_VNC_PASSWORD})"
else
# AMD64: native X11 forwarding, no VNC.
# Native X11 forwarding (VNC disabled via LUCY_FORCE_VNC=0).
GUI_DISPLAY="${DOCKER_GUI_DISPLAY:-$DISPLAY}"
if [ -n "$GUI_DISPLAY" ]; then
if command -v xhost &>/dev/null; then
Expand Down
Loading