Robot API

hulk serves one API on TCP port 7700, on every network interface of the robot. A client (the "brain" on a computer, the simulator app, your own program) connects, says hello, subscribes to what it wants and sends commands. The message types are defined in the nao_rs_api crate; a client in another language needs only TCP and MessagePack.

Framing

Each message is one frame: a big-endian u32 byte count, then one MessagePack value encoded with field names. Frames above 8 MiB are rejected.

Enums are externally tagged, as rmp-serde writes them:

Connection

1. Hello. Within 2 seconds of connecting, send {"Hello": {"version": 1, "client": "<your name>"}}. The robot answers {"Hello": {"version": 1, "robot": {"body_id", "head_id", "simulated"}}} and closes the connection if the versions differ.
2. One controller at a time. A new connection replaces the previous client, and its subscription starts empty.
3. Heartbeat. Send something at least every 100 ms; "Heartbeat" is enough. When the client goes quiet, the watchdog takes over: after 0.5 s the robot stands still, after 3 s it sits down. A Watchdog event reports both changes.

To the robot

Motion

speed is "Slow", "Normal" or "Fast". head is "Center", "LookAround" or {"LookAt": {"x", "y"}} (a point on the ground relative to the robot, in metres).

Leds

All fields are optional; a field set to nil keeps the robot's own status for that group.

From the robot

State

Units are on Body sensors and units.

Joint order: head_yaw, head_pitch, left_shoulder_pitch, left_shoulder_roll, left_elbow_yaw, left_elbow_roll, left_wrist_yaw, left_hand, right_shoulder_pitch, right_shoulder_roll, right_elbow_yaw, right_elbow_roll, right_wrist_yaw, right_hand, left_hip_yaw_pitch, left_hip_roll, left_hip_pitch, left_knee_pitch, left_ankle_pitch, left_ankle_roll, right_hip_yaw_pitch, right_hip_roll, right_hip_pitch, right_knee_pitch, right_ankle_pitch, right_ankle_roll. The NAO's two hip yaw-pitch joints share one motor.

The Rust client

nao_rs_api::client::Client handles framing, the handshake and the heartbeat:

use nao_rs_api::{client::Client, Head, Motion, Power, Speed, Subscription, ToRobot};

let robot = Client::connect("nao.local:7700", "my-brain")?;
robot.send(&ToRobot::Subscribe(Subscription { state: true, ..Default::default() }))?;
robot.send(&ToRobot::Power(Power::Wake))?;
robot.send(&ToRobot::Motion(Motion::WalkTo {
    x: 1.0, y: 0.0, turn_to: None, speed: Speed::Normal, head: Head::Center,
}))?;
println!("{:?}", robot.state().map(|state| state.battery));

Security

Today's API binds all interfaces and has no authentication or encryption. The REST API's security table lists what exists and what is planned for both APIs.