mesh-rs extensions

This document specifies the protocol and firmware extensions implemented by mesh-rs for developers building compatible firmware or applications.

• Turn-based games
• Aquarium visits
• Clock tower
• Public channel discovery
• Region channels
• Repeater relay filter
• Vendor companion frames
• Companion frame fragmentation
• Companion response additions
• BLE alert and time services
• Multipart reassembly
• Admin CLI additions

Turn-based games

Two-player games are carried as readable chat lines that stock clients display as ordinary messages.

Transport

Frames are transmitted as plain-text DMs or room posts, not group-channel messages. In a room, the 4-byte author prefix in the server's push identifies the player.

A message is treated as a game frame if it parses as a v1 frame, or if it begins with ~g<N> (for decimal N from 2 to 99) followed by a non-empty body. Other text, including malformed ~g1 lines, remains chat. A session is identified by the conversation key (the DM peer or room server) and gid.

Frame

~g1 <game> <gid> <verb> [args...]

• A frame consists of at most 151 bytes of printable ASCII, with single spaces between tokens and no leading, trailing or extra tokens. Hexadecimal digits are lowercase.
• game identifies the ruleset: t tic-tac-toe, b battleships, k checkers, m mancala, n nine men's morris, g gomoku, q quarto, c chess, or p pente.
• gid is a 4-digit hex identifier chosen by the inviter so that it is unique within the conversation. Receivers use the identifier from the invitation to match subsequent frames to the session.
• seq is an unsigned 16-bit decimal integer formatted without leading zeros; move frames carry a non-zero sequence number. #hash consists of # followed by 4 hex digits. Payload blobs (move, echo, state, layout) are non-empty strings of characters from [a-z0-9.-].
• The state hash is the first 2 bytes of SHA-256(gid[2] ‖ seq u16 ‖ canonical state bytes after the move), where gid[2] is the 2-byte binary value of gid. Each game's canonical state encoding is defined below and is hashed bit for bit.

~g1 t 3fa2 inv f
~g1 t 3fa2 ok
~g1 t 3fa2 m 1 5 #2829
~g1 t 3fa2 m 2 1/5 #8b27

Lifecycle

Side A always moves first, and the invite argument selects the inviter's side. The active turn is determined by the game state rather than sequence-number parity.

In a direct-message session, the game becomes active for the invitee when it sends ok, and for the inviter when it receives either ok or a valid move at sequence 1 from the peer.

In a room, members track incoming invitations while below their session limit. The inviter binds the session to the sender of the first ok by sending go with that member's author prefix; that member becomes the second player and all other room members spectate. Moves are accepted only from the player whose turn is indicated by the state.

An invitation for an unsupported game or protocol version is answered with no v. When the session limit (6 sessions, or 4 on small-screen boards) is reached, a node answers DM invitations with no f and ignores room invitations. Incoming invitations never evict active sessions, and unanswered invitations expire locally after 7 days. Each client detects game completion directly from the rules without a separate end frame.

Repair

Let held denote the receiver's local sequence number. An incoming move with a sequence number at or below held is discarded. A move at held + 1 is applied if the sender holds the active turn. A move at held + 2 that includes an echo field first applies the echoed move at held + 1, provided doing so transfers the turn to the sender, and then applies the move at held + 2. Any larger sequence gap, illegal move or state-hash mismatch triggers a sync <held> reply.

A participant replies to sync with an st snapshot only when the session is active, its local sequence number exceeds the requested value, and it sent the most recent move. A snapshot is accepted only when its state blob and hash are valid and its sequence number is at least held. Active sessions accept snapshots only while a sync request is pending, whereas pending room sessions also accept snapshots to initialize their state. Automatic sync requests and st responses are each rate-limited to one per 60 s per session.

Receiving a move, resignation, draw frame, commitment or reveal for an unknown gid triggers at most one sync 0 per gid every 300 s. An unsolicited snapshot for an unknown gid is not applied without explicit user acceptance.

Per-game encodings

Snapshots encode the canonical state bytes as lowercase hex unless stated otherwise. In canonical binary states, the turn byte is 0 for side A and 1 for side B; in snapshots, the trailing letter a or b identifies the side to move. Turns alternate strictly in every game except mancala.

A trit board packs five cells per byte, placing cell i in byte i / 5 at weight 3^{i mod 5} with values 0 for empty, 1 for side A and 2 for side B. Battleships uses the cell values defined in its table entry below.

Aquarium visits

Virtual fish visit other nodes using the LFG1| direct-message protocol from LoRaGotchi DX, in which fields are separated by literal ASCII pipe characters (|). mesh-rs extends the COMMIT message with an optional trailing appearance field that stock hosts ignore.

• Visit messages are transmitted as acknowledged plain-text DMs. Any message beginning with LFG1| is suppressed from normal chat display.
• tx and fid are unsigned 32-bit decimal integers. fid is a non-zero random identifier fixed for the lifetime of the fish, while tx is generated fresh for each visit request. Valid replies echo both identifiers and originate from the expected peer.
• stage encodes the life stage as 0 (fry), 1 (young), 2 (adult) or 3 (elder). name spans the remainder of the line and is at most 23 bytes.
• look is an unsigned 16-bit decimal integer packing hue in bits 0 to 2, fin style in bits 3 to 4, body pattern in bits 5 to 6, and a round-body flag in bit 7. When look is omitted, the appearance byte defaults to SHA-256(fid u32)[0].

Owner

After sending REQ, the owner waits up to 90 s for ACK or BUSY. After ACK, the owner sends COMMIT and waits 120 s for ARRIVED. It retries COMMIT once before abandoning the visit after another 120 s.

The 3600 s visit lease begins when the owner receives ARRIVED. At expiry or on user recall, the owner sends RECALL. The fish returns home when RETURN is received or after 120 s.

Host

A host accommodates between 1 and 3 visiting fish at a time, with at most one guest per owner. A duplicate REQ for an active reservation is answered with ACK again. The host replies with BUSY when its tank is full, the fish is already present, visitor hosting is disabled, local time is between 20:00 and 06:00, or the node's clock is unset.

The host replies to every matching COMMIT with ARRIVED and starts its 3600 s lease on receipt of the first matching COMMIT. A reservation that receives no COMMIT expires after 300 s. The host ends the visit and sends RETURN either on receipt of RECALL or when the lease expires.

Fry

A visiting adult or elder fish leaves a fry in the host tank if the visit ends within 120 s of the lease deadline. The breeding seed is the first 4 bytes of SHA-256(host fid ‖ visitor fid ‖ tx), with each identifier encoded as a 4-byte integer. The fry inherits the host's hue, the visitor's fin and body shape, and the pattern encoded in bits 5 to 6 of the first seed byte.

Clock tower

A node without a trusted clock requests the time from a designated contact so its adverts and messages carry accurate timestamps. A node serves as a tower when the feature is enabled and its own clock source is at app, network or GNSS tier.

Request and reply

A time request is transmitted as a DIRECT anonymous info request (ANON_REQ) with subtype 0x05 along the contact's stored path, or zero-hop when no path is stored. Multi-byte binary integers in this and other wire formats are little-endian unless stated otherwise.

Clock tiers in ascending priority order are 0 (unset), 1 (manual), 2 (restored), 3 (mesh), 4 (app), 5 (network) and 6 (GNSS).

Tower

The tower responds only to DIRECT requests while clock.tower is enabled and its clock source is above mesh tier. Time replies are rate-limited to 16 per 180 s, independently of other info replies.

A direct neighbour receives a zero-hop reply, while other requesters receive replies along the supplied reply path.

Room login messages have the layout timestamp u32 | sync cursor u32 | password. To distinguish time requests from logins, a room server treats a message as a time request only when its first four bytes fall outside the login timestamp window (15 minutes before to 5 minutes after the server's clock).

Requester

Eligible contacts are favourites with bit 0x20 set in the contact flags byte. The first request is sent 300 s after boot, and subsequent requests are sent every clock.tower.interval (default 1800 s, minimum 300 s). No requests are sent while the local clock source is at mesh tier or higher. Candidates are queried in turn, starting with the most recently active contact.

A reply is accepted only from the last queried tower, with a matching request tag, before the next request is sent, and with a reported tier above mesh. The accepted timestamp is applied at mesh tier according to the tier priority order above.

CLI

Public channel discovery

Repeaters advertise the public hashtag channels active around them so users can discover and join those channels by name.

A public channel name begins with # followed by 1 to 29 bytes of UTF-8 containing no commas, 0x7F, or bytes at or below 0x20. The prefix #$ is reserved. The 16-byte channel key is SHA-256(name with #)[0..16].

A discovery request is an ANON_REQ info request with subtype 0x04, framed and routed in the same manner as a clock-tower request. The reply body has the layout tag u32 | unix u32 | names, where names is a comma-separated list truncated on a channel-name boundary to at most 160 bytes; an empty list is valid. Receivers stop parsing the list at the first NUL byte and ignore invalid or duplicate names. Channel-discovery replies share the repeater's general info-reply budget of 4 replies per 180 s.

On the repeater CLI, channel advertise <name>, channel remove <name> and channel list (which prints -none- when empty) manage the advertised list. Up to 8 channel names are persisted in configuration storage.

To scan for channels, a client broadcasts a zero-hop node-discovery request for repeaters and, over the next 60 s, queries up to 4 newly heard repeaters every 5 s.

Region channels

A region channel is a public channel bound to a geographic region whose messages always flood under that region's transport scope. This extension implements the proposal in meshcore-dev/MeshCore#2908.

A region channel name begins with + followed by a valid region name of 1 to 29 bytes of ASCII lowercase letters, digits and hyphens. The channel key is SHA-256(name with +)[0..16], derived in the same way as a hashtag channel key, while the flood scope is the region key SHA-256(# and the bare name)[0..16].

A channel is treated as a region channel only if its name is valid and its 16-byte key matches the derivation; otherwise it is treated as an ordinary private channel. The flood scope is re-derived from the name and key on every load and every channel write, so a client cannot strip the scope without modifying the channel itself.

Messages sent on a region channel use its region scope in place of both the app's session scope and the node's default scope. Requests to change the scope of a region channel are ignored. The leading characters +, # and $ are reserved and cannot be used to start a new private channel name.

Repeater relay filter

A repeater evaluates an ordered list of filter rules and a per-origin advert rate limiter before relaying packets. Operators can suppress traffic from a noisy channel, bot, region or upstream repeater while continuing to relay other traffic.

Matching

Packets not addressed to the local node are filtered after duplicate suppression and before the standard hop, region and loop checks.

Content predicates are evaluated only on group packets decrypted with a known channel key and a valid message authentication code (MAC). The first ": " substring separates the sender name from the message body, and the first NUL byte terminates the text.

Filtering is enabled by default with an empty rule list. The repeater supports up to 32 rules, 32 filter channels and 512 tracked advert origins.

Rules

A rule matches a packet only when every predicate configured on the rule matches. Omitted predicates impose no restriction, and repeating a key in a rule definition replaces its earlier value.

Numeric intervals are written as a single value v or as a range [a,b], (a,b), [a,b) or (a,b], where square brackets are inclusive, parentheses are exclusive, and * denotes an unbounded endpoint.

When type is specified on a rule, the predicates chan, sender, text, signed and chanhash are accepted only if the listed types include the corresponding packet types.

A MeshOS v1 trailer immediately follows the NUL byte terminating the text and has the binary layout 'S' 0x01 | key id [8] | signature [64], followed by fewer than 16 zero padding bytes. The 8-byte key identifier is the prefix of the signer's public key. The signature covers "MeshOS signed channel v1" ‖ SHA-256(channel key)[0..16] ‖ ts u32 ‖ "name: text"; repeaters check only the trailer structure and do not verify the Ed25519 signature because the signer's full public key is not transmitted in the packet.

Rule actions

• Enabled rules are evaluated in order. The action of the first rule with matching predicates and satisfied gate conditions is applied. drop discards the packet, while forward terminates rule evaluation and passes the packet to the advert rate limiter and standard relay checks.
• prob applies the rule's action to the specified percentage of matching packets, producing the same decision for duplicate copies of a packet.
• With throttle, the first matching packet opens the cooldown window and continues to subsequent rules. Further matches within the window apply the rule's action without extending the window.
• The advert limiter suppresses repeated flood adverts from the same origin for a configurable window of 0 to 720 hours. The window starts when an advert from that origin is relayed. When all 512 origin slots are in use, a new origin evicts the oldest tracked entry.

Patterns

Pattern predicates use tiny-regex-c syntax, supporting . ^ $ * + ?, character classes [abc] and [^a-z], shorthand classes \d \D \w \W \s \S, and backslash-escaped literals. Matching is byte-oriented, case-sensitive and unanchored unless explicitly anchored with ^ or $. The wildcard . matches any byte except CR and LF. A top-level | splits a pattern into at most 8 branches with anchors binding to their own branch, whereas \| matches a literal ASCII pipe character.

A quantifier with no preceding atom or an anchor placed away from its branch boundary never matches. Each branch compiles to at most 29 pattern atoms, and evaluation stops after 5000 steps per branch so complex expressions cannot stall packet relaying. Exceeding the step limit treats the branch as a non-match.

CLI

Arguments are separated by spaces, and double quotes group values that contain spaces. Replies fit within 160 bytes, error replies begin with Err - , and multi-page listings end with ; next=N giving the start index for the next page.

Filter channel names are 1 to 15 bytes long and exclude , = " and control bytes. Keys for Public and #name are derived automatically when those channels are first referenced in a rule. Deleting a channel removes it from every rule, and a rule left with an empty channel list never matches.

Vendor companion frames

Vendor companion frames provide diagnostics, file transfer and channel discovery using opcodes outside the upstream range. Commands (0xE0), responses (0xE0) and pushes (0xE1) share the binary layout sub | payload, and chunk sequence numbers increment modulo 256.

Console commands include screenshot, mem, key [long] <key> and tap <x> <y> [long] for remote input.

Companion frame fragmentation

Responses exceeding the 176-byte frame limit are fragmented for apps that send CMD_DEVICE_QUERY with app_target_ver 15 or above.

Each fragment is sent as push 0x91 with the layout frag_id u16 | index | count | orig_type | orig_len u16 | offset u16 | chunk (≤166 bytes).

Fragments of live pushes are sent consecutively. For queued messages, one fragment is sent per CMD_SYNC_NEXT_MESSAGE request, which carries the payload flags (bit 0 ack) | frag_id u16 | index. The next fragment is sent after a matching acknowledgement; any other request resends the current fragment.

Companion response additions

• The twelfth byte of RESP_CODE_BATT_AND_STORAGE indicates the power source: 0 unknown, 1 battery, 2 plugged in, or 3 charging.
• For CMD_GET_CHANNEL without an index byte, the node sends one channel-info frame per configured slot.

BLE alert and time services

Nodes expose standard Bluetooth GATT services alongside the Nordic UART service so a bonded phone can trigger an audible alert or synchronize the clock without speaking the companion protocol.

• The Immediate Alert service (0x1802) exposes Alert Level (0x2A06) for writes without response: 0 stops alerting, 1 sounds a mild alert (roughly one beep per second), and 2 sounds a high alert (rapid beeps at full volume, overriding mute). Alert writes are accepted only over an authenticated link, and an active alert stops 5 s after the most recent write, on a write of 0, or on disconnect.
• The Current Time service (0x1805, characteristic 0x2A2B) reports the node's UTC time, or all zero bytes when the clock is unset. An authenticated write updates the node's clock at app tier.

Multipart reassembly

The receiver reassembles MULTIPART packets carrying payload types other than ACK. The remaining-parts counter decreases by one in each successive part until it reaches zero. Up to 4 messages of at most 1024 bytes each are reassembled concurrently, and an out-of-order part resets the partial message.

Stock repeaters do not relay MULTIPART packets, so multipart exchanges are limited to direct neighbours.

Admin CLI additions