Open-source wearable hardware for building Combodied AI.
Website · Get the Kit · Development kits · Coding agents · Quick start · 简体中文
OpenZilo is an open development platform for building always-available AI experiences with wearable hardware.
Starting with smart rings, OpenZilo provides developers with hardware, firmware, SDKs, and reference applications for connecting voice, gestures, physiological signals, AI agents, computers, robots, and the physical world.
This repository contains the Python SDK and CLI for scanning and connecting to an OpenZilo ring, reading device information, downloading recordings, converting Speex or mono/stereo Opus to WAV, and receiving IMU and gesture events.
Run openzilo device use to scan and save a default ring, then openzilo shell for an interactive terminal. Device commands also accept OPENZILO_ADDRESS or --address. Use sensor-stream --seconds 10 --output imu.jsonl for timed IMU capture. See the Chinese CLI guide; remote recording requires matching extended firmware.
Run uvx --from git+https://github.com/ziloai/OpenZilo.git openzilo shell to start the interactive terminal directly from GitHub. See the CLI guide.
It documents protocol v4 on firmware V2.001.0002.0000. Check device behavior on your own hardware.
- We released OpenZilo-HMM, an AI framework for training custom gestures with the OpenZilo ring.
- We released an AI-powered ring sizing tool. Try it by searching for the “Zilo” mini program in WeChat.
OpenZilo currently includes two development kits: OpenZilo Q and OpenZilo X.
Choose Q for voice-first development with dual microphones.
Choose X when your prototype also needs physiological sensing.
| Sensor configuration | OpenZilo Q | OpenZilo X |
|---|---|---|
| Microphones | 2 | 1 |
| IMU | Included | Included |
| PPG sensor | — | Included |
Voice + Gesture Development Kit
Built for:
- AI agents
- voice interaction
- gesture control
- robotics
- computers and mobile devices
- experimental human–AI interfaces
Voice + Gesture + Physiological Sensing Development Kit
Adds physiological sensing for building:
- health-aware AI agents
- context-aware applications
- multimodal interaction
- personal sensing experiments
- wearable AI research
OpenZilo is designed as an open interaction layer rather than a closed consumer device.
Use it to build:
- AI Agents — invoke and interact with agents through voice and gestures
- Robotics — connect wearable input to robots and physical systems
- Desktop & Mobile — create new shortcuts, workflows, and AI interfaces
- AR / XR — explore subtle wearable interaction for spatial computing
- Health-aware AI — combine physiological signals with personal context
- Experimental Interfaces — build interactions we have not imagined yet
Open the cloned repository in your tool. The project instructions point to the SDK's public API and the llms.txt documentation index.
| Tool | Start in repository root | Project instructions |
|---|---|---|
 Codex |
codex |
AGENTS.md |
 Claude Code |
claude |
CLAUDE.md |
 Cursor |
Open the repository | AGENTS.md |
 GitHub Copilot |
Open the repository | Copilot instructions |
 Gemini CLI |
gemini |
GEMINI.md |
 OpenCode |
opencode |
AGENTS.md |
Try:
“Read
llms.txtand the Python SDK guide. Write a script using exportedopenziloAPIs that scans for a ring and prints its model, firmware version, and battery level.”
See the setup guide for installation links and using these docs from another repository.
You need uv, Python 3.10+ (uv can install it), and a BLE adapter. On Linux, you also need BlueZ and Bluetooth access.
Install the device CLI from GitHub:
uv tool install git+https://github.com/ziloai/OpenZilo.git
openzilo scan --timeout 10
openzilo info --address AA:BB:CC:DD:EE:FFReplace the example address with one returned by scan. To use the SDK in your uv project, run uv add git+https://github.com/ziloai/OpenZilo.git. Without uv, use python -m pip install git+https://github.com/ziloai/OpenZilo.git.
In Python:
import asyncio
import openzilo as sdk
async def main() -> None:
async with sdk.OpenZiloClient(address="AA:BB:CC:DD:EE:FF") as ring:
info = await sdk.get_system_info(ring)
print(info.model, info.firmware_version, info.battery_percent)
asyncio.run(main())See the examples for audio download and IMU streaming.
For live mono/stereo PCM, install uv add "openzilo[pcm] @ git+https://github.com/ziloai/OpenZilo.git" and consume
sdk.open_live_audio_stream(ring) with async with / async for. It yields
LiveAudioStart, 20 ms LivePcmFrame blocks (16 kHz s16le, with the configured channel count),
then a verified LiveAudioEnd. Slow consumers fail explicitly; leaving the
context stops an unfinished capture and attempts unsubscribe. This path uses
PyAV and does not need an ffmpeg executable. See the live PCM example
and live audio guide.
Use output="opus" to consume original packets with only the base SDK.
Install ffmpeg if you need Speex/Opus-to-WAV conversion. audio-clear deletes recordings from the device and requires --yes.
ComBodied Agents: a New Paradigm of Human-Centric Agentic AI is featured on the OpenZilo website.
If you find OpenZilo or the ComBodied Agents paradigm useful in your research, please consider citing:
@article{ding2026combodied,
title={ComBodied Agents: a New Paradigm of Human-Centric Agentic AI},
author={Ding, Qianggang and Wang, Xingyao and Feng, Rui and Wang, Zhibin and Yao, Feixiang and Mao, Kelong and Sun, Hao and Luo, Zhiyao and Tang, Jiankai and Li, Lei and Guo, Jiadong and Ni, Minheng and Lin, Weicong and Yang, Chenxi and Gao, Hongxiang and Chen, Zhenghua and Bai, Yang and Wu, Min and Cheng, Jun and Fu, Huazhu and Tao, Dacheng and Liu, Bang},
journal={arXiv preprint arXiv:2608.10915},
year={2026}
}Want your project to appear on the OpenZilo homepage GitHub Trend?
Simply mention “ComBodied AI” in your README.md.
OpenZilo automatically discovers and surfaces GitHub projects building around the ComBodied AI ecosystem.
-
Documentation home: user and developer guides
-
Feature requirements: firmware and SDK requirements
-
SDK and firmware compatibility: supported features and interface versions
-
Recording control: experimental session control and audio configuration for matching extended firmware
-
Python SDK documentation: quick start, feature guides and API reference
-
BLE protocol reference: packet format and implemented commands
-
Architecture and data flow: recording transfer, audio decoding, and events
Software and documentation use MPL-2.0. Hardware designs use CERN-OHL-W-2.0. Brand and third-party marks belong to their respective owners.
See CONTRIBUTING.md for contributions and SECURITY.md for private security reports.