Crate zendo_protocol

Expand description

Wire-protocol definitions for the Zendo motion-tracking WebSocket stream.

This crate is the single source of truth for the binary protocol that the Zendo desktop app emits and that zendo-sdk consumes. It owns the port range, the message-type tags, the joint and landmark vocabularies, and the pure decode/encode routines.

It has no dependencies, performs no I/O, never allocates, and is no_std by default-disabling the std feature.

§Frame layout

Every frame is one binary WebSocket message: byte 0 is the type tag, the rest is the payload. All numeric values are little-endian f64.

Message	Tag	Payload
Hello	`0x01`	protocol version (`u16` LE)
Body quaternions	`0x02`	13 joints x (w, x, y, z)
Body landmarks	`0x03`	19 landmarks x (x, y, z, confidence)
Hand quaternions	`0x04`	1 side byte + 16 joints x (w, x, y, z)
Hand landmarks	`0x05`	1 side byte + 21 landmarks x (x, y, z, confidence)
Body ISB angles	`0x06`	21 scalar angles (radians)

The server sends the hello frame first on every connection so clients can detect a PROTOCOL_VERSION mismatch before decoding data frames.

§Example

use zendo_protocol::{decode, Message};

match decode(frame) {
    Ok(Message::BodyQuaternions(q)) => println!("hips: {:?}", q.hips),
    Ok(other) => println!("other message: {other:?}"),
    Err(e) => eprintln!("bad frame: {e}"),
}

Structs§

BodyIsbAnglesFrame: Body ISB joint angles for one frame (21 scalars, radians).
BodyLandmarkFrame: Body-landmark positions for one frame (19 MAIA landmarks).
BodyQuaternionFrame: Body-joint orientations for one frame (13 joints).
HandLandmarkFrame: Hand-landmark positions for one frame (21 BlazePose hand landmarks).
HandQuaternionFrame: Hand-joint orientations for one frame (16 joints).
Landmark: A 3D landmark position with a detection confidence in [0, 1].
Quaternion: A unit quaternion describing a joint orientation: w + xi + yj + zk.

Enums§

HandJoint: A hand joint in a HandQuaternionFrame.
HandLandmarkName: A hand landmark in a HandLandmarkFrame.
HandSide: Which hand a hand frame describes.
IsbAngleName: A scalar angle in a BodyIsbAnglesFrame.
Joint: A body joint in a BodyQuaternionFrame.
LandmarkName: A body landmark in a BodyLandmarkFrame.
Message: One decoded message from the Zendo stream.
ProtocolError: Why a binary frame could not be decoded.

Constants§

BODY_ISB_ANGLE_COUNT: Number of scalar angles in a body ISB-angles frame.
BODY_JOINT_COUNT: Number of joints in a body-quaternion frame.
BODY_LANDMARK_COUNT: Number of landmarks in a body-landmark frame (MAIA topology).
ENCODED_BODY_ISB_ANGLES_LEN: Encoded size of a body ISB-angles frame, in bytes.
ENCODED_BODY_LANDMARK_LEN: Encoded size of a body-landmark frame, in bytes.
ENCODED_BODY_QUATERNION_LEN: Encoded size of a body-quaternion frame, in bytes.
ENCODED_HAND_LANDMARK_LEN: Encoded size of a hand-landmark frame, in bytes.
ENCODED_HAND_QUATERNION_LEN: Encoded size of a hand-quaternion frame, in bytes.
ENCODED_HELLO_LEN: Encoded size of a hello frame, in bytes (tag + u16 version).
HAND_JOINT_COUNT: Number of joints in a hand-quaternion frame (wrist + 5 digits x MCP/PIP/DIP).
HAND_LANDMARK_COUNT: Number of landmarks in a hand-landmark frame (BlazePose hand topology).
HAND_SIDE_LEFT: Side byte identifying the left hand in hand frames.
HAND_SIDE_RIGHT: Side byte identifying the right hand in hand frames.
MSG_BODY_ISB_ANGLES: Type tag for a body ISB-angles frame.
MSG_BODY_LANDMARK: Type tag for a body-landmark frame.
MSG_BODY_QUATERNION: Type tag for a body-quaternion frame.
MSG_HAND_LANDMARK: Type tag for a hand-landmark frame.
MSG_HAND_QUATERNION: Type tag for a hand-quaternion frame.
MSG_HELLO: Type tag for the hello frame the server sends first on every connection.
PROTOCOL_VERSION: The wire-protocol version this crate implements.
WEBSOCKET_PORT_END: Last TCP port the Zendo WebSocket server tries to bind, inclusive.
WEBSOCKET_PORT_START: First TCP port the Zendo WebSocket server tries to bind.

Functions§

decode: Decodes one binary WebSocket frame.
decode_hello: Decodes a hello frame, returning the server’s protocol version.
encode_body_isb_angles: Encodes a body ISB-angles frame (0x06).
encode_body_landmarks: Encodes a body-landmark frame (0x03).
encode_body_quaternions: Encodes a body-quaternion frame (0x02).
encode_hand_landmarks: Encodes a hand-landmark frame (0x05).
encode_hand_quaternions: Encodes a hand-quaternion frame (0x04).
encode_hello: Encodes a hello frame (0x01) announcing the protocol version.