Documentation index for agents¶

OpenZilo is a Python 3.10+ SDK and CLI for compatible BLE rings. This index points coding agents to the repository's maintained documentation. The SDK API is the openzilo package and its __all__ list.

Documentation target: SDK v0.6.1. Device instructions cover firmware V2.001.0002.0000; the SDK uses protocol v4. Firmware and SDK versions evolve independently. Hardware dependent behavior must be checked on the target device.

The OpenZilo website describes a broader platform. Do not infer Python PPG APIs or a TypeScript package from its product concepts; use this repository's public API guide and openzilo.__all__ for implemented SDK features.

Start here¶

• Installation: Python, BLE, uv and audio dependencies.
• Quick start: a complete connect/read/disconnect example.
• Saved recordings: download files and receive post-save transfers.
• Live audio: PCM and Opus streaming.
• IMU: start reports, receive batches and stop.
• Events: button and tap events.
• Firmware updates: Python OTA usage and version verification.

• Data types and troubleshooting: result fields and failures.

• Documentation home (简体中文): SDK installation, quick start and feature navigation.

• Feature requirements: feature requirements and version notes.

• README (English): install, first commands, requirements, and project status.

• README (简体中文): Chinese quick start and navigation.
• Python SDK guide (English): API index linking to feature guides and returned data types.
• Protocol reference (English): v4 packet format and command bodies used by the SDK.
• Architecture and data flow (English): BLE framing, recording transfer, audio decoding, and IMU events.
• Coding agent setup: how to use this SDK with Codex, Claude Code, and other coding tools.
• Ring user guide: first use, buttons, LED indicators, and firmware updates.

Website and research¶

• OpenZilo website: product and platform overview.
• Development kits: ordering and reservation information.
• ComBodied Agents paper: research featured on the OpenZilo website; PDF.

Source and examples¶

• CLI guide (简体中文): default device selection, interactive shell, remote recording, and timed IMU JSONL capture.

• Public SDK API: authoritative __all__; implementation lives in the package's private submodules.

• Examples: scan, system information, audio download, and IMU streaming.
• Live PCM example: open_live_audio_stream() with async context/iteration, bounded queues, stereo PCM frames, and verified END; optional pcm extra uses PyAV.
• Security policy: private vulnerability reporting.
• MPL-2.0 software license: current software and documentation license.
• CERN-OHL-W-2.0 hardware license: hardware design license.

Agent integration notes¶

• Install the SDK in your uv project with uv add git+https://github.com/ziloai/OpenZilo.git. Start the device terminal with uvx --from git+https://github.com/ziloai/OpenZilo.git openzilo shell.
• Import with import openzilo as sdk or use uv run openzilo --help.
• sdk.OpenZiloClient is the connected BLE session; pass it to high-level functions such as sdk.get_system_info(client).
• ffmpeg is only required when converting Speex or Opus recordings to WAV.
• For live PCM use uv add "openzilo[pcm] @ git+https://github.com/ziloai/OpenZilo.git" and open_live_audio_stream(client); it needs no ffmpeg executable. output="opus" uses only base dependencies. Frames are provisional until verified END; context exit aborts unfinished capture.
• audio-clear permanently erases device recordings and requires --yes.

• Codex, Cursor, and OpenCode use AGENTS.md. Claude Code uses CLAUDE.md and Gemini CLI uses GEMINI.md, both importing AGENTS.md. GitHub Copilot uses .github/copilot-instructions.md for repository guidance. This llms.txt remains a documentation index and is not automatically consumed as a plugin or MCP server.

• SDK / firmware compatibility: capability discovery, legacy fallback, SDK version information and feature interface versions.