Skip to content

CLAUDE.md

Latest commit

 

History

History
136 lines (105 loc) · 4.18 KB

CLAUDE.md

File metadata and controls

136 lines (105 loc) · 4.18 KB

MeshCore Open - Flutter Client

Open-source Flutter client for MeshCore LoRa mesh networking devices.

Build Commands

# Install dependencies
~/flutter/bin/flutter pub get

# Run in debug mode
~/flutter/bin/flutter run

# Build Android APK
~/flutter/bin/flutter build apk

# Build iOS
~/flutter/bin/flutter build ios

# Run static analysis
~/flutter/bin/flutter analyze

# Run tests
~/flutter/bin/flutter test

Project Structure

lib/
├── main.dart                    # App entry point, MaterialApp setup with Provider
├── connector/
│   └── meshcore_connector.dart  # BLE communication layer (MeshCoreConnector)
├── screens/
│   ├── scanner_screen.dart      # BLE device scanning (home screen)
│   ├── device_screen.dart       # Connected device hub with navigation
│   ├── chat_screen.dart         # Chat interface (placeholder)
│   ├── contacts_screen.dart     # Contacts list (placeholder)
│   └── settings_screen.dart     # Device info and app settings
└── widgets/
    └── device_tile.dart         # Device list item with signal strength

Architecture

State Management

  • Provider with ChangeNotifier pattern
  • MeshCoreConnector is the central state holder for BLE connection
  • Screens use Consumer<MeshCoreConnector> for reactive UI updates

Theming

  • Material 3 design (useMaterial3: true)
  • System-based dark/light mode (ThemeMode.system)
  • Blue color scheme seed

BLE Protocol

Nordic UART Service (NUS)

  • Service UUID: 6e400001-b5a3-f393-e0a9-e50e24dcca9e
  • RX Characteristic: 6e400002-b5a3-f393-e0a9-e50e24dcca9e (Write to device)
  • TX Characteristic: 6e400003-b5a3-f393-e0a9-e50e24dcca9e (Notify from device)

Device Discovery

  • Scans for devices with name prefix MeshCore-
  • Filters by platformName or advertisementData.advName

Connection States

enum MeshCoreConnectionState {
  disconnected,
  scanning,
  connecting,
  connected,
  disconnecting,
}

Frame I/O

  • Send: MeshCoreConnector.sendFrame(Uint8List data)
  • Receive: MeshCoreConnector.receivedFrames stream of Uint8List

Dependencies

Package Version Purpose
flutter_blue_plus ^2.1.0 BLE communication
provider ^6.1.5+1 State management
cupertino_icons ^1.0.8 iOS-style icons

Platform Configuration

Android (android/app/src/main/AndroidManifest.xml)

  • BLUETOOTH, BLUETOOTH_ADMIN (API 30 and below)
  • BLUETOOTH_SCAN, BLUETOOTH_CONNECT, BLUETOOTH_ADVERTISE (API 31+)
  • ACCESS_FINE_LOCATION, ACCESS_COARSE_LOCATION (for BLE scanning)

iOS (ios/Runner/Info.plist)

  • NSBluetoothAlwaysUsageDescription
  • NSBluetoothPeripheralUsageDescription

Coding Conventions

Code Philosophy

  • Minimal: Only write code that is necessary. Avoid over-engineering.
  • Organized: Keep related code together. One responsibility per file.
  • Maintainable: Favor readability over cleverness. Simple is better.

Style

  • Use StatelessWidget with Consumer for state-dependent UI
  • Use const constructors where possible
  • Prefix private methods/fields with _
  • Center app bar titles (centerTitle: true)
  • Material widgets only - no Cupertino or custom widgets
  • Handle disconnection gracefully (auto-navigate back to scanner)

Avoid

  • Premature abstractions - don't create helpers until needed in 3+ places
  • Unnecessary comments - code should be self-explanatory
  • Feature flags or backwards-compatibility shims
  • Over-engineered error handling for impossible scenarios

Key Files

File Purpose
lib/connector/meshcore_connector.dart All BLE logic - scanning, connecting, data transfer
lib/screens/scanner_screen.dart Entry point UI, device list
lib/main.dart App configuration, theme, Provider setup
pubspec.yaml Dependencies and project metadata

Placeholder Screens

The following screens are implemented as placeholders and need full implementation:

  • chat_screen.dart - Mesh chat functionality
  • contacts_screen.dart - Contact management
  • settings_screen.dart - Radio settings, node identity, location (partially implemented)