# meshcore_c vs meshcore_py — Feature Gap Analysis

Date: 2026-06-08 (Phase 1 + 2 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`, `contacts`), ESP-IDF,
STM32 HAL, and Arduino.

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.

---

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

**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

*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

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

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

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

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

#### 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) · `TELEMETRY` push (0x8B, Cayenne LPP) · `PATH_DISCOVERY` (0x8D) ·
`CONTROL_DATA` push (0x8E).

#### 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.
- **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) — 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).
- 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 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 ·
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 · TELEMETRY/Cayenne-LPP decode · more examples and tests.

*(Phases 1 & 2 complete — see "Already implemented".)*

---

*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`.*