Skip to main content

Overview

This page describes the Bluetooth Low Energy (BLE) protocol used to communicate between the Omi app and device. Use this reference when building custom apps or SDKs.

Firmware update discovery

GET /v2/firmware/latest accepts device_model, firmware_revision, hardware_revision, and manufacturer_name, plus an optional device_id for stable device rollout cohorts: the lowercase hex SHA-256 of the normalized DIS serial (UTF-8), never the raw serial. Omit it when no serial is available. Without a device identifier, partial rollouts are excluded; existing releases without a rollout limit keep their behavior. A blocked release is excluded from every firmware endpoint. No eligible newer release returns 404. Explicit GET /v2/firmware/version requests ignore rollout_percent for support and reverts, but return 404 for a blocked release. See the CV1 release contract for packaging, promotion and rollout details.

BLE discovery

The official app discovers the device by scanning for BLE devices with the name Omi.

BLE services

The Omi wearable implements three BLE services:

Battery service

Standard BLE battery level monitoring

Device info service

Device metadata and firmware version

Audio service

Audio streaming and codec configuration

Battery service

Battery notifications require firmware v1.5 or later. Earlier versions (1.0.x) do not support notifications.
This is the standard BLE Battery Service.

Device information service

Available since firmware version 1.0.3
This is the standard BLE Device Information Service.

Characteristics

Audio streaming service

This is the main service for streaming audio from the device to the app.

Characteristics

Codec types

The codec type characteristic determines how to decode the audio data:
Starting with firmware v1.0.3, the default codec is Opus. Earlier versions used PCM 16-bit at 8 kHz.

Audio data format

Audio data is sent as BLE notifications on the Audio Data characteristic.

Packet structure

Each value update includes a 3-byte header:
Each audio packet contains 160 samples. If the packet exceeds (negotiated BLE MTU - 3 bytes), it will be split across multiple value notifications.Example: PCM 16-bit at 16 kHz
  • 160 samples × 2 bytes = 320 bytes per packet
  • On iOS devices, this typically results in:
    • Notification 1: packet n, index 0, 251 bytes
    • Notification 2: packet n+1, index 1, 75 bytes
All audio data is sent in little-endian format.

Implementation example

Python SDK

Python SDK with Opus decoding

Swift SDK

Native iOS SDK

React Native SDK

Cross-platform mobile SDK

Firmware

Compile custom firmware