Gateway API (WebSocket)¶
The uMe Gateway is the primary programming interface to the robot. It runs on the robot's Perception Board and exposes the uMe on-board SDK as a JSON message stream over WebSocket. Any client — the Robotics Group App, a Python script, or your own software — controls the robot by exchanging JSON messages with the Gateway.
For IT, technicians and integration partners
Technical reference for IT departments, URG technicians and trained partners. It is not written as operating instructions for end users.
API 1.1 — discovery and pairing (in development, 31.10.2026)
From API 1.1 on, the Gateway announces itself in the Wi-Fi with the mDNS service
_ume-gw._tcp; the robot keeps its previous host name, and ume-<kennung>.local is published
additionally only where the robot can do so. By default the Gateway accepts commands only from
paired clients (HMAC-SHA256 challenge-response; before pairing only ping and pair, so
no software stop either). This page still describes API 1.0. Details:
uMe Gateway — discovery and pairing (API 1.1).
Endpoint¶
ws://<robot-ip>:8765/ws
| Transport | WebSocket (ws://, plain, LAN only) |
| Host | The robot's Perception Board IP (recorded at commissioning) |
| Port | 8765 |
| Encoding | UTF-8 JSON, one JSON object per message |
LAN only
The Gateway listens on the local network only and is not intended to be exposed to the internet. Keep the robot and the controlling device on the same router/switch. There is no authentication layer yet — network isolation is the security boundary.
Message model¶
Communication is fully asynchronous and message-based:
- Commands (client → Gateway) are fire-and-forget. Each message has a
typefield. - Status (Gateway → client) is broadcast to every connected client once per second.
A message that is not valid JSON, or whose type is unknown, is silently ignored — send a
well-formed object for every command.
Commands (client → Gateway)¶
move — omnidirectional locomotion¶
{ "type": "move", "vx": 0.5, "vy": 0.0, "wz": -0.2 }
| Field | Range | Meaning |
|---|---|---|
vx |
-1.0 … 1.0 |
Forward (+) / backward (−) |
vy |
-1.0 … 1.0 |
Sideways: left (+) / right (−) |
wz |
-1.0 … 1.0 |
Rotation (turn) |
Only effective in WALK mode. Values are normalized; the Gateway maps them to the robot's
configured maximum speeds. Send move repeatedly (e.g. on every joystick change); send zeros to
stop moving.
head — head orientation¶
{ "type": "head", "yaw": 0.3, "pitch": -0.1 }
yaw and pitch are normalized to -1.0 … 1.0.
mode — state switching¶
{ "type": "mode", "mode": "prep" }
Accepted values: damp, prep, walk. See Modes & State Machine for the
allowed transitions and their meaning.
action — predefined action¶
{ "type": "action", "id": "get_up" }
Runs a predefined motion by id, e.g. get_up, wave, shake_hand. Available actions depend on
the robot's firmware and active agent — see Motion & Commands.
estop — STOP (software stop)¶
{ "type": "estop" }
Damps all motors and forces the robot into DAMP mode.
Known limitation (Gateway 2.6 and later, not yet checked on a device): while an action is
running (gesture, dance, get up, also as a step in a skill), STOP takes effect only after that
action has ended. If the robot does not go to DAMP, press the emergency stop on the robot at once.
See Safety.
The app's red STOP button sends it. estop is not a safety function: always keep the emergency stop on the robot within reach; see Safety.
persona — context & welcome¶
{ "type": "persona", "context": "Kern conference in Billerbeck, greeting visitors", "welcome": "Hello and welcome!" }
The Gateway writes the robot's custom_settings.toml and restarts the voice service so the
conversational agent knows where it is and how to greet people. See
Daily Operation.
Status (Gateway → client)¶
Every connected client receives a status object once per second:
{ "type": "status", "battery": 95, "mode": "walk", "warning": null }
| Field | Type | Meaning |
|---|---|---|
battery |
integer 0–100 |
Battery level in percent |
mode |
string | Current mode: damp, prep, walk, custom, protect |
warning |
string | null |
Human-readable warning, or null when healthy |
Minimal client (Python)¶
import asyncio, json, websockets
async def main():
async with websockets.connect("ws://<ROBOT-IP>:8765/ws") as ws:
await ws.send(json.dumps({"type": "mode", "mode": "prep"}))
await ws.send(json.dumps({"type": "move", "vx": 0.2, "vy": 0, "wz": 0}))
for _ in range(3):
print(json.loads(await ws.recv())) # status frames
asyncio.run(main())
See Python Client for the ready-made test_client.py and
Motion & Commands for the full command catalogue.