more complete radio support

2026-06-08 13:37:27 +10:00
parent 372c177479
commit c2c2646e3d
10 changed files with 676 additions and 63 deletions
@@ -1,6 +1,6 @@
 # meshcore_c vs meshcore_py — Feature Gap Analysis

-Date: 2026-06-08 (Phase 1 complete)
+Date: 2026-06-08 (Phase 1 + 2 complete)

 ## Summary

@@ -9,12 +9,12 @@ Companion Radio **serial** protocol. It implements the wire framing (0x3C/0x3E,
 LE length), handshake, channel text/data send/receive (incl. the V3 SNR
 variants), direct/contact + CLI message sending, channel PSK programming, full
 device/self/stats parsing, and basic radio parameters. Zero external deps in the
-core; ships examples for Linux (`tty_bridge`, `info`), ESP-IDF, STM32 HAL, and
-Arduino.
+core; ships examples for Linux (`tty_bridge`, `info`, `contacts`), ESP-IDF,
+STM32 HAL, and Arduino.

-Against the reference `meshcore_py`, coverage is now roughly **45%**. The two
-remaining **major** areas are contact management and binary (telemetry/status)
-requests. Everything else is feature-completeness or convenience.
+Against the reference `meshcore_py`, coverage is now roughly **65%**. With
+Phase 2 done (contacts + binary requests), no **major** subsystems remain — the
+rest is device-management/network commands and convenience features.

 ---

@@ -31,73 +31,59 @@ contact recv (SNR) · `send_txt_msg` / `send_cmd` (direct + CLI, CMD 2) ·
 `get_stats` → **Stats** (core/radio/packets) · self-advert · auto-drain on
 `MsgWaiting` (Arduino wrapper).

+**Phase 2:** contacts — `get_contacts` (delta sync), `add_update_contact`,
+`remove_contact`, `reset_path`, `share_contact`, `export_contact` /
+`import_contact`, `get_contact_by_key`; parsing of **ContactsStart / Contact /
+EndOfContacts**, **NewAdvert** (0x8A as a contact), **ContactUri**,
+**ContactDeleted**, **ContactsFull**, **AdvertPath**, **AutoaddConfig**,
+**AllowedRepeatFreq**. Binary — `send_binary_req` / `send_anon_req`,
+**BinaryResponse** (0x8C) parse with ack-tag correlation, and `mc_parse_status`
+to decode a STATUS response. Arduino wrapper gains `onContact` /
+`onContactsDone` / `onBinaryResponse` + matching command methods.
+
 Host unit tests (`test/test_codec.c`) cover all of the above parsers/builders.

 ---

 ## Remaining gaps

-### MAJOR
-
-#### 1. Contact management — entirely missing
-No way to enumerate or manage the mesh node list from C.
-
-| Feature | CMD | meshcore_py | meshcore_c |
-|---|---|---|---|
-| GET_CONTACTS (lastmod delta sync) | 4 | ✅ | ❌ |
-| ADD_UPDATE_CONTACT | 9 | ✅ | ❌ |
-| REMOVE_CONTACT | 15 | ✅ | ❌ |
-| SHARE_CONTACT | 16 | ✅ | ❌ |
-| EXPORT_CONTACT / IMPORT_CONTACT | 17 / 18 | ✅ | ❌ |
-| RESET_PATH | 13 | ✅ | ❌ |
-| GET_CONTACT_BY_KEY | 30 | ✅ | ❌ |
-| SET_ADVERT_NAME / SET_ADVERT_LATLON | 8 / 14 | ✅ | ❌ |
-| GET_ADVERT_PATH | 42 | ✅ | ❌ |
-| SET/GET_AUTOADD_CONFIG | 58 / 59 | ✅ | ❌ |
-| GET_ALLOWED_REPEAT_FREQ | 60 | ✅ | ❌ |
-
-Response parsing needed: `CONTACT_START` (2), `CONTACT` (3), `CONTACT_END` (4),
-`CONTACT_URI` (11), `ADVERT_PATH` (22), `AUTOADD_CONFIG` (25),
-`ALLOWED_REPEAT_FREQ` (26), `CONTACT_DELETED` (0x8F), `CONTACTS_FULL` (0x90),
-`NEW_ADVERT` push (0x8A).
-
-#### 2. Binary + anonymous requests — entirely missing
-Remote interrogation of other nodes.
- `SEND_BINARY_REQ` (50) subtypes: STATUS, TELEMETRY, MMA, ACL, NEIGHBOURS
- `SEND_ANON_REQ` (57) subtypes: REGIONS, OWNER, BASIC (remote clock)
- `BINARY_RESPONSE` push (0x8C) parsing + tag tracking (`expected_ack` →
-  response correlation, reusing the `MsgSent` ack-tag + timeout already parsed)
- `TELEMETRY` push (0x8B) parsing (Cayenne LPP — likely decoded by the caller)
+*Phase 2 cleared the two former major gaps — contact management and
+binary/anonymous requests. No major subsystems remain; everything below is
+feature-completeness or convenience.*

 ### MINOR

-#### 3. Direct-message reliability
+#### 1. Direct-message reliability
 - `SEND_LOGIN` (26) / `SEND_LOGOUT` (29) / `SEND_STATUS_REQ` (27)
 - Retry helper: resend up to N times, auto-switch to flood after K direct
  failures (uses the already-parsed `MsgSent` suggested-timeout).

-#### 4. Device-management commands
+#### 2. Device-management commands
 `REBOOT` (19) · `FACTORY_RESET` (51, two-step) · `SET_DEVICE_PIN` (37) ·
 `SET_OTHER_PARAMS` (38: telemetry modes, multi_acks, advert policy) ·
 `SET_TUNING_PARAMS` (21) / `GET_TUNING_PARAMS` (43) · `HAS_CONNECTION` (28) ·
-`SET_TX_POWER` (12).
+`SET_TX_POWER` (12). Also the advert/autoadd command *builders* whose responses
+are already parsed: `SET_ADVERT_NAME` (8), `SET_ADVERT_LATLON` (14),
+`GET_ADVERT_PATH` (42), `SET/GET_AUTOADD_CONFIG` (58/59),
+`GET_ALLOWED_REPEAT_FREQ` (60).

-#### 5. Crypto & security
+#### 3. Crypto & security
 `EXPORT_PRIVATE_KEY` (23) / `IMPORT_PRIVATE_KEY` (24) ·
 `SIGN_START` (33) / `SIGN_DATA` (34) / `SIGN_FINISH` (35).
 (Signature *extraction* from received signed messages is already done.)

-#### 6. Network-layer commands
+#### 4. Network-layer commands
 `SEND_RAW_DATA` (25) · `SEND_TRACE_PATH` (36, per-hop SNR) ·
 `SEND_CONTROL_DATA` (55) · `SET_FLOOD_SCOPE` (54) /
 `SET/GET_DEFAULT_FLOOD_SCOPE` (63 / 64).

-#### 7. Remaining response/push parsing
+#### 5. Remaining response/push parsing
 `SIGN_START`/`SIGNATURE` (19/20) · `CUSTOM_VARS` (21) · `TUNING_PARAMS` (23) ·
 `DEFAULT_FLOOD_SCOPE` (28) · `LOG_RX_DATA` push (0x88) · `TRACE_DATA` push
-(0x89) · `PATH_DISCOVERY` (0x8D) · `CONTROL_DATA` push (0x8E).
+(0x89) · `TELEMETRY` push (0x8B, Cayenne LPP) · `PATH_DISCOVERY` (0x8D) ·
+`CONTROL_DATA` push (0x8E).

-#### 8. Smaller data gaps
+#### 6. Smaller data gaps
 - **Battery**: only the 2-byte voltage is parsed; the full `BATT_AND_STORAGE`
  response adds `used_kb` + `total_kb`.
 - **CUSTOM_VARS**: `GET_CUSTOM_VARS` (40) / `SET_CUSTOM_VAR` (41) + parse.
@@ -108,7 +94,7 @@ Remote interrogation of other nodes.
 - Event filtering / `wait_for_event(timeout)` helpers (C core stays struct-based).
 - Optional contact / self-info / time state tracking in the wrapper.
 - Synchronous request→response helpers (lock, await matching event, apply
-  suggested timeout) — pairs with #2 binary requests and #3 retry.
+  suggested timeout) — builds on the binary-request ack-tag + the retry helper (#1).
 - Channel-log AES decryption (heavy; needs crypto — probably out of scope for
  the bare-metal core).
 - Cayenne LPP telemetry decode (application layer / caller).
@@ -128,24 +114,18 @@ Remote interrogation of other nodes.

 ## Roadmap

-### Phase 2 — Contacts & binary requests (next, major)
-1. Contact command builders: GET_CONTACTS, ADD_UPDATE_CONTACT, REMOVE_CONTACT,
-   RESET_PATH, SHARE_CONTACT, EXPORT/IMPORT_CONTACT, GET_CONTACT_BY_KEY.
-2. Contact response parsing: CONTACT_START / CONTACT / CONTACT_END (+ CONTACT_URI,
-   CONTACT_DELETED, CONTACTS_FULL, NEW_ADVERT).
-3. Binary-request infrastructure: `mc_cmd_send_binary_req` / `mc_cmd_send_anon_req`,
-   `BINARY_RESPONSE` parsing, ack-tag correlation (reuse `MsgSent` tag+timeout).
-4. Tests + a `contacts` Linux example.
-
-### Phase 3 — Device management & network commands (minor)
+### Phase 3 — Device management & network commands (next, minor)
 REBOOT / FACTORY_RESET / SET_DEVICE_PIN / SET_OTHER_PARAMS · TUNING_PARAMS
 get/set · EXPORT/IMPORT_PRIVATE_KEY · CUSTOM_VARS · SET_ADVERT_NAME/LATLON ·
-flood scope get/set · HAS_CONNECTION · BATT_AND_STORAGE storage fields ·
-SEND_TRACE_PATH / SEND_RAW_DATA / SEND_CONTROL_DATA.
+autoadd-config + advert-path + allowed-repeat-freq command builders · flood scope
+get/set · HAS_CONNECTION · BATT_AND_STORAGE storage fields · SEND_TRACE_PATH /
+SEND_RAW_DATA / SEND_CONTROL_DATA · direct-message retry helper (SEND_LOGIN/LOGOUT).

 ### Phase 4 — Polish (nice to have)
 Connection-manager reconnect · sync request/response + retry-with-flood-fallback
-helpers · event filtering · more examples and tests.
+helpers · event filtering · TELEMETRY/Cayenne-LPP decode · more examples and tests.
+
+*(Phases 1 & 2 complete — see "Already implemented".)*

 ---