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.

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 — emergency stop

{ "type": "estop" }

Immediately damps all motors and forces the robot into DAMP mode. Always keep an emergency stop 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://192.168.10.101: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.