Skip to content

Install the current platform

Choose a path

Host role Installation path Acceptance focus
amd64 robot/control host System Console package and selected coherent SDK release Configuration, containers, ROS control, speech, Unity and hardware
arm64 Jetson perception host Matching JetPack/L4T, perception host setup and GPU image NVIDIA runtime, RealSense, inference, DDS and fused outputs
Development workstation Sibling source checkouts and development Compose Source builds and local interface validation; hardware configuration is separate

The main ROS image is Jazzy-based. Jetson perception currently targets Humble on JetPack 6.2/L4T R36.4.3; CPU perception uses its own Jazzy target. This handbook describes those source targets, not a hardware-certified compatibility matrix. Verify the actual paired images and ROS interfaces on the intended robot.

Prepare the control host

The current automated console clean-install path requires Ubuntu 24.04 amd64. Do not use its success criteria as a claim that automated installation is supported on another host OS/architecture. Exact setup and credential contract.

Before installation record CPU architecture, OS, available disk, selected operator user, robot head/body, character/world, robot Ethernet interface and domain ID. Keep internet/default routing separate from the dedicated robot LAN where the topology requires it. Confirm Docker support and access to required registries/config repositories.

uname -m
cat /etc/os-release
ip -brief address
ip route
ls -l /dev/serial/by-id

Do not infer the robot calibration from a generic head name. Obtain the correct configuration and credential access before starting physical control.

Install System Console

Use an approved exact package version from the release channel or build one from the selected source. The published artifact naming is hr-system-console_<version>.deb; inspect package metadata and release checksums before installing.

export CONSOLE_VERSION='APPROVED_VERSION'
curl --fail --location \
  "https://hrsdk-static.hr-tools.io/hr-system-console_${CONSOLE_VERSION}.deb" \
  --output /tmp/hr-system-console.deb
curl --fail --location \
  "https://hrsdk-static.hr-tools.io/hr-system-console_${CONSOLE_VERSION}.deb.sha256" \
  --output /tmp/hr-system-console.release.sha256

The release checksum names the versioned artifact. Download using that exact filename or compare its expected digest against the local file explicitly before proceeding. Verify the downloaded artifact against the first digest in the sidecar:

python3 - <<'PYTHON'
import hashlib
from pathlib import Path
expected = Path('/tmp/hr-system-console.release.sha256').read_text().split()[0]
actual = hashlib.sha256(Path('/tmp/hr-system-console.deb').read_bytes()).hexdigest()
if len(expected) != 64 or actual != expected:
    raise SystemExit('Package checksum mismatch')
print('Package checksum verified')
PYTHON

Do not paste an unreviewed checksum into a script as executable text.

dpkg-deb --info /tmp/hr-system-console.deb
sudo apt install /tmp/hr-system-console.deb
systemctl status hr-system-console.service --no-pager

The package installs application files under /opt/hr-system-console, configuration under /etc/hr-system-console, and systemd services for console, remote access and VS Code integration. Its packaged default listens on port 80 on the robot LAN. Use the actual host address. The console intentionally has administrative LAN access without login; place it on the intended network.

Use the setup UI

  1. Open the host console and enter HRSDK setup if no installation exists.
  2. Read preflight/readiness results; fix network/storage/operator prerequisites first.
  3. Validate and save registry/repository credentials through the setup form.
  4. Select the operator, exact compatible SDK release and configuration reference.
  5. Select robot Ethernet/DDS configuration, then configure/test host audio.
  6. Save progress if necessary; start Install and start SDK when ready.
  7. Follow the background task and installation logs through completion. A browser refresh is not cancellation.
  8. Verify the installed release/configuration and container states before any motion test.

A failed or interrupted task must be diagnosed from its last stage/logs. The installer maintains state and supports resumable work; do not delete storage or recreate all credentials as the first recovery step.

CLI path for an existing prepared host

Install the selected CLI through the approved package/source workflow, then run it as the SDK operator:

hr version
hr configure
hr stack show APPROVED_STACK_VERSION
hr stack pull APPROVED_STACK_VERSION
hr start --head CONFIGURED_HEAD --body CONFIGURED_BODY

hr configure selects storage and stack settings; stack pull alone does not select that version as the configured startup release. Verify STACK_VERSION through configuration before starting. Startup sources configuration environment scripts and can detect hardware. CLI details.

Prepare Jetson perception

Use the supported JetPack/L4T combination and a correctly attached RealSense camera. From the selected head-perception/main checkout:

./scripts/install_host_docker.sh
./scripts/install_realsense_host_rules.sh
./scripts/configure_ros_domain.sh

Host setup installs Docker/NVIDIA support, configures Ethernet DDS routing and a Fast DDS interface whitelist. Verify auto-detected Ethernet selection before applying it. Use the same intended ROS domain as the control host; the startup script requires an explicitly configured integer from 0 through 101.

Acquire a matching perception image with the repository image-setup helper or build it using scripts/build_image.sh. Then start:

./scripts/start_perception_container.sh
./scripts/smoke_test.sh --live

The container uses host networking, NVIDIA runtime where selected, device access and model cache. Check script/environment settings for HEAD_PERCEPTION_IMAGE, DDS profile, camera topics and model options. Local smoke mode checks source/import shape; --live also probes the running graph. Do not substitute a CPU smoke result for GPU/camera acceptance.

System Console's Jetson page can provision the remote host using selected SSH/user/interface settings and a one-time password. Follow its task and verify the resulting service/graph independently. Avoid provisioning concurrently through UI and shell.

Acceptance checks

  • Console health and SDK service active, with no failed install task.
  • Expected images/architecture and exact selected release/configuration recorded.
  • Robot WebUI health plus ROS adapter connection, not merely a rendered frontend.
  • Correct head/body/character/world and motor definitions loaded.
  • Required ROS nodes, topic types and QoS visible across control/perception hosts.
  • Perception color/depth, inference, fused people and UI image functional on hardware.
  • Selected speech provider and audio path functional; test at a controlled volume.
  • Unity assets load, stream connects and expected channels animate.
  • Controlled hardware checks completed by a prepared operator with the correct calibration.

These hardware acceptance checks are a deployment checklist; they were not executed while writing the documentation.

Evidence: hr_system_console/README.md, packaging and api/system_console/setup.py; hrcli/README.md and source; head-perception/README.md, supported-platform document and setup/start/smoke scripts; selected ROS/configuration launch files.