Remote client recipes

Establish addresses and schema

Set the actual service addresses from the deployment's network map. All examples use placeholders and require access to the intended robot network/proxy. The documentation domain does not proxy these APIs.

export CONSOLE_URL='http://ROBOT_HOST:CONSOLE_PORT'
export ROBOT_UI_URL='http://ROBOT_HOST:WEBUI_PORT'
curl --fail-with-body "$CONSOLE_URL/api/health"
curl --fail-with-body "$ROBOT_UI_URL/api/health"
curl --fail-with-body "$ROBOT_UI_URL/api/openapi.json" --output robot-openapi.json

Inspect adapter/backend state after liveness. Read /api/teleops/catalog and /api/teleops/state before choosing provider voices, animations, scenes or behavior values.

Speak supplied text

This produces actual speech and associated animation through the configured pipeline:

curl --fail-with-body "$ROBOT_UI_URL/api/teleops/command" \
  -H 'Content-Type: application/json' \
  --data '{"type":"teleops.speech.say","requestId":"speech-example-1","text":"Hello.","language":"en-US","voice":"CONFIGURED_VOICE"}'

Check application ok, then speech/audio events. An accepted command can still fail downstream because a provider, voice, audio device or animation sink is unavailable. A direct TTS synthesis request returns encoded audio/metadata and does not itself mean the robot spoke.

Submit a conversation turn

curl --fail-with-body "$ROBOT_UI_URL/api/teleops/command" \
  -H 'Content-Type: application/json' \
  --data '{"type":"teleops.chat.send","requestId":"chat-example-1","text":"Hello.","language":"en-US","source":"remote-client"}'

Observe suggestion/utterance events according to the selected hybrid/provider mode. Do not submit metadata updates or interim transcripts again as separate turns. Repeating a timed-out request can duplicate input.

Read perception remotely

Use matching ROS interfaces, domain and compatible network/QoS:

ros2 topic info -v /hr/perception/people
ros2 topic echo /hr/perception/people --once --qos-reliability best_effort
ros2 interface show hr_msgs/msg/People2

For browser clients, fetch the current image from /api/video/fov.jpg. The after sequence and timeout support waiting for a newer frame; HTTP 204 means no new frame in that wait. Keep headers/status handling separate from image decoding.

Browser monitor without microphone ownership

Connect the Robot WebUI audio socket, send hello with outputChannel: monitor, then subscribe:

{"type":"audio.hello","version":2,"clientId":"remote-monitor","outputChannel":"monitor"}

{"type":"output.subscribe","enabled":true}

Read output.start format before consuming binary PCM. Monitoring does not require acquiring microphone ownership and does not release robot speech gates. Full audio contract.

Follow a performance without replaying it

Connect /ws, consume performance.runtime, then matching performance.tick messages. Fetch /api/performances/current on content revision changes. Ignore ticks from other runtime revisions. Reconnect by reading snapshots; do not automatically resend Run.

To operate a selected performance, use the performance command protocol and ID/payload from current storage/catalog. Playback can trigger speech and motion, so the client must deliberately select the intended robot/content.

Read host diagnostics

curl --fail-with-body "$CONSOLE_URL/api/system/summary"
curl --fail-with-body "$CONSOLE_URL/api/system/services"
curl --fail-with-body "$CONSOLE_URL/api/network/routes"
curl --fail-with-body "$CONSOLE_URL/api/audio/routing/container-check"

Cached status can include stale/refresh/error metadata. Health polling marks the console active for automatic refresh; individual reads are not necessarily synchronous probes. Use task IDs and task.updated events for long-running operations.

Controlled motor operation

Read motor definitions, current state and control/torque status first. The motor API guide defines named posture and torque semantics. Values in this API are not raw servo register positions. Use the selected calibration/units and an operator-approved narrow target; no universal motor value is safe for every assembly.

After issuing a command, inspect application result and actual feedback. Publication acknowledgement is not physical completion. The generic WebUI command.stop is unsupported; implement recovery around the appropriate subsystem and the robot's prescribed physical procedure.