dandri/HaloKeymind
1
0
Fork 0
mirror of https://github.com/mikecarper/MeshCore.git synced 2026-10-20 20:51:59 +00:00
Code Issues Packages Projects Releases Wiki Activity
Files
4bbd6134178b723619d6aeb8e810d01a3f64daf3
HaloKeymind/docs/packet_format.md
T
mikecarper 4bbd613417 Publish 1.17.1.9 USA Cascade picker and Mesh America catalogs 
Point both stable providers and runtime controls to the validated v1.17.1.9-halo-keymind-cascade-dev-88c85108 family. Record completed package validation while retaining hardware coverage limitations. Give all documentation source pages their exact hosted links and mount the telemetry form only in the browser. Verify current combined Full and nRF52 Full/Reduced catalog fixtures.
2026-10-07 13:56:17 -07:00

9.0 KiB
Raw Blame History

View this page on MeshCore Docs.

Packet Format

This document describes the MeshCore packet format.

  • 0xYY indicates YY in hex notation.
  • 0bYY indicates YY in binary notation.
  • Bit 0 indicates the bit furthest to the right: 0000000X
  • Bit 7 indicates the bit furthest to the left: X0000000

Version 1 Packet Format

This is the current version-1 MeshCore wire packet structure. Older firmware may support only a subset of the path encodings and payload types described here.

[header][transport_codes(optional)][path_length][path][payload]
  • header - 1 byte
    • 8-bit Format: 0bVVPPPPRR - V=Version - P=PayloadType - R=RouteType
    • Bits 0-1 - 2-bits - Route Type
      • 0x00/0b00 - ROUTE_TYPE_TRANSPORT_FLOOD - Flood Routing + Transport Codes
      • 0x01/0b01 - ROUTE_TYPE_FLOOD - Flood Routing
      • 0x02/0b10 - ROUTE_TYPE_DIRECT - Direct Routing
      • 0x03/0b11 - ROUTE_TYPE_TRANSPORT_DIRECT - Direct Routing + Transport Codes
    • Bits 2-5 - 4-bits - Payload Type
      • 0x00/0b0000 - PAYLOAD_TYPE_REQ - Request (destination/source hashes + MAC)
      • 0x01/0b0001 - PAYLOAD_TYPE_RESPONSE - Response to REQ or ANON_REQ
      • 0x02/0b0010 - PAYLOAD_TYPE_TXT_MSG - Plain text message
      • 0x03/0b0011 - PAYLOAD_TYPE_ACK - Acknowledgment
      • 0x04/0b0100 - PAYLOAD_TYPE_ADVERT - Node advertisement
      • 0x05/0b0101 - PAYLOAD_TYPE_GRP_TXT - Group text message (unverified)
      • 0x06/0b0110 - PAYLOAD_TYPE_GRP_DATA - Group datagram (unverified)
      • 0x07/0b0111 - PAYLOAD_TYPE_ANON_REQ - Anonymous request
      • 0x08/0b1000 - PAYLOAD_TYPE_PATH - Returned path
      • 0x09/0b1001 - PAYLOAD_TYPE_TRACE - Trace a path, collecting SNR for each hop
      • 0x0A/0b1010 - PAYLOAD_TYPE_MULTIPART - Packet is part of a sequence of packets
      • 0x0B/0b1011 - PAYLOAD_TYPE_CONTROL - Control packet data (unencrypted)
      • 0x0C/0b1100 - PAYLOAD_TYPE_OTA - OTA-over-LoRa firmware distribution
      • 0x0D/0b1101 - reserved
      • 0x0E/0b1110 - reserved
      • 0x0F/0b1111 - PAYLOAD_TYPE_RAW_CUSTOM - Custom packet (raw bytes, custom encryption)
    • Bits 6-7 - 2-bits - Payload Version
      • 0x00/0b00 - v1 - 1-byte src/dest hashes, 2-byte MAC
      • 0x01/0b01 - v2 - Future version (e.g., 2-byte hashes, 4-byte MAC)
      • 0x02/0b10 - v3 - Future version
      • 0x03/0b11 - v4 - Future version
  • transport_codes - 4 bytes (optional)
    • Only present for ROUTE_TYPE_TRANSPORT_FLOOD and ROUTE_TYPE_TRANSPORT_DIRECT
    • transport_code_1 - 2 bytes - uint16_t - calculated from region scope
    • transport_code_2 - 2 bytes - uint16_t - reserved
  • path_length - 1 byte - Encoded path metadata
    • Bits 0-5 store path hash count / hop count (0-63)
    • Bits 6-7 store path hash size minus 1
      • 0b00: 1-byte path hashes
      • 0b01: 2-byte path hashes
      • 0b10: 3-byte path hashes
      • 0b11: reserved / unsupported
  • path - hop_count * hash_size bytes - Path to use for Direct Routing or flood path tracking
    • Up to a maximum of 64 bytes, defined by MAX_PATH_SIZE
    • Effective byte length is calculated from the encoded hop count and hash size, not taken directly from path_length
    • v1.12.0 firmware and older only handled legacy 1-byte path hashes and dropped packets whose path bytes exceeded 64 bytes
  • payload - variable length - Payload Data
    • Up to a maximum 184 bytes, defined by MAX_PACKET_PAYLOAD
    • Generally this is the remainder of the raw packet data
    • The firmware parses this data based on the provided Payload Type
    • v1.12.0 firmware and older drops packets with payload sizes larger than 184

Packet Format

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_length 1 Encodes path hash size in bits 6-7 and hop count in bits 0-5
path up to 64 (MAX_PATH_SIZE) Stores hop_count * hash_size bytes of path data if applicable
payload up to 184 (MAX_PACKET_PAYLOAD) Data for the provided Payload Type

NOTE: see the Payloads documentation for more information about the content of specific payload types.

Header Format

Bit 0 means the lowest bit (1s place)

Bits Mask Field Description
0-1 0x03 Route Type Flood, Direct, etc
2-5 0x3C Payload Type Request, Response, ACK, etc
6-7 0xC0 Payload Version Versioning of the payload format

Route Types

Value Name Description
0x00 ROUTE_TYPE_TRANSPORT_FLOOD Flood Routing + Transport Codes
0x01 ROUTE_TYPE_FLOOD Flood Routing
0x02 ROUTE_TYPE_DIRECT Direct Routing
0x03 ROUTE_TYPE_TRANSPORT_DIRECT Direct Routing + Transport Codes

Path Length Encoding

path_length is not a raw byte count. It packs both hash size and hop count:

Bits Field Meaning
0-5 Hop Count Number of path hashes (0-63)
6-7 Hash Size Code Stored as hash_size - 1

Hash size codes:

Bits 6-7 Hash Size Notes
0b00 1 byte Legacy / default mode
0b01 2 bytes Supported in current firmware
0b10 3 bytes Supported in current firmware
0b11 4 bytes Reserved / invalid

Examples:

  • 0x00: zero-hop packet, no path bytes
  • 0x05: 5 hops using 1-byte hashes, so path is 5 bytes
  • 0x45: 5 hops using 2-byte hashes, so path is 10 bytes
  • 0x8A: 10 hops using 3-byte hashes, so path is 30 bytes

Payload Types

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 SNR for each hop
0x0A PAYLOAD_TYPE_MULTIPART Packet is part of a sequence of packets
0x0B PAYLOAD_TYPE_CONTROL Control packet data (unencrypted)
0x0C PAYLOAD_TYPE_OTA OTA-over-LoRa firmware distribution
0x0D reserved reserved
0x0E reserved reserved
0x0F PAYLOAD_TYPE_RAW_CUSTOM Custom packet (raw bytes, custom encryption)

Payload Versions

Value Version Description
0x00 1 1-byte src/dest hashes, 2-byte MAC
0x01 2 Future version (e.g., 2-byte hashes, 4-byte MAC)
0x02 3 Future version
0x03 4 Future version
Reference in New Issue View Git Blame Copy Permalink