Source branches, builds and development
Primary source choices
Use the current ROS 2 branches as the platform baseline. In particular, select head-ros-nodes/ros2 and hrsdk_configs/ros2; a repository's default branch pointer does not override that platform choice. Supporting repositories use their active branch conventions below.
| Component | Current source baseline | Build/output and consumer |
|---|---|---|
| ROS runtime | head-ros-nodes/ros2 |
Unified Jazzy image, ROS nodes, WebUI frontend/API, Blender source and audio2lips; selected by stack/config launch |
| Configuration | hrsdk_configs/ros2 |
Compose, startup scripts, robot calibration, behavior/character/world/media configuration; consumed as host storage/mounts |
| Perception | head-perception/main |
arm64 Humble L4T GPU image and amd64 Jazzy CPU image; Jetson or optional control-host perception |
| CLI | hrcli/main is the installation/upstream ref |
Python hr tool; installed console release can bundle a pinned CLI commit |
| Console | hr_system_console/main is the mainline; release workflow can build selected tagged/manual ref |
Debian package with host daemon, frontend and integration tooling |
| TTS | ttsserver/sdk3 |
Python 3 TTS image with provider plugin support |
| Unity | sophia_unity/master |
Sophia WebGL static assets and multi-architecture asset image |
The inspected CLI and console working checkouts are feature branches. Their exact names/commits are in the source inventory; do not present those automatically as released mainline behavior. This handbook's detailed references describe inspected source. Verify an installed release's version/commit before relying on a feature found only in that checkout.
CI trigger and artifact matrix
| Workflow | Trigger | Architecture and artifact policy |
|---|---|---|
| ROS image CI | Pushes to main/dev/ros2, tags, manual | Separate amd64/arm64 builds; source tags build-<sha>-<arch>; published latest, commit and sanitized ref tags, with manifest publication stages |
| Perception CI | main pushes, tags, manual | arm64 L4T build/smoke plus amd64 CPU build/smoke; GPU release tag humble-l4t-r36.4.3, CPU tag jazzy-cpu |
| TTS CI | sdk3 pushes, tags, manual | amd64/arm64 builds and smoke checks; Python 3 repository, architecture source tags and published ref/commit/latest tags |
| Console package | v* tags or manual version |
amd64 Debian artifact, SHA-256 sidecar and update marker; workflow pins a CLI dependency commit |
| Unity WebGL | master pushes/manual from master | Unity 6000.3.22f1, Sophia scene only; commit/latest WebGL asset image for amd64/arm64 and separate protected character-site deployment |
An image tag is a pointer. Use commit/digest records for reproducible deployment. A tag being declared in YAML is not proof a particular CI run succeeded or that the artifact is present in a registry.
Build the ROS image locally
From the platform workspace:
docker build -t hansonrobotics/head-ros-nodes:ros2 head-ros-nodes
The Dockerfile builds ten selected ROS packages, compiles WebUI assets separately, installs audio2lips and copies Blender runtime source. The image's entrypoint sources ROS, the built workspace and configuration environment before executing commands. Use a unique local tag while developing if the existing tag is used by an operating robot.
The root dev.sh supplies development orchestration; inspect its help and selected configuration before invoking startup. Development Compose profiles are test/development topology, not a substitute for the deployment configuration in hrsdk_configs/main.yaml.
Build perception
GPU target uses scripts/build_image.sh and the L4T Dockerfile. CPU target uses:
cd head-perception
./scripts/build_cpu_image.sh --load
CPU defaults are linux/amd64 and head-perception:jazzy-cpu. Buildx output options matter: a build not loaded or pushed may not be available to docker run. GPU base/release tags deliberately differ where the available NVIDIA base uses a nearby L4T version; follow the supported-platform policy and validate on the actual Jetson.
Build console and WebUI
From hr_system_console, the package builder is ./packaging/build_deb.sh. It assembles frontend/backend plus packaged host integrations. Review required dependency paths/pins before running it; the release workflow additionally checks out a pinned CLI dependency.
For Robot WebUI frontend use npm ci and npm run build in its frontend directory. Production-style API startup uses scripts/run_webui.sh; development uses scripts/dev_webui.sh. The current factory always constructs ROS2, so an old fake-adapter environment example does not create a simulated robot in this checkout.
Build Unity
Use the pinned editor and invoke SophiaUnity.Editor.SophiaWebGLBuild.Build with WebGL target in batch mode. UNITY_BUILD_PATH overrides the output directory. Git LFS assets and a valid Unity installation/license are prerequisites. Keep editor/build caches outside documentation artifacts.
The WebGL asset image is a distribution artifact consumed by CLI asset activation. Its multi-architecture manifest does not mean the browser runs native robot control code; the same browser assets are packaged for those deployment architectures.
Development verification
Use existing component tests/gates that exercise the changed behavior. Source builds and unit tests cannot certify physical motion, GPU inference, camera USB, provider credentials or browser audio permissions. Separate those acceptance checks and record which were executed.
For documentation changes run the source generators, strict MkDocs build, coverage checker and built-link/credential checks. Follow the documentation deployment runbook for publishing.
Evidence: each component's inspected Dockerfiles/setup/package metadata, .github/workflows files, root dev.sh, and current configuration launch scripts. Source commit inventory records the inspected baseline.