# meshcore_c vs meshcore_py — Feature Gap Analysis

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

## Summary

`meshcore_c` is a clean, portable C99 core + Arduino C++ wrapper for the MeshCore
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.

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.

---

## Already implemented (baseline)

Framing/RX assembler + resync · `app_start` · `device_query` → **DeviceInfo**
(incl. `ver`, `repeat` fw≥9, `path_hash_mode` fw≥10) · **SelfInfo** (incl.
`multi_acks`, `adv_loc_policy`, `telemetry_mode` base/loc/env) · get/set device
time · **CurrTime** · battery voltage (2-byte only) · channel get/set + PSK →
**ChannelInfo** · send channel text · **ChannelMsgRecv / ChannelDataRecv** ·
**ContactMsgRecv** (+ signature extraction for `txt_type=2`) · **V3** channel +
contact recv (SNR) · `send_txt_msg` / `send_cmd` (direct + CLI, CMD 2) ·
**MsgSent** parse (ack tag + suggested timeout) · `set_radio_params` ·
`get_stats` → **Stats** (core/radio/packets) · self-advert · auto-drain on
`MsgWaiting` (Arduino wrapper).

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)

### MINOR

#### 3. 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
`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).

#### 5. 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
`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
`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).

#### 8. 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.
- **GET_SELF_TELEMETRY**: local-node telemetry request + `TELEMETRY` parse.

### NICE TO HAVE
- Auto-reconnect / connection-manager logic in the Arduino wrapper.
- 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.
- Channel-log AES decryption (heavy; needs crypto — probably out of scope for
  the bare-metal core).
- Cayenne LPP telemetry decode (application layer / caller).
- More examples (chat, contacts sync, telemetry display) and more tests
  (contact parsing, error paths, edge cases).

---

## What meshcore_c does better than meshcore_py
- **Zero dependencies / no malloc / no I/O in the core** — drops into any C99
  target; transport is 100% external (Linux, ESP-IDF, STM32, Arduino, no `#ifdef`).
- **Build simplicity** — one `CMakeLists.txt`, a single `cc`, or `pio test`.
- **Struct-based, caller-owns-memory API**, with an Arduino wrapper that
  auto-drains the radio queue on `MsgWaiting`.

---

## 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)
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.

### Phase 4 — Polish (nice to have)
Connection-manager reconnect · sync request/response + retry-with-flood-fallback
helpers · event filtering · more examples and tests.

---

*Compared against [meshcore_py](https://github.com/meshcore-dev/meshcore_py),
HEAD as of 2026-06-08. Protocol codes cross-checked against meshcore.js
`constants.js` and meshcore_py `packets.py`.*