Mesh Protocol

A technical overview of how Socialmesh extends the Meshtastic radio protocol to support presence beacons, compact signals, and node identity exchange — without modifying firmware.

1. Overview

Socialmesh is a companion app for Meshtastic mesh radios. It adds features that the stock Meshtastic app does not provide: presence awareness, broadcast signals with expiry, and a node identity system called NodeDex.

These features need to send data over the mesh. Rather than forking Meshtastic firmware, Socialmesh uses private portnums — a range (256–511) that Meshtastic reserves for third-party applications. Stock firmware routes packets on private portnums identically to any other packet. No firmware changes are required.

Socialmesh defines three new packet types, each on its own portnum:

A fourth portnum, 256, carries legacy JSON-encoded signals for backward compatibility with older Socialmesh releases.

All three new packet types use hand-packed binary encoding rather than protobuf. The result is smaller payloads, less airtime, and more room on the mesh for everyone.

2. Why Binary?

LoRa is a slow, shared radio channel. Every byte costs airtime, and airtime is the scarcest resource on a mesh network. The original Socialmesh signal format used JSON on portnum 256. A typical signal with a short message and GPS coordinates consumed roughly 130 bytes.

The binary encoding reduces this to about 50 bytes — a 60% reduction. Presence beacons, which previously had to piggyback on full signal payloads, shrink to as little as 3 bytes.

The encoding is also deterministic. Every field has a fixed size and position (conditionally present based on flags), which makes byte budgets easy to enforce and decode logic trivial.

3. Packet Families

4. The Header Byte

All three packet types share a common first byte, called hdr0:

hdr0 = (version << 4) | kind

• High nibble (4 bits): Protocol version (currently 0)
• Low nibble (4 bits): Packet kind (1 = presence, 2 = signal, 3 = identity)

This gives room for 16 protocol versions and 16 packet kinds with zero additional overhead — a single byte.

The second byte is always a flags byte. Its layout is specific to each packet kind, controlling which optional fields are present. Together, the two-byte header tells the decoder everything it needs to parse the rest of the payload.

5. Signal IDs & Collision Probability

Each SM_SIGNAL carries an 8-byte (64-bit) random identifier generated by a cryptographically secure random number generator. This ID serves two purposes:

1. Deduplication. The mesh naturally rebroadcasts packets. The signal ID lets receivers discard duplicates they have already processed.
2. Cloud sync mapping. For users who optionally sync signals to the cloud, the app maps the 64-bit wire ID to a local UUID.

The ID is not a secret — it travels in the clear alongside the signal content. Its purpose is uniqueness, not secrecy. A 64-bit random ID saves 28 bytes per signal compared to a string UUID, which matters when every byte costs airtime.

Collision probability

The birthday-bound formula gives the probability that at least two signals in a set of n share the same 64-bit ID:

At the throughput of a LoRa mesh network, these volumes would take years to accumulate. Collisions are negligible.

6. Compatibility & Migration

Stock firmware compatibility

Socialmesh extensions require no firmware changes. The relationship is straightforward:

Stock firmware relays packets on portnums 260–262 just as it relays any other packet. It does not need to understand the payload. The routing layer is portnum-agnostic.

Peer capability detection

Socialmesh detects capable peers passively. When a node sends any packet on portnums 260–262, it reveals itself as a Socialmesh node. The app tracks this per-node — no explicit handshake or beacon is needed.

Dual-send migration

During the transition period, the app can operate in dual-send mode: it sends both a binary SM_SIGNAL (portnum 261) for current peers and a legacy JSON signal (portnum 256) for older peers. Both formats carry the same content and map to the same signal ID, so the receiving app deduplicates them into a single item regardless of which encoding arrives first.

Dual-send increases airtime by roughly 38% during the migration window. Once all peers on the mesh are detected as SM-capable, legacy sending can be disabled.

7. Design Principles

Pure extension, no fork. All Socialmesh logic lives in the app. The firmware is unmodified. This means zero rebase cost when Meshtastic releases a new firmware version, and zero risk of breaking upstream compatibility.

Conservative airtime. Every packet type has app-enforced rate limits. Presence beacons are limited to once per 5 minutes. Signals have a 30-second minimum interval. Emergency signals are capped at 3 per hour. These limits exist to be good neighbors on a shared radio channel.

Graceful degradation. If a receiving node does not understand a Socialmesh packet, nothing bad happens — the packet is silently ignored. If a sending node cannot detect any SM-capable peers, it falls back to legacy JSON. The app never assumes the entire mesh runs Socialmesh.

Byte budgets, not MTU promises. All content limits (63 bytes for presence status, 140 bytes for signal content) are enforced at encoding time, well below the LoRa payload ceiling. This provides headroom for radio overhead and avoids fragmentation.

Client-side expiry. TTL values on signals are display hints for receiving apps. The mesh has no mechanism to enforce expiry or recall a broadcast. This keeps the protocol stateless and avoids complexity in the relay layer.

Deterministic encoding. Binary fields have fixed sizes and positions. There are no variable-length integers, no field tags, no schema negotiation. A decoder needs only the flags byte to know which fields are present.

Version tolerance. Unknown protocol versions and unknown packet kinds are silently dropped. This allows the protocol to evolve without coordination across all nodes on a mesh.

8. For Developers

Interoperability

If you are building an app or tool that operates on a Meshtastic mesh alongside Socialmesh nodes, here is what to expect:

• Portnums 260–262 will appear in your received packet stream. If you do not handle them, ignore them — they are well-formed Meshtastic packets with opaque binary payloads.
• Portnum 256 carries JSON-encoded signals for backward compatibility. If you already handle portnum 256, you may see both a JSON and a binary version of the same signal during the dual-send period. Deduplicate by signal ID if needed.
• No collision risk with your portnums unless you also use 260–262. The Meshtastic private range (256–511) is first-come, first-served.

Decoding SM packets

Every SM packet starts with a one-byte header (hdr0). To identify the packet type:

version = (hdr0 >> 4) & 0x0F
kind    = hdr0 & 0x0F

If version is higher than you support, discard the packet. If kind is not one you recognize, discard the packet. Otherwise, read the flags byte (byte 1) and decode the remaining fields based on the kind.

All multi-byte integers are big-endian. All strings are UTF-8 with a one-byte length prefix counting bytes, not characters.

Rate limit expectations

These are app-side limits, not mesh-enforced. A misbehaving implementation could exceed them, but the firmware's duty cycle enforcement provides a hard backstop regardless.