Offline (read-only) mode - The last connected radio is remembered; with no radio the app opens on its saved contacts, channels, messages and unread counts. - Main screens stay open on disconnect. A Connect button replaces the battery and signal indicators, with a sheet to reconnect, choose a radio or stop a pending reconnect. - While disconnected everything is read-only: the composer becomes a "connect to send" bar (drafts kept) and controls that change the radio or stored history are disabled or hidden. - Resending while disconnected no longer deletes the message; a different radio no longer shows the previous radio's channels. - Notification taps open the saved chat while offline. Chats and menus - Channel chat menu: notifications, edit channel, delete channel; the filter row lines up with the others; bell moved out of the app bar. - DM and room menus: remove from contacts; rooms get room management. - Search field uses the full app bar; long-press a result to copy. - Hashtag channel titles no longer read "# #name"; more room around the radio activity dot. - Repeat filter: short messages from one sender are caught at the same count as long ones. Layout - Shared menu row (wraps to two lines) and segment label (never splits a word) used across the app. - One Scan button on the scanner; consistent settings tile titles; contact "last seen" wraps instead of truncating; unfetched repeater settings are dimmed. Localization - New European Portuguese locale (pt_PT); regional locales are handled by the language picker, notifications and the background service. - Fill 67 missing strings per locale, including backup and restore. - Keep "Flood" and "Zero Hop" untranslated, shorten "last seen" and routing labels, and fix mistranslated scan, theme and hop strings. - Received-image strings, badge and caption come from translations. - Regenerate the Czech localizations, which were missing strings. Docs - Add documentation/design.md (UI reference) and offline-mode.md; update channel, chat, navigation and scanner docs.
6.4 KiB
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 for repository rules and 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):
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). pubspec.yaml pins an exact Flutter release (environment.flutter); flutter pub get refuses other versions and every CI job reads it via flutter-version-file. Linux packaging uses the matching pin in scripts/appimage-tools.json, and CI fails if the two differ. The Nix shell does not provide Flutter; use the pinned SDK on PATH. Read pubspec.yaml for current app version and dependencies rather than copying them into this guide.
Linux Release installs generate architecture-matched AppImages using linuxdeploy/GTK and appimagetool: x86_64 on x64 and AArch64 on ARM64. Tools and 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 x64 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 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 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 |
| Message filter (rules, duplicate/spam checks, on-device classifier) | lib/services/message_filter/, lib/models/message_filter.dart, lib/storage/message_filter_store.dart, lib/screens/message_filter_settings_screen.dart, lib/screens/filtered_messages_screen.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/ (19 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, ReceivedImageStore, and MessageFilterService; 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.
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, regions, image messages, message filter, and routing reference. Keep protocol details in the canonical reference rather than maintaining competing command tables.
Follow the UI design reference for any UI work, and update it in the same change when you add or change a UI pattern.