sdrangel/modemmeshtastic/README.md

# Meshtastic port payload reference

This note summarizes Meshtastic port names used by SDRangel packet decoding and what payload kind to expect.

Scope:
- Port names and IDs come from the local map in `meshtasticpacket.cpp` (`kPortMap`).
- Payload types are practical expectations based on Meshtastic app semantics.
- SDRangel currently does **generic** data decode only (header + protobuf envelope fields + raw payload), not per-port protobuf decoding.

## How to interpret payload display in SDRangel

- Text is shown only when payload bytes look like valid UTF-8.
- Otherwise payload is shown as hex.
- For most ports (POSITION, NODEINFO, TELEMETRY, ROUTING, etc.), payload is protobuf/binary, so hex is the normal representation.
- Seeing a mix of readable text and binary garbage (for example NODEINFO_APP showing the node name) is normal: protobuf stores `string` fields as raw UTF-8 bytes inline in the binary stream. The readable parts are string field values; the surrounding bytes are protobuf field tags (varints), numeric IDs, and other binary-encoded fields.

## Port list (current SDRangel map)

| Port name | ID | Expected payload kind | Typical content | SDRangel decode level |
|---|---:|---|---|---|
| UNKNOWN_APP | 0 | binary/unknown | unspecified | envelope + raw payload |
| TEXT / TEXT_MESSAGE_APP | 1 | UTF-8 text | plain chat text | envelope + text/hex payload |
| REMOTE_HARDWARE_APP | 2 | protobuf/binary | remote hardware control messages | envelope + raw payload |
| POSITION_APP | 3 | protobuf/binary | GPS position fields | envelope + raw payload |
| NODEINFO_APP | 4 | protobuf/binary | node metadata / identity (long name, short name, hardware model, node ID) | envelope + raw payload. Node name strings appear in clear because protobuf stores `string` fields as raw UTF-8 bytes; surrounding bytes are binary (field tags, varint IDs, enums). |
| ROUTING_APP | 5 | protobuf/binary | routing/control data | envelope + raw payload |
| ADMIN_APP | 6 | protobuf/binary | admin/config operations | envelope + raw payload |
| TEXT_MESSAGE_COMPRESSED_APP | 7 | compressed/binary | compressed text payload | envelope + raw payload |
| WAYPOINT_APP | 8 | protobuf/binary | waypoint structures | envelope + raw payload |
| AUDIO_APP | 9 | binary | encoded audio frames | envelope + raw payload |
| DETECTION_SENSOR_APP | 10 | protobuf/binary | sensor detection events | envelope + raw payload |
| ALERT_APP | 11 | protobuf/binary | alert/notification message | envelope + raw payload |
| KEY_VERIFICATION_APP | 12 | protobuf/binary | key verification/signaling | envelope + raw payload |
| REPLY_APP | 32 | protobuf/binary | reply wrapper/ack data | envelope + raw payload |
| IP_TUNNEL_APP | 33 | binary | tunneled IP packet bytes | envelope + raw payload |
| PAXCOUNTER_APP | 34 | protobuf/binary | pax counter telemetry | envelope + raw payload |
| STORE_FORWARD_PLUSPLUS_APP | 35 | protobuf/binary | store-and-forward control/data | envelope + raw payload |
| NODE_STATUS_APP | 36 | protobuf/binary | node status information | envelope + raw payload |
| SERIAL_APP | 64 | binary | serial tunnel bytes | envelope + raw payload |
| STORE_FORWARD_APP | 65 | protobuf/binary | store-and-forward messages | envelope + raw payload |
| RANGE_TEST_APP | 66 | protobuf/binary | range test metadata/results | envelope + raw payload |
| TELEMETRY_APP | 67 | protobuf/binary | telemetry records | envelope + raw payload |
| ZPS_APP | 68 | protobuf/binary | ZPS-specific messages | envelope + raw payload |
| SIMULATOR_APP | 69 | protobuf/binary | simulator-generated messages | envelope + raw payload |
| TRACEROUTE_APP | 70 | protobuf/binary | traceroute path/hops | envelope + raw payload |
| NEIGHBORINFO_APP | 71 | protobuf/binary | neighbor table entries | envelope + raw payload |
| ATAK_PLUGIN | 72 | protobuf/binary | ATAK integration payloads | envelope + raw payload |

## Notes

- This is a practical operator reference, not a protocol authority.
- For authoritative and exhaustive app payload schemas, use Meshtastic upstream protobuf definitions (for example `portnums.proto` and related message protos).
- If SDRangel later adds per-port protobuf decoding, this table should be updated with "decoded fields available" per port.

## Protocol availability and per-port decoding

The Meshtastic protocol is fully public and open-source (GPL v3, same license as SDRangel).

- Full `.proto` definitions: https://github.com/meshtastic/protobufs
- Browsable API reference with all message types and fields: https://buf.build/meshtastic/protobufs
- Protocol architecture doc: https://meshtastic.org/docs/overview/mesh-algo/

Key message types relevant to SDRangel decoding:

| Proto message | Port | Fields of interest |
|---|---|---|
| `Position` | POSITION_APP (3) | latitude, longitude, altitude, time, speed, heading |
| `User` | NODEINFO_APP (4) | id (node ID string), long_name, short_name, hw_model, is_licensed |
| `Routing` | ROUTING_APP (5) | route success/failure error codes |
| `Data` | (envelope, already decoded) | portnum, payload, want_response, dest, source |
| `Telemetry` | TELEMETRY_APP (67) | device metrics (battery, voltage, utilization), environment (temp, humidity), air quality |
| `RouteDiscovery` | TRACEROUTE_APP (70) | route (node ID list), snr_towards, snr_back |
| `NeighborInfo` | NEIGHBORINFO_APP (71) | node_id, node_broadcast_interval_secs, neighbors list |
| `Waypoint` | WAYPOINT_APP (8) | id, latitude, longitude, expire, locked_to, name, description |

### Adding per-port decoding to SDRangel

Three practical approaches (in order of fit for this codebase):

1. **Extend the existing hand-parser** — `meshtasticpacket.cpp` already contains a minimal protobuf varint/length-delimited parser for the `Data` envelope. The same approach can be extended per-port for common types (POSITION, NODEINFO, TELEMETRY) with no extra dependency. Best choice for portability and minimal build impact.

2. **nanopb** — the C library used by Meshtastic firmware itself; tiny footprint, no external runtime, generates `.pb.c`/`.pb.h` from the upstream `.proto` files. Would require adding it to `CMakeLists.txt` as a dependency.

3. **Qt Protobuf** (`QProtobufSerializer`) — available in Qt 6.5+. Adds a Qt version constraint that may conflict with Qt5 builds.