Core Protocol Specification — Part 1: The Protocol (RF Network Layer) ¶

Version: 1.0 (Draft) Status: Derived from ZephCore firmware implementation, cross-referenced with MeshCore reference firmware and documentation. Scope: This document defines The Protocol — the RF network protocol used by nodes to communicate over a LoRa mesh. It specifies packet format, routing, payload structures, and cryptography.

Companion document: The host-side protocol used by applications to control and query a node over a local transport (serial/USB, Bluetooth Low Energy, or TCP) is defined separately in Core Protocol Specification — Part 2: The Companion Protocol (Host Layer). This document and the Companion Protocol document share the conventions defined in §1.

This document is written to be implementation-agnostic. Field names, constants, and structures are described in neutral terms, not tied to any specific language or firmware. Where pseudo-code is provided, it is illustrative only.

Table of Contents ¶

• 1. Conventions and Terminology
• 2. The Protocol (RF Network Layer)
  • 2.1. Packet Structure
  • 2.2. Header Encoding
  • 2.3. Route Types
  • 2.4. Transport Codes
  • 2.5. Path Encoding
  • 2.6. Payload Types
  • 2.7. Cryptography
  • 2.8. Advertisement Payload
  • 2.9. Direct-Encrypted Payloads (Request / Response / Text / Path)
  • 2.10. Anonymous Request Payload
  • 2.11. Group Payloads
  • 2.12. Acknowledgement Payload
  • 2.13. Trace Payload
  • 2.14. Multipart Payload
  • 2.15. Control Payload
  • 2.16. Raw Custom Payload
  • 2.17. Routing and Forwarding Rules
  • 2.18. Duplicate Suppression
• Appendix A: Compliance Checklist
• Appendix B: Constants Summary
• Appendix C: Known Discrepancies Between Documentation and Implementation

1. Conventions and Terminology ¶

1.1. Notation ¶

• 0x prefix denotes hexadecimal. Example: 0x80 = 128 decimal.
• 0b prefix denotes binary. Example: 0b0110 = 6 decimal.
• Bit positions count from the least-significant bit as bit 0. A byte 0bABCDEFGH has A as bit 7 and H as bit 0.
• Byte ranges are inclusive on both ends. “bytes 4–7” means four bytes at offsets 4, 5, 6, 7.
• Field sizes are expressed in bytes unless noted otherwise.

1.2. Byte Order ¶

• All multi-byte integer fields are little-endian unless explicitly stated otherwise.
• Cryptographic outputs (hashes, signatures, MACs, public keys) are byte sequences and are not re-ordered — they are transmitted in the order produced by the underlying algorithm.
• The CayenneLPP format used for sensor data is the exception: it is big-endian (per the CayenneLPP specification).

1.3. Strings ¶

• All textual fields (names, messages, passwords) are UTF-8 encoded.
• Fixed-size text fields are padded with null bytes (0x00) on the right when shorter than the field size.
• Variable-length text fields at the end of a payload are not null-terminated on the wire; their length is implied by the remaining payload length.

1.4. Terminology ¶

• Node — any device participating in the mesh.
• Contact — a known peer node, identified by its Ed25519 public key.
• Advert — an advertisement packet broadcast by a node to announce its presence.
• Path — an ordered list of node hashes representing a route through the mesh.
• Node hash — a short prefix of a node’s public key used for routing. One, two, or three bytes; the length is selected per-packet.
• Channel hash — a one-byte identifier for a group channel, derived from the channel secret.
• Direct routing — the packet travels along a pre-known path, hop-by-hop.
• Flood routing — the packet is rebroadcast by every node that hears it (with deduplication).
• Transport codes — optional 4-byte region/scope identifier that filters which nodes will rebroadcast.
• MAC — a 2-byte HMAC-SHA256 prefix used as a message authentication code.
• MTU — Maximum Transmission Unit; the largest physical-layer payload the radio can carry.
• Companion — a host application (phone, PC, embedded controller) that manages a node over a local link.
• Push notification (or “push”) — an unsolicited message from the node to the companion.

1.5. Protocol Layering ¶

A compliant implementation consists of three layers:

┌─────────────────────────────────────────────────────┐
│  Application (contacts, channels, messaging, UI)    │
├─────────────────────────────────────────────────────┤
│  The Companion Protocol (host ↔ node)               │  ← Part 2 (companion document)
├─────────────────────────────────────────────────────┤
│  The Protocol (RF network)                          │  ← this document (Part 1)
├─────────────────────────────────────────────────────┤
│  Physical Layer (LoRa radio)                        │
└─────────────────────────────────────────────────────┘

The Protocol and the Companion Protocol are independent. A node that speaks only The Protocol (e.g., a repeater with no host interface) is compliant. A host library that speaks only the Companion Protocol (without touching the radio) is compliant. The two are bridged by the node firmware.

2. The Protocol (RF Network Layer) ¶

This part specifies the packet format, routing, payload structures, and cryptography used by nodes to communicate over the LoRa RF mesh.

2.1. Packet Structure ¶

Every packet transmitted over the air has the following layout:

┌──────────┬─────────────────────┬─────────────┬──────┬──────────┐
│  header  │  transport_codes    │ path_length │ path │ payload  │
│  1 byte  │ 4 bytes (optional)  │   1 byte    │  V   │    V     │
└──────────┴─────────────────────┴─────────────┴──────┴──────────┘

2.1.1. Size Limits ¶

Receivers MUST drop any packet whose payload length exceeds MAX_PACKET_PAYLOAD or whose total length exceeds MAX_TRANS_UNIT. Receivers MUST drop packets whose path byte-length exceeds MAX_PATH_SIZE.

2.2. Header Encoding ¶

The header byte packs three fields:

  bit 7   6   5   4   3   2   1   0
      │   │   │           │   │   │
      └─┬─┘   └─────┬─────┘   └─┬─┘
        │           │           │
     Payload     Payload      Route
     Version     Type         Type
     (2 bits)    (4 bits)     (2 bits)

2.2.1. Payload Version ¶

The current specification defines only version 1. Versions 2–4 are reserved.

Nodes implementing this specification MUST emit version 1 only. Nodes MUST ignore packets whose payload version is unknown.

2.2.2. Sentinel Header Value ¶

The value 0xFF for the entire header byte is reserved as a local in-memory “do not retransmit” marker. It MUST NOT appear on the wire. Receivers that see 0xFF on the wire MUST drop the packet.

2.3. Route Types ¶

The low 2 bits of header specify how the packet is routed.

• Flood packets are rebroadcast by every node that hears them, subject to deduplication and forwarding policy.
• Direct packets are rebroadcast only by the node whose hash matches the next entry in the path.
• Transport variants include a 4-byte transport_codes field (§2.4) used to scope forwarding to a region or subnetwork.
• A zero-hop packet is a direct-routed packet with path_length = 0; it is not forwarded at all.

2.4. Transport Codes ¶

When the route type is ROUTE_TYPE_TRANSPORT_FLOOD or ROUTE_TYPE_TRANSPORT_DIRECT, the header is immediately followed by four bytes:

2.4.1. Transport Code Derivation ¶

A transport code is computed from a 16-byte transport key and the packet’s payload:

message   = payload_type_byte || payload
hmac      = HMAC-SHA256(key = transport_key, data = message)
code      = (hmac[0]) | (hmac[1] << 8)            # little-endian 16-bit
if code == 0x0000:  code = 0x0001                 # reserved
if code == 0xFFFF:  code = 0xFFFE                 # reserved

The codes 0x0000 and 0xFFFF are reserved and MUST NOT appear on the wire; implementations MUST coerce them to 0x0001 and 0xFFFE respectively.

A node that does not share a given transport key cannot verify a matching transport code and therefore MUST NOT forward transport-scoped packets whose code does not match any of its loaded transport keys.

transport_code_2 is reserved; senders MUST set it to 0x0000 and receivers MUST accept any value without treating it as a match criterion.

2.5. Path Encoding ¶

The path_length byte encodes two fields:

  bit 7   6   5   4   3   2   1   0
      │   │   │   │   │   │   │   │
      └─┬─┘   └───────┬───────────┘
        │             │
  Hash Size       Hop Count
  Code (2 bits)   (6 bits, 0–63)

The on-wire path field is exactly hop_count × hash_size bytes. Receivers MUST compute the byte length from these two values; the path_length byte is NOT a raw byte count.

2.5.1. Path Examples ¶

2.5.2. Validity ¶

A path_length byte is valid if and only if:

• The hash size code is not 0b11, and
• hop_count × hash_size ≤ MAX_PATH_SIZE (64).

Receivers MUST drop packets with invalid path_length.

2.5.3. Node Hash Derivation ¶

A node hash of size N is the first N bytes of the node’s Ed25519 public key. All nodes in a given path-hash-mode deployment MUST use the same hash size for a packet’s path field.

2.6. Payload Types ¶

Bits 2–5 of header specify the payload type. The payload structure for each type is defined in sections 2.8–2.16.

2.7. Cryptography ¶

The following primitives are used in The Protocol:

2.7.1. Identity ¶

Each node has an Ed25519 keypair:

• Public key: 32 bytes.
• Private key: 64 bytes (expanded form). Some implementations store only a 32-byte seed and derive the 64-byte private key on demand; this is permitted.

The node hash used in paths and routing is a 1, 2, or 3-byte prefix of the public key (§2.5.3).

2.7.2. Shared Secret ¶

The shared secret between two nodes is derived by X25519 key exchange on their Ed25519 keypairs:

shared_secret = X25519(my_private_key, their_public_key)    # 32 bytes

Both sides produce the same 32-byte secret.

2.7.3. Encryption ¶

AES-128-ECB with zero padding. The first 16 bytes of the 32-byte shared secret are used as the AES key.

Plaintext is padded with zero bytes up to a multiple of 16. Ciphertext length equals padded plaintext length.

aes_key   = shared_secret[0..16]                           # first 16 bytes
padded    = plaintext || zero_pad_to_multiple_of(16)
ciphertext = AES-128-ECB-encrypt(aes_key, padded)

Decryption reverses the process. The receiver cannot distinguish trailing zero bytes added by padding from trailing zero bytes in the original plaintext; application payloads either carry an internal length field or tolerate trailing zeros.

2.7.4. Message Authentication Code (MAC) ¶

The MAC is the first 2 bytes of HMAC-SHA256 computed over the ciphertext, using the full 32-byte shared secret as the HMAC key.

mac = HMAC-SHA256(key = shared_secret, data = ciphertext)[0..2]

Wire format for an encrypted region is mac || ciphertext (MAC first, then ciphertext). Receivers MUST verify the MAC before decrypting; packets with mismatched MACs MUST be silently dropped.

Note on the HMAC key: The HMAC key uses the full 32-byte shared secret, even though the AES key uses only the first 16 bytes. Implementations that truncate the HMAC key to 16 bytes will not interoperate.

2.7.5. Channel Key Derivation ¶

A group channel has a symmetric secret. The secret is either 16 or 32 bytes:

• A 16-byte secret is used both as the AES key and as the HMAC key (zero-padded to 32 bytes implicitly by HMAC processing).
• A 32-byte secret uses its first 16 bytes as the AES key and the full 32 bytes as the HMAC key.

The 1-byte channel hash used on the wire is:

channel_hash = SHA-256(channel_secret)[0]    # first byte

Where channel_secret is the raw 16-byte (or 32-byte) secret bytes.

2.7.6. Well-Known Channel Keys ¶

• Public channel: a well-known 16-byte key shared by all devices for the default open channel. The canonical value is defined by the ecosystem; see reference implementations.
• Hashtag channel for a name #tag: the first 16 bytes of SHA-256("#tag").
• Private channel: a randomly generated 16-byte secret shared out-of-band.

2.8. Advertisement Payload ¶

Payload type PAYLOAD_TYPE_ADVERT (0x04). Broadcast by every node to announce its presence. The payload is not encrypted but is signed by the advertising node.

┌───────────────┬───────────┬───────────┬────────────┐
│  public_key   │ timestamp │ signature │  app_data  │
│    32 bytes   │  4 bytes  │ 64 bytes  │ 0–32 bytes │
└───────────────┴───────────┴───────────┴────────────┘

The maximum app_data length is MAX_ADVERT_DATA_SIZE = 32 bytes. Receivers MUST clip app_data to 32 bytes if the payload length suggests otherwise.

2.8.1. Signature Verification ¶

A receiver verifies the signature by computing:

message = public_key || timestamp || app_data
valid   = Ed25519-verify(signature, message, public_key)

Receivers MUST drop adverts with invalid signatures.

2.8.2. app_data Structure ¶

When present, app_data begins with a flags byte that indicates which optional fields follow:

┌───────┬───────────┬───────────┬──────────┬──────────┬─────────────────┐
│ flags │ latitude  │ longitude │ feature1 │ feature2 │      name       │
│ 1 byte│ 4 (opt)   │ 4 (opt)   │ 2 (opt)  │ 2 (opt)  │ 0–N bytes (opt) │
└───────┴───────────┴───────────┴──────────┴──────────┴─────────────────┘

Fields appear in the listed order; each is present if and only if the corresponding flag bit is set. The name field, if present, fills the remainder of app_data.

2.8.3. flags Byte ¶

The flags byte is split into a 4-bit node type (low nibble) and 4 presence flag bits (high nibble).

Node Type values (low 4 bits):

Clarification: Earlier documentation listed the node-type values among the presence flag bits, which is incorrect. They occupy the low 4 bits of the flags byte. The high 4 bits are the presence flags.

2.8.4. Location Encoding ¶

If the Has Location flag is set:

Example: latitude = 49123456 encodes 49.123456°.

2.8.5. Name ¶

If the Has Name flag is set, all remaining bytes of app_data are the UTF-8 node name. There is no null terminator on the wire.

2.9. Direct-Encrypted Payloads (Request / Response / Text / Path) ¶

Payload types PAYLOAD_TYPE_REQ (0x00), PAYLOAD_TYPE_RESPONSE (0x01), PAYLOAD_TYPE_TXT_MSG (0x02), and PAYLOAD_TYPE_PATH (0x08) share a common wrapper:

┌──────────────────┬─────────────┬──────┬────────────┐
│ destination_hash │ source_hash │ mac  │ ciphertext │
│     1 byte       │   1 byte    │  2   │   variable │
└──────────────────┴─────────────┴──────┴────────────┘

The shared secret used for encryption and MAC is derived between the source and destination via X25519 (§2.7.2).

2.9.1. Receiver Processing ¶

When a node receives a packet with one of these payload types:

1. If destination_hash does not match any of the node’s own hashes, treat as not-for-me (but may still forward per routing rules).
2. For each known peer whose source_hash matches, derive the shared secret, verify the MAC, decrypt. If MAC verification succeeds, process the plaintext.
3. If no peer matches or no MAC verifies, the packet is either not for this node or is malformed; treat as not-for-me.

2.9.2. REQ Plaintext (Request) ¶

┌───────────┬───────────────────────┐
│ timestamp │     request_data      │
│  4 bytes  │  rest of plaintext    │
└───────────┴───────────────────────┘

• timestamp — sender’s Unix time in seconds (little-endian).
• request_data — application-defined request body. The first byte typically encodes a request sub-type.

Common request sub-types (first byte of request_data):

Other sub-types are application-defined and out of scope for this specification.

2.9.3. RESPONSE Plaintext ¶

┌───────────────────────────────────┐
│           response_data           │
│         rest of plaintext         │
└───────────────────────────────────┘

Responses are opaque to this layer. The format is determined by the application and the corresponding request.

2.9.4. TXT_MSG Plaintext ¶

┌───────────┬─────────────────┬─────────────────┐
│ timestamp │ txt_type_attempt│    message      │
│  4 bytes  │     1 byte      │ rest of plaintxt│
└───────────┴─────────────────┴─────────────────┘

The txt_type_attempt byte packs two fields:

Defined text types (after right-shift):

2.9.5. PATH Plaintext (Returned Path) ¶

A path-return packet communicates a discovered route back to an originator.

┌─────────────┬──────────┬────────────┬────────────────┐
│ path_length │   path   │ extra_type │  extra_payload │
│   1 byte    │ variable │   1 byte   │    variable    │
└─────────────┴──────────┴────────────┴────────────────┘

When extra_type is 0xFF (no extra), senders MUST follow it with 4 random bytes. This prevents the encrypted block from being a known-plaintext target.

2.10. Anonymous Request Payload ¶

Payload type PAYLOAD_TYPE_ANON_REQ (0x07). Used when the sender is not yet a known contact of the destination; the sender includes their full public key inline so the destination can derive a shared secret.

┌──────────────────┬────────────────┬──────┬────────────┐
│ destination_hash │ sender_pubkey  │ mac  │ ciphertext │
│     1 byte       │    32 bytes    │  2   │   variable │
└──────────────────┴────────────────┴──────┴────────────┘

The destination derives the shared secret via X25519 between its own private key and the inline sender_pubkey, then MAC-verifies and decrypts.

2.10.1. Common Anonymous-Request Plaintext Formats ¶

The plaintext format depends on the use case. Common examples:

Room-server login:

┌───────────┬────────────────┬──────────┐
│ timestamp │ sync_timestamp │ password │
│  4 bytes  │    4 bytes     │ variable │
└───────────┴────────────────┴──────────┘

• timestamp — sender time (Unix seconds, little-endian).
• sync_timestamp — “sync messages since” epoch (Unix seconds, little-endian).
• password — UTF-8 password for the room.

Repeater / sensor login:

┌───────────┬──────────┐
│ timestamp │ password │
│  4 bytes  │ variable │
└───────────┴──────────┘

Repeater sub-request (regions / owner info / clock-and-status):

┌───────────┬──────────┬────────────────┬────────────┐
│ timestamp │ req_type │ reply_path_len │ reply_path │
│  4 bytes  │  1 byte  │     1 byte     │  variable  │
└───────────┴──────────┴────────────────┴────────────┘

Where req_type is 0x01 (regions), 0x02 (owner info), or 0x03 (clock and status). The reply_path uses the same encoding as §2.5.

Other plaintext formats are application-defined.

2.10.2. Repeater Sub-Request Responses ¶

Responses to the repeater sub-requests defined in §2.10.1 are delivered as a PAYLOAD_TYPE_RESPONSE payload (§2.9.3), encrypted with the same shared secret used for the request (§2.7.2). A receiver without the relevant shared secret cannot recover any of the fields described below — only the destination/source hashes and ciphertext length are visible on the wire.

If the original request arrived as ROUTE_TYPE_FLOOD, the response is wrapped in a PATH payload (§2.9.5) addressed back along the path the request travelled, so the requester also learns a route to the responder. If the request arrived as ROUTE_TYPE_DIRECT with an explicit reply path already supplied in the request body (see §2.10.1), the response is sent directly along that path instead.

All three sub-request responses share an 8-byte preamble:

Both timestamp fields are little-endian uint32, consistent with §1.2.

Despite its name in the reference firmware (“prefix with sender_timestamp, like a tag”), reflected_tag is not a freshly generated tag — it is the requester’s own timestamp, reflected back, serving the same correlation role as tag does in DISCOVER_RESP (§2.15.2). responder_time is the responder’s clock in Unix seconds, included both for opportunistic clock sync and to vary the packet hash across replies to structurally identical requests.

2.10.2.1. Regions Response (req_type = 0x01) ¶

The body is a UTF-8 string, not null-terminated on the wire, listing the responder’s configured transport scopes (“regions”) as comma-separated names — for example: NORTHEAST,SOUTHWEST. The string length is implied by the remaining payload length, per the general convention in §1.3.

A bare * entry represents the responder’s wildcard/default scope (the scope applied to packets that don’t match any more specific transport key). It is included under the same inclusion rule as every other region — see below — not unconditionally.

Inclusion rule. A region (including the wildcard) is included in the response if and only if it does not have its flood-deny flag set (reference firmware: REGION_DENY_FLOOD, value 0x01, checked against each region’s flags byte). This means a responder configured to deny flood-forwarding for a particular scope omits that scope’s name from the regions response entirely — even if the scope is otherwise configured and actively used for direct-routed traffic. Implementations querying this response to enumerate all configured scopes (not just flood-eligible ones) should be aware this response under-reports relative to the responder’s full configuration.

Name normalization. Region names that begin with # in the responder’s local configuration have that prefix stripped before being included in the response; the # is a local naming convention (its own meaning is out of scope for this section) and is never transmitted.

Name length and truncation. Each region name is at most 30 characters in the reference implementation (RegionEntry.name is a 31-byte buffer, one byte reserved for a null terminator that is never itself transmitted). The overall response is bounded by MAX_PACKET_PAYLOAD (184 bytes, §2.1.1) minus the 8-byte preamble and a 4-byte safety margin reserved by the reference implementation (12 bytes total). A responder with enough configured regions that the full comma-separated list would not fit truncates silently: names are appended one at a time only while they still fit, and the response is returned with however many fit, dropping the rest without any truncation indicator. Implementations should not assume a regions response that fills (or nearly fills) the available space represents the complete list.

Rate limiting. The reference implementation rate-limits responses to this sub-request (shared with owner-info and clock-and-status — see §2.10.2.4) to at most 4 responses per any 180-second rolling window, on top of any per-anon-request channel limits already implied by §2.10. A request arriving while the limiter is exhausted receives no response at all (not an error response); requesters should be prepared to retry after a delay rather than treating silence as “no regions configured.”

2.10.2.2. Owner Info Response (req_type = 0x02) ¶

The body is two UTF-8 strings joined by a single \n (0x0A) byte: the responder’s configured node name, followed by its configured owner-info text. Neither component is independently length-prefixed; a consuming implementation splits on the first \n byte. The combined string is not null-terminated on the wire; its length is implied by the remaining payload length.

In the reference implementation, the node name component is sourced from a 32-byte (including null terminator) configuration field and the owner-info component from a 120-byte (including null terminator) field, so the practical maximum combined length is approximately 150 characters — comfortably within MAX_PACKET_PAYLOAD once the 8-byte preamble is accounted for, and unlike the regions response, this response has no documented truncation behavior in the reference implementation (the two source fields are themselves bounded at configuration time, not at response-construction time).

2.10.2.3. Clock-and-Status Response (req_type = 0x03) ¶

The body is exactly one byte: a features/status flags byte.

Note on bit overlap: This flags byte does not follow the clean “each bit is independent” convention used elsewhere in this specification (e.g. the advert presence flags in §2.8.3). The UART and ESP-NOW bridge indicators overlap at bit 0 and are mutually exclusive in the reference firmware (selected at compile time): a value of 0x03 means ESP-NOW, not “both bridges” with bit 1 set independently. Implementations should treat 0x00 (no bridge), 0x01 (UART bridge), and 0x03 (ESP-NOW bridge) as the three valid low-bit states rather than decoding bit 0 and bit 1 independently.

A comment in the reference implementation notes a planned but unimplemented “moving-window utilization metric” field; no such field exists in the current wire format, and implementations should not expect one until a future protocol revision documents it.

2.10.2.4. Shared Rate Limiting ¶

All three sub-request types (§2.10.2.1–§2.10.2.3) draw from the same rate limiter in the reference implementation: at most 4 accepted requests per any rolling 180-second window, shared across regions, owner-info, and clock-and-status requests combined (not 4 of each). A responder that has exhausted this budget silently drops the request and sends no response, indistinguishable on the wire from a request that was lost in transit. Implementations should apply normal request timeout/retry handling rather than treating one missing response as conclusive evidence the responder doesn’t support the sub-request type.

2.11. Group Payloads ¶

Payload types PAYLOAD_TYPE_GRP_TXT (0x05) and PAYLOAD_TYPE_GRP_DATA (0x06). Used for channel (group) messaging with a pre-shared channel secret.

┌──────────────┬─────┬────────────┐
│ channel_hash │ mac │ ciphertext │
│   1 byte     │  2  │  variable  │
└──────────────┴─────┴────────────┘

The maximum plaintext length for group payloads is MAX_PACKET_PAYLOAD − 16 − 3 = 165 bytes (accounting for cipher block rounding, channel_hash, and mac).

2.11.1. GRP_TXT Plaintext ¶

Same format as TXT_MSG plaintext (§2.9.4). The convention is that the message body is of the form sender_name: message_body so receivers can display the sender.

2.11.2. GRP_DATA Plaintext ¶

Application-defined. The first byte typically identifies a data sub-type; the remainder is sub-type-specific data.

2.12. Acknowledgement Payload ¶

Payload type PAYLOAD_TYPE_ACK (0x03).

┌──────────┐
│ ack_hash │
│ 4 bytes  │
└──────────┘

The field is conventionally called a “checksum” in parts of the reference firmware, but it is NOT a CRC — it is the first 4 bytes (not a truncated CRC-32) of a SHA-256 digest, used as a short collision-resistant identifier of the specific message being acknowledged.

2.12.1. ACK Hash Computation ¶

The hash is computed over a buffer whose contents depend on the message type being acknowledged. The recipient or sender’s public key is appended to the hashed data to “salt” the hash — ensuring that different recipients of the same broadcast text produce different ACK hashes, so that senders can tell which peer acknowledged.

For TXT_MSG with txt_type == TXT_TYPE_PLAIN (0x00) or TXT_TYPE_CLI_DATA (0x01):

buffer    = timestamp (4 bytes LE)
          ∥ txt_type_attempt (1 byte)
          ∥ message_text (UTF-8, no terminator)
          ∥ sender_public_key (32 bytes)
ack_hash  = SHA-256(buffer)[0..4]        ; first 4 bytes

CLI-type messages (TXT_TYPE_CLI_DATA) MUST NOT produce an ACK on the wire despite being hashable. The sender does not track an expected hash for CLI messages; only TXT_TYPE_PLAIN triggers the full send/ack lifecycle.

For TXT_MSG with txt_type == TXT_TYPE_SIGNED_PLAIN (0x02):

buffer    = timestamp (4 bytes LE)
          ∥ txt_type_attempt (1 byte)
          ∥ sender_pubkey_prefix (4 bytes)
          ∥ message_text (UTF-8, no terminator)
          ∥ recipient_public_key (32 bytes)
ack_hash  = SHA-256(buffer)[0..4]        ; first 4 bytes

The sender’s 4-byte public-key prefix that appears at the start of a signed-plain plaintext (§2.9.4) participates in the hash; otherwise the hash input is identical in structure to the plain form.

Salting note. The public key is appended to the message bytes but is NOT transmitted as part of the hash input over the air — it is implicitly known to both sides (sender knows it from its contact record; recipient knows its own key). This turns the 4-byte ACK hash into a message-AND-recipient identifier, enabling the sender to match incoming ACKs even when the same message has been sent to multiple contacts.

2.12.2. Sender Expectations ¶

A sender that emits a TXT_MSG requesting acknowledgement SHOULD:

1. Compute the expected ack_hash using the public key at send time. NOTE The public key differs between TXT_TYPE_PLAIN and TXT_TYPE_SIGNED_PLAIN.
2. Store the expected hash in a pending-ack table, keyed to the recipient contact and a send timestamp.
3. On receipt of a PAYLOAD_TYPE_ACK whose 4-byte ack_hash matches a pending entry, mark the message as delivered and discard the entry.

The same ACK MAY be received multiple times if the acknowledging peer retransmits (e.g., via multi-ACK, §2.14); senders SHOULD tolerate this and treat only the first arrival as delivery confirmation.

2.12.3. CRC-32 Historical Note ¶

Earlier drafts of this specification described the ack_hash field as a little-endian CRC-32. That was incorrect. The reference firmware (BaseChatMesh.cpp:221-222, 248-249) uses SHA-256(...)[0..4] exclusively. An implementation that computes CRC-32 over the same input buffer will not match any valid ACK and will fail all deduplication checks.

2.13. Trace Payload ¶

Payload type PAYLOAD_TYPE_TRACE (0x09). Used to discover and measure a path through the mesh, collecting a per-hop SNR sample at each forwarding node.

TRACE packets use an unusual wire layout that repurposes fields from the normal packet structure. Three specific oddities distinguish TRACE from every other payload type:

1. The header’s path_length byte is a hop-consumption counter, not an encoded path-length (§2.5). The low 6 bits start at zero and increment by one at each forwarding hop as the packet travels. The top 2 bits of the byte remain zero; the actual per-hash byte size used for the hop sequence is carried in the flags byte of the payload instead.
2. The original hop-hash sequence is appended to the payload, after the 9-byte preamble — not placed in the header’s path field as with other direct-routed payloads. Forwarders never modify these hashes; they remain in the payload for the life of the packet.
3. The header’s path field accumulates SNR measurements, one signed byte per consumed hop, written at position path_length immediately before path_length is incremented. By the time the packet reaches its final destination, the header’s path buffer holds the sequence of measured link qualities in traversal order.

2.13.1. Payload Layout ¶

┌─────┬───────────┬───────┬────────────────────┐
│ tag │ auth_code │ flags │   path_hashes      │
│  4  │     4     │   1   │ variable (per hop) │
└─────┴───────────┴───────┴────────────────────┘

Flags byte:

Note that the TRACE flags’ path-hash-size encoding (1 << bits, values 1/2/4) differs from the encoding used in the normal packet header’s path_length byte (§2.5), which encodes hash sizes 1/2/3 as code + 1. TRACE’s encoding permits a 4-byte hash size that the normal header cannot represent.

2.13.2. Header Fields for TRACE ¶

The packet header fields adjacent to the payload carry protocol-repurposed meaning:

The header’s path field is thus written at byte positions (one per consumed hop), not at hash positions, even when path_hash_size > 1. This is valid because each SNR sample is always exactly one byte.

2.13.3. SNR Encoding ¶

Each accumulated SNR sample is a signed 8-bit integer representing measured_SNR_dB × 4 — i.e., 0.25 dB resolution, range approximately −32 to +31.75 dB. The same convention is used by PACKET_STATS and every place else SNR is carried in this protocol.

2.13.4. Trace Forwarding ¶

When a node receives a TRACE packet with route_type == ROUTE_TYPE_DIRECT:

1. Parse the payload preamble: tag, auth_code, flags. Extract path_sz = flags & 0x03.
2. Compute consumed_bytes = header.path_length × (1 << path_sz). This is the byte offset within the payload’s path_hashes trailer of the next hop hash to be checked.
3. If consumed_bytes ≥ path_hashes_length, the TRACE has consumed every hop: this node is the final destination. Deliver the trace (hashes + SNRs) to the application layer and do not forward.
4. Otherwise, compare the (1 << path_sz) bytes at path_hashes[consumed_bytes] against this node’s own public-key prefix. If they do not match, drop the packet (this node is not the expected next hop).
5. If they match, and forwarding policy permits, and the packet’s dedup signature is not already in the “seen” table: a. Append this node’s measured SNR byte ((int8)(measured_snr_dB × 4)) to the header’s path buffer at offset path_length. b. Increment the header’s path_length by 1. c. Retransmit.

Because only the header fields change during forwarding, the payload (including the original path_hashes) remains byte-stable across hops. This is what makes a TRACE packet useful: at the final destination, the receiver can hand both the original intended path and the measured per-hop SNRs to the application for analysis.

2.13.5. Deduplication Caveat ¶

Because TRACE packets mutate their header fields as they traverse the mesh, a naive packet-signature scheme that ignores the header (§2.17.5) would correctly deduplicate each hop. However, the specification in §2.17.5 explicitly includes path_length in the TRACE signature precisely to prevent the same trace from being forwarded twice along overlapping sub-paths (which could occur if the return path revisits an intermediate node). Implementations MUST follow §2.17.5.

2.13.6. Historical Note ¶

Earlier drafts of this specification stated that “SNR samples are in the payload” and described only a flat payload of tag + auth + flags + snr_samples. That description is inconsistent with the reference firmware, which:

• Keeps the original path_hashes in the payload (never modified by forwarders).
• Places the accumulated SNR bytes in the header path[] buffer, not the payload.
• Uses the header path_length field as a hop-consumption counter, not as its §2.5 encoded form.

The layout documented above reflects the actual wire behaviour of the reference firmware (see Mesh.cpp:41-65, Mesh.cpp:684-698).

2.14. Multipart Payload ¶

Payload type PAYLOAD_TYPE_MULTIPART (0x0A). A composite payload that encapsulates another payload plus a “remaining” counter. Currently used only for multi-ACK bursts.

┌─────────────────────────┬──────────────────────┐
│ remaining_and_subtype   │    sub_payload       │
│         1 byte          │      variable        │
└─────────────────────────┴──────────────────────┘

The leading byte packs:

For a multi-ACK:

• Sub-type = PAYLOAD_TYPE_ACK (0x03)
• Sub-payload = the 4-byte ACK checksum
• Total payload length = 5 bytes

2.15. Control Payload ¶

Payload type PAYLOAD_TYPE_CONTROL (0x0B). Carries unencrypted control data, typically for discovery.

┌───────┬─────────────────┐
│ flags │      data       │
│  1 B  │    variable     │
└───────┴─────────────────┘

The flags byte has two sub-fields:

Bit 7 of the flags byte (0x80) additionally signals that the control packet is valid only as a zero-hop direct packet; receivers MUST drop it if the packet’s hop count is not zero.

2.15.1. DISCOVER_REQ (sub-type 0x8) ¶

┌───────┬─────────────┬──────┬──────────────┐
│ flags │ type_filter │ tag  │    since     │
│  1 B  │    1 B      │  4 B │  4 B (opt)   │
└───────┴─────────────┴──────┴──────────────┘

• flags = 0x80 | 0x01 if prefix-only reply is requested.
• type_filter — bitfield. Bit n set means the sender wants responses from ADV_TYPE_n nodes.
• tag — random identifier, reflected in responses.
• since — optional 4-byte Unix timestamp; responders with a last-advert-time earlier than this SHOULD NOT respond. Omitted means 0.

2.15.2. DISCOVER_RESP (sub-type 0x9) ¶

┌───────┬──────┬──────┬──────────────────┐
│ flags │ snr  │ tag  │     pubkey       │
│  1 B  │ 1 B  │  4 B │    8 or 32 B     │
└───────┴──────┴──────┴──────────────────┘

• flags — high nibble = 0x9, low nibble = responder’s ADV_TYPE_*.
• snr — signed 8-bit SNR of the request packet (SNR × 4, 0.25 dB units).
• tag — echoed from the request.
• pubkey — 32-byte full public key, or 8-byte prefix if the request’s prefix-only bit was set.

2.16. Raw Custom Payload ¶

Payload type PAYLOAD_TYPE_RAW_CUSTOM (0x0F). The payload is opaque to the network layer; the application is responsible for any framing, encryption, and authentication. Raw packets are handled only in direct routing mode.

2.17. Routing and Forwarding Rules ¶

2.17.1. Flood Routing ¶

When a node sends a flood packet:

1. The route type is set to ROUTE_TYPE_FLOOD (or ROUTE_TYPE_TRANSPORT_FLOOD with appropriate codes).
2. The sender’s own hash is not appended to path; the hop_count is 0 when transmitted.
3. The packet’s deduplication signature is recorded locally.
4. The packet is broadcast.

When a node receives a flood packet:

1. Validate path_length. Drop if invalid.
2. Check the deduplication table (§2.18). If already seen, drop.
3. Process the payload (decrypt/verify/etc.) to the extent the node is able.
4. If the node’s forwarding policy (§2.17.4) permits forwarding: a. Append this node’s hash to path, incrementing hop_count. b. If appending would cause hop_count × hash_size > MAX_PATH_SIZE, do not forward. c. Schedule a retransmission after a randomized delay based on estimated airtime.

2.17.2. Direct Routing ¶

Direct-routed packets carry an explicit ordered path of hashes. Each forwarder consumes one entry.

When a node sends a direct packet with a known path of length N:

1. Route type = ROUTE_TYPE_DIRECT (or ROUTE_TYPE_TRANSPORT_DIRECT).
2. path = the sequence of hashes from the next hop to the final destination, in order.
3. hop_count = N.

When a node receives a direct packet:

1. Validate path_length.
2. If hop_count == 0, this is a zero-hop packet — process only if this node is the intended destination.
3. If the first entry in path matches this node’s hash: a. Process the payload if addressed to us. b. If forwarding is permitted, remove the first entry from path (shifting subsequent entries left) and decrement hop_count. c. Retransmit.
4. Otherwise, do not forward (but may still process the payload if addressed to us — e.g., ACKs sent back along a known path).

2.17.3. Zero-Hop Packets ¶

A zero-hop packet is a direct-routed packet with hop_count = 0. It is intended only for neighbours in direct radio range and is never forwarded.

2.17.4. Forwarding Policy ¶

Each node decides locally whether to forward a given packet. Typical policies:

• Repeater — forwards most packets.
• Room server — forwards packets addressed to its room, adverts, and selected control packets.
• Chat client — does not forward by default; may optionally act as a “client repeater” for a limited frequency range and payload types.

A forwarder MUST respect these hard rules:

• Do not forward a packet whose path_length is invalid.
• Do not forward PAYLOAD_TYPE_TRACE unless the next-hop entry matches this node.
• Do not forward a transport-scoped packet (ROUTE_TYPE_TRANSPORT_*) unless the node has a transport key whose derived code matches the packet’s transport_code_1.
• Do not forward a packet whose deduplication signature is already in the “seen” table.
• Respect duty-cycle regulations applicable to the region of operation (e.g., EU ETSI EN 300 220).

2.17.5. Packet Hash (Deduplication Signature) ¶

Every packet has a deduplication signature computed from the payload type and payload content. For most payload types:

signature_input = payload_type_byte || payload
signature       = SHA-256(signature_input)[0..8]   # first 8 bytes, used as 64-bit hash

For PAYLOAD_TYPE_TRACE, the path length is also included:

signature_input = payload_type_byte || path_length_byte || payload

This ensures TRACE packets with different accumulated SNR paths are not falsely deduplicated.

2.18. Duplicate Suppression ¶

A compliant node MUST maintain a “seen packets” table that retains recent packet signatures (§2.17.5) for long enough to suppress duplicate retransmissions across the mesh.

Recommended policy:

• Table size: enough to hold the signatures of all packets received in the last several seconds under typical load.
• Entry lifetime: a few seconds, tuned to typical mesh diameter × per-hop retransmit delay.

Duplicate suppression is REQUIRED to prevent broadcast storms during flood routing.

Appendix A: Compliance Checklist ¶

A minimally compliant implementation of The Protocol MUST:

1. Parse and emit packets per §2.1–§2.6.
2. Validate path_length per §2.5.2 and drop invalid packets.
3. Respect MAX_PACKET_PAYLOAD and MAX_TRANS_UNIT.
4. Implement deduplication per §2.18.
5. Implement Ed25519 signature verification for adverts per §2.8.1.
6. Implement X25519 key agreement, AES-128-ECB encryption, HMAC-SHA256 MAC per §2.7.
7. Use PUB_KEY_SIZE = 32 bytes for the HMAC key and the first 16 bytes for the AES key (§2.7.4).
8. Treat 0xFF as an on-wire invalid header and drop such packets (§2.2.2).

Compliance requirements for the Companion Protocol are defined in the companion document (Part 2: The Companion Protocol, Appendix A).

Appendix B: Constants Summary ¶

B.1. Size Constants ¶

The Companion Protocol’s default MAX_FRAME_SIZE (172 bytes) is defined in the companion document (Part 2, Appendix B).

B.2. Route Types ¶

B.3. Payload Types ¶

B.4. Advert Node Types ¶

B.5. Text Types ¶

Companion Protocol command and response codes are tabulated in the companion document (Part 2, Appendix B).

Appendix C: Known Discrepancies Between Documentation and Implementation ¶

This specification reflects the actual on-wire behaviour of a compliant implementation, not prior Core documentation drafts. The following discrepancies were identified and resolved in favour of the implementation:

C.1. Advert Flags Byte (§2.8.3) ¶

Earlier documentation listed the values 0x01 (chat), 0x02 (repeater), 0x03 (room), 0x04 (sensor) alongside the bit-flag masks 0x10, 0x20, 0x40, 0x80 in a single “flags” table, implying they occupied the same field. In reality, the node type occupies the low 4 bits of the flags byte, and the presence flags occupy the high 4 bits. The type and presence flags are decoded independently. This specification clarifies the split.

C.2. HMAC Key Length (§2.7.4) ¶

The HMAC key uses the full 32-byte shared secret, even though the AES key uses only the first 16 bytes of that same secret. A reader of the existing MeshCore docs might reasonably assume a 16-byte HMAC key by symmetry; the implementation does not. Incorrectly truncating the HMAC key to 16 bytes produces MAC verification failures that are hard to diagnose.

C.3. TRACE Packet Wire Layout ¶

Most payload types carry their routing path in the packet header’s path field. TRACE packets do not: the header’s path field is repurposed as an accumulator of measured per-hop SNR bytes, and the original path-hash sequence lives in the payload trailer (after the 9-byte tag/auth/flags preamble). Additionally, the header’s path_length byte is reinterpreted as a hop-consumption counter (its low 6 bits) and the top 2 bits (normally the hash-size code of §2.5) are locked at zero — the TRACE hash size is carried separately in the payload’s flags byte using a distinct encoding (1 << bits → 1/2/4 bytes per hash).

This is substantially different from every other payload type and requires special-case handling by forwarders. See §2.13 for the full specification.

Earlier drafts of this specification described TRACE packets as carrying their SNR samples in the payload. That description does not match the reference firmware; it has been replaced.

C.4. Protocol Version v1 Only ¶

Payload versions 2–4 (header bits 6–7) are reserved but not in use. All current implementations emit and expect version 1.

C.5. ACK Hash Algorithm (§2.12) ¶

Earlier drafts described PAYLOAD_TYPE_ACK as carrying a 4-byte little-endian CRC-32 of the acknowledged message. This was incorrect. The reference firmware (BaseChatMesh.cpp) computes the field as the first 4 bytes of SHA-256 over a message-type-dependent buffer that includes the recipient’s public key as a salt, and transmits those 4 bytes directly (no additional byte-order transformation).

The field name checksum in some firmware comments is a legacy term; it is not a CRC in any standard sense. Implementations of the original CRC-32 description will never produce a matching ACK.

Companion Protocol discrepancies (error codes, stats frames) are documented in the companion document (Part 2, Appendix C).

End of Specification — Part 1 ¶