MeshCore SAR

A Flutter-based Search and Rescue (SAR) application that communicates with MeshCore mesh network devices via Bluetooth Low Energy (BLE).

Features

• Real-time Messaging: Receive and display messages from MeshCore mesh network
• Contact Management: Track team members, repeaters, and communication channels
• SAR Markers: Special location markers for found persons, fires, and staging areas
• Interactive Map: View team locations and SAR markers on an interactive map with multiple layer options:
  • OpenStreetMap (default)
  • OpenTopoMap (topographic)
  • ESRI World Imagery (satellite)
• Offline Support: Map tiles cached for offline operation
• Telemetry Tracking: Monitor battery levels, GPS locations, and temperature for all contacts
• BLE Communication: Direct connection to MeshCore devices via Bluetooth

Prerequisites

Before building the app, ensure you have:

• Flutter SDK 3.19.0 or higher
• Dart SDK 3.3.0 or higher
• Xcode 15+ (for iOS builds)
• Android Studio with Android SDK (for Android builds)
• CocoaPods (for iOS dependencies)

Install Flutter

If you haven't installed Flutter yet:

# macOS/Linux
git clone https://github.com/flutter/flutter.git -b stable
export PATH="$PATH:`pwd`/flutter/bin"

# Verify installation
flutter doctor

Setup

1. Clone the repository:

   cd /path/to/meshcore-sar/meshcore_sar_app
   

2. Install dependencies:

   flutter pub get
   

3. Verify setup:

   flutter doctor
   

   Fix any issues reported by Flutter Doctor before proceeding.

Building and Running

iOS

Requirements

• macOS computer
• Xcode 15 or higher
• Apple Developer account (for physical device deployment)
• iOS device with iOS 13.0 or higher

Steps

1. Open iOS folder in Xcode:

   open ios/Runner.xcworkspace
   

2. Configure signing:

   • In Xcode, select the Runner project
   • Go to "Signing & Capabilities"
   • Select your development team
   • Xcode will automatically handle provisioning

3. Connect your iOS device via USB

4. Enable Developer Mode on your iOS device:

   • Settings → Privacy & Security → Developer Mode → Enable

5. Trust your Mac on the iOS device when prompted

6. Run the app:

   # Run in debug mode
   flutter run
   
   # Or build release
   flutter build ios --release
   

7. Install on device from Xcode:

   • Select your device in Xcode
   • Click the "Run" button (▶️)

Common iOS Issues

Problem: "Runner has conflicting provisioning settings"

# Solution: Clean and rebuild
cd ios
pod deintegrate
pod install
cd ..
flutter clean
flutter pub get

Problem: Bluetooth permissions not working

• Ensure Info.plist contains all required permission keys
• Check that permissions are requested at runtime

Android

Requirements

• Android Studio installed
• Android SDK 21 (Android 5.0) or higher
• Physical Android device or emulator

Steps

1. Enable Developer Options on your Android device:

   • Settings → About Phone → Tap "Build Number" 7 times
   • Go back → Developer Options → Enable "USB Debugging"

2. Connect your Android device via USB and authorize the computer

3. Verify device connection:

   flutter devices
   

4. Run the app:

   # Run in debug mode
   flutter run
   
   # Or specify device
   flutter run -d <device-id>
   

5. Build APK:

   # Debug APK
   flutter build apk --debug
   
   # Release APK
   flutter build apk --release
   
   # App Bundle (for Play Store)
   flutter build appbundle --release
   

   The APK will be located at:

   • Debug: build/app/outputs/flutter-apk/app-debug.apk
   • Release: build/app/outputs/flutter-apk/app-release.apk

6. Install APK manually:

   # Install on connected device
   flutter install
   
   # Or use adb
   adb install build/app/outputs/flutter-apk/app-release.apk
   

Common Android Issues

Problem: Gradle build fails

# Solution: Clean and rebuild
flutter clean
cd android
./gradlew clean
cd ..
flutter pub get
flutter build apk

Problem: Bluetooth permissions denied

• Ensure all Bluetooth permissions are in AndroidManifest.xml
• For Android 12+, request BLUETOOTH_SCAN and BLUETOOTH_CONNECT at runtime

Problem: "Execution failed for task ':app:minifyReleaseWithR8'"

# Add to android/app/build.gradle
android {
    buildTypes {
        release {
            minifyEnabled false
        }
    }
}

Running on Emulator/Simulator

iOS Simulator

# List available simulators
flutter emulators

# Launch a simulator
flutter emulators --launch <simulator-id>

# Run app
flutter run

Note: BLE functionality will not work on iOS Simulator. Use a physical device for testing.

Android Emulator

# List available emulators
flutter emulators

# Create new emulator in Android Studio:
# Tools → Device Manager → Create Virtual Device

# Launch emulator
flutter emulators --launch <emulator-id>

# Run app
flutter run

Note: BLE functionality requires specific emulator setup or physical device.

Permissions

The app requires the following permissions:

iOS (ios/Runner/Info.plist)

• NSBluetoothAlwaysUsageDescription: Bluetooth access for MeshCore devices
• NSLocationWhenInUseUsageDescription: Location access for map features

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

• BLUETOOTH_SCAN: Scan for BLE devices
• BLUETOOTH_CONNECT: Connect to BLE devices
• ACCESS_FINE_LOCATION: Required for BLE scanning
• INTERNET: Download map tiles

Usage

1. Connect to MeshCore Device:

   • Tap "Connect" in the status bar
   • Select your MeshCore device from the scan results
   • Wait for connection confirmation

2. View Messages:

   • Messages tab shows all received messages
   • SAR marker messages are highlighted
   • Tap SAR marker to view on map

3. Manage Contacts:

   • Contacts tab shows team members, repeaters, and channels
   • Tap contact to view details
   • Use refresh button to request telemetry updates

4. View Map:

   • Map tab displays team locations and SAR markers
   • Tap layer selector to switch between map styles
   • Use zoom controls or pinch gestures
   • Tap markers for details
   • Tap items in bottom list to navigate

SAR Marker Format

Messages can contain SAR markers using this format:

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

Examples:

• S:🧑:46.0569,14.5058 - Found person
• S:🔥:46.0570,14.5060 - Fire location
• S:🏕️:46.0571,14.5062 - Staging area

Architecture

• Models: Data structures for contacts, messages, markers, telemetry
• Services: BLE communication, tile caching, protocol parsing
• Providers: State management using Provider pattern
• Screens: UI components for messages, contacts, map
• Widgets: Reusable UI elements like map markers

Dependencies

Key packages used:

• flutter_blue_plus: BLE communication
• flutter_map: Interactive mapping
• flutter_map_tile_caching: Offline map tiles
• provider: State management
• latlong2: GPS coordinate handling
• permission_handler: Runtime permissions

Troubleshooting

App crashes on launch

flutter clean
flutter pub get
flutter run

BLE not working

• Ensure Bluetooth is enabled on device
• Check that all permissions are granted
• Verify MeshCore device is powered on and in range

Map tiles not loading

• Check internet connection
• Verify tile URLs are accessible
• Clear tile cache and reload

Build errors

# Complete clean rebuild
flutter clean
cd ios && pod deintegrate && pod install && cd ..
cd android && ./gradlew clean && cd ..
flutter pub get
flutter run

License

This project is for Search and Rescue operations using MeshCore mesh network devices.

Support

For issues related to:

• Flutter: https://flutter.dev/community
• MeshCore Protocol: https://github.com/meshcore-dev/meshcore.js
• App Issues: Open an issue in this repository