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.
5.7 KiB
5.7 KiB
Repository Guidelines
Project Structure & Module Organization
- Core Flutter code is in
lib/, with BLE protocol definitions inlib/connector/meshcore_protocol.dartand BLE transport/state inlib/connector/meshcore_connector.dart. - UI lives in
lib/screens/andlib/widgets/, models inlib/models/, tests intest/, and platform runners inandroid/,ios/,macos/,linux/,windows/,web/.
BLE Frames & Protocol Notes
- Nordic UART Service (NUS) UUIDs: Service
6e400001-b5a3-f393-e0a9-e50e24dcca9e, RX6e400002-b5a3-f393-e0a9-e50e24dcca9e, TX6e400003-b5a3-f393-e0a9-e50e24dcca9e. - Discovery: scans for the Nordic UART Service UUID; known name prefixes are reference values, not filters.
- Frames are capped at
maxFrameSize = 172bytes; byte 0 is the command/response/push code. I/O isMeshCoreConnector.sendFrameandMeshCoreConnector.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,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:
cmdAppStarttriggersrespCodeSelfInfowith tx power, pubkey, lat/lon, telemetry flags, radio params, and node name (see offsets inlib/connector/meshcore_connector.dart). - Radio/time helpers: radio settings come from self-info; companion stats use
cmdGetStats→respCodeStats;cmdGetDeviceTime→respCodeCurrTime;cmdSetDeviceTimeupdates device time. - Reboot: companion Settings calls
rebootDevice()→buildRebootFrame(); remote repeater management uses CLIreboot. - Companion radio format:
cmdSendTxtMsgexpects[cmd][txt_type][attempt][timestamp x4][pub_key_prefix x6][text...](no flags/full pubkey). CLI commands usetxtTypeCliDatain the same format, and the app mapsforceFloodto attempt3when 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 MeshCoreBaseChatMesh::sendGroupMessage). Sender identity is not in the payload; usePUSH_CODE_LOG_RX_DATAraw packet path bytes for origin hash when available. - 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.
- 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.
- Images: channel GRP_DATA framing is defined in
lib/services/image_chunk_transport.dart. Native codec/model requirements are documented in image messages.
Build, Test, and Development Commands
- Commands assume Flutter/Dart on PATH (or use your SDK's absolute path); see CLAUDE.md for the full list.
flutter pub getinstalls dependencies;flutter runlaunches the app;flutter build apk --release/flutter build ios --releaseproduce release builds.- CI checks:
dart format --output=none --set-exit-if-changed .,flutter analyze --fatal-infos --fatal-warnings, andflutter test.
Coding Style & Naming Conventions
- Follow
flutter_lints, uselowerCamelCase/UpperCamelCase/snake_case, preferStatelessWidget+Consumer, and useconstconstructors. - Material widgets only (no Cupertino); center app bar titles (
centerTitle: true); prefix private members with_. - Keep screens simple, keep the main screens open and read-only when the radio disconnects (see
documentation/offline-mode.md), 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.dartundertest/and runflutter testbefore 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 as the canonical protocol reference. Update affected guides, feature limitations, and screenshots when changing user-facing behavior. Read CONTRIBUTING.md for branch and review requirements.