Schemas

REST API: every request and response shape. Generated from the OpenAPI document.

AcquireRequest

Field	Type	Required	Meaning
`client`	string	yes	Who is asking (shown in status and logs), 1 to 64 printable characters. (example `joystick-app`)
`takeover`	boolean	no	Replace another client's lease. Never replaces a connected brain.

ActiveAnimation

Field	Type	Required	Meaning
`animation`	LedAnimation	yes
`group`	Group	yes

AnimationKind

Type: breathe, blink, rainbow, progress

AudioInfo

Field	Type	Required	Meaning
`channels`	integer	yes
`rate`	integer	yes	(example `16000`)
`sample_format`	string	yes	(example `s16le`)
`speaker_accepts`	array of string	yes	Content types `POST /v1/audio/speaker` accepts.

Battery

Field	Type	Required	Meaning
`charge`	number	yes	0..1
`charging`	boolean	yes
`current`	number	yes	Amperes; negative while discharging.
`temperature`	number	yes	Degrees Celsius, whole degrees. (LoLA and HULKs carry a tenth of it: Aldebaran's firmware scales the sensor twice, so 28 °C arrives as 2.8; the API converts it back.)

Board

Field	Type	Required	Meaning
`address`	integer	yes
`name`	string	yes	(example `LeftHipBoard`)
`version`	integer or null	no	Configuration version; `null` if the board did not answer.

CameraInfo

Field	Type	Required	Meaning
`last_image_age_s`	number or null	no	Seconds since the last image arrived; `null` if none yet.
`name`	CameraName	yes

Color

RGB color as "#rrggbb"

Type: string (pattern ^#[0-9a-fA-F]{6}$, example #ff8800)

ControlStatus

Field	Type	Required	Meaning
`client`	string or null	no
`controller`	string	yes	`none`, `brain` (MessagePack client) or `lease` (a REST client). (example `lease`)
`quiet_for_ms`	integer or null	no	Since the controller was last heard.
`watchdog_active`	boolean	yes	The watchdog has taken over because the controller went quiet.
`yours`	boolean	yes	True if the `Nao-Lease` header of this request is the active lease.

DeathSwitch

Field	Type	Required	Meaning
`all_off_confirmed`	boolean or null	no	The driver confirmed all-off frames since the trip.
`available`	boolean	yes	False when the switch page can't be read (e.g. in the simulator).
`driver`	Driver or null	no
`generation`	integer or null	no	Increments on every trip and re-arm.
`reason`	SwitchReason or null	no	What tripped it (`None` while armed).
`tripped`	boolean or null	no	Tripped: all motors are off and stay off until re-armed on the robot.
`tripped_for_ms`	integer or null	no
`unavailable_reason`	string or null	no	Why it is not available.

Driver

Field	Type	Required	Meaning
`beat_age_ms`	integer or null	no	Since the driver's last frame; `null` if no driver ran since the page was cleared.
`cycle`	integer	yes
`pid`	integer	yes

ErrorBody

The JSON body of every error response.

Field	Type	Required	Meaning
`error`	ErrorDetail	yes

ErrorDetail

Field	Type	Required	Meaning
`code`	string	yes	Stable, machine-readable error code (e.g. `invalid_input`, `not_lease_holder`). (example `invalid_input`)
`field`	string or null	no	The input field at fault, when there is one (dotted path).
`message`	string	yes	What went wrong and what to do about it.

Fan

Field	Type	Required	Meaning
`speed_percent`	integer	yes	Fan speed, percent.
`temperature`	integer	yes	The CPU temperature the fan control used, whole °C.

Feet

Field	Type	Required	Meaning
`left`	Foot	yes
`right`	Foot	yes

Foot

Pressure in kg.

Field	Type	Required
`front_left`	number	yes
`front_right`	number	yes
`rear_left`	number	yes
`rear_right`	number	yes

Group

A group in /v1/leds/{group}.

Type: left_eye, right_eye, eyes, left_ear, right_ear, ears, chest, left_foot, right_foot, feet

Hardware

Field	Type	Required	Meaning
`age_ms`	integer	yes	How old these readings are.
`boards`	array of Board	yes	Motor and foot boards with their configuration versions (empty until the board handshake finished, about 2 s after start).
`cpu_temperature`	number or null	no	The hottest CPU core in °C (hwmon coretemp; SoC DTS sensors as the fallback); `null` if the kernel exposes none.
`fan`	Fan or null	no	The head fan's last control round (every 10 s); `null` before the first.
`head`	HeadReadings or null	no	The head's power monitor and face board temperature as the head thread decoded them (zeros in the first ~300 ms after start).

HeadCommand

One of these, told apart by type:

center

look_around

look_at: Look at a point on the ground (|x|, |y| <= 10 m).

Field	Type	Required	Meaning
`x`	number	yes
`y`	number	yes

HeadReadings

Field	Type	Required	Meaning
`current`	number	yes	Ampere.
`power`	number	yes	Watt.
`temperature`	number	yes	°C.
`voltage`	number	yes	Volt.

Health

Field	Type	Required	Meaning
`api`	string	yes	(example `v1`)
`state_age_ms`	integer or null	no	Age of the latest robot state; `null` before the robot reported one.
`status`	string	yes	(example `ok`)
`uptime_s`	number	yes

Imu

Field	Type	Required	Meaning
`angular_velocity`	array of number	yes	rad/s.
`linear_acceleration`	array of number	yes	m/s², x forward, y left, z up.
`roll_pitch`	array of number	yes	Roll and pitch, radians.

Interfaces

Field	Type	Required	Meaning
`msgpack_port`	integer	yes	The MessagePack-over-TCP API of the brain.
`rest_port`	integer	yes	This API.
`udp_stop_port`	integer	yes	The guard's UDP stop (any datagram starting with the stop magic trips the death switch).

Joint

Field	Type	Required	Meaning
`current`	number	yes	Amperes.
`name`	string	yes	(example `head_yaw`)
`position`	number	yes	Radians (hands: 0 closed .. 1 open).
`temperature`	number	yes	Degrees Celsius.

LeaseGrant

Field	Type	Required	Meaning
`client`	string	yes
`heartbeat_interval_ms`	integer	yes	Send a heartbeat or command at least this often.
`lease`	string	yes	Send this in the `Nao-Lease` header.
`lease_timeout_ms`	integer	yes	The lease ends after this long without a heartbeat or command.

LedAnimation

An animation for one group.

Field	Type	Required	Meaning
`brightness`	number or null	no	Ears: peak brightness 0..1 (default 1). Not for the color groups.
`color`	Color or null	no	Eyes, chest and feet (default white). Not for ears, which are blue only.
`kind`	AnimationKind	yes
`period_ms`	integer or null	no	One cycle, 100 to 60000 ms (default: breathe 3000, blink 1000, rainbow 4000). (100 to 60000)
`value`	number or null	no	Progress only (required there): 0..1.

LedOverrides

Every LED group's override. null (or absent) hands the group back to the robot.

Field	Type	Required	Meaning
`chest`	Color or null	no
`left_ear`	array of 10 × number or null	no	10 brightness levels 0..1 (the ears are blue only).
`left_eye`	array of 8 × Color or null	no	8 colors, index 0 at the top, clockwise as seen from the front.
`left_foot`	Color or null	no
`right_ear`	array of 10 × number or null	no
`right_eye`	array of 8 × Color or null	no
`right_foot`	Color or null	no

What to show on a group or a single LED. Exactly one field: eyes take color or colors (8), ears take brightness or levels (10), chest and feet take color; a single LED takes color (eye) or brightness (ear).

Field	Type	Required	Meaning
`brightness`	number or null	no	One brightness 0..1 for every ear segment.
`color`	Color or null	no	One color for every LED of the group.
`colors`	array of 8 × Color or null	no	One color per eye segment (8).
`levels`	array of 10 × number or null	no	One brightness 0..1 per ear segment (10).

LedStatus

Field	Type	Required	Meaning
`overrides`	LedOverrides	yes	The controller's overrides; `null` groups show the robot's own status.
`shown`	boolean	yes	Overrides show only while a controller (lease or brain) is connected.

MotionCommand

One of these, told apart by type:

stand: Stand still.

Field	Type	Required	Meaning
`head`	HeadCommand	no

walk_to: Walk to a point (|x|, |y| <= 5 m), then stop there. turn_to: final heading relative to the current one (-pi..pi); without it the robot faces where it walked.

Field	Type	Required
`head`	HeadCommand	no
`speed`	WalkSpeed	no
`turn_to`	number or null	no
`x`	number	yes
`y`	number	yes

walk_toward: Keep walking toward a point that stays at this offset (|x|, |y| <= 2), like a joystick: (1, 0) straight on, (0.5, 0.5) a circle, (0.02, 0.5) turn on the spot. Send it again to steer, stand to stop.

Field	Type	Required
`head`	HeadCommand	no
`speed`	WalkSpeed	no
`x`	number	yes
`y`	number	yes

sit_down

arms_up

squat

MotionStatus

Field	Type	Required	Meaning
`commanded`	MotionCommand or null	no	What the controller commanded last (`null`: nothing yet).
`executing`	string or null	no	What the robot executes now (`Stand`, `Walk`, `SitDown`, `StandUpFront`, ...).

PowerRequest

Field	Type	Required	Meaning
`state`	PowerState	yes

PowerState

Type: wake, rest

PowerStatus

Field	Type	Required	Meaning
`primary_state`	string or null	no	The robot's primary state from the latest state (`Unstiff`, `Animation`, `Initial`, `Playing`, `Finished`); `null` before the first state.

Preset

Field	Type	Required	Meaning
`description`	string	yes
`name`	string	yes	(example `blue`)

Queued

Field	Type	Required	Meaning
`duration_ms`	integer	yes
`samples`	integer	yes

Robot

Field	Type	Required	Meaning
`body_id`	string	yes	Body serial number (empty until the robot runtime reported it).
`body_version`	string or null	no	Body hardware version (e.g. `6.0.0`); `null` outside the real robot.
`echo_cancellation`	boolean	yes	The robot removes its own voice from the microphones (echo cancellation), so clients can keep listening while it speaks. False: the robot mutes its microphones while speaking.
`head_id`	string	yes	Head serial number (empty until the robot runtime reported it).
`head_version`	string or null	no	Head hardware version; `null` outside the real robot.
`interfaces`	Interfaces	yes
`simulated`	boolean	yes	True in the simulator (no microphones, speakers or death switch page there).
`software`	Software	yes

RobotState

Field	Type	Required	Meaning
`age_ms`	integer	yes	How old this state is.
`battery`	Battery	yes
`fall_state`	string	yes	`Upright`, `Falling`, `Fallen`, `StandingUp` or `Sitting`.
`feet`	Feet	yes
`imu`	Imu	yes
`joints`	array of Joint	yes	Every joint, head to feet.
`motion`	string	yes	The motion being executed (`Stand`, `Walk`, `SitDown`, ...).
`primary_state`	string	yes	`Unstiff`, `Animation`, `Initial`, `Playing` or `Finished`.
`sonar`	Sonar	yes
`time`	number	yes	Robot clock when the state was taken, seconds since the Unix epoch.
`touch`	Touch	yes

Safety

Field	Type	Required	Meaning
`death_switch`	DeathSwitch	yes
`rearm`	string	yes	How to re-arm (never possible over the API).

Software

Field	Type	Required	Meaning
`msgpack_protocol`	integer	yes	Version of the MessagePack protocol on `msgpack_port`.
`name`	string	yes	(example `nao-rs`)
`rest_api`	string	yes	(example `v1`)
`version`	string	yes	Version of the robot program.

Sonar

Field	Type	Required	Meaning
`left`	number	yes	Meters to the nearest obstacle.
`right`	number	yes

StopResult

Field	Type	Required	Meaning
`death_switch`	DeathSwitch	yes
`page_tripped`	boolean	yes	The switch page was tripped directly (reason `Api`).
`udp_sent`	boolean	yes	The guard's UDP stop was sent too (works even if this program hangs).

StreamEvent

One event on GET /v1/events/stream. The SSE event name is type.

One of these, told apart by type:

touch: A touch sensor was pressed or released.

Field	Type	Required	Meaning
`pressed`	boolean	yes
`sensor`	string	yes

fall: The fall state changed (Upright, Falling, Fallen, StandingUp, Sitting).

Field	Type	Required	Meaning
`state`	string	yes

watchdog: The watchdog took over because the controller went quiet, or handed control back.

Field	Type	Required	Meaning
`active`	boolean	yes

safety: The death switch changed (tripped or re-armed on the robot).

Field	Type	Required
`generation`	integer	yes
`reason`	SwitchReason	yes
`tripped`	boolean	yes

control: The controller changed.

Field	Type	Required	Meaning
`client`	string or null	no
`controller`	string	yes	`none`, `brain` or `lease`.

StreamFormat

Type: wav, raw

SwitchReason

Why the death switch was tripped (the drivers' deathswitch::Reason; the first reason wins until re-armed).

Value	Meaning
`None`	Armed: not tripped.
`ChestButton`	The chest button was pressed.
`HeadTouch`	All three head touch pads at once.
`Api`	POST /v1/safety/stop, the WebSocket stop or the MessagePack Stop (each trips the page directly and also sends the UDP stop).
`Udp`	The guard's UDP stop alone, e.g. `nao-rs stop <address>` from the Mac.
`Cli`	naoctl on the robot, or a fresh page (it starts tripped).
`DriverFault`	The driver failed (cycle overrun, chest board error) or the runtime stopped.
`Overtemperature`	Too hot: a joint at 75 °C, or the CPU above 95 °C (the head's fan control).
`GuardHeartbeatLost`	The guard saw no driver heartbeat and took the chest board over.
`GuardNoConfirmation`	The driver did not confirm all-off frames after a trip; the guard took over.
`Test`	Tests.
`PageLost`	The page file was truncated, deleted or replaced on disk; it was restored tripped.

Touch

Field	Type	Required
`chest_button`	boolean	yes
`head_front`	boolean	yes
`head_middle`	boolean	yes
`head_rear`	boolean	yes
`left_foot`	boolean	yes
`left_hand`	boolean	yes
`right_foot`	boolean	yes
`right_hand`	boolean	yes

VolumeRequest

A volume change. Give percent, muted or both; a percent above 0 also unmutes unless muted is given too.

Field	Type	Required	Meaning
`muted`	boolean or null	no
`percent`	integer or null	no	0 to 100. (0 to 100)

VolumeStatus

Field	Type	Required	Meaning
`age_ms`	integer	yes	How old this readback is (the robot reads the mixer about once a second).
`muted`	boolean	yes
`percent`	integer	yes	Speaker volume 0..100 as the mixer holds it now. (example `65`)

WalkSpeed

Type: slow, normal, fast

WsClientMessage

A message from the client. Every message may carry an id, which the answer repeats.

Every field of WsCommand, plus:

Field	Type	Required	Meaning
`id`	integer or null	no

WsCommand

One of these, told apart by type:

hello: First message: take the lease for client (1 to 64 printable characters).

Field	Type	Required	Meaning
`client`	string	yes
`takeover`	boolean	no

heartbeat: Keeps control when nothing else is sent (at least every 100 ms).

motion: Like PUT /v1/motion.

Field	Type	Required	Meaning
`motion`	MotionCommand	yes

head: Like PUT /v1/motion/head.

Field	Type	Required	Meaning
`head`	HeadCommand	yes

power: Like PUT /v1/power.

Field	Type	Required	Meaning
`state`	PowerState	yes

leds: Like PUT /v1/leds/{group}.

Field	Type	Required	Meaning
`group`	Group	yes
`setting`	LedSetting	yes

volume: Like PUT /v1/audio/volume.

Field	Type	Required	Meaning
`volume`	VolumeRequest	yes

stop: Like POST /v1/safety/stop: the death switch, needs no lease.

WsServerMessage

A message from the robot.

One of these, told apart by type:

welcome: Answer to hello: you control the robot until the socket closes.

Field	Type	Required
`heartbeat_interval_ms`	integer	yes
`id`	integer or null	no
`lease`	string	yes
`lease_timeout_ms`	integer	yes

ok: The command was accepted. motion is the commanded motion after motion and head.

Field	Type	Required	Meaning
`id`	integer or null	no
`motion`	MotionCommand or null	no

error: The command was refused (same codes as the HTTP API).

Field	Type	Required
`code`	string	yes
`field`	string or null	no
`id`	integer or null	no
`message`	string	yes

stopped: The death switch was tripped.

Field	Type	Required
`id`	integer or null	no
`page_tripped`	boolean	yes
`udp_sent`	boolean	yes

event: A robot event, as on GET /v1/events/stream.

Field	Type	Required	Meaning
`event`	StreamEvent	yes

Schemas

On this page