<p><strong>Notes:</strong> This setting only controls the power level of the LoRa chip. Some nodes have an additional power amplifier stage which increases the total output. Refer to the node's manual for the correct setting to use. <strong>Setting a value too high may violate the laws in your country.</strong></p>
<hr/>
<h4id="view-or-change-the-boosted-receive-gain-mode">View or change the boosted receive gain mode</h4>
<h4id="view-or-change-this-nodes-rx-boosted-gain-mode-sx12xx-only-v1141">View or change this node's rx boosted gain mode (SX12xx only, v1.14.1+)</h4>
<h4id="view-or-change-this-nodes-rx-boosted-gain-mode-sx12xx-and-lr1110-v1141">View or change this node's rx boosted gain mode (SX12xx and LR1110, v1.14.1+)</h4>
<h4id="fine-tune-the-battery-reading">Fine-tune the battery reading</h4>
<p><strong>Usage:</strong>
@ -3359,7 +3372,7 @@
<p><strong>Parameters:</strong>
- <code>on</code>: enable power saving
- <code>off</code>: disable power saving</p>
<p><strong>Default:</strong><code>on</code></p>
<p><strong>Default:</strong><code>off</code></p>
<p><strong>Note:</strong> When enabled, device enters sleep mode between radio transmissions</p>
<hr/>
<h3id="routing">Routing</h3>
@ -3383,7 +3396,7 @@
- <code>3</code>: DO NOT USE (Reserved) </p>
<p><strong>Default:</strong><code>0</code></p>
<p><strong>Note:</strong> the 'path.hash.mode' sets the low-level ID/hash encoding size used when the repeater adverts. This setting has no impact on what packet ID/hash size this repeater forwards, all sizes should be forwarded on firmware >= 1.14. This feature was added in firmware 1.14</p>
<p><strong>Temporary Note:</strong> adverts with ID/hash sizes of 2 or 3 bytes may have limited flood propogation in your network while this feature is new as v1.13.0 firmware and older will drop packets with multibyte path ID/hashes as only 1-byte hashes are suppored. Consider your install base of firmware >=1.14 has reached a criticality for effective network flooding before implementing higher ID/hash sizes. </p>
<p><strong>Temporary Note:</strong> adverts with ID/hash sizes of 2 or 3 bytes may have limited flood propagation in your network while this feature is new as v1.13.0 firmware and older will drop packets with multibyte path ID/hashes as only 1-byte hashes are supported. Consider your install base of firmware >=1.14 has reached a criticality for effective network flooding before implementing higher ID/hash sizes. </p>
<hr/>
<h4id="view-or-change-this-nodes-loop-detection">View or change this node's loop detection</h4>
<p><strong>Usage:</strong>
@ -3396,7 +3409,7 @@
- <code>moderate</code>: packets are dropped if repeater's ID/hash appears 2 or more times (1-byte), 1 or more (2-byte), 1 or more (3-byte)
- <code>strict</code>: packets are dropped if repeater's ID/hash appears 1 or more times (1-byte), 1 or more (2-byte), 1 or more (3-byte)</p>
<p><strong>Default:</strong><code>off</code></p>
<p><strong>Note:</strong> When it is enabled, repeaters will now reject flood packets which look like they are in a loop. This has been happening recently in some meshes when there is just a single 'bad' repeater firmware out there (prob some forked or custom firmware). If the payload is messed with, then forwarded, the same packet ends up causing a packet storm, repeated up to the max 64 hops. This feature was added in firmware 1.14</p>
<p><strong>Note:</strong> When it is enabled, repeaters will now reject flood packets which look like they are in a loop. This has been happening recently in some meshes when there is just a single 'bad' repeater firmware out there (probably some forked or custom firmware). If the payload is messed with, then forwarded, the same packet ends up causing a packet storm, repeated up to the max 64 hops. This feature was added in firmware 1.14</p>
<p><strong>Example:</strong> If preference is <code>loop.detect minimal</code>, and a 1-byte path size packet is received, the repeater will see if its own ID/hash is already in the path. If it's already encoded 4 times, it will reject the packet. If the packet uses 2-byte path size, and repeater's own ID/hash is already encoded 2 times, it rejects. If the packet uses 3-byte path size, and the repeater's own ID/hash is already encoded 1 time, it rejects. </p>
<hr/>
<h4id="view-or-change-the-retransmit-delay-factor-for-flood-traffic">View or change the retransmit delay factor for flood traffic</h4>
<p><strong>Note:</strong> When multiple nearby repeaters all hear the same flood packet, each waits a random amount of time before retransmitting to avoid simultaneous collisions. This factor scales the size of that random window. Higher values reduce collision risk at the cost of added latency. <code>0</code> disables the window entirely.</p>
<hr/>
<h4id="view-or-change-the-retransmit-delay-factor-for-direct-traffic">View or change the retransmit delay factor for direct traffic</h4>
<p><strong>Usage:</strong>
@ -3414,6 +3428,7 @@
<p><strong>Parameters:</strong>
- <code>value</code>: Direct transmit delay factor (0-2)</p>
<p><strong>Default:</strong><code>0.2</code></p>
<p><strong>Note:</strong> Same collision-avoidance random window as <code>txdelay</code>, but applied to direct (non-flood, routed) traffic. The default is lower because direct packets are addressed to a specific next hop, so far fewer nodes compete to retransmit them.</p>
<hr/>
<h4id="experimental-view-or-change-the-processing-delay-for-received-traffic">[Experimental] View or change the processing delay for received traffic</h4>
<p><strong>Usage:</strong>
@ -3422,6 +3437,7 @@
<p><strong>Parameters:</strong>
- <code>value</code>: Receive delay base (0-20)</p>
<p><strong>Default:</strong><code>0.0</code></p>
<p><strong>Note:</strong> When enabled, repeaters that received a flood packet with a weak signal are held in a delay queue before processing, while those that received it with a strong signal process it immediately. This gives strong-signal paths forwarding priority. By the time weak-signal nodes process their copy, the packet may have already propagated and will be suppressed as a duplicate, reducing redundant retransmissions.</p>
<hr/>
<h4id="view-or-change-the-duty-cycle-limit">View or change the duty cycle limit</h4>
<p><strong>Usage:</strong>
@ -3503,6 +3519,15 @@
- <code>value</code>: Maximum flood hop count (0-64)</p>
<p><strong>Default:</strong><code>64</code></p>
<hr/>
<h4id="limit-the-number-of-hops-for-an-unscoped-flood-message">Limit the number of hops for an unscoped flood message</h4>
- <code>value</code>: Maximum flood hop count (0-64) for a packet without a scope (no region set)</p>
<p><strong>Default:</strong><code>0xFF</code> - indicates it hasn't been set, will track flood.max until it is.</p>
<p><strong>Note:</strong> An alternative to <code>region denyf *</code>, setting <code>flood.max.unscoped</code> to a lower value such as <code>3</code> would allow for local unscoped messages to propagate, while preventing noisy neighbors from flooding a local region.</p>
<hr/>
<h3id="acl">ACL</h3>
<h4id="add-update-or-remove-permissions-for-a-companion">Add, update or remove permissions for a companion</h4>
<p><strong>Usage:</strong>
@ -3585,6 +3610,34 @@
- <code>name</code>: Region name
- <code>parent_name</code>: Parent region name (optional, defaults to wildcard)</p>
<hr/>
<h4id="define-region-hierarchy-single-line">Define region hierarchy (single line)</h4>
<p><strong>Parameters (tokens):</strong> Space-separated. A logical <strong>cursor</strong> starts at the wildcard <code>*</code>.</p>
<ul>
<li><strong><code>name</code></strong> — Create <code>name</code> as a child of the current cursor (equivalent to <code>region put name</code> with the cursor as parent). Cursor moves to <code>name</code>.</li>
<li><strong><code>name|jump</code></strong><em>(or <code>name,jump</code>)</em> — Create <code>name</code> as a child of the current cursor, then move the cursor to <code>jump</code> (must already exist on the node, or have been created earlier in this command). <code>jump</code> is <strong>not</strong> the parent of <code>name</code>; use this form to pop back up and start another branch.</li>
</ul>
<p><strong>Behavior:</strong> Each created region defaults to flood-allowed (same as <code>region put</code>). The reply is the resulting region tree (same format as bare <code>region</code>); review it before running <code>region save</code> to persist. On error, the reply is <code>Err - ...</code> and any regions placed before the failure remain on the node, just like a partial chain of <code>region put</code>.</p>
<p><strong>Existing regions:</strong><code>region def</code> does not clear the existing tree — if a name already exists, its parent is updated to the current cursor; otherwise a new region is created. To start from scratch, <code>region remove</code> the unwanted regions first.</p>
<p><strong>Limits:</strong> Repeater serial accepts one line up to <strong>160 characters</strong>. For larger trees, split across multiple <code>region def</code> commands; the cursor resets to <code>*</code> between commands, so lead the next command with <code>child|ancestor</code> to reposition. Each token splits at most once on <code>|</code> — <code>region def a|b|c|d</code> is not a flat-list shorthand; see the flat-list example below.</p>
<p><strong>Example — linear chain</strong> (each token becomes a child of the previous):</p>
<pre><code>region def a b c d e
region save
</code></pre>
<p><strong>Example — branched tree</strong> (equivalent to <code>region put a</code>, <code>region put b a</code>, <code>region put c b</code>, <code>region put d c</code>, <code>region put e b</code>, <code>region put f e</code>):</p>
<pre><code>region def a b c d|b e f
region save
</code></pre>
<p><strong>Example — error and partial state:</strong></p>
<pre><code>region def a b c|nope d
</code></pre>
<p>The reply is <code>Err - unknown jump: nope</code>. <code>a</code>, <code>b</code>, and <code>c</code> were placed before the failure; <code>d</code> was not. Run <code>region</code> to inspect, then re-run with a corrected jump or repair with <code>region remove</code> / <code>region put</code>.</p>
<p><strong>Example — flat list</strong> (each region a child of <code>*</code>). Use <code>|*</code> after each token to pop the cursor back to the root before the next token:</p>
<p><strong>Response</strong>: <code>PACKET_MSG_SENT</code> (0x06) on success</p>
<hr/>
<h3id="6-send-channel-data-datagram">6. Send Channel Data Datagram</h3>
<p><strong>Purpose</strong>: Send binary datagram data to a channel.</p>
<p><strong>Purpose</strong>: Send a binary datagram to a channel. Unlike channel text messages, datagramscarry no built-in sender identity and no timestamp— applications needing either must encode them inside the binary payload.</p>
<p><strong>Command Format</strong>:</p>
<pre><code>Byte 0: 0x3E
Bytes 1-2: Data Type (`data_type`, 16-bit little-endian)
<p><strong>Data Type / Transport Mapping</strong>:
- <code>0x0000</code> is invalid for this command.
- <code>0x0000</code>(<code>DATA_TYPE_RESERVED</code>) is invalid and rejected with <code>PACKET_ERROR</code>.
- <code>0xFFFF</code> (<code>DATA_TYPE_DEV</code>) is the developer namespace for experimenting and developing apps.
- Other non-zero values can be used as assigned application/community namespaces.</p>
<p><strong>Note</strong>: Applications that need a timestamp should encode it inside the binary payload.</p>
- Values <code>0x0001</code>–<code>0xFFFE</code> are available for registered application/community namespaces. See the <ahref="#registered-data_type-values">Registered data_type values</a> table below.</p>
<p><strong>Limits</strong>:
- Maximum payload length is <code>163</code> bytes.
- Larger payloads are rejected with <code>PACKET_ERROR</code>.</p>
<p><strong>Response</strong>: <code>PACKET_OK</code> (0x00) on success</p>
- Maximum payload length is <code>MAX_CHANNEL_DATA_LENGTH = MAX_FRAME_SIZE - 9 = 163</code> bytes.
- Larger payloads are rejected with <code>PACKET_ERROR</code> (<code>ERR_CODE_ILLEGAL_ARG</code>).</p>
<p><strong>Response</strong>: <code>PACKET_OK</code> (0x00) on success, or <code>PACKET_ERROR</code> (0x01) with one of:
<p><strong>Inbound datagrams</strong> are delivered to the host via <code>RESP_CODE_CHANNEL_DATA_RECV</code> (0x1B); see <ahref="#receive-channel-data-datagram">Receive Channel Data Datagram</a>.</p>
<p><code>data_type</code> is an <strong>application identifier</strong>, not a payload-format identifier. Each registered value identifies an application that owns its own internal payload schemas. The firmware does not inspect payload contents — <code>data_type</code> is transported opaquely.</p>
<table>
<thead>
<tr>
<th>Value</th>
<th>Constant</th>
<th>Purpose</th>
</tr>
</thead>
<tbody>
<tr>
<td>0x0000</td>
<td><code>DATA_TYPE_RESERVED</code></td>
<td>Reserved; invalid on send</td>
</tr>
<tr>
<td>0x0001 – 0x00FF</td>
<td>—</td>
<td>Reserved for internal use</td>
</tr>
<tr>
<td>0x0100 – 0xFEFF</td>
<td>—</td>
<td>Registered application namespaces (see <ahref="../number_allocations/">number_allocations.md</a>)</td>
</tr>
<tr>
<td>0xFF00 – 0xFFFE</td>
<td>—</td>
<td>Testing/development; no registration required</td>
</tr>
<tr>
<td>0xFFFF</td>
<td><code>DATA_TYPE_DEV</code></td>
<td>Developer/experimental namespace</td>
</tr>
</tbody>
</table>
<p>To register a new application, submit a PR adding a row to the table in <ahref="../number_allocations/">docs/number_allocations.md</a>. Internal sub-formats within an allocated application ID are owned by that application and are not tracked in MeshCore firmware or this document.</p>
<hr/>
<h3id="receive-channel-data-datagram">Receive Channel Data Datagram</h3>
<p>Inbound group datagrams (radio-level <code>PAYLOAD_TYPE_GRP_DATA</code>, 0x06) are forwarded to the host as <code>RESP_CODE_CHANNEL_DATA_RECV</code> notifications.</p>
Byte 1: SNR (signed int8, scaled ×4 — divide by 4.0 to recover dB)
Bytes 2-3: Reserved (clients MUST ignore)
Byte 4: Channel Index (0-7)
Byte 5: Path Length (actual path length when flooded, otherwise 0xFF for direct)
Bytes 6-7: Data Type (uint16 little-endian)
Byte 8: Data Length
Bytes 9 .. 8+data_len: Payload
</code></pre>
<p><strong>Path bytes are not forwarded</strong>: Only <code>path_len</code> is reported in the receive frame — the path itself is not copied to the host. There are no path bytes between byte 5 and the data_type field at bytes 6–7, regardless of <code>path_len</code>.</p>
<p><strong>Path Length semantics differ between send and receive</strong>:</p>
<td>Packet was flooded; this is the encoded <code>pkt->path_len</code> field as observed (no path bytes follow)</td>
</tr>
</tbody>
</table>
<p>In other words, the meaning of <code>0xFF</code> is inverted between the two directions, and on receive the field carries metadata only — never a routable path. <code>path_len</code> is an encoded byte (see <code>Packet::isValidPathLen</code> / <code>Packet::writePath</code> in <code>src/Packet.cpp</code>), not a raw byte count.</p>
<p><strong>Note</strong>: The device may also emit <code>PACKET_MESSAGES_WAITING</code> (0x83) to notify the host that datagrams are queued; poll with <code>CMD_SYNC_NEXT_MESSAGE</code> (0x0A) to retrieve them.</p>
- <code>PACKET_CHANNEL_MSG_RECV</code> (0x08) or <code>PACKET_CHANNEL_MSG_RECV_V3</code> (0x11) for channel messages
- <code>PACKET_CONTACT_MSG_RECV</code> (0x07) or <code>PACKET_CONTACT_MSG_RECV_V3</code> (0x10) for contact messages
- <code>PACKET_CHANNEL_DATA_RECV</code> (0x1B) for channel data datagrams
- <code>PACKET_NO_MORE_MSGS</code> (0x0A) if no messages available</p>
<p><strong>Note</strong>: Poll this command periodically to retrieve queued messages. The device may also send <code>PACKET_MESSAGES_WAITING</code> (0x83) as a notification when messages are available.</p>
<hr/>
<h3id="7-get-battery-and-storage">7. Get Battery and Storage</h3>
<h3id="8-get-battery-and-storage">8. Get Battery and Storage</h3>
<p><strong>Purpose</strong>: Query device battery voltage and storage usage.</p>
<p><strong>Command Format</strong>:</p>
<pre><code>Byte 0: 0x14
@ -2181,6 +2366,13 @@ Bytes 11+: Message Text (UTF-8)
- Include a chunk indicator (e.g., "[1/3] message text")</p>
<hr/>
<h2id="response-parsing">Response Parsing</h2>
<h3id="terminology">Terminology</h3>
<p>This document uses a spec-level naming convention (<code>PACKET_*</code>) for bytes the firmware sends back to the host. In the firmware source these same values are split across two <code>#define</code> families by purpose:</p>
<ul>
<li><code>RESP_CODE_*</code> — direct replies to a command (e.g. <code>RESP_CODE_CHANNEL_DATA_RECV</code> = <code>PACKET_CHANNEL_DATA_RECV</code> = 0x1B).</li>
<li><code>PUSH_CODE_*</code> — asynchronous notifications not tied to a specific command (e.g. <code>PUSH_CODE_MSG_WAITING</code> = <code>PACKET_MESSAGES_WAITING</code> = 0x83).</li>
</ul>
<p>Byte values are authoritative; names are aliases. When reading firmware source, <code>RESP_CODE_X</code> / <code>PUSH_CODE_X</code> correspond to this doc's <code>PACKET_X</code> of the same numeric value.</p>
<h3id="packet-types">Packet Types</h3>
<table>
<thead>
@ -2272,6 +2464,11 @@ Bytes 11+: Message Text (UTF-8)
<p><strong>PACKET_ERROR</strong> (0x01) may include an error code in byte 1:</p>
<p><code>PACKET_ERROR</code> (0x01) carries a single-byte error code in byte 1. Values match the <code>ERR_CODE_*</code> constants defined in <code>examples/companion_radio/MyMesh.cpp</code>:</p>
<table>
<thead>
<tr>
<th>Error Code</th>
<th>Code</th>
<th>Constant (firmware)</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>0x00</td>
<td>Generic error (no specific code)</td>
</tr>
<tr>
<td>0x01</td>
<td>Invalid command</td>
</tr>
<tr>
<td>0x02</td>
<td>Invalid parameter</td>
</tr>
<tr>
<td>0x03</td>
<td>Channel not found</td>
</tr>
<tr>
<td>0x04</td>
<td>Channel already exists</td>
<td>1</td>
<td><code>ERR_CODE_UNSUPPORTED_CMD</code></td>
<td>Unknown or unsupported command byte / sub-command</td>
</tr>
<tr>
<td>0x05</td>
<td>Channel index out of range</td>
<td>2</td>
<td><code>ERR_CODE_NOT_FOUND</code></td>
<td>Target not found (channel, contact, message, etc.)</td>
</tr>
<tr>
<td>0x06</td>
<td>Secret mismatch</td>
<td>3</td>
<td><code>ERR_CODE_TABLE_FULL</code></td>
<td>Internal queue or table is full — retry later</td>
</tr>
<tr>
<td>0x07</td>
<td>Message too long</td>
<td>4</td>
<td><code>ERR_CODE_BAD_STATE</code></td>
<td>Operation not valid in current device state (e.g. iterator already running)</td>
<p><strong>Note</strong>: Error codes may vary by firmware version. Always check byte 1 of <code>PACKET_ERROR</code> response.</p>
<p><strong>Note</strong>: Error codes may vary by firmware version. Always check byte 1 of <code>PACKET_ERROR</code> response, and treat unknown codes as generic errors.</p>
<h3id="frame-handling">Frame Handling</h3>
<p>BLE implementations enqueue and deliver one protocol frame per BLE write/notification at the firmware layer.</p>
| 0x42 | BOOT_PROTECT | Boot voltage protection triggered |</p>
<p>Shutdown reason codes (stored in GPREGRET2):</p>
<table>
<thead>
<tr>
<th>Code</th>
<th>Name</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>0x00</td>
<td>NONE</td>
<td>Normal boot / no previous shutdown</td>
</tr>
<tr>
<td>0x4C</td>
<td>LOW_VOLTAGE</td>
<td>Runtime low voltage threshold reached</td>
</tr>
<tr>
<td>0x55</td>
<td>USER</td>
<td>User requested powerOff()</td>
</tr>
<tr>
<td>0x42</td>
<td>BOOT_PROTECT</td>
<td>Boot voltage protection triggered</td>
</tr>
</tbody>
</table>
<h2id="supported-boards">Supported Boards</h2>
<table>
<thead>
@ -1292,25 +1317,115 @@
- Use 50mV hysteresis for noise immunity
- Wake the device from SYSTEMOFF when triggered</p>
<p>VBUS wake is enabled via the POWER peripheral USBDETECTED event whenever <code>configureVoltageWake()</code> is used. This requires USB VBUS to be routed to the nRF52 (typical on nRF52840 boards with native USB).</p>
<p>This document lists unique numbers/identifiers used in various MeshCore protcol payloads.</p>
<p>This document lists unique numbers/identifiers used in various MeshCore protocol payloads.</p>
<h1id="group-data-types">Group Data Types</h1>
<p>The <code>PAYLOAD_TYPE_GRP_DATA</code> payloads have a 16-bit data-type field, which identifies which application the packet is for.</p>
<p>To make sure multiple applications can function without interfering with each other, the table below is for reserving various ranges of data-type values. Just modify this table, adding a row, then submit a PR to have it authorised/merged.</p>
<p>An acknowledgement that a message was received. Note that for returned path messages, an acknowledgement can be sent in the "extra" payload (see <ahref="#returned-path">Returned Path</a>) instead of as a separate ackowledgement packet. CLI commands do not cause acknowledgement responses, neither discrete nor extra.</p>
<p>An acknowledgement that a message was received. Note that for returned path messages, an acknowledgement can be sent in the "extra" payload (see <ahref="#returned-path">Returned Path</a>) instead of as a separate acknowledgement packet. CLI commands do not cause acknowledgement responses, neither discrete nor extra.</p>
ripplebiz
7 hours ago