Configuration storage, Redis and runtime settings

Three distinct kinds of state

The platform has source configuration files, live shared/config-node values in Redis, and saved per-node overrides. A setting displayed in a browser can have changed live without being written to its saved YAML file. Docker volumes and host bind mounts determine whether those files survive replacement of a container.

hrsdk_configs/ros2 is the primary configuration source. Its main.yaml is the deployment Compose entry point. It selects the ROS image, speech services, data stores, optional CPU perception and optional Spark integration. head-ros-nodes/docker-compose.ros2.yml is a separate development/test topology; do not copy its network or storage assumptions into a deployed robot without checking the selected launch file.

Configuration tree and identity

Area	Role
configs/common/all	Shared platform configuration
configs/common/<character>	Character-wide configuration
configs/bodies/<body>	Body assembly/calibration
configs/heads/<robot>	Head assembly/calibration and node overrides
characters/<character>/worlds/<world>	Agent/world selection
characters/<character>/scenes and data	Scene/prompt/interaction content
performances	Robot and common timed content
blend_files, virtual	Animation assets and virtual runtime resources
models, voices, sounds	Inference/speech/media assets
env	Shell environment loaded by the CLI

Identity is a combination of ROBOT_NAME, ROBOT_BODY, HR_CHARACTER and ROBOT_WORLD. These select different files and resources; changing only the visible character name does not select an appropriate physical calibration.

Bootstrap and configuration manager

The main ROS launch starts a bootstrap executable, then a configuration manager and dependent services. Bootstrap prepares /hr/profile, motor configuration and shared parameters. The manager owns saved-node commands. Inspect the active launch's clear_params setting before restarting during diagnostics: startup can intentionally rebuild live state.

The manager loads parameter directories in this order:

1. Common/all defaults.
2. Common/character defaults.
3. Body defaults.
4. Head defaults.
5. Head node parameters.

Later loaded mappings can override prior values; inspect the collection/load logic and effective values rather than inferring precedence from filenames alone. Node save filenames replace namespace slashes with hyphens, remove a matching robot prefix, and append .yaml beneath the selected target directory.

Shared parameter client

The Python hr_msgs.params API wraps RedisParamStore:

from hr_msgs import params
profile = params.get_param('/hr/profile', '{}')
names = params.list_params('/hr')
present = params.has_param('/hr/motors')

This code runs inside an environment with the installed platform packages and authorized Redis connectivity. Values read by many current callers are JSON strings and are decoded by the caller; do not assume all shared values are native dictionaries.

Read/write/delete/list/subscription APIs use exact normalized parameter names. A namespace-like key is not automatically an interchangeable leaf/subtree representation. Use the library rather than hand-editing Redis keys.

Redis connection defaults are localhost:6379, overridden by REDIS_SERVER_HOST, REDIS_SERVER_PORT, and optional REDIS_PASSWORD; APIs accepting an explicit Redis URL can use that instead. Database reachability is distinct from ROS DDS discovery.

Typed configuration client

ConfigClient discovers node schemas, reads values, updates configuration, resets defaults, saves/deletes overrides and subscribes to changes. The schema validates bool/int/double/string/list/dict types, numeric bounds and enumerated choices. In particular, bool is not accepted as int and numbers are not automatically accepted as strings.

from hr_msgs.config import ConfigClient
client = ConfigClient()
for namespace in client.list_nodes():
    print(namespace)
# Select a namespace returned by discovery before reading its description/values.

Updates write accepted differences and publish a config update. Saving enqueues a manager command. The default save_configuration(..., wait=False) result means queued, not persisted; request wait=True and inspect its result when persistence is required. Default wait timeout is five seconds. A missing manager can cause a save timeout even while live value edits work.

Reset returns values to registered defaults. It does not necessarily delete a previously saved file. Saved-file inspection/deletion is separate; the Settings UI offers deletion after reset when an override existed.

WebUI runtime settings

The WebUI exposes a stable runtime key layer over configuration-node fields. Keys include speech provider/language/voice, chatbot behavior, prompts, agents, arm mode/pose and performance options. A runtime.setting.set command updates one supported setting; clients observe runtime.settingResult and runtime.settings rather than assuming optimistic UI values were accepted.

The source mapping is webui/api/webui_api/runtime_settings.json. A setting may affect several nodes or need a specific provider/session restart. Dynamic and template-derived keys must be obtained from the current runtime snapshot/schema. Do not assume arbitrary dotted keys are writable.

Remote access and persistence diagnosis

Use the WebUI settings APIs for remote administration rather than exposing Redis publicly. Redis in the current deployment uses host networking and a persistent volume; confirm actual bind/password policy before network access. Direct parameter writes bypass UI guardrails and can affect robot behavior.

If a value reverts, compare the runtime result, effective config-node values, saved-file state, source defaults and selected identity. If a save fails, inspect manager availability, permissions and mount mode. If containers change but settings disappear, inspect named volumes/bind mounts and ensure shutdown did not remove volumes.

Evidence: hrsdk_configs/main.yaml, head-ros-nodes/ros/hr_msgs/src/hr_msgs/{params.py,config.py,config_backend/redis_config.py}, hr_ros2/launch/interaction_stack.launch.py, and WebUI runtime settings implementation. ROS/config source reference.