omi-flutter-patterns

Omi Flutter Patterns Skill

This skill provides guidance for working with the Omi Flutter app, including BLE device communication, state management, backend integration, and localization.

When to Use

Use this skill when:

• Working on Flutter/Dart code in app/
• Implementing BLE device communication
• Working with state management (Provider)
• Integrating with backend APIs
• Adding new UI screens or widgets

Key Patterns

State Management

The app uses Provider pattern for state management:

// Define provider
class ConversationProvider extends ChangeNotifier {
  List<Conversation> _conversations = [];
  
  List<Conversation> get conversations => _conversations;
  
  Future<void> loadConversations() async {
    _conversations = await api.getConversations();
    notifyListeners();
  }
}

// Use in widget
final provider = Provider.of<ConversationProvider>(context);

Localization

CRITICAL: All user-facing strings must use localization:

// ✅ GOOD
Text(context.l10n.helloWorld)

// ❌ BAD
Text('Hello World')

Adding keys: Use jq to add keys to ARB files, then run cd app && flutter gen-l10n

Backend Integration

REST API

// lib/backend/http/api/conversations.dart
class ConversationsAPI {
  Future<List<Conversation>> getConversations() async {
    final response = await httpClient.get('/v1/conversations');
    return (response.data['items'] as List)
        .map((json) => Conversation.fromJson(json))
        .toList();
  }
}

WebSocket

// lib/backend/http/webhooks.dart
class WebSocketClient {
  Future<void> connect(String uid) async {
    _socket = await WebSocket.connect('$baseUrl/v4/listen?uid=$uid');
    _socket!.listen((data) {
      // Handle transcript
    });
  }
}

BLE Device Communication

Device Connection

// Scan for devices
final devices = await scanForOmiDevices();  // Name: "Omi"

// Connect
await device.connect();

// Discover services
final services = await device.discoverServices();

// Audio service UUID: 19B10000-E8F2-537E-4F6C-D104768A1214
// Audio data UUID: 19B10001-E8F2-537E-4F6C-D104768A1214
// Codec type UUID: 19B10002-E8F2-537E-4F6C-D104768A1214

Audio Packet Format

• Header: 3 bytes (packet number + index)
• Payload: 160 audio samples
• Codec: Opus (preferred), PCM, Mu-law
• Byte order: Little-endian

Platform Support

The app supports:

• iOS: CocoaPods, Firebase config in ios/Config/
• Android: Gradle, Firebase config in android/app/src/
• macOS: CocoaPods, Firebase config in macos/Config/
• Windows: CMake, native Windows audio

Use PlatformManager for platform detection.

Common Tasks

Adding a New Screen

1. Create page in lib/pages/
2. Add route in navigation
3. Use Provider for state
4. Use localization for all strings
5. Test on all platforms

Adding a New API Endpoint

1. Add method to appropriate API class in lib/backend/http/api/
2. Use HttpClient for requests
3. Handle errors gracefully
4. Update data models if needed

Adding BLE Functionality

1. Use flutter_blue_plus package
2. Follow BLE protocol (see Protocol docs)
3. Handle packet fragmentation
4. Support all codec types

Related Documentation

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

• App Setup: docs/doc/developer/AppSetup.mdx - View online
• BLE Protocol: docs/doc/developer/Protocol.mdx - View online
• Flutter Architecture: .cursor/rules/flutter-architecture.mdc

Related Cursor Resources

Rules

• .cursor/rules/flutter-architecture.mdc - App structure and state management
• .cursor/rules/flutter-backend-integration.mdc - Backend API integration
• .cursor/rules/flutter-ble-protocol.mdc - BLE device communication
• .cursor/rules/flutter-localization.mdc - Localization requirements
• .cursor/rules/flutter-platform-specific.mdc - Platform-specific code

Subagents

• .cursor/agents/flutter-developer/ - Uses this skill for Flutter development

Commands

• /flutter-setup - Uses this skill for setup guidance
• /flutter-test - Uses this skill for testing patterns
• /flutter-build - Uses this skill for build patterns