# MeshCore Open - Flutter Client

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

## Build Commands

```bash
# 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
```dart
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)