Skip to content

Platform architecture

Responsibilities and boundaries

The platform is a collection of repositories rather than a single Git checkout. hrcli resolves configuration and stack manifests and starts Docker Compose workloads. hrsdk_configs supplies robot-specific configuration, characters, performances, models, sounds, voices, and runtime configuration scripts. ROS nodes implement the robot-facing behavior and control functions. The system console manages the host and installation lifecycle; Robot WebUI handles interactive robot operation.

flowchart TD
    Operator[Operator browser] --> Console[System Console: React and FastAPI]
    Operator --> WebUI[Robot WebUI: React and FastAPI]
    Console --> Host[Host services, network, audio and provisioning]
    Console --> CLI[hrcli and stack management]
    CLI --> Runtime[Docker Compose runtime]
    Runtime --> ROS[ROS 2 nodes and Blender]
    WebUI --> ROS
    WebUI --> Unity[Sophia Unity browser assets]
    Config[hrsdk_configs] --> Runtime
    ROS --> Speech[TTS service]
    Jetson[Jetson perception] --> ROS
    ROS --> Hardware[Actuator hardware]

Runtime layers

head-ros-nodes/README.md specifies ROS 2 Jazzy in the unified image, including the Blender source runtime under /opt/hansonrobotics/tools/blender. Its ROS packages include actuator control, performance execution, behavior, chatbot, speech, browser audio bridging, configuration utilities, support/monitoring integration, and the WebUI.

head-perception has a separate Jetson runtime. Its supported-platform document targets JetPack 6.2, L4T R36.4.3, Ubuntu 22.04 arm64, ROS 2 Humble, RealSense, CUDA, and TensorRT. Its CPU image and Jetson image are separate build targets. A successful amd64 build cannot prove GPU, camera, DDS, or TensorRT behavior on the robot.

The current development Compose file sets ROS_DOMAIN_ID with a default of 0. ROS naming, discovery, interfaces and network reachability must be considered together: matching a domain alone does not prove communication. Perception host setup includes Ethernet DDS routing and Fast DDS interface configuration.

Configuration and persistence

The development Compose configuration mounts hrsdk_configs read-only at /workspace/hrsdk_configs, with separate named volumes for /workspace/.hr and Redis data. Robot identity, body, character and world are passed through environment variables. Do not assume edits inside a container persist or that all deployments use the development volume layout.

Speech providers require separately configured credentials. Provider configuration and installed voice/model artifacts determine which speech paths work. The browser API and ROS adapter layer do not replace those dependencies.

Source authority

Start from the branch inventory, then follow the selected branch's Dockerfiles, launch files, Compose files and CI definitions. Working branches recorded in that inventory need verification before being recommended as installation sources.

Evidence: head-ros-nodes/docker-compose.ros2.yml, head-ros-nodes/README.md, head-perception/SUPPORTED_PLATFORMS.md, hr_system_console/README.md.