Documentation version: dev

API index¶

Device applicability

This document applies to OpenZilo Q.

The public API is defined by openzilo.__all__. Import it with import openzilo as sdk; underscore-prefixed modules are private. Start with the quick start; returned fields are listed in data types.

Find APIs by task¶

Task	Common APIs	Purpose
Connection	`scan_rings()`, `connect_ring()`, `OpenZiloClient`	Scan, connect, send requests, and await events.
Device information	`get_system_info()`, `parse_system_info()`	Firmware, time, storage, battery, serial number, CPUID and model.
Feature discovery	`get_device_capabilities()`, `DeviceCapabilities.supports()`	Check supported features, interface versions and parameter limits.
Remote recording	`start_audio_recording()`, `stop_audio_recording()`, `set_audio_recording_config()`	Start, stop and configure recordings.
Time synchronization	`enable_time_sync()`, `send_time_response()`	Reply automatically or manually to device `0x0401` with `0x0402`.
IMU and events	`start_sensor_report()`, `wait_sensor_data()`, `wait_sensor_double_tap_event()`	Receive IMU batches, taps and button events.
Logs	`get_log_storage()`, `read_log_chunk()`	Inspect log storage and read chunks by offset.
Recording transfers	`receive_auto_audio_file()`, `receive_live_audio_file()`, `download_audio_file()`	Receive completed or live recordings, or download a stored file.
Decode and save	`save_audio_bundle()`, `decode_audio_to_wav()`	Preserve raw audio and create WAV.
Protocol utilities	`encode_packet()`, `decode_packet()`, `PacketStream`	Inspect packets, CRC and binary fields.

Connection and system¶

Function	Signature	Returns	Usage
`scan_rings()`	`await scan_rings(address=None, timeout_s=25.0)`	`list[BleDeviceInfo]`	Scan BLE devices, optionally filtering by address.
`connect_ring()`	`await connect_ring(address=..., command_timeout_s=10.0, auto_time_sync=False)`	`OpenZiloClient`	Create and connect a client; the caller must disconnect it.
`get_system_info()`	`await get_system_info(client, timeout_s=None)`	`SystemInfo`	Read device information.
`parse_system_info()`	`parse_system_info(body)`	`SystemInfo`	Parse a `0x0102` body, normally for tests or protocol debugging.
`enable_time_sync()`	`enable_time_sync(client)`	`None`	Register an automatic responder for `0x0401`.
`send_time_response()`	`await send_time_response(client, request_time, response_time=None, send_time=None)`	`None`	Send a manual `0x0402` time response.
`get_log_storage()`	`await get_log_storage(client, timeout_s=None)`	`LogStorageInfo`	Read log storage information.
`read_log_chunk()`	`await read_log_chunk(client, index, offset, size, timeout_s=None)`	`bytes`	Read log bytes by index, offset and length.

Feature discovery¶

API	Returns	Description
`await get_device_capabilities(client, timeout_s=None, refresh=False)`	`DeviceCapabilities`	Query supported features and recording parameter ranges.
`capabilities.supports(name, major=None, min_minor=0)`	`bool`	Check a feature and its interface version.
`get_sdk_identity()`	`SdkIdentity`	Return the SDK version and source checksum for environment records.

Feature discovery results are cleared on disconnect. See compatibility for fields.

Remote recording¶

API	Purpose
`get_audio_recording_config()` / `set_audio_recording_config()`	Requires firmware `V2.001.0002.0001` or later. Read or change recording configuration.
`start_audio_recording()`	Requires firmware `V2.001.0002.0001` or later. Start recording and return its session ID.
`stop_audio_recording()`	Requires firmware `V2.001.0002.0001` or later. Stop early or cancel the specified recording.
`get_audio_recording_status()`	Requires firmware `V2.001.0002.0001` or later. Query recording state and the saved file.
`wait_audio_recording_finished()`	Requires firmware `V2.001.0002.0001` or later. Wait for recording and saving to finish.

These APIs are asynchronous. Arguments, results and complete examples are in recording control.

Firmware updates¶

Function	Call	Returns	Description
`inspect_firmware_bundle()`	`inspect_firmware_bundle(bundle, trusted_public_key=...)`	`FirmwareBundle`	Verify a signed ZIP and inspect metadata offline.
`update_firmware()`	`await update_firmware(client, firmware, trusted_public_key=..., allow_test_firmware=False, progress=..., timeout_s=30, total_timeout_s=600, reboot_timeout_s=90)`	`SystemInfo`	Upload an official application package, wait for reboot, and verify the running version. See firmware updates.

Recording downloads¶

Function	Signature	Returns	Usage
`get_audio_file_count()`	`await get_audio_file_count(client, timeout_s=None)`	`int`	Count recordings stored on the device.
`get_audio_file_info()`	`await get_audio_file_info(client, file_index, timeout_s=None)`	`AudioFileInfo`	Low-level normal transfer: send `0x0503` and await `0x0504`.
`read_audio_frame()`	`await read_audio_frame(client, file_index, frame_offset, timeout_s=None)`	`AudioDataFrame`	Low-level normal transfer: send `0x0506` and await `0x0505`.
`end_audio_extract()`	`await end_audio_extract(client, file_index, timeout_s=None, ignore_timeout=True)`	`None`	Low-level normal transfer: send `0x0507` and await `0x0508`.
`download_audio_file()`	`await download_audio_file(client, file_index, progress=None, timeout_s=None, quick=True)`	`tuple[AudioFileInfo, bytes]`	Download a complete recording, using fast transfer by default.
`receive_auto_audio_file()`	`await receive_auto_audio_file(client, timeout_s=None)`	`tuple[int, bytes]`	Download after `0x050A` on firmware `V2.001.0002.0001`, or receive consecutive legacy `0x0505` packets.
`wait_audio_record_result()`	`await wait_audio_record_result(client, timeout_s=None)`	`AudioRecordResult`	Wait for `0x050A` without downloading.
`set_live_audio_subscription()`	`await set_live_audio_subscription(client, enabled, timeout_s=None)`	`LiveAudioSubscription`	Requires firmware `V2.001.0002.0001` or later. Low-level subscription: send `0x050D` and await `0x050E`.
`receive_live_audio_file()`	`await receive_live_audio_file(client, on_packet=None, on_subscribed=None, timeout_s=60.0, recording_timeout_s=70.0)`	`LiveAudioRecording`	Requires firmware `V2.001.0002.0001` or later. Subscribe, receive one live recording, and unsubscribe.
`open_live_audio_stream()`	`open_live_audio_stream(client, output="pcm", queue_size=64, timeout_s=60.0, recording_timeout_s=70.0)`	`LiveAudioStream`	Requires firmware `V2.001.0002.0001` or later. Manage the subscription with `async with`; read START, audio and END with `async for`.
`clear_audio_files()`	`await clear_audio_files(client, timeout_s=None)`	`None`	Delete every recording on the device; irreversible.
`parse_audio_file_info()`	`parse_audio_file_info(body)`	`AudioFileInfo`	Parse a `0x0504` body.
`parse_audio_data_frame()`	`parse_audio_data_frame(body)`	`AudioDataFrame`	Parse a `0x0505` body.
`parse_audio_record_result()`	`parse_audio_record_result(body)`	`AudioRecordResult`	Parse a `0x050A` body.
`parse_live_audio_start()`	`parse_live_audio_start(body)`	`LiveAudioStart`	Parse a `0x050F` body.
`parse_live_audio_data()`	`parse_live_audio_data(body)`	`LiveAudioData`	Parse a `0x0510` body.
`parse_live_audio_end()`	`parse_live_audio_end(body)`	`LiveAudioEnd`	Parse a `0x0511` body.

Audio decoding and file output¶

Function	Signature	Returns	Usage
`save_audio_bundle()`	`save_audio_bundle(file_index, data, metadata=None, output_path=None, output_dir=None, pcm_config=None, ...)`	`AudioBundle`	Preserve raw audio and generate a playable file.
`decode_audio_to_wav()`	`decode_audio_to_wav(data, pcm_config=None, ...)`	`bytes`	Decode recording bytes to WAV bytes.
`build_playable_audio()`	`build_playable_audio(data, pcm_config=None, ...)`	`PlayableAudio`	Detect WAV, mono/stereo OP2C or Speex and return playable audio.
`build_wav_from_pcm()`	`build_wav_from_pcm(pcm_bytes, pcm_config=None)`	`bytes`	Wrap PCM in a WAV header.
`decode_speex_to_pcm()`	`decode_speex_to_pcm(data, pcm_config=None, ...)`	`SpeexDecodeResult`	Decode Speex to PCM.
`decode_opus_to_pcm()`	`decode_opus_to_pcm(data, ffmpeg_path="ffmpeg")`	`OpusDecodeResult`	Decode OP2C to PCM using its header channel count.
`parse_opus_recording()`	`parse_opus_recording(data)`	`list[bytes]`	Validate OP2C and extract Opus packets.
`build_opus_recording()`	`build_opus_recording(packets)`	`bytes`	Package Opus packets as an OP2C file.
`decode_ogg_speex_with_ffmpeg()`	`decode_ogg_speex_with_ffmpeg(ogg_bytes, pcm_config=None, ffmpeg_path="ffmpeg")`	`bytes`	Decode Ogg Speex to PCM with ffmpeg.
`parse_packetized_speex_stream()`	`parse_packetized_speex_stream(data, allow_framed_blocks=True)`	`list[bytes]`	Parse length-prefixed Speex packets.
`split_raw_speex_packets()`	`split_raw_speex_packets(data, quality=3, bits_size=None)`	`list[bytes]`	Split raw data by Speex frame size.
`build_ogg_speex()`	`build_ogg_speex(packets, pcm_config=None)`	`bytes`	Wrap Speex packets in Ogg Speex.
`normalize_decoded_speex_pcm()`	`normalize_decoded_speex_pcm(pcm, packet_count, pcm_config=None)`	`bytes`	Normalize decoded PCM length.
`normalize_pcm_config()`	`normalize_pcm_config(config=None)`	`PcmConfig`	Normalize a PCM configuration input.
`format_pcm_config()`	`format_pcm_config(config=None)`	`str`	Format PCM parameters as text.
`build_audio_bundle_paths()`	`build_audio_bundle_paths(file_index, metadata=None, output_path=None, output_dir=None)`	`tuple[Path, Path]`	Build paths for raw and playable files.
`build_base_name()`	`build_base_name(file_index, metadata=None)`	`str`	Build a recording base filename.
`is_wav()`	`is_wav(data)`	`bool`	Check for WAV data.
`is_ogg_speex()`	`is_ogg_speex(data)`	`bool`	Check for Ogg Speex data.
`pick_speex_mode()`	`pick_speex_mode(sample_rate)`	`int`	Select the Speex mode for a sample rate.
`pick_frame_size()`	`pick_frame_size(sample_rate)`	`int`	Select PCM samples per frame for a sample rate.
`pick_bits_size()`	`pick_bits_size(quality)`	`int`	Estimate Speex frame bytes from quality.

IMU and events¶

Function	Signature	Returns	Usage
`start_sensor_report()`	`await start_sensor_report(client, timeout_s=None)`	`SensorStartInfo`	`V2.001.0002.0001` starts capture directly; `V2.001.0002.0000` requires gesture mode first.
`wait_sensor_data()`	`await wait_sensor_data(client, timeout_s=None)`	`SensorDataBatch`	After starting reports, wait for a single-sample or batch `0x0605`; does not automatically send `0x0601`.
`stop_sensor_report()`	`await stop_sensor_report(client, timeout_s=None)`	`SensorStopInfo`	`V2.001.0002.0001` stops capture; `V2.001.0002.0000` can retain local capture in gesture mode.
`open_calibrated_imu_stream()`	`async with open_calibrated_imu_stream(client, profile=None, device_id=None)`	`CalibratedImuStream`	Explicit host correction in g / deg/s, with profile binding and report cleanup; no calibration writes.
`apply_imu_calibration()`	`apply_imu_calibration(batch, config, calibration, accel=True, gyro=True)`	`CalibratedImuBatch`	Offline conversion of original integer batches; input remains untouched.
`load_imu_calibration_profile()`	`load_imu_calibration_profile(path)`	`ImuCalibrationProfile`	Validate local schema, units and parameters.
`save_imu_calibration_profile()`	`save_imu_calibration_profile(profile, path)`	`None`	Atomically save locally after independent validation.
`parse_sensor_data_batch()`	`parse_sensor_data_batch(body)`	`SensorDataBatch`	Parse a `0x0605` body.
`wait_sensor_double_tap_event()`	`await wait_sensor_double_tap_event(client, timeout_s=None)`	`SensorDoubleTapEvent`	Wait for a physical double-tap event (`0x0701`).
`wait_sensor_key_double_press_event()`	`await wait_sensor_key_double_press_event(client, timeout_s=None)`	`SensorKeyDoublePressEvent`	Wait for a double button press (`0x0703`).
`wait_sensor_key_single_press_event()`	`await wait_sensor_key_single_press_event(client, timeout_s=None)`	`SensorKeySinglePressEvent`	Wait for a single button press (`0x0704`).
`parse_sensor_double_tap_event()`	`parse_sensor_double_tap_event(body)`	`SensorDoubleTapEvent`	Parse a `0x0701` body.
`parse_sensor_key_double_press_event()`	`parse_sensor_key_double_press_event(body)`	`SensorKeyDoublePressEvent`	Parse a `0x0703` body.
`parse_sensor_key_single_press_event()`	`parse_sensor_key_single_press_event(body)`	`SensorKeySinglePressEvent`	Strictly parse the four-byte `0x0704` timestamp.

Protocol utilities¶

Function	Signature	Returns	Usage
`encode_packet()`	`encode_packet(command, body=b"")`	`bytes`	Build a complete packet including header and CRC.
`decode_packet()`	`decode_packet(data)`	`Packet`	Parse a complete protocol packet.
`crc16_compute()`	`crc16_compute(data, initial=0xFFFF)`	`int`	Calculate the protocol CRC16.