72 lines
5.7 KiB
Markdown
72 lines
5.7 KiB
Markdown
# MeshCore Open — development guide
|
||
|
||
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.
|
||
|
||
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
|
||
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
|
||
flutter build linux --release
|
||
MESHCORE_BUILD_APPIMAGE=0 flutter build linux --release
|
||
bash scripts/appimage/test_packaging.sh
|
||
```
|
||
|
||
The versioned web build uses `dart run build_pipe:build` (also `bun run build`). Web deployment pins Flutter 3.41.2; Linux packaging uses the SDK pin in `scripts/appimage-tools.json`; other CI jobs track stable. Read `pubspec.yaml` for current app version and dependencies rather than copying them into this guide.
|
||
|
||
Linux Release installs also generate `build/linux/x64/release/meshcore-open-x86_64.AppImage` using linuxdeploy/GTK and an explicit appimagetool invocation. Tools and the runtime download automatically with pinned SHA-256 checksums. `MESHCORE_BUILD_APPIMAGE=0` skips packaging at install time, without a CMake cache reset. Debug/Profile are unchanged. Nix-linked bundles and hosts with glibc newer than the pinned baseline trigger an isolated Ubuntu rebuild through an available Podman/Docker engine. Rootless Podman uses `--userns=keep-id` for host-owned bind mounts; see [Linux AppImage](README.md#linux-appimage) for prerequisites, cache/offline behavior and limitations. Preserve binary/data/lib adjacency and nested native assets when changing packaging.
|
||
|
||
For Linux, use `nix develop`; see [Linux with Nix](README.md#linux-with-nix) for the pinned SDK, native build checks, cache troubleshooting, and Sysprof host prerequisites.
|
||
|
||
## Architecture and important files
|
||
|
||
| Area | Source |
|
||
|---|---|
|
||
| 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) |
|
||
|
||
`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>()`.
|
||
|
||
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.
|
||
|
||
## Localization
|
||
|
||
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`.
|
||
|
||
## Transport and platform notes
|
||
|
||
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).
|
||
|
||
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.
|
||
|
||
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.
|
||
|
||
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.
|
||
|
||
## Documentation
|
||
|
||
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.
|