MeshMapper Flutter App

Note: All issues and feature requests are tracked in the main project repo: MeshMapper/MeshMapper_Project. Please open issues there rather than in this repository.

Cross-platform wardriving app for MeshCore. Connect to MeshCore companions via Bluetooth, map repeater coverage, and contribute data to the community mesh map.

Built with contributions by The Greater Ottawa Mesh Radio Enthusiasts

View the Map | Wiki | Onboard Your Region | Submit Bug/Feature

---

Get the App

App Store Releases

• Android:Google Play or grab the APK from GitHub
• iOS:App Store

Beta Releases

• iOS:TestFlight
• Android:APK from GitHub

Quick Start — Power on your MeshCore Companion, open the app, tap Connect, and select your device via Bluetooth.

---

Features

• Cross-Platform — Android and iOS
• BLE Connectivity — Connect to MeshCore companion devices via Bluetooth Low Energy
• GPS Tracking — High-accuracy location tracking with 50m distance filter
• Real-time Map — View TX/RX/DISC ping markers on OpenStreetMap with dark mode tiles
• Repeater Echo Detection — 7-second window detects which repeaters echo your pings
• Passive RX Logging — Continuously monitors mesh traffic and logs observations
• Persistent API Queue — Batch upload with retry logic, survives app restarts
• Offline Mode — Wardrive without connectivity, upload data later
• 30+ Device Models — Automatic identification and power reporting for Ikoka, Heltec, RAK, LilyGo, Seeed, and more
• Noise Floor Graphing — Track signal quality over time
• Dark/Light Theme — System theme support

---

Development

See CONTRIBUTING.md for setup instructions and PR workflow, and DEVELOPMENT.md for architecture docs and coding standards.

---

Architecture

The app uses a service-oriented architecture with platform-specific BLE abstraction:

lib/
├── main.dart # App entry point, platform detection
├── models/ # Data models (Hive-annotated)
├── providers/ # State management (Provider/ChangeNotifier)
├── screens/ # Full-page UI screens
├── widgets/ # Reusable components
└── services/
├── bluetooth/ # BLE abstraction layer
│ ├── bluetooth_service.dart # Abstract interface
│ ├── mobile_bluetooth.dart # Android/iOS (flutter_blue_plus)
│ └── web_bluetooth.dart # Web (flutter_web_bluetooth)
├── meshcore/ # MeshCore protocol layer
│ ├── connection.dart # 10-step connection workflow
│ ├── packet_parser.dart # Binary packet parsing
│ ├── unified_rx_handler.dart # Packet routing (TX vs RX)
│ ├── tx_tracker.dart # Repeater echo detection
│ └── rx_logger.dart # Passive observation logging
├── gps_service.dart # GPS tracking
├── ping_service.dart # TX/RX ping orchestration
├── api_queue_service.dart # Persistent upload queue
└── device_model_service.dart # Device identification

Key design decisions:

• Unified RX Handler — All incoming BLE packets are accepted, parsed once, then routed to TX tracking or RX logging
• Platform BLE abstraction — Runtime selection via kIsWeb in main.dart
• Hive for persistence — Local storage for API queue, preferences, and offline sessions
• Provider for state — Single AppStateProvider with ChangeNotifier

See DEVELOPMENT.md for full details.

---

Contributing

Contributions are welcome! Please read CONTRIBUTING.md before submitting a pull request.

License

This project is licensed under the MIT License — see LICENSE for details.

Acknowledgments

• Original MeshMapper WebClient
• MeshCore firmware project
• meshcore-open by zjs81 — Android USB Serial support is based heavily on its native USB host implementation (MIT License, see THIRD_PARTY_LICENSES)
• The Greater Ottawa Mesh Radio Enthusiasts community