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 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

omi-firmware-patterns