From 34c3bc48134e577458799d7805a3532fc20fed16 Mon Sep 17 00:00:00 2001 From: zach Date: Wed, 31 Dec 2025 22:29:42 -0700 Subject: [PATCH] update readme --- README.md | 199 +++++++++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 190 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index 8c9e5bc..d8dab79 100644 --- a/README.md +++ b/README.md @@ -1,16 +1,197 @@ -# meshcore_open +# MeshCore Open -A new Flutter project. +Open-source Flutter client for MeshCore LoRa mesh networking devices. + +## Overview + +MeshCore Open is a cross-platform mobile application for communicating with MeshCore LoRa mesh network devices via Bluetooth Low Energy (BLE). The app enables long-range, off-grid communication through peer-to-peer messaging, public channels, and mesh networking capabilities. + +## Features + +### Core Functionality +- **Direct Messaging**: Private encrypted conversations with individual contacts +- **Public Channels**: Broadcast messages to channel subscribers on the mesh network +- **Contact Management**: Organize contacts, track last seen times, and manage conversation history +- **Contact Groups**: Create custom groups to organize your mesh network contacts +- **Message Reactions**: React to messages with emoji responses +- **Message Replies**: Thread conversations with inline reply functionality + +### Mesh Network +- **Path Visualization**: View routing paths and signal quality for each contact +- **Route Management**: Manual path overriding and automatic route rotation +- **Signal Metrics**: Real-time SNR (Signal-to-Noise Ratio) tracking +- **Node Discovery**: Automatic detection of nearby mesh nodes +- **Repeater Support**: Connect to and manage repeater nodes for extended range + +### Map & Location +- **Live Map View**: Real-time visualization of mesh network nodes on an interactive map +- **Node Filtering**: Filter by node type (chat, repeater, sensor) and time range +- **Location Sharing**: Share GPS coordinates and custom markers with contacts +- **Offline Maps**: Download map tiles for offline use in remote areas +- **MGRS Coordinates**: Support for Military Grid Reference System coordinate format + +### Device Management +- **BLE Connection**: Scan and connect to MeshCore devices via Bluetooth +- **Device Settings**: Configure radio parameters, power settings, and network options +- **Battery Monitoring**: Real-time battery status with chemistry-specific voltage curves +- **Firmware Updates**: Over-the-air firmware updates via BLE (coming soon) + +### Repeater Hub +- **CLI Access**: Full command-line interface to repeater nodes +- **Settings Management**: Configure repeater behavior, power limits, and network settings +- **Statistics Dashboard**: View repeater traffic, connected clients, and system health +- **Remote Management**: Administer repeaters from anywhere on the mesh network + +## Technical Details + +### Architecture +- **Framework**: Flutter 3.38.5 / Dart 3.10.4 +- **State Management**: Provider pattern with ChangeNotifier +- **BLE Protocol**: Nordic UART Service (NUS) over Bluetooth Low Energy +- **Storage**: Local SQLite database for messages and contact data +- **Encryption**: End-to-end encryption for private messages using the MeshCore protocol + +### Platform Support +- ✅ **Android**: Full support (API 21+) +- ✅ **iOS**: Full support (iOS 12+) +- 🚧 **Desktop**: Limited support (macOS/Linux/Windows) + +### Dependencies +| Package | Purpose | +|---------|---------| +| flutter_blue_plus | Bluetooth Low Energy communication | +| provider | State management | +| sqflite | Local database storage | +| flutter_map | Interactive map display | +| latlong2 | Geographic coordinate handling | +| flutter_local_notifications | Background notification support | +| smaz | Message compression | +| pointycastle | Cryptographic operations | +| intl | Internationalization and date formatting | ## Getting Started -This project is a starting point for a Flutter application. +### Prerequisites +- Flutter SDK 3.38.5 or later +- Android Studio / Xcode (for mobile development) +- A MeshCore-compatible LoRa device -A few resources to get you started if this is your first Flutter project: +### Installation -- [Lab: Write your first Flutter app](https://docs.flutter.dev/get-started/codelab) -- [Cookbook: Useful Flutter samples](https://docs.flutter.dev/cookbook) +1. **Clone the repository** + ```bash + git clone https://github.com/zjs81/meshcore-open.git + cd meshcore-open + ``` -For help getting started with Flutter development, view the -[online documentation](https://docs.flutter.dev/), which offers tutorials, -samples, guidance on mobile development, and a full API reference. +2. **Install dependencies** + ```bash + flutter pub get + ``` + +3. **Run the app** + ```bash + flutter run + ``` + +### Building for Release + +**Android APK:** +```bash +flutter build apk --release +``` + +**iOS:** +```bash +flutter build ios --release +``` + +## Project Structure + +``` +lib/ +├── main.dart # App entry point +├── connector/ +│ ├── meshcore_connector.dart # BLE communication & state management +│ └── meshcore_protocol.dart # Protocol definitions & frame parsing +├── screens/ +│ ├── scanner_screen.dart # Device scanning (home screen) +│ ├── contacts_screen.dart # Contact list +│ ├── chat_screen.dart # Direct messaging +│ ├── channels_screen.dart # Public channels +│ ├── map_screen.dart # Network visualization map +│ ├── settings_screen.dart # Device settings +│ └── repeater_hub_screen.dart # Repeater management +├── models/ +│ ├── contact.dart # Contact data model +│ ├── message.dart # Message data structure +│ └── channel.dart # Channel definitions +├── services/ +│ ├── notification_service.dart # Push notifications +│ ├── message_retry_service.dart # Automatic message retry +│ ├── background_service.dart # Background BLE connection +│ └── map_tile_cache_service.dart # Offline map storage +└── storage/ + ├── message_store.dart # Message persistence + ├── contact_store.dart # Contact database + └── unread_store.dart # Unread message tracking +``` + +## 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 +Devices are discovered by scanning for BLE advertisements with the name prefix `MeshCore-` + +### Message Format +Messages are transmitted as binary frames using a custom protocol optimized for LoRa transmission. See `meshcore_protocol.dart` for frame structure definitions. + +## Configuration + +### App Settings +- **Theme**: System default, light, or dark mode +- **Notifications**: Configurable for messages, channels, and node advertisements +- **Battery Chemistry**: Support for NMC, LiFePO4, and LiPo battery types +- **Message Retry**: Automatic retry with configurable path clearing + +### Device Settings +- **Radio Power**: Transmit power adjustment (10-30 dBm) +- **Frequency**: LoRa frequency configuration +- **Bandwidth**: Channel bandwidth selection +- **Spreading Factor**: Range vs. speed trade-off +- **Network ID**: Mesh network identifier + +## Contributing + +This is an open-source project. Contributions are welcome! + +### Development Guidelines +- Follow the Flutter style guide +- Use Material 3 design components +- Write clear commit messages +- Test on both Android and iOS before submitting PRs + +### Code Style +- Prefer `StatelessWidget` with `Consumer` for reactive UI +- Use `const` constructors where possible +- Keep functions small and focused +- Avoid premature abstractions + +## License + +[Add your license information here] + +## Support + +For issues, questions, or feature requests, please open an issue on GitHub: +https://github.com/zjs81/meshcore-open/issues + +## Acknowledgments + +- Built with [Flutter](https://flutter.dev/) +- Map tiles from [OpenStreetMap](https://www.openstreetmap.org/) +- Voice codec support via [Codec2](https://github.com/drowe67/codec2)