HRCLI and stack management
Scope and state
hr manages SDK configuration, stack manifests, image acquisition, Compose startup/shutdown and servo diagnostics. It is a local command-line application, not a network API server. To use it remotely, SSH to the robot host and run the installed CLI as the configured operator. The system console invokes host integrations separately.
The current checkout is a feature branch; the installation constant still identifies the upstream main branch. Record the installed version and source commit before comparing behavior with this handbook. Inspected sources and the full command declarations distinguish implementation from assumptions about released packages.
Default state is rooted in the user's .hrsdk area, with .env, stack manifests and generated DDS profile. HR_CONFIG_STORAGE selects robot configuration storage; default is ~/workspace/hrsdk_configs. Other environment values choose robot/body/character, stack version, project name and image registry. Avoid running the same setup as an unrelated user: user homes, credentials and local state will differ.
Configure and start
hr version
hr --help
hr configure
hr stack list
hr stack show EXACT_STACK_VERSION
hr start --head CONFIGURED_HEAD --body CONFIGURED_BODY
configure prompts for required settings and prepares DDS networking. start validates storage, selects/detects robot hardware, prepares runtime paths, sources sorted configuration env/*.sh scripts, resolves launch files and assets, and starts Compose.
Environment scripts are executable shell configuration, not passive YAML. Review changes before sourcing them. Robot detection can use serial configuration matches and a Feetech ID fallback; ambiguous matches require an explicit head. The cached detection scan prioritizes known IDs in the 200–240 range.
Startup is local-first. It resolves with an empty ECR registry and uses --pull never after checking local images. Missing images trigger a pull through configured STACK_VERSION, local tagging and another check. A complete local set avoids contacting ECR. Starting does not mean every provider credential, microphone, GPU or physical device has passed a functional test.
Useful startup options
| Option | Purpose |
|---|---|
--launch, -f |
Launch file within selected storage; default main.yaml |
--service |
Limit selected services; repeatable |
--env |
Additional environment settings; repeatable |
--head, --body |
Explicit robot assemblies |
--project |
Compose project selection |
--perception/--no-perception |
Enable/disable integrated CPU perception |
--gui |
Enable Blender UI |
--dev |
Development mode |
--stt |
Enable configured speech integration |
Use explicit identity/project selection for remote work to avoid controlling the wrong stack. Some inherited command options remain in the signature; their presence alone does not establish a current ROS networking workflow. Use current DDS configuration rather than old ROS-master assumptions.
Stop and persistent volumes
hr stop resolves the selected configuration and issues Compose shutdown. Specify the matching launch/project when managing nondefault stacks. --volumes/-v removes declared named volumes; this can delete persistent runtime/Redis data and is not part of routine stop/start.
Stopping the stack is service lifecycle management, not a physical emergency-stop protocol. Make hardware safe using the robot's prescribed mechanism before maintenance.
Stack manifests and updates
| Command family | Use |
|---|---|
stack create, copy, edit |
Prepare a named image manifest |
stack list, show |
Inspect available versions and image choices |
stack pull, top-level pull |
Acquire selected or configured images |
stack publish, sync |
Distribute/fetch manifest metadata through registry integration |
stack delete |
Remove selected manifests according to options |
| Registry helper commands | Authenticate and manage manifest repositories where permitted |
Pull is architecture-aware: amd64 hosts skip arm64-only images; arm64 prefers native variants and can pull emulated alternatives when required. A downloaded image is not proof it can access Jetson GPU devices or satisfies the host's L4T requirements.
Record a coherent stack version and immutable artifact identifiers before updating. Per-image latest tags can change independently. Publishing a manifest changes shared release metadata; do not treat it as a prerequisite for installing an existing release.
Unity assets
Launch metadata can declare assets separately from runnable services. The selected stack can activate Sophia Unity assets by digest, then expose their directory through WebUI runtime environment. An asset image need not be started as a long-running service. Inspect manifest/asset activation results when the virtual character is missing even though containers are running.
Servo tools
hr servo ping scans matching serial ports over a selected ID range, optionally producing JSON or stopping at the first match. hr servo detect matches hardware against selected storage and falls back to head-ID detection. hr servo rw reads/writes selected registers or performs neutral/ID actions.
Direct register operations require correct protocol, baud, register width and signed-bit encoding. Never use a write example as a read probe. Stop competing bus ownership and preserve calibration before neutral or EEPROM changes. See command declarations for exact option requirements and ranges.
Diagnostics
If start fails, distinguish invalid storage, ambiguous robot detection, missing images, registry auth, manifest mismatch, launch interpolation, device access and application health. hr upgrade changes the installed tool; record its prior version and use a clean local source install for recovery when the installed package is corrupt. Do not publish credentials in command logs or support bundles.
Evidence: hrcli/hrcli/{cli.py,config.py,constants.py,start_cli.py,stop_cli.py,stack_cli.py,servo_cli.py,dds.py} and README. Commands shown here were inspected rather than run against robot hardware.