Files
meshcore-open/CLAUDE.md
T
2026-11-01 14:27:34 -07:00

72 lines
5.7 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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.