zendo-sdk 0.2.0

Python client for the Zendo motion-tracking WebSocket stream.

zendo-sdk (Python)

Python client for the Zendo motion-tracking WebSocket stream. Connect to a running Zendo instance and get typed quaternion and landmark events — no byte-parsing, no port hunting.

The package is a thin layer over the Rust zendo-sdk crate (via PyO3), so decoding and the connection lifecycle are handled in Rust. It imports as zendo.

Install

pip install zendo-sdk

Wheels are published for Linux (x86_64, aarch64), macOS (Apple Silicon and Intel), and Windows (x86_64), on CPython 3.10 and newer.

Quickstart

The client is synchronous and blocking: iterating it waits for the next frame. This keeps it ergonomic in notebooks and scripts.

import zendo

with zendo.connect() as client:          # auto-discovers the port (5432-5435)
    print(f"connected on port {client.port}")
    for event in client:
        match event:
            case zendo.BodyQuaternions(frame):
                print("hips:", frame.hips.w, frame.hips.x, frame.hips.y, frame.hips.z)
            case zendo.BodyLandmarks(frame):
                print("nose:", frame.nose.x, frame.nose.y, frame.nose.z)
            case zendo.HandQuaternions(side, frame):
                print(side, "wrist:", frame.wrist.w)
            case zendo.HandLandmarks(side, frame):
                print(side, "thumb tip:", frame.thumb_tip.x, frame.thumb_tip.confidence)
            case zendo.BodyIsbAngles(frame):
                print("right elbow flexion:", frame.right_elbow_flexion)

Without structural pattern matching:

import zendo

with zendo.connect() as client:
    for event in client:
        if isinstance(event, zendo.BodyQuaternions):
            print(event.frame.hips)

Connecting

Function	Behaviour
zendo.connect()	Scans ports 5432-5435 on 127.0.0.1, connects to the first Zendo found.
zendo.connect_at(port)	Connects to an explicit port on 127.0.0.1.
zendo.connect_url(url)	Connects to an explicit ws://host:port URL.

To reach a Zendo on another machine, copy the address from Zendo's Settings: zendo.connect_url("ws://192.168.1.42:5432"). The stream is plain ws:// — unencrypted and unauthenticated — so only use it on a trusted network.

All three accept reconnect=True to transparently re-establish a dropped connection with exponential backoff:

client = zendo.connect(reconnect=True, base_delay_ms=250, max_retries=10)

Types

Events are immutable dataclasses. Frames expose one attribute per joint or landmark — frame.hips, frame.left_wrist, frame.thumb_tip — each a Quaternion (w, x, y, z) or Landmark (x, y, z, confidence). Frames are also iterable: for name, value in frame: ....

BodyIsbAnglesFrame instead exposes 21 scalar float attributes (in radians) — frame.neck_flexion, frame.right_elbow_flexion, etc. The shoulder plane_of_elevation fields are float('nan') when the shoulder is near neutral (gimbal singularity).

The package ships type information (py.typed) and is checked with ty and linted with ruff.

Offline decoding

zendo.decode_frame(data: bytes) decodes a single raw protocol frame into a typed event — handy for replaying captures or testing.

License

Licensed under either of Apache-2.0 or MIT at your option.