ua1zbe/meshcore-sar_android
1
0
Fork 0
mirror of https://github.com/dz0ny/meshcore-sar.git synced 2026-08-11 16:30:28 +00:00
Code Issues Packages Projects Releases 1 Wiki Activity

docs: compact README, link meshcore_client package

Browse Source
This commit is contained in:
Janez T
2026-02-28 14:12:01 +01:00
parent c39e0e1344
commit 6f94d3a9ba
1 changed files with 39 additions and 308 deletions
Download Patch File Download Diff File Expand all files Collapse all files

347
README.md
View File

@@ -1,343 +1,74 @@
# MeshCore SAR
A Flutter-based Search and Rescue (SAR) application that communicates with MeshCore mesh network devices via Bluetooth Low Energy (BLE).
Flutter app for Search and Rescue operations over a [MeshCore](https://github.com/meshcore-dev) mesh radio network via Bluetooth Low Energy.
## 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
- **Messaging** — send/receive messages to contacts and channels
- **Contacts** — track team members, repeaters, and rooms with live telemetry
- **SAR Markers** — drop emoji-coded location pins (person found, fire, staging area) via chat messages
- **Map** — view team positions and markers on OpenStreetMap / topo / satellite; tiles cached for offline use
- **Location tracking** — periodic GPS updates broadcast to the mesh
- **Packet log** — inspect raw BLE frames for debugging
## Prerequisites
## BLE Protocol
Before building the app, ensure you have:
The BLE communication layer lives in a separate reusable package:
**[github.com/dz0ny/meshcore_client](https://github.com/dz0ny/meshcore_client)**
- 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)
It handles connection management, command queueing, and binary frame parsing/building.
### Install Flutter
## Requirements
If you haven't installed Flutter yet:
- Flutter 3.19+ / Dart 3.3+
- Physical device with Bluetooth (BLE does not work on simulators)
- iOS 13+ or Android SDK 21+
## Build
```bash
# 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**:
```bash
cd /path/to/meshcore-sar/meshcore_sar_app
```
2. **Install dependencies**:
```bash
flutter pub get
```
3. **Verify setup**:
```bash
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**:
```bash
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**:
```bash
# 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"
```bash
# Solution: Clean and rebuild
cd ios
pod deintegrate
pod install
cd ..
flutter clean
flutter pub get
flutter run # debug
flutter build apk --release # Android
flutter build ios --release # iOS
```
**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**:
```bash
flutter devices
```
4. **Run the app**:
```bash
# Run in debug mode
flutter run
# Or specify device
flutter run -d <device-id>
```
5. **Build APK**:
```bash
# 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**:
```bash
# 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
```bash
# 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'"
```bash
# Add to android/app/build.gradle
android {
buildTypes {
release {
minifyEnabled false
}
}
}
```
## Running on Emulator/Simulator
### iOS Simulator
### iOS signing
```bash
# List available simulators
flutter emulators
# Launch a simulator
flutter emulators --launch <simulator-id>
# Run app
flutter run
open ios/Runner.xcworkspace
# Select team in Signing & Capabilities, then run from Xcode
```
**Note**: BLE functionality will not work on iOS Simulator. Use a physical device for testing.
### Android Emulator
### Clean rebuild
```bash
# 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
flutter clean && flutter pub get
cd ios && pod deintegrate && pod install && cd ..
```
**Note**: BLE functionality requires specific emulator setup or physical device.
## Permissions
The app requires the following permissions:
| Platform | Permissions |
|----------|-------------|
| iOS | Bluetooth, Location (when in use) |
| Android | `BLUETOOTH_SCAN`, `BLUETOOTH_CONNECT`, `ACCESS_FINE_LOCATION`, `INTERNET` |
### iOS (ios/Runner/Info.plist)
- `NSBluetoothAlwaysUsageDescription`: Bluetooth access for MeshCore devices
- `NSLocationWhenInUseUsageDescription`: Location access for map features
## SAR Marker format
### 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>
S:<emoji>:<lat>,<lon>
```
Examples:
- `S:🧑:46.0569,14.5058` - Found person
- `S:🔥:46.0570,14.5060` - Fire location
- `S:🏕️:46.0571,14.5062` - Staging area
Examples: `S:🧑:46.0569,14.5058` · `S:🔥:46.057,14.506` · `S:🏕️:46.0571,14.506`
## 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
```bash
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
```bash
# Complete clean rebuild
flutter clean
cd ios && pod deintegrate && pod install && cd ..
cd android && ./gradlew clean && cd ..
flutter pub get
flutter run
lib/
├── models/ — data types (re-exported from meshcore_client)
├── providers/ — state management (Provider pattern)
├── screens/ — top-level pages
├── services/ — location tracking, SSE bridge, tile cache
└── widgets/ — reusable UI components
```
## 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