# OpenZilo

> 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.2. 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](https://openzilo.com) 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](docs/sdk-install.en.md): Python, BLE, uv and audio dependencies.
- [Quick start](docs/sdk-quickstart.en.md): a complete connect/read/disconnect example.
- [Saved recordings](docs/sdk-downloads.en.md): download files and receive post-save transfers.
- [Live audio](docs/sdk-live-audio.en.md): PCM and Opus streaming.
- [IMU](docs/sdk-imu.en.md): start reports, receive batches, software calibration and explicit physical-unit streams.
- [Events](docs/sdk-events.en.md): button and tap events.
- [Firmware updates](docs/sdk-ota.en.md): Python OTA usage and version verification.
- [Data types](docs/sdk-data-types.en.md) and [troubleshooting](docs/sdk-errors.en.md): result fields and failures.

- [Documentation home (简体中文)](docs/index.md): SDK installation, quick start and feature navigation.
- [Feature requirements](docs/features.en.md): feature requirements and version notes.

- [README (English)](https://raw.githubusercontent.com/ziloai/openzilo/main/README.md): install, first commands, requirements, and project status.
- [README (简体中文)](https://raw.githubusercontent.com/ziloai/openzilo/main/README.zh-CN.md): Chinese quick start and navigation.
- [Python SDK guide (English)](https://raw.githubusercontent.com/ziloai/openzilo/main/docs/python-sdk.en.md): API index linking to feature guides and returned data types.
- [Protocol reference (English)](https://raw.githubusercontent.com/ziloai/openzilo/main/docs/protocol.en.md): v4 packet format and command bodies used by the SDK.
- [Architecture and data flow (English)](https://raw.githubusercontent.com/ziloai/openzilo/main/docs/architecture.en.md): BLE framing, recording transfer, audio decoding, and IMU events.
- [Coding agent setup](https://raw.githubusercontent.com/ziloai/openzilo/main/docs/ai-tools.md): how to use this SDK with Codex, Claude Code, and other coding tools.
- [Ring user guide](https://github.com/ziloai/OpenZilo/wiki): first use, buttons, LED indicators, and firmware updates.

## Website and research

- [OpenZilo website](https://openzilo.com): product and platform overview.
- [Development kits](https://openzilo.com/buy): ordering and reservation information.
- [ComBodied Agents paper](https://arxiv.org/abs/2608.10915): research featured on the OpenZilo website; [PDF](https://arxiv.org/pdf/2608.10915).

## Source and examples

- [CLI guide (简体中文)](docs/cli.zh-CN.md): default device selection, interactive shell, remote recording, and timed IMU JSONL capture.

- [Public SDK API](https://raw.githubusercontent.com/ziloai/openzilo/main/src/openzilo/__init__.py): authoritative `__all__`; implementation lives in the package's private submodules.
- [Examples](https://github.com/ziloai/openzilo/tree/main/examples): scan, system information, audio download, and IMU streaming.
- [Live PCM example](examples/live_pcm.py): `open_live_audio_stream()` with async context/iteration, bounded queues, stereo PCM frames, and verified END; optional `pcm` extra uses PyAV.
- [Security policy](https://raw.githubusercontent.com/ziloai/openzilo/main/SECURITY.md): private vulnerability reporting.
- [MPL-2.0 software license](https://raw.githubusercontent.com/ziloai/openzilo/main/LICENSE): current software and documentation license.
- [CERN-OHL-W-2.0 hardware license](https://raw.githubusercontent.com/ziloai/openzilo/main/LICENSES/CERN-OHL-W-2.0.txt): 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](docs/compatibility.zh-CN.md): capability discovery, legacy fallback, SDK version information and feature interface versions.