Introduction

UMSH is an experimental LoRa-oriented mesh protocol that grew out of a simple question: what would a cryptographically addressed LoRa mesh look like if designed from the ground up with strong security and clean architecture? Inspired by MeshCore, UMSH started as a thought experiment addressing what its author saw as critical shortcomings—shortcomings that would practically require backward-incompatible changes to properly fix. What began as a toy protocol has since developed into this comprehensive specification.

Few, if any, of the ideas presented here are new or exotic. Many come directly from MeshCore—cryptographic addressing, source routing, regions, and more. The key contribution here is a clean, extensible design with stronger cryptography and clear layer separation.

This specification was written with MeshCore V2 in mind, but the ideas are free for anyone to adopt. Meshtastic has discussed the possibility of a breaking v3 revision, and some of these ideas may be relevant there as well. Point-by-point protocol comparisons with MeshCore, Meshtastic, and Reticulum are available in the appendices.

The project repository, reference implementation, and supporting tooling are available on GitHub.

Overview

In UMSH, endpoints are identified by public keys, and multicast communication is based on shared symmetric channel keys. At its core, UMSH defines a MAC layer with framing, addressing, encryption, authentication, and hop-by-hop forwarding. UMSH also defines application-layer protocols for text messaging, chat rooms, and node management that are built on top of this foundation. The MAC layer treats payloads opaquely and can equally carry UMSH-defined application protocols, third-party protocols such as CoAP, or any other higher-layer content.

UMSH is designed to support:

• Public-key-addressed unicast
• Symmetric-key multicast
• Optional payload encryption
• End-to-end authentication across multi-hop paths
• Selective flooding and source-routed delivery
• Operation in both encrypted and amateur-radio-compliant unencrypted modes
• Ability to operate in a way that preserves perfect forward secrecy (PFS)
• Timestamp-free at the MAC layer

Design Principles

The following principles guide UMSH’s design. When evaluating a design decision, prefer the option that best satisfies these principles. The order of these principles shouldn’t be interpreted as an order of importance.

Single-frame design. Every packet must fit in a single LoRa frame. Operations that require more data than one frame can carry belong at a higher layer.

Confidentiality. Encryption and authentication must be available for every kind of interaction. Where metadata concealment is also needed, the protocol should provide opt-in mechanisms rather than requiring it universally.

Robustness. Prefer constructions that fail gracefully over ones that fail catastrophically. A slightly less efficient design that degrades safely under adverse conditions is better than an efficient one that breaks badly.

Tolerance of loss and disorder. Assume packets will be dropped, duplicated, and delivered out of order. No operation should require synchronized state between two nodes that cannot recover from a missed message.

Brevity. Every byte costs airtime. Mandatory fields should be as small as correctness allows; optional fields should be absent when not needed.

Practicality. A protocol must be operable, not just correct. Prefer designs that make real networks easier to understand and debug—readable packet traces, attributable traffic, and identifiable nodes are operational requirements, not luxuries. Theoretical minimalism that makes a protocol difficult to deploy or troubleshoot is a real cost.

Layer separation. The MAC layer routes and delivers opaque payloads. It must not depend on payload content, and payload protocols must not depend on MAC-layer internals.

Minimal mandatory state. Basic operation should require only a node’s own keypair and its configured channel keys. Path tables, clock synchronization, and session state are optional enhancements, not prerequisites.

Graceful extensibility. The protocol must be able to evolve without requiring coordinated upgrades across a deployed network. New features should be deployable incrementally, with older nodes degrading gracefully rather than failing.

Note

Regarding layer separation… There is a case to be made that having the payload type be non-opaque could be a benefit to the mesh as a whole, because you could then do things like prioritize text chat messages over other types of messages at the repeater level. This would help to ensure that there is a minimum-level of text service always available, even if there is lots of other traffic present. I am not yet convinced this is a good idea yet, but it is worth thinking about.

Use Cases

UMSH is designed for deployments where LoRa’s range and low power consumption are valuable and where the constraints of LoRa—low data rates, small frame sizes, shared channel—make protocol efficiency and cryptographic robustness important.

Intended use cases include:

• Off-grid text communication—chat, direct messaging, and group channels between people in areas without cellular coverage: hiking, expeditions, disaster response, rural communities.
• Emergency and disaster communications—resilient mesh networking that operates without any fixed infrastructure and degrades gracefully as nodes go offline.
• IoT and sensor telemetry—authenticated sensor readings from battery-powered field devices, where per-packet overhead directly affects battery life and where tampered readings could have real consequences.
• Amateur radio mesh networking—the protocol defines explicit amateur-radio-compliant modes with callsign fields and mandatory unencrypted operation, supporting legal use on amateur frequencies.
• Privacy-sensitive communication—blind unicast and encrypted multicast allow metadata concealment (sender and recipient identity) for contexts where traffic analysis is a concern.
• Embedded and constrained deployments—compact encoding (1-byte FCF, compact address hints, minimal per-packet overhead), single-frame design, and no mandatory runtime state (no path tables, no clock synchronization) make UMSH suitable for bare-metal microcontrollers with minimal RAM and no operating system.

UMSH is not designed for:

• High-bandwidth applications—LoRa data rates (typically 0.3–27 kbps) make real-time voice, video, or large file transfer impractical.
• Applications requiring low latency—multi-hop flood delivery adds variable latency that makes UMSH unsuitable for interactive or time-sensitive protocols.

Key Concepts

Nodes

A node is a logical endpoint on the network, identified by a 32-byte Ed25519 public key. That public key is the node’s long-term network identity—it serves as both its address and its cryptographic credential. A single physical device may host multiple nodes (e.g., a repeater node and a chat node), each with its own keypair.

A node’s public key must be known to communicate with it directly. Public keys can be learned through several mechanisms:

• Beacons and advertisements—nodes periodically broadcast their presence, optionally including identity information (see Node Identity)
• QR codes and URIs—public keys can be shared out-of-band via umsh:n: URIs (see URI Formats)
• First-contact packets—a sender can set the S flag to include its full public key in any packet, allowing the receiver to learn it directly from the wire

Once a node’s public key is known, it can be cached and subsequent packets can use a compact source hint instead of the full key—saving 29 bytes per packet in unicast (3-byte hint vs 32-byte key).

Node Metadata

Nodes may also advertise additional metadata—such as a human-readable name, role, capabilities, and location—via the Node Identity payload. Metadata can also be contained in QR codes and URIs. This metadata is carried at the application layer and is not required by the MAC layer.

Unicast

Unicast packets are addressed to a destination node and may be authenticated or encrypted using per-destination cryptographic material derived from sender/recipient key agreement (see Frame Types and Security & Cryptography).

Channels

A channel is a shared symmetric key that serves two roles: multicast group communication and blind unicast metadata concealment. All nodes configured with a given channel key are members and can send and receive multicast packets addressed to it. Blind unicast uses the channel key to hide sender and destination addresses on the wire, while protecting the payload with combined keys that require both the channel key and the pairwise shared secret—only the intended recipient can read it. See Channels for channel types, membership models, and default channels.

Perfect Forward Secrecy

UMSH supports perfect forward secrecy, not as a core part of the underlying protocol but instead via ephemeral node addresses. Either node can initiate a PFS session, after which both parties communicate using ephemeral node addresses whose private keys are never stored durably and are erased at session end. Compromise of long-term keys cannot retroactively expose traffic protected by a completed PFS session.

Definitions

The following terms are used throughout this specification. Definitions are given in the context of UMSH; terms with broader meanings in other fields are defined here as they apply to this protocol.

Address

A node’s 32-byte Ed25519 public key, used as its stable network identifier. UMSH addresses are not numeric values used for routing. Short address hints derived from the address are used on the wire to save space.

Address Hint

A short prefix of a node’s public key used as a cheap prefilter before full cryptographic processing. Source and destination hints are 3 bytes; router hints, as used in source routes and traces, are 2 bytes. See Addressing.

AES (Advanced Encryption Standard)

A symmetric block cipher standardized by NIST. UMSH uses AES-256: AES-CMAC-based S2V for message authentication and AES-CTR for payload encryption.

AES-SIV (Synthetic Initialization Vector)

A misuse-resistant authenticated encryption scheme defined by RFC 5297. It uses S2V to compute a synthetic IV from the associated data and the plaintext, then encrypts with AES-CTR. UMSH secures packets with AES-SIV using AES-256, extended with MIC truncation and a SECINFO-padded CTR IV; with a full 16-byte MIC the construction is byte-for-byte AEAD_AES_SIV_CMAC_512. See Encrypted Packets.

ARNCE/HAM-64

A compact character encoding scheme for amateur radio callsigns, encoding up to 12 characters into 2, 4, 6, or 8 bytes. Used in UMSH’s Operator Callsign and Station Callsign packet options.

Beacon

A broadcast or multicast packet with an empty payload. Beacons advertise a node’s presence and are used for path discovery and route learning. See Beacons & Path Discovery.

Blind Unicast

A packet type that carries a unicast payload addressed to a specific destination while concealing both the sender and destination identities from observers who do not possess the channel key. The destination hint and source address are encrypted using the channel key; the payload is protected end-to-end using keys derived from both the channel key and the pairwise shared secret. See Frame Types.

Bridge

An arrangement that carries UMSH packets between two different media or channels—for example, from a local LoRa radio to an internet backhaul and back to a distant LoRa radio. Bridges are protocol-transparent: a repeater at each end forwards the packet as it would any other, so a crossing consumes source-route hints, spends two flood hops, and records both repeaters in a trace. The inbound repeater’s forwarding is observable on the medium the packet arrived from.

Broadcast

A packet intended for all nodes in range. Broadcast packets carry no destination hint and are not encrypted or authenticated at the MAC layer. See Frame Types.

CAD (Channel Activity Detection)

A LoRa physical-layer feature that listens briefly for preamble energy on the channel with minimal power draw. UMSH uses CAD to implement listen-before-talk channel access, reducing collisions without requiring continuous reception. See Channel Access.

Channel

A logical communication group secured by a shared symmetric key. Channels serve two purposes: group communication (multicast) and metadata concealment (blind unicast). See Channels.

CoAP (Constrained Application Protocol)

A lightweight request/response protocol designed for constrained networks (RFC 7252). UMSH borrows CoAP’s delta-length option encoding for packet options and application-layer payloads.

Confidentiality

The property that payload content is accessible only to intended recipients. UMSH provides confidentiality via AES-256 encryption keyed with material derived from ECDH (unicast) or the channel key (multicast).

Duplicate Suppression

A mechanism by which repeaters track recently forwarded packets and decline to forward the same packet a second time. Each packet is identified by its MIC (for authenticated packets) or a locally computed hash (for unauthenticated packets). This prevents flood-routed packets from circulating indefinitely. See Repeater Operation.

ECDH (Elliptic Curve Diffie-Hellman)

A key agreement protocol that allows two parties to derive a shared secret using only their public keys and their own private keys. UMSH uses X25519 ECDH to derive pairwise shared secrets for unicast encryption and authentication.

Ed25519

An elliptic curve digital signature algorithm using the Edwards25519 curve. UMSH uses Ed25519 keypairs as node identities. The same keypair is converted to X25519 form for key agreement.

EdDSA (Edwards-curve Digital Signature Algorithm)

The family of signature algorithms that includes Ed25519. Used in UMSH for frame signatures, which attribute a frame to its sender’s key, and for the optional signature that lets a node identity stand on its own outside a frame.

Ephemeral Key

A temporary Ed25519 keypair generated for a single PFS session. Unlike a long-term identity keypair, ephemeral keys are never written to persistent storage and are explicitly erased when the session ends, ensuring that compromise of long-term keys cannot retroactively decrypt traffic protected by them. See Security & Cryptography.

Flood Hop

A hop spent from FHOPS_REM: a transmission made with FHOPS_REM > 0 and no source-route hint left to follow, which is what permits the repeaters that hear it to flood-forward the packet. The final transmission of a flood-routed packet is made with FHOPS_REM = 0 and is a hop but not a flood hop, and a source-routed hop is not a flood hop either. A path’s hop count is its source-routed hops plus its flood hops plus one, so it is one more than FHOPS_ACC if and only if no source route was involved. See Flood Hop Count.

Flood Routing

A routing strategy where a packet is forwarded by every eligible repeater within the flood radius, subject to duplicate suppression. Requires no topology state at repeaters. Bounded by the flood hop count field (FHOPS). See Repeater Operation.

Frame

The unit of transmission at the LoRa PHY layer. A UMSH packet must fit within a single frame. The terms frame and packet are used interchangeably in this specification; frame emphasizes the physical transmission unit, packet emphasizes the logical protocol unit.

Frame Counter

A monotonically increasing 4-byte value included in every authenticated packet. The receiver tracks recently seen counter values and rejects packets with counters it has already processed, providing replay protection without requiring synchronized clocks. The counter must be persisted across reboots to prevent reuse. See Security & Cryptography.

Hop

One leg of a packet’s path through the network—the transmission from one node to an adjacent node within radio range. A packet that travels through two repeaters before reaching its destination has traversed three hops. A zero-hop message is a message sent to yourself that is never sent over the radio. A hop taken by a repeater matching a source-route hint is a source-routed hop and spends no FHOPS budget; a hop spent from FHOPS_REM is a flood hop. Between them the two counts leave exactly one transmission uncounted, so a path always has one more hop than the two counts together.

HKDF (HMAC-based Key Derivation Function)

A key derivation function standardized in RFC 5869, composed of two steps: Extract (combining a secret and optional salt into a pseudorandom key) and Expand (stretching that key to the required output length). UMSH uses HKDF-SHA256 with domain-separated labels to derive encryption keys, authentication keys, and channel identifiers from shared secrets and channel keys.

IoT (Internet of Things)

A broad term for networked embedded devices. UMSH is designed to be applicable to IoT use cases in addition to human communication, though it is optimized for the latter.

Latency

The time elapsed between a packet being transmitted and its receipt or acknowledgement. LoRa’s low data rate and mesh forwarding introduce significant latency compared to IP networks.

LoRa (Long Range)

A proprietary wireless modulation technology using chirp spread spectrum, designed for long range and low power consumption at the cost of low data rate. LoRa payloads are typically limited to 200–250 bytes, and transmitting a single packet may take hundreds of milliseconds depending on spreading factor and bandwidth. UMSH is designed around these constraints.

Long-Term Identity

A node’s stable Ed25519 keypair, used as its persistent network identity. Contrast with ephemeral keypairs used in PFS sessions, which are discarded after use.

MAC Layer (Medium Access Control)

The sublayer of the data link layer responsible for addressing, packet framing, and channel access. In UMSH, the MAC layer handles packet types, addressing, routing options, and cryptography. Application-layer protocols are carried in the payload and are defined separately.

MAC Ack

A packet type generated by the final destination of a unicast packet (UNAR or BUAR) to confirm receipt. The MAC Ack carries an ack MIC—the first 4 bytes of the original packet’s MIC, a public handle that lets the sender and any forwarding repeater correlate the ack with the original packet—and a 4-byte ack tag, a MIC over the ack’s static options bound to the original packet, which allows the original sender to verify the acknowledgement. It carries no destination hint. Repeaters do not generate MAC Acks; they forward them like any other packet. See Frame Types.

Mesh

A network topology where nodes can relay packets on behalf of other nodes, enabling communication beyond direct radio range. UMSH is designed for LoRa mesh networks where repeaters and bridges are used to extend coverage.

MIC (Message Integrity Code)

UMSH’s authentication tag, the truncated S2V output (RFC 5297) computed over the packet’s static fields and payload. Size is configurable from 4 to 16 bytes. The term MIC is used instead of the more common “MAC” (Message Authentication Code) to avoid confusion with Medium Access Control. See Security & Cryptography.

Multicast

A packet intended for all members of a channel, identified by a 2-byte channel identifier derived from the channel key. See Frame Types.

Node

A logical participant in a UMSH network, defined by a unique Ed25519 keypair. A single physical device may host multiple nodes. A node may act as an endpoint (sending and receiving application data), a repeater (forwarding packets), or both.

Packet

The logical unit of the UMSH protocol. Every packet must fit within a single LoRa frame. See Frame above.

Pairwise Key

A symmetric key derived from X25519 ECDH between a specific sender and recipient. Each pair of nodes shares a unique set of pairwise keys (one for encryption, one for authentication) derived deterministically from their long-term key material. Pairwise keys are stable across sessions unless a PFS session is used. See Security & Cryptography.

PFS (Perfect Forward Secrecy)

A property ensuring that compromise of long-term keys does not allow retroactive decryption of past traffic. UMSH provides optional PFS via ephemeral keypair sessions. See Security & Cryptography.

PHY (Physical Layer)

The lowest layer of a network stack, responsible for modulation and transmission over the physical medium. In UMSH deployments, this is typically LoRa. The PHY layer is below the MAC layer and is not defined by this specification.

Private Key

The secret half of an asymmetric keypair. In UMSH, a node’s Ed25519 private key is used to derive its X25519 private key for ECDH and to sign payloads when required. Must never be transmitted or disclosed.

Privacy

Broader than confidentiality: the protection of metadata and communication patterns in addition to payload content. UMSH provides confidentiality but does not fully protect against traffic analysis. See Security Considerations.

Public Key

The public half of an asymmetric keypair, which can be freely shared. In UMSH, a node’s Ed25519 public key is its address. Address hints are derived from it.

RSSI (Received Signal Strength Indicator)

A measurement of received radio signal power, expressed in dBm (negative values; higher is stronger).

Repeater

A node that forwards packets to extend the effective range of the mesh. Repeaters participate in flood routing and source routing but do not generate or consume application payloads for the packets they forward. See Repeater Operation.

SNR (Signal-to-Noise Ratio)

A measurement of the ratio between received signal power and background noise, expressed in dB. Unlike RSSI, SNR remains a reliable indicator of link quality even when the signal is below the noise floor, which is common in LoRa’s spread-spectrum operating regime.

Source Routing

A routing strategy where the sender specifies the explicit sequence of repeaters a packet must traverse. Requires the sender to have prior knowledge of a valid path. See Packet Options.

Trace

A packet option that instructs each forwarding repeater to prepend a record of itself—its router hint and the signal it received the packet with—to the option value, building an ordered record of the path a packet has taken (most-recent repeater first). Used for route learning: a destination that receives a packet with a complete trace has enough information to construct a source route for the reply. See Packet Options.

Unicast

A packet addressed to a single destination node, identified by a 3-byte destination hint. Unicast packets are always authenticated end-to-end; encryption is optional and controlled by the E flag. See Frame Types.

URI (Uniform Resource Identifier)

A compact string that identifies a resource or address. UMSH defines URI schemes for addressing nodes and channels. See URI Formats.

X25519

An elliptic curve Diffie-Hellman function over Curve25519. UMSH converts Ed25519 keypairs to X25519 form for key agreement. The conversion is deterministic and well-defined.

Common Patterns

UMSH reuses a small set of encoding patterns across both the MAC layer and application-layer protocols. This chapter collects them in one place so that individual protocol sections can reference them without repeating the details.

Byte Order

Multi-byte numeric fields are transmitted in big-endian (most-significant byte first), also known as network byte order. This is the standard convention for protocol specifications and is straightforward to interpret in packet diagrams. Modern hardware can convert between byte orders at effectively zero cost, so this choice imposes no practical performance penalty.

Non-numeric multi-byte data—such as SHA-256 hashes, Ed25519 public keys, and EdDSA signatures—is transmitted in its most common byte-wise representation, independent of any underlying endianness of the represented value.

CoAP-Style Option Encoding

UMSH uses the delta-length option encoding defined in CoAP (RFC 7252 §3.1) wherever a set of typed key-value fields needs to be carried compactly. This allows the protocols to be flexible and adapt to future needs while retaining backward compatibility.

Each option is encoded as a delta from the previous option’s number, a length, and a value. The sequence is terminated by a 0xFF end-of-options marker when a PAYLOAD follows the options block; packets with no payload omit the marker.

This encoding appears in:

• MAC-layer packet options—routing, signal-quality thresholds, callsigns (see Packet Options)
• Text message options—message type, sender handle, fragmentation, colors (see Text Messages)
• Chat room payloads—room info responses, login parameters (see Chat Rooms)
• Node identity metadata—name, location, altitude, timestamp, supported regions (see Node Identity)

The full encoding rules—nibble interpretation, extended bytes, and the end marker—are defined in Packet Structure. Application-layer uses follow the same wire format.

ARNCE/HAM-64 Text Encoding

ARNCE (Amateur Radio Numeric Callsign Encoding), also known as HAM-64, is a compact encoding for short alphanumeric strings. It packs up to 12 characters into 2, 4, 6, or 8 bytes, making it well suited for identifiers that must fit in constrained fields.

UMSH uses ARNCE/HAM-64 for:

• Operator callsign (packet option 4)—identifies the originating operator under amateur radio rules
• Station callsign (packet option 15)—identifies the transmitting station, updated by repeaters during forwarding
• Region codes (packet option 11)—short codes of one to three letters or digits encoded as 2-byte ARNCE values (e.g. SJC → 0x7853)

UTF-8 Strings

All human-readable text in UMSH—message bodies, node names, sender handles, room descriptions—is encoded as UTF-8. String length is determined by context:

• Inside a CoAP-style option, the option’s length field defines the string boundary.
• As trailing data after a 0xFF marker, the string extends to the end of the payload (or to the start of a trailing signature).

A sender that shortens a string to fit a byte limit (a node name, a sender handle, a region name) cuts it at an extended grapheme cluster boundary (UAX #29), so that an emoji sequence or a letter with combining marks is kept whole or dropped whole. A receiver given a string that ends mid-cluster renders what it can; it does not reject the string. Message fragmentation splits bodies at byte boundaries and is unaffected (see Text Messages).

Base58 Encoding

Public keys and channel keys in human-facing contexts (URIs, QR codes) are encoded using Base58. This avoids visually ambiguous characters (0/O, l/1) and produces compact, copy-paste-friendly strings.

See URI Formats for the defined URI schemes.

Addressing

UMSH nodes are identified by their 32-byte Ed25519 public keys. Including a full 32-byte address in every packet would be expensive in the constrained LoRa frame budget, so UMSH defines several compact hint representations—short prefixes of a public key that allow receivers to quickly identify likely matches without the full key. Hints are not cryptographically authoritative; they serve only as cheap prefilters to avoid unnecessary work.

The sections below describe the three addressing forms used across the protocol: node hints, router hints, and source addresses.

Presentation

UMSH addresses are canonically encoded and displayed using base 58. Addresses may also be rendered using base 16 as 64 hexadecimal digits—lowercase preferred, either case accepted when parsing—but the preferred encoding is base58. The two forms are unambiguously distinguished by length.

The base58 encoding is fixed-length: a 32-byte address always renders as exactly 44 digits, left-padded with 1 (the base58 zero digit) when its numeric value would otherwise encode shorter.

Node Hint

A node hint is defined as:

• the first three bytes of a node’s 32-byte public key

Node hints serve as the destination hint in unicast packets and as the compact source hint in source addresses (see below). A node hint is not authoritative and is used only as a fast prefilter to avoid unnecessary cryptographic work.

A receiver that sees a matching destination hint must still confirm that it is the intended destination by successfully processing the packet cryptographically.

Rendering Node Hints

Rendering a node hint to the user is a little tricky due to the fact that most node hints can be rendered as just the first four characters of the encoded public key. In these cases, we would simply take our node hint, append 29 zeros, perform the base 58 encoding, and just drop everything except the first four characters.

However, in some cases when using this method, the fourth character may differ from the fourth character in the actual address. This is highly undesirable.

One way to address this is to perform two base58 encodings: one padded with 0x00 and one padded with 0xFF. If the fourth encoded character is the same between them both, then four characters can be used as the rendered node hint. However, if the encodings differ, the rendered hint is the longest common prefix of the two encodings followed by a single *. The common prefix is three characters except in the rare case where a carry propagates into the third digit, leaving two verified characters. Every character preceding the * is guaranteed to match the full base58 rendering of any matching address.

Note that there are more efficient ways of calculating this than padding with 0x00 and 0xFF and encoding the whole address twice, but logically that is the process.

Router Hint

A router hint is defined as:

• the first two bytes of the repeater’s 32-byte public key

Router hints are used in:

• source-route options
• trace options

Because router hints are only 2 bytes, collisions are possible in dense networks but are handled gracefully: the MIC-based duplicate suppression ensures that each repeater forwards a given packet at most once, so a router hint collision causes a spurious forward but not a loop or incorrect delivery.

Rendering Router Hints

Router hints are rendered using the same procedure as node hints, with a three-character budget and 30 bytes of padding. Because two bytes pin down only slightly more than two base58 digits, the third character is ambiguous for most router hints; the two-characters-plus-* form is the common case.

Source Address

A source address in a packet is either:

• a compact source hint (a prefix of the sender’s 32-byte public key), when the S flag in the FCF is clear, or
• the full 32-byte public key, when the S flag is set.

The source hint is 3 bytes (the first three bytes of the public key) when S is clear.

The source hint is a compact reference used when the receiver is expected to already have the sender’s full public key cached (e.g., from a prior advertisement or first-contact exchange). When the full public key is present, the receiver can perform ECDH directly from the packet without any prior state.

In encrypted multicast and blind unicast packets, the source address is carried inside the ciphertext: a 3-byte hint when S is clear, or the full 32-byte public key when S is set.

Packet Structure

All UMSH packets begin with a one-byte Frame Control Field (FCF). Optional common fields then follow in a fixed order, followed by packet-type-specific fields.

Top-Level Packet Layout

+-----+-------+----------+---------+-----------+---------+---------+-------+-----+
| FCF | FHOPS | DST/CHAN |   SRC   |  SECINFO  | OPTIONS | PAYLOAD | [SIG] | MIC |
+-----+-------+----------+---------+-----------+---------+---------+-------+-----+
  1 B   0/1 B    0/2/3 B   0/3/32 B   0/5/7 B   variable  variable  0/64 B  0-16 B

Where:

• FHOPS is present if the FCF flood hop count flag is set
• DST is a 3-byte destination hint (MAC Ack packets carry no DST)
• CHAN is a 2-byte channel identifier
• SRC is a compact 3-byte source hint (when S flag is clear) or 32-byte source public key (when S flag is set); in multicast and blind unicast packets, SRC follows the options rather than preceding them, and with encryption enabled it is encrypted inside the ciphertext
• SECINFO is present on authenticated/encrypted packet types
• SIG is a 64-byte frame signature, present when the SCF’s D bit is set; with encryption enabled it is encrypted with the payload
• MIC is present on authenticated/encrypted packet types; MAC acks carry a fixed ack trailer (ack MIC + ack tag) instead

A broadcast carries its frame signature, if any, in the Frame Signature option instead of SIG.

Not all fields are supported for all packet types.

Frame Control Field

The Frame Control Field is one byte:

  7   6   5   4   3   2   1   0
+-------+-----------+---+---+---+
|  VER  | PKT TYPE  | S | R | H |
+-------+-----------+---+---+---+
 2 bits    3 bits     1   1   1

Where:

• VER = protocol version (this specification defines version 3, i.e., both bits set)
• PKT TYPE = packet type
• S = full 32-byte source address included (when clear, a compact source hint is used instead; see Source Address for hint size by packet type)
• R = reserved; senders MUST set to 0; receivers MUST drop packets where this bit is non-zero
• H = flood hop count present. Zero if direct. Cleared before the byte enters the AAD

Packet Type Values

Common Optional Fields

Flood Hop Count

If present, FHOPS is a single byte containing two 4-bit fields:

  7   6   5   4   3   2   1   0
+---------------+---------------+
| FHOPS_REM     | FHOPS_ACC     |
+---------------+---------------+
     4 bits          4 bits

Where:

• FHOPS_REM (high nibble) = hops remaining—the number of additional flood hops remaining. Decremented by each flood-forwarding repeater. When zero, no further flood forwarding is allowed.
• FHOPS_ACC (low nibble) = hops accumulated—the number of flood hops already traversed. Incremented by each flood-forwarding repeater.

Important

FHOPS counts flood hops only. A repeater that forwards a packet because it matched a source-route hint MUST leave the byte untouched—including the repeater that removes the last remaining hint. Emptying the route makes the packet floodable, but the first flood hop is performed by the next repeater, which sees an empty route and pays for it there.

The sum FHOPS_REM + FHOPS_ACC is constant across forwarding hops and usually equals the original flood hop limit set by the sender. An exception to this rule is bridging, which can decrease FHOPS_REM unilaterally. The maximum flood radius is 15 flood hops, which is a path of sixteen hops when no source route is involved; longer paths can be achieved by combining source routing with flooding (see Routing Implications).

FHOPS_ACC enables the destination to determine how many flood hops the packet traversed—one less than the hops it took, unless a source route carried it part of the way—which is used for MAC ack routing when no complete trace is available.

Options Field

Options use the same delta-length encoding as CoAP (RFC 7252 §3.1). Each option is encoded as a delta from the previous option’s number, a length, and a value. The sequence is terminated by a 0xFF byte if a payload is present.

Option Encoding

Each option begins with a single byte containing two 4-bit fields:

  7   6   5   4   3   2   1   0
+---------------+---------------+
| Option Delta  | Option Length |
+---------------+---------------+
     4 bits          4 bits

Followed by optional extended delta bytes, optional extended length bytes, and then the option value:

+---------------+---------------+
| Option Delta  | Option Length |  (1 byte)
+---------------+---------------+
| Extended Delta (0-2 bytes)    |
+-------------------------------+
| Extended Length (0-2 bytes)   |
+-------------------------------+
| Option Value (0 or more bytes)|
+-------------------------------+

Delta and length interpretation:

The value 15 is legal only as part of the 0xFF end-of-options marker, where both nibbles are 15. Any other appearance of nibble value 15—a delta nibble of 15 whose length nibble is not 15, or a length nibble of 15 in an ordinary option record—is malformed, and the packet MUST be dropped.

The option delta is the difference between this option’s number and the previous option’s number (or zero for the first option). Options must appear in order of increasing option number. Multiple options with the same number are permitted (delta = 0).

Option numbers range from 0 to 0xFFFF. Deltas accumulate, so a sequence of records can name a larger number; such a record is malformed, and the packet MUST be dropped.

End-of-Options Marker

The byte 0xFF (delta nibble = 15, length nibble = 15) separates the options block from a following variable-length payload.

Parsing proceeds as follows:

1. Determine the options+payload region: buf[options_start .. packet_end − trailer_len], where trailer_len is the length of the fixed-size trailer at the end of the packet (the MIC length from SECINFO, plus 64 when the SCF’s D bit is set; 8 for the MAC ack trailer; or 0 for broadcast). The trailer length is known before options are parsed. With encryption enabled, the 64 bytes before the MIC are the encrypted SIG.
2. Scan options in order through that region, consuming each delta-length-value record. Because option records are variable-length, this scan is the only way to locate the end of the options block.
3. If a 0xFF byte is encountered during the scan, the bytes remaining in the region (between the 0xFF and the trailer) are the payload. A 0xFF with zero bytes remaining is a valid empty payload.
4. If the region is exhausted without encountering a 0xFF, there is no payload.

Senders SHOULD omit 0xFF when there is no payload. Receivers MUST accept a 0xFF in any position where the marker is syntactically valid (i.e., immediately after the last option record), regardless of if payload bytes follow.

Example

Two options—option 3 (1-byte value) followed by option 9 (2-byte value):

+------+-------+  +------+-------+-------+  +------+
| 0x31 |  val  |  | 0x62 |  val  |  val  |  | 0xFF |
+------+-------+  +------+-------+-------+  +------+
 delta=3 opt 3     delta=6 opt 9             marker
 len=1   val (1B)  len=2   val (2B)

Frame Types

Broadcast Packet

Broadcast packets carry a source and payload, with no SECINFO and no MIC. A broadcast may carry a Frame Signature option, which supplies a frame counter and an Ed25519 signature that attributes the frame to its source key.

+-----+-------+-----+---------+---------+
| FCF |[FHOPS]| SRC | OPTIONS |[PAYLOAD]|
+-----+-------+-----+---------+---------+
  1 B   0/1 B  3/32B  variable    var.

A broadcast with an empty payload is a Beacon. Beacons omit the 0xFF end-of-options marker since no payload follows (see End-of-Options Marker).

MAC Ack Packet

A MAC acknowledgement is generated by the final destination—the node that successfully processes and accepts the original packet. Repeaters do not generate MAC acks; they forward ack packets like any other packet type.

If the original packet is received again because its acknowledgement was lost, the final destination MAY retransmit the same acknowledgement without accepting or delivering the original packet again, subject to the bounded duplicate-acknowledgement window.

The ack carries two fixed trailer fields: an ack MIC—the first four bytes of the original packet’s MIC, which lets the original sender (and any repeater that forwarded the original) correlate the ack with the packet it acknowledges—and an ack tag—a MIC over the ack’s static options, bound to the packet it acknowledges, that only the original sender can verify. The ack carries no destination hint. See Ack Tag Construction for the derivation.

+-----+-------+---------+---------+---------+
| FCF |[FHOPS]| OPTIONS | ACK MIC | ACK TAG |
+-----+-------+---------+---------+---------+
  1 B   0/1 B  variable     4 B       4 B

Where:

• ACK MIC is the first 4 bytes of the original packet’s on-wire MIC—a publicly derivable correlation handle, not an authenticator
• ACK TAG is a 4-byte MIC computed with the pairwise K_mic over the ack’s FCF and static options, bound to the original packet’s full S2V output (see Ack Tag Construction)

The ACK MIC is public—any observer who received the original packet can compute it—so it provides correlation, not authentication. Authentication comes from the ACK TAG, which requires knowledge of the pairwise K_mic and cannot be produced by an observer who lacks it, even one who received the original packet in its entirety. The tag covers the ack’s static options, such as an operator callsign, so those cannot be altered in transit; dynamic options and the flood hop count remain open to repeaters, as on any packet. Because the ack carries no destination hint and the correlation handle is only a prefix of the (already public) original MIC, the ack adds no explicit endpoint identifier: an observer who received the original packet learns that it was delivered, but the ack itself names neither party. This removes the direct sender-identity leak a destination hint would introduce; it does not by itself defeat correlation by other means (timing, RF fingerprinting, or tying the ack back to an original packet that already exposed endpoint hints). For blind unicast, whose forward frame conceals both endpoints from non-channel observers, this keeps the ack from undoing that concealment.

Because the ack carries no destination hint, it is a return-routed token: it is routed back to the original sender using whatever routing state is available—a cached source route, a cached flood response scoped by FHOPS_ACC and any learned region-code options, or both. See Route Learning for how nodes learn and cache routing information from incoming packets. For reliable ack delivery over long source-routed paths, the original sender should include a Trace option. The original sender matches an incoming ack to an outstanding request by its ACK MIC, then verifies the ACK TAG; a colliding ACK MIC from an unrelated exchange fails tag verification and is discarded.

Because the ack trailer (ACK MIC followed by ACK TAG) is a known fixed length and no payload follows, the options field MUST be followed immediately by the trailer with no intervening bytes. The 0xFF end-of-options marker MAY be omitted (the trailer length is what bounds the options region). If the marker is present it MUST be the last byte of the options region—receivers MUST reject packets that carry trailing bytes between the marker and the ack trailer.

Unicast Packet

Unicast packets are addressed by destination hint and carry the source address.

+-----+-------+-----+-----+---------+---------+---------+-------+------+
| FCF |[FHOPS]| DST | SRC | SECINFO | OPTIONS |[PAYLOAD]| [SIG] | MIC  |
+-----+-------+-----+-----+---------+---------+---------+-------+------+
  1 B  0/1 B   3 B  3/32B   5/7 B    variable    var.    0/64 B 4-16 B

DST is the first three bytes of the recipient’s public key. SIG is present when the SCF’s D bit is set (see Frame Signatures); this holds for every packet type that carries SECINFO.

Receivers first use DST as a cheap filter, then use the source public key (or its cached equivalent when only a hint is present) and their own key to derive the shared secret and authenticate/decrypt the packet.

Unicast Packet with Ack Requested

This is identical to unicast, but the packet-type value signals that a MAC acknowledgement is requested.

+-----+-------+-----+------+---------+---------+---------+-------+------+
| FCF |[FHOPS]| DST | SRC  | SECINFO | OPTIONS |[PAYLOAD]| [SIG] | MIC  |
+-----+-------+-----+------+---------+---------+---------+-------+------+
  1 B  0/1 B   3 B   3/32B   5/7 B    variable    var.    0/64 B 4-16 B

Semantics differ, wire layout does not.

Multicast Packet

Multicast packets carry a 2-byte channel identifier derived from the channel key.

Channel Identifier Derivation

channel_identifier = HKDF-SHA256(channel_key, salt="UMSH-CHAN-ID", info="", L=16)
channel_id         = first_2_bytes( channel_identifier )

The CHANNEL field carries channel_id. The full 16-byte channel identifier is what names a channel where two channels must be told apart without revealing either key—two keys can derive the same 2-byte channel_id, and management interfaces cannot leave that ambiguous. The same derivation extended to 32 bytes is the channel commitment that binds a frame signature to its channel.

Encrypted Multicast (E = 1)

When encryption is enabled, the source address is encrypted together with the payload, concealing the sender’s identity from observers who do not possess the channel key.

+-----+-------+---------+---------+---------+----------------------------+------+
| FCF |[FHOPS]| CHANNEL | SECINFO | OPTIONS | ENCRYPT(SRC+PAYLOAD+[SIG]) | MIC  |
+-----+-------+---------+---------+---------+----------------------------+------+
  1 B  0/1 B     2 B     5/7 B    variable       3/32 + var. + 0/64     4-16 B

The SRC inside the ciphertext follows the S flag convention: a 3-byte hint when S is clear, or the full 32-byte public key when S is set.

Only a node with the correct channel key can recover the source address and payload.

Unencrypted Multicast (E = 0)

When encryption is not enabled, the source address appears in cleartext, but in the same place that it appeared in encrypted multicast. SRC is covered by the MIC as part of the plaintext, just as when it is encrypted (see Associated Data):

+-----+-------+---------+---------+---------+------+---------+-------+------+
| FCF |[FHOPS]| CHANNEL | SECINFO | OPTIONS | SRC  | PAYLOAD | [SIG] | MIC  |
+-----+-------+---------+---------+---------+------+---------+-------+------+
  1 B  0/1 B     2 B     5/7 B    variable  3/32 B    var.    0/64 B 4-16 B

Blind Unicast Packet

Blind unicast uses a multicast channel to conceal sender and destination metadata from observers without the channel key while still protecting the payload end-to-end for the actual destination.

Like other channel-addressed packets, blind unicast honors the E flag in SECINFO.

Encrypted Blind Unicast (E = 1)

+-----+-------+---------+---------+---------+-------------+-------------+------+
| FCF |[FHOPS]| CHANNEL | SECINFO | OPTIONS | ENC_DST_SRC | ENC_PAYLOAD | MIC  |
+-----+-------+---------+---------+---------+-------------+-------------+------+
  1 B  0/1 B     2 B     5/7 B    variable      6/35 B    var. + 0/64   4-16 B

The MIC is computed using the blind unicast payload keys, which combine the pairwise shared secret with the channel key. It covers the payload, and the plaintext DST and SRC as part of the associated data. ENC_DST_SRC is encrypted using the channel’s derived encryption key K_enc_channel (see Multicast Packet Keys) and an IV derived from the MIC (see Blind Unicast Address Encryption). Any change to ENC_DST_SRC changes the recovered destination or source address, and the MIC check rejects the packet.

Unencrypted Blind Unicast (E = 0)

When encryption is disabled, blind unicast still uses the channel identifier and the blind-unicast packet type, but the destination hint, source address, and payload appear in cleartext:

+-----+-------+---------+---------+---------+-----+------+---------+-------+------+
| FCF |[FHOPS]| CHANNEL | SECINFO | OPTIONS | DST | SRC  | PAYLOAD | [SIG] | MIC  |
+-----+-------+---------+---------+---------+-----+------+---------+-------+------+
  1 B  0/1 B     2 B     5/7 B    variable   3 B  3/32 B    var.    0/64 B 4-16 B

In this mode, the packet remains channel-associated and authenticated with the blind-unicast keys, but it does not conceal sender or destination metadata. This can still be useful when an implementation wants channel-associated unicast semantics without encryption.

Blind Unicast Processing

1. Receiver uses CHANNEL to identify candidate channel keys.
2. Receiver derives the channel’s candidate keys via HKDF.
3. If E = 1, receiver reads the MIC and uses K_enc_channel plus MIC to decrypt ENC_DST_SRC, recovering the destination hint and sender address.
4. If E = 0, receiver reads DST and SRC directly from the cleartext packet.
5. Receiver converts the sender Ed25519 public key into an X25519 public key.
6. Receiver converts its own Ed25519 private key into an X25519 private key.
7. Receiver performs ECDH and derives the stable pairwise keys.
8. Receiver computes the blind unicast payload keys by XORing the pairwise keys with the channel keys.
9. If E = 1, receiver decrypts ENC_PAYLOAD using the blind unicast payload keys.
10. Receiver verifies the blind-unicast MIC, whose associated data includes the plaintext DST and SRC whether or not E is set.
11. If verification fails, the packet is rejected. This covers a tampered address block as well as a tampered payload.

Some repeaters may decline to forward blind unicast packets for unknown channels.

Blind Unicast with Ack Requested

Same wire layout as blind unicast, but with ack-requested semantics.

+-----+-------+---------+---------+---------+-------------+-------------+------+
| FCF |[FHOPS]| CHANNEL | SECINFO | OPTIONS | ENC_DST_SRC | ENC_PAYLOAD | MIC  |
+-----+-------+---------+---------+---------+-------------+-------------+------+
  1 B  0/1 B      2 B     5/7 B    variable     6/35 B    var. + 0/64   4-16 B

Packet Options

UMSH packet options use the delta-length encoding described in Packet Structure. Each option has a numeric option number whose low four bits encode its semantic attributes:

• Bit 0: Forwarding-Critical (1) / not (0)
• Bit 1: Dynamic (1) / Static (0)
• Bits 2 and 3: both set on a static option ((number & 0xE) == 0xC): Delivery-Critical

This means a node can determine an unrecognized option’s attributes by inspecting its option number without consulting a registry.

Attribute Encoding

The attribute combinations and their option number patterns, by the low four bits of the number:

Dynamic options are never delivery-critical. Delivery-criticality is an end-to-end demand from the sender, and only a static option, which the MIC and any frame signature cover, can carry one.

Forwarding and Delivery Criticality

These determine behavior when a node encounters an unknown option. The two classes are independent, and a node that both forwards and receives a packet applies each check to its own role.

• Forwarding-Critical (bit 0 set): if unrecognized, a repeater does not forward the packet. It can still deliver the packet locally.
• Delivery-Critical (low four bits 12 or 13): if unrecognized, an endpoint does not accept, deliver, or acknowledge the packet. It drops the packet and counts the drop. Repeaters forward it as normal.
• Non-Critical: if unrecognized, the option is ignored and the node continues processing.

A recognized option whose value the node cannot interpret, such as one of the wrong length, is handled as unrecognized, within the option’s own classes.

MAC acks are exempt from delivery-critical interpretation. An ack delivers nothing, so a receiver accepts an otherwise valid ack whatever delivery-critical options it carries. Every static option on an ack, recognized or not, is still covered by its ack tag.

Dynamic vs. Static

These determine whether an option is covered by the MIC:

• Dynamic (bit 1 set): not protected by the security MIC; may be modified in transit by repeaters
• Static (bit 1 clear): protected by the security MIC; must not be modified in transit

This distinction allows forwarding-related metadata (source routes, traces, station callsigns) to be modified by repeaters without invalidating end-to-end authentication.

Defined Options

Frame Signature (option 0)

• Type: FRAME COUNTER (4 B, big-endian) ‖ SIG (64 B), exactly 68 bytes.
• Semantics: a frame signature for a broadcast, which has no SECINFO to carry a counter or the D bit. SIG is an Ed25519 signature by the source key over the signature input, in which this option’s 64 signature bytes are replaced by zeros. FRAME COUNTER is drawn from the sender’s one counter sequence, and a verified frame is judged by the signed-frame counter rules.
• Defined for broadcast only. A sender MUST NOT include it on a packet type that carries SECINFO, which signs with the SCF’s D bit instead; a receiver ignores it there.
• A value of any other length is handled as an unrecognized option.
• A sender MUST NOT include more than one. A broadcast carrying more than one is treated as unsigned.
• The full source key is not required. A hint-only signed broadcast can be verified only by a receiver that already holds the sender’s key.

Source Route (option 3)

• Semantics: contains an ordered list of repeater hints designating the forwarding path.
• A sender MUST NOT include more than one. A packet carrying more than one is handled as carrying an unrecognized forwarding-critical option.
• Repeater behavior:
  • Only the repeater matching the first hint may forward the packet.
  • That repeater removes its own hint before retransmission.
  • If removing its own hint leaves zero remaining hints, the repeater still preserves the source-route option with an empty value.
    • This is important: the forwarded packet still carries the information that it was explicitly source-routed, even though the route is now exhausted.
    • Removing the last hint does not change what kind of hop this is. The repeater was named, so it forwards as a source-routed hop and leaves FHOPS, region policy, and signal-quality thresholds alone. The next repeater sees the empty option and is the first to flood.
  • Repeaters that do not match the first hint must not forward the packet.
• Value layout: see Source Route Option Value.

Operator Callsign (option 4)

• Encoding: ARNCE/HAM-64 (2, 4, 6, or 8 bytes; encodes callsigns up to 12 characters)
• Semantics: identifies the original packet sender’s amateur radio callsign.
• Use: required for locally originated packets in Licensed-Only amateur operation.
• In Hybrid operation, its presence marks the packet as eligible for forwarding under amateur-radio authority; packets without it may still be forwarded under unlicensed authority if local rules allow.

Minimum RSSI (option 5)

• Type: unsigned 1-byte integer, interpreted as a negative dBm value
• A sender MUST NOT include more than one. A packet carrying more than one is handled as carrying an unrecognized forwarding-critical option.
• Semantics: packet must be received with at least this RSSI to be flood-forwarded. This option does not apply to source-routed hops.
• Example: value 130 means -130 dBm
• If present with no value (length 0), default is -100 dBm (THIS VALUE IS SUBJECT TO CHANGE)
• If a repeater has a locally configured minimum RSSI, it must use the higher of the packet’s minimum RSSI threshold and the repeater’s configured minimum RSSI threshold.

Route Retry (option 6)

• Type: flag. A sender includes it with no value; a receiver treats the option as present whatever its value, and a forwarder carries the value unchanged.

• Semantics: indicates that the originator is re-attempting delivery of the same logical packet after its acknowledgment timed out: either a route it had assumed failed, or, for a packet that assumed none, the acknowledgment was lost on its way back (Route Failure Recovery).

• A sender MUST NOT include more than one. A receiver reads the first and ignores the rest, and a forwarder carries only the first.

• This option is intended for sender-originated route recovery, not for ordinary first transmission. A sender sends at most one Route Retry of a logical packet.

• The failed assumption need not be a source route. A sender that narrowed FHOPS because it believed the destination was directly reachable, or reachable within a known flood distance, has made the same kind of assumption; nothing on the wire distinguishes that packet from an ordinary short-radius flood, and the recovery is the same.

• When present, repeaters treat the packet as a distinct forwarding attempt for duplicate-suppression purposes even though the MIC and frame counter are unchanged.

• The destination does not treat this option as creating a new logical packet. Replay acceptance and duplicate application delivery remain governed by the packet’s normal security state, especially its frame counter.

• A Route Retry that duplicates a packet the destination already acknowledged tells it that acknowledgment was lost. The destination re-acknowledges by a scoped, traced flood instead of along the route the lost acknowledgment took (Lost Acknowledgments).

• A sender using this option for route recovery typically:

  • removes the stale source-route option, if one was present
  • adds or refreshes flood hops, up to but not beyond the budget the sending application was willing to spend; a packet that already flooded at that budget keeps it
  • includes a Trace option to learn a replacement route
  • preserves the same frame counter and payload

  Each of these rewrites a field the associated data excludes, which is what lets the retry reuse the original MIC unchanged. Adding FHOPS to a packet that had none also sets the FCF’s H bit, and the AAD clears that bit for this reason.

Trace (option 7)

• Semantics: if present, each hop that forwards the packet prepends a record of itself before retransmitting, so the value lists the hops the packet took, most recent first. If absent, no trace information is added.
• Each record names the hop’s router hint and the signal with which that hop received the packet. Value layout and forms: see Trace Option Value.
• The option is forwarding-critical. A repeater that does not implement it does not forward a traced packet, so a trace never silently skips a hop; that repeater still forwards untraced packets.
• A sender MUST NOT include more than one. A receiver reads the first and ignores the rest, and a forwarder carries only the first.
• A malformed value is handled as unrecognized: a repeater does not forward the packet, and a receiver ignores the trace and still delivers the packet.

Signal. A record’s RSSI byte is the negative of the RSSI in dBm (so −90 dBm becomes 90), and its SNR byte is the signed SNR in cB (centibels, or tenths of a dB). A hop that received the packet over a point-to-point link rather than the air—a bridge, for example—writes zero for both. The zero entry marks a hop with no radio in it, so it has no signal to report and does not lose packets to fading. A hop that received the packet over the air never writes it: a reading of 0 dBm or stronger is carried as an RSSI byte of 1.

Sender. A sender that includes a Trace option originates the packet at least one byte below the frame limit, which leaves room for the last-resort form on a link with the same limit when the repeater adds nothing else. A repeater that also inserts a Region Code or inserts or lengthens a Station Callsign may need more than that byte; if even the last-resort form does not fit, the repeater does not forward the packet on that link.

Receiver.

• A complete trace, with signal or hints only, is a complete path. It is used for routes and hop counts; a hints-only trace lacks only the per-hop signal, and the receiver still measures the final link’s signal itself.
• A truncated trace reports the most recent hops but is not a complete path. Nothing builds a route from it: route learning, acknowledgement return routes, and source routes built from observed hints all require a complete trace.
• The hop count of a packet with a truncated trace is FHOPS_ACC + 1 if the packet carries no Source Route option, and unknown if it carries one.

Ack MIC (option 8)

This option is a piggy-backed acknowledgement: a packet carrying it acknowledges the packet whose ack_mic it names, exactly as a MAC ack for that packet would. A destination that answers an ack-requested packet with a unicast or blind unicast of its own MAY include the option in the answer, whether or not it also sends the standalone MAC ack. The original sender takes whichever of the two arrives first as the acknowledgement; the other then matches no outstanding packet and is discarded.

• Type: 4-byte ack MIC—the first 4 bytes of the acknowledged packet’s on-wire MIC (see Ack Tag Construction).

The option carries only the correlation handle, not a keyed ack tag: the packet carrying the option is itself authenticated to the original sender, so its own MIC already proves the acknowledgement is genuine. The ack_mic value simply identifies which outstanding request the reply acknowledges. The original sender accepts the option only on a packet authenticated as coming from the destination of the packet it names.

The option is a courtesy to the original sender. A sender that cannot fit it into a frame omits it.

Because the option sits in the plaintext options block, forwarders read it under the same terms as a standalone MAC ack, including for ack cancellation.

On a Verify Frame the option names the packet to be verified instead of acknowledging it: the sender holds that packet but has not accepted it, so the original sender MUST NOT treat the option as an acknowledgement (see Counter Resynchronization). Forwarders still apply ack cancellation, since the named packet has reached its destination.

Minimum SNR (option 9)

• Type: signed 1-byte integer, in dB
• Semantics: packet must be received with at least this SNR to be flood-forwarded. This option does not apply to source-routed hops.
• If present with no value (length 0), default is -3 dB. (THIS VALUE IS SUBJECT TO CHANGE)
• A sender MUST NOT include more than one. A packet carrying more than one is handled as carrying an unrecognized forwarding-critical option.
• If a repeater has a locally configured minimum SNR, it must use the higher of the packet’s minimum SNR and the repeater’s configured minimum SNR.

Region Code (option 11)

• Type: 2-byte region identifier
• Semantics: restricts flood-routing to repeaters configured for the specified region.
• A repeater configured for one or more regions MUST NOT flood-forward a packet whose region is none of them. A repeater configured for no regions makes no regional claim and applies no such restriction.
• This option MUST NOT be enforced on a source-routed hop, which includes the hop that removes the last remaining hint. A repeater named in the route forwards regardless of region.
• Multiple region-code options may appear on the same packet. In that case, a repeater MAY flood-forward the packet if any one of the listed regions matches local policy.
• Because this option is dynamic, repeaters may insert it while flood-forwarding a packet that currently has no region code.
• A repeater must never rewrite an existing region code and must never add a second region code to a packet that already has one or more region-code options.
• Region insertion is a local policy decision. When no explicit local policy exists, a reasonable default is the IATA code of the closest regional commercial airport.
• Region insertion applies only during flood forwarding. An untagged source-routed packet is first tagged by the repeater that flood-forwards it—the one that receives it with an already-empty source route—not by the repeater that emptied the route.

Region Code Encoding

Region codes are 2-byte identifiers derived by one of two methods, depending on the type of region. Both ignore ASCII case—ARNCE/HAM-16 encodes A–Z and a–z alike, and the hash folds A–Z to lowercase a–z before it is taken, altering no other character. Strings that differ only in ASCII case therefore derive the same code and name the same region.

As with channel names, folding is restricted to ASCII: correct case-folding of the full Unicode range is locale-dependent, and a name that folded under one implementation and not another would be two regions on one mesh.

Short codes. A region named by one to three ASCII letters or digits encodes directly into a 16-bit value with ARNCE/HAM-16, the unused trailing characters left as NUL. Three letters are conventionally the IATA code of the nearest airport or of a metro area that has one; two are conventionally an ISO 3166-1 alpha-2 country code or a bare subdivision code, for a region that spans one. Examples:

An all-letter short code is exclusive: the transform below vacates every one of them, so no named region can ever derive one. A short code bearing a digit—W7, 5X2—encodes just as faithfully and no two short codes ever share a code, but it is not vacated, so it shares its space with the hashes. Such a code is worth using when a mnemonic is wanted in place of a hash, and it is nothing more than that: an implementation MUST NOT display a region code as a digit-bearing short code, because the code it is reading may equally have come from a name.

/, -, and ^, though ARNCE spells them, MUST NOT appear in a short code. The transformed codes are led by / and -, and a short code able to reach that space would read back as a region it is not.

Named regions. For regions that a short code does not suit (super-regions, cities without a nearby airport, geographic areas, etc.), the region code is the first two bytes of the SHA-256 hash of the folded region name (UTF-8 encoded), EXCEPT when performing ARNCE/HAM-16 decoding on the resulting value would yield nothing but letters—one, two, or three of them. In that case, you additionally perform the following transform:

def transform_letter_chunk(encoded: int) -> int:
    """Transform an all-letter ARNCE chunk into a non-letter ARNCE chunk."""

    LETTER_MIN = 1
    LETTER_MAX = 26

    TRANSFORM_BASE = 27 * 1600                    # 0xA8C0
    TWO_LETTER_BASE = TRANSFORM_BASE + 26 ** 3    # 0xED68
    ONE_LETTER_BASE = TWO_LETTER_BASE + 26 ** 2   # 0xF00C

    a = encoded // 1600
    b = (encoded // 40) % 40
    c = encoded % 40

    def is_letter(x: int) -> bool:
        return LETTER_MIN <= x <= LETTER_MAX

    if not is_letter(a):
        return encoded

    if is_letter(b) and is_letter(c):
        return TRANSFORM_BASE + (a - 1) * 26 * 26 + (b - 1) * 26 + (c - 1)
    if is_letter(b) and c == 0:
        return TWO_LETTER_BASE + (a - 1) * 26 + (b - 1)
    if b == 0 and c == 0:
        return ONE_LETTER_BASE + (a - 1)
    return encoded

The three lengths occupy three consecutive blocks, longest first, and together vacate 18,278 of the 64,000 encodable chunks. The highest code the transform yields is 0xF025; every one of them decodes to a string led by / or -, and so to nothing that reads as a region.

Examples, with the folded name each hash is taken over:

Note that the first two bytes of the SHA256 of “rogue valley” is 0x3F56, which would decode to JEN, so it is transformed to 0xC0F9, which decodes to no letters. “wasatch front” hashes to 0x5FA0, which would decode to the two letters OL, and is transformed to 0xEEDF for the same reason.

Thus, a hash-derived region code will never collide with an all-letter short code. This allows all region codes which decode to nothing but letters to be assumed to be short codes and to be used/displayed unambiguously without additional context.

However, collisions can still happen between hash-originated region codes, and between one of those and a digit-bearing short code. These collisions are rarely of practical concern. If a region code in one part of the world collides with a region code in a different part of the world, there is no actual ambiguity because flood repeating is an inherently local event. In the rare case of a collision within a geographic area, it can be resolved by adjusting the named region slightly (for example, making it more specific).

The assignment and scope of hash-derived region codes—and resolution of any collisions—are generally handled locally.

Literal codes. In any context that takes a region’s string form, a string of 0x followed by four hexadecimal digits (e.g. 0x31d9) denotes the two-byte code it spells. Strings of this shape are by definition excluded from the other two derivations—there is no named region 0x31d9, only the code. This is also the display form for a code that reads as no short code and whose name is unknown, so a region list read off the air can be fed back in unchanged. Note that a string of one to three characters is a short code before it is anything else: 0x1 encodes as the three characters 0, x, 1, and only 0x followed by four hexadecimal digits is a literal.

A region name MUST NOT exceed 24 bytes of UTF-8. Names travel on the wire in identity payloads, and the bound is what lets a list of them fit there.

Capitalization. Folding applies to derivation and comparison, not to storage: wherever a region is held or carried in its string form—a repeater’s configured list, the Supported Regions identity option—it keeps the capitalization it was written with. A set of regions holds at most one entry per folded string; writing a region already present in a different capitalization respells the entry rather than adding a second one. A short code is displayed uppercase whatever case it was written in.

Station Callsign (option 15)

• Encoding: ARNCE/HAM-64 (2, 4, 6, or 8 bytes; encodes callsigns up to 12 characters)
• Semantics: identifies the transmitting station’s amateur radio callsign.
• If absent, the station callsign is assumed to equal the source callsign (if present)
• This option is forwarding-critical because repeaters must replace or remove it during forwarding.
• Use:
  • in Licensed-Only mode, repeaters replace or insert it on every forwarded packet
  • in Hybrid mode, repeaters also replace or insert it on every forwarded packet
  • in Unlicensed mode, repeaters remove it if present and do not add their own

Fence (option 257)

• Type: flag. A receiver ignores it whatever its value, and a forwarder carries it unchanged.
• Semantics: none. A sender does not include it.

Routing Option Layouts

Source Route Option Value

A source-route option contains zero or more router hints:

+----------+----------+----------+-----+
|  RH[0]   |  RH[1]   |  RH[2]   | ... |
+----------+----------+----------+-----+
    2 B         2 B       2 B

Where each RH[i] is the first two bytes of a repeater’s public key.

Interpretation:

• RH[0] is the next repeater that must forward the packet
• when that repeater forwards, it removes RH[0]

An empty source-route option indicates that all explicit routing hints have been consumed.

• For forwarding purposes, an empty source-route option behaves the same as an absent source-route option: there is no remaining explicit next hop.
• However, it is still semantically useful and should be preserved when produced by forwarding, because it records that the packet did in fact traverse an explicit source-routed path before the hints were exhausted.

Trace Option Value

A complete trace with signal contains zero or more 4-byte records:

+----------+--------+--------+----------+--------+--------+-----+
|  RH[0]   | RSSI[0]| SNR[0] |  RH[1]   | RSSI[1]| SNR[1] | ... |
+----------+--------+--------+----------+--------+--------+-----+
    2 B       1 B      1 B       2 B       1 B      1 B

Each hop prepends its own record:

new_trace = my_router_hint || rssi || snr || old_trace

So the list is ordered most-recent hop first. A bridge prepends a record as a repeater does, with zero signal bytes.

A trace can outgrow the frame limit as hops add records: each record adds 4 bytes, and the option’s length field gains a byte once the value passes 12 bytes. The path matters more than the per-hop signal, so a trace that no longer fits first sheds its signal and only then drops hops. The value takes one of three forms:

Hints are most recent first in every form, and a lone 0xFE or 0xFF is valid. The length tells the hints-only forms apart from a record list whose first router hint happens to begin with 0xFE or 0xFF. Every other value is malformed: a length of 2 modulo 4, or an odd length beginning with any other byte.

Before forwarding a traced packet, a repeater computes the exact size of the forwarded packet on the outgoing link, including any options it inserts, and takes the first of these that fits:

1. Add its own entry in the trace’s current form: a 4-byte record to a trace with signal, or its 2-byte hint to a 0xFE or 0xFF trace.
2. For a trace with signal: convert it to 0xFE ‖ hints and add its own hint.
3. Convert it to 0xFF ‖ hints, add its own hint, and drop hints from the end, oldest first, until the packet fits. A lone 0xFF is the last resort.
4. If even a lone 0xFF does not fit, do not forward the packet on that link, and count the drop.

Forms only degrade. No repeater adds signal to a hints-only trace, so the forms never mix, and a 0xFF trace never returns to 0xFE.

Security & Cryptography

UMSH authenticates and optionally encrypts packets using AES-SIV (RFC 5297) with AES-256. Unicast packets are secured with pairwise keys derived from X25519 ECDH between sender and recipient Ed25519 keys. Multicast packets are secured with keys derived from the shared channel key. In both cases, a monotonic frame counter provides replay protection without requiring synchronized clocks. Any frame other than a MAC ack may also carry an Ed25519 frame signature that attributes it to its sender’s key.

Each secured packet carries a Security Information (SECINFO) field containing a Security Control Field, a frame counter, and an optional salt. The sections below describe these fields, the key derivation process, and the cryptographic operations applied to each packet.

Security Information (SECINFO)

SECINFO Encoding

+--------+--------------------+----------------+
|  SCF   | FRAME COUNTER (4B) | [SALT (2B)]    |
+--------+--------------------+----------------+
   1 B            4 B              0/2 B

Security Control Field

  7   6   5   4   3   2   1   0
+---+-------+---+---+-----------+
| E |  MIC  | S | D | RESERVED  |
+---+-------+---+---+-----------+
 1b   2 bits 1b  1b    3 bits

Where:

• E = encrypted payload flag
• MIC = MIC size code
• S = salt included
• D = signed: a 64-byte frame signature follows the payload
• RESERVED = must all be set to zero

If the RESERVED bits read as anything other than zero, the packet MUST be dropped by the recipient.

MIC size encodings:

The MIC is produced by computing the full 16-byte synthetic IV V with S2V (RFC 5297 §2.4) and truncating to the specified length. The S2V output is an AES-CMAC, and truncation of CMAC outputs is permitted by NIST SP 800-38B.

MIC Size Selection Guidance

Shorter MICs save bytes on the wire but reduce forgery resistance and increase the probability of duplicate-suppression collisions in repeater caches (see Duplicate Suppression). The following guidelines help choose an appropriate MIC size:

• 16 bytes (default): Recommended for long-term stable identities where the same pairwise keys may be used for months or years. The cost of a successful forgery is high (attacker gains persistent access to impersonate a node), and the 2^-128 forgery probability makes brute-force infeasible regardless of how many packets an attacker can attempt.

• 8 bytes: A reasonable middle ground for most communication. Provides 2^-64 forgery probability—well beyond practical brute-force for LoRa’s low packet rates—while saving 8 bytes per packet. Suitable for general unicast and multicast traffic.

• 4 bytes: Appropriate for short-lived contexts where the keys will be discarded soon, such as PFS sessions or one-time exchanges using ephemeral node addresses. The 2^-32 forgery probability (~1 in 4 billion) is adequate when the window of exposure is brief. Also useful for latency-sensitive or payload-constrained scenarios where every byte matters, such as sensor telemetry on slow LoRa links.

• 12 bytes: Available as an intermediate option when 8 bytes feels too tight but 16 bytes is more overhead than warranted. Provides 2^-96 forgery probability.

As a general principle: the longer the keys will be in use and the higher the value of the traffic they protect, the larger the MIC should be. For ephemeral keys that will be erased within minutes, a small MIC is sufficient. For a node’s long-term identity keys, prefer the full 16 bytes.

Frame Counter

The 4-byte frame counter must increase monotonically. UMSH uses this monotonic counter—rather than timestamps—for replay protection, keeping the protocol free of any dependency on synchronized clocks or absolute time.

A node address draws the counters of all its secured and signed frames—unicast, blind unicast, multicast, and signed broadcast—from one monotonic sequence, and MUST NOT let that sequence go backward (see Counter Persistence). A receiver judges every frame authenticated as a peer’s, whether pairwise or by a frame signature, against one baseline for that peer, so the sequence belongs to the sending address, not to a destination or channel.

Replay Detection

A receiver determines whether a frame counter is acceptable by computing:

delta = (received_counter - last_accepted_counter) mod 2^32

If delta is zero or exceeds the forward window, the packet is rejected. This modular comparison allows the counter to wrap around 2^32 without requiring special overflow handling. The suggested default forward window is 172800. Implementations MAY use a different value, but it should be large enough to accommodate gaps from packets sent to other destinations and small enough to limit the scope of replay attacks.

Implementations that need to tolerate out-of-order delivery may also define a backward window—a small range of counter values behind the highest accepted counter within which late-arriving packets are still considered. The suggested default backward window is 8. When a packet’s counter falls within the backward window, the receiver checks a small cache of recently accepted packets, keyed by frame counter and MIC (similar to the approach used for duplicate suppression in repeaters): if the packet is already present, it is a replay and is rejected; if not, the packet is accepted and added to the cache.

Regardless of window sizes, a packet must not be accepted if it is more than 5 minutes out of order—that is, if the highest accepted counter was last advanced more than 5 minutes ago and the received counter is behind it. MIC cache entries only need to be retained for the duration of this time bound. Additionally, the first packet accepted from a given node (or after a counter resynchronization) establishes that node’s counter baseline—packets with earlier counter values must be rejected, even if they arrive within the backward window.

Duplicate Acknowledgement Window

Rejecting a packet as a duplicate does not prohibit retransmitting its MAC acknowledgement. An authenticated packet that requests an acknowledgement and whose MIC identifies it as a previously received packet MAY be acknowledged again if its frame counter is no more than 8 counts behind the highest accepted counter for that traffic direction, inclusive. Equivalently:

ack_distance = (last_accepted_counter - received_counter) mod 2^32

The duplicate may be acknowledged only when ack_distance <= 8. A receiver MUST NOT acknowledge a replay farther behind the stored counter. Re-sending the acknowledgement is idempotent and allows a sender to recover when the original acknowledgement was lost; it does not accept the packet as new and MUST NOT advance or otherwise modify the stored replay baseline. A receiver may suppress duplicate delivery itself. In a split implementation, such as a companion radio and host MAC, it may instead pass the authenticated duplicate to the host, which is then responsible for suppressing duplicate application delivery.

Eligibility is not obligation: re-acknowledgement SHOULD be paced. Flood routing delivers one transmission as several copies, and a copy of a transmission whose acknowledgement was already sent proves nothing was lost. A receiver SHOULD NOT acknowledge the same packet more than once per forwarding-confirmation window, measured from its most recent acknowledgement of that packet: copies arriving inside the window share the acknowledgement already sent, while a sender that lost its acknowledgement cannot retransmit before its own confirmation window has lapsed.

A duplicate that carries the Route Retry option, of a packet already acknowledged and arriving after this window, shows that the acknowledgement was lost on its way back. Its re-acknowledgement SHOULD NOT follow the route the lost one took (Lost Acknowledgments). Any other late duplicate may have crossed an acknowledgement still in transit and says nothing about the route.

Payload acceptance does not begin the acknowledgement pacing window. A destination may accept an overheard source-routed copy while hints remain, withholding its ACK until the route is consumed. The first eligible copy may then be acknowledged immediately. A duplicate remains the same accepted packet: acknowledging it does not renew its replay-retention interval or deliver the payload again.

Signed-Frame Counters

A frame whose frame signature verifies is judged by the rules above against its signer’s counter, and is either accepted or dropped. The cache of recently accepted packets keys a signed broadcast, which has no MIC, by its frame counter and the first 16 bytes of its signature.

• Known peer. A frame signed by a known peer is checked against that peer’s receive baseline, the one its unicast traffic is checked against. Because the peer draws every counter from one sequence, its signed multicast and broadcast frames continue the sequence its unicast frames follow.
  • An accepted frame advances the baseline, which is persisted as for unicast.
  • A replay is dropped.
  • A frame behind the baseline or outside the forward window is dropped. When the gap is too large for reordering to explain, the receiver MAY start counter resynchronization with an Echo Request, at the usual rate limit.
• Stranger. A frame that verifies against a key that is not a known peer’s is first contact: it is accepted at face value, as Counter Resynchronization describes for any new peer. Later frames from that key are judged by the same rules, in a window the receiver keeps for that signing key. A frame behind that window’s baseline or outside it is dropped, with no resynchronization, since there is no pairwise relationship to run one over.
  • A receiver MAY discard a stranger’s window when it is idle or under memory pressure.
  • After a discard, or after the receiver restarts, the stranger’s next frame is first contact again, so a replay of one of its earlier frames is accepted once. With no prior knowledge of the sender, a receiver cannot tell that replay from a new frame.

Counter Persistence

How a node persists and recovers its own frame counter across reboots is implementation-specific. Possible strategies include writing the counter to non-volatile storage periodically or advancing the counter by a large margin on startup to avoid replaying previously used values.

A node MUST also persist each known peer’s receive baseline and restore it at startup. A node that lost a peer’s baseline would treat that peer’s next frame as first contact and accept a replay of any earlier one.

• The persisted baseline MAY lag the live one, so that writes can be batched. A node SHOULD write a peer’s baseline once it has accepted 16 frames from that peer since the last write, however far those frames moved the counter. The frames accepted since the last successful write are what an unexpected restart leaves replayable.
• Before a deliberate restart, a node SHOULD write every baseline that has changed since its last write.

Caution

If counters or baselines are written to non-volatile storage, care should be taken to avoid wearing out the underlying storage medium if it has a limited number of writes.

Counter Resynchronization

On first contact with a new peer, the received frame counter is accepted at face value and recorded as the baseline for future replay detection.

An authenticated packet from a known peer whose frame counter is far outside the window means the two nodes disagree about that counter—for example, because the peer rebooted and lost its persisted counter. Far outside means past the forward window, or far enough behind the baseline that reordering cannot explain it (the suggested threshold is 1024). The receiver MAY then re-establish a baseline with one of the two exchanges below. It SHOULD send at most one such probe to a peer every 5 seconds, and a Verify Frame or Frame Verified never prompts one.

When the packet requested an acknowledgement, the receiver—the requester—holds it without acknowledging it and sends Verify Frame to the peer, naming the packet in an Ack MIC option. The peer—the responder—proceeds as follows:

1. It matches the option against the acknowledgement-requested packets it sent to the requester that are still awaiting acknowledgement. If none matches, it ignores the Verify Frame.
2. It stops retransmitting the matched packet and answers with Frame Verified, which requests an acknowledgement.
3. When Frame Verified is acknowledged, it treats the matched packet as acknowledged. If Frame Verified is never acknowledged, the matched packet has failed.

The responder processes a Verify Frame whose own counter falls outside its window for the requester, since the match with an outstanding packet already shows the request is fresh. When Frame Verified is acknowledged, it adopts that counter as the requester’s new baseline. A Verify Frame whose counter falls within the window is subject to the ordinary replay rules.

When a Frame Verified arrives echoing the nonce of a Verify Frame for a packet the requester still holds, the requester adopts its frame counter as the peer’s new baseline, whatever the value. It then delivers the held packet and acknowledges Frame Verified; that acknowledgement stands for the held packet too, which is not acknowledged separately. A requester that no longer holds the packet discards Frame Verified without acknowledging it, so the responder reports the packet as failed. The requester MUST choose nonces so that a Frame Verified recorded from an earlier exchange cannot match a later one.

When the packet did not request an acknowledgement, the peer has nothing outstanding to match, so the receiver MAY instead send an Echo Request carrying a nonce. An Echo Response echoing it establishes the response’s frame counter as the peer’s new baseline. The packet that prompted the probe is dropped.

Salt

The optional 2-byte salt is chosen randomly to reduce the likelihood of a nonce collision.

Cryptographic Processing

Unicast Key Agreement

For unicast and blind unicast:

1. Start with sender Ed25519 keypair and recipient Ed25519 keypair.
2. Convert both Ed25519 keys to X25519 form.
3. Perform X25519 ECDH.
4. Feed the resulting shared secret into HKDF-SHA256, bound to both parties’ Ed25519 public keys.
5. Derive separate stable pairwise keys for encryption and MIC/authentication.

Ed25519 to X25519 Conversion

UMSH uses a single Ed25519 keypair per node as both its identity (for addressing) and the basis for key agreement. Standard cryptographic guidance recommends separate keys for signing and key agreement, so this choice warrants justification.

The Ed25519 and X25519 curves are birationally equivalent (both are defined over Curve25519), and the conversion between Edwards and Montgomery form is a well-understood, deterministic mapping. Using a single keypair for both purposes is not itself insecure—it is the approach taken by, among others, the Signal protocol’s X3DH key agreement and libsodium’s crypto_sign_ed25519_pk_to_curve25519 API.

The alternative—carrying separate Ed25519 (signing) and X25519 (key agreement) keys per node—would require a cryptographic binding between the two. Each node must distribute an additional 32-byte X25519 public key alongside its Ed25519 key, and the binding must be authenticated (e.g. by including the X25519 key in a signed advertisement). Every recipient must then verify that binding before trusting the key agreement key. On a LoRa link where the entire frame budget is ~255 bytes, even 32 extra bytes per identity exchange is a significant cost. By deriving X25519 keys from Ed25519 keys, UMSH eliminates this overhead entirely: the node address is the key agreement key, with no additional key distribution required.

UMSH assumes standard Edwards-to-Montgomery conversion:

• sender Ed25519 private key → sender X25519 private key
• sender Ed25519 public key → sender X25519 public key
• recipient Ed25519 private key → recipient X25519 private key
• recipient Ed25519 public key → recipient X25519 public key

Implementations MUST reject malformed public keys before conversion. A public key is accepted only if re-encoding its decoded point yields the same 32 bytes, which rejects non-canonical encodings of a point.

ECDH Shared Secret

The ECDH shared secret is:

ss = X25519(local_x25519_private, remote_x25519_public)

This shared secret is used as the input keying material for deriving the cryptographic keys to secure and authenticate messages.

HKDF Inputs for Unicast

For unicast packets, the encryption and MIC keys are derived from the X25519 ECDH shared secret and both nodes’ Ed25519 public keys, and are stable for a given pair of nodes. These keys are not derived from packet-specific fields.

Let:

ss = X25519(local_x25519_private, remote_x25519_public)

The pairwise key material is then derived as:

ikm  = ss
salt = "UMSH-PAIRWISE-SALT"
info = "UMSH-UNICAST-V3" || min(PK_a, PK_b) || max(PK_a, PK_b)
okm  = HKDF-SHA256(ikm, salt, info, 64)

PK_a and PK_b are the two nodes’ 32-byte Ed25519 public keys, ordered by comparing their encodings lexicographically, so both ends derive the same keys. Binding the full keys gives each key its own pairwise keys: an Ed25519 key and its negation convert to the same X25519 key and so produce the same shared secret, but not the same info.

The output keying material is split as follows:

K_mic = okm[0..32]
K_enc = okm[32..64]

Where:

• K_mic is the 32-byte message authentication key (the S2V key)
• K_enc is the 32-byte encryption key (the CTR key)

This layout makes okm exactly the AES-SIV key K from RFC 5297: K_mic is the leftmost half K1 (S2V) and K_enc is the rightmost half K2 (CTR), so okm can be handed directly to an AEAD_AES_SIV_CMAC_512 implementation.

These keys are stable for the sender/recipient pair and may be cached by the implementation. They do not change from packet to packet.

Because the key derivation depends only on the ECDH shared secret, the two public keys, and fixed UMSH-specific HKDF parameters, it does not need to be recomputed for each transmitted packet.

Blind Unicast Payload Keys

Blind unicast payload encryption and authentication must require knowledge of both the pairwise shared secret and the channel key. This ensures that an attacker who compromises one of the two secrets—but not both—cannot decrypt blind unicast payloads.

The blind unicast payload keys are derived by XORing the pairwise unicast keys (see HKDF Inputs for Unicast) with the channel’s multicast keys (see Multicast Packet Keys):

K_enc_blind = K_enc_pairwise XOR K_enc_channel
K_mic_blind = K_mic_pairwise XOR K_mic_channel

Where:

• K_enc_pairwise, K_mic_pairwise are the stable pairwise keys derived from the sender/recipient ECDH shared secret
• K_enc_channel, K_mic_channel are the stable channel keys derived from the channel key

Both sets of input keys are independent HKDF outputs—pseudorandom and uncorrelated. XOR of two independent uniform random values is uniform random: an attacker who knows only one side sees the combined key as informationally equivalent to a one-time pad over the unknown side.

These combined keys are stable for a given (sender, recipient, channel) triple and may be cached. If the same two nodes use blind unicast over different channels, they get different payload keys—compromise of one channel key does not expose blind unicast traffic on another channel between the same pair.

Both the pairwise and channel keys can be cached independently by the implementation. Computing the blind unicast keys requires only a 32-byte XOR per key, with no additional HKDF calls.

Per-Packet Security Inputs

Although K_enc and K_mic are stable for a given node pair, each packet still carries per-packet security inputs in SECINFO.

These inputs are:

• the 4-byte frame counter
• the optional 2-byte salt

These values are not used to derive the pairwise keys. Instead, they are used as packet-specific inputs to encryption, authentication, and replay protection.

For encrypted packets:

• K_enc and K_mic are the stable pairwise keys
• SECINFO and other immutable header fields are supplied as associated data
• the frame counter and optional salt provide packet-specific variability and replay-detection context

For authenticated but unencrypted packets:

• K_mic is the stable pairwise MIC key
• the MIC is computed over the protected packet contents and relevant static fields

The frame counter must increase monotonically for a given traffic direction. Receivers must not rely on the construction’s resistance to nonce misuse as a substitute for replay detection.

Multicast Packet Keys

For multicast, the configured channel key is the base secret. The encryption and authentication keys are derived once and are stable for a given channel.

ikm  = channel_key
salt = "UMSH-MCAST-SALT"
info = "UMSH-MCAST-V2" || channel_id
okm  = HKDF-SHA256(ikm, salt, info, 64)

K_mic = okm[0..32]
K_enc = okm[32..64]

As with the pairwise keys, okm is exactly the RFC 5297 AES-SIV key for the channel: S2V key first, CTR key second.

These keys are stable for the channel and may be cached by the implementation. They do not change from packet to packet. Per-packet variability is provided by the frame counter and optional salt in SECINFO, which serve as inputs to encryption and replay detection (see Per-Packet Security Inputs).

Encrypted Packets

When encryption is enabled, UMSH uses AES-SIV (RFC 5297) with AES-256.

The processing is:

1. Compute the full 16-byte synthetic IV V = S2V(K_mic, S1, S2) per RFC 5297 §2.4, where S1 is the canonical associated data (see Associated Data) and S2 is the plaintext.
2. Truncate V to the MIC length specified by the SCF; this is the on-wire MIC.
3. Construct the CTR IV from the MIC (see CTR IV Construction).
4. Encrypt the plaintext using AES-256-CTR with K_enc and the constructed IV. The counter is the full 16-byte IV, incremented as a 128-bit big-endian integer (RFC 5297 §2.5).

The plaintext S2 is the region of the packet after its options and before its MIC:

SIG is the frame signature, present when the SCF’s D bit is set. Blind unicast’s address block is not part of S2: it is covered through the associated data and encrypted separately (see Blind Unicast Address Encryption).

The MIC is transmitted at the end of the packet rather than prepended as in RFC 5297, allowing its length to be controlled independently via the SCF MIC size field.

With a 16-byte MIC, the result is byte-for-byte AEAD_AES_SIV_CMAC_512 (RFC 5297 §6.3): the key is K = K_mic || K_enc, the canonical AAD is the single associated-data component, and the CTR IV construction reduces to the RFC’s initial counter Q. Shorter MIC lengths use the same computation and differ only in how the CTR IV is filled.

As in RFC 5297, the synthetic IV binds the ciphertext to the key, associated data, and plaintext, so there is no caller-supplied nonce to misuse: repeating all three inputs yields an identical packet and reveals only the repetition itself. Truncated MICs weaken this bound in proportion to the truncation, since the CTR IV is reconstructed from the truncated MIC and SECINFO rather than the full V.

CTR IV Construction

The 16-byte CTR IV is constructed by appending the SECINFO field to the MIC, zero-padding or truncating the result to exactly 16 bytes, and then clearing the top bit of bytes 8 and 12 as RFC 5297 §2.6 does when forming the initial counter:

IV     = truncate_or_pad_to_16( MIC || SECINFO )
IV[8]  = IV[8]  & 0x7F
IV[12] = IV[12] & 0x7F

The bit-clearing step is applied unconditionally, whatever bytes—MIC, SECINFO, or zero padding—occupy positions 8 and 12.

For the 16-byte MIC, SECINFO is entirely truncated away and the IV is the masked synthetic IV—exactly the initial counter Q from RFC 5297 §2.6. For shorter MICs, the IV incorporates the frame counter and optional salt from SECINFO, providing additional per-packet IV variability.

Unencrypted Packets

When encryption is disabled, the MIC is computed exactly as for encrypted packets—the truncated S2V(K_mic, S1 = AAD, S2), with the same S2—and the encryption step is simply omitted. An unencrypted multicast’s SRC is therefore covered as part of S2, just as when it is encrypted.

Associated Data

The associated data (AAD) binds the immutable header fields to the MIC so that any modification is detected. The canonical AAD enters S2V as the single associated-data component S1; the plaintext S2 (see Encrypted Packets) is the final component.

The AAD is the packet’s header fields in wire order, with these differences:

• FHOPS is omitted, and the FCF enters with its flood-hops-present (H) bit cleared.
• The static options are re-encoded as type-length-value triples (see below) and dynamic options are omitted.
• The options are followed by the 2-byte terminator FF FF, which is present even when there are no static options.
• Blind unicast’s address block, DST ‖ SRC, follows the terminator in plaintext form, whether or not it is encrypted on the wire.
• Multicast’s SRC is not part of the AAD. It is part of S2, with either value of E.

Addresses enter as they appear on the wire: a hint as a 3-byte hint, and a full key only where the packet carries one.

No AAD depends on E: two packets that differ only in E have AADs that differ only in the SCF byte. A broadcast has no MIC; its AAD is used only by a frame signature.

The AAD is unambiguous because the packet format is self-describing from left to right. The FCF decides which fields are present, and its S bit gives SRC’s length; SECINFO’s own SCF gives its length. On the wire the options block is delimited by its 0xFF end-of-options marker, which the type-length-value re-encoding drops; the FF FF terminator restores that delimiter. No static option can begin with it: option number 0xFFFF has both low bits set, so it is dynamic and never enters the AAD, and no larger option number exists (see Option Encoding). The AAD therefore fixes its own end.

Dynamic options and the flood hop count are excluded from the AAD because they may be modified by repeaters during forwarding. The FCF’s flood-hops-present (H) bit is part of that budget rather than of the packet’s identity, and is cleared before the byte enters the AAD: a sender abandoning a source route re-floods a packet that is already sealed, which adds FHOPS where the original had none. Masking the bit does not weaken the binding. Flipping it on the wire shifts every field the parser reads after it, so the fields that follow enter the AAD as different values and the MIC check still fails.

A MAC Ack has no DST, CHANNEL, SRC, or SECINFO field, so its AAD is the FCF, static options, and terminator alone (see Ack Tag Construction). For an ack, masking H is what lets a re-sent acknowledgement, which may differ from the first only in its flood budget, carry the same tag.

Static Option Encoding in AAD

Static options are not included in their wire delta-length form. Instead, each static option present in the packet is re-encoded using absolute type-length-value triples:

+----------+----------+-------+
|  number  |  length  | value |
+----------+----------+-------+
    2 B (BE)   2 B (BE)  var.

Where number is the option’s absolute option number (not a delta), encoded as a 2-byte big-endian unsigned integer, and length is the value length in bytes, also encoded as a 2-byte big-endian unsigned integer. Static options appear in the AAD in order of increasing option number. This avoids recomputing deltas after dynamic options have been removed.

Using 2-byte fields for both number and length ensures that option numbers above 255 (which are valid in the CoAP-style encoding used on the wire) and long option values are represented without truncation or ambiguity. A packet that names an option number above 0xFFFF is malformed (see Option Encoding).

Ack Tag Construction

When a packet type requests an acknowledgement (UNAR or BUAR), the acknowledgement carries two 4-byte fields: an ack MIC for correlation and an ack tag for authentication.

The ack MIC is simply the first 4 bytes of the original packet’s on-wire MIC:

ack_mic = first_4_bytes( on_wire_MIC )

It is public—any node that received the original packet, including forwarding repeaters, can compute it. Its purpose is correlation: it lets the original sender match the ack to the outstanding request it belongs to, and lets a repeater that forwarded the original packet recognize the ack as its acknowledgement (enabling passive-ack optimizations). It is not an authenticator.

The ack tag is the MIC of the acknowledgement itself. Only the original sender and the final destination can produce it, and it covers the acknowledgement’s static options as well as the packet it answers:

ack_tag = truncate_to_4( S2V( K_mic, S1 = AAD_ack, S2 = V, S3 = ack_mic ) )

Where:

• K_mic is the MIC key that sealed the original packet—the pairwise key for unicast (see HKDF Inputs for Unicast), or the combined blind unicast key for blind unicast (see Blind Unicast Payload Keys)
• V is the original packet’s full 16-byte S2V output, before truncation to its on-wire MIC length
• AAD_ack is the acknowledgement’s associated data: its FCF with the H bit cleared, followed by its static options and the FF FF terminator

The three components take the shape of any other packet’s MIC: associated data first, V where a nonce would sit, and ack_mic as the payload. The component count and the acknowledgement’s own FCF keep the result distinct from every packet MIC computed under the same key. Dynamic options and the flood hop count stay outside AAD_ack, so forwarding does not disturb the tag.

Binding V ties the tag to one exchange in one direction. Both peers hold the same pairwise keys, but an acknowledgement of a packet one peer sent cannot pass for one answering a packet the other sent. V need not be secret for this; a packet sent with a 16-byte MIC carries all of it.

The standalone MAC Ack carries both fields (ack_mic followed by ack_tag, 8 bytes total). The Ack MIC option carries only ack_mic, because the packet carrying the option is itself authenticated to the original sender and therefore needs no separate keyed tag.

The ack_mic is a prefix of the original packet’s on-wire MIC, so it was already visible to anyone who received that packet. Producing the ack_tag requires K_mic, so an observer who intercepts the original packet can neither forge a standalone ack nor alter the static options of a genuine one. With a 4-byte tag, a blind forgery succeeds with probability 2^-32 per attempt, and only while the original packet still awaits acknowledgement: no offline check exists, each guess costs a transmission, and a failed guess draws no response. A successful forgery would cause the sender to treat an undelivered packet as delivered and suppress retransmission, or to act on options the destination never sent—a reliability denial-of-service confined to one exchange, not a confidentiality break. A weaker variant needs no forged tag at all: repeaters cancel queued forwards on the public ack_mic alone, so an observer who saw the original packet can suppress its pending forwards at repeaters within earshot. The exposure is the same reliability class, costs the attacker a transmission per suppression, and is bounded by the sender’s Route Retry recovery.

The correlation exposed by ack_mic is deliberate. To an observer who already received the original packet, it confirms that the packet was delivered and links the ack to that packet. Because the MAC ack carries no destination hint, it adds no explicit endpoint identifier of its own—which removes the direct sender-identity leak a destination hint would introduce. This is not a guarantee of unlinkability: a determined adversary may still correlate an ack with its endpoints through timing, RF fingerprinting, return-path analysis, or by tying the ack_mic back to an original packet that itself exposed endpoint hints. For blind unicast, whose forward frame reveals no endpoint identity to a non-channel observer, omitting the destination hint keeps that concealment from being undone by the ack.

Blind Unicast Address Encryption

Blind unicast packets encrypt both the destination hint and source address together, separately from the payload. The address block is encrypted with the channel key alone, so that any channel member can recover both the intended recipient and the sender’s identity. The payload is then encrypted with the combined blind unicast keys (see Blind Unicast Payload Keys), which require both the channel key and the pairwise shared secret.

The address block is encrypted using AES-256-CTR with the channel’s derived encryption key K_enc_channel (see Multicast Packet Keys), using the CTR IV constructed from the packet MIC and SECINFO (see CTR IV Construction).

Let:

• K_enc_channel = channel encryption key derived from the channel key via HKDF
• IV = CTR IV constructed from the packet MIC and SECINFO
• DST = 3-byte destination hint
• SRC = source address: 3-byte source hint when S=0, or 32-byte source public key when S=1

Then:

ENC_DST_SRC = AES-256-CTR( key=K_enc_channel, iv=IV, plaintext=DST || SRC )

This allows a receiver possessing the channel key to recover both the destination (to confirm the packet is addressed to them) and the source address (to derive the pairwise keys needed to authenticate and decrypt the payload).

The address block is covered by the MIC. DST ‖ SRC enters the associated data in plaintext form, so the sender computes the MIC over the plaintext addresses and only then encrypts the block with the IV that MIC yields. The receiver decrypts the block from the on-wire MIC and the channel key, which it can do before it knows the payload keys, then derives the payload keys from the recovered SRC and verifies the MIC. Any change to the encrypted block changes the recovered addresses, and the MIC fails. Because the MIC covers the addresses it was derived from, the address block’s IV is a true synthetic IV.

Frame Signatures

A frame signature is an Ed25519 signature by the sender’s node key over the bytes the MIC covers. It attributes a frame to a key: a verified signature shows that the holder of that key sent this frame, with this header and frame counter, on this channel. A channel MIC alone shows only that the sender holds the channel key.

The signature is carried in one of two ways:

• Frames with SECINFO (unicast, multicast, blind unicast): the SCF’s D bit is set, and a 64-byte SIG follows the payload and precedes the MIC. SIG is the last part of S2, so the MIC covers it, and with E set it is encrypted with the payload.
• Broadcast: the Frame Signature option carries a frame counter and the signature.

Signature Input

The signed bytes are:

signature_input = "UMSH-SIG" || AAD || [CHANNEL_COMMITMENT] || plaintext

Where:

• "UMSH-SIG" is the 8 ASCII bytes 55 4D 53 48 2D 53 49 47. It is never transmitted.
• AAD is the frame’s associated data, with the SCF’s D bit set. For a broadcast, the Frame Signature option enters the AAD with its 64 signature bytes replaced by zeros; its frame counter enters as sent.
• CHANNEL_COMMITMENT is present only on multicast and blind unicast (see Channel Commitment).
• plaintext is S2 without SIG, in plaintext form whether or not it is encrypted on the wire:

A multicast’s SRC is not in its AAD, so it enters the signature input at the front of the plaintext. The SRC that names the signing key is therefore always covered by the signature.

The input is unambiguous without length prefixes: the label has a fixed length, the AAD fixes its own end, the FCF inside the AAD decides whether a 32-byte commitment follows, and the plaintext is everything after that.

Channel Commitment

The CHANNEL field carries only a 2-byte channel identifier, which distinct channel keys can share. Without a commitment, someone holding two channel keys with the same identifier could move a signed frame from one channel to the other and recompute its MIC, and the signature would still verify on a channel its sender never signed for. The channel commitment binds the signature to the channel key:

CHANNEL_COMMITMENT = first_32_bytes( HKDF-SHA256(ikm = channel_key, salt = "UMSH-CHAN-ID", info = "") )

This is the same derivation as the channel identifier, extended to 32 bytes; the 2-byte channel_id and the 16-byte channel identifier are prefixes of it. The commitment is never transmitted. A receiver computes it from the channel key that verified the frame’s MIC, so when channel identifiers collide the signature is checked against the channel whose key authenticated the frame, never one matched by identifier alone.

HKDF is one-way, so a receiver can disclose a channel’s commitment to let a third party verify an unencrypted signed multicast without disclosing the channel key.

Verification

A receiver verifies a frame signature against the signer’s public key: the full SRC when the frame carries one, or the key of the one known peer whose hint matches SRC. A hint-only signed frame can be verified only by a receiver that already holds the sender’s key.

• A frame whose signature verifies is attributed to that key, and its counter is judged by Signed-Frame Counters.
• A frame whose signature does not verify, or whose key cannot be resolved, is not attributed to any key. It is processed as an unsigned frame from the same source would be. A failed verification is not by itself grounds to drop the frame: a hint can match a different known peer than the one that signed.

The signature does not change how a frame is authenticated. A secured frame’s MIC is verified as usual, and a frame whose MIC fails is dropped before its signature is considered.

Perfect Forward Secrecy Sessions

UMSH provides optional perfect forward secrecy (PFS) via ephemeral node addresses exchanged using the PFS Session MAC commands. Once a PFS session is established, traffic between the two nodes is encrypted and authenticated exactly as if the ephemeral addresses were any other long-term node identities. Compromise of either node’s long-term private key cannot retroactively expose traffic encrypted during a PFS session, because the private keys for the ephemeral addresses are erased when the session ends and the session’s ECDH shared secret is irrecoverable.

Handshake

A PFS session is established via a two-message exchange over the existing authenticated unicast channel:

1. Initiator: Generates a fresh ephemeral node address. Sends a PFS Session Request carrying the new ephemeral address and a requested session duration. The request is authenticated with the initiator’s long-term keys.

2. Responder: Generates its own fresh ephemeral node address. Sends a PFS Session Response carrying the responder’s ephemeral address and the accepted session duration. The response is authenticated with the responder’s long-term keys.

After this exchange, both sides hold each other’s ephemeral addresses and can independently derive the session keys. No further setup messages are required. The first data packet sent by the initiator using the ephemeral address hints serves as an implicit acknowledgement to the responder that the response was received and the session is active.

Session Key Derivation

A PFS session is cryptographically identical to a normal UMSH unicast session in every respect—the only difference is that the participating node addresses are ephemeral rather than long-term. Key derivation follows the exact same process as Unicast Key Agreement.

The PFS property arises not from any difference in how the keys are derived, but from the fact that the private keys for the ephemeral addresses are never stored durably and are securely erased when the session ends.

An ephemeral node address is a fully functional temporary UMSH node identity: it has an address hint, can be addressed directly, and its private key is converted to X25519 for ECDH the same way a long-term identity is.

Because a PFS session is indistinguishable from an ordinary unicast session at the MAC layer, it requires no changes to MAC-layer processing, no changes to any application-layer protocol, and adds zero per-packet overhead. Once the two-message handshake completes, every subsequent packet in the session is exactly the size it would have been without PFS.

Wire-Level Privacy

While a PFS session is active, packet hint fields are derived from the ephemeral node address rather than the long-term address. A passive observer sees packets flowing between two unfamiliar node IDs that appear only for the duration of the session. The only packets that expose the long-term node IDs are the two handshake messages (PFS Session Request and PFS Session Response), which are themselves protected by the long-term pairwise keys.

Because ephemeral node addresses are structurally identical to long-term node addresses, an observer cannot distinguish PFS session traffic from ordinary unicast traffic, nor associate the ephemeral addresses with the original nodes that created the session.

This identity separation is not unconditional. The PFS handshake messages are authenticated with the nodes’ long-term keys, so an attacker who later compromises a long-term private key can retroactively identify which long-term identities established the session—even though the session’s content remains protected by the erased ephemeral keys.

Additionally, implementations that use a single device-wide frame counter expose a correlation opportunity: an observer who can read the frame counter field across packets (e.g. by receiving a packet before and after the PFS handshake) may notice continuity in the counter value and link the ephemeral addresses to the originating nodes. Implementations that wish to preserve wire-level identity unlinkability should use independent frame counters for each node address—including ephemeral ones—so that session traffic is not correlated with long-term traffic through counter continuity.

From the application layer’s perspective, the implementation maps the ephemeral identity back to the originating long-term node ID throughout the session, so applications continue to see communication with the same peer they initiated the session with.

Session Lifetime

A PFS session ends when any of the following occur:

• The agreed session duration expires.
• Either party sends an End PFS Session command.
• Either device reboots.

Upon session end, both sides must securely erase/zeroize the private keys for their ephemeral addresses. Without those private keys, the session’s ECDH shared secret cannot be reconstructed, and the session traffic cannot be decrypted even by an attacker who later obtains the long-term private keys. This erasure is the mechanism that provides forward secrecy.

Caution

Implementations must ensure that the private keys for ephemeral addresses are not swapped to disk, written to logs, or otherwise persisted in any form. On embedded platforms, this requires explicitly zeroing the key material in RAM before releasing it. Failure to securely erase these keys eliminates the PFS property entirely.

Routing Overview

UMSH packets can be delivered directly to nodes within radio range, flooded across the mesh, source-routed through a specific sequence of repeaters, or delivered using a hybrid of source routing and flooding. This chapter gives a high-level picture of how these mechanisms fit together; detailed procedures are covered in the sections linked below.

In general, it is the responsibility of the individual endpoints to properly route their traffic to their destination.

Direct (Single-Hop) Delivery

The simplest case: the sender transmits a packet with no source-route option and no flood hop count. Only nodes within direct radio range will receive it. No repeater forwarding occurs. This is appropriate when the destination is known to be a direct neighbor, or for local broadcasts and beacons that do not need multi-hop propagation.

Flood Routing

The sender sets a flood hop count in the packet header, and every repeater that receives the packet decrements the remaining count, increments the accumulated count, and retransmits. The packet radiates outward until the hop count is exhausted or all reachable repeaters have forwarded it.

Flood routing requires no prior knowledge of the network topology. It is used for broadcasts, multicast, and unicast when no source route is known. The cost is airtime: every repeater in range participates, so a high hop count can saturate a busy mesh.

See Packet Structure § Flood Hop Count for encoding details and Repeater Operation § Forwarding Procedure for the forwarding rules.

Region Scoping

The region code option restricts flood forwarding to repeaters configured for that specific geographic region. A repeater that does not recognize or is not configured for the region MUST NOT flood-forward the packet. If multiple region code options are present, matching any one of them is sufficient for flood forwarding. If a packet is being flood-forwarded without a region code, a repeater may add one according to local policy, but it must never rewrite an existing region code or add a second one. Region scoping is not enforced during the source-routed portion of a hybrid route—only after the source-route hints are exhausted and the packet transitions to flooding.

See Packet Options § Region Code.

Signal-Quality Filtering

Two packet options let the sender control which links are acceptable for flood forwarding:

• Minimum RSSI—a repeater that received the packet below the specified signal strength must not flood-forward it.
• Minimum SNR—a repeater that received the packet below the specified signal-to-noise ratio must not flood-forward it.

These thresholds prevent retransmission over weak links that are unlikely to deliver the packet reliably, saving airtime and transmit power. The repeater may also enforce its own local thresholds; the effective threshold is the higher of the two.

See Packet Options § Minimum RSSI and Packet Options § Minimum SNR.

Source Routing

When the sender knows a path to the destination, it can include a source-route option listing the sequence of repeater hints the packet should traverse. Each repeater checks whether it matches the next hint, removes its own hint, and forwards. Only the designated repeaters handle the packet, so source routing avoids the airtime cost of flooding.

Source routes are learned from the Trace option: when a packet carries one, each forwarding repeater prepends a record of itself, on routed hops as well as flooded ones. The recipient can cache the router hints of a complete trace as a source route for future replies. This means path discovery is not a separate operation—it falls out of normal packet exchange.

Knowing the path forward is not the same as the destination knowing the path back. A source-routed packet arrives with its hints consumed, so nothing on it describes the return direction, and a destination with no cached route composes a reply that no repeater may carry. A sender therefore includes a Trace option whenever the destination may not hold a working path back; the routed hops record themselves, and the reply or acknowledgement has a path home. See When to Include a Trace.

See Packet Options § Source Route, Packet Options § Trace, and Beacons & Path Discovery § Route Learning.

Hybrid Routing

A packet can carry both a source-route option and a flood hop count. The packet is source-routed through the listed repeaters first; once the source-route hints are exhausted, it transitions to flood routing bounded by the remaining flood hop count. This enables “deliver to a region, then flood locally” behavior—useful for reaching a node in a known area without flooding the entire mesh.

See Repeater Operation § Routing Implications.

Bridging

A bridge is a node that relays UMSH packets between two different media or RF channels—for example, from a local LoRa radio to an internet backhaul and back to a distant LoRa radio, or between two radio bands.

Bridges are not prohibited per-se, as that is not a protocol-level decision. Instead, this document provides some guidance on how bridges can be deployed while lowering the risk of hurting local mesh performance.

Bridges are largely protocol-transparent. A bridge carries a packet between the repeaters at either end of it, and those repeaters do the forwarding: each consumes source-route hints, accounts for a hop, and records itself in a trace exactly as it would for a packet it heard off the air. A trace that crosses a bridge therefore contains records for both of them, and source-routed packets traverse the bridge transparently.

Because a repeater at each end forwards the packet, a crossing spends two flood hops rather than one. The repeater on the inbound side transmits on the medium the packet arrived from, which is the ordinary forwarding confirmation the previous hop listens for; a bridge needs no retransmission of its own to provide it.

Flooding works across bridges, and the two hops a crossing spends are what keep individual meshes local and accountable while still enabling multi-segment routing. A bridge MAY additionally clamp the remaining flood hop count of packets that transit it, which lets an operator narrow a bridge’s reach without reconfiguring the nodes behind it.

Caution

Internet bridges have the potential to be destructive to the mesh and are generally discouraged because 1) they cannot be relied upon in an emergency, and 2) they can waste airtime with useless, non-local chatter. Moreso than other types of bridges, internet bridges MUST limit what transits them: the flood hop count is bounded by the two hops a crossing spends, and deployments SHOULD rate-limit each participant and MAY clamp the hop count further.

A client–server tunnel realization of an internet bridge is specified in Internet Bridging. A node with a LoRa radio and its repeater enabled that joins an IP multicast group is a bridge between the group and its LoRa channel.

Forwarding Confirmation and Recovery

UMSH provides hop-by-hop forwarding confirmation for both source-routed and flood-originated packets. After transmitting, a node listens for the next hop to retransmit the same packet. If no retransmission is heard within a timeout, the node retries after a short jittered delay (up to 3 retries). The original sender does not currently receive any notification of a forwarding failure when source routing.

If a cached route fails entirely (noticed because of a timeout), the sender can fall back to flood routing for the same logical packet using the route retry option, which allows repeaters to forward it even if they already suppressed the original attempt.

A cached source route is the visible case, but not the only one. A sender that believes the destination is directly reachable, or reachable within a known flood distance, narrows FHOPS accordingly and carries no option recording that it did so. When such a packet goes unacknowledged, the cached distance is as stale as a dead source-route hint, and the recovery transmission restores the flood budget the sending application originally allowed. A radius the application itself chose is not a stale assumption and is not widened.

A packet that flooded at its whole budget may have failed on the way back instead: the destination’s route to the sender may be dead, and a MAC ack is never itself acknowledged. A sender that has heard from the destination recently therefore sends one Route Retry even then, at the same budget. When that retry reaches a destination that already acknowledged the packet, the destination retires the route its acknowledgment took and re-acknowledges by a scoped flood with a trace. Each logical packet gets at most one Route Retry.

See Repeater Operation § Forwarding Confirmation and Repeater Operation § Route Failure Recovery.

Channel Access

Before any transmission—original, forwarded, or acknowledgment—a node performs Channel Activity Detection (CAD) and backs off if the channel is busy. Flood-forwarding repeaters additionally use a contention window based on received SNR and RSSI, so that better-positioned repeaters transmit first and the rest can suppress their retransmission if they overhear an earlier forward.

See Channel Access.

Packet Processing

This chapter describes how a receiving node processes an incoming packet. This procedure applies to all nodes, not just repeaters. Repeater-specific forwarding logic is described separately in Repeater Operation.

A packet enters this procedure however it reached the node. Most arrive off the air, but a node whose radio is shared with another stack also receives what that stack transmits, and a node reachable over a point-to-point link—a backhauled host, for instance—receives what arrives across it. A node with a LoRa radio that is also in an IP multicast group receives what other nodes send to the group. Such a packet is processed exactly as a received one, with one difference: it carries no signal measurements, so anything defined in terms of how well the packet was heard does not apply to it.

Receive Procedure

1. Well-formedness check

   • If the packet is malformed (invalid FCF, truncated fields, non-zero reserved bits in the SCF), drop.

2. MAC Ack handling

   • If the packet is a MAC Ack:
     • If this node was not expecting the ack, stop.
     • Otherwise, handle the ack and stop.

3. Address matching

   • If the packet is a broadcast, continue.
   • If the packet carries a destination hint that matches this node, continue.
   • If the packet carries a channel hint matching a configured channel, continue.
   • Otherwise, stop.

   A node always attempts to handle a packet that matches its destination hint, even if the packet has remaining source-route hops. This differs from systems like MeshCore and allows two nodes that are suddenly in direct range of each other to recover quickly without waiting for the packet to traverse the full source route. A node acting as a repeater does not also forward such a packet: it is the destination, and the packet has arrived (see Routing Invariants).

4. Channel processing (multicast and blind unicast)

   4.1. If the packet is a blind unicast:

   • Decrypt the source address using the channel’s derived encryption key K_enc.
   • If the source address is a hint (S=0), look up candidate public keys matching the hint. If no candidates exist, stop.

   4.2. Attempt decryption and MIC verification for each candidate channel key.

   • For blind unicast, this may require re-decrypting the source address for each candidate channel from step 4.1.
   • If no candidate channel succeeds, stop.

5. Unicast processing

   5.1. If the source address is a hint (S=0), look up candidate public keys matching the hint. If no candidates exist, stop.

   5.2. Attempt MIC verification (and decryption if encrypted) for each candidate source address.

   • If no candidate succeeds, stop.

   5.3. If the source address is blacklisted, drop.

6. Payload type and option validation

   • If the payload type is not allowed for this packet type (see Payload and Packet Type Compatibility), drop.
   • If the packet carries a delivery-critical option this node does not recognize, or whose value it cannot interpret, drop it and count the drop. The packet is not accepted, delivered, or acknowledged.

7. Replay and Ack Processing

   • If the packet carries a frame signature, verify it. A packet whose signature verifies is judged by the signed-frame counter rules; one whose signature does not verify continues as an unsigned packet.
   • Apply the replay-detection rules.
   • If the packet is accepted as new and requests an ACK, the receiving node (i.e., the final destination) computes the ack MIC and ack tag—the first 4 bytes of the original packet’s MIC and a 4-byte MIC under the pairwise K_mic over the ack’s own static options, bound to the original packet’s full 16-byte S2V output—prepares a MAC Ack packet, and adds it to the outbound queue. Repeaters do not generate acks—see MAC Ack Packet.
   • If the authenticated packet is a previously received packet within the bounded duplicate-acknowledgement window, the receiver MAY prepare and queue its ACK again. This does not make the packet new or advance its replay state. Unless duplicate suppression is delegated to a host MAC, stop after queueing the ACK and do not process the application payload again.
   • A Verify Frame or Frame Verified whose counter falls outside the window is processed as Counter Resynchronization describes rather than dropped.
   • Otherwise, if replay detection rejects the packet, drop it without acknowledging it.

8. Application processing

   • Continue processing the application payload.

Channels

A channel is a named communication context defined by a shared symmetric key. Possession of the channel key grants membership and enables two distinct roles in UMSH:

• Multicast—any node that possesses the channel key can send and receive packets addressed to the channel, enabling group communication.
• Blind unicast—the channel key conceals both sender and destination addresses on the wire, while the payload itself is protected end-to-end using combined keys that require both the channel key and the pairwise shared secret. The channel serves as a metadata-concealment layer; the payload is readable only by the intended recipient, not by all channel members. See Blind Unicast Packet and Blind Unicast Address Encryption for details.

In both cases, the channel key is the membership credential—possessing it is both necessary and sufficient to participate.

Channel Keys

A channel key is a 32-byte symmetric key. It serves as the root secret from which encryption, authentication, and identification keys are derived (see Multicast Packet Keys).

How a node obtains a channel key depends on the type of channel—see Joining a Channel below.

Channel Identifier

Each channel is identified on the wire by the first 2 bytes of the 16-byte channel identifier derived from the channel key. What travels on the wire is a compact hint that allows receivers to quickly identify candidate channels without attempting decryption with every configured key. Like destination hints, it is not cryptographically authoritative—collisions are possible and must be resolved by attempting cryptographic verification. The full identifier is where a collision cannot be tolerated: it names a channel to a management interface without disclosing the key.

Encrypted and Unencrypted Modes

Channel-addressed packets (multicast and blind unicast) may be sent with or without encryption, controlled by the E flag in the Security Control Field.

• Encrypted (E=1): The source address is encrypted together with the payload, concealing the sender’s identity from observers who do not possess the channel key. Only channel members can recover the source address and payload. See Encrypted Multicast for the packet layout.

• Unencrypted (E=0): The source address and payload appear in cleartext, but the packet is still authenticated with a MIC derived from the channel key. This mode is useful for amateur radio operation or other contexts where encryption is not permitted. See Unencrypted Multicast for the packet layout.

Multi-Hop Delivery

Channel-addressed packets are delivered via flood forwarding, bounded by the optional flood hop count field. Repeaters forward these packets according to the standard forwarding procedure, including duplicate suppression, signal-quality filtering, and region-scoped flooding.

Sender Authentication

Multicast authentication is based on the shared channel key, not on individual sender identity. The MIC proves that the sender possesses the channel key, but any channel member can construct a valid packet with any claimed source address. This is a fundamental property of symmetric-key multicast—see Multicast Sender Authentication for further discussion.

A signed multicast (the SCF’s D bit set) is the exception. Its frame signature attributes the packet to the key that signed it, and is bound to the channel through the channel commitment, so it cannot be moved to another channel that shares its identifier. A multicast whose signature does not verify is no more attributable than an unsigned one.

Blind unicast payloads are additionally authenticated using pairwise keys derived from the sender and recipient’s key agreement, so only the true sender can produce a valid payload and only the intended recipient can verify it.

Joining a Channel

UMSH supports three models for channel membership, from simplest to most capable.

Named Channels

Channel keys may be derived from human-readable channel names rather than distributed as raw keys. A named channel is identified by a umsh:cs: URI (see URI Formats):

umsh:cs:Public

Named channels are effectively public—anyone who knows the name can derive the key and participate. Long, high-entropy names may provide practical obscurity, but this should not be treated as strong secrecy.

The channel key is derived from the channel name using HKDF-Extract:

channel_key = HKDF-Extract-SHA256(salt = "UMSH-CHANNEL-V1", ikm = canonical_name)

Where canonical_name is the canonicalized name portion of the umsh:cs: URI (everything after umsh:cs:). Canonicalization is defined as follows:

1. Percent-decode the name portion of the URI.
2. The decoded name MUST consist only of ASCII characters (letters, digits, and symbols). Non-ASCII (multi-byte UTF-8) names are not currently supported and MUST be rejected. Any character that is not URI-safe is carried through percent-encoding in the URI and recovered by step 1.
3. Fold ASCII letters A–Z to lowercase a–z. No other characters are altered.
4. Encode the result as an ASCII byte string; this is canonical_name.

For example, given umsh:cs:Public, the input to canonicalization is Public, which folds to public, and the key is derived over the bytes of public. Because folding is applied before derivation, umsh:cs:Public, umsh:cs:public, and umsh:cs:PUBLIC all derive the same channel key. The output is a 32-byte pseudorandom key that serves as the channel key. This key then flows through the standard Multicast Packet Keys derivation to produce K_enc and K_mic.

Note

Case-folding is restricted to ASCII deliberately. Correct case-folding of the full Unicode range is non-trivial (locale-dependent, with characters that fold to multiple code points), so UTF-8 channel names are deferred to a future revision. Note that percent-encoding does not provide a workaround: canonicalization operates on the decoded name, so a percent-encoded non-ASCII name still decodes to non-ASCII and is rejected. A group that wants a non-ASCII display name should use a private channel (umsh:ck:) with an explicit key and carry the display name as a URI parameter.

HKDF-Extract is appropriate here because named channels are not secrets—the name is public input keying material, not a password. Password-based KDFs (PBKDF2, Argon2) would add computational cost without meaningful security benefit, since the channel name is assumed to be known to all participants.

Private Channels

For channels that require real secrecy, the channel key is distributed out-of-band—via QR codes, umsh:ck: URIs (see URI Formats), or any other secure channel (including in-band exchange over an existing authenticated unicast session). Anyone who possesses the key is a member; there is no central authority and no mechanism to revoke membership without changing the key for everyone.

Managed Channels

A managed channel is administered by a designated managing node that controls membership. Unlike named and private channels, a managed channel supports adding and removing individual members without requiring all remaining members to re-join manually.

Note: The specific wire formats and MAC commands for managed channel operations (join requests, key distribution, rotation signalling) are not yet defined. The MAC layer itself is unaffected—managed channels use the same multicast packet format and cryptographic processing as any other channel.

To join a managed channel, a node provides its public key to the managing node—either out-of-band or via an in-band join request that the manager can accept or deny. Once accepted, the new member receives the current channel key and channel metadata from the managing node.

The managing node periodically rotates the channel key. When a key rotation occurs, each current member receives the new key along with the time at which it becomes active, allowing a coordinated switchover. Because the channel identifier is derived from the channel key, a key rotation also changes the channel’s on-wire identifier; the application layer masks this from the user so the channel appears to be the same.

To remove a member, the managing node distributes a new key to all members except the excluded node. The excluded node still holds the old key but cannot decrypt traffic encrypted under the new one.

Members that are offline during a key rotation can request the current key from the managing node when they reconnect.

Default Channels

Implementations should recognize two well-known named channels with specific behavior requirements.

public

The public channel (derived from umsh:cs:public) is the default flooded group chat channel. It provides a shared communication space analogous to an open town square—any node that knows the name can participate.

• Maximum flood hops: 10.
• Traffic may be encrypted (E=1), but the key is known so this doesn’t really offer privacy.
• Blind unicast on this channel is forbidden.
• Chat messages that do not include the full source key (S=1) MUST NOT be displayed in the user interface. This ensures that users can always verify sender identity on the public channel, even though the channel key itself is public knowledge.

EMERGENCY

The emergency channel (written EMERGENCY here for emphasis, but derived from umsh:cs:emergency after the ASCII case-folding described in Named Channels, so umsh:cs:EMERGENCY and umsh:cs:emergency derive the same key) is reserved for emergency communications. Repeaters should prioritize forwarding packets on this channel.

• Maximum flood hops: 10.
• Chat messages must not be encrypted—all emergency traffic must be readable by any node in range, including nodes that have not explicitly joined the channel.
• Chat messages must include the full source key (S=1).
• Every multicast carrying text-message traffic on this channel must be signed (the SCF’s D bit, see Frame Signatures). This includes resend responses to the channel and Message Unavailable responses. Resend requests and one-to-one repairs travel by blind unicast, which already authenticates the sender pairwise, and are not signed.
• Messages that do not meet all three requirements (unencrypted, full source key, signed) must not be accepted or displayed by the user interface. A multicast whose signature does not verify does not meet them.

These requirements ensure that emergency traffic is universally readable, attributable to a specific node, and cryptographically authenticated against impersonation.

Text messages beginning with TEST: are test messages, which raise no alert by default.

Payload Reuse

Application-layer channel communication reuses the same payload types as unicast. For example, group chat uses the same text message and chat room payload formats as direct messaging. However, not all application types are valid over multicast—see Payload Types for compatibility.

Channel Access

This chapter describes how UMSH nodes contend for channel access before transmitting. These procedures apply to all transmissions—original packets, forwarded packets, and acknowledgments—unless otherwise specified.

Frame Duration

T_frame is the maximum on-air duration of a LoRa frame at the configured channel settings (spreading factor, bandwidth, coding rate, and maximum payload size). T_frame is not a fixed protocol constant; implementations derive it from the channel configuration. All timing parameters in this chapter are expressed as multiples of T_frame.

ULCP hosts can read PROP_PHY_T_FRAME from the device instead of calculating it from modulation-specific parameters.

For reference, typical T_frame values for a maximum-length (255-byte) packet using common MeshCore-style channel settings:

Channel Sensing

In general, before transmitting any packet, a node SHOULD perform Channel Activity Detection (CAD), or whatever the appropriate analogous mechanism is for the given physical layer. CAD is a LoRa hardware primitive that detects preamble energy on the channel with minimal power draw.

• If CAD indicates the channel is idle, proceed to transmit.
• If CAD indicates the channel is busy, enter the backoff procedure.

Backoff Procedure

When CAD indicates the channel is busy:

1. Wait a random duration uniformly sampled from [T_frame/40, T_frame/4].
2. Perform CAD again.
3. Repeat up to 15 more times (16 CAD attempts total).
4. If the channel remains busy after all attempts, drop the packet silently.

Flood Forwarding Contention Window

When a repeater is eligible to flood-forward a packet, it SHOULD NOT just transmit like it would any other packet. Instead, it waits a contention delay proportional to the power of the received signal yet also inversely proportional to the quality of the received signal. Nodes that heard the packet cleanly but faintly transmit first; nodes that heard it very strongly wait longer; and nodes that heard it near the limit of demodulation wait until the others have had their chance. When a well-positioned repeater transmits, others overhear it, recognize the packet via duplicate suppression, and usually defer or abandon their own pending forwarding.

Note

This guidance is still provisional and should be treated as a starting point until it is validated with real-world measurements.

Although the contention parameters below are configurable in principle, nodes in the same mesh SHOULD use the same values so that forwarding behavior remains predictable. Unless a deployment intentionally overrides them, implementations SHOULD use the defaults in this section.

For the first forwarding decision after reception, compute the contention window as:

SNR_low = SNR_floor + 6 dB
SNR_high = SNR_floor + 18 dB
RSSI_low = -100 dBm
RSSI_high = -70 dBm

W_min = 0
W_max = T_frame/2
W_jitter = T_frame/10

quality = clamp((received_SNR − SNR_low) / (SNR_high − SNR_low), 0, 1)
signal = clamp((received_RSSI − RSSI_low) / (RSSI_high − RSSI_low), 0, 1)

if received_SNR < SNR_low:
    W   = W_max + W_jitter
else:
    W   = W_min + (W_max − W_min) × max((1 − quality), signal)
delay   = D_ack + W + uniform_random(0, W_jitter)

Where:

• When flood-forwarding, the effective minimum SNR threshold is the higher of the Minimum SNR packet option (if present) and any locally configured minimum SNR. A repeater MUST NOT flood-forward if the received SNR is below that effective threshold. (Signal-quality thresholds do not apply to source-routed hops.)
• SNR_floor is the lowest SNR at which LoRa demodulates at the spreading factor in use: −7.5 dB at SF7, and 2.5 dB lower for each step up, to −20 dB at SF12. The same reading is a comfortable margin at one spreading factor and a failing link at another, so the band is measured from the floor. Bandwidth moves the receiver’s sensitivity in dBm, not the SNR it needs.
• SNR_low/SNR_high and RSSI_low/RSSI_high define the clamp ranges that normalize the two measurements for the contention heuristic.
• A reception below SNR_low waits out the whole window and one jitter range before drawing its own jitter. Any repeater that heard the packet within the band transmits first, and this one forwards only if none did.
• W_min is the minimum contention window for strong receptions.
• W_max is the maximum intentional forwarding-delay window.
• W_jitter bounds the random tie-breaking delay added after the deterministic window, so that nodes whose measurements agree do not transmit in the same instant.
• received_SNR and received_RSSI are the SNR and RSSI measured during reception of the packet being forwarded.
• D_ack is the ACK protection interval: a guard delay that applies when the forwarded packet may elicit an immediate ACK from its destination, and zero otherwise.

After computing the delay, the repeater waits. Other packets SHOULD continue to be forwarded while waiting, assuming the channel is clear.

If the repeater overhears the same packet forwarded by another node (identified by MIC in the duplicate cache) before the delay expires, it SHOULD defer rather than transmit. A safe default is to recalculate a new delay using the same W_min/W_max limits—including D_ack when it applies, since the overheard copy may itself elicit an immediate ACK from the destination—and restart the waiting period. The first two overheard copies each defer the pending forward this way; on overhearing a third copy, the repeater SHOULD abandon the pending forward.

Only a copy received over the radio defers. A packet received from an IP multicast group, heard by every bridge in the group at once, contends with a window drawn uniformly from [W_min, W_max].

If the repeater instead overhears a MAC ack whose ack_mic matches the pending packet’s MIC prefix, it SHOULD cancel the pending forward outright rather than defer: the destination provably has the packet.

This deferral behavior is intended only for the first local forwarding decision after reception. Once a repeater has actually transmitted its own copy, any later retransmission behavior is governed by Repeater Operation.

Nodes waiting for implicit forwarding confirmation MUST size their confirmation timeout to include this full forwarding-delay window. A safe default is to allow:

• up to D_ack of ACK protection delay, when it applies
• up to W_max + 2 × W_jitter of intentional forwarding delay
• up to T_frame for the forwarded transmission itself
• an additional guard margin of up to T_frame

ACK Protection Interval

The final destination of an ack-requested packet transmits its ACK as soon as the packet ends, without performing CAD (see Immediate ACK Transmission). CAD alone cannot protect that ACK from flood forwarders triggered by the end of the same reception: the contention delay W + uniform_random(0, W_jitter) may be arbitrarily small, CAD detects preamble energy and may miss an ACK already past its preamble, and a forwarder may not be able to hear the destination at all.

D_ack therefore provides deterministic separation. When the packet being flood-forwarded requests an ACK (UNAR or BUAR) and was received with no remaining source-route hops—the conditions under which its destination transmits an immediate ACK—the forwarder MUST delay by at least D_ack before transmitting, in addition to the computed contention delay. D_ack SHOULD cover the destination’s receive-to-transmit turnaround plus the on-air duration of a MAC Ack packet at the configured channel settings. The suggested default is 0.25 × T_frame; implementations that compute the actual MAC Ack airtime MAY use a tighter bound.

A packet received with source-route hops still pending does not elicit an immediate ACK from its destination, so D_ack does not apply when forwarding it.

Immediate ACK Transmission

When a node is the final destination of an ack-requested packet (UNAR or BUAR) and the packet has no remaining source route hops, the node SHOULD transmit the ACK immediately—without performing CAD—provided the radio is available for transmission. This is warranted because the channel is known to have been clear at the moment the received packet ended, and flood forwarders hold their transmissions back by the ACK protection interval so the ACK gets first use of the channel.

If the radio is not immediately available for transmission, the node SHOULD perform normal CAD and backoff before transmitting the ACK.

Repeater Operation

Forwarding logic is intentionally conservative. A repeater should evaluate packets in the following order.

Routing Invariants

The routing model is governed by a few simple rules:

• Every currently defined on-mesh packet type is routable.
  • In the current protocol this includes broadcast, MAC ack, unicast, multicast, and blind unicast packets.
  • Reserved or opaque packet types are not routable until the protocol defines their forwarding semantics (there is only one at the moment, type 5).
• A repeater forwards other nodes’ traffic, never its own and never traffic that has arrived.
  • A repeater MUST NOT forward a packet whose source address identifies one of its own identities, by hint or in full-key form. Re-flooding its own transmission wastes airtime, and prepending its record to the trace would fabricate a hop that never happened.
  • A repeater MUST NOT forward a packet whose destination address identifies one of its own identities. Such a packet has reached its destination; whether the repeater could actually process it is a separate question.
• A packet is forwarded as either a source-routed hop or a flood hop, never both.
  • A hop named in the source route is a source-routed hop, including the hop that consumes the final hint.
  • Every other forwarded hop is a flood hop.
  • Rules written for flood forwarding—flood hop accounting, signal-quality thresholds, region policy, and forwarding contention—apply to flood hops only.
• Repeaters MUST mutate specific dynamic routing metadata while forwarding (source route, trace, hop count, etc)
  • Typical examples are flood hop counts, traces, source routes.
  • A repeater SHALL NOT simply repeat a packet verbatim under any circumstances.
  • The Route Retry flag MUST NOT be added to a packet by anyone other than the original sender.
  • These mutations do not create a new logical packet.
• A packet’s logical delivery identity and its repeater forwarding identity are related but distinct.
  • The final destination decides whether a packet is new by its normal replay and destination-processing rules.
  • Repeaters suppress duplicates using a forwarding identity that remains stable across legal forwarding rewrites.
• Forwarding confirmation uses the same identity as repeater duplicate suppression.
  • This ensures a sender or repeater recognizes “the same packet, forwarded onward” even if the next hop mutates dynamic routing metadata.

Duplicate Suppression

Each repeater maintains a fixed-size cache of recently seen cache keys used to detect duplicate packets.

Parameters:

• cache size = implementation configurable (see sizing guidance below)
• eviction policy = oldest entry removed when full
• entry lifetime = bounded (see entry expiry below)

The cache key is derived from the packet as follows:

• Authenticated packets (unicast, multicast, blind unicast): the cache key is normally the packet’s MIC. Because the MIC covers all static fields and is unaffected by repeater modifications to dynamic options or the flood hop count, it remains stable across forwarding hops.
  • If the packet carries the Route Retry option, the cache key must distinguish that retry attempt from the same packet without the option present. A simple and sufficient rule is to treat the cache key as (MIC, route_retry_present).
  • This gives a packet two bounded forwarding identities: the original forwarding attempt and one explicit reroute attempt.
• MAC acks and broadcasts: these packet types do not carry a MIC. The cache key is a locally-computed hash of the packet content, excluding the flood hop count and dynamic options—the same fields that would be excluded from a MIC. The hash does not need to be cryptographic; CRC-32 is suggested, but any hash with comparable distribution is acceptable. The choice of hash algorithm is a local implementation detail.

Before forwarding a packet, the repeater checks the cache:

• if the cache key is already present, do not forward
• if the cache key is not present, continue processing
• once the repeater decides the packet is eligible, insert the cache key into the cache

To avoid racy reforward behavior, the repeater should insert the cache key into the cache as soon as it accepts the packet for forwarding, not after transmission completes.

Shorter cache keys increase the probability of false-positive collisions. Deployments that use 4-byte or 8-byte MICs should account for this when sizing the duplicate cache.

Entry Expiry

Cache entries MUST also age out. Capacity alone does not bound how long a key is suppressed, and a MIC-less packet’s cache key is derived from its content: a node that repeats an identical packet—a beacon, whose body is empty and whose non-dynamic options do not change—produces the same key every time. On a quiet mesh, capacity-only eviction would suppress that node’s packets for as long as the repeater runs.

An entry SHOULD be discarded once it is older than a cache lifetime measured from when the key was first inserted. One hour is a reasonable default: long enough that every retransmission of a single packet still collapses to one forward, short enough that a node re-announcing itself is heard again well within the time anyone would wait for it.

MAC-ack entries are the exception: their lifetime SHOULD be on the order of tens of seconds—the scale of a sender’s retry ladder—not an hour. An identical re-acknowledgement is the one duplicate a correct node emits deliberately (see the duplicate acknowledgement window), and it recovers a lost ack only if repeaters carry it; under a lifetime longer than the sender’s recovery horizon, the first forward of an ack absorbs every later one and the recovery path dies at the first hop. A short lifetime still collapses the copies of any single exchange, which play out within a few confirmation windows.

A repeat of a key already held MUST NOT extend that entry’s lifetime. Refreshing the timestamp on each sighting would let a node repeating itself inside the window hold its own suppression open indefinitely, which is the behavior expiry exists to prevent.

Cache Sizing

Each cache entry is small (equal to the cache key size—typically 4 to 16 bytes), so generous sizing is inexpensive. The recommended minimum is 32 entries; the suggested default is 64 entries. High-traffic deployments or networks with large diameters may benefit from 128 or more entries.

Forwarding Procedure

1. Duplicate suppression

   • If this packet was forwarded recently, do not forward.

2. Local origin and local destination

   • If this repeater’s own radio already transmitted this packet, do not forward. A repeater that shares its radio with another stack—an attached host, most commonly—receives a copy of what that stack transmits. Forwarding it would put a packet back on the air that this antenna already sent, and the source address belongs to the other stack, so the check below cannot catch it. The repeater MUST insert the cache key as if it had forwarded the packet: a neighbor’s repeat arrives shortly after, and it is the same packet, already carried.
   • If the packet’s source address identifies one of this repeater’s own identities, do not forward.
   • If the packet’s destination address identifies one of this repeater’s own identities, do not forward.

3. Locally-handled unicast

   • If this packet was a unicast (blind or direct) packet that was fully handled and processed according to Packet Processing, do not forward. This covers the blind-unicast case, where the destination address is encrypted and step 2 cannot see it.

4. Unknown forwarding-critical options

   • If the packet contains any forwarding-critical option the repeater does not understand, or whose value it cannot interpret, do not forward. Delivery-critical options do not affect forwarding.

5. Policy checks

   • If the packet does not satisfy local repeater policy, do not forward.

6. Source-route match

   • If the packet contains a non-empty source-route option:
     • If this repeater does not match the next source-route hint, do not forward.
     • Otherwise, remove the repeater’s own hint from the source-route option.
   • If the repeater mutates a source-route option, it MUST preserve the option on the forwarded packet even when no hints remain.
     • In that case, the forwarded packet carries a source-route option with zero remaining hops.
     • This preserves provenance: downstream nodes can still determine that the packet arrived via explicit source routing rather than by pure flooding.
   • If this repeater matched a source-route hint, it is forwarding a source-routed hop. Skip directly to step 10 (trace processing), including when the hint just removed was the last one. Steps 7 through 9 describe flood forwarding and MUST NOT be applied to a source-routed hop.

7. Region policy (flood forwarding only!)

   • If the router has no region configuration at all, skip this section. A repeater with no configured regions applies no regional restriction and forwards a tagged packet whatever its region.
   • If none of the region codes in the packet match those configured on the repeater, do not forward.
   • If the packet has no region code option, the repeater SHOULD insert its configured default region before flood-forwarding. A repeater with no default region configured forwards the packet untagged; the default region is not implied by the configured region list.
     • If one or more region codes are already present, the repeater MUST preserve them unchanged.
     • A repeater MUST NOT add a second region code to a packet that already carries at least one region code.

8. Flood hop accounting (flood forwarding only!)

   • If the packet has a flood hop count field with FHOPS_REM > 0, decrement FHOPS_REM and increment FHOPS_ACC.
   • Otherwise, do not forward.

9. Signal-quality thresholds (flood forwarding only!)

   • If either the packet or repeater imposes a minimum RSSI, the effective threshold is the higher of the two. If the received RSSI is below the effective threshold, do not forward.
   • If either the packet or repeater imposes a minimum SNR, the effective threshold is the higher of the two. If the received SNR is below the effective threshold, do not forward.
   • These thresholds ask how well the packet was heard. A packet handed to the repeater over a point-to-point link rather than a radio was not heard at all, and carries no measurement to compare; the thresholds do not apply to it.

10. Trace processing

• If the packet contains a Trace option, add this repeater’s own entry, degrading the trace’s form as needed to fit the outgoing link (Trace Option Value). If even a lone 0xFF does not fit, do not forward the packet on that link, and count the drop.

11. Retransmit

• If this is a flood forward, implement the flood forwarding contention window
  • The contention window staggers the repeaters that all heard one transmission. A packet that arrived over a point-to-point link was heard by this repeater alone, so there is no contention to resolve and no window to wait out.
• Forward the modified packet according to normal channel access rules.

A packet that arrives carrying an empty source-route option matched no hint at this repeater, so it takes the flood path: steps 7 through 9 apply in full. This is how a hybrid route transitions to flooding—the transition is observed by the repeater after the one that emptied the route, not performed by it.

A bridge rewrites nothing of its own: a repeater at each end of it forwards the packet by this procedure, so a crossing applies these rules twice.

A bridge in an IP multicast group applies this procedure once to a packet received from the group, as to one heard on its radio.

Forwarding Confirmation

Repeaters do not generate MAC acks—acks are generated only by the final destination. Instead, a node can passively confirm that a transmitted or forwarded packet was received by listening for a subsequent retransmission of the same packet (or it’s ack).

This applies to:

• Source-routed packets: Each forwarding hop listens for the next hop—the node matching the next source-route hint—to retransmit.
• Flood originators: The originating node listens for any node to retransmit.
• Flood repeaters: Intermediate flood-forwarding nodes MUST NOT retry. Multiple nodes may forward the same flood packet, and a repeater has no designated next hop to listen for; retrying would increase congestion without improving reliability.
• Routed MAC acks: An ack that carries a source route or flood budget is a routed send like any other; the destination that produced it listens for the first hop to carry it onward and retries on silence. Retrying the ack first is what spares the sender a full data retransmission when only the ack’s first hop failed. Once the destination sends a packet carrying an Ack MIC option for the same packet, it stops retrying an ack that has already been transmitted: repeaters drop their forwards of that ack on hearing the option, and the packet carrying it is confirmed and retried in its own right.

Confirmation, and the retry ladder below, apply whether or not the packet requests an ACK. An ack-requested sender goes on to await the ACK once forwarding is confirmed; a sender that requested no ACK is finished the moment it hears the packet carried onward, and if the retry budget runs out without that, the send simply ends—there is no failure signal to wait for. A point-to-point packet with no flood budget and no source route travels straight to its destination, confirms nothing, and MUST be transmitted exactly once.

After transmitting, the node listens for the same packet—identified by its cache key—to be retransmitted. This confirmation timeout MUST be large enough to cover the worst-case forwarding delay allowed by Channel Access, plus the airtime of the forwarded frame itself, plus a guard margin. A safe default is:

confirm_timeout = 2 × T_frame + W_max + 2 × W_jitter + D_ack

where W_max + 2 × W_jitter bounds the intentional forwarding delay permitted for the path, including the wait of a repeater that heard the packet below the contention band, and D_ack is the ACK protection interval when it applies. With the suggested defaults W_max = T_frame/2, W_jitter = T_frame/10, and D_ack = 0.25 × T_frame, this yields confirm_timeout = 2.95 × T_frame.

If the packet is heard before confirm_timeout expires, forwarding is confirmed. A copy received from an IP multicast group confirms as one heard on the air does.

If confirm_timeout expires without a retransmission, the node SHOULD schedule a retry after a jittered delay:

retry_delay = uniform_random(0, T_frame)

The delay does not grow with the retry number. Its only job is to decorrelate retries between nodes, and one frame time is enough for that; every additional window would be time the payload spends undelivered. After this delay expires, the retry is transmitted using normal CAD and backoff as described in Channel Access.

A node MUST NOT retry more than 3 times.

Ack Cancellation

A MAC ack echoes the acknowledged packet’s ack_mic—the first four bytes of its on-wire MIC—which any forwarder can read without keys, and which survives the mutations repeaters perform. A repeater that overhears a MAC ack (or an Ack MIC option) whose ack_mic matches the MIC prefix of a queued, not-yet-transmitted forward of an ack-eliciting packet (UNAR or BUAR) SHOULD cancel that forward: the destination provably has the packet, and repeating it spends airtime on nothing. The ACK protection interval puts the ack on the air ahead of pending forwards precisely so that this observation is available.

An overheard Ack MIC option also SHOULD cancel a queued, not-yet-transmitted forward of a MAC ack carrying the same ack_mic. The packet carrying the option delivers that acknowledgement to the same node, so the standalone ack has nothing left to deliver. An overheard MAC ack never cancels another ack’s forward: an ack’s trailer opens with the four bytes it echoes, so a second copy would cancel the first.

Cancellation acts on the queue, not on the future. It removes whatever matching forward is queued at that moment—a Route Retry copy included—and records nothing. A Route Retry copy received after a cancellation is a separate forwarding identity under duplicate suppression and is forwarded normally: the origin resorts to it precisely because the ack never reached it, and carrying the copy prompts the destination to acknowledge again. That copy is in turn cancelable by another overheard ack.

The duplicate-cache entry for a cancelled forward remains. The packet was handled; a later copy of the same attempt is still a duplicate.

A repeater holds no key to verify the ack_tag half of the trailer, so cancellation rests on the public ack_mic alone. The forgery this exposes suppresses at most one queued forward per overheard ack and is bounded by the Route Retry path.

Route Failure Recovery

When a node sends an ack-requested unicast or blind-unicast packet against a cached route and that attempt fails, it needs a way to re-attempt delivery without causing duplicate application delivery at the final destination.

Two kinds of cached route can fail this way, and they fail identically from the sender’s point of view:

• an explicit source route, carried in the packet as a source-route option
• a cached distance—the destination believed to be directly reachable, or reachable within a known number of flood hops—which narrows FHOPS and leaves no trace in the options

A practical recovery rule is:

1. if the sender exhausts the retry budget for a packet sent against a cached route, it SHOULD treat that cached route as failed
2. the failed route SHOULD be discarded or marked unusable for immediate reuse
3. if the sender wishes to re-attempt delivery of the same logical packet, it SHOULD:
   • preserve the same frame counter, payload, and MIC
   • remove the stale source-route option, if one was present
   • add or refresh flood hops
   • include a Trace option if route rediscovery is desired
   • set the Route Retry option

These edits touch only fields the associated data excludes, which is what lets the MIC carry over. Adding FHOPS where the original had none also sets the FCF’s H bit, and the AAD clears that bit for this reason.

The restored flood radius SHOULD be the one the sending application asked for. A radius the application chose for itself is not a failed cache entry, and recovery MUST NOT widen it: a sender that was told to reach no further than one hop has not made a stale assumption, it has been given an instruction.

A sender that assumed nothing—it held no route and flooded at the whole budget it was allowed—has no cached route to discard, but its timeout is no more specific about which leg failed. The destination may hold a route back that no longer works, and its acknowledgment may have died on it. A MAC ack is never itself acknowledged, so the destination cannot discover this on its own. Such a sender SHOULD send one Route Retry of the packet when it has heard from the destination recently—within 10 minutes is a reasonable window—at the same flood budget and with a trace. A sender that has not heard from the destination recently SHOULD NOT: a destination that is unreachable answers a second full flood no more than the first.

Either way, a sender MUST NOT send a Route Retry of a packet that already carries the Route Retry option. A logical packet gets at most one.

Lost Acknowledgments

A Route Retry that arrives at the destination as a duplicate of a packet it has already acknowledged, after the duplicate acknowledgment holdoff, shows that the acknowledgment did not reach the sender: the sender sends a Route Retry only once its whole acknowledgment timeout has run out. The destination SHOULD then:

• retire or demote the route its acknowledgment followed, and not relearn that same path from the retry for a while
• re-acknowledge by a scoped flood rather than along any cached route: FHOPS_REM set to the retry’s FHOPS_ACC plus a one-hop margin, the retry’s region codes, and a trace, so that the sender learns a path back

A path the retry itself traced MAY still be adopted as an ordinary route candidate, but the re-acknowledgment does not follow it. A route the application has fixed in place MAY stay; the re-acknowledgment floods regardless.

Only an acknowledged original makes the retry evidence of a lost acknowledgment. A destination may have accepted the original without acknowledging it—overheard before its source route was consumed, for instance—and then the retry is the first copy it acknowledges, along its route as usual. A late duplicate without the Route Retry option may have crossed an acknowledgment still in transit, so it is re-acknowledged along the route without retiring it.

This recovery transmission is intentionally the same logical packet, not a new application message. The destination therefore still accepts it at most once according to the normal replay rules. The Route Retry option exists only to let repeaters forward the re-attempted packet even if they already suppressed the original as a duplicate.

This preserves a useful separation of responsibilities:

• routing recovery remains a MAC concern
• duplicate application delivery remains prevented by the end-to-end replay rules
• repeaters remain largely stateless and do not need to understand application semantics

For flood-forwarding repeaters that have accepted a packet for forwarding but have not yet transmitted it, overhearing another forwarding of the same packet SHOULD normally cause a bounded deferral rather than an immediate transmission. A safe default is:

1. on each of the first two overheard copies, recalculate a forwarding delay using the contention-window procedure in Channel Access
2. restart the waiting period
3. on overhearing a third copy, abandon the pending forward

This behavior is still provisional and should be validated empirically. The intent is to reduce near-simultaneous forwarding while still allowing a second or third repeater to contribute if an earlier forward was not widely heard.

Routing Implications

This forwarding model allows hybrid routing behavior.

For example, a packet can be source-routed to a specific repeater and also carry a flood hop count. The routed hops cost nothing against FHOPS_REM, so the whole budget is available to the flood that begins where the route ends. This permits “delivery-to-region, then flood” behavior, which is useful when searching for a node in a known geographic area without flooding the entire mesh, and it is why the flood radius limit of 15 bounds the flood rather than the total path length.

A sender sizing FHOPS_REM for a source-routed packet is therefore budgeting the flood beyond the route’s last hop, not the route itself.

Beacons & Path Discovery

Beacons

A Beacon is defined as either:

• a broadcast packet with no payload, or
• a multicast packet with no payload

Beacons are used to announce the presence of a node on the network without carrying additional data. Because beacons have no payload, they omit the 0xFF end-of-options marker; the options block is parsed until the end of the packet. The minimum beacon size is unchanged.

A beacon with a Trace option can inform listeners of both:

• the node’s presence
• a repeater path that may be usable to reach it

This is particularly useful when a receiver already knows the node’s identity information.

A trace that carries signal reports the quality of each hop as well as its identity, which is what distinguishes a path that merely works from one worth using.

Advertisements

An advertisement is a broadcast or multicast packet whose payload is a node identity payload—a beacon that additionally identifies and describes its sender. Advertisements are sent unsolicited, announcing presence, name, role, and capabilities. An advertisement carries a frame signature, which is what authenticates the identity it carries (see Signature Usage). To obtain a specific node’s identity, use the Identity Request MAC command, which is answered with a targeted unicast identity response rather than a broadcast advertisement.

Announcing on a Schedule

A node MAY emit beacons and advertisements on periods of its own. The two are configured separately because they announce different things at very different costs: a beacon publishes a path for a handful of bytes, while an advertisement carries an identity in a signed frame and is the largest frame a node originates unprompted. A mesh is normally best served by refreshing the path often and restating the identity rarely.

A scheduled advertisement SHOULD be sent without flood hops. What it carries is a standing statement rather than news, so flooding it across the mesh on every period spends airtime out of proportion to what a distant listener learns; a node that wants to be findable further away publishes a path with a beacon instead.

A configured period is a minimum rather than an exact cadence. A node SHOULD scatter each period by a random fraction of it—a quarter is a reasonable choice—and that scatter MUST only delay an announcement, never bring it forward, so the configured value remains a floor on how often the node transmits unasked. Nodes commissioned alike and powered on together otherwise stay in step for as long as they run, colliding every period and colliding again on each retry, since a shared schedule makes them contend from the same instant every time. Carrier sensing resolves the individual collision; the scatter is what keeps the mesh from having to resolve one on every period.

A node that has just restarted is the node whose neighbors hold the stalest paths to it, so emitting one beacon at bring-up is RECOMMENDED. That beacon is not delayed: nodes do not restart in unison, so bring-up is already scattered by whatever staggered it.

On a device managed over ULCP, these periods are the advertisement-policy properties.

Path Discovery

UMSH does not define a dedicated path-discovery packet type. Instead, path discovery is performed using existing primitives:

1. Outbound discovery: Node A sends a unicast packet to Node B with the Trace option present and an appropriate flood hop count. The packet floods through the mesh; repeaters prepend their records to the Trace option as they forward.

2. Path learning: When Node B receives the packet, the Trace option contains the sequence of repeaters traversed, ordered most-recent first. If the trace is complete, Node B can use its router hints directly as a candidate source route back to Node A.

3. Return path: Node B can now send unicast packets to Node A using the learned source route. If the packet was ack-requested, Node B’s MAC ack also traverses the mesh, allowing Node A to confirm reachability.

4. Bidirectional establishment: The trace Node A sent taught Node B a path back, and nothing else. Node B’s response—MAC ack, beacon, or application payload—teaches Node A a path only if it carries a trace of its own. Where the response is a MAC ack, that ack is the whole of what Node A receives.

When to Include a Trace

A beacon or advertisement that permits flooding SHOULD always carry a trace: publishing a path back to its sender is much of what it is for, and every listener it reaches may lack one.

A trace gives the destination a path back to the sender, so a sender spends one when the destination may not hold a working path back. A sender SHOULD include a trace on a unicast or blind unicast when any of the following holds:

• it holds no route to the destination
• the packet answers one from the destination that arrived with FHOPS_ACC greater than zero; a MAC ack is such an answer
• no packet from the destination has arrived with FHOPS_ACC of zero in the last 5 minutes; a MAC ack correlated to the destination counts as a packet from it
• it is a Route Retry resend

A packet that arrives with FHOPS_ACC of zero, off the sender’s own transmitter or along a source route, shows that its sender holds a working path to the receiver. That is what a trace would otherwise give it. A packet that had to flood to arrive shows the opposite. The 5-minute window bounds how long the evidence is trusted, since a path that worked can stop working.

A response to a packet that carried a trace MAY carry one. Any other packet MAY carry one, but a sender SHOULD otherwise prefer the smaller frame.

A packet carrying neither flood hops nor a source route SHOULD NOT carry a trace at all, whatever the sender knows. No repeater may forward such a packet, so the option can only arrive as empty as it left, and its arrival already proves what an empty trace would have said.

Because router hints are only two bytes, different repeaters may share the same hint, which may result in redundant (but harmless) forwarding along a source route.

Route Learning

A destination may overhear a frame while source-route hints remain unconsumed. The way back is then the remaining hints in reverse, followed by the trace: the whole path the sender chose, through the repeaters still to forward it. The trace alone would describe a shortcut past those repeaters, and a repeater being audible at the destination does not establish that it hears the destination. Historical buffered frames do not establish current reachability.

Copies of one packet, or of one MAC ack, that arrive over different paths each describe a path, and the first to arrive is not necessarily the best. A node MAY weigh them against each other and against the route it holds, using the per-hop signal of their traces where the copies carry it. A copy that arrives long after the first is a replay rather than evidence of a current path.

When a node successfully processes other live incoming packets, it can update its routing state for the sender:

• Trace: if the packet contains a complete trace, with signal or hints only, the node caches its router hints as a source route for future packets back to the sender. Because the trace is accumulated most-recent first, it already describes the return path from the receiver back toward the original sender. This is the primary mechanism for learning precise multi-hop paths. A truncated trace is not a complete path, and no route is learned from it.

• Flood hop count: if the packet contains a flood hop count, the node caches the sender’s FHOPS_ACC value together with any region-code options that arrived on the packet. When no source route is available, these cached flood parameters can be reused for flood responses—scoping the flood to approximately the right radius and regional domain rather than flooding the entire network.

• Neither: a packet that arrives carrying no flood hop count and no source route was one that no repeater had permission to forward, so it reached the receiver off the sender’s own transmitter. The node SHOULD cache the sender as a direct neighbor. This is the same conclusion an empty trace supports, drawn from the packet’s structure rather than from an option, which is what lets an unforwardable packet leave the trace off.

A MAC ack can also supply routing evidence. It names no source, but its ack trailer correlates it to an outstanding request and so to the peer that sent it. Its trace can establish a route or replace a provisional direct observation with a repeater path. An ACK confirms that the exchange succeeded; its return path may differ from the outbound path, so it need not replace a working source route. Route selection and retention are local policy.

A packet that arrives carrying a source-route option—including one whose hints are all consumed—spends flood hops only after the route runs out, so its FHOPS_ACC counts the tail of the path rather than its length. Such a packet SHOULD NOT be used to derive a flood-distance estimate.

This routing state applies to all subsequent communication with the sender—replies, acknowledgments, and new messages alike. A node MAY replace a cached route when a newer packet provides a fresher trace, and SHOULD discard cached routes that have proven unreachable.

An ACK timeout is evidence that the exchange failed, not proof that the outbound leg alone failed. When an ACK-requested packet exhausts its retry budget on a cached route, the sender can return to route discovery:

• discard or demote the cached source route
• send the same logical packet again using flood hops instead of the stale source route
• include a Trace option so that a fresh source route can be learned from the peer’s reply
• set the Route Retry option so intermediate repeaters treat the rerouted attempt as a new forwarding opportunity even though the packet’s MIC and frame counter are unchanged

Trading a source route for flood hops rewrites only fields the associated data excludes. Adding FHOPS sets the FCF’s H bit, which the AAD clears, so the MIC carries over unchanged.

Recovery stays within the sender’s original flood ceiling; disabled flooding does not authorize a flooded retry. Once a replacement route is learned, normal routed transmission can resume. An ACK following Route Retry confirms delivery of the logical packet but does not identify which attempt delivered it.

A sender that held no route and flooded at its whole budget has no route to discard, yet the timeout may still be the destination’s fault: a route back to the sender that no longer works, on which the ACK died. When it has heard from the destination recently, the sender sends one Route Retry anyway, at the same budget and with a trace. A logical packet gets at most one Route Retry.

The destination learns from that retry. A Route Retry duplicating a packet it already acknowledged shows the ACK was lost, so the destination retires or demotes the route the ACK followed and re-acknowledges by a flood scoped to the retry’s FHOPS_ACC plus one hop, within the retry’s regions, carrying a trace. A path the retry traced may become an ordinary route candidate; the re-acknowledgment does not follow it. See Lost Acknowledgments.

Scoping Flood Hops to a Known Route

A wide flood hop count is a first-contact cost. Once routing state exists for a destination, the sender SHOULD scope FHOPS_REM to what the known path actually costs, plus a margin where the far end of the path is in doubt:

• Source route: named repeaters consume hints without spending flood budget; the margin is available only after all hints are consumed.
• Flood distance: the cached FHOPS_ACC is the radius at which the destination was last heard.
• Direct observation: no repeater carried the observed packet.

The margin is one flood hop. It keeps delivery self-healing when the destination has moved since the path was learned, without paying for a mesh-wide flood on every packet. What decides it is the path’s last hop: the link between the destination and the first node that heard it. For a direct observation that node is the sender itself; for a traced path it is the earliest repeater in the trace, whose trace record holds how it heard the destination, when the trace still carries signal. A cached flood distance names no last hop. The sender SHOULD include the margin when:

• the destination advertises itself as mobile (the MOB bit of its capabilities), unless it was observed directly and strongly;
• the last hop was never measured; or
• the last hop was measured weak.

The sender MAY omit the margin when the destination was observed directly and strongly or across a point-to-point link, when the last hop was measured without being weak, or when the application chose the path rather than learned it. Stronger than −75 dBm is a reasonable bar for a strong direct observation, and −96 dBm or weaker a reasonable bar for a weak last hop. A later packet whose path ends at the same last hop refreshes its measurement, whether or not that path replaces the one in use. A route that has failed outright is repaired through the route-retry behavior above, which floods at the sender’s full budget rather than the narrowed one.

A weak direct observation keeps the margin partly because the reverse direction may need a repeater the observed packet did not. ACKs can use the same margin, judged from the path the request taught, retaining the request’s region codes to scope any flooding even when the ACK also follows a source route. A strong link can still be one-way, so an ACK for a retransmission of a packet already acknowledged SHOULD carry the margin whatever its path: the retransmission shows the earlier ACK did not arrive. A consumed source route without a usable return trace supplies no total distance; a direct observation alone is insufficient to bound that ACK’s return path. The request’s flood ceiling governs the request, not the ACK’s independently selected return path.

An optional hop does not imply that a repeater is present. Not hearing a repeat is therefore insufficient reason to retransmit a directly addressed packet that requests no ACK, or an ACK sent directly with that allowance. A successful exchange with the margin does not show it was unnecessary.

Potential Improvement: Proactive Route Refresh

The recovery behavior above is reactive: a node continues using a cached source route until that route appears to have failed. In mobile scenarios, this may mean the sender does not attempt to discover a fresher route until after packets have already stopped flowing end-to-end.

One possible future improvement would be to allow a sender to occasionally perform a low-rate exploratory route refresh even when there is no strong indication of failure. This behavior is not part of the current specified protocol behavior and has not been validated with real-world measurements. It is described here only as a possible future optimization.

A conservative version of this idea would look like:

• only perform exploratory refresh when the sender is believed to be mobile or moving
• use a normal cached source route, but also include a Trace option
• allow only a small flood budget, capped at one flood hop more than the source route has hints
• perform this no more than occasionally, for example no more than once every N successful transmissions and no more than once every T minutes, whichever is longer

The intent would be to probe for a slightly better or fresher route without incurring the cost of a full rediscovery flood. A small tail flood could help discover alternate final hops or nearby replacement repeaters when the old route is only partially stale.

This approach has important limitations:

• if the cached source route breaks early, a small tail flood will not help, because forwarding remains constrained by the explicit source route until that route is exhausted
• excessive probing would waste airtime and increase contention, especially on busy meshes
• a newly observed route is not necessarily better and may require local policy before replacing the old route

If this idea is ever standardized, meshes should converge on the same probing policy and parameter values so that behavior remains predictable across implementations. Any such policy should be treated as provisional until it has been evaluated on real radios in mobile conditions.

UMSH over IP Multicast

UMSH can be used over IP multicast the way it is used over LoRa. A frame sent to a multicast group on a local network is heard by every node in the group, as a frame transmitted on a LoRa channel is heard by every node in range, and the group carries UMSH as a LoRa channel does: nodes on it address one another, flood, route, acknowledge, and share channels by the same rules. Phones and computers on one network form a UMSH mesh among themselves, with no LoRa radio anywhere.

A node with a LoRa radio may join the group too. With its repeater enabled it is a bridge between the group and its LoRa channel, as described in Nodes With a LoRa Radio, so that the nodes on the network and the nodes within reach of its radio share one mesh. The group needs no LoRa radio to work.

Why a Multicast Group

A multicast group gives a local network an independent UMSH segment that works as soon as a node joins it. There is no server to set up and no connection to establish or authenticate: a node needs only the group’s address and port, which have defaults, and from then on it hears every other node in the group and is heard by them. Nothing at the transport needs authenticating, because UMSH secures its frames end to end and a node trusts a frame on its contents, never on where it arrived from.

The group can be this simple because it is the kind of medium UMSH is designed for. UMSH frames are sent to a medium, not to a peer:

• A frame names no link-layer receiver. A unicast frame is addressed by a hint of its destination’s public key, and a multicast channel frame by its channel. It is transmitted once, every node in range hears it, and the node it is meant for recognizes it by its cryptographic contents.
• A sender needs no picture of the network. A frame sent with no route reaches every node in direct range; beyond that, a flood carries it, and routes are learned from the traffic itself. Every node in the group is in direct range of every other, so a frame reaches its destination with no route at all.

Over unicast, the same segment would need each node to find its peers and send every frame once per peer, or a server for every node to connect to and relay through. Either is something to set up and keep running that the group does without.

A multicast group is appropriate only because UMSH is a low-bandwidth protocol. Its frames are at most 255 octets, and its rates are set by LoRa: well under a kilobyte per second. Every datagram sent to the group reaches every host in it and, on Wi-Fi, is sent to every station at a low basic rate. That cost is negligible at UMSH’s rates; a protocol that carried pictures or video would not belong in a multicast group, and UMSH is not designed to carry either.

Transport

Frames travel in UDP datagrams sent to an IPv4 multicast group. The default group is 239.255.134.121, in the administratively scoped range, and the default port is 15056. A deployment MAY configure another IPv4 multicast group and another nonzero port; every node that is to hear the others uses the same pair.

Every node sends from the group’s port as well as to it, and listens on it; several nodes on one host share it.

A node joins the group on the interface it uses for the local network and sends to the group from that interface, with a multicast TTL of 16 unless configured otherwise. How far the group reaches is the network’s decision: routers forward a multicast group only where they are configured to, and 239.255.0.0/16 is scoped to the organization. A network that routes the group between its subnets joins their nodes into one group.

Echoes

A node in a multicast group hears its own datagrams when multicast loopback, or an access point repeating a station’s multicast, hands them back. A node MAY drop a datagram whose source address and port are its own, which on a host with several nodes also drops the others’. A node that is alone on its host MAY instead disable multicast loopback.

Point-to-Point

A unicast address MAY be configured in place of the group, naming the one peer of a point-to-point link. The node joins nothing, sends to the peer at the group’s port, and drops every datagram whose source address and port are not the peer’s. Each end names the other, on the same port.

Datagram Format

A datagram carries exactly one frame, with no header: the frame exactly as it is transmitted over LoRa.

• A sender MUST NOT send a datagram that is empty or larger than 255 octets.
• A receiver drops, with accounting, a datagram that is empty or larger than 255 octets, and handles any other as a frame received over LoRa.

The sender of a frame is not identified in the datagram, and nothing about the datagram’s source address is carried onward.

A datagram is a group reception. It was heard by every node in the group, and measured by none of them: it carries no RSSI or SNR, and the signal-quality thresholds do not apply to it.

Traffic

A node sends a datagram only when it transmits a frame: one it originates, an acknowledgment, or, on a node with a LoRa radio, a frame its radio transmits. There is no keepalive, membership, or routing exchange of the group’s own.

Every node in the group hears every datagram, so one datagram delivers a frame to the whole group. A frame reaches the group again when a bridge repeats it onto LoRa, and what a radio sends to the group is bounded by its airtime and its duty cycle.

A node whose only medium is the group SHOULD NOT repeat. Every node it could reach has already heard the frame, so a repeat spends a flood hop and sends one more datagram to every host in the group while carrying the frame to no one new. A network on which a multicast datagram does not reach every node, such as an ad hoc Wi-Fi network whose nodes are not all in range of one another, is the exception: there a repeater carries frames to nodes the sender cannot reach.

Discovery

Nodes advertise themselves with DNS-SD over multicast DNS, under the service type _umsh._udp. A bridge SHOULD advertise; other nodes MAY.

• The instance name is the node’s device name.
• The SRV port is the group’s port.
• The TXT record carries the keys below.

Numbers are decimal with no leading zeros. A node updates its record when any value changes.

A node reading a record ignores keys it does not recognize, treats a missing optional key as false, and ignores a record whose v it does not recognize. Discovery is only discovery: frames travel over the group whatever the records say, and a node learns from them which LoRa meshes the group reaches and on which settings, before it sends anything.

Nodes With a LoRa Radio

A node with a LoRa radio that joins the group is attached to both its LoRa channel, called the air below, and the group:

• What arrives from the group is a reception. The node handles it as it handles a frame heard on its radio, recording that it arrived from the group, and applies the forwarding procedure to it once. With its repeater enabled the node may repeat it on its radio; with its repeater disabled it forwards nothing, whatever the frame arrived on.
• What the radio transmits goes to the group. Each frame the node’s radio puts on the air is sent to the group, its repeats included. A frame the radio does not transmit—a repeat abandoned to a better-placed repeater, or canceled by an overheard acknowledgment—does not reach the group.

A node whose repeater is disabled is therefore a member of the group and nothing more; only a node with its repeater enabled is a bridge.

A frame a node on the group originates spends one flood hop at each bridge that carries it onto the air. A frame heard on the air and carried back onto the air by way of the group spends one hop at the bridge that hears it and repeats it, which is what reaches the group, and one at each bridge that receives it from the group and repeats it. A repeat returns to the group, where every node has already seen the frame and suppresses it as a duplicate.

A bridge that repeats a group reception prepends a Trace record with zero signal bytes, the record for a hop that measured nothing.

The duty cycle a radio spends repeating group receptions counts against its limit like any other forward. Copies sent to the group spend no radio airtime.

Ingress Limit

A bridge MUST bound the rate at which it accepts group receptions, so that a busy network cannot spend the radio’s airtime faster than its operator allows. A token bucket of frames per minute is recommended. Receptions over the limit are dropped with accounting.

Channel Access

Every bridge in the group receives each datagram at once, so bridges on the same LoRa channel would carry it onto the air together. Group receptions therefore contend, and only what is heard over the air says anything about the air.

• Group receptions contend. A group reception carries no measurement to rank bridges by. Its flood contention window is drawn uniformly from [W_min, W_max], and the jitter and D_ack are added as for any other forward.
• Only the air defers. Only a copy received over the radio defers or abandons a pending forward. A copy received from the group says nothing about who has transmitted on the radio’s channel, and is a duplicate and nothing more.
• A group copy confirms. A copy received from the group is a frame some radio transmitted, and satisfies forwarding confirmation as a copy overheard on the air does.
• Ack cancellation is unchanged. An overheard acknowledgment cancels a matching pending forward whatever it arrived on: it proves delivery either way.

Bridges on one LoRa channel that hear the same group reception draw different windows. The first to transmit is overheard by the others, which defer as they would for any repeat they overheard.

Security Considerations

• Frames are protected end to end. A UMSH frame that carries security information is authenticated, and encrypted where it is marked encrypted, by the node that sends it, before it reaches any medium. The group adds no protection and removes none: what crosses the network is what crosses the air, and a node trusts a frame on its contents, never on where it arrived from.
• Anyone on the network hears the group. A listener on the network learns what a LoRa receiver in range of the same nodes would.
• Anyone on the network can send to the group. The group is as open as a LoRa channel is to anyone with a radio. A frame that fails authentication is dropped by the node it is addressed to. Where bridges are present, the ingress limit and the duty-cycle limit bound what injected traffic costs the air.
• The group reaches as far as the network routes it. The default group is administratively scoped. A network that routes it between subnets has extended the group, and any bridges in it, to everyone the routing reaches.
• DNS-SD records are public. A record reveals a node’s public key and, for a node with a LoRa radio, its LoRa settings—which its transmissions already reveal to anyone in range—to everyone on the network.
• Bridges join meshes. The cautions in Routing Overview § Bridging apply: a bridge in the group puts the flood traffic of every LoRa mesh reachable through the group on its own mesh’s airtime. Region policy and the flood hop budget are the tools for keeping that local.

Payload Format

The UMSH payload carries higher-layer content—either a network-layer protocol (e.g., 6LoWPAN), a third-party application protocol (e.g., CoAP), or one of the UMSH-defined application protocols (e.g., text messages, chat rooms). The MAC layer treats the payload opaquely; it does not interpret, fragment, or reassemble payload content (see Layer Separation).

Payloads are typically prefixed by a 1-byte payload type identifier. Values from 128-255 (all values with the most significant bit set) are currently RESERVED.

Payload Type Registry

Payload and Packet Type Compatibility

Not all payload types are valid with all packet types. A receiver should drop a packet whose payload type is not compatible with its packet type. For the purposes of this table, blind unicast follows the same rules as unicast.

Unless explicitly configured otherwise, the only payload types allowed for broadcast are empty payloads, node identities, the broadcast-permitted MAC commands (Note 2), and Meet Hellos (Note 3).

Note 1: Some MAC commands may be permitted on specific channels. For example, a private channel might allow echo requests to all members and receive echo responses from everyone. Whether a given MAC command is accepted over multicast is deployment-defined and not yet specified by the protocol.

Note 2: MAC commands are admitted to broadcast individually: a command may be carried in a broadcast only when its definition says so, and any such definition must weigh the solicitation load a broadcast can create. Currently only the Identity Request permits broadcast carriage, under the flood-management restrictions defined there. Receivers drop any other MAC command arriving by broadcast.

Note 3: Only a Hello rides a broadcast. Every other Meet kind is unicast between session keys.

Response Carriage

A response to a unicast request is carried the same way the request was: a request that arrived as blind unicast on a channel is answered as blind unicast on that same channel, and a request that arrived as plain unicast is answered as plain unicast. This holds for every request and response the protocol defines—MAC commands, node identity, node management—and applies whether the response comes from the MAC layer or from an application above it.

Blind unicast conceals both endpoints from observers who lack the channel key. A response sent off the channel names the parties the request took care to hide, so it would undo that concealment for the exchange as a whole. A MAC acknowledgement is not a response and remains channel-less; it carries no destination hint and so names neither party.

A node answering a multicast or broadcast request is not bound by this rule, since such a request has no pairwise carriage to mirror. What a node may answer with is left to each command’s own definition.

In-Band Node Management

Nodes may optionally support remote management via Node Management Request and Node Management Response payloads, which carry ULCP exchanges over the mesh itself. The payload format, authorization model, and reachable state are specified in Node Management; support is advertised through the CAP_ADMIN ULCP capability.

Node Identity

The node identity payload is an application-layer structure carried inside the UMSH payload. Its contents—including the timestamp option below—are not interpreted or required by the MAC layer. The MAC layer itself is timestamp-free (see Frame Counter).

Structure

+------+------+---------+------+-----------+
| ROLE | CAPS | OPTIONS | 0xFF | SIGNATURE |
+------+------+---------+------+-----------+
  1 B    1 B   variable   1 B     64 B

Fields:

• ROLE (1 byte)—the node’s primary role.
• CAPS (1 byte)—the node’s capability bitmap.
• OPTIONS (variable, optional)—a CoAP-style option list of node identity options, using the same delta-length encoding as packet options.
• 0xFF (1 byte, optional)—options-terminator marker. Present only when a signature follows.
• SIGNATURE (64 bytes, optional)—EdDSA signature covering ROLE through the 0xFF terminator, inclusive.

The smallest node identity payload is two bytes: role and capability bitmap, with no options or signature.

Node Primary Role

Defined values:

• 0—Unspecified
• 1—Repeater
• 2—Chat
• 3—Tracker
• 4—Sensor
• 5—Bridge
• 6—Chat Room
• 7—Temporary Session
• all other values—Reserved

Capability Bitmap

A single byte describing optional feature support, orthogonal to the primary role:

  7   6   5   4   3   2   1   0
+---+---+---+---+---+---+---+---+
| - | - |CoA|CHR|TLM|TXT|MOB|REP|
+---+---+---+---+---+---+---+---+

• bit 0 (REP)—Repeater
• bit 1 (MOB)—Mobile/Handheld (As opposed to “fixed”)
• bit 2 (TXT)—Text Messages
• bit 3 (TLM)—Public Telemetry
• bit 4 (CHR)—Chat Room
• bit 5 (CoA)—CoAP
• bits 6–7—RESERVED (set to zero; ignore on read)

A node may advertise multiple capabilities independently of its primary role. For example, a node with role Chat may also set the REP bit to advertise repeater duty.

Node Identity Options

Options use the CoAP-style delta-length encoding defined in Packet Options.

Node Name (option 0)

A UTF-8 display name for the node, typically shown in user interfaces. Max length: 24 bytes.

Node Location (option 1)

The node’s geographic position, encoded as a variable-precision grid code. See Variable-Precision Location Format. Max precision: 7 bytes. Implementations MUST ignore bytes beyond the seventh and MUST NOT encode more than 7 bytes.

Altitude in Meters (option 2)

The node’s altitude above mean sea level in meters, encoded as a minimal big-endian signed integer (leading 0x00 and 0xFF sign-extension bytes omitted, provided the sign bit of the remaining value is unambiguous). Max length: 4 bytes.

Unix Timestamp (option 3)

Seconds since the Unix epoch indicating when this identity payload was generated. Lets a consumer judge how fresh the identity is—most useful when the identity stands alone (e.g. in a QR code), where a stale capture could otherwise be presented indefinitely. Not used by the MAC layer. Encoded as a minimal big-endian unsigned integer (leading zero bytes omitted). Max length: 4 bytes.

Supported Regions (option 4)

For repeaters, the regions the node will flood-forward for, one option per region. Each entry carries the region’s string form—the short code for a region that has one, the region name otherwise—rather than its two-byte region code: the code is always derivable from the string, while a hash-derived code cannot be turned back into a name. A sender lists at most 10 regions, and the identity payload must still fit its enclosing packet, so a node whose full list does not fit omits regions; the option names regions the node forwards for without promising to name every one. A node that omits the option entirely makes no claim about its regional forwarding policy. Entries carry the capitalization the region was written with, and a receiver comparing them derives their codes, which ignores ASCII case. Max length: 24 bytes per entry, the bound on region names.

Nonce (option 5)

Copied verbatim from the Identity Request that solicited this identity payload, letting the requester correlate the response to its request. Present only in responses whose request carried a NONCE option. Length: 4 bytes.

Variable-Precision Location Format

The node location is encoded as a string of one or more bytes, where each byte narrows the position to a 16×16 sub-grid of the preceding byte’s cell. Additional bytes increase precision; trailing bytes may be omitted to give a coarser—and therefore more privacy-preserving—location.

Grid Subdivision

Each byte splits its parent cell into a 16×16 grid of children. Within each byte, the high nibble indexes along latitude and the low nibble indexes along longitude:

  7   6   5   4   3   2   1   0
+---------------+---------------+
|   LAT NIBBLE  |   LON NIBBLE  |
+---------------+---------------+
     4 bits          4 bits

The first byte subdivides the entire globe (latitude in 16 slices of 11.25°, longitude in 16 slices of 22.5°). Each subsequent byte subdivides the cell selected by the byte before it, using the same high-nibble-latitude, low-nibble-longitude convention.

Latitude leads here for the same reason it leads everywhere else in UMSH: a coordinate pair is written, spoken, and passed as (latitude, longitude), and an encoding that reversed the pair would be the one place the convention did not hold.

Encoding a Location

Given latitude LAT in degrees (-90..+90) and longitude LON in degrees (-180..+180), an N-byte code can be derived either in a single step or byte by byte. The direct form is normative; where floating-point rounding makes the iterative form disagree at the final nibble, the direct form’s result is the correct code.

Direct form

Compute two 4N-bit indices over the full desired precision:

• lat_index = floor((LAT + 90) × 16^N / 180)
• lon_index = floor((LON + 180) × 16^N / 360)

Then read nibbles from most significant to least significant:

• byte k high nibble = (lat_index >> (4 × (N − 1 − k))) & 0xF
• byte k low nibble = (lon_index >> (4 × (N − 1 − k))) & 0xF

This form makes the hierarchy explicit: truncating an N-byte code to k bytes yields exactly the k-byte code for the same position.

Edge cases: LON = +180° is equivalent to LON = −180° and wraps lon_index to 0. LAT = +90° is a single degenerate point; clamp lat_index to 16^N − 1.

Iterative form

Emitting one byte at a time, with lat_step = 11.25° / 16^k and lon_step = 22.5° / 16^k:

• byte k high nibble = floor(((LAT + 90) mod (16 × lat_step)) / lat_step)
• byte k low nibble = floor(((LON + 180) mod (16 × lon_step)) / lon_step)

For byte 0 (k = 0), lat_step = 11.25° and lon_step = 22.5°, so the modulus is a no-op for valid inputs and the formulas reduce to:

• high_nibble = floor((LAT + 90) / 11.25)
• low_nibble = floor((LON + 180) / 22.5)

The same edge cases apply as in the direct form: LON = +180° wraps to nibble 0 naturally via the modulus, but LAT = +90° must be clamped to nibble 0xF at every position—the modulus would otherwise wrap it to nibble 0.

Worked Example

Encode (LAT, LON) = (37.331°, −121.883°) (San Jose, CA) at 3-byte precision.

Direct form:

• lat_index = floor(( 37.331 + 90) × 4096 / 180) = floor(2897.49) = 2897 = 0xB51
• lon_index = floor((−121.883 + 180) × 4096 / 360) = floor(661.24) = 661 = 0x295

Reading nibbles most-significant first:

Final code: B2 59 15.

Decoding a Location

An N-byte code denotes the entire cell it selects, not a point. When a single coordinate is needed (e.g. to plot on a map), decoders use the center of the cell, with an uncertainty of ± half a cell in each axis. Using any other point (such as the cell’s south-west corner) would place decoded positions up to half a cell apart between implementations.

Precision Scaling

Each additional byte divides both the latitude and longitude spans by 16. The span shrinks geometrically, so just a few bytes yield very fine precision:

Longitude cells narrow with latitude, so cells are physically smaller in east-west extent away from the equator.

Comparison with float32: Two single-precision floats (8 bytes) give non-uniform resolution: ~85 cm latitude and ~1.7 m longitude worst-case near ±90°/±180°, improving to ~1 cm near 0°. At 7 bytes, this encoding achieves ~7.5 × 15 cm uniformly across the globe—better than the float32 worst case while using one fewer byte. At 8 bytes—beyond the 7-byte wire limit, considered here only for an apples-to-apples comparison against the 8 bytes two floats occupy—the cell shrinks to ~5 × 9 mm, better than float32 everywhere.

Properties

• Simple encoding. Two nibble divisions per byte; comparison and truncation are pure integer operations, and decoding needs only integer or fixed-point arithmetic.
• Arbitrary precision. Any desired accuracy is reachable by adding bytes.
• Compact. Scales linearly with precision: one byte per factor-of-16 refinement in both axes.
• Free coarsening. Reducing precision is just truncation; no recomputation is needed. This makes it trivial to publish, say, a 2-byte location in a broadcast and a 5-byte location in a private message, both derived from the same underlying position.

Caveats

• Prefix locality is one-way. Codes sharing a prefix select nearby cells, but nearby positions straddling a cell boundary may share no prefix at all. Prefix comparison alone is therefore suitable only for coarse filtering; proximity queries must also check neighboring cells.
• Coarseness is angular, not metric. Because longitude cells narrow with latitude, a given byte count discloses a physically smaller area at high latitudes. When truncating for privacy, choose the precision by the physical extent of the resulting cell rather than by byte count alone.

Location Privacy

This section is non-normative implementation guidance for senders, with one exception noted below. Receivers cannot distinguish a diluted position from a true one, so nothing here affects the wire format or interoperability.

Truncation is the first privacy tool: dropping bytes discloses only a cell. But a cell is a set, and an observer with context can shrink it. If a cell is mostly water and the tip of an isthmus barely pokes into it, reporting that cell effectively reports the isthmus tip, no matter how large the cell is. Truncation alone cannot defend against such priors, because the disclosed region is always aligned to the fixed cell lattice.

The defense is to add a deliberate position offset before encoding, so that the feasible region becomes the reported cell dilated by the offset’s magnitude—spilling across cell boundaries and decoupling the disclosure from the lattice. Done naively, however, this mechanism leaks more than plain truncation. The recommended construction and the pitfalls it avoids follow.

Recommended Construction

1. Offset in meters, not degrees. Draw a planar offset (east and north components in meters) and convert to degrees at the current latitude. An offset specified in degrees gives latitude-dependent, anisotropic protection.
2. Uniform distribution. Draw the offset uniformly, over either a disk of radius R (isotropic) or a box of half-width R (simplest: two independent uniform components taken directly from a keyed hash). A uniform offset makes every position within R of the report equally plausible. A peaked distribution such as a Gaussian defeats the purpose: its density gradient leaves the reported position the single most probable true position, so the report still points at the sender, just fuzzily. The cost of bounded support is that an observer knows the true position is certainly within R of the report—but every bounded distribution shares this, and unbounded tails trade it for occasionally reporting positions an absurd distance away.
3. Magnitude matched to the published precision. Choose R between roughly 0.5× and 2× the extent of the cell at the coarsest precision being protected. Much below that range the reported cell almost never differs from the true one and the offset is a placebo; much above it the reports are useless. Note that the offset and truncation are complementary: truncation coarsens in 16× steps, while R tunes ambiguity continuously between those steps.
4. Deterministic per place. Derive the offset from a keyed hash of a secret location-privacy key and the true position quantized to a coarse derivation cell (comparable in extent to R). The same place then always yields the same offset—across reports, reboots, and revisits—with no random-number state to persist and no re-draw event to observe or provoke.
5. Hysteresis at derivation boundaries. A device straddling a derivation-cell boundary must not flap between the two derived offsets: keep the current offset until the true position moves well inside a neighboring derivation cell. Flapping hands an observer two independent samples of nearly the same position, and the flapping pattern itself localizes the device to the boundary.
6. One diluted position feeds all encodings. Apply the offset once, to the underlying position, and derive every published precision by truncating that single result. If a coarse broadcast and a fine private message are diluted independently, comparing them yields two samples of the same position.

The Resampling Trap

The offset MUST NOT be re-drawn per report. This is the one normative statement in this section, because the failure is worse than doing nothing: fresh noise per report combined with quantization is a dithering scheme. The expected value of the reported cell is a continuous, monotone function of the true position, so an observer averaging repeated reports recovers the position to a precision limited only by the number of samples—below the cell size, without bound. A stationary node adding fresh noise to every identity broadcast discloses more over time than one publishing its true cell.

The intuition that quantization backstops the noise is exactly backwards: deterministic truncation has a hard resolution floor; truncation of freshly-noised input has a soft floor that averages away.

Limits

• Mobile nodes. A fixed offset protects a stationary position well. If the device moves while the offset is held, the reported track is the true track translated by a constant vector, and matching the track’s shape against roads or coastlines recovers the offset exactly. For mobile nodes the mechanism obscures where a track is anchored, not its shape; treat it accordingly.
• Ground-truth correlation burns the offset. Any single correlation between a reported position and the true one—a precise disclosure through another channel, a physical encounter—reveals the offset for as long as it is held. After such an event the privacy key (or derivation input) should be rotated.
• Radio-layer localization is out of scope. The mechanism launders only the advertised location field. Observers in RF range can localize a transmitter by which nodes hear it and at what signal strength, regardless of what its identity payload claims. The mechanism is meaningful against remote consumers of identity payloads, not against nearby receivers.

Signature Usage

The optional 64-byte EdDSA signature lets an identity stand on its own, apart from any frame, as in QR codes and exported identities.

An identity carried in a frame is authenticated by that frame instead, and need not carry the embedded signature. An advertisement is authenticated by its frame signature, and an identity response by its unicast MIC.

A receiver believes an identity only when one of these holds:

• its embedded signature verifies against the sender’s key;
• it has no embedded signature, and its frame authenticates the sender: a verified frame signature, or a unicast or blind unicast MIC.

A multicast MIC alone does not authenticate the sender, since any channel member can produce one under any source address. An identity whose embedded signature does not verify is not believed.

A frame signature is checkable only against the sender’s public key. An advertisement meant for receivers that may not yet hold that key MUST therefore carry its source address in full-key form; a hint-only advertisement can be verified only by a receiver that already holds the key.

An identity authenticated by its frame SHOULD replace stored details only when that frame advanced the sender’s established receive baseline (see Replay Detection). A frame accepted as first contact, or one accepted from behind the baseline, MAY fill details that are missing but SHOULD NOT replace stored ones: a late frame can carry details older than those already stored. A baseline restored from storage is established.

Contact Exchange

![NOTE] This section is an early work in progress and this protocol may change significantly.

Meet payloads (payload type 10) let two people standing together exchange contacts without typing an address. Each device announces itself under a session key drawn for the purpose, showing only its model and a color derived from that key. One holder asks, the other agrees, and both screens show a six-digit code. Each holder compares the codes and presses Same or Different. A device sends its own long-term key and node identity only when its holder presses Same.

Nothing a device sends before its holder’s Same identifies it beyond its model. The person standing there is the identification, and the code confirms that the two devices talking are the two in their hands.

Session Keys

A session key is a fresh Ed25519 key pair, used as an ordinary node identity for the length of one session and never again. Every Meet frame is sent from the session key with the full source key in the header, and every unicast is addressed to the other device’s session key.

A device MUST draw a new session key, and new nonces, for every exchange attempt. That includes trying again after an attempt ends in Not now, Busy, Different, a timeout, or a failure. When an attempt ends for any reason, the session key’s private half is erased.

A session key answers for nothing but Meet. A device MUST NOT accept or answer any other payload addressed to a session key: no node identity, no MAC command, no text. Meet unicasts addressed to a long-term identity are dropped.

Payload Format

+------+---------+------+------+
| 0x0A | VERSION | KIND | BODY |
+------+---------+------+------+
  1 B     1 B      1 B    var

VERSION is 1. Any change to a body layout, or a new kind, takes a new version. Every kind except Identity has a body of exactly the length given below. Identity’s body runs to the end of the payload. No kind is followed by anything: bytes past the end of a body make the payload malformed.

A Hello is carried in a broadcast with no flood hops. Every other kind is carried in an encrypted unicast between the two session keys, with an acknowledgment requested and no flood hops. A kind on the wrong carriage is malformed.

Hello

MODEL is the sender’s hardware model, a model identifier (big-endian, 0 when unspecified). A Hello carries nothing else. It lists the sender on the receiver’s Nearby screen, keyed by its session key.

Request

Sent by the device whose holder asked (A) to the device asked (B):

COMMITMENT = SHA-256("UMSH meet commit" ‖ S_A ‖ S_B ‖ N_A)

S_A and S_B are the two session public keys, and N_A is 16 random bytes A keeps until Reveal.

Accept

Sent by B when its holder agrees. NONCE is N_B, 16 random bytes.

Reveal

Sent by A on receiving Accept. NONCE is N_A. B checks that the commitment it holds equals SHA-256("UMSH meet commit" ‖ S_A ‖ S_B ‖ N_A). On a mismatch B sends End with reason failed.

Identity

+-----+---------------------------------------------+
| KEY | ROLE | CAPS | OPTIONS | [0xFF | SIGNATURE] |
+-----+---------------------------------------------+
 32 B   node identity payload, to the end of the frame

KEY is the sender’s long-term public key. The rest of the body is its node identity payload, read as follows:

• ROLE, CAPS, then options until the end of the frame or a 0xFF marker.
• If the end of the frame is reached, the payload is unsigned.
• If a 0xFF marker is found, exactly 64 bytes MUST follow it, and they are the signature. Any other count, including none, makes the Identity malformed.

The signature is the ordinary node identity signature: Ed25519 by KEY over ROLE through the 0xFF marker, as in a node URI bundle. It is optional. A signature that does not verify under KEY makes the Identity malformed.

An Identity carries no session binding. A sender that passed along someone else’s key and payload could neither read what is sent to that key nor send as it.

A device sends its Identity when its holder presses Same, and the Identity stands for that Same.

End

Ends the attempt for both devices.

An unknown reason still ends the attempt.

Code and Color

Both devices show:

CODE = BE32(SHA-256("UMSH meet code" ‖ S_A ‖ S_B ‖ N_A ‖ N_B)[0..4]) mod 1000000

as six decimal digits, zero-padded.

Each session key has a color. Its hue step is:

HUE = SHA-256("UMSH meet color" ‖ S)[0]

The color is the OKLCH color with lightness 0.75, chroma 0.12, and hue angle HUE × 360° / 256, converted to 8-bit sRGB:

1. a = 0.12·cos(h), b = 0.12·sin(h).
2. l' = 0.75 + 0.3963377774·a + 0.2158037573·b m' = 0.75 − 0.1055613458·a − 0.0638541728·b s' = 0.75 − 0.0894841775·a − 1.2914855480·b
3. l = l'³, m = m'³, s = s'³.
4. Linear sRGB: R = 4.0767416621·l − 3.3077115913·m + 0.2309699292·s G = −1.2684380046·l + 2.6097574011·m − 0.3413193965·s B = −0.0041960863·l − 0.7034186147·m + 1.7076147010·s
5. Each channel x, clamped to [0, 1], is encoded as 12.92·x when x ≤ 0.0031308 and 1.055·x^(1/2.4) − 0.055 otherwise, then scaled by 255 and rounded.

All 256 colors fall inside the sRGB gamut. Implementations may precompute them as a table.

Exchange

1. Both devices broadcast Hellos and list each other.
2. A’s holder picks B’s row. A sends Request.
3. B’s holder is asked. Agreeing sends Accept. Declining sends End (not now).
4. A sends Reveal, and shows the code.
5. B checks the commitment and shows the code.
6. Each holder compares. Same sends that device’s Identity. Different sends End (different).
7. A device that has both sent and received an Identity has exchanged.

The commitment is sent before either nonce, and each nonce only after the other side is bound: B sends N_B only while holding C_A, and A reveals N_A only after receiving N_B.

What a device does with a received Identity is up to it, except that it MUST discard it if its own holder presses Different or leaves.

Rules

• An Identity received before the device shows the code is dropped.
• An Identity whose KEY is the receiver’s own long-term key is dropped.
• When both devices send Request to each other, the device with the lower session key (compared as big-endian unsigned integers) ignores the incoming one. The other drops its own Request and sends Accept without asking its holder, who already asked.
• A Request arriving while the receiver is in an exchange, or after its session’s attempt has ended, is answered with End (busy).
• A device sends no Hellos while an attempt is in progress.

Timeouts

A device whose limit passes sends End (timed out).

Malformed Frames

A frame from the session key a device is in an exchange with, by unicast, is inside the exchange. Inside the exchange, any malformed frame—an unknown version or kind, a wrong length, a wrong carriage, or an Identity that does not parse or verify—ends the attempt: the receiver sends End (failed) and keeps nothing.

Any other frame is outside. A malformed frame outside an exchange is dropped and never answered. A device speaking a newer version is simply not listed.

A well-formed frame that does not fit the current state is dropped.

Nearby

A device sends a Hello when it opens a session, one more between 0.5 and 2 seconds after it first hears a session key it has not listed, and then periodically. The periodic interval is at least 5 seconds, scaled to the airtime of the current channel settings, and each one is jittered by up to a quarter either way. A row ages out after three intervals without a Hello.

Two devices of the same model whose hue steps are within 24 of each other (about 34°, wrapping around) are hard to tell apart. While idle, the device with the lower session key of such a pair opens a new session, with a new key and a new color.

Transmit Power

A device SHOULD send every Meet frame, and every acknowledgment of one, at −9 dBm, or at the least power its radio can transmit if that is higher. The two holders stand together; nothing farther away needs to hear them.

Linking a Name to a Key

A Meet Identity travels between session keys, not from KEY, so nothing but its signature links its payload to KEY. An unsigned Identity’s name and other claims are the sender’s word only.

MAC Commands

A MAC command payload consists of:

• 1 byte: command identifier
• optional bytes: command-specific payload

Support for MAC commands is optional.

A receiver reads the fields a command defines and ignores any bytes that follow them. A command shorter than its defined fields, or with an unrecognized identifier, is ignored.

MAC commands are addressed to a single node. Unless a command’s definition provides rules for multicast or broadcast use, as Identity Request does, a node ignores a command that arrives by multicast or broadcast.

A node answering a command carries its response the way the request was carried, as Response Carriage defines.

Command Registry

Identity Request (1)

Requests that the destination respond with its node identity.

A common use is resolving a node hint to a full address. A node that knows only a peer’s hint sends this command as a broadcast or multicast carrying a FILTER_NODE_HINT filter; a matching node replies with an encrypted unicast (or blind unicast) response carrying its full node identity. When the requester believes the peer may not yet know the requester’s own address, it sends its full source address in the request so the peer can reply directly.

Because a broadcast Identity Request can solicit many replies:

• A node MAY decline to respond to a request from an unknown source.
• A repeater MAY decline to forward a broadcast Identity Request, particularly when its filters are broad enough to solicit a large number of replies.

In order to manage the potential flood of responses, the following rules MUST be applied for broadcast (always) and (by default) multicast:

• The Route option must either be absent or empty, otherwise the request should be dropped.
• Responses must be delayed by a random amount of time drawn from a window of 0.5 to 30 seconds, so that the selected nodes do not all answer at once. A delayed response that then fails channel-activity assessment follows the responder’s normal bounded CCA backoff-and-retry before being dropped. A request every FILTER_NODE_HINT of which is 2 or 3 bytes is exempt and MUST be answered without the delay: such a request names a node rather than a share of the mesh, so there is no crowd of replies to spread and the hold would only make the answer late. One byte names a 256th of what the request reaches, so it is not exempt; filters of the same type combine as OR, and the shortest one decides.
• One solicitation is answered at most once. A request reaches a node once per path it travels, and a plain broadcast carries no frame counter for a lower layer to recognize the repeat by; the NONCE is what names the solicitation. A responder suppresses a request matching one it has already answered—same sender, same NONCE—for at least as long as it may hold the reply. A request carrying no NONCE cannot be distinguished from a repeat of itself; a requester that wants a further answer inside that window asks with a fresh NONCE.

A FILTER_NODE_HINT filter names a single node, so a request carrying one solicits a single reply however far it travels. A partial hint names a small set rather than one node, and the shorter it is the larger that set: a requester sends the longest hint it holds. A request with no hint filter at all selects by role or capability, and every node it reaches may answer; such a request is therefore confined to the requester’s own neighborhood:

• The FHOPS byte must either be absent or set to 0x00. A request that is flood routed—FHOPS present with either nibble nonzero—MUST NOT be answered.
• The response MUST NOT carry a FHOPS field (the FCF flood hop count flag is clear). The invariant is that the reply travels exactly as far as the question did and no further: a request that crossed one hop is answered across that one hop, and a request steered along a Source Route option is answered back along the path it was steered down.

A request steered by a Route option reaches its destination neighborhood with that option emptied, since each repeater consumes its own hint. The nodes there are strangers to the requester: they hold no route to it, and their replies carry no flood budget for a repeater to spend. Such a request therefore carries a Trace option, and a node answering it sends the response as a source route built from the trace the request arrived with, when that trace is complete. Repeaters prepend when forwarding, so the accumulated trace already reads as the path back and is used as-is, without reversal.

The response carries a Trace option of its own. The trace on the request is what taught the responder a path home, and it taught the requester nothing: a broadcast solicitation leaves no route behind at the requester, and the response reaches it with its own Route option consumed and its FHOPS_ACC counting only the tail of the path. Without a trace on the response the requester ends the exchange holding no route to the node it just identified. A broadcast solicitation names no responder, so even one that arrived without flooding gives the requester no path to whoever answers it; the response traces regardless of the general rule.

A repeater consumes its own hint while forwarding, not while receiving, so a request whose Route option still names a repeater is one that repeater drops. Asking a named router to identify itself therefore means steering the request to the hop before it and narrowing it with that router’s two-byte hint: the request arrives with an empty Route option, and the router answers it as any other node in that neighborhood would.

These requirements MAY be relaxed for specific private channels, but MUST remain in place for all public channels. Note that these requirements are specifically designed to allow discovering identities from a specific repeater location on the mesh network.

An Identity Request is answered with a targeted unicast identity response, never by flooding an advertisement to the whole network.

Identity Request Options

A unicast Identity Request requires no payload. A multicast or broadcast request MUST carry at least one filter option, so that only the intended nodes respond.

Options use the CoAP-style delta-length encoding defined in Packet Options. As in CoAP, an option’s key encodes its criticality: odd-numbered keys (least-significant bit set) are critical, even-numbered keys are elective. A node that encounters a critical option it does not understand MUST treat itself as excluded and MUST NOT respond.

Filter options select which nodes respond. They combine as a logical AND across different filter types and a logical OR among repeated filters of the same type: a node responds only if it satisfies every filter type present, and it satisfies a given filter type if it matches any one of that type’s values. Non-filter options (such as NONCE) do not participate in this matching.

Signal Report Request (2)

Requests that the destination respond with signal quality information about the link.

No command-specific payload.

Signal Report Response (3)

Reports signal quality measurements in response to a Signal Report Request.

Echo Request (4)

Requests that the destination respond with an Echo Response.

Echo requests may be used for:

• round-trip latency measurement
• reachability testing
• frame-counter synchronization (by observing the frame counter in the response’s SECINFO)

Echo Response (5)

Carries a response to a prior Echo Request, including any echo data from the request.

The response SHOULD carry a Trace option when the request carried one. An echo measures a path, and a response traced differently from the request measures a different one; the per-hop signal in the two traces is what makes the measurement per-hop rather than end to end.

PFS Session Request (6)

Initiates a PFS session. The sender generates a fresh ephemeral node address and transmits it along with a requested session duration. See Perfect Forward Secrecy Sessions for the session establishment mechanism, key derivation, and wire-level privacy properties.

PFS Session Response (7)

Sent in response to a PFS Session Request. The responder generates its own ephemeral node address, returns it along with the accepted duration, and both sides derive session keys from the ephemeral addresses. See Perfect Forward Secrecy Sessions.

The responder MAY accept a shorter lifetime than was requested, and both parties hold the session to the accepted one. A node that receives a duration of 0 treats it as a finite lifetime of its own choosing; a responder answers with that lifetime.

End PFS Session (8)

Terminates an active PFS session. May be sent by either party. Upon receipt, both sides securely erase the private keys for their ephemeral addresses and revert to using their long-term keys. See Session Lifetime for all conditions under which a session ends.

No command-specific payload. The sender and recipient are identified by the packet’s addressing fields.

No-Op (9)

This command does nothing, however it will produce a UACK when sent via a packet type that requests an ACK.

Peer Repeaters Request (10)

Asks the destination—typically a repeater—for its list of known peer repeaters.

The list is the responder’s repeater neighborhood: the repeaters it has heard from their own transmitters. A repeater enters it in one of two ways. Forwarding a frame the responder receives is one—a repeater prepends its record to the frame’s Trace, so the first hint names the repeater whose transmission was just heard. Advertising is the other—a node identity claiming the repeater role or capability, heard directly rather than forwarded. Frames heard from nodes that are not repeaters, and identities that arrived through a repeater, put nothing in the list. Nor does anything naming the responder itself: a trace that begins with its own router hint, or its own identity. A neighbor need not be on the air: a repeater reached over a point-to-point link, such as an attached host, is listed the same way and simply carries no signal measurements.

The command-specific payload is a CoAP-style option list, using the delta-length encoding defined in Packet Options:

No payload follows the options, so the sender omits the 0xFF end-of-options marker.

A list too large for one response is retrieved page by page: the first request carries no Cursor, and each response that carries one names the place a follow-up request should resume from. The cursor is opaque to the requester; only the responder gives it meaning.

Peer Repeaters Response (11)

Returns one page of the responder’s peer-repeater list in response to a Peer Repeaters Request:

+---------+------+---------+------+---------+------+     +---------+--------+
| OPTIONS | 0xFF | ENTRY 0 | 0xFF | ENTRY 1 | 0xFF | ... | ENTRY N | (0xFF) |
+---------+------+---------+------+---------+------+     +---------+--------+

The response options:

The 0xFF after the response options is the ordinary end-of-options marker; the entry list that follows is the command’s payload. Each entry is itself a CoAP-style option list terminated by its own 0xFF byte. The final entry MAY omit its terminator, consistent with omitting the marker when nothing follows.

The options per entry:

An option whose value the responder does not know is omitted. Entries carry region codes rather than the strings the identity option carries—the entry format is tighter on space, and the string form of a code, when one is wanted, is available from the peer’s own identity.

Verify Frame (12)

Asks the destination to vouch for a packet it sent to the requester whose frame counter the requester could not accept. See Counter Resynchronization for when it is sent and what each side does with the answer.

The packet carrying the command MUST include an Ack MIC option naming the packet to verify, and does not request an acknowledgement. A responder ignores a Verify Frame without the option.

Frame Verified (13)

Answers a Verify Frame naming a packet the responder sent and is still waiting to have acknowledged.

The packet carrying the command MUST request an acknowledgement. Its acknowledgement acknowledges the verified packet as well.

Node Management

![NOTE] This section is an early work in progress and this protocol may change significantly.

A node that supports node management can be configured and observed over the mesh itself, using the same command grammar, property model, and numeric registries that ULCP defines for the local link. Node Management Request (payload type 8) and Node Management Response (payload type 9) payloads carry ordinary ULCP frames between an administrator—a node listed in the device’s administrator list—and the device, in unicast packets exchanged with the device identity. Support is optional and advertised through CAP_ADMIN.

Administering a device over the mesh reaches the device domain and nothing else. An administrator is not a tethered host: a remote exchange is not an attach, touches no session state, and neither sees nor disturbs the host domain or the assistance the device owes to whatever host it serves. Two Kinds of Attach draws the same boundary on the local link; over the mesh, only the administrative kind exists.

Transport Properties

The binding relies on exactly what the MAC layer guarantees for secure unicast: the source of every accepted packet is authenticated, payloads are confidential, and replay protection accepts a given frame at most once. It assumes nothing more—not delivery, and not ordering. The payload format adds what the ULCP grammar needs on such a transport:

• a token correlates responses with requests across long and variable round trips, in place of the TID of the local bindings;
• retained responses make retransmission safe: a repeated request that changes something is answered again, not executed again;
• cursors carry a response larger than one frame across as many exchanges as needed, every fragment cut from that one response.

Several operations per exchange need nothing from the envelope: the multi-property commands already carry several reads, or several ordered writes, in a single frame.

Because wire-level duplicates are impossible, the binding has no deduplication window of its own; the only duplicates that can exist are an administrator’s own retransmissions, which the token identifies.

Payload Format

Request and Response payloads share one format, consisting of, following the payload type byte:

+-------+---------+------+----------+
| TOKEN | OPTIONS | 0xFF |  FRAME   |
+-------+---------+------+----------+
  2 B    variable   1 B    variable

Direction lives entirely in the payload type. A device drops a Response payload—it never solicits anything—and an administrator that receives a Response matching no outstanding exchange of its own discards it, both with accounting.

Node Management payloads travel only in unicast and blind unicast packets: Requests are addressed to the device identity, and Responses return to the requesting node on the carriage the Request arrived on (see Response Carriage), using whatever routing state the exchange has supplied (see Route Learning). A Response carries the Ack MIC option naming the Request it answers, so it confirms the Request’s delivery even when the MAC acknowledgment is lost. A device drops a Node Management payload arriving by multicast or broadcast, with accounting.

Token

Two opaque octets chosen by the administrator and echoed verbatim in the response. The token correlates a response with its request and identifies retransmissions (see Retries and At-Most-Once Processing). An administrator MUST choose a token different from its previous exchange’s when beginning a new exchange, and MUST reuse the token when retransmitting a request unchanged.

Options

Options use the CoAP-style delta-length encoding defined in Packet Options. As in MAC command options, odd-numbered options are critical and even-numbered options are elective. A device that receives a request carrying an unrecognized critical option answers with PROP_LAST_STATUS of STATUS_UNIMPLEMENTED and does not process the request; unrecognized elective options are ignored. An administrator that receives a response carrying an unrecognized critical option treats the exchange as failed.

The 0xFF end-of-options marker is always present, since the frame follows.

Frame

Exactly one ULCP frame, extending to the end of the payload—the payload bounds it, so it carries no length prefix. The embedded frame uses the exact frame format of the local bindings, so a device dispatches it through the same machinery that serves its local link. Senders MUST set its TID bits to zero, and receivers ignore them: correlation is by token. A request whose frame is absent or cannot be parsed is answered with a CMD_PROP_IS of PROP_LAST_STATUS reporting STATUS_PARSE_ERROR.

The payload, envelope included, must fit a single UMSH frame; there is no fragmentation. The unassigned option numbers are this format’s growth space: a future need—carrying a request larger than one frame, say—is met by assigning a critical option, and existing devices already reject what they do not recognize.

Exchanges

Every interaction is an exchange: one request payload from an administrator, one response payload from the device. The device sends nothing over this binding except in response to a request—CMD_PROP_IS in its unsolicited role, and CMD_PROP_INSERTED and CMD_PROP_REMOVED as spontaneous notifications, do not occur here. State an administrator cares about is read, not pushed.

The Response echoes the token and carries one frame: exactly the frame the device would emit in reply on a local binding—a CMD_PROP_IS, CMD_PROP_INSERTED, CMD_PROP_REMOVED, CMD_PROP_ARE, or CMD_I2C_RESULT on success, or a CMD_PROP_IS of PROP_LAST_STATUS reporting the error. A request frame carrying a Device→Host command is answered STATUS_INVALID_COMMAND. Long-running operations report STATUS_IN_PROGRESS as on any binding; the administrator observes completion by reading state in a later exchange.

Multi-Property Requests

Several operations travel in one exchange through the multi-property commands, whose semantics this binding leaves untouched: CMD_PROP_MULTI_GET reads several properties, continuing past per-property failures, and CMD_PROP_MULTI_SET applies writes strictly in order, stopping at the first failure—which is how an administrator expresses writes whose effects depend on sequence. CAP_ADMIN requires CAP_CMD_MULTI, so an administrator may rely on both.

One rule is the binding’s own: the device does not execute a CMD_PROP_MULTI_SET entry whose reply entry would not fit the remaining space in the response payload, and stops there exactly as an error would stop it. An administrator that receives fewer reply entries than it sent examines the last entry it did receive: an error means the sequence stopped on that failure; a success means it stopped for space, and the administrator reissues the remainder as a new exchange.

Resets

Commands that initiate a reset—CMD_RST, CMD_RESTORE in its reset form, CMD_REBOOT, and CMD_FACTORY_RESET— are answered by no response payload. Delivery of such a command is confirmed by requesting a MAC acknowledgment, and its completion by a later exchange reading PROP_LAST_STATUS for the reset code.

A device that restarts is unreachable for as long as it takes to come back, and a repeater that restarts takes its stretch of the network with it. CMD_REBOOT is nonetheless within an administrator’s reach, because the node it is most worth sending to is the one nobody can walk to.

DFU Entry

CMD_DFU uses an ordinary request/response exchange with TID zero and the request token in the Node Management Response. A MAC acknowledgment confirms delivery only; it does not confirm DFU acceptance. The device finishes fallible preparation and persists replay-counter state before emitting STATUS_OK, then enters the bootloader after that specific response transmits. No additional wire acknowledgment is requested for the response.

A pending handoff belongs to its retained reply. Retries cannot initiate another handoff. If transmission fails, is canceled, or exceeds the completion deadline, the device remains running and replaces the retained success with a failure, so a later retry cannot falsely confirm entry. Normal administrator authorization applies; DFU preserves saved settings and credentials. The administrator stops operating on the target after confirmed entry, while its companion-radio connection remains intact.

Retries and At-Most-Once Processing

The MAC layer’s replay protection means a device never receives the same request frame twice; what it can receive twice is the same request sent twice—an administrator retransmitting because no response arrived, though the request may in fact have been executed. Executing a request that changes something twice would be wrong, so for every request other than a read the device retains, per administrator, the token and the complete response of the most recent exchange. A request whose token matches the retained token is answered by retransmitting the retained response, without executing anything.

A read (CMD_PROP_GET or CMD_PROP_MULTI_GET) changes nothing, so its response is not retained: a retransmitted read is executed again and answered with current values. The exception is a read whose response does not fit one payload. Its whole response is retained, and each fragment is cut from it (see Reading Large Values).

Each new exchange ends the one before it. When an administrator begins an exchange under a different token, the device discards that administrator’s retained entry, whether or not the new exchange is retained in turn; only a continuation carries the read it continues forward. A device MAY bound what it retains, in entries or in octets, evicting the least recently active administrator’s entry first, but retains at least the entry for the most recently active administrator.

An administrator requests a MAC acknowledgment for every request, and recovering a lost request is the MAC’s work: its retransmissions and Route Retry. An administrator MUST NOT retransmit a request whose delivery the MAC has not yet resolved, since a retransmission is a new packet that repeaters forward again. A request the MAC fails to deliver ends the exchange. A request that is acknowledged but not answered is retransmitted, identical and under the identical token, once its response is overdue for the path’s round-trip behavior. This is safe whether or not the device executed the request: a retained response is repeated, and a read is answered afresh. An administrator MUST NOT have more than one exchange outstanding with a given device.

Retained entries do not survive a reset. A reset command retransmitted after it has already acted is therefore executed again—with the same result.

Reading Large Values

A read whose response does not fit one payload is completed across several exchanges. This applies to both read requests: a CMD_PROP_GET whose value does not fit, and a CMD_PROP_MULTI_GET whose entry list does not fit. The response frame is well-formed, but its trailing content (the value of the CMD_PROP_IS, or the entry list of the CMD_PROP_ARE) is a leading fragment, accompanied by a CURSOR option: an opaque continuation handle, one to eight octets, chosen entirely by the device. The administrator continues with a new exchange, under a fresh token, whose request carries the returned cursor verbatim alongside a repeat of the request being continued. Each response carries the cursor to present in the next request; a response without one ends the read, its fragment being the last. Fragment sizes are the device’s choice, made to fill each frame; there is no fixed block size and no position numbering.

The request is executed once, by the exchange that begins the read. The device retains that complete response and answers each continuation with the next fragment cut from it, executing nothing. The reassembled value or entry list is therefore exactly what one execution produced, however the device’s state changes between exchanges.

A request carrying a CURSOR option MUST be the read being continued—the same CMD_PROP_GET or CMD_PROP_MULTI_GET that began it. A cursor on any other request is answered STATUS_INVALID_ARGUMENT.

The contract:

• A cursor is meaningful only to the device that issued it, and only for the request it was issued for. The administrator returns it byte-for-byte and MUST NOT construct or modify one.
• Fragment boundaries are the device’s choice and carry no meaning. The administrator reassembles the read by concatenating the fragments in order and parses the whole: a property value under the property’s own rules, an entry list under CMD_PROP_ARE’s.
• Presenting the same cursor again yields a fragment cut from the same response at the same position; a retransmitted continuation is in any case answered from the retained response (see Retries and At-Most-Once Processing).
• Cursors are untrusted input. The device validates every cursor it receives and answers one it cannot honor (it does not parse, it was issued for a different request, or the response it continues is no longer retained) with STATUS_CURSOR_INVALID (see Status Codes); the administrator restarts from a cursor-less request.
• A cursor is honored only while the response it continues is retained. Any other exchange from the same administrator ends the read, a fresh start of the same read included, and eviction or a reset discards it.
• A response MAY carry a REMAINING option: the approximate number of octets not yet returned, as a packed unsigned integer. It is advisory, for progress reporting.
• Between exchanges, the position lives entirely in the cursor the administrator holds; the device keeps nothing for the read beyond the retained response.

Authorization

A device executes a Node Management request only when the packet arrived by unicast or blind unicast, its source is authenticated by the MAC layer, and the source’s public key is listed in PROP_DEV_ADMINS. Everything else it drops, with accounting and without a response: an unlisted sender learns nothing about whether the device is manageable.

Administrators read everything: CMD_PROP_GET is never refused for lack of standing, and a property the device does not serve fails exactly as it would on the local link. PROP_CAPS in particular is readable, so capability discovery works exactly as on the local link.

Writes are narrower. A device answers STATUS_NOT_PERMITTED—the operation exists, and the binding is what refused it—to:

• CMD_PROP_SET, CMD_PROP_INSERT, and CMD_PROP_REMOVE naming session state or the host domain (see State Classes): that state belongs to the tethered host, and an administrator is not one. The exception is PROP_MAC_BACKHAUL: which side of the radio multiplexer the tethered host sits on is worth flipping from across the mesh, so an administrator may write it, though the host’s next attach still resets it;
• CMD_STR_SEND and CMD_QUEUE_DRAIN: the raw PHY stream and the receive queue are likewise the tethered host’s;
• writes to PROP_DEV_PRIVATE_KEY: a device identity cannot be installed over the mesh.

For everything else this binding meets the transport requirement of Provisioning Security: every executed request already arrives authenticated and encrypted from a listed administrator, so device-domain key material—channel keys, peer entries —may be provisioned remotely. The read-back rules are unchanged: key-bearing properties report their digest forms, never secrets.

PROP 4865: PROP_DEV_ADMINS

• Type: Multiple-Value
• Has Item Length Prefix: No
• Asynchronous Updates: No
• Required: CAP_ADMIN
• Item Type: 32 octets
• Post-Reset Value: Empty

Each item is the Ed25519 public key of a node authorized as an administrator of this device. Items are public keys: they carry no secret material and are reported verbatim.

An empty list disables node management entirely and is the post-reset default. The property is device-domain state: it participates in the saved snapshot like any other device-domain property, which is how a commissioned repeater stays manageable across a power cycle. It is writable over the local bindings and over this one—a listed administrator may add or remove administrators, itself included.

Capabilities

A device that does not advertise CAP_ADMIN drops Node Management payloads, with accounting.

Text Messages

![NOTE] This section is an early work in progress and this protocol may change significantly.

The text message protocol carries human-readable text between nodes (unicast) or from a node to a channel (multicast).

The payload consists of a CoAP-style option list terminated by a 0xFF byte, followed by the message body. All options are non-critical—unrecognized options are ignored and the remainder of the message is displayed normally.

Message Options

Every recognized option is a singleton unless a specification explicitly declares otherwise. How a receiver treats a duplicated recognized option depends on the option’s role:

• An option that carries identity, sequencing, or reference semantics—Message Type, Message Sequence, Regarding, Editing, and extension options in the same role such as Sender Sequence—makes the message invalid when repeated, even if the repeated values are identical. The message MUST be dropped.
• A presentation option—Sender Handle, Background Color, Text Color—keeps the first occurrence when repeated; later occurrences are ignored and MAY be reported diagnostically.
• Duplicates of a zero-length flag option—Sequence Reset, Channel Group Resend—are idempotent.

Repeated unrecognized options remain ignorable.

A recognized option whose value the receiver cannot decode is ignored, with two exceptions. A message whose Message Sequence cannot be decoded is dropped. A message whose Message Type is unrecognized or undecodable, or whose Regarding or Editing is undecodable or of the wrong width for the conversation, is not displayed, but its sequence position is accounted for as with Message Unavailable.

Message Type

If absent or empty, the message type defaults to 0 (basic text).

The presence of the Regarding option changes the semantics a bit: A reply is a type 0 message with a Regarding option specifying which message is being replied to. A reaction is a type 1 message with a Regarding option specifying which message is being reacted to; the body is a single Unicode emoji or a short text token such as +1, -1, !, or ?. Implementations may differentiate reactions from plain status text by the presence of the Regarding option.

Reaction bodies SHOULD be short text tokens rather than emoji: <3, +1, -1, ha, !, and ? cover the common reactions in one or two bytes. Receivers SHOULD accept the equivalent spellings—♥ for <3, haha or lol for ha, !! for !, letter case being insignificant—as well as the emoji themselves, and SHOULD render a reaction as a single glyph, taking the first extended grapheme cluster (UAX #29) when a body carries more, so that a sequence such as 👍🏽 or 🇫🇷 stays whole.

There are six canonical reactions:

A sender has at most one reaction in force per message. Sending another supersedes the previous one, and a reaction with a zero-length body withdraws it; a receiver displays the most recently received reaction from each sender (unless it was withdrawn).

Reactions reference the original message’s ID even when the message has since been edited, as Editing requires of every reference. A receiver MAY additionally tolerate a reaction that names an edit’s own ID by resolving it to the message that edit replaced.

A message resend request is itself not a message but a request to re-send a message that was inferred to exist but was not received. Such a request SHALL contain exactly one Message Type option with value 2 and exactly one Message Sequence option identifying the missing frame. A request with duplicate Message Type or Message Sequence options is invalid and MUST be ignored. It MAY also contain the Channel Group Resend flag described below and SHOULD NOT contain any other options. After validating the required options and the Channel Group Resend flag, receivers MUST ignore every other option and the entire body. Senders SHOULD use an empty body. The request MUST be received via unicast (for one-on-one messages) or blind-unicast (for channel messages), and SHALL be dropped if received via broadcast or multicast.

A resend request identifies exactly one missing frame, and a successful response retransmits exactly one frame. The 1-byte Message Sequence form requests a message by ID without specifying a fragment; the sender responds with the unfragmented message or, if it was fragmented, with fragment zero. The fragment count carried in fragment zero lets the requester ask for any remaining fragments individually. The 3-byte form requests one specific fragment.

Responses to a message resend request are optional and MAY be ignored.

Not all messages are available to be resent; for example, a requested message may have been deleted or evicted. In that case, the original sender SHOULD respond with Message Unavailable. A sender producing Message Unavailable SHOULD include only a Message Type option with value 3 and one Message Sequence option exactly matching the requested message or fragment. Its body SHOULD be empty.

Message Unavailable follows the delivery path appropriate to the requested conversation, just like a successful resend of the original message: direct-conversation responses use unicast, blind-unicast one-to-one channel responses use blind-unicast, and channel-group responses use multicast to the channel.

Once a receiver has unambiguously recognized Message Unavailable and its single Message Sequence option, it MUST ignore all other options and the entire body. The indicated sequence position is treated as accounted for, so it no longer remains a gap in that sender’s sequence history. The receiver is not required to render a whole-message unavailable response in the UI.

When the three-byte Message Sequence form identifies a fragment, only that requested fragment is reported unavailable, even if the sender no longer has any part of the message. Other fragments remain independently repairable. The receiver SHOULD render the unavailable portion of the partial message as unavailable rather than continuing to show it as pending.

Message Unavailable is also the standard response to a request for an unknown Message Sequence ID, including an ID that has not been sent.

Channel Group Resend

A zero-length flag used only on a Message Resend Request received by blind-unicast. Both a request for a message missed from a multicast channel conversation and a request for a message missed from a blind-unicast one-to-one conversation arrive by blind-unicast. The presence of this flag selects the sender’s archive for the multicast channel conversation. Its absence selects the sender’s archive for the blind-unicast one-to-one conversation with the requester.

A receiver MUST drop a request containing this flag if the request was not received by blind-unicast or if the option has a non-zero length. The flag has no meaning on other message types and MUST be ignored there.

Sender Handle

A UTF-8 string containing the name or pseudonym of the sender. If not supplied, a handle may be inferred from previously received node metadata for the sender’s address.

Message Sequence

Associates a packet with a monotonically increasing message identifier maintained independently for each sender within each conversation, and optionally carries fragmentation state. The option is encouraged on all messages but is not required. Messages without this option cannot be directly referenced in replies or reactions.

The option value is either 1 byte or 3 bytes:

1-byte form (message ID only):

3-byte form (fragment):

Rules:

• Message IDs are monotonically increasing per sender within each conversation, wrapping at 255. A one-to-one blind-unicast conversation and the group conversation on the same channel are distinct conversations with independent sequence streams, even though they share channel key material.
• When an ID wraps and is reused, the older message with that ID in the same conversation-and-sender stream is retired: it is no longer a valid target for Regarding, Editing, or a resend request in that stream. Retirement does not affect any other stream or already-displayed history.
• Messages smaller than MTU-32 bytes SHOULD NOT be fragmented.
• A fragment body carries at most 160 bytes, and a message has at most 10 fragments; senders MUST NOT exceed either limit. Larger fragment bodies and larger fragment counts are nevertheless syntactically valid; a receiver that will not reassemble such a message drops the assembly and MAY account for the ID as unavailable rather than leaving a gap.
• Fragmentation splits the body at byte boundaries. An individual fragment body is not required to be valid UTF-8; the reassembled body is validated as UTF-8 only after every fragment is present.
• Options from the first fragment (Fragment Index 0) apply to the entire reassembled message. Subsequent fragments MUST NOT include options that would override those of the first fragment, and any such options MUST be ignored by the receiver.
• During reassembly, missing fragments SHOULD be rendered as [FRAGMENT MISSING], or an appropriately-localized equivalent. When a fragment boundary splits a UTF-8 code point, rendering discards the incomplete code point on each side of the gap; the substituted marker is part of the rendered display, not the message body.
• Out-of-order reassembly SHOULD be supported for fragments received within a reasonable amount of time (thirty seconds to two minutes).
• Edits (see Editing) carry their own message IDs and MUST NOT be referenced by subsequent Editing or Regarding options. The original message ID is the stable reference.

Ordering, Gaps, and Automatic Repair

Message IDs compare using serial-number arithmetic modulo 256. Relative to the most recent ID accepted from a sender in a conversation, a forward delta of 1 through 127 is newer; a delta of 128 through 255 is old or ambiguous.

A forward delta greater than 1 within one conversation-and-sender stream means messages are missing from that stream. A gap in one sender’s stream says nothing about any other sender in the conversation. After a short reordering grace period, a receiver MAY request each missing message with a resend request using the 1-byte Message Sequence form, subject to the limits below:

• Automatic repair is bounded: a receiver SHOULD NOT automatically request more than 8 missing messages from a single observed gap, and SHOULD apply per-peer and overall rate limits to all generated resend requests.
• A forward delta greater than the receiver’s automatic-repair bound, an ambiguous delta, the first message observed from a sender, and the first message after a Sequence Reset all establish a new baseline. Receivers MUST NOT generate automatic resend requests to backfill across a baseline.
• Repair of a channel-group conversation requires addressing a blind unicast to the original sender, which requires that sender’s full public key. A member holding only the source hint cannot construct the request and simply renders the loss.
• In a channel-group conversation every member observes the same loss at nearly the same moment. Receivers MUST delay each automatic group repair request by an independently randomized interval, and MUST cancel a pending request when the missing message—or a Message Unavailable naming it—arrives on the channel before the request is sent.
• Room conversations are unicast; room repair requests are sent directly to the room without group jitter, and responses repair only the requester.

A repaired message occupies its position in sequence order within the sender’s stream, not the position at which it happened to arrive. A receiver MAY reserve that ordered position when the gap is first observed—rendering a pending-gap placeholder there while a repair is outstanding—and fill the same position in place when the message arrives, rather than appending it at the end of the transcript. A message that fills a reserved position after later messages are already displayed MAY be marked as having arrived late. A gap whose repair is ultimately exhausted, expired, or disclaimed by the sender MAY be presented as an unavailable position rather than silently removed.

When a message is delivered in fragments, a receiver SHOULD raise any user-facing notification once the final fragment is received, or once a bounded latency (on the order of thirty seconds) has elapsed since the first fragment—whichever comes first—so a stalled reassembly still notifies without waiting for the full reassembly lifetime.

Sequence Reset

A 0-byte flag option that signals the sender has reset its message ID counter for the current conversation—for example, after losing that conversation’s persistent sequence state. Receivers SHOULD discard cached message context for this sender in this conversation, including pending fragment reassembly state. State for the same sender in other conversations is unaffected.

The Sequence Reset option SHOULD accompany a Message Sequence option bearing the sender’s new starting ID. In the absence of a Message Sequence option, receivers SHOULD treat the next message from that sender as starting a fresh sequence.

Reset announcement is lazy and scoped to the affected conversation: the sender includes the flag on the next message it actually sends in that conversation. Senders do not transmit standalone reset messages preemptively to conversations they are not otherwise sending to.

Regarding

References a previously sent message for the purposes of replies and reactions.

The option length depends on the conversation, not on how the MAC packet is addressed:

• One-to-one conversation (unicast, or a blind-unicast conversation with a single logical destination): 1 byte—the Message ID of the referenced message.
• Channel-group conversation (delivered by multicast to the channel): 4 bytes—the 1-byte Message ID followed by the first 3 bytes of the source public key of the original sender.

The source prefix is necessary in multicast channels to disambiguate messages from different senders that may share the same Message ID. This means a message cannot be referenced if it is more than 255 messages old in that sender’s sequence, or if the user has since reset their sequence ID.

In chat rooms, the room assigns canonical Message IDs across all senders (see Chat Rooms), so the 1-byte form is used and no source prefix is needed.

Editing

Indicates that this message replaces a previously sent message in the same conversation and sender scope. The option value is 1 byte: the Message ID of the message being edited. No source prefix is needed because the source scope comes from the enclosing packet. For unicast and blind-unicast, pairwise authentication binds that source to a peer key. For multicast, the MIC proves only possession of the channel key; the source is a claimed identity, and one channel member can impersonate another. A multicast whose frame signature verifies is the exception: the signature binds it to the signer’s key.

An edit with a zero-length body signals deletion of the original message.

For as long as a client retains sequence history for an edited or deleted message, it SHOULD retain the stable original-message identity or a tombstone so that references can still be resolved. A client MAY retain prior revision content, including deleted content, for edit-history display; this is a local storage and privacy policy rather than a protocol requirement.

Edit messages carry their own Message IDs. References in subsequent Editing or Regarding options MUST use the original message’s ID, not the edit’s ID.

Once a message has been edited or deleted, its superseded content MUST NOT be retransmitted: a resend request naming the original Message ID is answered with the current content re-issued under that ID, or with Message Unavailable—never with the pre-edit bytes. This obligation is durable; it survives restarts of the sending node. Retaining superseded content locally for the sender’s own review remains permitted, per the retention note above.

A receiver holding an unrepaired gap at an edited message’s original ID MAY treat an arriving edit that references it as satisfying that gap—the edit already carries the position’s current content—and cancel the pending repair rather than requesting content the sender is no longer willing to send.

How edits are presented to users is implementation-defined. Implementations typically display only the most recent edit, with some indication that edits exist, and an optional mechanism to view edit history.

Background Color

Three bytes (red, green, blue) specifying a suggested background color for the text bubble. Receivers may ignore this option. If supported, implementations should ensure adequate contrast with the text color.

Text Color

Three bytes (red, green, blue) specifying a suggested text color. Receivers may ignore this option. If supported, implementations should ensure adequate contrast with the background color.

Padding

The padding option is used to add padding to a message to obfuscate the true length of the message. All instances of this option and their values SHALL be ignored by the receiver.

Message Body

The message body is a UTF-8 string.

Channel Invitations

A basic text message whose entire body, ignoring leading and trailing whitespace, is a channel URI invites its recipients to that channel. A receiver that recognizes the URI MAY present the message as an invitation to join; one that does not displays the body as text.

Test Messages

A basic or status text message on the EMERGENCY channel is a test message when its body, ignoring leading whitespace, begins with TEST: in any ASCII letter case. For a fragmented message, the body of fragment zero decides.

Unless the user has opted in to test messages, a receiver SHOULD NOT raise any alert for a test message: no sound, vibration, notification, screen wake, or unread indication. The message is still stored and displayed.

Chat Rooms

![NOTE] This section is an early work in progress and this protocol may change significantly.

A chat room is a special node that provides limited store-and-forward capability for text messages and potentially other types of data. Chat rooms may be polled or can push updates to joined members.

Action Types

The first byte of the payload identifies the action type.

Regular message exchange—including system events—does not use a dedicated action type. Users send messages to the room as plain text message payloads by unicast, and the room distributes them to each member by separate unicast transmissions. Chat rooms do not use multicast. Action types are reserved for room management operations. Room Update (action 8) is used only for batch history delivery and is also delivered by unicast.

Get Room Info / Room Info

A user may send a Get Room Info action to a room node without being logged in. The room responds with a Room Info action containing CoAP-option-encoded metadata:

If the options are terminated with a 0xFF byte, the remainder of the response is a UTF-8 description of the room.

Login

The login payload is CoAP-option-encoded:

All options are optional. Behavior details:

• If a last-message timestamp is provided and more than 10 messages have been received since then, only the 10 most recent are sent automatically. Older messages MAY be retrieved with Fetch Messages, if stored.
• If the room is password-protected but already recognizes the user’s public key, the password is ignored. A room may forget a public key after prolonged inactivity, requiring a password on the next login.
• First-time logins must include the full 32-byte public key (S flag set).

Logout

Logging out unsubscribes the user from push updates and removes them from the active user list. Previously sent messages remain stored and retrievable by other users up to the history limit.

If the user is currently logged in, the room sends a final text message to all members using the User Left message type (see System Events).

Send Message

To send a message to a chat room, a user sends a standard text message unicast to the room node. The Sender Handle option is ignored—the room fills it in from the sender’s registered handle when distributing the message to members.

The Message Sequence option SHOULD be included, using the sender’s own sequence for its conversation with this room. The room uses this to detect duplicate submissions and to order rapid messages from the same user. This sender-assigned ID is separate from the canonical room-assigned ID that the room assigns when distributing the message.

Fetch Messages

Retrieves previous messages posted to the room, which may include system messages.

Fetch Users

Retrieves the currently active user list, possibly including their public keys.

Admin Commands

TBD.

Message Distribution

When the room receives a message from a user, it assigns a monotonically increasing canonical Message Sequence ID from a single room-wide counter and distributes the message to each logged-in member as a separate unicast text message. System events (user join/leave, admin messages) are distributed the same way, using room-specific message types. This gives the room a single unified message ordering across all activity—a Regarding option referencing a room message ID is unambiguous without a source prefix (see Regarding).

All timestamps are managed by the room and are relative to its own clock—typically a UTC UNIX timestamp, though accuracy depends on whether the room’s clock is synchronized.

Sender Sequence

When the room echoes a message back to the original sender, it faces a correlation problem: the sender showed the message optimistically in their UI the moment they sent it, but the echoed copy arrives with a room-assigned ID the client has never seen. Without some way to link them, the client cannot reliably identify which pending outbound message the echo corresponds to—matching by content alone fails if the user sends identical messages in quick succession.

To solve this, the room includes a Sender Sequence option on the echo it sends back to the original sender. This option is not included in copies sent to other members.

The Sender Sequence value is the per-sender Message Sequence ID the user included in their outbound message. The client matches this value against its pending outbound messages to identify the echo. It then retains both wire identities on the same local message record: the sender-assigned ID and the canonical room-assigned Message Sequence ID carried by the echo. Room-wide Regarding references use the canonical room-assigned ID. When the original sender submits an edit or deletion of its own message to the room, its Editing option uses the original sender-assigned ID so that the room can correlate the update before redistributing it with the appropriate canonical reference.

System Events

The room delivers system notifications as text messages to all logged-in members, using message types reserved for room use:

The Sender Handle option is automatically populated by the room for all distributed messages, including system events.

Room Update

Room Update is used exclusively for batch delivery: the history sent on login (via the Last Message Timestamp login option) and the response to Fetch Messages. It contains a list of length-prefixed text messages in chronological order, each carrying the room-injected options defined above (Timestamp Received, and Sender Sequence where applicable). This batching avoids the per-packet overhead of sending history as individual unicast messages on LoRa.

URI Formats

UMSH defines URI forms for nodes, channels, and CoAP resources.

Node URIs

Nodes are identified by their 32-byte public key encoded in Base58.

Example:

umsh:n:HJC9DJaaQEn88tAzbMM7BrYbsepNEB69RK1gZiKEYCPp

Node identity information may optionally be appended after a colon, encoded in a suitable representation of the identity structure and optional signature.

Example:

umsh:n:HJC9DJaaQEn88tAzbMM7BrYbsepNEB69RK1gZiKEYCPp:Rgx5U993cN52iHc9rPEFPpLTB66o2JLaDvSpCxmhPdReNd3QtrYcyrACdWV89L1xfZPJz4rZGeHX9BypGtDDYJXbDrWKJZixp9A8d3qcDNFq

This allows a node identity bundle to be embedded in a QR code.

Channel URIs

Internally, channels are identified by a 32-byte shared key.

Example direct-key URI:

umsh:ck:5BFn8YGKJ6pZR4qV3tW7mNhDrXsCxEaL9kUv2wAjT8bP

Additional metadata may be attached as URI parameters:

umsh:ck:5BFn8YGKJ6pZR4qV3tW7mNhDrXsCxEaL9kUv2wAjT8bP?n=MyPrivateChannel;mh=6;r=Eugene

Where, for example:

• n = channel name
• mh = recommended maximum flood hops
• r = recommended region

A channel may also be identified by a string from which the channel key is derived:

umsh:cs:public

The name that follows umsh:cs: is canonicalized before key derivation: it is percent-decoded, required to be ASCII, and folded to lowercase (see Named Channels). Because of the fold, umsh:cs:public, umsh:cs:Public, and umsh:cs:PUBLIC all identify the same channel.

CoAP-over-UMSH URIs

CoAP resources on a node use the coap-umsh scheme, with the node public key as the authority component.

Example:

coap-umsh://HJC9DJaaQEn88tAzbMM7BrYbsepNEB69RK1gZiKEYCPp/data/1

Local Control Protocol (ULCP)

![NOTE] This section is an early work in progress and this protocol may change significantly.

The UMSH Local Control Protocol (ULCP) is the interface between a UMSH device—hardware that owns a physical transceiver and runs always-on firmware—and a host such as a phone, tablet, laptop, or small computer that configures or uses it over a local out-of-band link. The device is not merely a dumb modem, but it is also not normally the primary home of the user’s long-term UMSH identity.

This chapter describes the architecture: what the device and host each are, where the security boundary sits, and which responsibilities belong to each side. The protocol itself is specified in the chapters that follow:

• Framing and Common Semantics defines the frame format, the command grammar and property model, the classes of state a device holds, and the status, reset, and capability registries
• one chapter per subsystem, each defining its own capabilities, commands, and properties: Radio Control, Frame Transport, Device Domain, Saved State, Tethered Host Services, Wi-Fi, IP Connectivity, Bridge Client, IP Multicast, and I2C Bus Access
• Minimum Requirements states what a device has to implement to be a ULCP device, and the Command and Property Index locates every numeric identifier
• ULCP over BLE binds the protocol to BLE GATT; serial transports (UART, USB-CDC) use HDLC-Lite framing
• Node Management carries the same grammar over the mesh itself, letting an authorized administrator reach a device’s device domain in-band, with no local link at all

One protocol serves every deployment of a device; the familiar deployment names describe configuration, not distinct firmware:

• a companion radio is a device tethered to a host that owns the user’s long-term identity—the device owns the physical LoRa transceiver, and it may also host a local device-owned node for management and diagnostics
• a repeater is a device commissioned over the same protocol and then left to run autonomously, forwarding traffic with no host attached

This differs from systems where the radio itself is the user’s primary mesh identity. In UMSH, the user-facing identity usually lives on the host device, not in the radio.

That separation has important consequences:

• the device does not hold the user’s long-term private key
• the host device remains the authority for user identity, contacts, and high-level application behavior
• the device may still perform some limited actions while disconnected if the host has provisioned the necessary state in advance

Identities

A device deals with at most two node identities:

The Device Identity

The device hosts a node that belongs to the device itself. This node exists even when no phone is attached and can be used for:

• in-band management
• diagnostics
• repeater or bridge behavior
• announcing the presence or capabilities of the device
• on a device with a messaging interface of its own, the messaging identity of whoever carries it

By default, such a node need not advertise itself with ordinary beacons. Its private key is either generated on the device itself (preferred) or installed once by the host; it is never readable back over the ULCP link. The host can read the corresponding public key at any time.

The device identity, its channel keys, its peer list, and the device’s own settings (RF configuration, and eventually repeater policy, positioning, and advertisement behavior) form the device domain: state that belongs to the device and survives a change of host.

The Tethered Host Identity

A phone or computer attaches to the device and uses it as its radio interface. The host’s UMSH identity remains on the host: the device learns only the identity’s public key, forwards traffic for it, and may cache narrowly scoped related state (channel keys, per-peer symmetric keys, queued inbound frames).

ULCP supports exactly one tethered host identity at a time. A host application that manages multiple user identities is expected to select one for the device to assist; it can still send and receive traffic for others through the raw frame stream while attached.

Everything provisioned for the host identity—its public key, channel keys, peer keys, filters, and queued inbound traffic—forms the host domain: state that is keyed by the host identity and wiped wholesale when a different host identity takes over the device. Pairing the device with a new phone therefore starts the host state over cleanly while leaving the device’s own identity and settings untouched.

Operating Modes

Tethered

In tethered mode, a host device uses the device almost as though it were a local hardware peripheral. This is the most direct mode and is expected to be the common case for phones. It is the mode the ULCP protocol chapters specify, and a device deployed this way is a companion radio.

Tethered mode supports:

• radio configuration
• raw UMSH frame transmit and receive
• receive filtering so the host is not woken for irrelevant traffic
• optional offline assistance when the host disconnects

Bridged

In bridged mode, the device behaves more like an infrastructure service. One or more nearby devices may submit traffic through it, or it may forward traffic on their behalf subject to local policy, without being the primary owner of the identities using it.

Bridged mode is useful for:

• a fixed radio shared by multiple users in one location
• a site gateway that extends range for nearby devices
• deployments where the host device is intermittent but the radio remains on

Bridged mode should not be confused with tethered ULCP. Tethering is one host talking to its own companion radio over a local control link. Bridging is a separate local access problem in which nearby devices are treated more like peers or clients of the device itself. Bridging is not yet specified; see BLE As A Local Bearer for the design space.

Hybrid Use

A real device may use both modes at once. For example, a phone is tethered for its user’s personal traffic while the device’s own local node remains available for management. ULCP therefore must not assume exclusivity.

Two Kinds of Attach

A host on the ULCP link is doing one of two things, and the difference is not a mode of the device but a description of the host’s intent. The device does not track it; the host knows which it means and confines itself accordingly.

Tethered attach. The host is this device’s host. It writes PROP_HOST_KEY, provisions the host domain—channel keys, peer keys, receive filters, delegation policy—and thereafter the device filters, queues, and acknowledges on its behalf. A device serves at most one tethered host at a time, and being tethered is a transient local relationship: it does not appear in the device’s node identity, does not survive a power cycle, and is re-established on every attach.

Administrative attach. The host is configuring the device: its own identity, its radio, its behavior, its saved snapshot. It writes nothing in the host domain. This is what commissioning a repeater is, and it is the normal relationship for any device that is not somebody’s radio.

The rule that follows is short: configuring a device’s device domain MUST NOT claim its host domain. One phone administering ten repeaters must not write PROP_HOST_KEY on any of them—it would make each repeater start filtering and queueing for a host that has no intention of coming back, and would displace whatever host the repeater was actually serving.

Nothing in the protocol distinguishes the two: a host that has reached the link can do either (see ULCP over BLE). The distinction belongs in host implementations, which SHOULD make it explicit rather than incidental—an administrative handle that refuses host-domain writes cannot commit this error by accident.

Security Boundary

The fundamental rule is:

A device must not be provisioned with private keys owned by another device.

In particular, the host device keeps ownership of its own long-term and ephemeral private keys. This keeps the device from becoming an alternate trust anchor for the user’s identity and reduces the impact of device compromise, theft, or firmware bugs.

However, the device may still be provisioned with some additional keying material, depending on what offline behavior is desired.

Material That May Be Provisioned

A host may choose to provision the device with:

• multicast channel keys
• pairwise symmetric keys derived for specific peers
• receive filters tied to specific identities, hints, or packet classes

Material That Must Not Be Provisioned

ULCP must not provide a mechanism for provisioning:

• any private key owned by the host device

Material That Should Generally Be Avoided

Implementations should also avoid provisioning:

• broad contact databases unrelated to radio operation

Why Provision Keys At All?

If the device does not have the host’s private key, it cannot perform fresh ECDH on the host’s behalf. That means it cannot derive new pairwise state for previously unknown peers by itself.

Nevertheless, there are useful cases where the host may deliberately preload symmetric key material for specific already-known peers and channels:

• Pairwise peer keys let the device authenticate inbound secure traffic from those peers and send MAC acks on the host’s behalf while the host is asleep or disconnected, so that senders’ retransmission logic is satisfied.
• Channel keys let the device recognize multicast traffic on the host’s channels—and, importantly, blind unicast traffic addressed to the host, whose destination and source addresses are concealed under the channel key (see Blind Unicast Packet). Without the channel key the device cannot even tell such traffic is for the host.

This does not grant the device the full power of the host’s identity. It only grants limited capability for the specific peers and channels that were provisioned. Provisioning Security specifies the exact mechanism and its security consequences.

Subsystems

The interface divides into nine subsystems, each specified by its own chapter and each discoverable through the capabilities it advertises. Only the first two are unconditional.

Radio Control

The host configures the physical radio link, through an interface that is not LoRa-specific in shape where that can be avoided—different radios have different parameter sets. The host can:

• configure frequency, bandwidth, spreading factor, coding rate, power, and similar link parameters where applicable
• query device capabilities and current active configuration
• observe radio health and diagnostics
• observe and limit transmit duty cycle

Frame Transport

The host uses the device as a transport for UMSH frames:

• transmit of raw complete UMSH frames
• receive of raw complete UMSH frames, with RSSI/SNR receive metadata
• transmit result indications

This keeps the layering clean: the ULCP link carries UMSH frames, not re-encoded UMSH semantics. One practical consequence is that the host can also communicate with the device’s own local UMSH node using ordinary UMSH frames sent over this stream, rather than requiring a separate bespoke message path for such traffic.

Device Domain

The radio’s own node identity and the settings that make it behave the way its operator commissioned it: its keys and peers, its name, its repeater switch, what it advertises about itself on the mesh, and its battery telemetry. This is what a host writes when it is administering a device rather than being that device’s host.

Saved State

The device can snapshot its device-domain configuration to non-volatile storage and restore it at boot, which is what lets a radio come back after a power cut still configured and still forwarding with nobody attached.

Tethered Host Services

Receive filtering, inbound queueing, key provisioning, and acknowledgement delegation: the work a device does on behalf of the host identity it is serving.

A major value of a companion radio is letting the host sleep while the device stays awake. For that, the device filters—implicitly from the provisioned host identity and channel keys, explicitly by destination hint, channel identifier, or packet type—so it only wakes the host when a frame is relevant. While the host is disconnected it may also be asked to buffer inbound frames until the host asks for them, and to send MAC acks for peers whose pairwise keys were provisioned.

These remain tightly scoped: the device is assisting the host, not impersonating it in the general case. Outbound traffic is deliberately not queued—a transmit either happens or fails while the host is attached to observe the result.

Wi-Fi

The 802.11 hardware some devices carry alongside the LoRa radio, in three functions the host configures separately: scanning for access points, joining a network as a station, and offering one as an access point. Each is its own capability, because a tracker whose transceiver sniffs beacons for geolocation can scan and can do nothing else.

IP Connectivity

Addressing on whichever link the device has: DHCP or a static configuration per family, the addresses and routers in effect, and the resolvers. One capability per family, and nothing in it knows what the link is.

Bridge Client

The device’s own node connected to an internet bridge over IP: where to connect, which server key to trust, whether the client is enabled, and what state the connection is in.

IP Multicast

The device’s own node joined to an IP multicast group: whether it is enabled, which multicast group it joins, how many frames from the network it takes, and whether it has joined.

I2C Bus Access

Raw transactions with the device’s I2C peripherals, for bring-up and diagnosis: the buses and known peripherals the device names, one transaction per command with its read data in the reply, and a scan of who acknowledges. The device’s own drivers keep the bus between commands.

Suggested Capability Matrix

The table below summarizes which side owns which function.

Low-Power Expectations

A companion radio is especially useful when the host processor should remain asleep most of the time. The architecture supports:

• the device remaining awake while the host sleeps
• filtering, acknowledgement, and queueing happening on the device side
• host wakeup only when relevant traffic arrives
• reconnect and drain of queued frames without losing radio continuity

This fits well with the broader UMSH design goal that devices should wait on real events rather than spin in polling loops.

Protocol Shape

ULCP is a single transport-independent protocol, inspired by the framing discipline of Spinel but with a UMSH-specific command and property namespace. The same frames run over:

• UART / USB-CDC serial, using HDLC-Lite framing
• BLE, using the GATT frame transport of ULCP over BLE
• a local socket between processes on one host, using HDLC-Lite framing
• any other reliable, ordered, flow-controlled local transport

The key structural ideas:

• lightweight binary framing with a one-byte header and small transaction identifiers, allowing up to seven in-flight host commands
• properties for simple state—a change is confirmed by publication of the new authoritative value, and asynchronous state changes use the same publication form
• streams for packet-like flows such as raw UMSH frames, which are not modeled as state
• unsolicited notifications share the grammar of solicited responses

Framing and Common Semantics defines the wire format and the grammar every device implements; the subsystem chapters layer configuration and assistance features on top of it without changing the framing or the version.

Whatever the transport, ULCP is a privileged interface: an attached host commands transmission with arbitrary content, timing, and power, and provisioning moves real key material onto the device. On serial transports this is protected by physical possession, and on a local socket by access to the socket; the BLE binding specifies an equivalent barrier (see Security), and key provisioning must never be carried over a transport that provides less.

BLE As A Local Bearer

If BLE is used for more than tethering, it should be treated as a separate local bearer concept rather than an extension of ULCP.

Two broad BLE directions are relevant:

• connection-oriented tethering, where one host talks directly to one radio over a local link
• connectionless or mesh-style local participation, where multiple nearby devices can observe, relay, or respond

The first case is what ULCP is about. The second case is a different design problem.

For clarity:

• tethered ULCP means “my host talks to my radio”
• BLE local bearer means “nearby devices can discover and use this radio or exchange nearby UMSH-related traffic over BLE”

The first is point-to-point control and framing. The second is local network access.

Plausible BLE Building Blocks

BLE does have modes that are closer to local ad-hoc participation than ordinary GATT tethering:

• ordinary LE advertising for one-to-many broadcast
• periodic advertising for scheduled connectionless broadcast
• Periodic Advertising with Responses (PAwR) for scheduled broadcast with slotted responses
• Bluetooth Mesh, which defines an advertising bearer and a GATT bearer

These are the main reasons it is reasonable to think BLE could support a small local access or bridge protocol. In particular:

• ordinary advertising can announce the presence, capabilities, and service class of a nearby radio
• periodic advertising can provide a more structured broadcast schedule for status or downlink announcements
• PAwR is notable because it adds scheduled responses, making it one of the clearer BLE building blocks for a low-rate shared local uplink/downlink model
• Bluetooth Mesh is relevant less as a complete stack to adopt wholesale and more as proof that the Bluetooth ecosystem already recognizes both advertising-bearer and GATT-bearer styles of participation

Practical Payload Size Considerations

Not all BLE bearers are equally suitable for carrying complete UMSH frames.

For the tethered ULCP case, GATT is attractive partly because its payload sizes are large enough to be practical for whole-frame carriage. In BLE, an attribute value may be up to 512 octets, which in practice corresponds to the familiar “ATT MTU up to 517 bytes” figure once ATT overhead is included. That is comfortably in the range needed for ULCP.

Advertising-oriented bearers are different. Their payloads are much smaller, and they should therefore be treated as:

• discovery bearers
• short-message bearers
• or fragmented local bearers

rather than assumed to be “GATT, but connectionless.”

As a practical rule of thumb:

This suggests a clean split:

• if the goal is host-to-device tethering, prefer GATT first and L2CAP CoC where available—this is what ULCP over BLE specifies
• if the goal is nearby-device participation over BLE, assume the bearer is constrained and design for small messages or fragmentation from the outset

That BLE local bearer would need its own answers for questions such as:

• how nearby devices discover an available bridge or repeater
• how access is authorized
• whether traffic is connectionless, connection-oriented, or mixed
• whether the bearer only tunnels complete UMSH frames or also exposes local service messages
• how buffering, fairness, and airtime limits are handled when several nearby clients share one radio

Bluetooth Mesh is particularly notable because the Bluetooth SIG already defines an advertising bearer and a GATT bearer, with Proxy nodes bridging between them. That architecture is conceptually similar to what a UMSH device may eventually want: one mode for direct tethered interaction and another for local many-to-many participation. At the same time, adopting Bluetooth Mesh itself would mean adopting a substantial stack, not just borrowing the bearer idea.

Open Questions

The following items remain intentionally open:

• how much application-layer filtering is appropriate before violating layer separation
• whether and how the device’s own node should announce itself
• the design of a bridged / local-bearer mode, including whether bridged clients may provision keys or only use pre-provisioned shared services

Summary

A companion radio should be understood as a UMSH radio service with optional delegated capabilities, not as the default owner of the user’s identity. The host keeps authority over long-term identity, while the device contributes:

• always-on physical connectivity
• receive filtering and low-power wake support
• inbound buffering and delegated acknowledgement for provisioned peers
• optional narrowly scoped offline assistance

That split preserves UMSH’s cryptographic model while still making small, low-power, phone-connected radios practical.

ULCP: Framing and Common Semantics

This chapter defines the ULCP wire format and the semantics every device implements whatever else it supports: the frame layout, the command grammar, the property model, the classes of state a device holds, how a host attaches and synchronizes, and the numeric registries for status codes, reset codes, and capabilities. The subsystem chapters that follow build on it.

ULCP is inspired by the Spinel protocol from OpenThread, but it is not Spinel and does not aim for wire compatibility with it. The protocol assumes reliable, in-order delivery of frames, as well as a way to assert flow control. The framing mechanism depends on the underlying transport:

• Asynchronous serial links (UART, USB-CDC) use HDLC-Lite, exactly as used by Spinel.
• BLE uses the GATT frame transport defined in ULCP over BLE.
• A reliable, in-order byte stream standing in for a serial link—a TCP connection to a bridged port, say—uses the same HDLC-Lite framing.
• A local stream socket between two processes on one host—a Unix domain socket—uses HDLC-Lite as well; see Local Sockets.

In this chapter, the device is the side that owns the transceiver and the host is the side that attaches to it over the local link (see Local Control Protocol).

The protocol version is 6.0. Which subsystems a device implements is discovered through PROP_CAPS, never through the version number; see Minimum Requirements for what a device is required to implement in order to be a ULCP device at all.

Data Representation

Spinel, being a low-level protocol between two devices which are likely to have a little-endian architecture, uses little-endian representations exclusively for all integers smaller than four bytes. For implementation convenience, values larger than four bytes (EUI64, IPv6 addresses, etc.) are stored as they are traditionally represented (typically, but not always, big-endian).

Packed Unsigned Integers

Certain types of integers, such as command or property identifiers, usually have a value on the wire that is less than 127. However, in order to not preclude the use of values larger than 255, we would need to add an extra byte. Doing this would add an extra byte to all packets, which can add up in terms of bandwidth. To address this, Spinel uses Packed Unsigned Integers, or PUIs.

The PUI format used in Spinel is based on the unsigned integer format in EXI, except that we limit the maximum value to the largest value that can be encoded in three bytes. The maximum value that can be encoded is 2,097,151.

For all values less than 127, the packed form of the number is simply a single byte which directly represents the number. For values larger than 127, the following process is used to encode the value:

1. The unsigned integer is broken up into n 7-bit chunks and placed into n bytes, leaving the most significant bit of each byte unused.
2. Order the bytes from least-significant to most-significant. (Little-endian)
3. Clear the most significant bit of the most significant byte. Set the most significant bit on all other bytes.

Where n is the smallest number of 7-bit chunks you can use to represent the given value.

Take the value 1337, for example:

1337 => 0x0539
     => [39 0A]
     => [B9 0A]

To decode the value, you collect the 7-bit chunks until you find a byte with the most significant bit clear.

Frame Format

A ULCP frame is the concatenation of the following elements:

• A header comprising a single byte.
• A command identifier.
• A command-defined payload, which may be empty.

  0                   1                   2                   3
 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|     HEADER    |  COMMAND ID   | PAYLOAD ...
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

Figure: Structure of a typical ULCP frame

Since the size of the frame is part of the framing mechanism, it is omitted from the frame.

Frame Header

Each frame has the following format:

  0   1   2   3   4   5   6   7
+---+---+---+---+---+---+---+---+
|  FLG  | RESERVED  |    TID    |
+---+---+---+---+---+---+---+---+

Figure: Header Format

FLG: Flag

The Flag (FLG) field in the two most significant bits of the header byte is always set to the value two (or 10 in binary). Any frame received with these bits set to any other value SHALL NOT be considered a ULCP frame.

RESERVED: Reserved

These three bits must always be set to zero and the entire frame ignored if set to any other value. They may be assigned a meaning (such as an interface identifier) in a future version of this protocol.

TID: Transaction Identifier

The Transaction Identifier (TID) field in the three least significant bits of the header is used for correlating responses to the commands which generated them. This allows for up to seven host-issued commands to be in flight at once.

When a command is sent from the host, any reply to that command sent by the device will use the same value for the TID. When the host receives a frame that matches the TID of the command it sent, it can easily recognize that frame as the actual response to that command.

The zero value of TID is used for commands to which a correlated response is not expected or needed, such as for unsolicited update commands sent to the host from the device.

Note that while the frame format is symmetric between the frames being sent to the device versus frames being sent from the device, the behaviors are not. The device MUST NOT send a frame with a non-zero TID that is not a response to a frame it had recently received with that same TID. All unsolicited or asynchronous commands originating from the device MUST use TID zero (0).

Command ID

The command identifier is a 7-bit unsigned integer encoded from 0 to 127. The most significant bit is not set and the frame must be ignored if it is set.

Payload

The command payload follows the command identifier in a ULCP frame, containing the serialization of any arguments that the indicated command may require. The exact composition of a command payload is determined by the specific command identifier being used and MUST be empty if the command has no arguments.

Commands

This chapter defines the commands that operate on the protocol itself— resets, liveness, and the property grammar. The remaining commands are defined with the subsystem they act on: CMD_STR_SEND and CMD_STR_RECV in Frame Transport, CMD_QUEUE_DRAIN in Tethered Host Services, CMD_ANNOUNCE in Device Identity, the four state-management commands in Saved State, and the three bus-access commands in I2C Bus Access. The complete numeric allocation is in the Command and Property Index.

The multi-property commands (21–23) are gated by CAP_CMD_MULTI, CMD_REBOOT, CMD_DFU, and CMD_FACTORY_RESET by CAP_REBOOT, CMD_ANNOUNCE by CAP_ADVERT, and the bus-access commands (25–27) by CAP_I2C (see Capabilities); everything else is unconditional.

CMD 0: (Host -> Device) CMD_NOP

 0                   1
 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|1 0| RES | TID |    CMD_NOP    |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
^     HEADER    ^    COMMAND    ^

Figure: Structure of CMD_NOP

No-Operation. Commands the device to reply with a STATUS_OK code. This is primarily used for liveness checks.

The command payload for this command SHOULD be empty. The receiver MUST ignore any non-empty command payload.

There is no error condition for this command.

CMD 1: (Host -> Device) CMD_RST

 0                   1
 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|1 0| RES | TID |    CMD_RST    |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

Figure: Structure of CMD_RST

Reset device. Commands the device to perform a software reset. Due to the nature of this command, the TID is ignored. The host should instead wait for a CMD_PROP_IS command from the device indicating PROP_LAST_STATUS has been set to STATUS_RESET_SOFTWARE (see Status Codes).

The command payload SHOULD be empty, and it SHOULD NOT be processed.

If an error occurs, the value of the emitted PROP_LAST_STATUS will be set accordingly to the status code for the error.

CMD 2: (Host -> Device) CMD_PROP_GET

  0                   1                   2                   3
 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|1 0| RES | TID |      CMD      | PROP_KEY (PUI, 1-3 bytes) ...
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

Figure: Structure of CMD_PROP_GET

Get property value. Commands the device to emit a CMD_PROP_IS command for the given property identifier.

The payload for this command is the property identifier encoded in the packed unsigned integer format described in Packed Unsigned Integers.

If an error occurs, the value of the emitted PROP_LAST_STATUS will be set accordingly to the status code for the error.

CMD 3: (Host -> Device) CMD_PROP_SET

  0                   1                   2                   3
 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|1 0| RES | TID |      CMD      | PROP_KEY (PUI, 1-3 bytes) ...
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|  NEW PROPERTY VALUE ...
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

Figure: Structure of CMD_PROP_SET

Set property value. Commands the device to set the given property to the specific given value, replacing any previous value, and to emit a CMD_PROP_IS command for that property indicating the new authoritative value if successful.

The payload for this command is the property identifier encoded in the packed unsigned integer format described in Packed Unsigned Integers, followed by the property value. The exact format of the property value is defined by the property.

If an error occurs, the value of the emitted PROP_LAST_STATUS will be set accordingly to the status code for the error.

The value reported by that CMD_PROP_IS need not be the value written: a device that adjusts a write to what it can honor reports the result, and that result is the property’s value. A write fails only by way of PROP_LAST_STATUS—a differing value is a successful write, not a rejected one.

CMD 4: (Host -> Device) CMD_PROP_INSERT

  0                   1                   2                   3
 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|1 0| RES | TID |      CMD      | PROP_KEY (PUI, 1-3 bytes) ...
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|  ITEM VALUE ...
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

Figure: Structure of CMD_PROP_INSERT

Insert item into property. Commands the device to add the given item to the given multi-value property, and to emit a CMD_PROP_INSERTED command for that property if successful.

The payload for this command is the property identifier encoded in the packed unsigned integer format, followed by exactly one item encoded in the property’s item form (see Multi-Value Properties). The item is not preceded by a length prefix, regardless of whether the property uses item length prefixes in its multi-item value form; the framing layer bounds the item.

If the item is already present the command fails with STATUS_ALREADY, except where a property defines replacement semantics for matching items (see, e.g., PROP_HOST_PEER_KEYS). If the property exists but is not a multi-value property, the command fails with STATUS_INVALID_ARGUMENT.

If an error occurs, the value of the emitted PROP_LAST_STATUS will be set accordingly to the status code for the error.

CMD 5: (Host -> Device) CMD_PROP_REMOVE

  0                   1                   2                   3
 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|1 0| RES | TID |      CMD      | PROP_KEY (PUI, 1-3 bytes) ...
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|  ITEM SELECTOR ...
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

Figure: Structure of CMD_PROP_REMOVE

Remove item from property. Commands the device to remove the item matching the given selector from the given multi-value property, and to emit a CMD_PROP_REMOVED command for that property if successful.

The payload for this command is the property identifier encoded in the packed unsigned integer format, followed by an item selector. Each multi-value property documents its selector form; unless stated otherwise it is the full item value.

If no matching item is present, the command fails with STATUS_ITEM_NOT_FOUND. If the property exists but is not a multi-value property, the command fails with STATUS_INVALID_ARGUMENT.

If an error occurs, the value of the emitted PROP_LAST_STATUS will be set accordingly to the status code for the error.

CMD 6: (Device -> Host) CMD_PROP_IS

  0                   1                   2                   3
 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|1 0| RES | TID |      CMD      | PROP_KEY (PUI, 1-3 bytes) ...
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|  CURRENT PROPERTY VALUE ...
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

Figure: Structure of CMD_PROP_IS

Property value notification. This command can be sent by the device in response to a previous command from the host, or it can be sent by the device in an unsolicited fashion to notify the host of various state changes asynchronously.

The payload for this command is the property identifier encoded in the packed unsigned integer format described in Packed Unsigned Integers, followed by the current value of the given property.

CMD 7: (Device -> Host) CMD_PROP_INSERTED

  0                   1                   2                   3
 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|1 0| RES | TID |      CMD      | PROP_KEY (PUI, 1-3 bytes) ...
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|  REPORTED ITEM ...
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

Figure: Structure of CMD_PROP_INSERTED

Item-inserted notification. Sent by the device in response to a successful CMD_PROP_INSERT (with the TID of that command), or unsolicited with a TID of zero when the device adds an item to a multi-value property for its own reasons.

The payload is the property identifier followed by the inserted item as the device reports it (see Multi-Value Properties)—never in a form containing key material.

CMD 8: (Device -> Host) CMD_PROP_REMOVED

  0                   1                   2                   3
 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|1 0| RES | TID |      CMD      | PROP_KEY (PUI, 1-3 bytes) ...
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|  REPORTED ITEM ...
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

Figure: Structure of CMD_PROP_REMOVED

Item-removed notification. Sent by the device in response to a successful CMD_PROP_REMOVE (with the TID of that command), or unsolicited with a TID of zero when the device removes an item from a multi-value property for its own reasons.

The payload is the property identifier followed by the removed item as the device reports it.

CMD 16: (Host -> Device) CMD_REBOOT

 0                   1
 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|1 0| RES | TID |  CMD_REBOOT   |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

Figure: Structure of CMD_REBOOT

Restart the device. Commands the device to power-cycle its hardware, keeping every piece of state it has persisted: the saved snapshot, the device identity, the pairing PIN, and all bonds survive, and the device comes back configured as it was.

This differs from CMD_RST, which returns protocol state to its post-reset values with the device still running, and from CMD_FACTORY_RESET, which erases that state before restarting. Between the three, this is the one that changes nothing—it is how a host clears a condition the protocol cannot name.

The command payload SHOULD be empty and MUST be ignored. A device that restarts sends no response: the reboot drops the transport link, and the TID is therefore irrelevant. A host treats the ensuing disconnect (and the device’s subsequent reappearance announcing STATUS_RESET_POWER_ON) as completion, and MUST NOT wait for a PROP_LAST_STATUS.

This command is only available on devices advertising CAP_REBOOT. A device without it answers STATUS_UNIMPLEMENTED—which is the only response this command ever produces, and the only thing that distinguishes a device that declined from one that is already restarting.

CMD 17: (Host -> Device) CMD_DFU

Enter the platform’s bootloader for a firmware update. The payload is empty or one UINT8 selecting the DFU method:

An empty payload selects Default. The default is fixed by the platform, independent of the command’s transport. XIAO nRF52 and SenseCAP Solar use BLE; T-Echo, T1000-E, and Wio Tracker L1 use UF2. Other mode values are undefined. Entering the bootloader is a restart into it, so this command is only available on devices advertising CAP_REBOOT; a device without it answers STATUS_UNIMPLEMENTED. There is no discovery property for the methods; the device decides whether its supported bootloader can enter the requested mode.

The device answers with CMD_PROP_IS(PROP_LAST_STATUS):

Other failure statuses report preparation failures and leave the application running. Before returning success, the device MUST complete all fallible preparation, including persisting replay-counter state. It MUST NOT enter DFU until the complete matching response has transmitted. Queue acceptance alone is insufficient. Failed, canceled, or expired response transmission MUST leave the application running and invalidate the pending action and any retained success response. Completion of another response, or of an earlier transport generation, MUST NOT authorize entry.

A direct request MUST use a nonzero TID. A direct TID-zero request records STATUS_INVALID_ARGUMENT without entering DFU. Over Node Management, the TID is zero and the ordinary token-correlated response confirms acceptance. This command does not use reset-command acknowledgment semantics.

DFU entry preserves saved configuration, identity, bonds, and pairing credentials. Unsaved application state is lost. Existing administrative authentication and authorization apply. Bootloader residency and exit behavior are bootloader-defined; automatic return to UMSH is not promised. The command enters DFU only and does not transfer or install firmware.

A host MUST report success only upon receiving STATUS_OK. Timeout or disconnect before that response leaves entry unconfirmed and MUST NOT cause an automatic new DFU command. Hosts SHOULD warn that the device may remain inaccessible indefinitely, and that BLE updating requires an updater within Bluetooth range. Older firmware’s STATUS_INVALID_COMMAND is treated as unsupported. This additive command does not change the protocol version.

CMD 21: (Host -> Device) CMD_PROP_MULTI_GET

  0                   1                   2                   3
 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|1 0| RES | TID |      CMD      | PROP_KEY (PUI) | PROP_KEY ...
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

Figure: Structure of CMD_PROP_MULTI_GET

Get several property values at once. Commands the device to reply with a single CMD_PROP_ARE carrying one entry for each requested property, in request order.

The payload is one or more property identifiers, each encoded in the packed unsigned integer format, one after another with no delimiters.

Fetching continues past failures: a property that cannot be fetched occupies its position in the reply as a PROP_LAST_STATUS entry whose value is the status code a CMD_PROP_GET of that property would have produced. Position, not the entry’s key, identifies which request an entry answers.

This command is available only on devices advertising CAP_CMD_MULTI. On any other device it is an unrecognized command, STATUS_INVALID_COMMAND.

Battery diagnostics define a shared acquisition group: when a device implements those properties, supported battery readings within one multi-get use one acquisition pass, including duplicate keys. This does not make other properties atomic or imply simultaneous hardware measurements.

CMD 22: (Host -> Device) CMD_PROP_MULTI_SET

  0                   1                   2                   3
 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|1 0| RES | TID |      CMD      | ENTRY | ENTRY | ENTRY ...
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

Figure: Structure of CMD_PROP_MULTI_SET

Set several property values in order. The payload is a sequence of entries, each the combined length of its key and value encoded as a packed unsigned integer, followed by that many octets—the property identifier as a packed unsigned integer, then the value:

+--------------+---------------------------+--------------------+
| LENGTH (PUI) | PROP_KEY (PUI, 1-3 bytes) | VALUE (remainder)  |
+--------------+---------------------------+--------------------+

Figure: CMD_PROP_MULTI_SET Entry Format

The device applies each entry exactly as a CMD_PROP_SET of that property would, strictly in payload order, stopping at the first entry that fails. Mutation Atomicity applies to each entry alone: the sequence is not a transaction, and a failure partway leaves the earlier entries applied.

The reply is a single CMD_PROP_ARE containing, for each applied entry in order, the property and its reported value— exactly what the CMD_PROP_IS answering a lone CMD_PROP_SET would carry—and, for the failing entry, a PROP_LAST_STATUS entry carrying the error, after which the reply ends. Entries past the failure are not executed and contribute nothing; a reply whose every entry is a success covers the entire request.

This command is available only on devices advertising CAP_CMD_MULTI. On any other device it is an unrecognized command, STATUS_INVALID_COMMAND.

CMD 23: (Device -> Host) CMD_PROP_ARE

  0                   1                   2                   3
 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|1 0| RES | TID |      CMD      | ENTRY | ENTRY | ENTRY ...
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

Figure: Structure of CMD_PROP_ARE

Multiple property value notification. The payload is a sequence of entries in the same encoding as CMD_PROP_MULTI_SET: a combined key-and-value length as a packed unsigned integer, the property identifier, and the value as the device reports it—under the same reporting rules as CMD_PROP_IS, so key material never appears (see Multi-Value Properties).

The device emits this command only in response to CMD_PROP_MULTI_GET or CMD_PROP_MULTI_SET, with the TID of that command. It MUST NOT be emitted unsolicited: asynchronous updates use CMD_PROP_IS and its companions, one property at a time.

CMD 24: (Device -> Host) CMD_SESSION_RESET

  0                   1                   2
 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|1 0| RES | TID |      CMD      |     REASON
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

Figure: Structure of CMD_SESSION_RESET

The device has discarded session state, so every session-scoped property is back at its documented default under a host that did not ask for it. The TID MUST be zero: the frame is always unsolicited.

REASON is a packed unsigned integer. It is diagnostic—a host’s obligation is the same for every value:

Unassigned values are reserved. A host MUST treat an unrecognized reason as a session reset it does not have a name for, never as a parse failure.

A device MUST emit this command whenever it discards session state while a host is attached, and MUST NOT emit it when no host is attached: a detach discards session state with nobody to tell.

The frame MUST be emitted before any frame belonging to the new session, so a host can tell which session anything it receives came from. The completion of the command that caused the discard belongs to the exchange that requested it and MAY precede the notice; a CMD_RST is answered by its STATUS_RESET_SOFTWARE and then the notice. Where a session is instead created by the host’s own first frame, nothing has been answered yet and the notice comes first.

The command MUST NOT be emitted over the administrative binding. It concerns the local tethered session; an administrator over the mesh is not party to it, and the binding carries only what was asked for.

A host MUST tolerate the frame at any time while attached. On receiving it, a host MUST re-establish anything it holds in session state and SHOULD otherwise resynchronize as it would on a fresh attach (see Attach, Detach, and Synchronization).

This is deliberately not a reset code, and MUST NOT disturb PROP_LAST_STATUS. The two report different losses: STATUS_RESET_POWER_ON means the host domain went with the session and must be reprovisioned in full, whereas a session reset means only session state went. A reboot implies a session reset, so recording the narrower fact over the broader one would lose the distinction that governs recovery.

Properties and Streams

A property is a piece of device state with a value the host can read and, where the property allows it, write. A stream is a packet-like flow that is not modeled as state; streams share the property identifier space and are carried by their own commands (see Frame Transport).

Note

The properties marked as supporting Is means that the property may be emitted asynchronously. All properties that support Get or Set will emit an Is to respond with the current/new value of that property.

A multi-value property marked as supporting Inserted or Removed may likewise emit those asynchronously, reporting one item the device added or dropped for its own reasons rather than the whole value. A host that tolerates an unsolicited Is must tolerate these as well.

Multi-Value Properties

A multi-value property holds an unordered set of items rather than a single value. PROP_CAPS is one, and is constant; the key, peer, and filter tables of the device and host domains are mutable ones.

The host writes items (CMD_PROP_SET, CMD_PROP_INSERT) in the property’s item form. When the device reports items (CMD_PROP_IS, CMD_PROP_INSERTED, CMD_PROP_REMOVED), it reports them exactly as written—except where the item form contains symmetric key material. Such a property documents its reported form instead: the entry with its key material omitted, or a value derived from it (a channel key is reported as its derived channel identifier), so that secrets can never be read back (see Provisioning Security).

The commands valid on a mutable multi-value property are:

• CMD_PROP_GET—the device replies with CMD_PROP_IS whose value is the concatenation of all items as reported. If the property is documented as having an item length prefix, each item is preceded by its length in octets encoded as a packed unsigned integer; properties whose reported items are fixed-size omit the prefix.
• CMD_PROP_SET—replaces the entire contents with the items encoded in the value, each in item form (with the same length-prefix rule). Setting an empty value clears the property. Success is reported with a CMD_PROP_IS carrying the new complete value as reported.
• CMD_PROP_INSERT / CMD_PROP_REMOVE—add or remove one item, as defined above.

Hosts manipulating large tables SHOULD prefer Insert/Remove over whole-table Set, since a full table may not fit comfortably in one frame on all transports.

Mutation Atomicity

State-changing operations in this protocol are transactional and fail closed:

• The device MUST validate a complete request before changing any state. A whole-table CMD_PROP_SET whose value contains any invalid item fails without applying any of it.
• Whole-table replacement is atomic: no observer of device behavior (frame filtering, acknowledgement decisions) sees a mixture of the old and new contents.
• Operations that include durable writes—CMD_SAVE, CMD_CLEAR, installing or generating the device identity, and setting PROP_BLE_PAIRING_PIN—MUST NOT report success before the durable write has completed.
• On any failure, the prior live and durable state remains unchanged, and the device MUST NOT emit CMD_PROP_IS, CMD_PROP_INSERTED, or CMD_PROP_REMOVED notifications describing a partially applied change.
• Host replacement is atomic in the same sense: at no point may the device operate with a mixture of the old and new hosts’ keys, filters, or policy. It involves no durable write, so it cannot fail partway.

Atomicity is per operation, not per sequence. Establishing a host domain is several property writes, and an interruption between them leaves a mixture of old and new—bounded by the fact that a host-key change resets the domain first and a reboot empties it. A host repairs this the same way it provisions in the first place: by writing everything again.

Core Properties

These properties exist on every device and are not gated by any capability.

PROP 0: PROP_LAST_STATUS

• Type: Single-Value, Read-Only
• Asynchronous Updates: Yes
• Required: REQUIRED
• Value Type: PUI + STRING(opt.)
• Units: Enumeration
• Post-Reset Value: Reset Reason Code

This property describes the status code of the last device operation. For many commands, failure is indicated by emitting CMD_PROP_IS for this property with a TID matching the failing command. It is generally not necessary to ever fetch the value of this property explicitly, as it is often emitted directly as an error response. It is also occasionally emitted as a success response with a value of STATUS_OK.

Upon device reset, this property MUST be emitted with a status code indicating the reset reason.

Upon receiving an asynchronous update to PROP_LAST_STATUS with a status code that indicates a reset, the host SHALL assume that the device has been reset and that all properties have reverted to their defined after-reset values.

See Status Codes for the complete list of status codes.

PROP 1: PROP_PROTOCOL_VERSION

• Type: Single-Value, Constant
• Asynchronous Updates: No
• Required: REQUIRED
• Scope: Device
• Value Type: UINT8, UINT8
• Post-Reset Value: 6, 0

Describes the ULCP version information. This property contains two fields:

  0                   1
 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| MAJOR_VERSION | MINOR_VERSION |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

Figure: PROP_PROTOCOL_VERSION Value Format

MAJOR_VERSION

The major version number is used to identify backward incompatible differences between protocol versions.

MINOR_VERSION

The minor version number is used to identify backward-compatible differences between protocol versions. A mismatch between the advertised minor version number and the minor version that is supported by the host SHOULD NOT be fatal to the operation of the host.

This document describes major version 6, minor version 0 of this protocol.

PROP 2: PROP_DEV_VERSION

• Type: Single-Value, Constant
• Asynchronous Updates: No
• Required: REQUIRED
• Scope: Device
• Value Type: STRING
• Post-Reset Value: Implementation-Specific

Contains a zero-terminated ASCII string which describes the firmware currently running on the device.

The value of this string MUST be different for every firmware release.

The format of the string is not strictly defined, but it is intended to present similarly to the “User-Agent” string from HTTP. The following format is RECOMMENDED:

STACK-NAME/STACK-VERSION[BUILD-INFO][; OTHER-INFO][; BUILD-DATE]

The hardware the firmware is running on belongs in PROP_DEV_MODEL, not here.

PROP 3: PROP_INTERFACE_TYPE

• Type: Single-Value, Constant
• Asynchronous Updates: No
• Required: REQUIRED
• Scope: NLI
• Value Type: PUI
• Units: Enumeration
• Post-Reset Value: Implementation-Specific

This unsigned packed integer identifies the network protocol implemented by this device. It must return the value 8.

PROP 4: PROP_DEV_MODEL

• Type: Single-Value, Constant
• Asynchronous Updates: No
• Required: OPTIONAL
• Scope: Device
• Value Type: STRING
• Post-Reset Value: Implementation-Specific

Contains a zero-terminated ASCII string naming the hardware model the device is, such as Seeed SenseCAP T1000-E. Where PROP_DEV_VERSION describes the firmware a device runs, this describes the thing it runs on, and the two change independently: the same firmware release covers several models, and a model outlives every release built for it.

Firmware built for one specific board SHOULD implement this. A device whose hardware has no fixed identity—a simulator, or an implementation that runs on whatever it is compiled for—SHOULD omit the property rather than return an empty or invented string. A host MUST treat a refused get as “this device does not name its hardware” and continue.

The value SHOULD name the product as its vendor does, so that a host can match it against an external hardware description. It is intended for display and for lookup, and is deliberately not an identifier: a host that needs to make decisions based on what a device can do has PROP_CAPS for that.

PROP 5: PROP_CAPS

• Type: Multiple-Value, Constant
• Has Item Length Prefix: No
• Asynchronous Updates: No
• Required: REQUIRED
• Scope: NLI
• Item Type: PUI
• Units: Enumeration
• Post-Reset Value: Implementation-Specific

Describes the supported capabilities of this device. Encoded as a list of packed unsigned integers. See Capabilities for a list of values.

PROP 6: PROP_UPTIME

• Type: Single-Value, Read-Only
• Asynchronous Updates: No
• Required: OPTIONAL
• Scope: Device
• Value Type: UINT32
• Units: Seconds
• Post-Reset Value: 0

Seconds elapsed since the device last booted, truncated toward zero. A device that runs long enough to exhaust the range saturates rather than wrapping, so the value never falsely reports a recent restart.

This dates what PROP_LAST_STATUS describes: the reset code says why the device last started, and this says how long ago. Read together they distinguish a node that came up cleanly weeks back from one that is restarting under a fault and reporting the same code each time.

Only a power cycle or a genuine restart resets it. CMD_RST returns protocol state to its post-reset values without rebooting the device, and MUST NOT reset this property; neither does a host attaching or detaching.

A device with no monotonic clock to answer from SHOULD omit the property rather than report a fabricated value. A host MUST treat a refused get as “this device does not report its uptime” and continue.

State Classes

Every piece of device state belongs to exactly one of three classes. The classes determine what survives a host attach, a change of host, and a power cycle.

Session State

State that exists only while a host is attached: transaction (TID) correlation, transport reassembly buffers, and the session-scoped properties PROP_MAC_PROMISCUOUS and PROP_MAC_BACKHAUL. Session state is reset to defaults on every attach. Resetting it never affects radio operation.

Device Domain

State that belongs to the device itself, independent of which host is attached:

• the device identity keypair (independently persisted; never part of the saved snapshot—see Saved State)
• the device identity’s channel keys (PROP_DEV_CHANNEL_KEYS) and peer list (PROP_DEV_PEERS)
• the RF configuration (PROP_PHY_*), including PROP_PHY_ENABLED, and the duty-cycle limit
• the human-readable device name (PROP_DEV_NAME)
• live battery telemetry (PROP_BATTERY), when CAP_BATTERY is present
• device behavior settings (property identifiers 70–95): the repeater forwarding switch (PROP_MAC_REPEATER_ENABLED), with the rest of the range reserved for future definition (further repeater policy, positioning, periodic advertisement of the device identity, and similar)
• the administrator list (PROP_DEV_ADMINS) authorizing node management over the mesh
• transport configuration such as PROP_BLE_PAIRING_PIN

The RF configuration is deliberately device-domain: a site repeater keeps its frequency and regulatory limits no matter which phone pairs with it. An attached host may still reconfigure it at any time.

Host Domain

State that belongs to the currently configured tethered host identity:

• PROP_HOST_KEY itself
• the host’s channel keys and peer keys
• the receive filter table and acknowledgement-delegation policy
• the inbound queue: its configuration and its contents

The host domain is volatile across a power cycle, and only across a power cycle. It MUST NOT be persisted: it is not part of the saved snapshot, and at power-on every host-domain property takes its documented default.

It emphatically does survive a disconnect. A detached radio keeps filtering, queueing and acknowledging on behalf of its host for as long as it stays powered—that is the entire value of the host domain, and nothing about the host going out of range changes what the host wants done.

The two together give the host a simple rule with no detection in it: a host MUST establish its complete host domain on every tethered attach, writing every part of it rather than reasoning about what the device already holds. Key material cannot be compared anyway—the key tables never read it back (see Provisioning Security), so a peer’s pairwise keys can be replaced without changing anything the host can observe. Where the device is already provisioned as asked, the rewrite is redundant; that is preferable to depending on a signal that would also have to cover partial provisioning, another administrator’s intervention, and future device behavior. A boot generation or reset indication MAY be used to skip the rewrite as an optimization, never to decide whether it is needed.

Property Allocation

Property and stream identifiers are allocated by state class and subsystem:

Unassigned identifiers in these ranges are reserved. The identifiers in use are listed in the Command and Property Index.

Attach, Detach, and Synchronization

How attach and detach are detected is defined by the transport binding:

• BLE—enabling/disabling notifications on Frame Out, as specified in ULCP over BLE.
• USB-CDC—assertion and deassertion of DTR on the ULCP interface.
• TCP—establishment and closure of the connection.
• Local socket—establishment and closure of the connection.
• Bare UART—implementation-defined. A device with no way to detect host presence MAY treat the host as permanently attached, in which case it never enters detached operation and offline assistance (Inbound Queueing, Acknowledgement Delegation) is unavailable on that transport.

On attach, the device MUST reset session state (see State Classes) and MUST NOT modify the device or host domains in any way. In particular, the PHY is not disabled and no property outside session state changes value. The device MUST NOT emit any frame before attach; the first frame of the session is the CMD_SESSION_RESET announcing the session state the attach discarded, with reason 0, and the attach itself produces no other unsolicited notification.

Because attach no longer implies any known default state, the host synchronizes by fetching, not by assuming. The following post-attach procedure is RECOMMENDED:

1. CMD_PROP_GET for PROP_LAST_STATUS. If it returns a reset code (see Reset Codes), the device has reset since the last host command, so any state that is not restored from saved state (notably queue contents) has been lost.
2. CMD_PROP_GET for PROP_HOST_KEY. An empty value is the ordinary case after a power cycle—the host domain does not survive one—and the host simply provisions. A value matching the host’s own identity means its provisioning is still live from before the disconnect. Any other value means another host has taken the radio over since this host last attached; the queue and provisioning belong to that identity, and this host must decide whether to take the radio over (see Host Replacement) before doing anything else.
3. CMD_PROP_GET for the device-domain properties the host depends on (PROP_SAVED, the PROP_PHY_* configuration), and for PROP_HOST_RX_QUEUE_COUNT.
4. Establish the complete host domain (see Host Domain): write PROP_HOST_KEY, the key tables, the filter table and the delegation policy in full. The key tables are read back only to find entries the host no longer wants, which it removes; entries it does want are written whether or not the device reports them, since key material is not readable and so cannot be compared.
5. Issue CMD_QUEUE_DRAIN when actually ready to process backlogged traffic.

More generally, a host MUST tolerate unsolicited CMD_PROP_IS, CMD_PROP_INSERTED, and CMD_PROP_REMOVED notifications at any time while attached, updating its view of the affected property accordingly: device state can change for reasons the host did not initiate, and publication of the new authoritative value is how the protocol reports that.

A request from another binding is one such reason. Whatever a request changes, the device MUST publish to everyone else listening—an attached host, and the device’s own interface— whether the request came from one of them or from a Node Management administrator. Each property the answer reports goes out unsolicited, one at a time, as the answer reported it; the status that closes the request goes to the requester alone. This holds for every property: a property’s Asynchronous Updates entry describes the changes the device makes for its own reasons. A fire-and-forget request (TID 0) on a local binding is not answered, and what it changes need not be published.

The same applies to CMD_SESSION_RESET, which reports the one change no property notification can: the session itself starting over. A host that receives one runs this procedure again.

On detach, the device discards session state, keeps operating with the current device- and host-domain state, and begins detached operation: accepted frames are queued rather than delivered, and acknowledgement delegation (if enabled) becomes active.

Local Sockets

A device that runs as a process—a virtual radio hosted beside the application that attaches to it—may serve ULCP on a local stream socket, such as a Unix domain socket:

• Framing: HDLC-Lite, as on a serial link.
• Attach and detach: a connection opening is an attach, and its closing is a detach.
• One host at a time: a new connection replaces the current one, which the device closes first. A host that went away without closing never holds the device against its successor.
• Security binding: access to the socket. The device MUST place the socket where the operating system lets only the processes entitled to the device reach it—a file in a directory private to those processes—which stands in for physical possession.

The Device’s Own Interface

A device with a settings interface of its own—a screen and keyboard, or a menu—may administer its own session in process, with the commands a host uses. The interface is a binding of its own:

• Authority. Whoever is holding the device has physical possession, which is a serial link’s security binding (see Provisioning Security). The interface may provision key material, the device identity’s private key included.
• Reach. The device domain. Session state, the host domain, the raw PHY stream, and the receive queue belong to whichever host is tethered, and the device answers the interface’s writes to them with STATUS_NOT_PERMITTED, as it answers an administrator’s.
• A local binding. The device answers every request that carries a non-zero TID exactly once.
• Not an attach. Its requests reset no session state, emit no CMD_SESSION_RESET, and displace no attached host.
• Publications. The interface hears everything the device publishes, whether or not a host is attached, including what an attached host or an administrator changes. What the interface changes reaches an attached host the same way (see Attach, Detach, and Synchronization).

What the interface changes is saved as anything set at the device is (see Changes Made at the Device).

Provisioning Security

Provisioning moves real key material onto the device, within the limits of the security boundary: channel keys and per-peer symmetric keys—and the device identity’s own private key— but never the host’s private key. The rules:

• All symmetric key material, and the device identity private key, is write-only. CMD_PROP_GET and all device-emitted notifications report key-bearing properties without their secrets (see Multi-Value Properties): peer public keys without K_ENC/K_MIC, derived channel identifiers instead of channel keys, and never the device private key. This holds for both identities’ key tables. These read-backs let the host verify what is provisioned after a reconnect without any secret ever crossing the link a second time— which matters because more than one host may be able to attach over the radio’s lifetime (transport bonds are possession credentials, not identity credentials), and a later host must not be able to extract an earlier host’s keys.
• Commands that carry key material—CMD_PROP_SET and CMD_PROP_INSERT for the key tables, and any set of PROP_DEV_PRIVATE_KEY—MUST NOT be carried over a transport that does not meet the requirements of the transport’s security binding: physical possession for serial transports, access to the socket for a local socket, or an encrypted bonded LESC link as specified in ULCP over BLE.
• A compromised or stolen device exposes the provisioned channels, the provisioned pairwise conversations, and its own device identity, but cannot impersonate the host to any new peer, cannot sign as the host, and cannot decrypt traffic for peers or channels that were never provisioned.
• Hosts SHOULD provision the minimum useful set of peers and channels, SHOULD remove entries that are no longer needed, and SHOULD prefer on-device generation of the device identity over installing one.
• A device advertising CAP_SAVE MUST store persisted key material in the most protected storage available to it.

Status Codes

Status codes are used for PROP_LAST_STATUS. When a command generates a status code, it is returned via a CMD_PROP_IS with a property of PROP_LAST_STATUS and the TID of command it is referring to.

STATUS_OK

Indicates that the operation has completed successfully.

STATUS_FAILURE

Indicates that the operation has failed for an unspecified reason. The use of this status code SHOULD be avoided. If a more specific status code exists that better explains the failure, then that status code MUST be used instead.

STATUS_UNIMPLEMENTED

Indicates that the given operation has not been implemented.

STATUS_INVALID_ARGUMENT

Indicates that an argument to the given operation is invalid. The value may be out of range or improperly formatted. This status code is also returned when setting an invalid value to a property.

STATUS_INVALID_STATE

Indicates that the given operation is invalid for the current state of the device.

STATUS_INVALID_COMMAND

The given command id is not recognized.

STATUS_INTERNAL_ERROR

An internal runtime error has occurred.

STATUS_PARSE_ERROR

An error has occurred while parsing the command.

STATUS_IN_PROGRESS

Indicates that the operation was started but has not completed, and completion will be reported asynchronously.

STATUS_NOMEM

The operation has been prevented due to memory pressure.

STATUS_BUSY

The device is currently performing a mutually exclusive operation. This status differs from STATUS_INVALID_STATE in that it will resolve spontaneously.

STATUS_PROP_NOT_FOUND

The given property key is not recognized.

STATUS_ALREADY

The requested state is already in effect; in particular, the item passed to CMD_PROP_INSERT is already present in the property.

STATUS_ITEM_NOT_FOUND

The item or selector passed to CMD_PROP_REMOVE does not match any item in the property; or the value written by a CMD_PROP_SET names an item of another property that does not exist, as a write of PROP_WIFI_NETWORK names an entry of the known-network table. It is distinct from STATUS_INVALID_ARGUMENT because a host acts on it differently: the value is well-formed and the item it names has merely to be created first.

STATUS_CURSOR_INVALID

The cursor presented in a Node Management continuation is not one the device can honor—it does not parse, it was issued for a different request, or the response it continues is no longer retained. The administrator restarts the read from an initial, cursor-less request.

STATUS_NOT_PERMITTED

The property or command exists, but the binding the request arrived over is not allowed to perform it—in particular, a Node Management write to a property reserved to the tethered host. Distinct from STATUS_PROP_NOT_FOUND and STATUS_INVALID_COMMAND: the operation would be accepted from a binding with the standing to ask.

STATUS_CHANNEL_NOT_FOUND

The request names a channel by its channel identifier and the device holds no channel key that derives it. Distinct from STATUS_ITEM_NOT_FOUND, which concerns an item of the property being written, and from STATUS_INVALID_ARGUMENT: the value is well formed, and the channel has only to be provisioned first (PROP_DEV_CHANNEL_KEYS).

STATUS_NO_DEVICE

An I2C transfer was addressed to a peripheral that did not acknowledge its address: nothing answered on the bus. Distinct from STATUS_ITEM_NOT_FOUND, which is the bus itself not being one the device offers.

STATUS_NACK

The peripheral acknowledged its address but refused a data octet of the transfer. Operations before the refused one have completed.

STATUS_BUS_ERROR

The bus failed under the transaction: arbitration was lost, a bus error or overrun occurred, a line stayed stuck, or the transaction outlasted the device’s deadline. The device may attempt bus recovery.

STATUS_CCA_FAILURE

The packet was not sent due to a CCA failure. This status code is only emitted when sending data to a packet stream with a TID other than zero.

STATUS_DUTY_LIMIT

The packet cannot be sent because it would exceed the currently set duty-cycle limit.

Reset Codes

All status codes which fall into the inclusive range of 112-127 are considered reset codes. These codes are emitted asynchronously after a device reset and provide a way to differentiate different causes of resets. If the first command the host sends to the device after a reset is to fetch PROP_LAST_STATUS, then the reset code MUST be returned.

Note

On a device holding a saved snapshot, the post-reset value of every saved property is its saved value rather than the documented default. A host MUST NOT assume that a reset implies documented factory defaults; it should fetch or explicitly set the properties it depends on. Without a snapshot the documented post-reset values apply unconditionally.

Of these defined reset codes, only STATUS_RESET_POWER_ON, STATUS_RESET_EXTERNAL, STATUS_RESET_SOFTWARE, and STATUS_RESET_RESTORED are emitted during normal operation. All other reset codes generally indicate some sort of software bug or hardware failure.

Unexpected or unrequested resets are always an indication of a problem, no matter what the code value is.

A session reset is not one of these. Discarding session state costs the host what it established there and nothing more, so it is announced by CMD_SESSION_RESET and leaves PROP_LAST_STATUS alone. Every reset code above implies a session reset; none of them is implied by one.

STATUS_RESET_POWER_ON

Cold power-on start.

STATUS_RESET_EXTERNAL

External device reset. This is generally caused by RESET pin on the device being asserted.

STATUS_RESET_SOFTWARE

Software-requested orderly reset. This is generally caused by the host sending the device CMD_RST.

STATUS_RESET_RESTORED

Protocol reset into the saved snapshot, emitted when a device completes CMD_RESTORE in its reset form (see CMD_RESTORE). Unlike the other reset codes, this one does not indicate a hardware or firmware restart: the transport link and attach state survive it.

STATUS_RESET_CRASH

Unrecoverable software execution failure, like a segmentation fault or a stack overflow.

STATUS_RESET_ASSERT

Software invariant property not respected.

STATUS_RESET_OTHER

Unspecified cause.

STATUS_RESET_UNKNOWN

Failure while recovering cause of reset.

STATUS_RESET_WATCHDOG

Watchdog timer expired, forcing a reset.

Capabilities

Capabilities are how a device can advertise support for specific behaviors and functionalities. They can be fetched via the PROP_CAPS property.

Each capability is defined by the chapter that specifies the behavior it grants:

A device MUST NOT advertise a capability without also advertising the capabilities it requires. Apart from the multi-property commands, which CAP_CMD_MULTI gates, CMD_REBOOT, CMD_DFU, and CMD_FACTORY_RESET, which CAP_REBOOT gates, CMD_ANNOUNCE, which CAP_ADVERT gates, and the bus-access commands, which CAP_I2C gates, the commands and status codes defined in this chapter are unconditional and need no capability; a device that defines no mutable multi-value properties simply has nothing to apply CMD_PROP_INSERT/CMD_PROP_REMOVE to.

ULCP: Radio Control

Radio control is the subsystem the host uses to configure and observe the physical transceiver: frequency, modulation, transmit power, and the transmit duty-cycle budget. Every ULCP device implements it.

The interface is deliberately not LoRa-specific in shape where that can be avoided. The properties that any radio has—enable, frequency, transmit power, RSSI, MTU—are unconditional; the LoRa modulation parameters are gated behind CAP_PHY_LORA, and duty-cycle accounting behind CAP_PHY_DUTY_LIMIT. Traffic counters are exposed by CAP_STATS.

The RF configuration is device-domain state: it belongs to the radio rather than to whichever host is attached, it is part of a saved snapshot, and it survives a change of host.

Capabilities

Properties

PROP 32: PROP_PHY_ENABLED

• Type: Single-Value, Read/Write
• Asynchronous Updates: No
• Required:
  • CMD_PROP_GET: REQUIRED
  • CMD_PROP_SET: REQUIRED
• Scope: NLI
• Value Type: BOOL
• Post-Reset Value: 0 (false)

Set to 1 if the PHY is enabled, set to 0 otherwise. Enabling the PHY bypasses nothing: a device with a node of its own brings up whatever that node is configured to do, forwarding included.

PROP 35: PROP_PHY_FREQ

• Type: Single-Value, Read-Write
• Asynchronous Updates: No
• Required: REQUIRED
• Scope: NLI
• Value Type: UINT32_LE
• Units: kHz
• Post-Reset Value: Unspecified

Value is the radio frequency (in kilohertz) of the current channel.

PROP 37: PROP_PHY_TX_POWER

• Type: Single-Value, Read-Write
• Asynchronous Updates: No
• Required: REQUIRED
• Scope: NLI
• Value Type: INT8
• Units: dBm
• Post-Reset Value: Implementation-Specific

Value is the radio transmit power in dBm.

A device MUST clamp a written value to the range its radio can reach rather than rejecting it, and the emitted CMD_PROP_IS carries the clamped value. Nothing else publishes that range, so this is how a host discovers it: a host that needs to know what a device will actually transmit at reads the value it gets back rather than the one it wrote.

PROP 38: PROP_PHY_RSSI

• Type: Single-Value, Read-Only
• Asynchronous Updates: No
• Required: REQUIRED
• Value Type: INT8
• Unit: dBm (RF Power)
• Post-Reset Value: Unspecified

Value is the current RSSI (Received Signal Strength Indication) from the radio. This value can be used in energy scans and for determining the ambient noise floor for the operating environment.

Zero dBm represents one milliwatt of power.

Sampling ambient RSSI requires the radio to be actively receiving. If PROP_PHY_ENABLED is false, getting this property fails with STATUS_INVALID_STATE. A get may also fail with STATUS_FAILURE if the radio cannot service the read (for example, mid-reconfiguration).

PROP 39: PROP_PHY_LORA_BW

• Type: Single-Value, Read-Write
• Asynchronous Updates: No
• Required: CAP_PHY_LORA
• Scope: NLI
• Value Type: UINT32_LE
• Units: Hz
• Post-Reset Value: Implementation-Specific

Value is the configured LoRa bandwidth.

PROP 40: PROP_PHY_LORA_SF

• Type: Single-Value, Read-Write
• Asynchronous Updates: No
• Required: CAP_PHY_LORA
• Scope: NLI
• Value Type: UINT8
• Post-Reset Value: Implementation-Specific

Value is the configured LoRa spreading factor.

PROP 41: PROP_PHY_LORA_CR

• Type: Single-Value, Read-Write
• Asynchronous Updates: No
• Required: CAP_PHY_LORA
• Scope: NLI
• Value Type: UINT8
• Post-Reset Value: Implementation-Specific

Value is the configured LoRa coding rate.

PROP 42: PROP_PHY_MTU

• Type: Single-Value, Read-Only
• Asynchronous Updates: No
• Required: REQUIRED
• Scope: NLI
• Value Type: UINT16_LE
• Units: octets
• Post-Reset Value: Implementation-Specific

Maximum size of the DATA field that may be supplied to STR_PHY_RAW.

PROP 43: PROP_PHY_LORA_SW

• Type: Single-Value, Read-Write
• Asynchronous Updates: No
• Required: CAP_PHY_LORA
• Scope: NLI
• Value Type: UINT16
• Post-Reset Value: Implementation-Specific, but 0x1424 is a good suggestion.

Value is the 16-bit (SX126x-style) LoRa sync-word.

PROP 44: PROP_PHY_T_FRAME

• Type: Single-Value, Read-Only
• Asynchronous Updates: No
• Required: REQUIRED for new implementations; older devices may return STATUS_PROP_NOT_FOUND
• Scope: NLI
• Value Type: UINT32_LE
• Units: milliseconds
• Post-Reset Value: Derived from the post-reset PHY configuration

An upper bound on the on-air duration of a frame with PROP_PHY_MTU data octets at the current PHY settings, rounded up to a whole millisecond. Implementations MAY round conservatively upward. The positive, nonzero value includes the transmit preamble, PHY header, coding overhead, and PHY CRC. It excludes channel-access waiting, retry delays, duty-cycle deferral, queueing, and host transport latency. It remains readable while the PHY is disabled and is recomputed from the current configuration.

This is the PHY-independent T_frame used by channel-access timing. Hosts can use it without interpreting modulation-specific properties. A host SHOULD refresh it after PHY configuration changes and before choosing a transmit response deadline; max(3000 ms, 2 × T_frame) is a suggested budget. An explicit failure response, including STATUS_CCA_FAILURE, completes the request immediately rather than waiting for this deadline.

Older LoRa devices can be supported by deriving an estimate from their live PHY parameters, with an implementation-specific assumption about the preamble when it is not exposed. Hosts MUST NOT substitute their desired or default configuration for the device’s current configuration.

PROP 4820: PROP_PHY_DUTY_NOW

• Type: Single-Value, Read-Only
• Value Type: u16
• Units: Percent, 0-65535 -> 0-100%
• Post-Reset Value: 0%
• Required Capability: CAP_PHY_DUTY_LIMIT

The radio transmit duty cycle over the past hour, updated in 4-minute intervals.

Under the hood, this is represented as 15 16-bit bins, one for each 4-minute interval. An increment of 1 represents 5ms. For each 5ms of transmission time, the current bin is incremented by 1. So a 20ms transmission would increment the current bin by 4, but a 22ms transmission would increment the bin by 5. At the transition between intervals, the new current bin is reset to zero.

To calculate the current duty cycle, all of the bins are added together, multiplied by 65535, and then divided by 720000.

PROP 4822: PROP_PHY_DUTY_LIMIT

• Type: Single-Value, Read-Write
• Value Type: u16
• Units: Percent, 0-65535 -> 0-100%
• Post-Reset Value: Settings-dependent
• Required Capability: CAP_PHY_DUTY_LIMIT

The value for PROP_PHY_DUTY_NOW above which sending additional packets will be prevented. Packets that are prevented from being sent will be dropped with STATUS_DUTY_LIMIT.

Set to 0xFFFF to disable duty-cycle limiting. Note that PROP_PHY_DUTY_NOW will continue to be updated even if duty-cycle limiting is disabled.

Values for common duty cycles:

Statistics

A device advertising CAP_STATS exposes cumulative UINT32_LE traffic counters. Values count since boot or the most recent reset of that counter and wrap modulo 2^32. Writing four zero octets resets a counter. A device MUST reject every other value or length with STATUS_INVALID_ARGUMENT.

Statistics are live hardware history rather than configuration. They are not part of a saved snapshot, and CMD_RST MUST NOT clear them. A host can reset several counters with CMD_PROP_MULTI_SET, but the individual resets do not occur simultaneously: traffic arriving during the write sweep can fall on different sides of different counter resets.

PROP_PHY_DUTY_NOW is commonly displayed alongside these counters, but it is a rolling regulatory measurement and is not resettable.

PROP 4832: PROP_STAT_TX_PACKETS

Packets whose transmission completed successfully over the physical radio. Requires CAP_STATS.

PROP 4833: PROP_STAT_TX_CHANNEL_BUSY

Transmission attempts deferred because channel assessment reported the channel busy. Such an attempt does not also increment PROP_STAT_TX_PACKETS. Requires CAP_STATS.

PROP 4834: PROP_STAT_RX_PACKETS

Off-air receptions whose first octet carries the UMSH version and valid reserved bits. This classification does not require the rest of the packet to parse. Requires CAP_STATS.

PROP 4835: PROP_STAT_RX_BAD_CRC

Receptions the physical radio rejected because their payload CRC was invalid. Requires CAP_STATS.

PROP 4836: PROP_STAT_RX_NON_UMSH

Off-air receptions whose first octet does not carry the UMSH version and valid reserved bits. Requires CAP_STATS.

PROP 4837: PROP_STAT_RX_ACCEPTED

Receptions on which this device’s own node acted. Frames addressed to an attached host’s identity are not included. Requires CAP_STATS and CAP_REPEATER.

PROP 4838: PROP_STAT_FORWARDED

Receptions this device’s own node chose to repeat. The counter records the forwarding decision; successful physical transmissions are counted separately by PROP_STAT_TX_PACKETS. Requires CAP_STATS and CAP_REPEATER.

PROP 4839: PROP_STAT_FORWARD_DROPPED

Packets that were eligible for forwarding but were rejected by this repeater’s configured minimum RSSI, minimum SNR, or region policy. Exhausted flood budgets and packet-imposed signal thresholds are normal packet behavior, not administrator policy, and are not included. Duplicates, self-addressed packets, and packets received while forwarding is disabled are also excluded. Requires CAP_STATS and CAP_REPEATER.

PROP 4840: PROP_STAT_FORWARD_CANCELLED

Queued forwards cancelled because the destination’s acknowledgement was overheard before transmission. Requires CAP_STATS and CAP_REPEATER.

PROP 4841: PROP_STAT_MESHCORE_SEEN

MeshCore packets received while MeshCore forwarding is running. Every one is also counted in exactly one of PROP_STAT_MESHCORE_FORWARDED_ROUTED, PROP_STAT_MESHCORE_FORWARDED_FLOOD, or PROP_STAT_MESHCORE_DECLINED, or is a duplicate. Copies of this device’s own transmissions are not received packets. Requires CAP_STATS and CAP_MESHCORE_FORWARDER.

PROP 4842: PROP_STAT_MESHCORE_FORWARDED_ROUTED

MeshCore packets this device chose to forward along their source route. The counter records the forwarding decision; successful physical transmissions are counted by PROP_STAT_TX_PACKETS. Requires CAP_STATS and CAP_MESHCORE_FORWARDER.

PROP 4843: PROP_STAT_MESHCORE_FORWARDED_FLOOD

MeshCore packets this device chose to flood, counted at the decision as above. Requires CAP_STATS and CAP_MESHCORE_FORWARDER.

PROP 4844: PROP_STAT_MESHCORE_DECLINED

MeshCore packets this device neither forwarded nor recognized as duplicates: declined by MeshCore’s own forwarding rules or by the region policy, below the configured signal thresholds, malformed, or dropped for want of queue space. Requires CAP_STATS and CAP_MESHCORE_FORWARDER.

PROP 4850: PROP_STAT_RX_OWN_HINT

Packets received over the air whose trace begins with this device’s own router hint. A radio cannot receive its own transmission, so each is a copy of one of this device’s repeats retransmitted without a hop being added, or a packet repeated by another node sharing this device’s router hint. Packets received over a point-to-point link or a shared IP bearer are not counted. None of these names a neighbor, and a device does not list itself in a Peer Repeaters Response. Requires CAP_STATS and CAP_REPEATER.

PROP 4851: PROP_STAT_RADIO_RESETS

Times the device reset its radio chip because the chip stopped doing what it was told: a transmission that did not complete within its time limit, or any other radio operation that did not finish. A transmission abandoned this way increments neither PROP_STAT_TX_PACKETS nor PROP_STAT_TX_CHANNEL_BUSY. Requires CAP_STATS.

ULCP: Frame Transport

Frame transport is the data plane: the host transmits and receives raw, complete UMSH frames through the device. Frames cross the link untouched—the ULCP link carries UMSH frames, not re-encoded UMSH semantics—so the host runs the entire UMSH MAC and the device moves frames on its behalf.

One practical consequence is that a host can address the device’s own device identity with ordinary UMSH frames over this stream, rather than needing a separate bespoke message path for such traffic.

There is no outbound queueing. A transmit either happens or fails while the host is attached to observe the result. Inbound frames may be queued while no host is attached, which is a tethered host service rather than a property of the stream.

Capabilities

Reception needs no capability, and CMD_STR_SEND support is required of every device (see Minimum Requirements). The capability is an affirmative advertisement that transmission is available, not a gate on the command.

Commands

CMD 9: (Host -> Device) CMD_STR_SEND

  0                   1                   2                   3
 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|1 0| RES | TID |      CMD      | STREAM_KEY (PUI, 1-3 bytes) ...
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|   DATA_LEN (Little endian)    | DATA ...
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|   METADATA ...
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

Figure: Structure of CMD_STR_SEND

Command for sending data (such as a packet) to a stream.

The format of the metadata is defined by the stream, and may be absent. Since the framing layer provides the total frame length, DATA_LEN is sufficient to determine the length of both the data and any trailing metadata.

If a non-zero TID is used, the command completes only once the frame has either been transmitted on air or definitively failed. Success is reported by emitting CMD_PROP_IS for PROP_LAST_STATUS with STATUS_OK and a matching TID.

The device only attempts one confirmed transmit at a time. If a CMD_STR_SEND with a non-zero TID arrives while another confirmed transmit is in progress, the new command fails with STATUS_BUSY.

The device will never wait for duty-cycle allowance. If transmission would exceed the currently configured duty-cycle limit and the NODUTY flag is not set, the command fails immediately with STATUS_DUTY_LIMIT.

Commands sent with TID zero are fire-and-forget and do not receive a correlated completion response.

If an error occurs, the value of the emitted PROP_LAST_STATUS will be set accordingly to the status code for the error.

CMD 10: (Device -> Host) CMD_STR_RECV

  0                   1                   2                   3
 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|1 0| RES |0 0 0|      CMD      | STREAM_KEY (PUI, 1-3 bytes)...
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|   DATA_LEN (Little endian)    | DATA ...
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|   METADATA ...
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

Figure: Structure of CMD_STR_RECV

Notification of incoming data received on the given stream. Because this command is only ever sent asynchronously, the TID is always zero.

The format of the metadata is defined by the stream, and may be absent. Since the framing layer provides the total frame length, DATA_LEN is sufficient to determine the length of both the data and any trailing metadata.

Streams

STREAM 113: STR_PHY_RAW

• Type: Packet-Stream, Input/Output
• Required: REQUIRED
• Supported Commands: Send, Recv
• Scope: NLI
• Value Type: Structure

  0                   1                   2                   3
 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|   PACKET_LEN (Little endian)  | PACKET_DATA ...
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|   PACKET_METADATA ...
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

This stream provides the capability of sending and receiving raw packets to and from the radio.

The packet metadata is optional, but if present will be after the packet data and will have the following format:

Metadata for Send

The Send metadata is the following fields in order:

• TX_POWER (i8): Transmit power override (0x7F indicates to use the radio default, 0x7E indicates to transmit at maximum power). A power the radio cannot reach is clamped to its range, as for PROP_PHY_TX_POWER.
• TX_FLAGS (u8): Transmit flags
  • TX_FLAG_NOCCA Bit 0: If set, do not use CCA (or the equivalent LoRa mechanism)
  • TX_FLAG_NODUTY Bit 1: If set, send the packet even if it would push us over the duty-cycle limit
  • All other bits: RESERVED

Metadata for Recv

The Recv metadata is the following fields in order:

• RX_RSSI (u8): This is the negative RSSI that this packet was received with. So if the RSSI was -91, the value of this field would be 91.
  • If 0xFF, no RSSI is supported.
• RX_LQI (u8): This is the link-quality indicator, which is a metric of link quality between 1 and 255 with 1 being the worst possible quality that still decodes and 255 is perfect reception.
  • If 0x00, LQI is not supported.
• RX_SNR (i16): Signal-to-noise ratio in centibels, or 1/10 of a decibel.
  • If 0x8000 (i16::MIN), SNR is not supported. This sentinel is chosen because it is -3276.8 dB, a value no real link can report, so it never collides with a genuine measurement (unlike 0xFFFF, which is -0.1 dB).

Extended Recv Metadata

The Recv metadata may carry two further trailing fields:

• RX_FLAGS (u8): Delivery flags
  • RX_FLAG_BUFFERED Bit 0: The frame was held in the inbound queue and is being delivered by CMD_QUEUE_DRAIN.
  • RX_FLAG_ACKED Bit 1: The device already transmitted a MAC ack for this frame on the host’s behalf. The host MUST NOT send another ack for it.
  • RX_FLAG_SELF_TX Bit 2: The device transmitted this frame itself and is delivering a copy of it. RX_RSSI and RX_SNR MUST carry their unsupported sentinels: a transmitter measures nothing.
  • All other bits: RESERVED, transmitted as zero
• RX_AGE (u32, little-endian): Seconds elapsed between reception of the frame and its delivery to the host. Zero for live delivery.

As with the existing metadata fields, the metadata may be truncated at any field boundary; absent fields are treated as zero. A live delivery with nothing to flag MAY therefore omit these fields entirely, which keeps the encoding byte-compatible with a device that does not queue at all.

ULCP: Device Domain

The device domain is everything that belongs to the radio itself: its own node identity, the settings that make it behave the way its operator commissioned it, and the telemetry it can report about its own hardware. None of it is keyed by the attached host, and none of it is disturbed when one host replaces another (see State Classes).

Commissioning a repeater is exactly this: writing device-domain state and saving it. It is also the reason a host that is merely administering a device writes nothing in the host domain—see Two Kinds of Attach.

The Device Identity

The device hosts a node belonging to the device itself, used for in-band management, diagnostics, repeater forwarding (see PROP_MAC_REPEATER_ENABLED), and (in future revisions) periodic advertisement behavior. Its Ed25519 private key is held by the device and is never readable through this protocol.

On a device with a messaging interface of its own (see The Device’s Own Interface), the device identity is also the messaging identity of whoever carries the device: its conversations are held under it, and its peers address it. Such a device advertises the TXT capability bit (see Capability Bitmap), derives its role as Chat (see PROP_IDENT_ROLE), and advertises itself as mobile by default (see PROP_IDENT_MOBILE).

A device identity always exists. A device advertising CAP_DEV_IDENTITY that finds no stored keypair at power-on MUST generate one from a cryptographic random source and persist it before processing any host command; PROP_DEV_KEY therefore never reports an empty value on a running device. Provisioning an identity is not a commissioning step: a factory-fresh radio is already a node, and PROP_DEV_PRIVATE_KEY exists to install a particular identity—restoring a known repeater onto replacement hardware—not to bring one into being.

The corollary is that a radio holds a throwaway identity from first power-on until a specific one is installed. This is safe because it never reaches the air: PROP_PHY_ENABLED is false post-reset, and a radio with nothing saved boots with the PHY disabled. It is not safe automatically on the restore path—see CMD_RESTORE.

Because the device holds this identity’s private key, it performs its own key agreement and needs only peer public keys (see PROP_DEV_PEERS). That is the opposite of the host identity, for which the device holds no private key and every pairwise key must be provisioned explicitly (see Tethered Host Services).

Lists Held by the Device’s Store

A device with a messaging interface of its own keeps a store for its conversations, and that store MAY also keep the device identity’s lists, PROP_DEV_PEERS and PROP_DEV_CHANNEL_KEYS: whom its carrier talks with and on which channels belong with the conversations, not with the radio’s configuration.

Lists the store keeps are persisted as they change, as the device identity is, and are outside the saved snapshot (see Saved State):

• CMD_SAVE does not record them, and CMD_RESTORE leaves them as they are.
• CMD_RST restores them as last stored.
• CMD_CLEAR erases them with the rest of the persisted provisioning, and leaves the conversations.

With none stored, PROP_DEV_PEERS is empty and PROP_DEV_CHANNEL_KEYS holds the channels the messaging interface starts out on: the default channels, public and EMERGENCY.

Capabilities