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
This commit is contained in:
zjs81 committed 2026-09-27 13:12:23 -07:00
1 parent 5eca459e1c
commit aa00a863c3
28 files changed
+1774 -3233

No files matched your search

+18 -10
View File
@@ -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.
+44 -317
View File
@@ -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<T>`, `context.watch<T>()`, or `context.read<T>()`.
### 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<T>` (or `context.watch<T>()` / `context.read<T>()`) 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<Uint8List> 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=<pubspec version>` 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.
+10 -5
View File
@@ -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.
+60 -42
View File
@@ -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/)
<a href="http://apps.obtainium.imranr.dev/redirect.html?r=obtainium://add/https://github.com/zjs81/meshcore-open">
<a href="https://apps.obtainium.imranr.dev/redirect.html?r=obtainium://add/https://github.com/zjs81/meshcore-open">
<img src="assets/badges/badge_obtainium.png" height="80" align="center" alt="Get it on Obtainium"/>
</a>
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
<table>
<tr>
<td><img src="docs/screenshots/contacts.jpg" width="200"/><br/><p align="center"><b>Contacts</b></p></td>
<td><img src="docs/screenshots/chat1.jpg" width="200"/><br/><p align="center"><b>Chat</b></p></td>
<td><img src="docs/screenshots/chat2.jpg" width="200"/><br/><p align="center"><b>Reactions</b></p></td>
<td><img src="docs/screenshots/map.jpg" width="200"/><br/><p align="center"><b>Map</b></p></td>
<td><img src="docs/screenshots/channels.jpg" width="200"/><br/><p align="center"><b>Channels</b></p></td>
<td><img src="docs/screenshots/contacts.jpg" alt="Contact list" width="200"/><br/><p align="center"><b>Contacts</b></p></td>
<td><img src="docs/screenshots/chat1.jpg" alt="Direct message conversation" width="200"/><br/><p align="center"><b>Chat</b></p></td>
<td><img src="docs/screenshots/chat2.jpg" alt="Message reactions" width="200"/><br/><p align="center"><b>Reactions</b></p></td>
<td><img src="docs/screenshots/map.jpg" alt="Mesh node map" width="200"/><br/><p align="center"><b>Map</b></p></td>
<td><img src="docs/screenshots/channels.jpg" alt="Channel list" width="200"/><br/><p align="center"><b>Channels</b></p></td>
</tr>
</table>
@@ -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 | ✅ | 🚧 | ✅ | ✅ | ✅ | ❌<br>(requires websocket bridge) |
| BLE companion | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ |
| USB companion | ✅ | ❌ | ✅ | ✅ | ✅ | ✅<br>(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)
+62 -221
View File
@@ -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)
+9 -1293
View File
File diff suppressed because it is too large. Load diff
+20 -7
View File
@@ -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.
+28 -1
View File
@@ -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).
+18 -8
View File
@@ -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.
+30 -15
View File
@@ -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<pubKey10>` | Per device identity |
| Communities | `communities_v1<pubKey10>` | Per device identity |
| Unread Counts | `contact_unread_count<pubKey10>` | Per device identity |
| Discovered Contacts | `discovered_contacts` | Global |
| Discovered Contacts | `discovered_contacts<pubKey10>` | Per device identity (legacy global `discovered_contacts` is migrated on first load) |
| App Settings | `app_settings` | Global |
| Path History | `path_history_<contactKey>` | Per contact |
| Region Names | `regions` | Global |
| Channel Region | `channel_region_<pubKey10><index>` | Per device + channel |
| Default Region | `default_region_<pubKey10>` | 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:<four-hex message hash>:<two-hex emoji index>`. Channel replies use `@[senderName] text`; location pins use `m:<lat>,<lon>|<label>|...`. These are application conventions and require compatible clients for special rendering.
## Regions and image data
Transport-routed raw packets include four transport-code bytes before packed path metadata. For transport floods, the app matches the first two code bytes against locally known region candidates using HMAC-SHA256 over `[payloadType][payload]`. Region scope keys are the first 16 bytes of SHA256 of `#<region>`. The name itself is not carried as plain text. Unknown or ambiguous matches remain null; see [regions](regions.md).
Image chunks use `CMD_SEND_CHANNEL_DATA` (62), `RESP_CODE_CHANNEL_DATA_RECV` (27), and application data type `0xAE1C`. The framing, capacities, metadata byte, and XOR recovery algorithm are defined in [image_chunk_transport.dart](../lib/services/image_chunk_transport.dart), which is the source of truth. See [image messages](image-messages.md) for user requirements and limitations.
+9 -3
View File
@@ -2,7 +2,7 @@
## Overview
Channels are broadcast group-chat spaces secured by a 16-byte pre-shared key (PSK). Any device with the same channel index and PSK will receive and decrypt channel messages. Unlike direct messages, channel messages are broadcast to the entire mesh.
Channels are broadcast group-chat spaces secured by a 16-byte pre-shared key (PSK). Devices using the same channel PSK can decrypt matching channel traffic; channel indices are local device slots and need not match between peers. Unlike direct messages, channel messages are broadcast to the entire mesh.
The number of active channels is determined by the firmware (default 40); the device reports its actual limit at login.
@@ -59,7 +59,7 @@ Tap the "+" FAB to open a dialog with six options:
| Action | Description |
|---|---|
| Edit | Change name, PSK (with a dice icon to generate a random PSK), SMAZ compression toggle (compresses outgoing messages to allow longer text within the byte limit), or Cyr2Lat encoding toggle (transliterates Cyrillic to Latin for compatibility) |
| Edit | Change name, PSK (with a dice icon to generate a random PSK), SMAZ compression toggle (compresses outgoing messages to allow longer text within the byte limit), Cyr2Lat encoding toggle (transliterates Cyrillic to Latin for compatibility), or "Enable URL images" toggle (previews image links; requires internet) |
| Mute / Unmute | Toggle push notification suppression for this channel |
| Delete | Remove the channel from the device (confirmation required) |
@@ -71,7 +71,8 @@ Tap a channel card to open the channel chat screen.
- Type icon: globe for public channels, tag (#) for all other channel types
- Channel name
- Subtitle: "{Public|Private} • {N} unread" (e.g., "Public • 3 unread")
- Subtitle: channel type and effective region when set, with `(default)` when inherited
- Tap the title or landscape icon to select a region; see [Regions](regions.md)
### Message Display
@@ -83,11 +84,15 @@ Tap a channel card to open the channel chat screen.
- **Pinch-to-zoom**: Two-finger zoom (0.8x–1.8x) and double-tap to reset text size
- **Message tracing mode** (when enabled in App Settings): Each bubble additionally shows path prefix bytes (`via XX,YY,...`), a timestamp, and a repeat count icon
Messages also show a region label when known, independently of message tracing. The [message-region guide](regions.md#regions-displayed-on-messages) explains why some incoming messages have no label.
### Message Types in Chat
- **Plain text** with linkified URLs
- **GIFs** (`g:{gifId}`) rendered inline via Giphy CDN
- **Location pins** (`m:{lat},{lon}|{label}|`) shown as tappable location cards
- **Mesh images** sent as GRP_DATA chunks and reconstructed locally ([setup and limitations](image-messages.md))
- **URL image previews** when enabled per channel; content is fetched over the internet
- **Reactions** displayed as emoji pills below target messages
### Replies (Channel Chat Only)
@@ -95,6 +100,7 @@ Tap a channel card to open the channel chat screen.
- **Mobile**: Swipe an **incoming** message left to trigger reply (with haptic feedback). You cannot swipe your own outgoing messages. Swipe reply is not available on desktop.
- **All platforms**: Long-press → "Reply"
- Reply banner appears above the input bar with the quoted message (tap X to cancel)
- A known original region is selected for the reply by default. Tap the region chip to cross it out and use the channel’s effective region instead. This temporary choice does not change channel settings; see [reply regions](regions.md#reply-using-the-original-region).
- Sent replies are prefixed `@[{senderName}] {text}`
- Received replies show a bordered quote block inside the bubble; tapping scrolls to the original. Reply previews render GIF thumbnails and location pin icons, not just text.
+6 -1
View File
@@ -46,6 +46,7 @@ From the Contacts screen, tap any Chat-type contact to open the ChatScreen.
| Type | Wire Format | Display |
|---|---|---|
| Plain text | Raw UTF-8 string | Inline text with link detection |
| URL image preview | Image URL in text (per-contact opt-in; requires internet) | Downloaded inline preview |
| GIF | `g:<giphy-id>` | Inline GIF image from Giphy CDN |
| Location pin | `m:<lat>,<lon>\|<label>\|...` | Location icon + label; tap to open map |
| Reaction | `r:<hash>:<emoji-index>` | Applied to target message as emoji pill |
@@ -72,7 +73,7 @@ When enabled in App Settings, additional metadata appears inside each bubble:
## Message Length Limits
- **Direct messages**: 156 bytes (UTF-8) — enforced in real-time by the input formatter
- **Channel messages**: 160 minus sender name length minus 2 bytes for the `"<name>: "` prefix
- **Channel messages**: 160 minus sender name UTF-8 byte length minus 2 bytes for the `"<name>: "` prefix (the name counts as at most 31 bytes, and as 31 when unknown)
- Over-length paste shows a snackbar error
## Send Queue
@@ -119,3 +120,7 @@ Add emoji reactions to incoming messages (not your own):
| Delete | All messages | Removes locally (not from mesh) |
| Retry | Failed outgoing messages | Re-sends the message |
| Open chat with sender | Room server chats | Opens 1:1 chat with the message sender |
## Image and translation setup
Enable URL images in the contact’s chat settings to preview supported image links; see [URL images](additional-features.md#url-image-previews). Mesh image packets are currently sent through channel chat, not this direct-message composer. Set up translation and download a model in [App Settings](settings.md#translation) before using incoming or pre-send translation.
+4
View File
@@ -109,6 +109,10 @@ Overflow menu (or the FAB shortcut) → "Add Contact from Clipboard". Reads a `m
### Import from Discovered Contacts
Overflow menu → "Discovered Contacts". Shows nodes heard passively that haven't been added yet. Tap to immediately import (no confirmation dialog), or long-press for more options (Copy URI, Delete). The Discovery screen has its own search bar, type filters (Users, Repeaters, Rooms), and sort options (Last Seen, A-Z). An overflow "Delete All" option clears all discovered contacts.
### Import from a QR Code
Choose **Scan QR Code** from the Contacts overflow menu or the add-contact sheet. Allow camera access and scan a compatible contact QR code, or use **Scan QR from Gallery** on the scanner screen to import a QR code from a saved image. Contact QR import is separate from community QR scanning; use Channels for community codes.
## Contact Sharing Format
Contacts are shared using the `meshcore://` URI scheme:
+40
View File
@@ -0,0 +1,40 @@
# Image Messages
MeshCore Open can send a highly compressed image as channel GRP_DATA packets. Unlike a GIF reference or URL preview, the compressed image bytes travel over the mesh. A compatible recipient reconstructs them locally using the image model.
## Requirements and setup
- Companion firmware version code **11 or later** (identified in the connector as v1.15.0) for the current channel-data layout.
- A native runtime with a working ONNX backend. The web build has no image codec backend.
- The image model bundle installed through App Settings → Image model, and Enable image messages turned on.
- Enough storage for the roughly 1 GB bundle and enough available memory for reconstruction, which can peak above 2 GB. Actual latency and memory usage depend on hardware.
Downloads use the configured Hugging Face model bundle, support resume, and verify file checksums. Download the model while internet is available. Once installed, encoding and reconstruction run locally; photos are not uploaded for inference. Compatible recipients need the same supported codec/model format.
## Send an image
1. Open channel chat and tap the image button beside the composer.
2. Pick a photo from your gallery.
3. Wait for encoding. Inspect the source preview and, if available, the reconstructed preview.
4. Review transmitted bytes, packet count, and estimated send duration. Estimates use the current radio settings and are unavailable if those settings are unknown.
5. Choose whether to include a recovery packet, then send. The chat shows per-packet progress.
The current build ships one quality/model setting: **ft32**, with a 512×512 codec reconstruction and metadata used to restore a supported aspect ratio. Reserved rate/resolution codes are not additional selectable quality options.
The result is a lossy, AI-reconstructed image and can differ materially from the original. It is labeled accordingly. Send confirmation describes companion acceptance of packets, not end-to-end proof that every recipient reconstructed the image.
## Receive, reconstruct, and save
Chunks are reassembled into an image entry in channel chat. A partially received stream is retained for up to 60 seconds before expiry. An optional XOR parity packet can recover **one missing data chunk**, provided the parity and other required chunks arrive; it does not guarantee delivery.
With Process images automatically enabled, complete images are queued for local reconstruction. Automatic decoding runs only while the app is in the foreground, one image at a time, with at most 3 images queued; when more arrive, the newest 3 are kept and the rest wait for a tap. Otherwise, tap an image entry to process it. Download/enable the model if prompted. A failed reconstruction can be retried; missing chunks and inference errors are different failures.
Tap a reconstructed image to inspect it. Long-press or right-click its chat bubble for Packet info, Delete, and Save (available once decoded). Deletion is local. Encoded streams and reconstructed images are persisted in application storage, capped at 200 images, 64 MB, and 30 days. When the cap is reached, the oldest reconstructed images are evicted first and show "Image no longer stored"; they can be decoded again while their small encoded stream remains. Past 30 days the stream is removed too.
## Other image features
[GIFs and URL image previews](additional-features.md#url-image-previews) transmit references and fetch image content over the internet. They do not use this mesh image transport.
## Implementation reference
[image_chunk_transport.dart](../lib/services/image_chunk_transport.dart) defines the wire layout, capacities, metadata, and recovery algorithm. The current transport uses command 62, response 27, and data type `0xAE1C`. See the [protocol reference](ble-protocol.md#regions-and-image-data) and [fixture regeneration guide](../tools/aeic/README.md).
+13 -9
View File
@@ -41,27 +41,27 @@ Many contacts on the mesh don't have GPS hardware, so the map has no explicit co
#### Why guessed locations exist
In a mesh network, every message hops through one or more repeaters on its way to the destination. Each repeater in the path is identified by the first byte of its public key. If any of those repeaters have a known GPS location (because they advertise it), then a contact that routes through those repeaters must be somewhere within radio range of them. By combining the positions of multiple repeaters a contact is known to use, the app can triangulate a rough area where the contact is likely located.
In a mesh network, every message hops through one or more repeaters on its way to the destination. Each repeater in the path is identified by a prefix of its public key whose width is recorded with the path. If any of those repeaters have a known GPS location (because they advertise it), then a contact that routes through those repeaters must be somewhere within radio range of them. By combining the positions of multiple repeaters a contact is known to use, the app can place a rough marker near the anchors. This is a routing heuristic, not measured triangulation or a reliable estimate of physical location.
#### How the algorithm works
1. **Build a repeater index**: The app collects all known contacts of type Repeater that have a valid GPS position and indexes them by the first byte of their public key.
1. **Build an anchor index**: The app collects known Repeater and Room contacts that have a valid GPS position and indexes them by the public-key prefixes (1–3 bytes) that paths can use. Only contacts without GPS that were seen within the last 7 days are candidates for a guess.
2. **Collect anchor points**: For each contact that lacks GPS, the app looks at the **last-hop byte** of the contact's current path and also searches the `PathHistoryService` for recent paths. Each last-hop byte that matches a located repeater becomes an "anchor point" — a GPS coordinate the contact is likely near.
2. **Walk each path**: For each candidate, the app takes its current path plus recent paths from `PathHistoryService`. Each path is walked hop by hop, starting from your own radio's position, and the last hop that resolves to an anchor is the repeater that heard the contact directly.
3. **Resolve ambiguity**: If multiple repeaters share the same first public-key byte (a hash collision), that byte is discarded as ambiguous. Only unambiguous one-to-one matches are kept.
3. **Resolve ambiguity**: If several anchors share a hop's prefix (a hash collision), the hop resolves to the candidate nearest the previous hop that is within the maximum link range. Without a self position there is no reference point, so ambiguous prefixes are dropped and only unambiguous matches are kept. The maximum link range is the estimated LoRa range (computed from the current frequency, bandwidth, spreading factor, and TX power using a free-space path loss model), capped at a plausible 150 km.
4. **Filter geometric inconsistencies**: Two anchor points separated by more than `2 × maxRangeKm` (the estimated LoRa radio range, computed from the current frequency, bandwidth, spreading factor, and TX power using a free-space path loss model) cannot both be in range of the same node. Outlier anchors are removed to keep only a geometrically consistent set.
4. **Vote and filter inconsistencies**: Each observed path contributes one vote for the anchor it ended on. Two anchors more than `2 × max link range` apart cannot both be in range of the same node, so outliers are removed; if no anchors agree, the most-voted anchor wins.
5. **Compute the estimated position**:
- **Single anchor**: The contact is placed on a small circle (330m radius) around the repeater. The angle on the circle is deterministic — derived from an FNV-1a hash of the contact's public key — so the same contact always appears at the same offset, preventing markers from stacking on top of each other.
- **Two or more anchors**: The position is a weighted average of all anchor coordinates (each subsequent anchor weighted at half the previous one, biasing toward the first), with a smaller offset radius (120m for 2 anchors, 80m for 3+) applied for visual separation.
- **Two or more anchors**: The position is the average of the anchor coordinates weighted by their vote counts, with a smaller offset radius (120m for 2 anchors, 80m for 3+) applied for visual separation.
6. **Assign confidence level**:
- **High confidence** (2+ anchors): The marker border uses the node's type color (brighter border).
- **Low confidence** (1 anchor): The marker border is rendered in a muted grey.
7. **Cache the result**: The computation is cached using a key derived from the contact's paths, anchor positions, path-history version, and radio parameters. The cache is only invalidated when any of these inputs change, avoiding recomputation on every UI rebuild.
7. **Cache the result**: The computation runs in a background isolate and is cached using a key derived from the contacts' paths, anchor positions, path-history version, radio parameters, and your own position. The cache is only invalidated when any of these inputs change, avoiding recomputation on every UI rebuild.
#### How to read guessed locations on the map
@@ -122,7 +122,7 @@ The bottom panel also provides **packet animation controls**:
- A live **"Hop x of y · from → to"** label that tracks the active segment
### How It Works
Sends a trace request frame over the mesh. The repeater network traces the path hop-by-hop and returns per-hop SNR data. For hops without GPS, positions are inferred by averaging GPS coordinates of contacts sharing that last-hop byte.
Sends a trace request frame over the mesh. The repeater network traces the path hop-by-hop and returns per-hop SNR data. For hops without GPS, positions are inferred by averaging GPS coordinates of contacts sharing that last-hop prefix.
---
@@ -166,7 +166,7 @@ Settings → App Settings → Map Display → Offline Map Cache
3. Adjust the zoom range slider
4. Tap "Download Tiles" (confirmation dialog shows estimated count)
5. Tiles are downloaded with up to 8 concurrent connections
6. Once cached, tiles are served from disk without internet (365-day stale period)
6. Once cached, tiles are served without internet where supported by the cache backend. Select a Stadia Maps source with a configured API key for bulk offline downloads; OpenStreetMap is for live viewing/already cached tiles. Check the provider’s current terms and quotas.
---
@@ -191,3 +191,7 @@ The phone's own GPS is **never used**. All location data comes from the mesh:
1. **Device self-location**: Read from firmware device-info response. Set manually in Settings → Location, or updated automatically if the device has a GPS module.
2. **Remote node locations**: Extracted from advertisement packets received over the mesh. Encoded as integer lat/lon × 1,000,000.
## Regions and offline use
A [message region](regions.md) is a forwarding scope, not a coordinate or GPS boundary. The map does not establish that a sender is physically inside that region. Cached tiles can be used offline; uncached tiles and uncached LOS elevation lookups require internet.
+6 -2
View File
@@ -32,7 +32,7 @@ Tapping a tab replaces the current screen with a subtle fade + slight horizontal
- **Theme mode** is user-configurable in App Settings (System / Light / Dark) — not locked to system
- **Language** can be overridden to one of 18 supported languages, or follow the system locale
- On web, if a non-Chromium browser is detected, the app shows a `ChromeRequiredScreen` instead of the Scanner (Web Bluetooth requires Chromium)
- On web, if a non-Chromium browser is detected, the app shows a `ChromeRequiredScreen` instead of the Scanner (the web client needs Chrome for Web Serial USB)
## Full Navigation Graph
@@ -69,4 +69,8 @@ Settings (push from any main screen)
└─ [Offline Map Cache] → push → MapCacheScreen
```
Any disconnection from any screen triggers `popUntil(route.isFirst)`, returning to the Scanner.
Screens using disconnect navigation trigger `popUntil(route.isFirst)`, returning to the Scanner.
## Additional settings destinations
Settings → Regions opens [region management](regions.md). Settings → Radio stats opens [companion statistics](radio-statistics.md), including self-telemetry access. Settings → Telemetry opens telemetry for your own radio directly. App Settings contains image model setup and translation model controls. Contact QR scanning is available from Contacts; community QR scanning is available from Channels.
+4
View File
@@ -81,6 +81,10 @@ The notification system prevents notification storms:
- **Opening a channel**: Cancels the channel notification and resets unread count
- **Opening Contacts screen**: Cancels all advertisement notifications
## Translation and image references
Automatic incoming translation can also translate notification text when enabled with a ready local model. GIF and URL-image retrieval still need internet; receiving a notification does not make those references available offline. For image packet progress and reconstruction states, use [channel image chat](image-messages.md).
## Platform Support
| Platform | Message Notifs | Badge | Background Service |
+21
View File
@@ -0,0 +1,21 @@
# Companion Radio Statistics
These statistics describe the radio connected to the app. They are separate from a remote repeater’s status and do not measure every link in a mesh path.
## Open the screen
Use Settings → Radio stats, or a radio-stats shortcut where shown. The companion must report firmware version code **8+**. On unsupported firmware the Settings tile is disabled and its subtitle shows the firmware requirement; an unsupported or disconnected radio shows an explanatory state instead of statistics.
## Read the measurements
| Measurement | Meaning |
|---|---|
| Noise floor (dBm) | Radio’s reported background noise level |
| Last RSSI (dBm) | Strength of the last received signal |
| Last SNR (dB) | Signal-to-noise ratio of the last reception |
| TX / RX airtime | Reported accumulated transmit/receive airtime |
| Recent noise chart | Up to 120 received samples while viewing the screen |
The screen requests one-second polling while open. Closing it restores the 30-second interval, or stops stats polling entirely if nothing else is holding it. The chart is a recent view, not a persistent measurement log. Use last-reception metrics together with route and delivery observations rather than interpreting one sample as a complete coverage survey.
The thermometer action opens telemetry for your own companion radio. For remote measurements, see [repeater management](repeater-management.md#repeater-status) and [path tracing](map-and-location.md#path-trace-map).
+39
View File
@@ -0,0 +1,39 @@
# Regions
Regions limit which configured repeaters forward a channel flood. They are routing scopes, not geographic fences or encryption keys. A region does not create a private channel: recipients still need the channel PSK, and forwarding depends on repeater configuration.
## Add and select regions
1. While connected, open Settings → Regions.
2. Add a region name manually, or choose Fetch from repeaters and add names from the results. Discovery queries nearby responding repeaters already present in your contacts; an empty result does not prove that no regions exist on the wider mesh.
3. Manual names accept lowercase letters, digits, and hyphens, up to 30 characters. Use the exact name configured by your local repeater operators.
4. Choose a Default region to use for channels without their own override. None means the app sets no default scope.
5. In channel chat, tap the title or landscape icon to select an override. The subtitle shows the effective region, with `(default)` when inherited.
Tapping the selected region again, or choosing Clear region, removes the channel override. **If a default exists, clearing an override falls back to that default; it does not force an unscoped send.** With no override and the default set to None, the app sets no scope: the companion's scope override stays cleared (`[54, 0]`). Since companion firmware v1.15.0, the radio then falls back to its own default flood scope if one is configured on the device. The app does not issue an explicitly unscoped send.
The saved region-name list is global to the app. Default and channel assignments are stored per connected radio identity. Removing a region from the list also clears matching assignments stored for the current radio; it does not change repeater configuration.
## Regions displayed on messages
Channel text messages show a region label beside routing metadata when a region is known. The label appears in the message bubble only when the message has path data; message tracing does not otherwise need to be enabled. The message-path screen always shows the known region.
Outgoing messages retain the effective region used when they were sent. Changing a channel or default region does not relabel earlier messages. Region metadata persists with message history; older records may have no region.
Incoming region names are inferred from raw **transport-flood** packets by testing locally known names (saved regions, channel overrides, and the default). The name is not sent as plain text in the packet. Unknown names, ambiguous matches, and messages without suitable raw transport metadata do not get a region label. `foo` and `#foo` are treated as the same candidate for matching.
**No label does not prove a message was unscoped.** It can mean that its region could not be identified. A region label is routing metadata, not proof of the sender’s location or identity.
## Reply using the original region
When you reply to a message with a non-empty known region, the reply banner selects that region by default. Tap its region chip to turn this off; the chip becomes crossed out. Sending then uses the channel’s effective region instead. Canceling the reply clears this temporary choice; it does not change the channel setting.
Example: a channel defaults to `arizona`, but you reply to a message labeled `phoenix`. The reply uses `phoenix` while the reply-region chip is selected. If you cross out the chip, it uses `arizona`.
If the original message has no known region, the reply uses the channel’s effective region. This behavior applies to channel text replies; it is not a region selector for direct messages or a claim that image messages expose the same region metadata.
## Technical reference
Scoped sends temporarily set the companion’s flood scope, send the message, and then clear the scope override (`buildSetFloodScopeFrame('')`); they do not restore a previously set scope. Channel sends are serialized to prevent another channel from inheriting the temporary setting. Repeaters and companion firmware must support the relevant scope functionality.
See [channels](channels.md), [routing paths](routing-paths.md), and [protocol metadata](ble-protocol.md#regions-and-image-data).
+4
View File
@@ -219,3 +219,7 @@ Nine configuration cards, each with its own per-field refresh button(s):
- Some changes (e.g. radio frequency) require a reboot; the firmware response triggers an orange "reboot needed" snackbar
- Advertisement interval sliders reset to defaults when re-enabled (local: 60 min, flood: 3 hours)
- **Erase Filesystem** does NOT send any command over the air — tapping it only shows a snackbar explaining the operation requires physical serial access
## Region configuration and companion statistics
Repeater region commands configure the relay’s forwarding policy. The app’s [region list and channel selector](regions.md) choose scopes for outgoing channel floods; adding a name locally does not configure a repeater. [Companion radio statistics](radio-statistics.md) describe your paired radio rather than the remote repeater shown here.
+28 -57
View File
@@ -1,79 +1,50 @@
# Routing Paths
This page covers how MeshCore Open represents, selects, validates, and stores routing paths in the UI and data layer.
MeshCore Open supports flood routing, direct paths, and routing overrides. Chat → Routing lets you choose Auto, Flood, or Manual and inspect recent paths. [Regions](regions.md) control the scope of channel floods; they do not replace direct-contact routing.
## Path Routing
## Hash widths and firmware capability
MeshCore supports variable-length multi-byte routing paths so the app can scale from small meshes to very large node sets.
Each hop is represented by a public-key prefix. Current device-info negotiation clamps mode to `0..2`, giving **1–3 bytes per hop**. Some parsing/display helpers accept four-byte widths; that is not a claim that current device negotiation offers a four-byte mode.
### Hash Width and Multi-Byte Paths
| Bytes per hop | Possible prefixes | Hops fitting in 64 path bytes |
|---|---|---|
| 1 | 256 | 63 with the current six-bit packed hop count |
| 2 | 65,536 | 32 |
| 3 | 16,777,216 | 21 |
The device capability determines the hash width (number of bytes per hop):
These are prefix-space sizes, not collision-free network capacities. Longer prefixes reduce collisions and leave less room for hops. Repeaters need compatible firmware to forward multi-byte paths; the UI identifies older-than-v1.14 firmware as incompatible with two- and three-byte IDs.
| Width | Max Unique Nodes | Typical Use |
|-------|-----------------|-------------|
| 1 byte | 256 | Single-byte node IDs |
| 2 bytes | 65,536 | Medium meshes |
| 3 bytes | 16.7M | Large networks |
| 4 bytes | 4.3G | Very large meshes / future-proofing |
## Encoded paths and model fields
### Device Capability Detection
On device connection, the app reads the firmware capability to set `pathHashByteWidth`:
For packed non-flood contact path metadata:
```dart
// Read from device info response (offset 81)
final modeRaw = firmwareBytes.length >= 82
? (firmwareBytes[81] & 0xFF)
: 0;
final mode = modeRaw.clamp(0, 3);
_pathHashByteWidth = mode + 1; // 1, 2, 3, or 4 bytes per hop
final width = ((pathLenRaw & 0xC0) >> 6) + 1;
final hopCount = pathLenRaw & 0x3F;
final byteLength = hopCount * width;
```
The connector reads a single-mode byte and clamps to `0..3`, so the supported hop width is `1..4` bytes. UI code also clamps widths when rendering (typically to `1..4`) so 4-byte hops are handled end-to-end in the current codebase.
`0xFF` is the contact flood/unknown-path sentinel. Handle it before decoding the packed fields.
### Path Data Structure
- Model/storage `pathLength` stores **hop count**, with `-1` representing flood/unknown.
- `pathHashWidth` stores the bytes per hop for that path.
- `pathBytes` (or `Contact.path`) contains concatenated prefixes.
- Use the path’s own width when splitting, reversing, matching, and rendering it; do not substitute the device’s current width for historical metadata.
Paths in messages and storage consist of:
For example, a three-hop path at width 2 has six bytes: `[A1,A2,B1,B2,C1,C2]`, rendered as `A1A2 → B1B2 → C1C2`, and `pathLength=3`.
- **`pathLength` (model/storage)**: Hop count (number of hops). Negative values (e.g. `-1`) are used as a flood sentinel.
- **On-air `path_len` byte**: A packed byte that encodes hop count + hash width and is decoded into `pathLength` + `pathBytes` when parsing frames.
- **`pathBytes`**: Raw bytes of the path (concatenated hop prefixes), grouped by `pathHashByteWidth`.
- **`hopCount`**: Derived display value computed from bytes and width: `(byteCount + hashByteWidth - 1) ~/ hashByteWidth`.
- **Example**: With `pathHashByteWidth=2`, a 3-hop path has 6 bytes (`pathBytes.length = 6`) and `pathLength = 3`:
- `pathBytes = [0xA1, 0xA2, 0xB1, 0xB2, 0xC1, 0xC2]`
- Hops: `[0xA1A2]`, `[0xB1B2]`, `[0xC1C2]`
For complete observed paths, hop count is `pathBytes.length ~/ width`. Some display helpers round up a partial final group; malformed or incomplete bytes must not be interpreted as a valid complete route. Prefer decoded observed path bytes when frame metadata describes a different route.
### Hop Count Calculation
## Where paths come from
Convert path byte length to hop count:
Contact response frames place packed path metadata at offset **35** and the 64-byte path area at offsets **36–99**, counting the response code as byte 0. See [contact frame layout](ble-protocol.md#contact).
```dart
int hopCount = (byteCount + hashByteWidth - 1) ~/ hashByteWidth;
```
Channel text payloads contain sender text, not an encrypted hop chain. Observed channel paths come from the raw packet header/path associated with `PUSH_CODE_LOG_RX_DATA`. Direct-message frame metadata and path updates likewise need their format-specific decoding.
Use this consistently when displaying hop counts in UI. Do not treat `pathLength` as a hop count when the path uses multi-byte hop hashes.
Short prefixes can match several known nodes. An unresolved or ambiguous hop is not proof of a particular repeater identity. Map positions derived from paths are estimates, not GPS fixes.
### Path Usage in Different Message Types
## Storage and route selection
- **Direct messages**: Extract path from decrypted payload to trace sender route.
- **Channel messages**: Decrypt hop-by-hop routing chain from payload; the header carries the encoded byte length for the path blob, not the derived hop count.
- **Contact storage**: Path length in byte 32, raw path bytes in bytes 33-96, grouped by detected `pathHashByteWidth`.
### UI Hop Count Display
⚠️ **Important**: In screens like "Channel Message Path", prefer the actual decoded `pathBytes` hop count over `pathLength` metadata:
```dart
// Preferred: use actual observed path length
final effectiveHopCount = (pathBytes.length + width - 1) ~/ width;
// Avoid: using encoded byte length as if it were a hop count
// pathLength is bytes; converting it twice causes inflated counts
```
Example scenario:
- Radio header reports `pathLength: 32` bytes
- Decoded path bytes: `[0xAB, 0xCD]` (2 bytes = 1 hop with width=2)
- **Display**: "1 hop" (from `pathBytes`), not "32 hops" (which would double-count the encoded length)
Contacts/messages persist hop count, path bytes, and width. Legacy contact records without width infer it from consistent hop and byte counts, falling back to one byte. `PathHistoryService` scores recent routes using delivery observations; automatic route rotation can select another route on retry when no manual override is active. Rotation follows the App Settings **Auto Route Rotation** toggle (`autoRouteRotationEnabled`, on by default).
For message-path actions, trace maps, and retry behavior, see [chat](chat-and-messaging.md), [channels](channels.md), and [map](map-and-location.md).
+20 -9
View File
@@ -60,8 +60,12 @@ Opens a dialog pre-populated with the device's current radio settings. Contains:
- **TX Power** (dBm): Validated 0 to device max (typically 22 dBm)
- **Client Repeat** toggle: Only shown on firmware v9+; requires frequency to be exactly 433.000, 869.000, or 918.000 MHz (the Off-Grid presets). Save is blocked with a warning if enabled on other frequencies
### Companion Radio Stats
Opens the RF statistics screen (RSSI, SNR, packet counts) for the paired radio. Only enabled when connected to a device that supports companion radio stats.
### Regions
Open region management to add/fetch names and select a default flood scope. Channel chat can override it; clearing an override inherits the default. See [Regions](regions.md), including message labels and temporary reply-region choices.
### Radio stats
Opens the radio statistics screen for the paired radio: noise floor, last RSSI, last SNR, and total TX/RX airtime. Only enabled when connected to a device that supports companion radio stats (firmware code 8+). See the [radio-statistics guide](radio-statistics.md).
---
@@ -132,17 +136,24 @@ A dedicated sub-screen for app-level preferences (nothing here is sent to the de
- **Raster Tile Source**: Sets the MAP theme and with that from where to get the map tile data:
- OpenStreetMap (Auto/Standard/Dark) is provided by the free OpenStreetMap tile server. (Can only be used for live view or already cached.)
- Stamen Terrain / AlidadeSmooth Dark / Outdoors / OSM Bright are [StadiaMaps.com raster tile maps](https://stadiamaps.com/products/maps/interactive-basemaps/) for which you can choose an Hosted Endpoint (Worldwide / Europe hosted) and have to provide the API key to your subscription. (You can cache these maps for offline Map usage.)
There will be no account provided by meshcore-open. You will have to get you own subscription. StadiaMaps offers a [free](https://stadiamaps.com/pricing/) subscription to download up to 200'000 Standart Raster Basemap tiles.
There will be no account provided by meshcore-open. You will have to get you own subscription. Check [current Stadia Maps plans and terms](https://stadiamaps.com/pricing/) for quotas and offline-use permissions.
- **Offline Map Cache**: Navigate to tile download screen
### Translation
Not shown on web. Controls on-device message translation powered by a locally-downloaded ML model:
- **Enable Translation**: Translates incoming messages into the selected target language
- **Translate Composer**: Translates outgoing messages from the target language back before sending
- **Target Language**: Language to translate into (searchable list; defaults to the app language)
- **Downloaded Model**: Dropdown to select among already-downloaded translation models
- **Preset Model**: Download a curated preset model with one tap
- **Custom Model URL**: Enter a URL to download a custom GGUF-format model; shows download progress and a cancel button
- **Enable translation**: Enables message translation controls
- **Auto-translate incoming messages**: Automatically translates incoming messages for chat/channel display and notifications
- **Translate before sending**: Sets the default state of the composer's translate icon (on means messages are translated before sending)
- **Target language**: Language to translate into (searchable list; defaults to the app language)
- **Downloaded model**: Dropdown to select among already-downloaded translation models
- **Preset Hugging Face model**: Download a curated preset model with one tap
- **Manual model URL**: Enter a URL to download a custom GGUF-format model; shows download progress and a cancel button
The auto-translate and composer toggles are disabled until **Enable translation** is on.
### Image Messages
Image message controls live in App Settings → Messaging. Turn on **Enable image messages** first; **Process images automatically** and the image model download/cancel/removal controls then appear. Automatic processing reconstructs every image as it arrives and uses about 2 GB of memory for a second each time; leave it off to reconstruct with a tap. See [Image Messages](image-messages.md) for firmware, native-runtime, storage, and memory requirements.
### Cyrillic-to-Latin (Cyr2Lat)
Controls character substitution profiles used to render Cyrillic text in Latin characters. A dropdown selects the active profile; Add, Edit, and Delete buttons manage the profile list (the last remaining profile cannot be deleted). Each profile stores a JSON character map.
+29
View File
@@ -0,0 +1,29 @@
# Connection and Feature Troubleshooting
## BLE radio not found
Confirm that Bluetooth is enabled, the app has Bluetooth permissions, and the radio is running companion firmware advertising the Nordic UART Service UUID. Custom names are supported. Stop other clients that may already hold the connection, bring the radio closer, and scan again. Older Android systems may require location permission for BLE scanning; the app does not use phone GPS for node locations.
On Linux, check that BlueZ is running and the adapter is enabled. Pairing may fall back to `bluetoothctl`; complete the system pairing prompt when requested. Include the pairing error and app log in a bug report.
## USB connection fails
Use a data-capable cable and a supported companion serial firmware. Close terminal programs or other apps using the port. On Linux, check port ownership and the serial-access group required by your distribution. For missing devices, check drivers and OS enumeration. For permission denied, busy, or detached errors, fix the reported cause and refresh the port list.
## Browser connection fails
Use Chrome (or a Chromium browser that identifies as Chrome) and HTTPS (or an appropriate local development secure context). Allow device access through the browser’s serial port chooser. The web build connects over USB via Web Serial only; BLE scanning is not available in the browser and TCP is not supported on web. Native model inference is unavailable on web.
## Unexpected disconnect
BLE can retry an unexpected disconnect with exponential backoff; manual disconnects do not trigger reconnect. USB and TCP require reconnection through their connection screens. Navigation returns to the scanner when a connection is lost. If reconnect continues to fail, check power, firmware, adapter state, and competing clients.
## Feature unavailable or no data
Companion stats require firmware code 8+, and image channel data requires code 11+. Image inference also needs an enabled, complete model bundle and adequate memory. A missing incoming region label can mean unknown or unavailable metadata, not an unscoped message. See [images](image-messages.md), [regions](regions.md), and [radio stats](radio-statistics.md).
## Useful bug-report details
Include app version, OS/device, radio board and firmware version, transport, reproduction steps, expected behavior, and the exact error. Where relevant, include entries from the **Companion Debug Log** in Settings (frame traffic for BLE, TCP, and USB) or the **App Debug Log**. The App Debug Log only records after you enable App Settings → Debug → **App Debug Logging**. Inspect logs before sharing: they can contain message content, identifiers, and location data.
Run the relevant automated tests when reporting a source/build failure. Submit reports to the [project issue tracker](https://github.com/zjs81/meshcore-open/issues).
+3 -1
View File
@@ -2,4 +2,6 @@
You can customize the launch screen with your own desired assets by replacing the image files in this directory.
You can also do it by opening your Flutter project's Xcode project with `open ios/Runner.xcworkspace`, selecting `Runner/Assets.xcassets` in the Project Navigator and dropping in the desired images.
You can also do it by opening your Flutter project's Xcode project with `open ios/Runner.xcworkspace`, selecting `Runner/Assets.xcassets` in the Project Navigator and dropping in the desired images.
These are launch-screen assets, separate from the app icons configured through `flutter_launcher_icons` in `pubspec.yaml`. After replacing assets, inspect the launch screen on a physical iOS device and keep screenshots/store assets separate from this asset catalog.
File diff suppressed because it is too large. Load diff
+597 -518
View File
File diff suppressed because it is too large. Load diff
+40 -10
View File
@@ -30,18 +30,48 @@ the research checkout that is **not** part of this repository:
produced by it, which is what makes them worth comparing against
- PyTorch, onnxruntime, NumPy 2
## Running them
## Preparing the research layout
```bash
cd <aeic-research-checkout>
AEIC_DEVICE=cpu python export_golden.py # tables + symbol vectors
AEIC_DEVICE=cpu python record_entropy_io.py # ONNX I/O recordings
The scripts import helpers that are not included in this app repository: `aeic_runner.py` and, for recording, `bitexact_encoder.py`. Obtain the matching research/export environment before running them. The app does not pin that external checkout’s revision; record its commit, checkpoint checksum, dependency versions, and patch diff alongside regenerated fixtures so others can reproduce your results.
Use this layout in the research checkout:
```text
exp/
export_golden.py
record_entropy_io.py
aeic_runner.py
bitexact_encoder.py
onnx/
aeic_entropy_side_fp32_op17.onnx
aeic_entropy_decode_fp32_op17.onnx
results/golden/
data/kodak_raw/
data/custom/
```
Then copy the output into `test/services/golden/`.
Copy the two scripts from this directory into `exp/`. Their output paths are resolved relative to the scripts’ parent directory, not just the shell’s working directory. Supply the ft32 checkpoint and expected image corpus in the research environment.
## If you change the wire format
## Running them
Regenerate. The fixtures encode the chunk framing and the metadata byte layout,
so a format change makes them stale in a way the tests will report as a codec
bug — which is the correct behaviour, but only if you know to look here.
From the prepared research checkout, with its dependencies installed:
```bash
AEIC_DEVICE=cpu python exp/export_golden.py --ckpt /absolute/path/AEIC_SE_ft32.pkl
AEIC_DEVICE=cpu python exp/record_entropy_io.py --ckpt /absolute/path/AEIC_SE_ft32.pkl --scratch /absolute/path/aeic-scratch
python exp/record_entropy_io.py --verify-only
```
The recorder’s default scratch path is machine-specific; always supply `--scratch` or `AEIC_SCRATCH`. `--decode-graph` can select an existing recording graph; `--images` selects an explicit corpus. The exporter defaults to ten images; `--all` uses the full configured corpus.
Copy the generated contents of `results/golden/` into the app’s `test/services/golden/`. Keep paired `.gv`, `.bin`, JSON metadata, recording files, and manifest together. Review generated differences and run the relevant tests:
```bash
flutter test test/services/rans_coder_test.dart test/services/entropy_tables_test.dart test/services/image_codec_e2e_test.dart
```
## When fixtures need regeneration
Regenerate when changing the reference model, entropy tables, rANS format, or recorded tensor interface. These fixtures validate the codec/entropy pipeline, **not the separate mesh chunk headers**.
Chunk framing and metadata are defined in [image_chunk_transport.dart](../../lib/services/image_chunk_transport.dart). Changes there need transport-focused test updates; a chunk-layout-only change does not automatically require new reference codec fixtures. See the [image-message guide](../../documentation/image-messages.md).
-82
View File
@@ -650,88 +650,6 @@
"receivedImage_saveFailed"
],
"nl": [
"messageStatus_failedChannel",
"messageStatus_resending",
"messageStatus_hopsNotReached",
"messageStatus_sentChannel",
"messageStatus_sentDirect",
"messageStatus_heardRepeatedCount",
"settings_regionEmptyExplanation",
"settings_regionFetchFromRepeaters",
"settings_regionDefault",
"settings_regionDefaultSubtitle",
"settings_regionDefaultNone",
"settings_telemetryPerContactHint",
"settings_multiAckSubtitle",
"settings_presetCustom",
"settings_radioMatchWarning",
"settings_txPowerRangeHelper",
"settings_clientRepeatFrequencyNote",
"settings_pathHashModeHelper",
"settings_requiresFirmware",
"appSettings_channelMinHops",
"appSettings_channelMinHopsSubtitle",
"appSettings_channelMinHopsCount",
"appSettings_channelMinHopsRetries",
"appSettings_batteryOptimization",
"appSettings_batteryOptimizationSubtitle",
"contacts_storageFull",
"contacts_removeFromContacts",
"contacts_removeFromContactsConfirm",
"contacts_keepChatHistory",
"contacts_remove",
"contacts_discoveredNearby",
"contacts_noContactsDiscoveredHint",
"channels_hashtag",
"channels_addSectionJoin",
"channels_addSectionCreate",
"channels_dragToReorder",
"channels_regionDefaultSuffix",
"channels_regionSelectExplanation",
"channels_regionEmpty",
"channels_manageRegions",
"chat_removeGif",
"chat_cancelReply",
"chat_viewPathOnMap",
"chat_today",
"chat_yesterday",
"map_centerOnMe",
"map_noNodesLocationHint",
"map_clusterNodes",
"map_groupChip",
"map_clusterNodesSubtitle",
"map_manageServer",
"login_showPassword",
"login_hidePassword",
"login_advanced",
"common_clearSearch",
"repeater_roleAdmin",
"repeater_roleGuest",
"repeater_refreshAll",
"repeater_settingsNotLoaded",
"repeater_settingsLoadIncomplete",
"contacts_scanQrCode",
"contacts_scanQrInstructions",
"contacts_qrFromGallery",
"contacts_noQrCodeFound",
"contacts_qrGalleryFailed",
"snrIndicator_nearByRepeatersDescription",
"radioStats_sectionSignal",
"radioStats_sectionAirtime",
"imageSend_lossyNote",
"imageSend_viewOriginal",
"imageSend_viewReconstruction",
"imageSend_reconstructionUnavailable",
"imageSend_modelNotDownloaded",
"receivedImage_save",
"receivedImage_shareCaption",
"receivedImage_packetInfo",
"receivedImage_parityRecovered",
"receivedImage_decodeTime",
"receivedImage_saveFailed"
],
"pl": [
"messageStatus_failedChannel",
"messageStatus_resending",