Robot WebUI
Robot WebUI handles robot interaction rather than host provisioning. REST manages reads and stored resources; WebSockets carry runtime commands/events and duplex audio. The frontend is served by the same application origin in a production-style deployment.
Useful surfaces
| Surface | Purpose | Interfaces to understand |
|---|---|---|
| TeleOps | Interactive speech, gesture/expression, scene and behavior controls | /api/teleops/state, /api/teleops/catalog, /api/teleops/settings, /ws |
| Motors | Definitions, live state, control enable and individual commands | /api/motors, /api/motors/states, /api/motors/control, /api/motors/command |
| Performances | Browse, create, edit, preview and execute timed content | /api/performances, /api/performance-*, runtime command channel |
| Faces | Face-related operator surface | /api/faces/*; see the enrollment/recognition guide |
| Visualization | Inspect the virtual character and runtime visualization | /api/virtual-project, mounted Unity assets and runtime connections |
| Settings | Inspect and edit node configuration and behavior trees | /api/settings/nodes/*, /api/settings/trees/* |
| TTS Files | Browse and play generated speech audio | TTS listing endpoints and /external/tts/* |
| ASR Files | Browse recordings and dated archives | /api/asr/files and /asr/* |
Runtime versus stored changes
Saving configuration or a performance and issuing a live runtime command are different operations. Settings exposes separate configuration update, save, reset, saved-file inspection and saved-file deletion endpoints. Check which action persists to storage before restarting the stack.
Performance APIs support robot/common source selection, folder creation, move/rename, properties, duration estimation, speech preview and individual-node preview. GET /api/performances/current includes state, runtime/content revisions and the current performance, including unsaved preview content. Use revisions and current runtime state when diagnosing differences between the editor and execution.
Speech and media
Speech commands depend on provider configuration and the selected voice. Browser audio and robot audio may use different routes. The dedicated /ws/audio protocol must be followed for PCM; it is separate from the JSON command WebSocket. Unity compressed assets require correct content type and content encoding, which the backend's UnityStaticFiles implementation supplies.
Connectivity checks
Read /api/health, then inspect teleoperation state/catalog. Connect the command socket and observe events before changing robot state. A frontend that loads successfully can still have an unavailable ROS adapter or disconnected audio socket.
Sources: head-ros-nodes/ros/webui/README.md, COMMUNICATION_PROTOCOL.MD, frontend/src/pages, and api/webui_api. See HTTP declarations and the UI source inventory. Detailed walkthroughs: TeleOps, performance editor, motors/settings/media/Unity, and Faces.