mirror of
https://github.com/vicliu624/trail-mate.git
synced 2026-09-26 21:57:55 +00:00
75 lines
4.4 KiB
Markdown
75 lines
4.4 KiB
Markdown
# Packet Structure
|
|
|
|
| Field | Size (bytes) | Description |
|
|
|-----------------|----------------------------------|-----------------------------------------------------------|
|
|
| header | 1 | Contains routing type, payload type, and payload version. |
|
|
| transport_codes | 4 (optional) | 2x 16-bit transport codes (if ROUTE_TYPE_TRANSPORT_*) |
|
|
| path_len | 1 | Packed path descriptor: upper bits encode hash width, lower 6 bits encode hop count. |
|
|
| path | up to 64 (`MAX_PATH_SIZE`) | Stores the routing path if applicable. |
|
|
| payload | up to 184 (`MAX_PACKET_PAYLOAD`) | The actual data being transmitted. |
|
|
|
|
Note: see the [payloads doc](./payloads.md) for more information about the content of payload.
|
|
Trail Mate's complete V2 multibyte path/profile rules are defined in
|
|
[V2 multibyte paths](./v2_multibyte_paths.md).
|
|
|
|
The wire `path_len` byte follows upstream MeshCore's packed descriptor:
|
|
|
|
```text
|
|
bits 7-6: path hash size minus one
|
|
bits 5-0: path hop count
|
|
path byte length = (hash_size) * (hop_count)
|
|
```
|
|
|
|
Trail Mate helper APIs expose `ParsedPacket::path_len` as the decoded path byte
|
|
length. Code that writes the wire envelope must use the shared path descriptor
|
|
helpers rather than storing the decoded byte length directly.
|
|
|
|
## Header Breakdown
|
|
|
|
bit 0 means the lowest bit (1s place)
|
|
|
|
| Bits | Mask | Field | Description |
|
|
|-------|--------|-----------------|-----------------------------------------------|
|
|
| 0-1 | `0x03` | Route Type | Flood, Direct, Reserved - see below. |
|
|
| 2-5 | `0x3C` | Payload Type | Request, Response, ACK, etc. - see below. |
|
|
| 6-7 | `0xC0` | Payload Version | Versioning of the payload format - see below. |
|
|
|
|
## Route Type Values
|
|
|
|
| Value | Name | Description |
|
|
|--------|-------------------------------|--------------------------------------|
|
|
| `0x00` | `ROUTE_TYPE_TRANSPORT_FLOOD` | Flood routing mode + transport codes |
|
|
| `0x01` | `ROUTE_TYPE_FLOOD` | Flood routing mode (builds up path). |
|
|
| `0x02` | `ROUTE_TYPE_DIRECT` | Direct route (path is supplied). |
|
|
| `0x03` | `ROUTE_TYPE_TRANSPORT_DIRECT` | direct route + transport codes |
|
|
|
|
## Payload Type Values
|
|
|
|
| Value | Name | Description |
|
|
|--------|---------------------------|-----------------------------------------------|
|
|
| `0x00` | `PAYLOAD_TYPE_REQ` | Request (destination/source hashes + MAC). |
|
|
| `0x01` | `PAYLOAD_TYPE_RESPONSE` | Response to REQ or ANON_REQ. |
|
|
| `0x02` | `PAYLOAD_TYPE_TXT_MSG` | Plain text message. |
|
|
| `0x03` | `PAYLOAD_TYPE_ACK` | Acknowledgment. |
|
|
| `0x04` | `PAYLOAD_TYPE_ADVERT` | Node advertisement. |
|
|
| `0x05` | `PAYLOAD_TYPE_GRP_TXT` | Group text message (unverified). |
|
|
| `0x06` | `PAYLOAD_TYPE_GRP_DATA` | Group datagram (unverified). |
|
|
| `0x07` | `PAYLOAD_TYPE_ANON_REQ` | Anonymous request. |
|
|
| `0x08` | `PAYLOAD_TYPE_PATH` | Returned path. |
|
|
| `0x09` | `PAYLOAD_TYPE_TRACE` | trace a path, collecting SNI for each hop. |
|
|
| `0x0A` | `PAYLOAD_TYPE_MULTIPART` | packet is part of a sequence of packets. |
|
|
| `0x0B` | `PAYLOAD_TYPE_CONTROL` | control packet data (unencrypted) |
|
|
| `0x0C` | . | reserved |
|
|
| `0x0D` | . | reserved |
|
|
| `0x0E` | . | reserved |
|
|
| `0x0F` | `PAYLOAD_TYPE_RAW_CUSTOM` | Custom packet (raw bytes, custom encryption). |
|
|
|
|
## Payload Version Values
|
|
|
|
| Value | Version | Description |
|
|
|--------|---------|---------------------------------------------------|
|
|
| `0x00` | 1 | 1-byte src/dest hashes, 2-byte MAC. |
|
|
| `0x01` | 2 | 2-byte hashes, 4-byte MAC; paths use 2 bytes per hop. |
|
|
| `0x02` | 3 | Future version. |
|
|
| `0x03` | 4 | Future version. |
|