Skip to content

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 type field.
  • 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.