Omi Firmware Patterns Skill

This skill provides guidance for working with Omi firmware, including BLE services, audio codecs, and device communication.

When to Use

Use this skill when:

• Working on firmware code in omi/ or omiGlass/

• Implementing BLE services

• Working with audio codecs (Opus, PCM, Mu-law)

• Debugging device communication issues

Key Patterns

BLE Services

Audio Streaming Service

UUID: 19B10000-E8F2-537E-4F6C-D104768A1214

Characteristics:

• Audio Data: 19B10001-E8F2-537E-4F6C-D104768A1214

• Codec Type: 19B10002-E8F2-537E-4F6C-D104768A1214

Standard Services

• Battery Service: 0x180F (standard)

• Device Information Service: 0x180A (standard)

Audio Packet Format

Header (3 bytes):

• Bytes 0-1: Packet number (little-endian, 0-65535)

• Byte 2: Index (position within packet)

Payload:

• 160 audio samples per packet

• Format depends on codec type

Fragmentation: If packet exceeds BLE MTU - 3 bytes, split across multiple notifications

Codec Types

• 0 : PCM 16-bit, 16 kHz, mono

• 1 : PCM 16-bit, 8 kHz, mono

• 10 : Mu-law, 16 kHz, 8-bit mono

• 11 : Mu-law, 8 kHz, 8-bit mono

• 20 : Opus, 16 kHz, 16-bit mono (default since v1.0.3)

Zephyr RTOS (Omi Device)

BLE Service Definition

BT_GATT_SERVICE_DEFINE(audio_svc, BT_GATT_PRIMARY_SERVICE(BT_UUID_AUDIO_SERVICE), BT_GATT_CHARACTERISTIC(BT_UUID_AUDIO_DATA, BT_GATT_CHRC_READ | BT_GATT_CHRC_NOTIFY, BT_GATT_PERM_READ, read_audio_data, NULL, NULL), );

Audio Packet Sending

void send_audio_packet(audio_packet_t *packet) { uint8_t buffer[3 + sizeof(packet->audio_data)];

// Header
buffer[0] = packet->packet_number & 0xFF;
buffer[1] = (packet->packet_number >> 8) & 0xFF;
buffer[2] = packet->index;

// Audio data
memcpy(&buffer[3], packet->audio_data, sizeof(packet->audio_data));

// Send via BLE notification
bt_gatt_notify(conn, &audio_char, buffer, sizeof(buffer));

}

ESP32-S3 (Omi Glass)

Arduino Framework

BLEService *pService = pServer->createService(SERVICE_UUID); BLECharacteristic *pChar = pService->createCharacteristic( AUDIO_DATA_UUID, BLECharacteristic::PROPERTY_READ | BLECharacteristic::PROPERTY_NOTIFY );

Common Tasks

Adding a New BLE Characteristic

• Define UUID

• Add to service definition

• Implement read/write/notify callbacks

• Handle data format correctly

Implementing Audio Codec

• Initialize codec encoder

• Encode audio samples

• Format as packet with header

• Send via BLE notification

Debugging BLE Issues

• Check service/characteristic UUIDs

• Verify packet format (header + payload)

• Check MTU size and fragmentation

• Verify codec type negotiation

Related Documentation

The docs/ folder is the single source of truth for all user-facing documentation, deployed at docs.omi.me.

• BLE Protocol: docs/doc/developer/Protocol.mdx

• View online

• Firmware Compilation: docs/doc/developer/firmware/Compile_firmware.mdx

• View online

• Hardware Docs: docs/doc/hardware/

• View online

• Firmware Architecture: .cursor/rules/firmware-architecture.mdc

Related Cursor Resources

Rules

• .cursor/rules/firmware-architecture.mdc

• Firmware system architecture

• .cursor/rules/firmware-ble-service.mdc

• BLE service implementation

• .cursor/rules/firmware-audio-codecs.mdc

• Audio codec implementation

• .cursor/rules/flutter-ble-protocol.mdc

• Flutter BLE integration

Subagents

• .cursor/agents/firmware-engineer/

• Uses this skill for firmware development

• .cursor/agents/flutter-developer/

• Uses this skill for BLE integration

Commands

• /flutter-setup
• Uses this skill for firmware setup