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
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, 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.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.