From aa00a863c3ee2c84709388eb11e7aaae7c41ba19 Mon Sep 17 00:00:00 2001 From: zjs81 Date: Sun, 27 Sep 2026 13:12:23 -0700 Subject: [PATCH] Refresh documentation and update Dutch translation Documentation: - Correct web transport support: USB via Web Serial in Chrome only; no BLE or TCP in the browser. - Fix region scope semantics, routing modes (Auto/Flood/Manual), the 156-byte DM limit, repeater CLI framing, the guessed-location algorithm, radio stats contents and settings labels. - Add regions, image messages, radio statistics and troubleshooting guides. - Restore coding conventions, localization workflow, storage scoping and transport entry points to CLAUDE.md/AGENTS.md; align build/CI commands. - Replace the obsolete docs/BLE_PROTOCOL.md with a pointer to the maintained protocol reference. Dutch (nl): - Translate the 79 missing strings and correct existing mistranslations, typos and grammar (e.g. "Uitzoomen", "Handmatig", "Slowaaks", frequency range 150-2500 MHz). - Use consistent terminology and informal "je" throughout; keep mesh terms such as repeater, node, flood, hop and advert in English. Fixes #538 --- AGENTS.md | 28 +- CLAUDE.md | 361 +---- CONTRIBUTING.md | 15 +- README.md | 102 +- TESTFLIGHT_GUIDE.md | 283 +--- docs/BLE_PROTOCOL.md | 1302 +---------------- docs/PRIVACY_POLICY.md | 27 +- documentation/README.md | 29 +- documentation/additional-features.md | 26 +- documentation/ble-protocol.md | 45 +- documentation/channels.md | 12 +- documentation/chat-and-messaging.md | 7 +- documentation/contacts.md | 4 + documentation/image-messages.md | 40 + documentation/map-and-location.md | 22 +- documentation/navigation.md | 8 +- documentation/notifications.md | 4 + documentation/radio-statistics.md | 21 + documentation/regions.md | 39 + documentation/repeater-management.md | 4 + documentation/routing-paths.md | 85 +- documentation/settings.md | 29 +- documentation/troubleshooting.md | 29 + .../LaunchImage.imageset/README.md | 4 +- lib/l10n/app_localizations_nl.dart | 1234 ++++++++-------- lib/l10n/app_nl.arb | 1115 +++++++------- tools/aeic/README.md | 50 +- untranslated.json | 82 -- 28 files changed, 1774 insertions(+), 3233 deletions(-) create mode 100644 documentation/image-messages.md create mode 100644 documentation/radio-statistics.md create mode 100644 documentation/regions.md create mode 100644 documentation/troubleshooting.md diff --git a/AGENTS.md b/AGENTS.md index 273bb966..df569d30 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -6,29 +6,37 @@ ## BLE Frames & Protocol Notes - Nordic UART Service (NUS) UUIDs: Service `6e400001-b5a3-f393-e0a9-e50e24dcca9e`, RX `6e400002-b5a3-f393-e0a9-e50e24dcca9e`, TX `6e400003-b5a3-f393-e0a9-e50e24dcca9e`. -- Discovery: scans for device names matching known prefixes and filters by `platformName`/`advertisementData.advName`. +- Discovery: scans for the Nordic UART Service UUID; known name prefixes are reference values, not filters. - Frames are capped at `maxFrameSize = 172` bytes; byte 0 is the command/response/push code. I/O is `MeshCoreConnector.sendFrame` and `MeshCoreConnector.receivedFrames`. -- Command codes (to device): `cmdAppStart`=1, `cmdSendTxtMsg`=2, `cmdSendChannelTxtMsg`=3, `cmdGetContacts`=4, `cmdGetDeviceTime`=5, `cmdSetDeviceTime`=6, `cmdSendSelfAdvert`=7, `cmdSetAdvertName`=8, `cmdAddUpdateContact`=9, `cmdSyncNextMessage`=10, `cmdSetRadioParams`=11, `cmdSetRadioTxPower`=12, `cmdResetPath`=13, `cmdSetAdvertLatLon`=14, `cmdRemoveContact`=15, `cmdShareContact`=16, `cmdExportContact`=17, `cmdImportContact`=18, `cmdReboot`=19, `cmdSendLogin`=26, `cmdGetChannel`=31, `cmdSetChannel`=32, `cmdGetRadioSettings`=57. -- Response codes (from device): `respCodeOk`=0, `respCodeErr`=1, `respCodeContactsStart`=2, `respCodeContact`=3, `respCodeEndOfContacts`=4, `respCodeSelfInfo`=5, `respCodeSent`=6, `respCodeContactMsgRecv`=7, `respCodeChannelMsgRecv`=8, `respCodeCurrTime`=9, `respCodeNoMoreMessages`=10, `respCodeContactMsgRecvV3`=16, `respCodeChannelMsgRecvV3`=17, `respCodeChannelInfo`=18, `respCodeRadioSettings`=25. +- Command codes (to device): `cmdAppStart`=1, `cmdSendTxtMsg`=2, `cmdSendChannelTxtMsg`=3, `cmdGetContacts`=4, `cmdGetDeviceTime`=5, `cmdSetDeviceTime`=6, `cmdSendSelfAdvert`=7, `cmdSetAdvertName`=8, `cmdAddUpdateContact`=9, `cmdSyncNextMessage`=10, `cmdSetRadioParams`=11, `cmdSetRadioTxPower`=12, `cmdResetPath`=13, `cmdSetAdvertLatLon`=14, `cmdRemoveContact`=15, `cmdShareContact`=16, `cmdExportContact`=17, `cmdImportContact`=18, `cmdReboot`=19, `cmdSendLogin`=26, `cmdGetChannel`=31, `cmdSetChannel`=32, `cmdGetStats`=56, `cmdSendAnonReq`=57, `cmdSetAutoAddConfig`=58, `cmdGetAutoAddConfig`=59, `cmdSetPathHashMode`=61, `cmdSendChannelData`=62. +- Response codes (from device): `respCodeOk`=0, `respCodeErr`=1, `respCodeContactsStart`=2, `respCodeContact`=3, `respCodeEndOfContacts`=4, `respCodeSelfInfo`=5, `respCodeSent`=6, `respCodeContactMsgRecv`=7, `respCodeChannelMsgRecv`=8, `respCodeCurrTime`=9, `respCodeNoMoreMessages`=10, `respCodeContactMsgRecvV3`=16, `respCodeChannelMsgRecvV3`=17, `respCodeChannelInfo`=18, `respCodeStats`=24, `respCodeAutoAddConfig`=25, `respCodeChannelDataRecv`=27. - Push codes (async): `pushCodeAdvert`=0x80, `pushCodePathUpdated`=0x81, `pushCodeSendConfirmed`=0x82, `pushCodeMsgWaiting`=0x83, `pushCodeLoginSuccess`=0x85, `pushCodeLoginFail`=0x86, `pushCodeLogRxData`=0x88, `pushCodeNewAdvert`=0x8A. - Device info: `cmdAppStart` triggers `respCodeSelfInfo` with tx power, pubkey, lat/lon, telemetry flags, radio params, and node name (see offsets in `lib/connector/meshcore_connector.dart`). -- Radio/time helpers: `cmdGetRadioSettings` → `respCodeRadioSettings`; `cmdGetDeviceTime` → `respCodeCurrTime`; `cmdSetDeviceTime` updates device time. -- Reboot: the UI sends `sendCliCommand('reboot')` (the raw `cmdReboot` code exists but no frame builder is wired in yet). +- Radio/time helpers: radio settings come from self-info; companion stats use `cmdGetStats` → `respCodeStats`; `cmdGetDeviceTime` → `respCodeCurrTime`; `cmdSetDeviceTime` updates device time. +- Reboot: companion Settings calls `rebootDevice()` → `buildRebootFrame()`; remote repeater management uses CLI `reboot`. - Companion radio format: `cmdSendTxtMsg` expects `[cmd][txt_type][attempt][timestamp x4][pub_key_prefix x6][text...]` (no flags/full pubkey). CLI commands use `txtTypeCliData` in the same format, and the app maps `forceFlood` to attempt `3` when sending. - Group text packets (`PAYLOAD_TYPE_GRP_TXT`): payload is `[channel_hash (1)][MAC (2)][encrypted data...]`. Decrypted data layout is `[timestamp x4][txt_type][text...]` where text is `"sender: message"` (see MeshCore `BaseChatMesh::sendGroupMessage`). Sender identity is not in the payload; use `PUSH_CODE_LOG_RX_DATA` raw packet path bytes for origin hash when available. -- Identity hash: `PATH_HASH_SIZE` is 1 byte; it is the prefix of the public key (see `Identity::copyHashTo`). Flooded packets append this hash to the path as they traverse hops. Self-identification via log data should compare sender name and presence of self pubkey prefix within the path bytes. +- Routing hashes are public-key prefixes. Firmware negotiation currently supports 1–3 bytes per hop; packed path metadata must be decoded before counting or reversing hops. Use per-path hash width, not a fixed one-byte stride. See [routing paths](documentation/routing-paths.md). +- Regions: channel messages retain their send region; incoming regions are resolved from raw transport-flood codes against locally known names. Replies use a known original region by default, with an opt-out chip. See [regions](documentation/regions.md). +- Images: channel GRP_DATA framing is defined in `lib/services/image_chunk_transport.dart`. Native codec/model requirements are documented in [image messages](documentation/image-messages.md). ## Build, Test, and Development Commands -- `~/flutter/bin/flutter pub get` installs dependencies (or `flutter pub get` if Flutter is on PATH). -- `~/flutter/bin/flutter run` launches the app; `~/flutter/bin/flutter build apk|ios` produces release builds. -- `~/flutter/bin/flutter analyze` and `~/flutter/bin/flutter test` run linting and tests. +- Commands assume Flutter/Dart on PATH (or use your SDK's absolute path); see [CLAUDE.md](CLAUDE.md) for the full list. +- `flutter pub get` installs dependencies; `flutter run` launches the app; `flutter build apk --release` / `flutter build ios --release` produce release builds. +- CI checks: `dart format --output=none --set-exit-if-changed .`, `flutter analyze --fatal-infos --fatal-warnings`, and `flutter test`. ## Coding Style & Naming Conventions - Follow `flutter_lints`, use `lowerCamelCase`/`UpperCamelCase`/`snake_case`, prefer `StatelessWidget` + `Consumer`, and use `const` constructors. -- Material widgets only; keep screens simple, handle disconnects by returning to the scanner, and avoid premature abstractions. +- Material widgets only (no Cupertino); center app bar titles (`centerTitle: true`); prefix private members with `_`. +- Keep screens simple, handle disconnects by returning to the scanner, and avoid premature abstractions (don't add a helper until it is needed in 3+ places). +- Avoid unnecessary comments, feature flags, and backwards-compatibility shims. ## Testing Guidelines - Tests use `flutter_test`; add `*_test.dart` under `test/` and run `flutter test` before UI/protocol changes. ## Commit & Pull Request Guidelines - Keep commit subjects short and action-focused; PRs should describe behavior changes, link issues, include screenshots for UI changes, and call out BLE protocol changes explicitly. + +## Documentation maintenance + +Keep user instructions in `documentation/` and use [ble-protocol.md](documentation/ble-protocol.md) as the canonical protocol reference. Update affected guides, feature limitations, and screenshots when changing user-facing behavior. Read [CONTRIBUTING.md](CONTRIBUTING.md) for branch and review requirements. diff --git a/CLAUDE.md b/CLAUDE.md index 6b706653..73509451 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,337 +1,64 @@ -# MeshCore Open - Flutter Client +# MeshCore Open — development guide -Open-source Flutter client for MeshCore LoRa mesh networking devices. Connects to MeshCore-compatible radios over **BLE, TCP, or USB serial** and provides direct/channel chat, contact and channel management, on-map node tracking, repeater administration, and on-device message translation. +MeshCore Open is a Flutter client for MeshCore radios over BLE, USB serial, or TCP. It supports direct/channel messaging, communities, region-scoped floods, channel image messages, maps, repeater administration, and optional on-device translation. -## Build Commands +Read [AGENTS.md](AGENTS.md) for repository rules and [CONTRIBUTING.md](CONTRIBUTING.md) for contribution workflow. Target `dev` and discuss changes before submitting a PR. + +## Commands + +Use Flutter and Dart on PATH (or your SDK’s absolute path): ```bash -# Install dependencies -~/flutter/bin/flutter pub get - -# Run in debug mode -~/flutter/bin/flutter run - -# Build Android APK -~/flutter/bin/flutter build apk - -# Build iOS -~/flutter/bin/flutter build ios - -# Build versioned web release (uses build_pipe) -~/flutter/bin/dart run build_pipe - -# Run static analysis -~/flutter/bin/flutter analyze - -# Run tests -~/flutter/bin/flutter test +flutter pub get +flutter run +dart format --output=none --set-exit-if-changed . +flutter analyze --fatal-infos --fatal-warnings +flutter test +flutter build apk --release +flutter build ios --release +flutter build web --release ``` -## Project Structure +The versioned web build uses `dart run build_pipe:build` (also `bun run build`). Web deployment pins Flutter 3.41.2; other CI jobs track stable. Read `pubspec.yaml` for current app version and dependencies rather than copying them into this guide. -``` -lib/ -├── main.dart # Entry point: MultiProvider wiring, locale + theme, initial route -├── connector/ # Unified BLE/TCP/USB transport layer -│ ├── meshcore_connector.dart # Central state holder + ChangeNotifier (all transports) -│ ├── meshcore_connector_tcp.dart # TCP transport helper -│ ├── meshcore_connector_usb.dart # USB serial transport helper -│ ├── meshcore_protocol.dart # Frame size + version constants -│ └── meshcore_uuids.dart # Nordic UART UUIDs + scan name prefixes -├── models/ # Plain data classes (Contact, Channel, Message, Community, …) -├── services/ # ChangeNotifier services + IO services (retry, translation, ML, …) -├── storage/ # SharedPreferences-backed stores, scoped per device key -├── helpers/ # Pure utilities (Smaz compression, GIF parsing, scroll helpers, path hop resolution) -├── utils/ # Platform / IO / UX utilities (logger, GPX export, dialogs) -├── theme/ # MeshPalette (defined, not yet wired in main.dart) -├── l10n/ # ARB localization for 18 locales -├── icons/ # Custom icon widgets -├── widgets/ # Reusable widgets (AppBar, BatteryUi, QR, jump-to-bottom, …) -└── screens/ # ~26 screens — see Screens section below -``` +## Architecture and important files -## Screens - -All screens are fully implemented (no remaining placeholders). - -### Connection / Scanning -| Screen | Purpose | +| Area | Source | |---|---| -| `scanner_screen.dart` | BLE device scan and connect — main entry point | -| `tcp_screen.dart` | Connect to a MeshCore device over TCP/IP | -| `usb_screen.dart` | Connect to a MeshCore device over USB serial | -| `discovery_screen.dart` | Browse all discovered (non-contact) mesh nodes | -| `chrome_required_screen.dart` | Web gate for non-Chrome browsers (BLE unavailable) | +| Entry point, providers, themes and locale | `lib/main.dart` | +| Shared BLE/TCP/USB state and frame dispatch | `lib/connector/meshcore_connector.dart` | +| Protocol constants and builders | `lib/connector/meshcore_protocol.dart` | +| NUS UUIDs; reference device name prefixes | `lib/connector/meshcore_uuids.dart` | +| Serial marker/length framing | `lib/services/usb_serial_frame_codec.dart` | +| ACK tracking and retry scheduling | `lib/services/message_retry_service.dart` | +| Route scoring/history | `lib/services/path_history_service.dart` | +| Preferences and JSON stores | `lib/storage/` | +| Region list and channel/default assignments | `lib/storage/region_store.dart`, `lib/storage/channel_region_store.dart` | +| Translation models/inference | `lib/services/translation_service.dart` | +| Image models/inference and GRP_DATA chunks | `lib/services/image_codec_service.dart`, `lib/services/image_chunk_transport.dart` | +| Image reassembly and file persistence | `lib/services/received_image_store.dart`, `lib/services/received_image_blob_store_io.dart` | +| Material themes | `lib/theme/mesh_theme.dart` | +| Screens and reusable UI | `lib/screens/`, `lib/widgets/` | +| Localization | `lib/l10n/` (18 locales) | -### Chat / Messaging -| Screen | Purpose | -|---|---| -| `chat_screen.dart` | Direct (private) messaging with a contact | -| `channel_chat_screen.dart` | Group messaging inside a named channel | -| `channels_screen.dart` | List and manage channels (add/edit/delete) | -| `channel_message_path_screen.dart` | Hop-by-hop route a channel message took, with map overlay | +`Provider`/`ChangeNotifier` drives UI state. `main.dart` wires `MeshTheme.light()` and `MeshTheme.dark()` and uses the saved theme preference. Its `MultiProvider` exposes `MeshCoreConnector`, `MessageRetryService`, `PathHistoryService`, `AppSettingsService`, `BleDebugLogService`, `AppDebugLogService`, `ChatTextScaleService`, `TranslationService`, `UiViewStateService`, `StorageService` (plain `Provider`), `MapTileCacheService`, `TimeoutPredictionService`, `ImageCodecService`, and `ReceivedImageStore`; screens read them with `Consumer`, `context.watch()`, or `context.read()`. -### Contacts / Neighbors -| Screen | Purpose | -|---|---| -| `contacts_screen.dart` | Full contacts list with previews and management | -| `neighbors_screen.dart` | Nodes directly heard by the connected radio (one-hop) | +Most JSON stores scope keys by the first 10 hex chars of the connected device's public key, so per-radio data stays isolated; some preferences, including the saved region-name list, are global. Model bundles, received images, and caches use files. -### Repeater Management -| Screen | Purpose | -|---|---| -| `repeater_hub_screen.dart` | Top-level repeater hub; navigates to sub-screens | -| `repeater_status_screen.dart` | Live status of a managed repeater node | -| `repeater_cli_screen.dart` | Raw command-line interface to a repeater | -| `repeater_settings_screen.dart` | Full radio/node settings editor for a repeater | +## Localization -### Map / Location -| Screen | Purpose | -|---|---| -| `map_screen.dart` | Main map view of contacts/nodes with live GPS positions | -| `line_of_sight_map_screen.dart` | Terrain LOS analysis between configurable endpoints | -| `path_trace_map.dart` | Animates the hop path a direct message traveled | -| `map_cache_screen.dart` | Download/clear offline map tile cache | -| `community_qr_scanner_screen.dart` | Scan QR to join a mesh community/channel | +Use `context.l10n` (from `lib/l10n/l10n.dart`) for all user-facing strings. `lib/l10n/app_en.arb` is the template; add new keys there first. Keys missing from other locales are written to `untranslated.json` (configured in `l10n.yaml`). Contact-type names live in `lib/l10n/contact_localization.dart`. -### Settings / Debug / Diagnostics -| Screen | Purpose | -|---|---| -| `settings_screen.dart` | Connected device settings: radio params, identity, GPS | -| `app_settings_screen.dart` | App preferences: theme, units, map source, notifications | -| `app_debug_log_screen.dart` | In-app log viewer (app-layer messages) | -| `ble_debug_log_screen.dart` | In-app log viewer (raw BLE frame traffic) | -| `companion_radio_stats_screen.dart` | RF stats (RSSI, SNR, packet counts) for paired radio | -| `telemetry_screen.dart` | Battery / sensor / environmental telemetry for a contact | +## Transport and platform notes -## Architecture +BLE scans by NUS service UUID, not advertised-name prefix. USB uses `[marker][length uint16 LE][payload]`, not COBS. TCP uses the same packet framing. See the [protocol reference](documentation/ble-protocol.md). -### State Management +Web supports USB via Web Serial in Chrome only, over a secure origin. BLE is not available in the browser (the scanner shows a snackbar instead of scanning), and TCP is not supported on web (`tcp_transport_service_web.dart` always throws). Translation and image inference have no web backend. -`Provider` with `ChangeNotifier`. `main.dart` wires a `MultiProvider` with the following: +Transport entry points on `MeshCoreConnector`: `connectTcp(host:, port:)`, `connectUsb(portName:, baudRate: 115200)`, and `listUsbPorts()`. On Linux, `lib/services/linux_ble_pairing_service.dart` falls back to `bluetoothctl` when BlueZ pairing prompts fail. -| Provider | Role | -|---|---| -| `MeshCoreConnector` | Active transport (BLE/TCP/USB), connection state, frame I/O | -| `MessageRetryService` | ACK tracking and retry scheduling with backoff | -| `PathHistoryService` | Per-contact routing history (LRU cache, 50 contacts) | -| `AppSettingsService` | App preferences (theme, units, locale, notifications) | -| `BleDebugLogService` | Raw BLE frame log buffer | -| `AppDebugLogService` | Structured app log buffer | -| `ChatTextScaleService` | Pinch-to-zoom text scale for chat screens | -| `TranslationService` | On-device LLM translation (llamadart) | -| `UiViewStateService` | Contacts/channels sort/filter/search state | -| `TimeoutPredictionService` | ML linear regression for ACK timeout prediction | -| `StorageService` | Path history + delivery observation persistence | -| `MapTileCacheService` | OSM tile pre-cache | +Android builds currently include ARM64 only and use Java 17. iOS targets 16.4. Read platform build files for current constraints; hardware testing remains necessary for transport changes. -Screens consume these via `Consumer` (or `context.watch()` / `context.read()`) for reactive UI. +## Documentation -### Storage / Persistence - -All stores in `lib/storage/` use `PrefsManager` (a `SharedPreferences` singleton initialized in `main()`). Most stores **scope keys by the first 10 hex chars of the connected device's public key**, so per-radio data is isolated. - -| Store | Persists | -|---|---| -| `message_store`, `channel_message_store` | Direct + channel messages | -| `contact_store`, `contact_discovery_store` | Known + discovered contacts | -| `channel_store`, `channel_order_store`, `channel_settings_store` | Channels, display order, per-channel Smaz toggle | -| `community_store` | Communities (32-byte shared secrets) | -| `contact_group_store`, `contact_settings_store` | Groups, per-contact Smaz toggle | -| `unread_store` | Per-contact unread counts (debounced writes) | - -GGUF translation models are stored as files (not SharedPreferences) via `translation_file_store`. - -### Theming -- Material 3 design (`useMaterial3: true`) -- System-based dark/light mode (`ThemeMode.system`) -- Blue color scheme seed -- `lib/theme/mesh_theme.dart` defines a warm-dark `MeshPalette` (phosphor-green accents) but is **not currently wired** in `main.dart` — available for a future redesign - -### Localization - -18 locales supported via Flutter's standard ARB pipeline (`lib/l10n/`): en, de, es, fr, it, pt, ru, uk, bg, hu, ja, ko, nl, pl, sk, sl, sv, zh. Language override comes from `AppSettingsService.settings.languageOverride`. Use the `context.l10n` extension (`lib/l10n/l10n.dart`) for translated strings; contact-type names live in `contact_localization.dart`. - -## Transports - -`MeshCoreConnector` unifies all three transports under one `ChangeNotifier`. There is **no shared base class** — selection is via the `MeshCoreTransportType { bluetooth, usb, tcp }` enum, and BLE/TCP/USB share the same connection-state enum, send/receive API, and frame protocol. - -### Connection State -```dart -enum MeshCoreConnectionState { - disconnected, - scanning, - connecting, - connected, - disconnecting, -} -``` - -### Frame I/O (all transports) -- **Send**: `MeshCoreConnector.sendFrame(Uint8List data, {String? channelSendQueueId, bool expectsGenericAck})` -- **Receive**: `Stream get receivedFrames` -- **Protocol constants** (`meshcore_protocol.dart`): `maxFrameSize = 172`, `maxTextPayloadBytes = 160`, `appProtocolVersion = 4` - -### BLE — Nordic UART Service (NUS) -- **Service UUID**: `6e400001-b5a3-f393-e0a9-e50e24dcca9e` -- **RX Characteristic** (write to device): `6e400002-b5a3-f393-e0a9-e50e24dcca9e` -- **TX Characteristic** (notify from device): `6e400003-b5a3-f393-e0a9-e50e24dcca9e` -- **Discovery**: scans for devices whose name starts with `MeshCore-`, `Whisper-`, `WisCore-`, `Seeed`, `Lilygo`, `HT-`, or `LowMesh_MC_` (filters on both `platformName` and `advertisementData.advName`) -- **Linux**: `linux_ble_pairing_service.dart` falls back to `bluetoothctl` when BlueZ agent prompts fail - -### TCP -- Manual host/port entry, persisted via `AppSettingsService` (`tcpServerAddress`, `tcpServerPort`) -- UI hint: `192.168.40.10` / port `5000` -- Disabled on web (`PlatformInfo.isWeb`) -- API: `MeshCoreConnector.connectTcp(host: ..., port: ...)` - -### USB Serial (flserial) -- Default baud rate: `115200` -- Port enumeration: `MeshCoreConnector.listUsbPorts()` -- COBS-framed packets via `usb_serial_frame_codec.dart` -- macOS device-name resolution via `ioreg` (`utils/macos_usb_device_names.dart`) -- API: `MeshCoreConnector.connectUsb(portName: ..., baudRate: 115200)` - -## Dependencies - -App version: `9.5.0+13` — Dart SDK constraint: `^3.9.2` - -**Connectivity** - -| Package | Version | Purpose | -|---------|---------|---------| -| flutter_blue_plus | ^2.1.0 | BLE scanning, connecting, and UART data transfer | -| flutter_blue_plus_platform_interface | ^9.0.2 | Platform-interface layer required by flutter_blue_plus | -| flserial | git (MeshEnvy fork) | USB serial transport for wired device connections (TODO: upstream pending) | - -**State / Storage** - -| Package | Version | Purpose | -|---------|---------|---------| -| provider | ^6.1.5+1 | ChangeNotifier-based state management across screens | -| shared_preferences | ^2.2.2 | Persistent key-value storage for user settings | -| path_provider | ^2.1.5 | Locates platform-appropriate directories for file I/O | - -**Crypto** - -| Package | Version | Purpose | -|---------|---------|---------| -| crypto | ^3.0.3 | SHA/HMAC hashing used in message authentication | -| pointycastle | ^4.0.0 | AES encryption/decryption for channel and direct messages | -| uuid | ^4.3.3 | Generates UUIDs for message and contact identity | - -**Maps & Location** - -| Package | Version | Purpose | -|---------|---------|---------| -| flutter_map | ^8.2.2 | Interactive tile map for node positions and path traces | -| latlong2 | ^0.9.1 | LatLng coordinate type used throughout map and GPS code | -| gpx | ^2.3.0 | Export node paths as GPX track files | - -**UI** - -| Package | Version | Purpose | -|---------|---------|---------| -| material_symbols_icons | ^4.2928.1 | Extended Material Symbols icon set (line-of-sight, etc.) | -| flutter_svg | ^2.0.10+1 | Renders SVG assets (custom icons such as LoS indicator) | -| cached_network_image | ^3.4.1 | Caches map tile images downloaded over the network | -| flutter_cache_manager | ^3.4.1 | Underlying cache manager used by cached_network_image | -| flutter_linkify | ^6.0.0 | Auto-detects and makes URLs tappable in chat messages | -| mobile_scanner | ^7.1.4 | QR/barcode scanning for contact and channel import | -| qr_flutter | ^4.1.0 | Generates QR codes for sharing contacts and channels | -| cupertino_icons | ^1.0.8 | iOS-style icon font (bundled for completeness) | -| characters | ^1.4.0 | Unicode-aware string operations for message text handling | - -**Notifications / Background** - -| Package | Version | Purpose | -|---------|---------|---------| -| flutter_local_notifications | ^22.0.0 | Shows local push notifications for incoming messages | -| flutter_foreground_task | ^9.2.0 | Keeps the app alive in background to maintain BLE/USB connection | - -**ML / AI** - -| Package | Version | Purpose | -|---------|---------|---------| -| ml_algo | ^16.0.0 | OLS regression used in `timeout_prediction_service.dart` to predict message ACK timeouts | -| ml_dataframe | ^1.0.0 | DataFrame input format required by ml_algo | -| llamadart | ^0.8.0 | On-device LLM inference used in `translation_service.dart` for message translation | -| flutter_langdetect | ^0.0.1 | Detects a message's source language in `translation_service.dart` before translating | - -**Misc** - -| Package | Version | Purpose | -|---------|---------|---------| -| http | ^1.2.0 | Fetches tile URLs and any remote API calls | -| url_launcher | ^6.3.0 | Opens URLs in the system browser from linkified chat text | -| share_plus | ^13.1.0 | Shares files (e.g. exported GPX tracks) via the system share sheet | -| package_info_plus | ^10.1.0 | Reads app version/build number displayed in settings | -| web | ^1.1.1 | Web-platform APIs for USB serial and browser detection on Flutter Web | -| intl | any | Internationalization and locale formatting (required by flutter_localizations) | -| build_pipe | ^0.3.1 | CI/CD build pipeline configuration (web release builds with versioned assets) | - -## Platform Configuration - -### Android (`android/app/src/main/AndroidManifest.xml`) -- `INTERNET` (map tiles, translation model downloads) -- `BLUETOOTH`, `BLUETOOTH_ADMIN` (API ≤ 30) -- `BLUETOOTH_SCAN` (with `neverForLocation`), `BLUETOOTH_CONNECT`, `BLUETOOTH_ADVERTISE` (API 31+) -- `ACCESS_FINE_LOCATION`, `ACCESS_COARSE_LOCATION` (BLE scanning on API ≤ 30) -- `POST_NOTIFICATIONS` (API 33+) -- `FOREGROUND_SERVICE`, `FOREGROUND_SERVICE_CONNECTED_DEVICE` (background BLE/USB connection) -- `WAKE_LOCK` -- `CAMERA` (QR scanning, declared as optional feature) -- USB host hardware feature (optional) - -`flutter_foreground_task` registers a `ForegroundService` with `foregroundServiceType="connectedDevice"` and `stopWithTask="false"`. - -**Build config (`android/app/build.gradle.kts`)**: `applicationId = com.meshcore.meshcore_open`, NDK `29.0.14206865`, Java 8 core-library desugaring (`desugar_jdk_libs:2.1.4`), release signing via `key.properties` (debug fallback). - -### iOS (`ios/Runner/Info.plist`) -- `NSBluetoothAlwaysUsageDescription`, `NSBluetoothPeripheralUsageDescription` -- `NSCameraUsageDescription` (QR scanning to join communities) -- Background modes: `bluetooth-central` -- `LSApplicationQueriesSchemes`: `http`, `https` - -### Web (`web/`) -PWA scaffold present but boilerplate (`manifest.json` and `index.html` are unmodified Flutter defaults). BLE is unsupported in browsers; TCP and Web Serial USB may work in Chrome only. `ChromeRequiredScreen` gates non-Chrome web users. Versioned releases are produced via `build_pipe` (`?v=` cache busting, no service worker). - -### Desktop -`linux/`, `windows/`, and `macos/` directories are present as Flutter scaffolds. No app-specific native config has been added; BLE on desktop has not been validated. - -## Coding Conventions - -### Code Philosophy -- **Minimal**: Only write code that is necessary. Avoid over-engineering. -- **Organized**: Keep related code together. One responsibility per file. -- **Maintainable**: Favor readability over cleverness. Simple is better. - -### Style -- Use `StatelessWidget` with `Consumer` for state-dependent UI -- Use `const` constructors where possible -- Prefix private methods/fields with `_` -- Center app bar titles (`centerTitle: true`) -- **Material widgets only** - no Cupertino or custom widgets -- Handle disconnection gracefully (auto-navigate back to scanner) - -### Avoid -- Premature abstractions - don't create helpers until needed in 3+ places -- Unnecessary comments - code should be self-explanatory -- Feature flags or backwards-compatibility shims -- Over-engineered error handling for impossible scenarios - -## Key Files - -| File | Purpose | -|------|---------| -| `lib/main.dart` | App configuration, MultiProvider setup, theme, locale, initial route | -| `lib/connector/meshcore_connector.dart` | Unified BLE/TCP/USB transport state holder | -| `lib/connector/meshcore_protocol.dart` | Frame size limits and protocol version | -| `lib/connector/meshcore_uuids.dart` | NUS UUIDs and BLE scan name prefixes | -| `lib/services/app_settings_service.dart` | App-wide settings (`AppSettings` JSON in SharedPreferences) | -| `lib/services/storage_service.dart` | Path history + delivery observation persistence | -| `lib/services/message_retry_service.dart` | ACK tracking + retry scheduling | -| `lib/services/translation_service.dart` | On-device LLM translation (llamadart) | -| `lib/storage/prefs_manager.dart` | SharedPreferences singleton initialized in `main()` | -| `lib/screens/scanner_screen.dart` | Home screen — BLE scan and connect | -| `pubspec.yaml` | Dependencies and project metadata (current version `9.5.0+13`) | +Use the [feature index](documentation/README.md), [regions](documentation/regions.md), [image messages](documentation/image-messages.md), and [routing reference](documentation/routing-paths.md). Keep protocol details in the canonical reference rather than maintaining competing command tables. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index ac727bad..b83b86e3 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -47,14 +47,13 @@ branch be sure to start on latest `dev`. * Ensure the PR description clearly describes the problem and solution. Include the relevant issue number if applicable. -* The PR should contain **one commit** only, the commit message should have a -clear title followed by a new line and then brief description if needed. PR with -multiple commits will be squashed into one before merging if required. See +* Prefer **one final commit** per PR. The commit message should have a +clear title followed by a new line and then brief description if needed. If review requires follow-up commits, maintainers may squash them before merging. See [Git Mastery](https://git-mastery.org/lessons/commitMessage/) for more information on good commit messages. -* **Before committing changes** on your branch, be sure to run both -`dart format .` and `flutter analyze`. The continuous development checks will +* **Before committing changes** on your branch, be sure to run +`dart format .`, `flutter analyze --fatal-infos --fatal-warnings`, and `flutter test`. CI also checks formatting with `dart format --output=none --set-exit-if-changed .`. The continuous development checks will fail if issues here are not addressed before hand. ## AI-use @@ -69,3 +68,9 @@ There are some limits to acceptable use however. Generally: for the patch, bug fix, etc. * The contributor should have a good understanding of what the code does and how the application works in order to effectively be able to manage the agent. + +## Documentation and validation + +Update the relevant [user guides](documentation/README.md) when changing features, defaults, navigation, firmware requirements, or platform limitations. Add screenshots for visible UI changes and keep localization keys consistent across supported locales. Include protocol changes explicitly in the PR description. + +Test on the platforms and hardware affected by the change. State what you tested and any untested platforms in the PR; automated builds do not prove BLE/USB/radio interoperability. Documentation-only changes need link and content checks, not a Flutter build. diff --git a/README.md b/README.md index 42ad8800..955ab6a6 100644 --- a/README.md +++ b/README.md @@ -4,25 +4,35 @@ 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. +MeshCore Open is a cross-platform application for communicating with MeshCore LoRa mesh radios over Bluetooth Low Energy (BLE), USB serial, or TCP. The app enables long-range, off-grid communication through peer-to-peer messaging, public channels, and mesh networking capabilities. **Website:** [meshcoreopen.org](https://meshcoreopen.org/) - + Get it on Obtainium -The [web client](https://meshcoreopen.org/install/web/) runs in Chromium (Chrome, Edge, Brave) over Web Bluetooth or Web Serial. Firefox and Safari do not support those APIs. TCP on the web needs a websocket bridge. +The [web client](https://meshcoreopen.org/install/web/) runs in Chrome (and Chromium browsers that identify as Chrome, such as Edge or Brave) and connects over USB via Web Serial. BLE and TCP are not available in the browser. Firefox and Safari do not support Web Serial. + +## Install and first use + +Use the [installation website](https://meshcoreopen.org/) for available downloads, Obtainium, and the web client. Building from source is covered below. + +1. Use a MeshCore radio running companion firmware with the transport you intend to use. +2. Open the app, scan for BLE devices or select USB/TCP, and connect. +3. After synchronization, open a channel to broadcast or open Contacts to send a direct message. Peers need compatible radio settings; channels need the same PSK. + +See the [user documentation](documentation/README.md), [connection guide](documentation/scanner-and-connection.md), and [troubleshooting](documentation/troubleshooting.md). ## Screenshots - - - - - + + + + +

Contacts


Chat


Reactions


Map


Channels

Contact list

Contacts

Direct message conversation

Chat

Message reactions

Reactions

Mesh node map

Map

Channel list

Channels

@@ -31,7 +41,10 @@ The [web client](https://meshcoreopen.org/install/web/) runs in Chromium (Chrome ### Core Functionality - **Direct Messaging**: Private encrypted conversations with individual contacts -- **Public Channels**: Broadcast messages to channel subscribers on the mesh network +- **Channels**: Public, hashtag, private, and community channels +- **Mesh Images**: Send compressed images in channel chat with optional recovery packets ([guide](documentation/image-messages.md)) +- **Regions**: Scope channel floods and reply using a message’s known region ([guide](documentation/regions.md)) +- **Translation**: Optional on-device incoming and pre-send translation - **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 @@ -50,7 +63,7 @@ The [web client](https://meshcoreopen.org/install/web/) runs in Chromium (Chrome - **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 (with [StadiaMaps](https://stadiamaps.com/pricing/) Free Subscription API-Key) +- **Offline Maps**: Download map tiles for offline use in remote areas using a configured Stadia Maps source and API key; see [map setup](documentation/map-and-location.md) - **MGRS Coordinates**: Support for Military Grid Reference System coordinate format ### Device Management @@ -58,7 +71,6 @@ The [web client](https://meshcoreopen.org/install/web/) runs in Chromium (Chrome - **BLE, USB, TCP Connection**: Scan and connect to MeshCore devices via Bluetooth, USB or TCP - **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 @@ -71,25 +83,27 @@ The [web client](https://meshcoreopen.org/install/web/) runs in Chromium (Chrome ### Architecture -- **Framework**: Flutter 3.38.5 / Dart 3.10.4 +- **Framework**: Flutter (web deployment pins 3.41.2); Dart SDK constraint `^3.9.2` - **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 +- **Storage**: JSON in SharedPreferences for messages and contacts; files for models, images, and map caches - **Encryption**: End-to-end encryption for private messages using the MeshCore protocol ### Platform Support -| Feature | Android (API 21+) | iOS (12+) | Linux | Windows | macOS | Web | +| Feature | Android (ARM64) | iOS (16.4+) | Linux | Windows | macOS | Web | |--------------------|:-----------------:|:---------:|:-----:|:-------:|:-----:|:---------------------------------:| -| BLE companion | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | -| USB companion | ✅ | 🚧 | ✅ | ✅ | ✅ | ✅ | -| TCP companion | ✅ | 🚧 | ✅ | ✅ | ✅ | ❌
(requires websocket bridge) | +| BLE companion | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ | +| USB companion | ✅ | ❌ | ✅ | ✅ | ✅ | ✅
(Web Serial, Chrome) | +| TCP companion | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ | | Core Functionality | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | | Mesh Network | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | | Map & Location | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | | Device Management | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | | Repeater Hub | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +The matrix describes implemented functionality, not a guarantee that every feature has been tested on every device. Web device connections use Web Serial and require Chrome and a secure origin. Image inference and translation require native runtimes and are unavailable on web. Android APKs currently include only `arm64-v8a`; the minimum Android API follows the Flutter SDK used to build. + ### Dependencies | Package | Purpose | @@ -108,11 +122,11 @@ The [web client](https://meshcoreopen.org/install/web/) runs in Chromium (Chrome ### Prerequisites -- Flutter SDK 3.38.5 or later +- Flutter SDK; web deployment currently pins 3.41.2. The Dart SDK constraint is `^3.9.2` (see `pubspec.yaml`). - Android Studio / Xcode (for mobile development) - A MeshCore-compatible LoRa device -### Installation +### Build from source 1. **Clone the repository** @@ -165,7 +179,7 @@ lib/ ├── connector/ │ ├── meshcore_connector.dart # BLE communication & state management │ ├── meshcore_protocol.dart # Protocol definitions & frame parsing -│ └── meshcore_uuids.dart # Device names and IDs (add prefixes here!) +│ └── meshcore_uuids.dart # NUS UUIDs; reference name prefixes (not filters) ├── screens/ │ ├── scanner_screen.dart # Device scanning (home screen) │ ├── contacts_screen.dart # Contact list @@ -179,13 +193,13 @@ lib/ │ ├── message.dart # Message data structure │ └── channel.dart # Channel definitions ├── services/ -│ ├── notification_service.dart # Push notifications +│ ├── notification_service.dart # Local OS 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 + ├── contact_store.dart # Contact persistence └── unread_store.dart # Unread message tracking ``` @@ -199,53 +213,48 @@ lib/ ### Device Discovery -Devices are discovered by scanning for BLE advertisements with known MeshCore device name prefixes. These are currently: - - `MeshCore-` - - `Whisper-` - - `WisCore-` - - `HT-` - - `LowMesh_MC_` - - `NRF52` - -New device prefixes can be added in `lib/connector/meshcore_uuids.dart`. - +BLE scanning filters on the Nordic UART Service UUID, so devices with custom names can be found. Known name prefixes in `lib/connector/meshcore_uuids.dart` are reference values, not discovery filters. ### Message Format -Messages are transmitted as binary frames using a custom protocol optimized for LoRa transmission. See `meshcore_protocol.dart` for frame structure definitions. +Messages are transmitted as binary frames using a custom protocol optimized for LoRa transmission. See the [protocol reference](documentation/ble-protocol.md) for frame definitions. ## Configuration ### App Settings - **Theme**: System default, light, or dark mode -- **Language**: Use one of 15 languages (English, Chinese, French, Spanish, Portuguese, German, Dutch, Polish, Swedish, Italian, Slovak, Slovene, Bulgarian, Russian, Ukrainian) +- **Language**: Use one of 18 languages (English, Chinese, French, Spanish, Portuguese, German, Dutch, Polish, Swedish, Italian, Slovak, Slovenian, Bulgarian, Russian, Ukrainian, Hungarian, Japanese, Korean) - **Notifications**: Configurable for messages, channels, and node advertisements -- **Battery Chemistry**: Support for NMC, LiFePO4, and LiPo battery types +- **Battery Chemistry**: Support for NMC, LiFePO4, LiPo, and LiPo HV battery types - **Message Retry**: Automatic retry with configurable path clearing ### Device Settings -- **Radio Power**: Transmit power adjustment (10-30 dBm) +- **Radio Power**: Transmit power adjustment within the connected device’s supported range - **Frequency**: LoRa frequency configuration - **Bandwidth**: Channel bandwidth selection - **Spreading Factor**: Range vs. speed trade-off -- **Network ID**: Mesh network identifier +- **Flood Scope**: Region selection for channel floods ## Contributing -This is an open-source project. Contributions are welcome! +Read [CONTRIBUTING.md](CONTRIBUTING.md) before starting a contribution. Discuss changes in an issue first and base PRs on `dev`. -## SWHID and Archive badge -[![SWH](https://archive.softwareheritage.org/badge/origin/https://github.com/zjs81/meshcore-open/)](https://archive.softwareheritage.org/browse/origin/?origin_url=https://github.com/zjs81/meshcore-open) -[![SWH](https://archive.softwareheritage.org/badge/swh:1:dir:d37a80b06359730864150ad2aeadd46cce9abd55/)](https://archive.softwareheritage.org/swh:1:dir:d37a80b06359730864150ad2aeadd46cce9abd55;origin=https://github.com/zjs81/meshcore-open;visit=swh:1:snp:47656c4b55ab40a689ff8d2f045196725f05096b;anchor=swh:1:rev:0fe250230905fdd05dbedc0f546736990beacf53) +Run the checks used by CI: + +```bash +dart format --output=none --set-exit-if-changed . +flutter analyze --fatal-infos --fatal-warnings +flutter test +``` ### 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 +- Test on the platforms affected by your change before submitting PRs ### Code Style @@ -273,7 +282,16 @@ If you find MeshCore Open useful and would like to support development, you can Your support helps maintain and improve this open-source project! +## License + +MeshCore Open is available under the [MIT License](LICENSE). + ## Acknowledgments - Built with [Flutter](https://flutter.dev/) - Map tiles from [OpenStreetMap](https://www.openstreetmap.org/) + +## SWHID and Archive badge + +[![SWH](https://archive.softwareheritage.org/badge/origin/https://github.com/zjs81/meshcore-open/)](https://archive.softwareheritage.org/browse/origin/?origin_url=https://github.com/zjs81/meshcore-open) +[![SWH](https://archive.softwareheritage.org/badge/swh:1:dir:d37a80b06359730864150ad2aeadd46cce9abd55/)](https://archive.softwareheritage.org/swh:1:dir:d37a80b06359730864150ad2aeadd46cce9abd55;origin=https://github.com/zjs81/meshcore-open;visit=swh:1:snp:47656c4b55ab40a689ff8d2f045196725f05096b;anchor=swh:1:rev:0fe250230905fdd05dbedc0f546736990beacf53) diff --git a/TESTFLIGHT_GUIDE.md b/TESTFLIGHT_GUIDE.md index b092678c..1c65a15f 100644 --- a/TESTFLIGHT_GUIDE.md +++ b/TESTFLIGHT_GUIDE.md @@ -1,244 +1,85 @@ -# TestFlight and App Store Deployment Guide +# TestFlight and App Store Release Guide + +This guide describes the project’s release preparation. Apple’s UI, submission requirements, and tooling change; use the official links below for current requirements. ## Prerequisites -- [x] Apple Developer Account ($99/year) - [developer.apple.com](https://developer.apple.com) -- [x] Xcode installed -- [x] Apple Transporter app installed -- [x] App icons ready (1024x1024px) -- [x] Bundle ID configured: `com.monitormx.meshcoreopen` +- Access to the app’s Apple Developer team and App Store Connect record. +- macOS with Xcode and Flutter configured; confirm the environment with `flutter doctor`. +- CocoaPods installed and available on PATH. Avoid copying a machine-specific Ruby/gems path. +- Signing certificates/profiles or automatic signing configured for the correct team. +- Bundle ID `com.monitormx.meshcoreopen`, matching `ios/Runner.xcodeproj/project.pbxproj`. +- A device running iOS **16.4 or newer**, the project’s current deployment target. -## Step 1: Register Bundle Identifier +If an app record already exists, use it rather than registering a duplicate identifier or listing. -1. Go to [Apple Developer - Identifiers](https://developer.apple.com/account/resources/identifiers/list) -2. Click the **"+"** button -3. Select **"App IDs"** → Continue -4. Select **"App"** → Continue -5. Fill in: - - **Description**: Meshcore Open - - **Bundle ID**: Explicit - `com.monitormx.meshcoreopen` - - **Capabilities**: Leave defaults (or add as needed) -6. Click **Continue** → **Register** +## Prepare a release -## Step 2: Create App in App Store Connect +1. Start from the intended release commit and verify `pubspec.yaml` version/build number. Increment the build number for a new upload; use the intended release version rather than a sample value copied from this guide. +2. Run dependency installation and project checks: -1. Go to [App Store Connect](https://appstoreconnect.apple.com) -2. Sign in with your Apple ID -3. Click **"My Apps"** -4. Click the **"+"** button → **"New App"** -5. Fill in the form: - - **Platforms**: iOS - - **Name**: Meshcore Open - - **Primary Language**: English (U.S.) - - **Bundle ID**: Select `com.monitormx.meshcoreopen` from dropdown - - **SKU**: `meshcore-open-001` (or any unique identifier) - - **User Access**: Full Access -6. Click **"Create"** - -## Step 3: Build the IPA - -Run these commands from the project directory: - -```bash -# Add CocoaPods to PATH -export PATH="/opt/homebrew/lib/ruby/gems/4.0.0/bin:$PATH" - -# Clean previous builds -../flutter/bin/flutter clean - -# Build IPA for App Store -../flutter/bin/flutter build ipa -``` - -The IPA will be created at: `build/ios/ipa/meshcore_open.ipa` - -## Step 4: Upload to App Store Connect via Transporter - -1. **Open Apple Transporter** - - Launch from Applications folder - - Sign in with your Apple ID - -2. **Upload the IPA** - - Drag and drop `build/ios/ipa/meshcore_open.ipa` into Transporter - - Click **"Deliver"** - - Wait for upload to complete (usually 1-5 minutes) - -3. **Processing** - - Apple will process your build (10-30 minutes) - - You'll receive an email when processing is complete - -## Step 5: Configure App Store Connect Metadata - -### App Information -1. In App Store Connect, go to your app -2. Fill in required information: - - **Subtitle**: Short description (30 chars max) - - **Privacy Policy URL**: Required for Bluetooth apps - - **Category**: Utilities or Productivity - - **Age Rating**: Complete questionnaire - -### App Store Listing -1. Go to **App Store** tab -2. Upload **Screenshots** (required): - - iPhone 6.7" display (1290 x 2796 pixels) - At least 1 screenshot - - iPhone 6.5" display (1242 x 2688 pixels) - At least 1 screenshot - - Optional: iPad screenshots - -3. Fill in **Description**: - ``` - Meshcore Open is a Flutter client for MeshCore LoRa mesh networking devices. - - Features: - - BLE connectivity to MeshCore devices - - Real-time mesh network communication - - Map visualization with OpenStreetMap - - Community management with QR code scanning - - Message tracking and retry system - - Connect to your MeshCore LoRa device and start communicating over the mesh network. - ``` - -4. **Keywords**: `lora,mesh,networking,bluetooth,communication` -5. **Support URL**: Your GitHub or website URL -6. **Marketing URL**: (Optional) - -### Version Information -1. **What's New in This Version**: - ``` - Initial release of Meshcore Open - - - BLE device connectivity - - Mesh network messaging - - Map integration - - Community features - ``` - -2. **Build**: Select the uploaded build once processing completes - -## Step 6: TestFlight Setup - -### Internal Testing (No Review Required) -1. Go to **TestFlight** tab in App Store Connect -2. Click **Internal Testing** → **"+"** to create a group -3. Name your group (e.g., "Internal Testers") -4. Add yourself as a tester using your email -5. Select the build you uploaded -6. Testers will receive an email with TestFlight invitation - -### External Testing (Requires Beta Review) -1. Click **External Testing** → **"+"** to create a group -2. Add build and testers -3. Fill in **Test Information**: - - **What to Test**: Brief description of features - - **Feedback Email**: Your email address -4. Click **Submit for Review** -5. Beta review typically takes 24-48 hours - -## Step 7: App Store Submission - -Once you're ready for public release: - -1. Go to **App Store** tab -2. Complete all required metadata (if not done) -3. Select your build -4. Fill in **App Review Information**: - - **Contact Information**: Your name, phone, email - - **Demo Account**: If app requires login - - **Notes**: Any special instructions for reviewers -5. Answer **Export Compliance** questions: - - Does your app use encryption? **Yes** (uses TLS/HTTPS) - - Is encryption registration required? **No** (standard encryption) -6. Click **Add for Review** -7. Review summary and click **Submit to App Review** - -## Step 8: After Submission - -- **App Review**: Typically 24-48 hours -- **Common Rejection Reasons**: - - Missing privacy policy - - Incomplete app information - - Crashes or bugs - - Misleading app description - -- **If Approved**: You can release immediately or schedule a release date -- **If Rejected**: Address issues and resubmit - -## Updating the App - -When you need to release an update: - -1. **Update version** in `pubspec.yaml`: - ```yaml - version: 0.5.0+6 # Increment version (0.5.0) and build number (+6) - ``` - -2. **Build new IPA**: ```bash - export PATH="/opt/homebrew/lib/ruby/gems/4.0.0/bin:$PATH" - ../flutter/bin/flutter clean - ../flutter/bin/flutter build ipa + flutter pub get + dart format --output=none --set-exit-if-changed . + flutter analyze --fatal-infos --fatal-warnings + flutter test ``` -3. **Upload via Transporter** (same process as above) +3. Review the changelog, store description, screenshots, support URL, and hosted privacy policy. Describe available features and their platform/firmware limits. +4. Test on physical hardware: BLE connect/reconnect, direct/channel messages, notifications/background behavior, and affected features such as contact QR import, regions, translation, and image reconstruction. +5. Confirm camera, Bluetooth, and photo-library usage descriptions match the app’s behavior. Test permissions and denial paths. -4. **Create new version** in App Store Connect: - - Click **"+"** next to versions - - Select version number - - Update "What's New" text - - Select new build - - Submit for review +## Build and upload -## macOS Build (Bonus) - -To build for macOS: +From the repository root: ```bash -export PATH="/opt/homebrew/lib/ruby/gems/4.0.0/bin:$PATH" -../flutter/bin/flutter build macos --release -cd build/macos/Build/Products/Release -zip -r meshcore_open-macos.zip meshcore_open.app +flutter build ipa --release ``` -Distribution: -- Share the zip file directly -- Users unzip and drag to Applications -- First run: Right-click → Open (to bypass Gatekeeper) +Locate the generated IPA under `build/ios/ipa/`; do not assume an exact filename. Upload it with Transporter or Xcode’s supported distribution flow. If signing fails, open `ios/Runner.xcworkspace` and check Runner → Signing & Capabilities, team access, bundle identifier, and provisioning. + +Wait for App Store Connect processing and inspect any validation messages before assigning the build to testers. Processing/review times vary. + +## TestFlight + +Use the existing app’s TestFlight page to assign a processed build to an internal testing group. External distribution may require beta review. Provide concrete What to Test notes, feedback contact information, and instructions for the companion radio/firmware needed to exercise the app. + +Follow [Apple’s TestFlight documentation](https://developer.apple.com/testflight/) for current tester limits, permissions, and review requirements. + +## App Store submission + +Update the app information, screenshots for required supported device classes, release notes, support URL, privacy-policy URL, and privacy disclosures. Use the current App Store Connect prompts for screenshot requirements rather than a fixed list of screen sizes in this guide. + +Reviewers need a clear explanation of the external MeshCore hardware requirement and accessible instructions for evaluating relevant features. Do not promise firmware updates or unsupported platform features in the listing. + +Assess export compliance using the app’s actual encryption, including app-provided cryptographic functions as well as HTTPS. Do not assume an exemption solely because standard algorithms are used. Follow [Apple’s encryption questionnaire and documentation workflow](https://developer.apple.com/help/app-store-connect/manage-app-information/determine-and-upload-app-encryption-documentation). + +Select the processed build, complete the current review prompts, and submit through App Store Connect. If rejected, address the stated issue and update the build or metadata as appropriate. + +## macOS distribution + +```bash +flutter build macos --release +``` + +The app bundle is under `build/macos/Build/Products/Release/`. For public distribution, prepare signing and notarization using the applicable Apple distribution workflow; a zip alone does not establish that an app is signed or notarized. ## Troubleshooting -### Build Errors -- **CocoaPods not found**: Ensure PATH includes `/opt/homebrew/lib/ruby/gems/4.0.0/bin` -- **No signing certificate**: Configure Team in Xcode (Signing & Capabilities) -- **Bundle ID mismatch**: Check `ios/Runner.xcodeproj/project.pbxproj` +| Problem | Check | +|---|---| +| CocoaPods missing | Installation and PATH; `flutter doctor` | +| Signing/profile error | Team, certificates, profiles, and matching bundle ID | +| Build not visible | Processing status and validation messages in App Store Connect | +| Permissions or hardware failure | Physical-device logs, usage descriptions, radio firmware, and reproduction steps | +| Native model crash | Available memory, supported runtime, and complete model bundle | -### Upload Errors -- **No profiles found**: Create app in App Store Connect first -- **Bundle ID not registered**: Register in Apple Developer portal -- **Authentication failed**: Use Transporter app instead of CLI - -### TestFlight Issues -- **Build not appearing**: Wait 10-30 minutes for processing -- **Can't add testers**: Check you have available slots (100 internal, 10,000 external) -- **TestFlight crashes**: Check device logs in Xcode → Devices & Simulators - -## Important Files - -- **iOS IPA**: `build/ios/ipa/meshcore_open.ipa` -- **macOS App**: `build/macos/Build/Products/Release/meshcore_open.app` -- **Bundle ID Config**: `ios/Runner.xcodeproj/project.pbxproj` -- **Version Info**: `pubspec.yaml` - -## Useful Links +## References and support - [App Store Connect](https://appstoreconnect.apple.com) -- [Apple Developer Portal](https://developer.apple.com/account) -- [TestFlight Documentation](https://developer.apple.com/testflight/) +- [Apple Developer support](https://developer.apple.com/contact/) - [App Store Review Guidelines](https://developer.apple.com/app-store/review/guidelines/) -- [Flutter iOS Deployment](https://docs.flutter.dev/deployment/ios) - -## Support - -For issues with: -- **App Store Process**: [Apple Developer Support](https://developer.apple.com/contact/) -- **Flutter Build Issues**: [Flutter GitHub](https://github.com/flutter/flutter/issues) -- **Meshcore Open App**: [GitHub Issues](https://github.com/wel97459/meshcore-open/issues) +- [Flutter iOS deployment](https://docs.flutter.dev/deployment/ios) +- [Project privacy policy](docs/PRIVACY_POLICY.md) +- [Project issues](https://github.com/zjs81/meshcore-open/issues) diff --git a/docs/BLE_PROTOCOL.md b/docs/BLE_PROTOCOL.md index c17c3e7a..1599bde2 100644 --- a/docs/BLE_PROTOCOL.md +++ b/docs/BLE_PROTOCOL.md @@ -1,1297 +1,13 @@ -# MeshCore BLE Protocol Documentation +# MeshCore protocol reference -## Overview +The maintained reference is [BLE Protocol & Data Layer](../documentation/ble-protocol.md). It covers shared BLE, USB, and TCP frames, command/response codes, persistence, and data flow. -The MeshCore BLE protocol implements a binary frame-based communication system using Nordic UART Service (NUS) for low-level transport. The protocol supports mesh networking operations including contact management, text messaging, channel communication, and device configuration. +Related references: -## BLE Transport Layer +- [Routing paths and multi-byte hashes](../documentation/routing-paths.md) +- [Regions and message region display](../documentation/regions.md) +- [Image messages and GRP_DATA transport](../documentation/image-messages.md) +- [App-level GRP_DATA chunk framing source](../lib/services/image_chunk_transport.dart) +- [Protocol constants and frame builders](../lib/connector/meshcore_protocol.dart) -### Nordic UART Service (NUS) - -**Service UUID**: `6e400001-b5a3-f393-e0a9-e50e24dcca9e` - -**Characteristics**: -- **RX Characteristic** (Write): `6e400002-b5a3-f393-e0a9-e50e24dcca9e` - - Used for sending commands/data TO the device - - Supports write with/without response - -- **TX Characteristic** (Notify): `6e400003-b5a3-f393-e0a9-e50e24dcca9e` - - Used for receiving responses/data FROM the device - - Notifications enabled during connection - -### Connection Flow - -1. **Scan** for devices with known name prefixes (defined in `MeshCoreUuids.deviceNamePrefixes`): - - `MeshCore-` - - `Whisper-` - - `WisCore-` - - `HT-` - - `LowMesh_MC_` -2. **Connect** with 15-second timeout -3. **Request MTU** of 185 bytes (falls back to default if unsupported) -4. **Discover services** and locate NUS characteristics -5. **Enable notifications** on TX characteristic (with 3 retry attempts) -6. **Initialize device** by sending: - - `CMD_DEVICE_QUERY` - Get device capabilities - - `CMD_APP_START` - Register app with device - - `CMD_GET_BATT_AND_STORAGE` - Request battery status - - `CMD_GET_RADIO_SETTINGS` - Get LoRa radio parameters - -## Frame Structure - -### Command Frames (App → Device) - -All command frames start with a single-byte command code followed by command-specific data. - -**Format**: `[command_code][parameters...]` - -**Maximum Frame Size**: 172 bytes (`maxFrameSize`) - -### Response Frames (Device → App) - -Response frames start with a response code, followed by response-specific data. - -**Format**: `[response_code][data...]` - -### Push Frames (Device → App, Asynchronous) - -Push frames are unsolicited notifications from the device, using codes ≥ 0x80. - -**Format**: `[push_code][data...]` - -## Command Codes (0x01-0x39) - -Commands sent from the app to the device: - -| Code | Name | Description | -|------|------|-------------| -| 0x01 | `CMD_APP_START` | Register application with device | -| 0x02 | `CMD_SEND_TXT_MSG` | Send direct text message to contact | -| 0x03 | `CMD_SEND_CHANNEL_TXT_MSG` | Send text message to channel | -| 0x04 | `CMD_GET_CONTACTS` | Request contact list | -| 0x05 | `CMD_GET_DEVICE_TIME` | Get device's current time | -| 0x06 | `CMD_SET_DEVICE_TIME` | Sync device time | -| 0x07 | `CMD_SEND_SELF_ADVERT` | Broadcast self advertisement | -| 0x08 | `CMD_SET_ADVERT_NAME` | Set node display name | -| 0x09 | `CMD_ADD_UPDATE_CONTACT` | Add/update contact with custom path | -| 0x0A | `CMD_SYNC_NEXT_MESSAGE` | Request next queued message | -| 0x0B | `CMD_SET_RADIO_PARAMS` | Configure LoRa radio settings | -| 0x0C | `CMD_SET_RADIO_TX_POWER` | Set transmit power | -| 0x0D | `CMD_RESET_PATH` | Clear contact's routing path | -| 0x0E | `CMD_SET_ADVERT_LATLON` | Set node GPS coordinates | -| 0x0F | `CMD_REMOVE_CONTACT` | Delete contact from device | -| 0x10 | `CMD_SHARE_CONTACT` | Share contact via mesh | -| 0x11 | `CMD_EXPORT_CONTACT` | Export contact data | -| 0x12 | `CMD_IMPORT_CONTACT` | Import contact data | -| 0x13 | `CMD_REBOOT` | Reboot device | -| 0x14 | `CMD_GET_BATT_AND_STORAGE` | Request battery and storage info | -| 0x15 | `CMD_SET_TUNING_PARAMS` | Set device tuning parameters | -| 0x16 | `CMD_DEVICE_QUERY` | Query device capabilities | -| 0x17 | `CMD_EXPORT_PRIVATE_KEY` | Export device private key (secure) | -| 0x18 | `CMD_IMPORT_PRIVATE_KEY` | Import device private key (secure) | -| 0x19 | `CMD_SEND_RAW_DATA` | Send raw data to contact | -| 0x1A | `CMD_SEND_LOGIN` | Authenticate to repeater | -| 0x1B | `CMD_SEND_STATUS_REQ` | Request status from repeater | -| 0x1C | `CMD_HAS_CONNECTION` | Check if connection exists to contact | -| 0x1D | `CMD_LOGOUT` | Disconnect from repeater | -| 0x1E | `CMD_GET_CONTACT_BY_KEY` | Get specific contact by public key | -| 0x1F | `CMD_GET_CHANNEL` | Get channel configuration | -| 0x20 | `CMD_SET_CHANNEL` | Configure channel | -| 0x21 | `CMD_SIGN_START` | Start signing operation | -| 0x22 | `CMD_SIGN_DATA` | Add data to be signed | -| 0x23 | `CMD_SIGN_FINISH` | Finish signing and get signature | -| 0x24 | `CMD_SEND_TRACE_PATH` | Send path trace request | -| 0x25 | `CMD_SET_DEVICE_PIN` | Set device PIN for pairing | -| 0x26 | `CMD_SET_OTHER_PARAMS` | Set miscellaneous parameters | -| 0x27 | `CMD_SEND_TELEMETRY_REQ` | Request telemetry data (deprecated) | -| 0x28 | `CMD_GET_CUSTOM_VARS` | Get custom variables | -| 0x29 | `CMD_SET_CUSTOM_VAR` | Set custom variable | -| 0x2A | `CMD_GET_ADVERT_PATH` | Get advertisement path for contact | -| 0x2B | `CMD_GET_TUNING_PARAMS` | Get device tuning parameters | -| 0x32 | `CMD_SEND_BINARY_REQ` | Send binary request to contact | -| 0x33 | `CMD_FACTORY_RESET` | Factory reset device | -| 0x34 | `CMD_SEND_PATH_DISCOVERY_REQ` | Request path discovery | -| 0x36 | `CMD_SET_FLOOD_SCOPE` | Set flood routing scope (v8+) | -| 0x37 | `CMD_SEND_CONTROL_DATA` | Send control data (v8+) | -| 0x38 | `CMD_GET_STATS` | Get statistics (v8+, sub-types: core/radio/packets) | -| 0x39 | `CMD_GET_RADIO_SETTINGS` | Get current radio parameters | - -## Response Codes (0x00-0x19) - -Responses from device to app: - -| Code | Name | Description | -|------|------|-------------| -| 0x00 | `RESP_CODE_OK` | Generic success | -| 0x01 | `RESP_CODE_ERR` | Generic error | -| 0x02 | `RESP_CODE_CONTACTS_START` | Beginning of contact list | -| 0x03 | `RESP_CODE_CONTACT` | Contact entry | -| 0x04 | `RESP_CODE_END_OF_CONTACTS` | End of contact list | -| 0x05 | `RESP_CODE_SELF_INFO` | Device identity and settings | -| 0x06 | `RESP_CODE_SENT` | Message sent (includes ACK hash) | -| 0x07 | `RESP_CODE_CONTACT_MSG_RECV` | Received direct message (v1/v2) | -| 0x08 | `RESP_CODE_CHANNEL_MSG_RECV` | Received channel message (v1/v2) | -| 0x09 | `RESP_CODE_CURR_TIME` | Current device time | -| 0x0A | `RESP_CODE_NO_MORE_MESSAGES` | Queue empty | -| 0x0B | `RESP_CODE_EXPORT_CONTACT` | Exported contact data | -| 0x0C | `RESP_CODE_BATT_AND_STORAGE` | Battery and storage status | -| 0x0D | `RESP_CODE_DEVICE_INFO` | Device capabilities | -| 0x0E | `RESP_CODE_PRIVATE_KEY` | Exported private key | -| 0x0F | `RESP_CODE_DISABLED` | Feature disabled | -| 0x10 | `RESP_CODE_CONTACT_MSG_RECV_V3` | Received direct message (v3) | -| 0x11 | `RESP_CODE_CHANNEL_MSG_RECV_V3` | Received channel message (v3) | -| 0x12 | `RESP_CODE_CHANNEL_INFO` | Channel configuration | -| 0x13 | `RESP_CODE_SIGN_START` | Signing operation started | -| 0x14 | `RESP_CODE_SIGNATURE` | Digital signature result | -| 0x15 | `RESP_CODE_CUSTOM_VARS` | Custom variables data | -| 0x16 | `RESP_CODE_ADVERT_PATH` | Advertisement path data | -| 0x17 | `RESP_CODE_TUNING_PARAMS` | Tuning parameters | -| 0x18 | `RESP_CODE_STATS` | Statistics data (v8+) | -| 0x19 | `RESP_CODE_RADIO_SETTINGS` | Radio parameters | - -## Push Codes (0x80-0x8E) - -Asynchronous notifications from device: - -| Code | Name | Description | -|------|------|-------------| -| 0x80 | `PUSH_CODE_ADVERT` | Advertisement received | -| 0x81 | `PUSH_CODE_PATH_UPDATED` | Contact path changed | -| 0x82 | `PUSH_CODE_SEND_CONFIRMED` | Message ACK received | -| 0x83 | `PUSH_CODE_MSG_WAITING` | New messages in queue | -| 0x84 | `PUSH_CODE_RAW_DATA` | Raw data received from contact | -| 0x85 | `PUSH_CODE_LOGIN_SUCCESS` | Repeater login succeeded | -| 0x86 | `PUSH_CODE_LOGIN_FAIL` | Repeater login failed | -| 0x87 | `PUSH_CODE_STATUS_RESPONSE` | Repeater status response | -| 0x88 | `PUSH_CODE_LOG_RX_DATA` | Raw LoRa packet log | -| 0x89 | `PUSH_CODE_TRACE_DATA` | Path trace response | -| 0x8A | `PUSH_CODE_NEW_ADVERT` | New contact advertisement | -| 0x8B | `PUSH_CODE_TELEMETRY_RESPONSE` | Telemetry data response | -| 0x8C | `PUSH_CODE_BINARY_RESPONSE` | Binary request response | -| 0x8D | `PUSH_CODE_PATH_DISCOVERY_RESPONSE` | Path discovery response | -| 0x8E | `PUSH_CODE_CONTROL_DATA` | Control data received (v8+) | - -## Key Frame Formats - -### CMD_APP_START (0x01) - -Registers the application with the device. - -**Format**: -``` -[0x01][app_ver][reserved x6][app_name...]\0 -``` - -**Fields**: -- `app_ver` (1 byte): Application version number -- `reserved` (6 bytes): Reserved for future use (zeros) -- `app_name` (variable): Null-terminated UTF-8 app name - -**Example**: -```dart -buildAppStartFrame(appName: 'MeshCoreOpen', appVersion: 1) -// [0x01][0x01][0x00 x6]["MeshCoreOpen"][0x00] -``` - -### CMD_SEND_TXT_MSG (0x02) - -Sends a direct message to a contact. - -**Format**: -``` -[0x02][txt_type][attempt][timestamp x4][pub_key_prefix x6][text...]\0 -``` - -**Fields**: -- `txt_type` (1 byte): Message type (0=plain, 1=CLI data) -- `attempt` (1 byte): Retry attempt number (0-3) -- `timestamp` (4 bytes LE): Unix timestamp in seconds -- `pub_key_prefix` (6 bytes): First 6 bytes of recipient's public key -- `text` (variable): UTF-8 message text, null-terminated - -**Max text length**: 160 bytes after overhead (matching firmware `MAX_TEXT_LEN`) - -**Example**: -```dart -buildSendTextMsgFrame(recipientPubKey, "Hello mesh!", attempt: 0) -``` - -### CMD_SEND_CHANNEL_TXT_MSG (0x03) - -Sends a message to a channel (broadcast group). - -**Format**: -``` -[0x03][txt_type][channel_idx][timestamp x4][text...]\0 -``` - -**Fields**: -- `txt_type` (1 byte): Message type (0=plain) -- `channel_idx` (1 byte): Channel index (0-7 typically) -- `timestamp` (4 bytes LE): Unix timestamp in seconds -- `text` (variable): UTF-8 message text, null-terminated - -**Max text length**: Depends on sender name prefix (see `maxChannelMessageBytes()`) - -### CMD_GET_CONTACTS (0x04) - -Requests contact list from device. - -**Format**: -``` -[0x04] # Get all contacts -[0x04][since x4] # Get contacts modified after timestamp -``` - -**Fields**: -- `since` (4 bytes LE, optional): Unix timestamp filter - -**Response**: -- `RESP_CODE_CONTACTS_START` (0x02) -- Multiple `RESP_CODE_CONTACT` (0x03) frames -- `RESP_CODE_END_OF_CONTACTS` (0x04) - -### CMD_GET_CONTACT_BY_KEY (0x1E) - -Fetches a specific contact by their public key. - -**Format**: -``` -[0x1E][pub_key x32] -``` - -**Fields**: -- `pub_key` (32 bytes): Contact's Ed25519 public key - -**Response**: -- `RESP_CODE_CONTACT` (0x03) if found -- `RESP_CODE_ERR` (0x01) with `ERR_CODE_NOT_FOUND` (2) if not found - -**Use case**: Efficiently check if a specific contact exists without fetching entire contact list. - -**Example**: -```dart -// Fetch specific contact -final pubKey = hexToPubKey('a1b2c3d4...'); -await connector.getContactByKey(pubKey); - -// Response handled in _handleContact() as usual -``` - -### CMD_SET_DEVICE_TIME (0x06) - -Synchronizes device clock with app. - -**Format**: -``` -[0x06][timestamp x4] -``` - -**Fields**: -- `timestamp` (4 bytes LE): Current Unix timestamp in seconds - -### CMD_SET_ADVERT_NAME (0x08) - -Sets the device's display name for advertisements. - -**Format**: -``` -[0x08][name...] -``` - -**Fields**: -- `name` (variable): UTF-8 name, max 31 bytes (truncated if longer) - -### CMD_SET_ADVERT_LATLON (0x0E) - -Sets the device's GPS coordinates. - -**Format**: -``` -[0x0E][lat x4][lon x4] -``` - -**Fields**: -- `lat` (4 bytes LE): Latitude × 1,000,000 (signed int32) -- `lon` (4 bytes LE): Longitude × 1,000,000 (signed int32) - -**Example**: -```dart -// 37.7749° N, -122.4194° W (San Francisco) -buildSetAdvertLatLonFrame(37.7749, -122.4194) -// lat_int = 37774900, lon_int = -122419400 -``` - -### CMD_ADD_UPDATE_CONTACT (0x09) - -Adds a new contact or updates an existing contact's routing path. - -**Format**: -``` -[0x09][pub_key x32][type][flags][path_len][path x64][name x32][timestamp x4] -``` - -**Fields**: -- `pub_key` (32 bytes): Contact's public key -- `type` (1 byte): Advertisement type (1=chat, 2=repeater, 3=room, 4=sensor) -- `flags` (1 byte): Contact flags -- `path_len` (1 byte): Number of path bytes used -- `path` (64 bytes): Custom routing path (padded with zeros) -- `name` (32 bytes): Contact name, null-padded UTF-8 -- `timestamp` (4 bytes LE): Unix timestamp - -**Total size**: 136 bytes - -### CMD_RESET_PATH (0x0D) - -Clears a contact's custom path, reverting to flood mode. - -**Format**: -``` -[0x0D][pub_key x32] -``` - -**Fields**: -- `pub_key` (32 bytes): Contact's public key - -### CMD_SET_RADIO_PARAMS (0x0B) - -Configures LoRa radio parameters. - -**Format**: -``` -[0x0B][freq x4][bw x4][sf][cr] -``` - -**Fields**: -- `freq` (4 bytes LE): Frequency in Hz (300,000 - 2,500,000) -- `bw` (4 bytes LE): Bandwidth in Hz (7,000 - 500,000) -- `sf` (1 byte): Spreading factor (5-12) -- `cr` (1 byte): Coding rate (5-8) - -**Example**: -```dart -// 915 MHz, 125 kHz BW, SF7, CR 4/5 -buildSetRadioParamsFrame(915000000, 125000, 7, 5) -``` - -### CMD_SET_CHANNEL (0x20) - -Creates or updates a channel configuration. - -**Format**: -``` -[0x20][idx][name x32][psk x16] -``` - -**Fields**: -- `idx` (1 byte): Channel index (0-7) -- `name` (32 bytes): Channel name, null-padded UTF-8 -- `psk` (16 bytes): Pre-shared key for encryption - -**To delete a channel**: Send empty name and zero PSK - -### RESP_CODE_SELF_INFO (0x05) - -Device identity and current settings. - -**Format**: -``` -[0x05][adv_type][tx_pwr][max_pwr][pub_key x32][lat x4][lon x4][multi_acks] -[adv_loc_policy][telemetry][manual_add][freq x4][bw x4][sf][cr][name...] -``` - -**Fields**: -- `adv_type` (1 byte): Advertisement type (1=chat, 2=repeater) -- `tx_pwr` (1 byte): Current TX power in dBm -- `max_pwr` (1 byte): Maximum TX power in dBm -- `pub_key` (32 bytes): Device's public key -- `lat` (4 bytes LE): Latitude × 1,000,000 -- `lon` (4 bytes LE): Longitude × 1,000,000 -- `multi_acks` (1 byte): Multi-ACK mode flag -- `adv_loc_policy` (1 byte): Location advertisement policy -- `telemetry` (1 byte): Telemetry mode flags -- `manual_add` (1 byte): Manual contact addition mode -- `freq` (4 bytes LE): Radio frequency in Hz -- `bw` (4 bytes LE): Radio bandwidth in Hz -- `sf` (1 byte): Spreading factor -- `cr` (1 byte): Coding rate -- `name` (variable): Node name, null-terminated UTF-8 - -**Minimum size**: 58 bytes (without name) - -### RESP_CODE_CONTACT (0x03) - -Contact entry from device. - -**Format**: -``` -[0x03][pub_key x32][type][flags][path_len][path x64][name x32][timestamp x4] -[lat x4][lon x4][lastmod x4] -``` - -**Fields**: -- `pub_key` (32 bytes): Contact's public key -- `type` (1 byte): Contact type (1=chat, 2=repeater, 3=room, 4=sensor) -- `flags` (1 byte): Contact flags -- `path_len` (1 byte): Path length (0xFF = flood mode) -- `path` (64 bytes): Routing path data -- `name` (32 bytes): Contact name, null-terminated UTF-8 -- `timestamp` (4 bytes LE): Last seen timestamp -- `lat` (4 bytes LE): Latitude × 1,000,000 -- `lon` (4 bytes LE): Longitude × 1,000,000 -- `lastmod` (4 bytes LE): Last modification timestamp - -**Total size**: 148 bytes - -**Path length interpretation**: -- `-1` (0xFF): Flood mode (no direct path) -- `≥0`: Direct path with N hops - -### RESP_CODE_CONTACT_MSG_RECV_V3 (0x10) - -Received direct message (protocol version 3). - -**Format**: -``` -[0x10][snr][res x2][prefix x6][path_len][txt_type][timestamp x4][extra? x4][text...] -``` - -**Fields**: -- `snr` (1 byte): Signal-to-noise ratio -- `res` (2 bytes): Reserved -- `prefix` (6 bytes): Sender's public key prefix -- `path_len` (1 byte): Path length (0xFF = direct) -- `txt_type` (1 byte): Text type (bits 7-2: type, bits 1-0: flags) - - Type 0: Plain text - - Type 1: CLI data -- `timestamp` (4 bytes LE): Message timestamp (Unix seconds) -- `extra` (4 bytes, optional): Extra data for signed/plain variants -- `text` (variable): Message text, null-terminated - -**Text decoding**: -1. Try reading at base offset (timestamp + 4) -2. If empty and room for extra bytes, try offset + 4 -3. Check for SMAZ compression prefix -4. Decode as UTF-8 - -### RESP_CODE_CHANNEL_MSG_RECV_V3 (0x11) - -Received channel message (protocol version 3). - -**Format**: -``` -[0x11][snr][res x2][channel_idx][path_len][txt_type][timestamp x4][sender_name...]: [text...] -``` - -**Fields**: -- `snr` (1 byte): Signal-to-noise ratio -- `res` (2 bytes): Reserved -- `channel_idx` (1 byte): Channel index -- `path_len` (1 byte): Path length -- `txt_type` (1 byte): Text type -- `timestamp` (4 bytes LE): Message timestamp -- Combined text format: `"[sender_name]: [message_text]"` - -### RESP_CODE_SENT (0x06) - -Confirmation that message was transmitted to LoRa radio. - -**Format**: -``` -[0x06][is_flood][ack_hash x4][timeout_ms x4] -``` - -**Fields**: -- `is_flood` (1 byte): 1 if flood mode, 0 if direct path -- `ack_hash` (4 bytes): Hash for matching future ACK -- `timeout_ms` (4 bytes LE): Expected ACK timeout in milliseconds - -### PUSH_CODE_SEND_CONFIRMED (0x82) - -ACK received for a sent message. - -**Format**: -``` -[0x82][ack_hash x4][trip_time_ms x4] -``` - -**Fields**: -- `ack_hash` (4 bytes): Hash matching RESP_CODE_SENT -- `trip_time_ms` (4 bytes LE): Round-trip time in milliseconds - -### PUSH_CODE_PATH_UPDATED (0x81) - -Notification that a contact's path has been updated by the device. - -**Format**: -``` -[0x81][pub_key x32] -``` - -**Fields**: -- `pub_key` (32 bytes): Contact whose path changed - -**Handler action**: Request updated contact list - -### RESP_CODE_BATT_AND_STORAGE (0x0C) - -Battery and storage status. - -**Format**: -``` -[0x0C][battery_mv x2][storage_used_kb x4][storage_total_kb x4] -``` - -**Fields**: -- `battery_mv` (2 bytes LE): Battery voltage in millivolts -- `storage_used_kb` (4 bytes LE): Used storage in kilobytes -- `storage_total_kb` (4 bytes LE): Total storage in kilobytes - -**Battery percentage calculation**: -```dart -// Chemistry-specific voltage ranges: -// LiFePO4: 2600-3650 mV -// LiPo/NMC: 3000-4200 mV -int percent = ((mv - minMv) * 100) / (maxMv - minMv); -``` - -### RESP_CODE_DEVICE_INFO (0x0D) - -Device capabilities and limits. - -**Format**: -``` -[0x0D][protocol_ver][max_contacts_div2][max_channels] -``` - -**Fields**: -- `protocol_ver` (1 byte): Protocol version -- `max_contacts_div2` (1 byte): Max contacts ÷ 2 (actual = value × 2) -- `max_channels` (1 byte): Max supported channels - -**Example**: `[0x0D][0x03][0x10][0x08]` = v3, 32 contacts, 8 channels - -### RESP_CODE_RADIO_SETTINGS (0x19) - -Current LoRa radio parameters. - -**Format**: -``` -[0x19][freq x4][bw x4][sf][cr] -``` - -**Fields**: -- `freq` (4 bytes LE): Frequency in Hz -- `bw` (4 bytes LE): Bandwidth in Hz -- `sf` (1 byte): Spreading factor (5-12) -- `cr` (1 byte): Coding rate (5-8, subtract 4 for actual CR) - -## Advanced Commands (Not Yet Implemented in Flutter) - -The following commands are supported by the firmware but not yet implemented in the Flutter app: - -### CMD_GET_ADVERT_PATH (0x2A) - -Get the recently heard advertisement path for a contact. - -**Purpose**: Retrieves the inbound path that was used when the contact's advertisement was last received. Useful for discovering optimal paths. - -**Format**: -``` -[0x2A][pub_key_prefix x6] -``` - -**Response**: `RESP_CODE_ADVERT_PATH` (0x16) with path data - -### CMD_GET_STATS (0x38) - -Get device statistics (protocol version 8+). - -**Format**: -``` -[0x38][stats_type] -``` - -**Stats types**: -- `0x00`: Core stats (packet counts, air time) -- `0x01`: Radio stats (RSSI, SNR, noise floor) -- `0x02`: Packet stats (detailed packet analysis) - -**Response**: `RESP_CODE_STATS` (0x18) with statistics data - -### CMD_SEND_TELEMETRY_REQ (0x27) - -Request telemetry data from a contact (deprecated in favor of binary requests). - -**Purpose**: Request sensor data, battery status, or environmental data from remote nodes. - -**Response**: `PUSH_CODE_TELEMETRY_RESPONSE` (0x8B) - -### CMD_SEND_PATH_DISCOVERY_REQ (0x34) - -Request path discovery to a contact. - -**Purpose**: Actively discover available paths to a contact by broadcasting a discovery request. - -**Response**: `PUSH_CODE_PATH_DISCOVERY_RESPONSE` (0x8D) with discovered paths - -### CMD_SET_FLOOD_SCOPE (0x36) - -Set flood routing scope (v8+). - -**Purpose**: Configure geographic or logical boundaries for flood routing to reduce mesh congestion. - -**Format**: -``` -[0x36][scope_data...] -``` - -### CMD_FACTORY_RESET (0x33) - -Factory reset the device. - -**Purpose**: Erase all stored data (contacts, keys, settings) and return to factory defaults. - -**Format**: -``` -[0x33] -``` - -**Response**: `RESP_CODE_OK` or `RESP_CODE_ERR` - -**WARNING**: This erases the device's identity! Use with caution. - -### CMD_EXPORT_PRIVATE_KEY (0x17) / CMD_IMPORT_PRIVATE_KEY (0x18) - -Export or import the device's Ed25519 private key. - -**Security**: These commands should be protected by device PIN or other authentication. - -**Export format**: -``` -[0x17] -``` - -**Import format**: -``` -[0x18][private_key x32] -``` - -**Response**: `RESP_CODE_PRIVATE_KEY` (0x0E) or `RESP_CODE_OK` - -### CMD_GET_CUSTOM_VARS (0x28) / CMD_SET_CUSTOM_VAR (0x29) - -Get or set custom device variables for application-specific configuration. - -**Get format**: -``` -[0x28] -``` - -**Set format**: -``` -[0x29][var_id][value...] -``` - -**Response**: `RESP_CODE_CUSTOM_VARS` (0x15) - -### CMD_SET_OTHER_PARAMS (0x26) - -Set miscellaneous device parameters (battery chemistry, telemetry mode, etc.). - -**Format**: -``` -[0x26][param_data...] -``` - -### CMD_SIGN_START/DATA/FINISH (0x21-0x23) - -Multi-step digital signing operation. - -**Purpose**: Sign arbitrary data using the device's private key. - -**Flow**: -1. `CMD_SIGN_START` - Initialize signing session -2. `CMD_SIGN_DATA` (multiple) - Add data chunks (max 8KB total) -3. `CMD_SIGN_FINISH` - Get Ed25519 signature - -**Response**: `RESP_CODE_SIGNATURE` (0x14) with 64-byte signature - -### PUSH_CODE_LOG_RX_DATA (0x88) - -Raw LoRa packet for debugging/decryption. - -**Format**: -``` -[0x88][flags][snr][raw_packet...] -``` - -**Used for**: Decrypting channel messages when device doesn't have the channel key. - -**Raw packet structure**: -``` -[header][transport_id? x4][path_len][path...][payload...] -``` - -**Channel message decryption flow**: -1. Parse header to get route type -2. Extract path and payload -3. For group text payload (type 0x05): - - First payload byte is channel hash - - Verify hash against known channels - - Decrypt payload using channel PSK - - Parse decrypted data as channel message - -## Message Features - -### Text Compression (SMAZ) - -The protocol supports optional SMAZ compression for text messages: - -**Encoding**: -```dart -// Only compress if it saves space -String outbound = Smaz.encodeIfSmaller(text); -``` - -**Decoding**: -```dart -// Detect and decode SMAZ prefix -String decoded = Smaz.tryDecodePrefixed(received) ?? received; -``` - -**Enable per-contact/channel**: -- Contact: Stored in `ContactSettingsStore` -- Channel: Stored in `ChannelSettingsStore` - -**Exclusions**: Structured payloads starting with `g:`, `m:`, or `V1|` are never compressed. - -### Message Reactions - -**Format**: `"m:[message_id]:[emoji]"` - -**Example**: `"m:abc123:👍"` - -**Processing**: -1. Parse reaction from incoming message -2. Find target message by `messageId` -3. Increment emoji counter in target message's `reactions` map -4. Don't display reaction as a separate message - -### Message Replies - -**Format**: `"@[node_name] [actual_message]"` - -**Example**: `"@Alice Hello there!"` - -**Processing**: -1. Parse reply mention from message text -2. Find most recent message from mentioned sender -3. Attach reply metadata to new message: - - `replyToMessageId` - - `replyToSenderName` - - `replyToText` - -### Message Retry and ACK Tracking - -The app implements automatic retry for failed messages: - -**Flow**: -1. Send message → Receive `RESP_CODE_SENT` with `ack_hash` and `timeout_ms` -2. Start timeout timer -3. On timeout: Retry with incremented attempt counter -4. On `PUSH_CODE_SEND_CONFIRMED`: Mark delivered, record trip time - -**Retry strategy**: Exponential backoff with path rotation (if auto-rotation enabled). - -## LoRa Timing Calculations - -### Airtime Calculation - -Based on Semtech SX127x datasheet formula: - -```dart -double symbolDuration = (1 << sf) / (bw / 1000.0); // ms -double preambleTime = (preambleSymbols + 4.25) * symbolDuration; - -int numerator = 8*payloadBytes - 4*sf + 28 + 16*crc - headerBytes; -int denominator = 4*(sf - 2*de); -int payloadSymbols = 8 + ceil(numerator/denominator) * (cr + 4); - -double payloadTime = payloadSymbols * symbolDuration; -int airtime = ceil(preambleTime + payloadTime); -``` - -**Variables**: -- `sf`: Spreading factor (5-12) -- `bw`: Bandwidth in Hz -- `cr`: Coding rate (5-8) -- `de`: Low data rate optimization (1 if sf≥11, else 0) -- `crc`: CRC enabled (always 1) - -### Message Timeout Calculation - -**Flood mode** (path_len = -1): -``` -timeout = 500 + (16 × airtime) ms -``` - -**Direct path** (path_len ≥ 0): -``` -timeout = 500 + ((airtime×6 + 250) × (hops+1)) ms -``` - -**Example** (SF7, BW125, 100 bytes, 2 hops): -``` -airtime ≈ 50 ms -timeout = 500 + ((50×6 + 250) × 3) = 500 + (550 × 3) = 2150 ms -``` - -## Path Routing - -### Path Format - -Paths are sequences of 1-byte public key prefixes: - -**Example path** (3 hops): -``` -[0xAB][0xCD][0xEF] // Route through nodes AB... → CD... → EF... -``` - -**Max path size**: 64 bytes = 64 hops maximum - -### Path Modes - -**Flood mode** (`path_len = -1`): -- Message floods through all nodes -- Higher latency, more reliable -- Used when no direct path known - -**Direct mode** (`path_len ≥ 0`): -- Message follows specific path -- Lower latency, less reliable -- Requires path discovery/maintenance - -### Auto Path Rotation - -When enabled, the app cycles through known paths: - -**Implementation**: -1. `PathHistoryService` tracks success/failure per path -2. On message send, select next path variant -3. Record attempt and outcome -4. Rotate to next path on retry -5. Update contact's path in-memory via `CMD_ADD_UPDATE_CONTACT` - -## Channel Encryption - -Channels use symmetric encryption with pre-shared keys (PSK). - -### Encryption Scheme - -**MAC**: HMAC-SHA256 (first 2 bytes) -**Cipher**: AES-128-ECB - -**Process**: -1. Compute channel hash: `sha256(psk)[0]` -2. Encrypt payload with AES-128-ECB using first 16 bytes of PSK -3. Compute HMAC-SHA256 of ciphertext using 32-byte padded PSK -4. Prepend 2-byte MAC to ciphertext -5. Prepend channel hash byte - -**Format**: -``` -[channel_hash][mac x2][ciphertext...] -``` - -### Decryption (from PUSH_CODE_LOG_RX_DATA) - -1. Extract channel hash from payload -2. Try each known channel's PSK -3. Verify 2-byte HMAC prefix -4. Decrypt with AES-128-ECB -5. Parse decrypted payload as channel message - -## Data Types - -### Binary Encoding - -**Little-endian** for all multi-byte integers: - -```dart -// Read uint32 -int val = data[offset] | (data[offset+1] << 8) | - (data[offset+2] << 16) | (data[offset+3] << 24); - -// Write uint32 -data[offset] = val & 0xFF; -data[offset+1] = (val >> 8) & 0xFF; -data[offset+2] = (val >> 16) & 0xFF; -data[offset+3] = (val >> 24) & 0xFF; -``` - -### String Encoding - -**Format**: Null-terminated UTF-8 - -```dart -// Read C-string -String readCString(Uint8List data, int offset, int maxLen) { - int end = offset; - while (end < offset + maxLen && end < data.length && data[end] != 0) { - end++; - } - return utf8.decode(data.sublist(offset, end), allowMalformed: true); -} -``` - -**Fallback**: If UTF-8 decoding fails, use Latin-1 (byte-to-char mapping). - -### Public Keys - -**Format**: 32-byte Ed25519 public keys - -**Hex representation**: -```dart -String hex = pubKey.map((b) => b.toRadixString(16).padLeft(2, '0')).join(); -// Example: "a1b2c3d4e5f6..." -``` - -**Prefix matching**: First 6 bytes used for message routing. - -## Connection Management - -### Connection States - -```dart -enum MeshCoreConnectionState { - disconnected, // Not connected - scanning, // BLE scan in progress - connecting, // Connection attempt in progress - connected, // Fully connected and initialized - disconnecting, // Disconnect in progress -} -``` - -### Auto-Reconnection - -When connection is lost (not manual disconnect): - -**Strategy**: Exponential backoff -```dart -int delayMs = 1000 * (1 << attempt); // 1s, 2s, 4s, 8s, 16s, 32s -delayMs = min(delayMs, 30000); // Cap at 30 seconds -``` - -**Attempts**: Unlimited until manual disconnect or successful reconnect. - -### Message Queue Syncing - -On connect, the app syncs queued messages: - -**Flow**: -1. Wait for `RESP_CODE_SELF_INFO` (device ready) -2. Wait for `RESP_CODE_END_OF_CONTACTS` (contacts loaded) -3. Send `CMD_SYNC_NEXT_MESSAGE` -4. Process each message/response -5. Send next `CMD_SYNC_NEXT_MESSAGE` -6. Continue until `RESP_CODE_NO_MORE_MESSAGES` - -**Trigger**: Also triggered by `PUSH_CODE_MSG_WAITING` notification. - -## Error Handling - -### Frame Validation - -All frame handlers validate: -1. Minimum frame length -2. Expected data offsets -3. Null-termination of strings -4. Public key prefix matching (for messages) - -**Invalid frames**: Silently ignored, logged to debug. - -### Send Failures - -**Exceptions**: -- Not connected: `throw Exception("Not connected to a MeshCore device")` -- No write support: `throw Exception("RX characteristic does not support write")` - -**Retries**: Write operations use platform-level retries (BLE stack). - -### Disconnection Recovery - -**Actions on disconnect**: -1. Cancel all subscriptions -2. Clear device references (but preserve ID/name for reconnection) -3. Clear in-memory contacts and conversations -4. Reset sync state flags -5. Schedule reconnection (if not manual) - -## CLI Commands - -The device supports text-based CLI commands for advanced configuration: - -**Format**: -``` -[0x01][command_string...][0x00] -``` - -**Examples**: -```dart -sendCliCommand('set privacy on') -sendCliCommand('radio sf 7') -sendCliCommand('channel add "TestChannel"') -``` - -**Note**: CLI commands don't use the frame-based protocol and are sent as UTF-8 text with 0x01 prefix. - -## Protocol Constants - -```dart -const int pubKeySize = 32; // Ed25519 public key -const int maxPathSize = 64; // Max routing path -const int pathHashSize = 1; // Path prefix size -const int maxNameSize = 32; // Max name length -const int maxFrameSize = 172; // BLE MTU constraint -const int maxTextPayloadBytes = 160; // Firmware limit (10 cipher blocks) -const int appProtocolVersion = 3; // Current protocol version -``` - -## Implementation Notes - -### Thread Safety - -`MeshCoreConnector` uses Flutter's `ChangeNotifier`: -- All state changes trigger `notifyListeners()` -- BLE callbacks run on main isolate -- No explicit locking required (single-threaded) - -### Storage - -Persistent storage uses separate stores: -- `ContactStore`: Contact list cache -- `MessageStore`: Per-contact message history -- `ChannelMessageStore`: Per-channel message history -- `ContactSettingsStore`: Per-contact settings (SMAZ, etc.) -- `ChannelSettingsStore`: Per-channel settings -- `UnreadStore`: Unread message tracking - -**Windowing**: Only most recent 200 messages kept in memory per conversation. - -### Deduplication - -**Contact messages**: Compare timestamp + text in last 10 messages. - -**Channel messages**: -- Same text + timestamp within 5 seconds = duplicate -- Self-messages: Match sender name + path contains own public key prefix - -### Notifications - -The app shows system notifications for: -- New advertisements (if enabled) -- New direct messages (if enabled) -- New channel messages (if enabled) - -**Filtering**: No notifications for outgoing messages or CLI data. - -## Firmware Implementation Details - -### C++ Firmware Side (companion_radio) - -The firmware implements the protocol through the `MyMesh` class which extends `BaseChatMesh`. Key implementation notes: - -#### Frame Constants - -```cpp -#define MAX_FRAME_SIZE 172 // BLE MTU constraint -#define MAX_TEXT_LEN (10*CIPHER_BLOCK_SIZE) // 160 bytes -``` - -#### Timeout Calculations - -**Base constants**: -```cpp -#define SEND_TIMEOUT_BASE_MILLIS 500 -#define FLOOD_SEND_TIMEOUT_FACTOR 16.0f -#define DIRECT_SEND_PERHOP_FACTOR 6.0f -#define DIRECT_SEND_PERHOP_EXTRA_MILLIS 250 -``` - -**Flood timeout**: `500 + (airtime × 16) ms` - -**Direct timeout**: `500 + ((airtime × 6 + 250) × (hops + 1)) ms` - -These match the Dart implementation. - -#### Offline Message Queue - -The firmware maintains an offline queue for when the BLE client is disconnected: - -```cpp -#define OFFLINE_QUEUE_SIZE 16 -Frame offline_queue[OFFLINE_QUEUE_SIZE]; -``` - -**Features**: -- Queues messages when app not connected -- On connection, sends `PUSH_CODE_MSG_WAITING` to trigger sync -- Channel messages can be evicted if queue full (oldest first) -- Contact messages are preserved over channel messages - -**Sync flow**: -1. App sends `CMD_SYNC_NEXT_MESSAGE` -2. Firmware sends oldest queued frame -3. App sends another `CMD_SYNC_NEXT_MESSAGE` -4. Repeat until firmware sends `RESP_CODE_NO_MORE_MESSAGES` - -#### Contact Storage - -**Lazy write strategy**: -```cpp -#define LAZY_CONTACTS_WRITE_DELAY 5000 // 5 seconds -``` - -Contact list changes trigger a delayed write (5s after last change) to reduce wear on flash storage. - -#### Advertisement Path Cache - -The firmware caches recently heard advertisement paths in volatile memory: - -```cpp -#define ADVERT_PATH_TABLE_SIZE 16 -struct AdvertPath { - uint8_t pubkey_prefix[6]; - char name[32]; - uint32_t recv_timestamp; - uint8_t path_len; - uint8_t path[MAX_PATH_SIZE]; -}; -``` - -**Purpose**: Allows `CMD_GET_ADVERT_PATH` to retrieve inbound paths for discovered nodes. - -#### Expected ACK Table - -```cpp -#define EXPECTED_ACK_TABLE_SIZE 8 -struct { - uint32_t ack; // Expected ACK hash - uint32_t msg_sent; // Timestamp when sent - ContactInfo* contact; // Recipient contact -} expected_ack_table[EXPECTED_ACK_TABLE_SIZE]; -``` - -When message is sent, firmware: -1. Computes `expected_ack` hash from message -2. Stores in table with send timestamp -3. On ACK receipt, computes trip time -4. Sends `PUSH_CODE_SEND_CONFIRMED` to app - -#### Protocol Version Negotiation - -```cpp -uint8_t app_target_ver = 0; // Set by CMD_APP_START -``` - -The firmware adapts response formats based on app version: -- Version < 3: Uses `RESP_CODE_CONTACT_MSG_RECV` (no SNR) -- Version ≥ 3: Uses `RESP_CODE_CONTACT_MSG_RECV_V3` (includes SNR + reserved bytes) - -#### Error Codes - -```cpp -#define ERR_CODE_UNSUPPORTED_CMD 1 -#define ERR_CODE_NOT_FOUND 2 -#define ERR_CODE_TABLE_FULL 3 -#define ERR_CODE_BAD_STATE 4 -#define ERR_CODE_FILE_IO_ERROR 5 -#define ERR_CODE_ILLEGAL_ARG 6 -``` - -Returned in `RESP_CODE_ERR` frames: `[0x01][err_code]` - -### Flutter Implementation Details - -#### Message Windowing - -```dart -static const int _messageWindowSize = 200; -``` - -Only most recent 200 messages per contact/channel kept in memory. Older messages stored on disk but must be explicitly loaded via `loadOlderMessages()`. - -#### Frame Processing - -All received frames processed in `_handleFrame()`: -```dart -void _handleFrame(List data) { - final frame = Uint8List.fromList(data); - final code = frame[0]; - switch (code) { - case respCodeSelfInfo: _handleSelfInfo(frame); - case respCodeContact: _handleContact(frame); - // ... etc - } -} -``` - -**Validations**: -- Minimum frame length checks -- Null-termination validation for strings -- Public key prefix matching for messages -- Contact existence checks before processing messages - -#### Auto-Reconnection - -```dart -int _nextReconnectDelayMs() { - final attempt = _reconnectAttempts.clamp(0, 6); - final delayMs = 1000 * (1 << attempt); // Exponential backoff - return delayMs > 30000 ? 30000 : delayMs; -} -``` - -**Strategy**: 1s, 2s, 4s, 8s, 16s, 32s, then capped at 30s. - -#### Self-Info Retry - -```dart -Timer.periodic(const Duration(milliseconds: 3500), (timer) { - if (!_awaitingSelfInfo) timer.cancel(); - sendFrame(buildAppStartFrame()); -}); -``` - -On connect, if `RESP_CODE_SELF_INFO` not received within 3s, retry `CMD_APP_START` every 3.5s until received. - -#### Message Deduplication - -**Contact messages**: Compare last 10 messages for same timestamp + text. - -**Channel messages**: -- Same text within 5 seconds = duplicate -- Self-message detection: Match sender name with self name + path contains own public key prefix - -#### Reaction Processing - -```dart -final reactionInfo = Message.parseReaction(message.text); -if (reactionInfo != null) { - _processContactReaction(messages, reactionInfo); - return; // Don't add as visible message -} -``` - -Reactions are parsed, processed to update target message's reaction counts, but never displayed as standalone messages. - -## References - -- **Firmware Repository**: https://github.com/nonik0/meshcore -- **LoRa Airtime Calculator**: Based on Semtech AN1200.22 -- **SMAZ Compression**: https://github.com/antirez/smaz -- **Ed25519**: https://ed25519.cr.yp.to/ -- **AES-128-ECB**: FIPS 197 -- **Nordic UART Service (NUS)**: Nordic Semiconductor BLE UART specification +The former reference at this path contained obsolete CLI framing, reaction syntax, radio-settings codes, and implementation status. Use the linked maintained reference for current behavior. Historical content remains available in Git history. diff --git a/docs/PRIVACY_POLICY.md b/docs/PRIVACY_POLICY.md index 64bff9fb..6737012e 100644 --- a/docs/PRIVACY_POLICY.md +++ b/docs/PRIVACY_POLICY.md @@ -1,6 +1,6 @@ # Privacy Policy for MeshCore Open -**Last Updated:** August 23, 2026 +**Last Updated:** September 27, 2026 ## Introduction @@ -30,6 +30,9 @@ The App stores the following data **locally on your device**: - **Message History**: Path history for message routing - **Debug Logs**: Optional BLE and app debug logs (if enabled by user) - **Cached Map Tiles**: Offline map data for the mapping feature +- **Images and Models**: Received image bitstreams, reconstructed images, and downloaded translation/image model files +- **Communities and Credentials**: Community secrets and repeater passwords when you choose to save them +- **Regions**: Saved region names, per-radio default/channel selections, and message-region metadata This locally stored data is not transmitted to the MeshCore Open developer. Some features may send specific data to third-party services as described in the Third-Party Services section. @@ -51,7 +54,7 @@ Required by Android for BLE scanning on Android 11 and below. MeshCore Open does ### Internet Permission - **INTERNET** -Used for features that access third-party internet services, including map tiles, Line-of-Sight elevation lookups, optional model downloads, and optional GIF search. +Used for features that access third-party internet services, including map tiles, Line-of-Sight elevation lookups, optional model downloads, GIF search/display, and optional URL image previews. ### Notification Permission - **POST_NOTIFICATIONS** (Android 13+) @@ -63,6 +66,10 @@ Used to display notifications for incoming messages when the app is in the backg Used to maintain BLE connection with your MeshCore device while the app is in the background. +### Camera and Photo Library + +Camera access is used for contact and community QR scanning. Photo-library access is used when you select a photo for mesh image messaging. Selected photos are encoded locally for transmission over the mesh; the App does not upload them to a model service for inference. + ## Third-Party Services ### Map Tiles @@ -90,7 +97,13 @@ The App includes a GIF picker feature powered by Giphy. When you use the GIF sea - Your device's IP address is visible to Giphy - Giphy may collect usage data according to their privacy policy -GIF search is optional and only activated when you choose to use it. See [Giphy's Privacy Policy](https://support.giphy.com/hc/en-us/articles/360032872931-GIPHY-Privacy-Policy) for more information about how they handle data. +GIF search is optional and activated through the picker. Displaying a GIF reference received in a chat also requests image content from Giphy’s CDN, even if you did not perform a search. See [Giphy's Privacy Policy](https://support.giphy.com/hc/en-us/articles/360032872931-GIPHY-Privacy-Policy) for more information about how they handle data. + +### URL Image Previews and Custom Model URLs + +When URL images are enabled for a contact or channel, supported links in messages can cause requests to the referenced image host, sharing-page provider, or IPFS gateway. These services receive the requested URL and normal connection information, including your IP address. Requests may occur when chat content is displayed rather than only after tapping the link. Disable URL images in the contact/channel settings to disable this preview feature. + +If you choose a custom model URL, model requests go to that host rather than only Hugging Face. Translation and mesh-image inference run locally after model installation; message content and selected photos are not sent to the model host for inference. ## Mesh Network Communications @@ -98,7 +111,7 @@ Messages sent through the MeshCore mesh network are transmitted over radio frequ ## Data Security -All data stored locally on your device uses standard Flutter/Android storage mechanisms. The App does not implement additional encryption for locally stored data beyond what the operating system provides. +Local data uses standard platform storage: preferences/JSON for metadata and files for models, images, and caches. Saved secrets and passwords are local data too. The App does not implement additional encryption for locally stored data beyond what the operating system provides. ## Children's Privacy @@ -106,7 +119,7 @@ The App does not knowingly collect any personal information from children under ## Open Source -MeshCore Open is open-source software. You can review the complete source code to verify these privacy practices at [the project repository]. +MeshCore Open is open-source software. You can review the complete source code to verify these privacy practices at [the project repository](https://github.com/zjs81/meshcore-open). ## Changes to This Policy @@ -114,8 +127,8 @@ We may update this Privacy Policy from time to time. Any changes will be reflect ## Contact -If you have questions about this Privacy Policy or the App's privacy practices, please open an issue on the project's GitHub repository. +If you have questions about this Privacy Policy or the App's privacy practices, please open an issue on the [project issue tracker](https://github.com/zjs81/meshcore-open/issues). --- -**Summary**: MeshCore Open does not use the phone's GPS for location, does not include analytics, and does not collect personal information for the developer. Some optional features communicate with third-party services, including map tile providers, Open-Meteo for LOS elevation lookups, Hugging Face for model downloads, and Giphy for GIF search. +**Summary**: MeshCore Open does not use the phone's GPS for location, does not include analytics, and does not collect personal information for the developer. Some optional features communicate with third-party services, including map tile providers, Open-Meteo for LOS elevation lookups, Hugging Face for model downloads, Giphy for GIF search/display, and image hosts/gateways for enabled URL previews. diff --git a/documentation/README.md b/documentation/README.md index a3700fc6..0afb4bc5 100644 --- a/documentation/README.md +++ b/documentation/README.md @@ -1,6 +1,13 @@ # MeshCore Open - Feature Documentation -MeshCore Open is an open-source Flutter client for MeshCore LoRa mesh networking devices. This documentation covers every user-facing feature, how to access it, and what it does. +MeshCore Open is an open-source Flutter client for MeshCore LoRa mesh networking devices. These guides describe current user-facing features and their requirements. Reviewed against app `9.5.0+16`, including region-display merge `5eca459e`, on September 27, 2026. Hardware behavior still depends on platform, radio, and firmware. + +## Start here + +1. Use compatible MeshCore companion firmware and [connect a radio](scanner-and-connection.md). +2. Wait for synchronization, then open a [channel](channels.md) or [contact chat](chat-and-messaging.md). +3. For scoped floods, configure [regions](regions.md). For image packets, install the [image model](image-messages.md). +4. If a device or feature is unavailable, use [troubleshooting](troubleshooting.md). ## Table of Contents @@ -16,6 +23,10 @@ MeshCore Open is an open-source Flutter client for MeshCore LoRa mesh networking 10. [Additional Features](additional-features.md) - GIF picker, localization, debug logs, SMAZ compression, and more 11. [Routing Paths](routing-paths.md) - Path encoding, validation, device capability detection, and storage 12. [BLE Protocol & Data Layer](ble-protocol.md) - Technical reference for the communication protocol and data architecture +13. [Regions](regions.md) - Default/override scopes, message labels, and reply regions +14. [Image Messages](image-messages.md) - Model setup, mesh image sending, recovery, and reconstruction +15. [Companion Radio Statistics](radio-statistics.md) - Noise, signal metrics, and airtime +16. [Troubleshooting](troubleshooting.md) - BLE, USB, browser, and firmware issues ## App Overview @@ -29,3 +40,19 @@ MeshCore Open connects to MeshCore LoRa mesh radios over BLE, USB, or TCP. Once - **Configure radio settings** including frequency, power, bandwidth, and spreading factor - **Cache offline maps** for use without internet connectivity - **Analyze line-of-sight** between nodes with terrain elevation profiles + +## What needs internet? + +| Feature | Internet requirement | +|---|---| +| Radio messaging, region-scoped sends | No internet needed for the mesh transport | +| Mesh image encoding/reconstruction | Local after model installation | +| On-device translation | Local after model installation | +| Model downloads | Internet required | +| GIF search/display and URL image previews | Internet required to retrieve content | +| Map display | Cached tiles work offline; uncached tiles need internet | +| Terrain LOS analysis | Elevation lookup needs internet unless the required data is already cached | + +## Keeping documentation current + +When changing a feature, update its access steps, defaults, platform/firmware requirements, failure states, and screenshots. Keep binary framing details in the protocol reference and implementation links. See [contribution guidelines](../CONTRIBUTING.md). diff --git a/documentation/additional-features.md b/documentation/additional-features.md index 6aeb37ed..c1e2fe76 100644 --- a/documentation/additional-features.md +++ b/documentation/additional-features.md @@ -63,7 +63,7 @@ A list of nodes heard passively over the air but not yet added as contacts. Each An optional per-contact and per-channel text compression feature using the SMAZ algorithm (optimized for short English text). ### How to Enable -- **Per contact**: Chat screen → info button → toggle "SMAZ compression" +- **Per contact**: Chat screen → overflow menu → Contact Settings → toggle "SMAZ compression" - **Per channel**: Long-press channel → Edit → toggle "SMAZ compression" ### How It Works @@ -95,10 +95,10 @@ A live QR scanner view with instruction text overlay. ## Channel Message Path Viewing ### How to Access -In a channel chat, tap a message bubble (mobile) or use the "Path" action (desktop). +In a channel chat, long-press a message (or right-click on desktop) and choose Path. ### What the User Sees -- Summary card: sender, time, repeat count, path type, observed hops +- Summary card: sender, time, repeat count, path type, observed hops, and region when known (see [Regions](regions.md)) - "Other Observed Paths" section (if multiple paths detected) - "Repeater Hops" section listing each hop with hex prefix, resolved name, and GPS coordinates @@ -133,7 +133,7 @@ Both logs support copy-all and clear operations. Automatically shown on web platforms when a non-Chromium browser is detected. ### What the User Sees -A full-screen informational page explaining that Web Bluetooth requires a Chromium-based browser. No interactive elements — purely informational. +A full-screen informational page explaining that the web client requires Chrome. On web the app connects over USB via Web Serial only; Bluetooth is not available in the browser. No interactive elements — purely informational. --- @@ -191,17 +191,17 @@ An ML-based service that predicts expected delivery timeouts: ## On-Device Message Translation ### What It Is -An optional on-device translation service powered by an embedded LLM (llamadart, running GGUF models). Translation runs entirely on-device — no data leaves the app. +An optional on-device translation service powered by an embedded LLM (llamadart, running GGUF models). Translation inference runs on-device; messages are not uploaded for inference. Installing models requires internet access. ### How to Access -Tap the translate button on any received message. On first use, the GGUF model file is downloaded and cached locally. +Open App Settings → Translation, download/select a model, and enable translation. Then long-press an incoming message and choose "Translate message" (right-click on desktop). Automatic incoming translation is a separate toggle; pre-send translation has its own composer control. ### How It Works - Model files are managed by `TranslationFileStore`; download progress is shown in-place - Before translating, the source language is automatically detected using the `flutter_langdetect` package. If the detected language already matches the target language, translation is skipped -- Translation runs via `TranslationService` using the llamadart CPU backend (arm64 and x64 on Android) +- Translation runs via `TranslationService` using llamadart. Android APKs currently ship ARM64 only; backend support does not imply an x64 APK is distributed - Translated text is shown in `TranslatedMessageContent` as an inline overlay on the original message bubble -- Each translation is cached; re-tapping shows the cached result without re-running inference +- The translation is stored with the message, so it is shown again without re-running inference --- @@ -260,3 +260,13 @@ On Android, a foreground service (`background_service.dart`) keeps the BLE conne ### User Impact - A persistent notification appears while the service is running - Messages are received and retry logic continues even when the app is not in the foreground + +## URL Image Previews + +Enable URL images per contact in Chat → overflow → Contact Settings, or per channel in Channels → long-press (right-click on desktop) → Edit. Supported references include direct PNG/JPEG/WebP URLs, pyx.li links, ibb.co sharing pages, and IPFS references/gateway URLs. + +The message sends a reference; image retrieval needs internet access and makes requests to the relevant host or gateway. This differs from [image packets transmitted over the mesh](image-messages.md). With previews disabled, the chat may indicate that a message contains a possible image URL. + +## Regions, Mesh Images, and Radio Statistics + +See [Regions](regions.md) for default scopes, per-message labels, and reply-region inheritance; [Image Messages](image-messages.md) for model installation and reconstruction; and [Companion Radio Statistics](radio-statistics.md) for connected-radio measurements. diff --git a/documentation/ble-protocol.md b/documentation/ble-protocol.md index e5ca6972..a8a67bf3 100644 --- a/documentation/ble-protocol.md +++ b/documentation/ble-protocol.md @@ -48,17 +48,9 @@ enum MeshCoreConnectionState { ## BLE Connection Lifecycle -1. **Scan** with known name prefixes (defined in `MeshCoreUuids.deviceNamePrefixes`): - - `MeshCore-` - - `Whisper-` - - `WisCore-` - - `Seeed` - - `Lilygo` - - `HT-` - - `LowMesh_MC_` - - `NRF52` +1. **Scan** for devices advertising the NUS service UUID; names are not discovery filters 2. **Connect** with 15-second timeout (6 seconds on Linux) -3. **Request MTU** 185 bytes (non-web only) +3. **Request MTU** 185 bytes (skipped on web and Linux) 4. **Discover services** and locate NUS 5. **Enable TX notifications** (up to 3 attempts on native) 6. **Subscribe** to TX characteristic for incoming frames @@ -120,13 +112,14 @@ On unexpected disconnection, auto-reconnect with exponential backoff: | 40 | CMD_GET_CUSTOM_VAR | Get custom variables | | 41 | CMD_SET_CUSTOM_VAR | Set a custom variable | | 50 | CMD_SEND_BINARY_REQ | Send binary request | -| 54 | CMD_SET_FLOOD_SCOPE | Set flood routing scope (v8+) | +| 54 | CMD_SET_FLOOD_SCOPE_KEY | Set flood routing scope (v8+; `cmdSetFloodScope` in the app) | | 55 | CMD_SEND_CONTROL_DATA | Send control data (e.g. zero-hop discovery, v8+) | | 56 | CMD_GET_STATS | Request companion radio stats | | 57 | CMD_SEND_ANON_REQ | Send anonymous request | | 58 | CMD_SET_AUTO_ADD_CONFIG | Set auto-add configuration | | 59 | CMD_GET_AUTO_ADD_CONFIG | Get auto-add configuration | | 61 | CMD_SET_PATH_HASH_MODE | Set path hash width (bytes per hop) | +| 62 | CMD_SEND_CHANNEL_DATA | Send GRP_DATA image chunks (firmware code 11+) | ## Response / Push Codes (Device → App) @@ -152,6 +145,7 @@ On unexpected disconnection, auto-reconnect with exponential backoff: | 21 | RESP_CODE_CUSTOM_VARS | Custom variables | | 24 | RESP_CODE_STATS | Companion radio stats | | 25 | RESP_CODE_AUTO_ADD_CONFIG | Auto-add flags | +| 27 | RESP_CODE_CHANNEL_DATA_RECV | Received GRP_DATA image chunk | | 0x80 | PUSH_CODE_ADVERT | Known contact re-seen | | 0x81 | PUSH_CODE_PATH_UPDATED | Better path found; carries the 32-byte public key of the updated contact | | 0x82 | PUSH_CODE_SEND_CONFIRMED | Delivery ACK from remote; carries ACK hash (4 bytes) + trip time (4 bytes) | @@ -189,17 +183,17 @@ On unexpected disconnection, auto-reconnect with exponential backoff: Sender key, text, timestamp, outgoing flag, status (pending/sent/delivered/failed), message ID (UUID), retry count, ACK hash, trip time, path data, reactions. ### Channel Message -Sender name, text, timestamp, status (pending/sent/failed), repeater hops, path variants, channel index, reactions, reply threading fields. +Sender name, text, timestamp, status (pending/sent/failed), repeater hops, path variants, channel index, reactions, reply threading fields, and nullable `region`. Outgoing messages snapshot the send region; incoming region names are resolved from raw transport-flood metadata when possible. See [regions](regions.md). ### Channel -Index (0–7), name, 16-byte PSK, unread count. PSK derivation methods for hashtag (SHA-256) and community (HMAC-SHA256) channels. +Index (0 through the firmware-reported channel limit minus one), name, 16-byte PSK, unread count. PSK derivation methods for hashtag (SHA-256) and community (HMAC-SHA256) channels. ### Community UUID, name, 32-byte secret, hashtag channel list. Shared via QR code. ## Persistence -All data is stored via `SharedPreferences` (JSON-serialized). No SQLite or other database. +Message/contact metadata and preferences use `SharedPreferences` (JSON-serialized); there is no SQLite database. Model bundles, received image bitstreams/reconstructions, and map caches use files. Region metadata is persisted with channel messages; older records without it load with a null region. | Data | Storage Key Pattern | Scope | |---|---|---| @@ -211,9 +205,12 @@ All data is stored via `SharedPreferences` (JSON-serialized). No SQLite or other | Contact Groups | `contact_groups` | Per device identity | | Communities | `communities_v1` | Per device identity | | Unread Counts | `contact_unread_count` | Per device identity | -| Discovered Contacts | `discovered_contacts` | Global | +| Discovered Contacts | `discovered_contacts` | Per device identity (legacy global `discovered_contacts` is migrated on first load) | | App Settings | `app_settings` | Global | | Path History | `path_history_` | Per contact | +| Region Names | `regions` | Global | +| Channel Region | `channel_region_` | Per device + channel | +| Default Region | `default_region_` | Per device identity | ## Auto-Add Configuration Bitmask @@ -260,3 +257,21 @@ Uses Flutter `Provider` with `ChangeNotifier`. The central state holder is `Mesh 5. Storage stores are persisted (async) 6. `notifyListeners()` triggers UI rebuilds 7. Screens read current state via getters + +## CLI and application payloads + +Remote repeater CLI commands use the text-message command with `txtTypeCliData`, addressed to the repeater's public-key prefix: + +```text +[CMD_SEND_TXT_MSG=2][txt_type=1][attempt][timestamp uint32 LE][public-key prefix x6][UTF-8 command][0] +``` + +See `buildSendCliCommandFrame()` (takes the repeater public key) in [meshcore_protocol.dart](../lib/connector/meshcore_protocol.dart). The companion's local CLI command (`CMD_RUN_CLI_COMMAND`, 66) is not used by the app. Companion reboot uses `buildRebootFrame()`; remote repeater reboot is a CLI command. + +Reactions use `r::`. Channel replies use `@[senderName] text`; location pins use `m:,|