meshcore-sar_android/CLAUDE.md

CLAUDE.md - MeshCore SAR Technical Reference

AI assistant guide for the MeshCore SAR Flutter application.

⚠️ CRITICAL: Flutter Development Rules

NEVER run or kill Flutter processes:

• DO NOT execute flutter run command
• DO NOT kill Flutter processes (pkill flutter, killall flutter)
• User manages Flutter development server - only make code changes
• Hot reload happens automatically when files are saved

Quick Reference

Project Type: Flutter Mobile App (iOS 13+, Android API 21+) Architecture: Provider-based state management + BLE communication Protocol: MeshCore BLE Companion Radio (Little Endian byte order) Repository: https://github.com/meshcore-dev/meshcore.js

BLE Service UUIDs:

• Service: 6E400001-B5A3-F393-E0A9-E50E24DCCA9E
• RX (write): 6E400002-B5A3-F393-E0A9-E50E24DCCA9E
• TX (notify): 6E400003-B5A3-F393-E0A9-E50E24DCCA9E

Key Dependencies:

• flutter_blue_plus ^2.0.0 (BLE)
• flutter_map ^8.2.2 (mapping)
• provider ^6.1.0 (state)
• geolocator ^14.0.2 (GPS)

Project Structure

lib/
├── models/              # Data models
│   ├── contact.dart, message.dart, sar_marker.dart
│   ├── map_drawing.dart           # MapDrawing, LineDrawing, RectangleDrawing
│   ├── device_info.dart, room_login_state.dart, map_layer.dart
├── services/            # Business logic
│   ├── meshcore_ble_service.dart      # BLE coordinator (399 lines)
│   ├── protocol/                      # Frame parsing & building (628 lines)
│   ├── ble/                           # Connection, commands, responses (963 lines)
│   ├── location_tracking_service.dart # GPS + mesh broadcast (501 lines)
│   ├── map_marker_service.dart        # Marker generation + geodesic (518 lines)
│   └── validation_service.dart        # Form validation (511 lines)
├── providers/           # State management
│   ├── connection_provider.dart       # BLE connection state
│   ├── contacts_provider.dart         # Contact list
│   ├── messages_provider.dart         # Messages + SAR markers
│   ├── map_provider.dart              # Map navigation
│   ├── drawing_provider.dart          # Map drawing state
│   └── app_provider.dart              # Coordinator (uses all above)
├── screens/             # UI screens (home, messages, contacts, map, settings, device_config, map_management, packet_log)
├── widgets/             # Reusable components
│   ├── map_markers.dart               # Map marker rendering
│   ├── map/                           # Map-specific widgets
│   │   ├── drawing_layer.dart         # Drawing rendering on map
│   │   └── drawing_toolbar.dart       # Drawing UI controls
│   ├── messages/, contacts/           # Feature-specific widgets
└── utils/               # Utilities
    ├── sar_message_parser.dart        # SAR marker parsing
    └── drawing_message_parser.dart    # Drawing message parsing

MeshCore Protocol

Frame Delimiters

• BLE: Single characteristic value (link layer handles integrity)
• USB: > (0x3E) outbound, < (0x3C) inbound, 2-byte length (LE), then frame data
• All uint32 values use Little Endian byte order

Command Codes (App → Radio)

Code	Name	Description
1	CMD_APP_START	First command after connection → RESP_CODE_SELF_INFO(5)
2	CMD_SEND_TXT_MSG	Send text message to contact (DM)
3	CMD_SEND_CHANNEL_TXT_MSG	Send flood-mode text to channel
4	CMD_GET_CONTACTS	Sync contacts (optional 'since' param)
5	CMD_GET_DEVICE_TIME	Get device clock (epoch secs, UTC)
6	CMD_SET_DEVICE_TIME	Set device clock
7	CMD_SEND_SELF_ADVERT	Send Advertisement packet
8	CMD_SET_ADVERT_NAME	Update node name in adverts
9	CMD_ADD_UPDATE_CONTACT	Add/modify contact
10	CMD_SYNC_NEXT_MESSAGE	Get next text message from queue
11	CMD_SET_RADIO_PARAMS	Save radio parameters
12	CMD_SET_RADIO_TX_POWER	Set radio TX power
13	CMD_RESET_PATH	Reset out_path for contact
14	CMD_SET_ADVERT_LATLON	Update lat/lon in adverts
15	CMD_REMOVE_CONTACT	Remove contact
16	CMD_SHARE_CONTACT	Share contact via zero-hop advert
17	CMD_EXPORT_CONTACT	Export contact as business card
18	CMD_IMPORT_CONTACT	Import contact from business card
19	CMD_REBOOT	Reboot companion device
20	CMD_GET_BATT_AND_STORAGE	Get battery mV and storage stats
21	CMD_SET_TUNING_PARAMS	Set tuning parameters
22	CMD_DEVICE_QUERY	First command to send → RESP_CODE_DEVICE_INFO(13)
25	CMD_SEND_RAW_DATA	Transmit PAYLOAD_TYPE_RAW_CUSTOM
26	CMD_SEND_LOGIN	Send login to repeater/room
27	CMD_SEND_STATUS_REQ	Send status request
36	CMD_SEND_TRACE_PATH	Initiate TRACE with SNR collection
37	CMD_SET_DEVICE_PIN	Set BLE PIN code
38	CMD_SET_OTHER_PARAMS	Set various parameters
39	CMD_SEND_TELEMETRY_REQ	Request telemetry (deprecated)
40	CMD_GET_CUSTOM_VARS	Retrieve custom variables
41	CMD_SET_CUSTOM_VAR	Set single custom variable
42	CMD_GET_ADVERT_PATH	Query last advert path
43	CMD_GET_TUNING_PARAMS	Get airtime-factor & rx-delay
50	CMD_SEND_BINARY_REQ	Binary request (preferred over 39)
51	CMD_FACTORY_RESET	Erase flash file system

Response Codes (Radio → App)

Code	Name	Description
0	RESP_CODE_OK	Success
1	RESP_CODE_ERR	Error (includes err_code)
2	RESP_CODE_CONTACTS_START	Start contacts sync
3	RESP_CODE_CONTACT	Single contact info
4	RESP_CODE_END_OF_CONTACTS	End contacts sync
5	RESP_CODE_SELF_INFO	Node's own information
6	RESP_CODE_SENT	Message sent with ACK/TAG
7	RESP_CODE_CONTACT_MSG_RECV	Contact message received
8	RESP_CODE_CHANNEL_MSG_RECV	Channel message received
9	RESP_CODE_CURR_TIME	Current device time
10	RESP_CODE_NO_MORE_MESSAGES	Message queue empty
11	RESP_CODE_EXPORT_CONTACT	Contact export data
12	RESP_CODE_BATT_AND_STORAGE	Battery and storage info
13	RESP_CODE_DEVICE_INFO	Device firmware/hardware info
21	RESP_CODE_CUSTOM_VARS	Custom variables state
22	RESP_CODE_ADVERT_PATH	Last advert path

Push Notifications (Radio → App, Async)

Code	Name	Description
0x80	PUSH_CODE_ADVERT	New advertisement received
0x81	PUSH_CODE_PATH_UPDATED	Contact received new path
0x82	PUSH_CODE_SEND_CONFIRMED	Message ACK received
0x83	PUSH_CODE_MSG_WAITING	New text message received
0x84	PUSH_CODE_RAW_DATA	PAYLOAD_TYPE_RAW_CUSTOM received
0x85	PUSH_CODE_LOGIN_SUCCESS	Login successful
0x86	PUSH_CODE_LOGIN_FAIL	Login failed
0x87	PUSH_CODE_STATUS_RESPONSE	Status response received
0x88	PUSH_CODE_LOG_RX_DATA	Debug: raw OTA packet (diagnostic)
0x89	PUSH_CODE_TRACE_DATA	TRACE packet end of path
0x8A	PUSH_CODE_NEW_ADVERT	New contact advert
0x8B	PUSH_CODE_TELEMETRY_RESPONSE	Telemetry response
0x8C	PUSH_CODE_BINARY_RESPONSE	Binary response

Constants

ADV_TYPE (Contact Type):

• 0: ADV_TYPE_NONE (unknown/invalid)
• 1: ADV_TYPE_CHAT (team member, shown on map)
• 2: ADV_TYPE_REPEATER (network repeater)
• 3: ADV_TYPE_ROOM (communication room/server)

TXT_TYPE (Message Type):

• 0: TXT_TYPE_PLAIN (plain text)
• 1: TXT_TYPE_CLI_DATA (CLI command)
• 2: TXT_TYPE_SIGNED_PLAIN (plain text + extra 4 bytes of sender's public key for verification)

ERR_CODE:

• 1: ERR_CODE_UNSUPPORTED_CMD
• 2: ERR_CODE_NOT_FOUND
• 3: ERR_CODE_TABLE_FULL
• 4: ERR_CODE_BAD_STATE
• 5: ERR_CODE_FILE_IO_ERROR
• 6: ERR_CODE_ILLEGAL_ARG

CRITICAL: Channels vs. Rooms

Channels (numeric identifiers):

• Channel 0 = "Public Channel" (default flood-mode broadcast)
• Channel 1+ = Reserved for future
• Ephemeral - messages NOT persisted
• Use CMD_SEND_CHANNEL_TXT_MSG

Rooms (ADV_TYPE_ROOM contacts):

• Named contacts with public keys
• Persistent and immutable storage
• Use CMD_SEND_TXT_MSG with room's public key (direct message)
• Optional: Login with CMD_SEND_LOGIN to read stored messages

SAR Message Routing:

• SAR markers MUST be sent to rooms, NOT public channel
• Rooms provide reliable delivery and storage for critical SAR data

Room Login Protocol Flow (CRITICAL)

1. Client sends CMD_SEND_LOGIN (26): Radio internally generates sender_timestamp and sync_since
2. Room server processes login: Validates password, stores sync_since, delays first push 2000ms
3. Client receives response: PUSH_CODE_LOGIN_SUCCESS (0x85) or PUSH_CODE_LOGIN_FAIL (0x86)
4. Room server auto-pushes messages: Round-robin every 1200ms, sends messages where post_timestamp > sync_since
5. Client receives pushed messages: PUSH_CODE_MSG_WAITING (0x83) → call CMD_SYNC_NEXT_MESSAGE (10)

Implementation Rules:

• ❌ DO NOT call syncAllMessages() after PUSH_CODE_LOGIN_SUCCESS
• ✅ DO wait for PUSH_CODE_MSG_WAITING push notifications
• ✅ DO call syncNextMessage() when onMessageWaiting fires

Cayenne LPP Format

Format: [Channel] [Type] [Data...]

Supported Types:

• 136 (0x88): GPS Location (lat/lon/alt: int32/10000, int32/10000, int32/100)
• 103 (0x67): Temperature (int16/10 for °C)
• 2 (0x02): Analog Input (uint16/100 for volts, used for battery)

SAR Message Format

Format: S:<emoji>:<latitude>,<longitude>:<optional_message>

Recognized Emojis:

• 🧑 or 👤: Found Person
• 🔥: Fire Location
• 🏕️ or ⛺: Staging Area

Rules:

• Must start with S:
• Single emoji after first colon
• Comma-separated lat/lon coordinates
• Optional message after third colon (displayed in message bubble)
• No spaces in coordinates section

Examples:

• S:🧑:37.7749,-122.4194 - Basic SAR marker
• S:🔥:40.7128,-74.0060:Large wildfire spreading rapidly - With message
• S:🏕️:34.0522,-118.2437:Base camp established, supplies available - With detailed note

Message Display:

• SAR markers shown with highlighted colored bubble
• Emoji, type name, and coordinates always displayed
• Optional message shown in secondary container below coordinates
• Tap to navigate to location on map

Map Drawing Message Format

Format: D:<json>

Ultra-Compact JSON Format:

• Prefix: D: identifies drawing messages
• Sender: Extracted from packet metadata (not in JSON)
• Type field (t): Shape type as integer
  • 0: Line drawing
  • 1: Rectangle drawing
• Color field (c): Color index (0-7)
  • 0: Red, 1: Blue, 2: Green, 3: Yellow
  • 4: Orange, 5: Purple, 6: Pink, 7: Cyan
• Points field (p): Flat array of coordinates [lat1,lon1,lat2,lon2,...]
• Bounds field (b): Rectangle bounds [topLat,topLon,botLat,botLon]

Example Line Drawing (red, 2 points):

D:{"t":0,"c":0,"p":[45.123,-122.456,45.234,-122.567]}

Example Rectangle Drawing (blue):

D:{"t":1,"c":1,"b":[45.1,-122.5,45.2,-122.4]}

Implementation Details:

• Models: lib/models/map_drawing.dart (MapDrawing, LineDrawing, RectangleDrawing)
• Parser: lib/utils/drawing_message_parser.dart (DrawingMessageParser)
• Provider: lib/providers/drawing_provider.dart (DrawingProvider)
• Colors: 8 predefined colors mapped to indices for bandwidth efficiency
• Local persistence uses full JSON format with timestamps and IDs
• Network transmission uses ultra-compact format (~37% size reduction)

State Management Architecture

Provider Hierarchy

MultiProvider
├── ConnectionProvider      # BLE connection state
├── ContactsProvider        # Contact list
├── MessagesProvider        # Messages + SAR markers
├── MapProvider            # Map navigation
├── DrawingProvider        # Map drawing state
└── AppProvider            # Coordinator (uses all above)

Event Flow

BLE Device → MeshCoreBleService → ConnectionProvider → AppProvider
                                         ↓
                                  ContactsProvider
                                  MessagesProvider
                                  DrawingProvider
                                         ↓
                                        UI

Drawing Message Flow:

User draws → DrawingProvider → DrawingToolbar (share) → ConnectionProvider (BLE)
                                                              ↓
Remote User ← UI ← DrawingProvider ← AppProvider ← ConnectionProvider ← BLE Device

Contact Types:

• none(0): Unknown/invalid
• chat(1): Team member (shown on map)
• repeater(2): Network repeater node
• room(3): Communication channel/room

Map Display: Only ContactType.chat with valid GPS shown on map

Service Layer

LocationTrackingService (Singleton)

Purpose: GPS tracking + intelligent mesh network location broadcasting

Key Features:

• Callback-based architecture (onPositionUpdate, onError, onBroadcastSent, onTrackingStateChanged)
• Configurable thresholds (minDistanceMeters: 5.0m, maxDistanceMeters: 100.0m, minTimeIntervalSeconds: 30s)
• Smart broadcasting: First = immediate, ≥100m = immediate, ≥5m + ≥30s = broadcast
• Haversine distance calculation for GPS accuracy

Files: lib/services/location_tracking_service.dart (501 lines)

MapMarkerService (Singleton)

Purpose: Map marker generation + geodesic calculations

Key Features:

• Pure functions (testability + performance)
• Contact markers (battery badge, distance from user)
• SAR markers (color-coded: green=person, red=fire, orange=staging)
• Calculate distance, bearing/azimuth, format distance display
• Automatic "time ago" labels

Files: lib/services/map_marker_service.dart (518 lines)

ValidationService (Singleton)

Purpose: Form validation + input parsing with structured error handling

Key Features:

• Structured result types (ValidationResult, ParseResult<T>)
• Coordinate validation (lat: -90 to +90, lon: -180 to +180)
• Radio parameters (freq: 137-1020 MHz, bw: 7.8-500 kHz, sf: 5-12, cr: 5-8, tx: -9 to +22 dBm)
• Text/name validation, zoom level (0-19)

Files: lib/services/validation_service.dart (511 lines)

Map Implementation

Tile Layers

1. OpenStreetMap (default): Max zoom 19, street-level navigation
2. OpenTopoMap: Max zoom 17, topographic features
3. ESRI World Imagery: Max zoom 19, satellite imagery

Offline Tile Caching

• Backend: flutter_map_tile_caching with ObjectBox
• Behavior: CacheBehavior.cacheFirst, 30-day validity
• Region downloads: RectangleRegion(bounds) → store.download.startForeground()

Map Markers

Team Member (Blue): CircleAvatar, battery badge, name label, tap for details SAR Event (Color-coded): Green (person), Red (fire), Orange (staging), time ago label, type label, tap for details

Map Navigation

Message tab → tap SAR marker → MapProvider.navigateToLocation() → switch to Map tab → MapTab._handleMapNavigation() → MapProvider.clearNavigation()

User Location Tracking

• Permission: NSLocationWhenInUseUsageDescription, NSLocationTemporaryPreciseUsageDescription
• Accuracy: LocationAccuracy.best, distance filter: 10m
• Marker: Blue pulsing circle, navigation icon, tap to center/track

Map Legend

Collapsible legend (top-right), shows counts of team members and SAR markers

Detailed Compass Dialog

Ultra-compact location display, tap to toggle DD/DMS formats, no close button (tap outside to close)

Common Development Tasks

Adding a New BLE Command

1. Add command code to lib/services/meshcore_constants.dart
2. Add frame builder in lib/services/protocol/frame_builder.dart
3. Add public API method in lib/services/meshcore_ble_service.dart
4. Add response parser in lib/services/protocol/frame_parser.dart
5. Handle response in lib/services/ble/ble_response_handler.dart
6. Add callback in lib/services/meshcore_ble_service.dart

Adding a New SAR Marker Type

1. Update enum in lib/models/sar_marker.dart
2. Add to parser in lib/utils/sar_message_parser.dart
3. Add color in lib/widgets/map_markers.dart
4. Update providers in lib/providers/messages_provider.dart

Adding a New Map Layer

1. Add to model in lib/models/map_layer.dart
2. Add to allLayers list
3. Layer appears automatically in layer selector UI

Working with Map Drawings

Drawing Flow:

1. User selects drawing mode (line/rectangle) → DrawingProvider.setDrawingMode()
2. User taps map → touch events captured by DrawingLayer
3. Preview rendered during drawing → DrawingProvider.getPreviewDrawing()
4. User completes drawing → saved to DrawingProvider._drawings list
5. User shares drawing → DrawingToolbar._shareDrawingsToChannel() or _shareDrawingsToRoom()
6. Message sent via BLE → ConnectionProvider.sendChannelMessage() or sendTextMessage()
7. Receiver parses message → DrawingMessageParser.parseDrawingMessage() with sender from packet
8. Drawing added to map → DrawingProvider.addReceivedDrawing()

Color Management:

• UI uses DrawingColors.palette (8 Flutter Color objects)
• Network uses color indices (0-7) via DrawingColors.colorToIndex()/indexToColor()
• Persistence uses full ARGB32 color values

Key Files:

• Models: lib/models/map_drawing.dart (278 lines)
• Parser: lib/utils/drawing_message_parser.dart (45 lines)
• Provider: lib/providers/drawing_provider.dart (280 lines)
• UI: lib/widgets/map/drawing_toolbar.dart, lib/widgets/map/drawing_layer.dart

Build Commands

# Dependencies
flutter pub get

# Development
flutter run               # Debug mode
flutter run -d <device>   # Specific device
# Hot reload: press 'r'  |  Hot restart: press 'R'

# Code Quality
flutter analyze          # Static analysis
flutter test            # Run tests
dart format lib/        # Format code
flutter clean           # Clean build

# iOS
flutter build ios --release
flutter build ipa

# Android
flutter build apk --debug
flutter build apk --release
flutter build appbundle --release

Troubleshooting

BLE Issues

• "Bluetooth adapter not available": Check Bluetooth on, verify permissions, check Info.plist/AndroidManifest.xml
• "Connection failed": BLE support required, check service UUID, verify range (<10m), try scanning again

Runtime Issues

MissingPluginException: Native plugin not installed (common after adding dependencies)

cd ios && pod install && cd .. && flutter clean && flutter pub get && flutter run

Build Issues

iOS Pod Install Fails:

cd ios && rm Podfile.lock && rm -rf Pods/ && pod install --repo-update && cd ..

CocoaPods ObjectBox Version Conflict:

cd ios && rm Podfile.lock && rm -rf Pods/ && pod repo update && pod install && cd ..
flutter clean && flutter pub get && flutter run

Android Gradle Timeout: Add to android/gradle.properties:

org.gradle.daemon=true
org.gradle.parallel=true
org.gradle.jvmargs=-Xmx4096m

Flutter Version Conflicts:

flutter channel stable && flutter upgrade && flutter pub upgrade

Performance Optimization

BLE Communication

• Buffer incoming data for partial packets
• Throttle telemetry requests (max 1/sec per contact)
• Use notifyListeners() sparingly

Map Performance

• Limit visible markers (cluster if >100)
• Use repaint boundary for marker widgets
• Implement marker virtualization for large datasets

Memory Management

• Dispose controllers in dispose() methods
• Clear message history after 1000 messages
• Implement tile cache size limits

Security Considerations

• BLE: No authentication in current protocol - add encryption for production
• Permissions: Request minimum required
• Data: No sensitive data logging
• Network: HTTPS for all tile sources

References

• Flutter Documentation
• flutter_blue_plus API
• flutter_map Documentation
• MeshCore Protocol
• Cayenne LPP Specification
• Provider Package