Merge pull request #3344 from robekl/docs/fix-stale-defaults

docs: correct stale defaults and stale references across docs 🤖🤖

README.md

@@ -123,6 +123,6 @@ There are a number of fairly major features in the pipeline, with no particular
 
 ## 📞 Get Support
 
-- Report bugs and request features on the [GitHub Issues](https://github.com/ripplebiz/MeshCore/issues) page.
+- Report bugs and request features on the [GitHub Issues](https://github.com/meshcore-dev/meshcore/issues) page.
 - Find additional guides and components on [my site](https://buymeacoffee.com/ripplebiz).
 - Join [MeshCore Discord](https://meshcore.gg) to chat with the developers and get help from the community.

docs/cli_commands.md

@@ -211,7 +211,7 @@ This document provides an overview of CLI commands that can be sent to MeshCore
 
 **Set by build flag:** `LORA_FREQ`, `LORA_BW`, `LORA_SF`, `LORA_CR`
 
-**Default:** `869.525,250,11,5`
+**Default:** `869.618,62.5,8,5`
 
 **Note:** Requires reboot to apply
 
@@ -256,7 +256,7 @@ This document provides an overview of CLI commands that can be sent to MeshCore
 **Parameters:**
 - `frequency`: Frequency in MHz
 
-**Default:** `869.525`
+**Default:** `869.618`
 
 **Note:** Requires reboot to apply
 **Serial Only:** `set freq <frequency>`
@@ -537,7 +537,7 @@ This document provides an overview of CLI commands that can be sent to MeshCore
 **Parameters:**
 - `value`: Direct transmit delay factor (0-2)
 
-**Default:** `0.2`
+**Default:** `0.3` (Repeater) - `0.2` (Room Server, Sensor)
 
 **Note:** Same collision-avoidance random window as `txdelay`, 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.
 
@@ -654,7 +654,7 @@ This document provides an overview of CLI commands that can be sent to MeshCore
 **Parameters:**
 - `hours`: Interval in hours (3-168)
 
-**Default:** `12` (Repeater) - `0` (Sensor)
+**Default:** `47` (Repeater, Room Server) - `0`, disabled (Sensor)
 
 ---
 
@@ -666,7 +666,12 @@ This document provides an overview of CLI commands that can be sent to MeshCore
 **Parameters:**
 - `minutes`: Interval in minutes rounded down to the nearest multiple of 2 (61 becomes 60) (60-240)
 
-**Default:** `0`
+**Default:** `2` on a factory-fresh node, then `0` (disabled) once configured.
+
+**Note:** A new install ships with a 2 minute zero-hop advert interval. Saving
+any setting resets an interval below the 60 minute minimum to `0`, on the
+assumption that the node has now been deliberately configured. To keep zero-hop
+adverts running, set an explicit value in the 60-240 range.
 
 ---
 

docs/companion_protocol.md

@@ -206,7 +206,7 @@ Byte 1: 0x03
 **Command Format**:
 ```
 Byte 0: 0x1F
-Byte 1: Channel Index (0-7)
+Byte 1: Channel Index (0 .. max_channels-1)
 ```
 
 **Example** (get channel 1):
@@ -225,7 +225,7 @@ Byte 1: Channel Index (0-7)
 **Command Format**:
 ```
 Byte 0: 0x20
-Byte 1: Channel Index (0-7)
+Byte 1: Channel Index (0 .. max_channels-1)
 Bytes 2-33: Channel Name (32 bytes, UTF-8, null-padded)
 Bytes 34-49: Secret (16 bytes)
 ```
@@ -233,8 +233,12 @@ Bytes 34-49: Secret (16 bytes)
 **Total Length**: 50 bytes
 
 **Channel Index**:
-- Index 0: Reserved for public channels (no secret)
+- Valid range is `0` to `max_channels - 1`. Read `max_channels` from byte 3 of
-- Indices 1-7: Available for private channels
+  the `PACKET_DEVICE_INFO` response; do not assume 8. Builds ship with
+  `MAX_GROUP_CHANNELS` set to 1, 8 or 40 depending on the board.
+- Index 0: pre-populated by the firmware with the built-in "Public" channel.
+  It can be overwritten like any other slot.
+- An out-of-range index is rejected with `PACKET_ERROR` / `ERR_CODE_NOT_FOUND`.
 
 **Channel Name**:
 - UTF-8 encoded
@@ -242,8 +246,18 @@ Bytes 34-49: Secret (16 bytes)
 - Padded with null bytes (0x00) if shorter
 
 **Secret Field** (16 bytes):
-- For **private channels**: 16-byte secret
+- Always a real 16-byte key; the firmware derives the channel hash from
-- For **public channels**: All zeros (0x00)
+  `SHA256(secret)` (`BaseChatMesh.cpp:936-942`). There is no "no secret" form.
+- Do **not** write an all-zero secret. `SHA256` over 16 zero bytes is a fixed,
+  globally identical value, so a zero-secret channel is a well-known channel
+  with an all-zero AES key that any node can read — not a private one. The
+  firmware skips *unnamed* slots when matching inbound group traffic for
+  exactly this reason (`BaseChatMesh.cpp:392-401`), but a slot that has been
+  given a name and a zero secret is not skipped, and will absorb null-key
+  group traffic from any node on the mesh.
+- The built-in public channel uses the well-known key
+  `izOH6cXN6mrJ5e26oRXNcg==` (base64), i.e.
+  `8b3387e9c5cdea6ac9e5edbaa115cd72` in hex.
 
 **Example** (create channel "YourChannelName" at index 1 with secret):
 ```
@@ -265,7 +279,7 @@ Bytes 34-49: Secret (16 bytes)
 ```
 Byte 0: 0x03
 Byte 1: 0x00
-Byte 2: Channel Index (0-7)
+Byte 2: Channel Index (0 .. max_channels-1)
 Bytes 3-6: Timestamp (32-bit little-endian Unix timestamp, seconds)
 Bytes 7+: Message Text (UTF-8, variable length)
 ```
@@ -288,7 +302,7 @@ Bytes 7+: Message Text (UTF-8, variable length)
 **Command Format**:
 ```
 Byte 0:                         0x3E
-Byte 1:                         Channel Index (0-7)
+Byte 1:                         Channel Index (0 .. max_channels-1)
 Byte 2:                         Path Length (0xFF = flood, otherwise actual path length)
 Bytes 3 .. 2+path_len:          Path (omitted when path_len == 0xFF)
 Next 2 bytes (little-endian):   Data Type (`data_type`, uint16)
@@ -306,13 +320,23 @@ Remaining bytes:                Binary payload (variable length)
 - Values `0x0001`–`0xFFFE` are available for registered application/community namespaces. See the [Registered data_type values](#registered-data_type-values) table below.
 
 **Limits**:
-- Maximum payload length is `MAX_CHANNEL_DATA_LENGTH = MAX_FRAME_SIZE - 9 = 163` bytes.
+- Maximum payload length is **165** bytes — `MAX_GROUP_DATA_LENGTH =
-- Larger payloads are rejected with `PACKET_ERROR` (`ERR_CODE_ILLEGAL_ARG`).
+  MAX_PACKET_PAYLOAD - CIPHER_BLOCK_SIZE - 3` (`src/MeshCore.h:21`). This is the
+  radio-side limit and the one clients should enforce.
+- Two different bounds are checked, and they do not agree. The host-frame check
+  uses the larger `MAX_CHANNEL_DATA_LENGTH = MAX_FRAME_SIZE - 9 = 167`
+  (`companion_radio/MyMesh.cpp:1265`); the radio-side check uses 165
+  (`BaseChatMesh.cpp:544`).
+- Payloads **above 167** are rejected with `ERR_CODE_ILLEGAL_ARG` (6).
+- Payloads of **166 or 167** pass the frame check, then fail the radio-side
+  check and return `ERR_CODE_TABLE_FULL` (3). Despite that code's usual
+  meaning, such a send can never succeed — do not retry it. Keep payloads at
+  165 bytes or fewer and this case cannot arise.
 
 **Response**: `PACKET_OK` (0x00) on success, or `PACKET_ERROR` (0x01) with one of:
 - `ERR_CODE_NOT_FOUND` (2) — unknown `channel_idx`
-- `ERR_CODE_ILLEGAL_ARG` (6) — invalid `path_len`, reserved `data_type` (`0x0000`), or payload larger than `MAX_CHANNEL_DATA_LENGTH`
+- `ERR_CODE_ILLEGAL_ARG` (6) — invalid `path_len`, reserved `data_type` (`0x0000`), or payload larger than `MAX_CHANNEL_DATA_LENGTH` (167)
-- `ERR_CODE_TABLE_FULL` (3) — outbound send queue is full; retry later
+- `ERR_CODE_TABLE_FULL` (3) — outbound send queue is full (retry later), **or** a payload of 166-167 bytes that exceeds the radio-side limit (permanent; see Limits above)
 
 **Inbound datagrams** are delivered to the host via `RESP_CODE_CHANNEL_DATA_RECV` (0x1B); see [Receive Channel Data Datagram](#receive-channel-data-datagram).
 
@@ -341,7 +365,7 @@ Inbound group datagrams (radio-level `PAYLOAD_TYPE_GRP_DATA`, 0x06) are forwarde
 Byte 0:                 0x1B (packet type)
 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 4:                 Channel Index (0 .. max_channels-1)
 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
@@ -550,7 +574,7 @@ def parse_contact_message(data):
 **Standard Format** (`PACKET_CHANNEL_MSG_RECV`, 0x08):
 ```
 Byte 0: 0x08 (packet type)
-Byte 1: Channel Index (0-7)
+Byte 1: Channel Index (0 .. max_channels-1)
 Byte 2: Path Length
 Byte 3: Text Type
 Bytes 4-7: Timestamp (32-bit little-endian)
@@ -562,7 +586,7 @@ Bytes 8+: Message Text (UTF-8)
 Byte 0: 0x11 (packet type)
 Byte 1: SNR (signed byte, multiplied by 4)
 Bytes 2-3: Reserved
-Byte 4: Channel Index (0-7)
+Byte 4: Channel Index (0 .. max_channels-1)
 Byte 5: Path Length
 Byte 6: Text Type
 Bytes 7-10: Timestamp (32-bit little-endian)

docs/faq.md

@@ -537,18 +537,18 @@ Mac: python3 should be already installed.
 
 Then it should be the same for all platforms:
 ```
-python3 -m venv meshcore
+python3 -m venv meshcore-venv
-cd meshcore && source bin/activate
+cd meshcore-venv && source bin/activate
 pip install -U platformio
-git clone https://github.com/ripplebiz/MeshCore.git
+git clone https://github.com/meshcore-dev/meshcore.git
-cd MeshCore
+cd meshcore
 ```
-open platformio.ini and in `[arduino_base]` edit the `LORA_FREQ=867.5`
+open platformio.ini and in `[arduino_base]` edit `LORA_FREQ` (it defaults to
-save, then run:
+`869.618`) to the frequency for your region, save, then run:
 ```
-pio run -e RAK_4631_Repeater
+pio run -e RAK_4631_repeater
 ```
-then you'll find `firmware.zip` in `.pio/build/RAK_4631_Repeater`
+then you'll find `firmware.zip` in `.pio/build/RAK_4631_repeater`
 
 ### 5.10. Q: Are there other MeshCore related open source projects?
 
@@ -592,7 +592,7 @@ For ESP-based devices (e.g. Heltec V3) you need:
 1. Download the firmware file from <https://flasher.meshcore.io>.
     - Go to the website in a browser and find the section that has the firmware you need.
     - Click the Download button, right-click on the file you need, for example:
-        - `Heltec_V3_companion_radio_ble-v1.7.1-165fb33.bin`
+        - `Heltec_v3_companion_radio_ble-v1.7.1-165fb33.bin`
             - Non-merged bin keeps the existing Bluetooth pairing database.
         - `Heltec_v3_companion_radio_usb-v1.7.1-165fb33-merged.bin`
             - Merged bin overwrites everything including the bootloader and existing Bluetooth pairing database, but keeps configurations.

docs/nrf52_power_management.md

@@ -186,11 +186,19 @@ Power management status can be queried via the CLI:
 | `get pwrmgt.bootreason` | Returns reset and shutdown reason strings                             |
 | `get pwrmgt.bootmv`     | Returns boot voltage in millivolts                                    |
 
-On boards without power management enabled, all commands except `get pwrmgt.support` return:
+On boards without power management enabled, `get pwrmgt.source` and
+`get pwrmgt.bootmv` return:
 ```
 ERROR: Power management not supported
 ```
 
+`get pwrmgt.support` returns `unsupported`. `get pwrmgt.bootreason` is not
+compiled out at all and answers on every board: `getResetReason()` and
+`getShutdownReason()` are virtuals on the base board class, so a board that
+does not override them reports `Not available` rather than an error. ESP32
+boards override the reset half with `esp_reset_reason()`, so they return a real
+reset reason and `Not available` for the shutdown reason.
+
 ## Debug Output
 
 When `MESH_DEBUG=1` is enabled, the power management module outputs:

docs/terminal_chat_cli.md

@@ -27,15 +27,17 @@ set lon {longitude}
 ```
 Sets your advertisement map longitude. (decimal degrees)
 
-```
-set dutycycle {percent}
-```
-Sets the transmit duty cycle limit (1-100%). Example: `set dutycycle 10` for 10%.
-
 ```
 set af {air-time-factor}
 ```
-Sets the transmit air-time-factor. Deprecated — use `set dutycycle` instead.
+Sets the transmit air-time-factor.
+
+> **Note:** `set dutycycle` is *not* available in Terminal Chat. Every other
+> firmware — Repeater, Room Server, Sensor and Companion Radio — routes its
+> `set`/`get` commands through the shared radio prefs handler and does support
+> it (see [CLI Commands](./cli_commands.md)). Terminal Chat is the sole
+> exception: it has its own inline `set` handler covering only the six options
+> listed above.
 
 
 ```
@@ -99,3 +101,8 @@ Resets the path to current recipient, for new path discovery.
 public {text}
 ```
 Sends the text message to the built-in 'public' group channel
+
+```
+help
+```
+Lists the available commands.