mirror
/
MeshCore
mirror of https://github.com/meshcore-dev/MeshCore
1
0
Fork 0
Code Issues Projects Releases Wiki Activity
Browse Source

docs: fix broken and misaligned tables

pull/2635/head
Sefinek 2 months ago
parent
888ad4589c
commit
2adea02e9c
7 changed files with 315 additions and 313 deletions
Whitespace
Show all changes Ignore whitespace when comparing lines Ignore changes in amount of whitespace Ignore changes in whitespace at EOL
Unified View
Diff Options
Show Stats Download Patch File Download Diff File
  1. 4
      docs/companion_protocol.md
  2. 46
      docs/faq.md
  3. 36
      docs/kiss_modem_protocol.md
  4. 8
      docs/nrf52_power_management.md
  5. 6
      docs/packet_format.md
  6. 20
      docs/payloads.md
  7. 10
      docs/stats_binary_frames.md

4
docs/companion_protocol.md
View File

@ -321,7 +321,7 @@ Remaining bytes: Binary payload (variable length)
`data_type` is an **application identifier**, 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 — `data_type` is transported opaquely. `data_type` is an **application identifier**, 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 — `data_type` is transported opaquely.
| Value | Constant | Purpose | | Value | Constant | Purpose |
|-----------------|----------------------|--------------------------------------------------------------------------| |-----------------|----------------------|----------------------------------------------------------------------------------------|
| 0x0000 | `DATA_TYPE_RESERVED` | Reserved; invalid on send | | 0x0000 | `DATA_TYPE_RESERVED` | Reserved; invalid on send |
| 0x0001 – 0x00FF | — | Reserved for internal use | | 0x0001 – 0x00FF | — | Reserved for internal use |
| 0x0100 – 0xFEFF | — | Registered application namespaces (see [number_allocations.md](number_allocations.md)) | | 0x0100 – 0xFEFF | — | Registered application namespaces (see [number_allocations.md](number_allocations.md)) |
@ -353,7 +353,7 @@ Bytes 9 .. 8+data_len: Payload
**Path Length semantics differ between send and receive**: **Path Length semantics differ between send and receive**:
| Direction | `path_len = 0xFF` | `path_len ≠ 0xFF` | | Direction | `path_len = 0xFF` | `path_len ≠ 0xFF` |
|-----------|---------------------------------|-------------------------------------------------------------------------------------| |-----------|---------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------|
| Send | Flood the network | Direct route; the encoded path follows (low 6 bits = hash count, top 2 bits + 1 = hash size; on-wire byte count = `hash_count × hash_size`) | | Send | Flood the network | Direct route; the encoded path follows (low 6 bits = hash count, top 2 bits + 1 = hash size; on-wire byte count = `hash_count × hash_size`) |
| Receive | Packet arrived via direct route | Packet was flooded; this is the encoded `pkt->path_len` field as observed (no path bytes follow) | | Receive | Packet arrived via direct route | Packet was flooded; this is the encoded `pkt->path_len` field as observed (no path bytes follow) |

46
docs/faq.md
View File

@ -717,15 +717,15 @@ You can get the epoch time on <https://www.epochconverter.com/> and use it to se
- For T1000-e, quickly disconnect and reconnect the magnetic side of the cable from the device **TWICE** - For T1000-e, quickly disconnect and reconnect the magnetic side of the cable from the device **TWICE**
- For Heltec T114, click the reset button **TWICE** (the bottom button) - For Heltec T114, click the reset button **TWICE** (the bottom button)
- For Xiao nRF52, click the reset button once. If that doesn't work, quickly double click the reset button twice. If that doesn't work, disconnect the board from your PC and reconnect again ([seeed studio wiki](https://wiki.seeedstudio.com/XIAO_BLE/#access-the-swd-pins-for-debugging-and-reflashing-bootloader)) - For Xiao nRF52, click the reset button once. If that doesn't work, quickly double click the reset button twice. If that doesn't work, disconnect the board from your PC and reconnect again ([seeed studio wiki](https://wiki.seeedstudio.com/XIAO_BLE/#access-the-swd-pins-for-debugging-and-reflashing-bootloader))
5. A new folder will appear on your computer's desktop 2. A new folder will appear on your computer's desktop
6. Download the `flash_erase*.uf2` file for your device on https://flasher.meshcore.io 3. Download the `flash_erase*.uf2` file for your device on https://flasher.meshcore.io
- RAK WisBlock and Heltec T114: `Flash_erase-nRF32_softdevice_v6.uf2` - RAK WisBlock and Heltec T114: `Flash_erase-nRF32_softdevice_v6.uf2`
- Seeed Studio Xiao nRF52 WIO: `Flash_erase-nRF52_softdevice_v7.uf2` - Seeed Studio Xiao nRF52 WIO: `Flash_erase-nRF52_softdevice_v7.uf2`
8. drag and drop the uf2 file for your device to the root of the new folder 4. drag and drop the uf2 file for your device to the root of the new folder
9. Wait for the copy to complete. You might get an error dialog, you can ignore it 5. Wait for the copy to complete. You might get an error dialog, you can ignore it
10. Go to https://flasher.meshcore.io, click `Console` and select the serial port for your connected device 6. Go to https://flasher.meshcore.io, click `Console` and select the serial port for your connected device
11. In the console, press enter. Your flash should now be erased 7. In the console, press enter. Your flash should now be erased
12. You may now flash the latest MeshCore firmware onto your device 8. You may now flash the latest MeshCore firmware onto your device
Separately, starting in firmware version 1.7.0, there is a CLI Rescue mode. If your device has a user button (e.g. some RAK, T114), you can activate the rescue mode by hold down the user button of the device within 8 seconds of boot. Then you can use the 'Console' on https://flasher.meshcore.io Separately, starting in firmware version 1.7.0, there is a CLI Rescue mode. If your device has a user button (e.g. some RAK, T114), you can activate the rescue mode by hold down the user button of the device within 8 seconds of boot. Then you can use the 'Console' on https://flasher.meshcore.io
@ -751,15 +751,15 @@ Allow the browser user on it:
5. you should see `OK` to confirm the repeater device is now in OTA mode 5. you should see `OK` to confirm the repeater device is now in OTA mode
6. Run the DFU app,tab `Settings` on the top right corner 6. Run the DFU app,tab `Settings` on the top right corner
7. Enable `Packets receipt notifications`, and change `Number of Packets` to 10 for RAK, 8 for T114. 8 also works for RAK. 7. Enable `Packets receipt notifications`, and change `Number of Packets` to 10 for RAK, 8 for T114. 8 also works for RAK.
9. Select the firmware zip file you downloaded 8. Select the firmware zip file you downloaded
10. Select the device you want to update. If the device you want to update is not on the list, try enabling`OTA` on the device again 9. Select the device you want to update. If the device you want to update is not on the list, try enabling`OTA` on the device again
11. If the device is not found, enable `Force Scanning` in the DFU app 10. If the device is not found, enable `Force Scanning` in the DFU app
12. Tab the `Upload` to begin OTA update 11. Tab the `Upload` to begin OTA update
13. If it fails, try turning off and on Bluetooth on your phone. If that doesn't work, try rebooting your phone. If you keep getting failures at the "Enabling Bootloader" step, try forgetting the NRF board in your iOS or Android device's bluetooth settings and re-pair it through the DFU app. 12. If it fails, try turning off and on Bluetooth on your phone. If that doesn't work, try rebooting your phone. If you keep getting failures at the "Enabling Bootloader" step, try forgetting the NRF board in your iOS or Android device's bluetooth settings and re-pair it through the DFU app.
14. Wait for the update to complete. It can take a few minutes. 13. Wait for the update to complete. It can take a few minutes.
15. It is strongly recommended that you install and use the OTAFIX bootloader at https://github.com/oltaco/Adafruit_nRF52_Bootloader_OTAFIX. 14. It is strongly recommended that you install and use the OTAFIX bootloader at https://github.com/oltaco/Adafruit_nRF52_Bootloader_OTAFIX.
16. To update a companion node over OTA, it must be running companion firmware v1.15 or greater. 15. To update a companion node over OTA, it must be running companion firmware v1.15 or greater.
17. Please see the MeshCore Blog for additional information on OTA firmware flashing: 16. Please see the MeshCore Blog for additional information on OTA firmware flashing:
- https://blog.meshcore.io/2026/04/06/otafix-bootloader - https://blog.meshcore.io/2026/04/06/otafix-bootloader
- https://blog.meshcore.io/2026/04/02/nrf-ota-update - https://blog.meshcore.io/2026/04/02/nrf-ota-update
@ -776,11 +776,11 @@ After this bootloader is flashed onto the device, you can trigger over the air u
**A:** For ESP32-based devices (e.g. Heltec V3): **A:** For ESP32-based devices (e.g. Heltec V3):
1. On https://flasher.meshcore.io, download the **non-merged** version of the firmware for your ESP32 device (e.g. `Heltec_v3_repeater-v1.6.2-4449fd3.bin`, no `"merged"` in the file name) 1. On https://flasher.meshcore.io, download the **non-merged** version of the firmware for your ESP32 device (e.g. `Heltec_v3_repeater-v1.6.2-4449fd3.bin`, no `"merged"` in the file name)
2. From the MeshCore app, login remotely to the repeater you want to update with admin privilege 2. From the MeshCore app, login remotely to the repeater you want to update with admin privilege
4. Go to the Command Line tab, type `start ota` and hit enter. 3. Go to the Command Line tab, type `start ota` and hit enter.
5. you should see `OK` to confirm the repeater device is now in OTA mode 4. you should see `OK` to confirm the repeater device is now in OTA mode
6. The command `start ota` on an ESP32-based device starts a Wi-Fi hotspot named `MeshCore OTA` 5. The command `start ota` on an ESP32-based device starts a Wi-Fi hotspot named `MeshCore OTA`
7. From your phone or computer connect to the 'MeshCore OTA' hotspot 6. From your phone or computer connect to the 'MeshCore OTA' hotspot
8. From a browser, go to http://192.168.4.1/update and upload the non-merged bin from the flasher 7. From a browser, go to http://192.168.4.1/update and upload the non-merged bin from the flasher
### 7.3. Q: Is there a way to lower the chance of a failed OTA device firmware update (DFU)? ### 7.3. Q: Is there a way to lower the chance of a failed OTA device firmware update (DFU)?
@ -821,7 +821,7 @@ where `&type` is:
### 7.6. Q: How do I connect to the companion via Wi-Fi, e.g. using a heltec v3? ### 7.6. Q: How do I connect to the companion via Wi-Fi, e.g. using a heltec v3?
**A:** **A:**
Wi-Fi firmware requires you to compile it yourself, as you need to set the wifi ssid and password. Wi-Fi firmware requires you to compile it yourself, as you need to set the Wi-Fi ssid and password.
Edit WIFI_SSID and WIFI_PWD in `./variants/heltec_v3/platformio.ini` and then flash it to your device. Edit WIFI_SSID and WIFI_PWD in `./variants/heltec_v3/platformio.ini` and then flash it to your device.
### 7.7. Q: I have a Station G2, or a Heltec V4, or an Ikoka Stick, or a radio with a EByte E22-900M30S or a E22-900M33S module, what should their transmit power be set to? ### 7.7. Q: I have a Station G2, or a Heltec V4, or an Ikoka Stick, or a radio with a EByte E22-900M30S or a E22-900M33S module, what should their transmit power be set to?
@ -832,7 +832,7 @@ For companion radios, you can set these radios' transmit power in the smartphone
⚠️ **WARNING: Set these values at your own risk. Incorrect power settings can permanently damage your radio hardware.** ⚠️ **WARNING: Set these values at your own risk. Incorrect power settings can permanently damage your radio hardware.**
| Device / Model | Region / Description | In-App Setting (dBm) | Target Radio Output | Notes | | Device / Model | Region / Description | In-App Setting (dBm) | Target Radio Output | Notes |
| :--- | :--- | :--- | :--- | :--- | |:-----------------------------------------------------------------------------------|:------------------------------------|:---------------------|:-----------------------|:-----------------------------------------------------------------------------------------------------------------------------------------------|
| **Station G2** <br> [Reference](https://wiki.uniteng.com/en/meshtastic/station-g2) | US915 Max Output | 19 dBm | 36.5 dBm (4.46W) | | | **Station G2** <br> [Reference](https://wiki.uniteng.com/en/meshtastic/station-g2) | US915 Max Output | 19 dBm | 36.5 dBm (4.46W) | |
| | US915 Max at 1dB compression point | 16 dBm | 35 dBm (3.16W) | 1dB compression point | | | US915 Max at 1dB compression point | 16 dBm | 35 dBm (3.16W) | 1dB compression point |
| | EU868 Max at 1dB compression point | 15 dBm | 34.5 dBm (2.82W) | 1dB compression point | | | EU868 Max at 1dB compression point | 15 dBm | 34.5 dBm (2.82W) | 1dB compression point |

36
docs/kiss_modem_protocol.md
View File

@ -11,7 +11,7 @@ Standard KISS TNC firmware for MeshCore LoRa radios. Compatible with any KISS cl
Standard KISS framing per the KA9Q/K3MC specification. Standard KISS framing per the KA9Q/K3MC specification.
| Byte | Name | Description | | Byte | Name | Description |
|------|------|-------------| |--------|-------|------------------------------------|
| `0xC0` | FEND | Frame delimiter | | `0xC0` | FEND | Frame delimiter |
| `0xDB` | FESC | Escape character | | `0xDB` | FESC | Escape character |
| `0xDC` | TFEND | Escaped FEND (FESC + TFEND = 0xC0) | | `0xDC` | TFEND | Escaped FEND (FESC + TFEND = 0xC0) |
@ -29,7 +29,7 @@ Standard KISS framing per the KA9Q/K3MC specification.
The type byte is split into two nibbles: The type byte is split into two nibbles:
| Bits | Field | Description | | Bits | Field | Description |
|------|-------|-------------| |------|---------|-------------------------------------|
| 7-4 | Port | Port number (0 for single-port TNC) | | 7-4 | Port | Port number (0 for single-port TNC) |
| 3-0 | Command | Command number | | 3-0 | Command | Command number |
@ -40,7 +40,7 @@ Maximum unescaped frame size: 512 bytes.
### Host to TNC ### Host to TNC
| Command | Value | Data | Description | | Command | Value | Data | Description |
|---------|-------|------|-------------| |-------------|--------|--------------------|-------------------------------------------------------------|
| Data | `0x00` | Raw packet | Queue packet for transmission | | Data | `0x00` | Raw packet | Queue packet for transmission |
| TXDELAY | `0x01` | Delay (1 byte) | Transmitter keyup delay in 10ms units (default: 50 = 500ms) | | TXDELAY | `0x01` | Delay (1 byte) | Transmitter keyup delay in 10ms units (default: 50 = 500ms) |
| Persistence | `0x02` | P (1 byte) | CSMA persistence parameter 0-255 (default: 63) | | Persistence | `0x02` | P (1 byte) | CSMA persistence parameter 0-255 (default: 63) |
@ -53,7 +53,7 @@ Maximum unescaped frame size: 512 bytes.
### TNC to Host ### TNC to Host
| Type | Value | Data | Description | | Type | Value | Data | Description |
|------|-------|------|-------------| |------|--------|------------|----------------------------|
| Data | `0x00` | Raw packet | Received packet from radio | | Data | `0x00` | Raw packet | Received packet from radio |
Data frames carry raw packet data only, with no metadata prepended. The Data command payload is limited to 255 bytes to match the MeshCore maximum transmission unit (MAX_TRANS_UNIT); frames larger than 255 bytes are silently dropped. The KISS specification recommends at least 1024 bytes for general-purpose TNCs; this modem is intended for MeshCore packets only, whose protocol MTU is 255 bytes. Data frames carry raw packet data only, with no metadata prepended. The Data command payload is limited to 255 bytes to match the MeshCore maximum transmission unit (MAX_TRANS_UNIT); frames larger than 255 bytes are silently dropped. The KISS specification recommends at least 1024 bytes for general-purpose TNCs; this modem is intended for MeshCore packets only, whose protocol MTU is 255 bytes.
@ -85,7 +85,7 @@ MeshCore-specific functionality uses the standard KISS SetHardware command. The
### Request Sub-commands (Host to TNC) ### Request Sub-commands (Host to TNC)
| Sub-command | Value | Data | | Sub-command | Value | Data |
|-------------|-------|------| |-----------------|--------|------------------------------------------|
| GetIdentity | `0x01` | - | | GetIdentity | `0x01` | - |
| GetRandom | `0x02` | Length (1 byte, 1-64) | | GetRandom | `0x02` | Length (1 byte, 1-64) |
| VerifySignature | `0x03` | PubKey (32) + Signature (64) + Data | | VerifySignature | `0x03` | PubKey (32) + Signature (64) + Data |
@ -118,7 +118,7 @@ MeshCore-specific functionality uses the standard KISS SetHardware command. The
Response codes use the high-bit convention: `response = command | 0x80`. Generic and unsolicited responses use the `0xF0`+ range. Response codes use the high-bit convention: `response = command | 0x80`. Generic and unsolicited responses use the `0xF0`+ range.
| Sub-command | Value | Data | | Sub-command | Value | Data |
|-------------|-------|------| |--------------|--------|-----------------------------------------|
| Identity | `0x81` | PubKey (32) | | Identity | `0x81` | PubKey (32) |
| Random | `0x82` | Random bytes (1-64) | | Random | `0x82` | Random bytes (1-64) |
| Verify | `0x83` | Result (1): 0x00=invalid, 0x01=valid | | Verify | `0x83` | Result (1): 0x00=invalid, 0x01=valid |
@ -149,7 +149,7 @@ Response codes use the high-bit convention: `response = command | 0x80`. Generic
### Error Codes ### Error Codes
| Code | Value | Description | | Code | Value | Description |
|------|-------|-------------| |---------------|--------|-------------------------|
| InvalidLength | `0x01` | Request data too short | | InvalidLength | `0x01` | Request data too short |
| InvalidParam | `0x02` | Invalid parameter value | | InvalidParam | `0x02` | Invalid parameter value |
| NoCallback | `0x03` | Feature not available | | NoCallback | `0x03` | Feature not available |
@ -173,7 +173,7 @@ The TNC sends these SetHardware frames without a preceding request:
All values little-endian. All values little-endian.
| Field | Size | Description | | Field | Size | Description |
|-------|------|-------------| |-----------|---------|-------------------------|
| Frequency | 4 bytes | Hz (e.g., 869618000) | | Frequency | 4 bytes | Hz (e.g., 869618000) |
| Bandwidth | 4 bytes | Hz (e.g., 62500) | | Bandwidth | 4 bytes | Hz (e.g., 62500) |
| SF | 1 byte | Spreading factor (5-12) | | SF | 1 byte | Spreading factor (5-12) |
@ -182,14 +182,14 @@ All values little-endian.
### Version (Version response) ### Version (Version response)
| Field | Size | Description | | Field | Size | Description |
|-------|------|-------------| |----------|--------|------------------|
| Version | 1 byte | Firmware version | | Version | 1 byte | Firmware version |
| Reserved | 1 byte | Always 0 | | Reserved | 1 byte | Always 0 |
### Encrypted (Encrypted response) ### Encrypted (Encrypted response)
| Field | Size | Description | | Field | Size | Description |
|-------|------|-------------| |------------|----------|------------------------------------------------|
| MAC | 2 bytes | HMAC-SHA256 truncated to 2 bytes | | MAC | 2 bytes | HMAC-SHA256 truncated to 2 bytes |
| Ciphertext | variable | AES-128 block-encrypted data with zero padding | | Ciphertext | variable | AES-128 block-encrypted data with zero padding |
@ -198,7 +198,7 @@ All values little-endian.
All values little-endian. All values little-endian.
| Field | Size | Description | | Field | Size | Description |
|-------|------|-------------| |---------|---------|----------------------------------------------|
| Airtime | 4 bytes | uint32_t, estimated air time in milliseconds | | Airtime | 4 bytes | uint32_t, estimated air time in milliseconds |
### Noise Floor (NoiseFloor response) ### Noise Floor (NoiseFloor response)
@ -206,7 +206,7 @@ All values little-endian.
All values little-endian. All values little-endian.
| Field | Size | Description | | Field | Size | Description |
|-------|------|-------------| |-------------|---------|-----------------------|
| Noise floor | 2 bytes | int16_t, dBm (signed) | | Noise floor | 2 bytes | int16_t, dBm (signed) |
The modem recalibrates the noise floor every 2 seconds with an AGC reset every 30 seconds. The modem recalibrates the noise floor every 2 seconds with an AGC reset every 30 seconds.
@ -216,7 +216,7 @@ The modem recalibrates the noise floor every 2 seconds with an AGC reset every 3
All values little-endian. All values little-endian.
| Field | Size | Description | | Field | Size | Description |
|-------|------|-------------| |--------|---------|---------------------|
| RX | 4 bytes | Packets received | | RX | 4 bytes | Packets received |
| TX | 4 bytes | Packets transmitted | | TX | 4 bytes | Packets transmitted |
| Errors | 4 bytes | Receive errors | | Errors | 4 bytes | Receive errors |
@ -226,7 +226,7 @@ All values little-endian.
All values little-endian. All values little-endian.
| Field | Size | Description | | Field | Size | Description |
|-------|------|-------------| |------------|---------|---------------------------------|
| Millivolts | 2 bytes | uint16_t, battery voltage in mV | | Millivolts | 2 bytes | uint16_t, battery voltage in mV |
### MCU Temperature (MCUTemp response) ### MCU Temperature (MCUTemp response)
@ -234,7 +234,7 @@ All values little-endian.
All values little-endian. All values little-endian.
| Field | Size | Description | | Field | Size | Description |
|-------|------|-------------| |-------------|---------|--------------------------------------------|
| Temperature | 2 bytes | int16_t, tenths of °C (e.g., 253 = 25.3°C) | | Temperature | 2 bytes | int16_t, tenths of °C (e.g., 253 = 25.3°C) |
Returns `NoCallback` error if the board does not support temperature readings. Returns `NoCallback` error if the board does not support temperature readings.
@ -242,7 +242,7 @@ Returns `NoCallback` error if the board does not support temperature readings.
### Device Name (DeviceName response) ### Device Name (DeviceName response)
| Field | Size | Description | | Field | Size | Description |
|-------|------|-------------| |-------|----------|----------------------------------|
| Name | variable | UTF-8 string, no null terminator | | Name | variable | UTF-8 string, no null terminator |
### Reboot ### Reboot
@ -252,7 +252,7 @@ Sends an `OK` response, flushes serial, then reboots the device. The host should
### Sensor Permissions (GetSensors) ### Sensor Permissions (GetSensors)
| Bit | Value | Description | | Bit | Value | Description |
|-----|-------|-------------| |-----|--------|----------------------------------------|
| 0 | `0x01` | Base (battery) | | 0 | `0x01` | Base (battery) |
| 1 | `0x02` | Location (GPS) | | 1 | `0x02` | Location (GPS) |
| 2 | `0x04` | Environment (temp, humidity, pressure) | | 2 | `0x04` | Environment (temp, humidity, pressure) |
@ -266,7 +266,7 @@ Data returned in CayenneLPP format. See [CayenneLPP documentation](https://docs.
## Cryptographic Algorithms ## Cryptographic Algorithms
| Operation | Algorithm | | Operation | Algorithm |
|-----------|-----------| |-----------------------------------|-------------------------------------------------------------------------------------|
| Identity / Signing / Verification | Ed25519 | | Identity / Signing / Verification | Ed25519 |
| Key Exchange | X25519 (ECDH) | | Key Exchange | X25519 (ECDH) |
| Encryption | AES-128 block encryption with zero padding + HMAC-SHA256 (MAC truncated to 2 bytes) | | Encryption | AES-128 block encryption with zero padding + HMAC-SHA256 (MAC truncated to 2 bytes) |

8
docs/nrf52_power_management.md
View File

@ -24,8 +24,9 @@ The nRF52 Power Management module provides battery protection features to preven
### Shutdown Reason Tracking ### Shutdown Reason Tracking
Shutdown reason codes (stored in GPREGRET2): Shutdown reason codes (stored in GPREGRET2):
| Code | Name | Description | | Code | Name | Description |
|------|------|-------------| |------|--------------|---------------------------------------|
| 0x00 | NONE | Normal boot / no previous shutdown | | 0x00 | NONE | Normal boot / no previous shutdown |
| 0x4C | LOW_VOLTAGE | Runtime low voltage threshold reached | | 0x4C | LOW_VOLTAGE | Runtime low voltage threshold reached |
| 0x55 | USER | User requested powerOff() | | 0x55 | USER | User requested powerOff() |
@ -35,7 +36,7 @@ Shutdown reason codes (stored in GPREGRET2):
| Board | Implemented | LPCOMP wake | VBUS wake | | Board | Implemented | LPCOMP wake | VBUS wake |
|-------|-------------|-------------|-----------| |-------------------------------------------|-------------|-------------|-----------|
| Seeed Studio XIAO nRF52840 (`xiao_nrf52`) | Yes | Yes | Yes | | Seeed Studio XIAO nRF52840 (`xiao_nrf52`) | Yes | Yes | Yes |
| RAK4631 (`rak4631`) | Yes | Yes | Yes | | RAK4631 (`rak4631`) | Yes | Yes | Yes |
| Heltec T114 (`heltec_t114`) | Yes | Yes | Yes | | Heltec T114 (`heltec_t114`) | Yes | Yes | Yes |
@ -143,6 +144,7 @@ The LPCOMP (Low Power Comparator) is configured to:
VBUS wake is enabled via the POWER peripheral USBDETECTED event whenever `configureVoltageWake()` is used. This requires USB VBUS to be routed to the nRF52 (typical on nRF52840 boards with native USB). VBUS wake is enabled via the POWER peripheral USBDETECTED event whenever `configureVoltageWake()` is used. This requires USB VBUS to be routed to the nRF52 (typical on nRF52840 boards with native USB).
**LPCOMP Reference Selection (PWRMGT_LPCOMP_REFSEL)**: **LPCOMP Reference Selection (PWRMGT_LPCOMP_REFSEL)**:
| REFSEL | Fraction | VBAT @ 1M/1M divider (VDD=3.0-3.3) | VBAT @ 1.5M/1M divider (VDD=3.0-3.3) | | REFSEL | Fraction | VBAT @ 1M/1M divider (VDD=3.0-3.3) | VBAT @ 1.5M/1M divider (VDD=3.0-3.3) |
|--------|----------|------------------------------------|--------------------------------------| |--------|----------|------------------------------------|--------------------------------------|
| 0 | 1/8 | 0.75-0.82 V | 0.94-1.03 V | | 0 | 1/8 | 0.75-0.82 V | 0.94-1.03 V |
@ -178,7 +180,7 @@ This ensures compatibility regardless of BLE stack state.
Power management status can be queried via the CLI: Power management status can be queried via the CLI:
| Command | Description | | Command | Description |
|---------|-------------| |-------------------------|-----------------------------------------------------------------------|
| `get pwrmgt.support` | Returns "supported" or "unsupported" | | `get pwrmgt.support` | Returns "supported" or "unsupported" |
| `get pwrmgt.source` | Returns current power source - "battery" or "external" (5V/USB power) | | `get pwrmgt.source` | Returns current power source - "battery" or "external" (5V/USB power) |
| `get pwrmgt.bootreason` | Returns reset and shutdown reason strings | | `get pwrmgt.bootreason` | Returns reset and shutdown reason strings |

6
docs/packet_format.md
View File

@ -68,7 +68,7 @@ This is the protocol level packet structure used in MeshCore firmware v1.12.0
### Packet Format ### Packet Format
| Field | Size (bytes) | Description | | Field | Size (bytes) | Description |
|-----------------|----------------------------------|----------------------------------------------------------| |-----------------|----------------------------------|-----------------------------------------------------------------|
| header | 1 | Contains routing type, payload type, and payload version | | header | 1 | Contains routing type, payload type, and payload version |
| transport_codes | 4 (optional) | 2x 16-bit transport codes (if ROUTE_TYPE_TRANSPORT_*) | | transport_codes | 4 (optional) | 2x 16-bit transport codes (if ROUTE_TYPE_TRANSPORT_*) |
| path_length | 1 | Encodes path hash size in bits 6-7 and hop count in bits 0-5 | | path_length | 1 | Encodes path hash size in bits 6-7 and hop count in bits 0-5 |
@ -101,14 +101,14 @@ Bit 0 means the lowest bit (1s place)
`path_length` is not a raw byte count. It packs both hash size and hop count: `path_length` is not a raw byte count. It packs both hash size and hop count:
| Bits | Field | Meaning | | Bits | Field | Meaning |
|------|-------|---------| |------|----------------|--------------------------------|
| 0-5 | Hop Count | Number of path hashes (`0-63`) | | 0-5 | Hop Count | Number of path hashes (`0-63`) |
| 6-7 | Hash Size Code | Stored as `hash_size - 1` | | 6-7 | Hash Size Code | Stored as `hash_size - 1` |
Hash size codes: Hash size codes:
| Bits 6-7 | Hash Size | Notes | | Bits 6-7 | Hash Size | Notes |
|----------|-----------|-------| |----------|-----------|-------------------------------|
| `0b00` | 1 byte | Legacy / default mode | | `0b00` | 1 byte | Legacy / default mode |
| `0b01` | 2 bytes | Supported in current firmware | | `0b01` | 2 bytes | Supported in current firmware |
| `0b10` | 3 bytes | Supported in current firmware | | `0b10` | 3 bytes | Supported in current firmware |

20
docs/payloads.md
View File

@ -98,7 +98,7 @@ Returned path messages provide a description of the route a packet took from the
For the common chat/server helpers in `BaseChatMesh`, the current request type values are: For the common chat/server helpers in `BaseChatMesh`, the current request type values are:
| Value | Name | Description | | Value | Name | Description |
|--------|----------------------|---------------------------------------| |--------|-----------|----------------------------------------------------|
| `0x01` | get stats | get stats of repeater or room server | | `0x01` | get stats | get stats of repeater or room server |
| `0x02` | keepalive | keep-alive request used for maintained connections | | `0x02` | keepalive | keep-alive request used for maintained connections |
@ -153,7 +153,7 @@ Not defined in `BaseChatMesh`.
## Response ## Response
| Field | Size (bytes) | Description | | Field | Size (bytes) | Description |
|---------|-----------------|-------------| |---------|-----------------|-----------------------------------|
| content | rest of payload | application-defined response body | | content | rest of payload | application-defined response body |
Response contents are opaque application data. There is no single generic response envelope beyond the encrypted payload wrapper shown above. Response contents are opaque application data. There is no single generic response envelope beyond the encrypted payload wrapper shown above.
@ -161,7 +161,7 @@ Response contents are opaque application data. There is no single generic respon
## Plain text message ## Plain text message
| Field | Size (bytes) | Description | | Field | Size (bytes) | Description |
|--------------------|-----------------|--------------------------------------------------------------| |--------------------|-----------------|-----------------------------------------------------------------------------------|
| timestamp | 4 | send time (unix timestamp) | | timestamp | 4 | send time (unix timestamp) |
| txt_type + attempt | 1 | upper six bits are txt_type (see below), lower two bits are attempt number (0..3) | | txt_type + attempt | 1 | upper six bits are txt_type (see below), lower two bits are attempt number (0..3) |
| message | rest of payload | the message content, see next table | | message | rest of payload | the message content, see next table |
@ -169,7 +169,7 @@ Response contents are opaque application data. There is no single generic respon
txt_type txt_type
| Value | Description | Message content | | Value | Description | Message content |
|--------|---------------------------|------------------------------------------------------------| |--------|---------------------------|--------------------------------------------------------------------------|
| `0x00` | plain text message | the plain text of the message | | `0x00` | plain text message | the plain text of the message |
| `0x01` | CLI command | the command text of the message | | `0x01` | CLI command | the command text of the message |
| `0x02` | signed plain text message | first four bytes is sender pubkey prefix, followed by plain text message | | `0x02` | signed plain text message | first four bytes is sender pubkey prefix, followed by plain text message |
@ -201,7 +201,7 @@ txt_type
## Repeater - Regions request ## Repeater - Regions request
| Field | Size (bytes) | Description | | Field | Size (bytes) | Description |
|----------------|-----------------|-------------------------------------------------------------------------------| |----------------|--------------|------------------------------|
| timestamp | 4 | sender time (unix timestamp) | | timestamp | 4 | sender time (unix timestamp) |
| req type | 1 | 0x01 (request sub type) | | req type | 1 | 0x01 (request sub type) |
| reply path len | 1 | path len for reply | | reply path len | 1 | path len for reply |
@ -210,7 +210,7 @@ txt_type
## Repeater - Owner info request ## Repeater - Owner info request
| Field | Size (bytes) | Description | | Field | Size (bytes) | Description |
|----------------|-----------------|-------------------------------------------------------------------------------| |----------------|--------------|------------------------------|
| timestamp | 4 | sender time (unix timestamp) | | timestamp | 4 | sender time (unix timestamp) |
| req type | 1 | 0x02 (request sub type) | | req type | 1 | 0x02 (request sub type) |
| reply path len | 1 | path len for reply | | reply path len | 1 | path len for reply |
@ -219,7 +219,7 @@ txt_type
## Repeater - Clock and status request ## Repeater - Clock and status request
| Field | Size (bytes) | Description | | Field | Size (bytes) | Description |
|----------------|-----------------|-------------------------------------------------------------------------------| |----------------|--------------|------------------------------|
| timestamp | 4 | sender time (unix timestamp) | | timestamp | 4 | sender time (unix timestamp) |
| req type | 1 | 0x03 (request sub type) | | req type | 1 | 0x03 (request sub type) |
| reply path len | 1 | path len for reply | | reply path len | 1 | path len for reply |
@ -229,7 +229,7 @@ txt_type
# Group text message # Group text message
| Field | Size (bytes) | Description | | Field | Size (bytes) | Description |
|--------------|-----------------|--------------------------------------------| |--------------|-----------------|----------------------------------------------|
| channel hash | 1 | first byte of SHA256 of channel's shared key | | channel hash | 1 | first byte of SHA256 of channel's shared key |
| cipher MAC | 2 | MAC for encrypted data in next field | | cipher MAC | 2 | MAC for encrypted data in next field |
| ciphertext | rest of payload | encrypted message, see below for details | | ciphertext | rest of payload | encrypted message, see below for details |
@ -239,7 +239,7 @@ The plaintext contained in the ciphertext matches the format described in [plain
# Group datagram # Group datagram
| Field | Size (bytes) | Description | | Field | Size (bytes) | Description |
|--------------|-----------------|--------------------------------------------| |--------------|-----------------|----------------------------------------------|
| channel hash | 1 | first byte of SHA256 of channel's shared key | | channel hash | 1 | first byte of SHA256 of channel's shared key |
| cipher MAC | 2 | MAC for encrypted data in next field | | cipher MAC | 2 | MAC for encrypted data in next field |
| ciphertext | rest of payload | encrypted data, see below for details | | ciphertext | rest of payload | encrypted data, see below for details |
@ -247,7 +247,7 @@ The plaintext contained in the ciphertext matches the format described in [plain
The data contained in the ciphertext uses the format below: The data contained in the ciphertext uses the format below:
| Field | Size (bytes) | Description | | Field | Size (bytes) | Description |
|--------------|-----------------|--------------------------------------------| |-----------|-----------------|----------------------------------------------------------|
| data type | 2 | Identifier for type of data. (See number_allocations.md) | | data type | 2 | Identifier for type of data. (See number_allocations.md) |
| data len | 1 | byte length of data | | data len | 1 | byte length of data |
| data | rest of payload | (depends on data type) | | data | rest of payload | (depends on data type) |

10
docs/stats_binary_frames.md
View File

@ -5,7 +5,7 @@ Binary frame structures for companion radio stats commands. All multi-byte integ
## Command Codes ## Command Codes
| Command | Code | Description | | Command | Code | Description |
|---------|------|-------------| |-----------------|------|--------------------------------------------------|
| `CMD_GET_STATS` | 56 | Get statistics (2-byte command: code + sub-type) | | `CMD_GET_STATS` | 56 | Get statistics (2-byte command: code + sub-type) |
### Stats Sub-Types ### Stats Sub-Types
@ -20,7 +20,7 @@ The `CMD_GET_STATS` command uses a 2-byte frame structure:
## Response Codes ## Response Codes
| Response | Code | Description | | Response | Code | Description |
|----------|------|-------------| |-------------------|------|--------------------------------------------------------|
| `RESP_CODE_STATS` | 24 | Statistics response (2-byte response: code + sub-type) | | `RESP_CODE_STATS` | 24 | Statistics response (2-byte response: code + sub-type) |
### Stats Response Sub-Types ### Stats Response Sub-Types
@ -39,7 +39,7 @@ The `RESP_CODE_STATS` response uses a 2-byte header structure:
**Total Frame Size:** 11 bytes **Total Frame Size:** 11 bytes
| Offset | Size | Type | Field Name | Description | Range/Notes | | Offset | Size | Type | Field Name | Description | Range/Notes |
|--------|------|------|------------|-------------|-------------| |--------|------|----------|---------------|---------------------------------|-------------------|
| 0 | 1 | uint8_t | response_code | Always `0x18` (24) | - | | 0 | 1 | uint8_t | response_code | Always `0x18` (24) | - |
| 1 | 1 | uint8_t | stats_type | Always `0x00` (STATS_TYPE_CORE) | - | | 1 | 1 | uint8_t | stats_type | Always `0x00` (STATS_TYPE_CORE) | - |
| 2 | 2 | uint16_t | battery_mv | Battery voltage in millivolts | 0 - 65,535 | | 2 | 2 | uint16_t | battery_mv | Battery voltage in millivolts | 0 - 65,535 |
@ -67,7 +67,7 @@ struct StatsCore {
**Total Frame Size:** 14 bytes **Total Frame Size:** 14 bytes
| Offset | Size | Type | Field Name | Description | Range/Notes | | Offset | Size | Type | Field Name | Description | Range/Notes |
|--------|------|------|------------|-------------|-------------| |--------|------|----------|---------------|----------------------------------------|----------------------|
| 0 | 1 | uint8_t | response_code | Always `0x18` (24) | - | | 0 | 1 | uint8_t | response_code | Always `0x18` (24) | - |
| 1 | 1 | uint8_t | stats_type | Always `0x01` (STATS_TYPE_RADIO) | - | | 1 | 1 | uint8_t | stats_type | Always `0x01` (STATS_TYPE_RADIO) | - |
| 2 | 2 | int16_t | noise_floor | Radio noise floor in dBm | -140 to +10 | | 2 | 2 | int16_t | noise_floor | Radio noise floor in dBm | -140 to +10 |
@ -97,7 +97,7 @@ struct StatsRadio {
**Total Frame Size:** 26 bytes (legacy) or 30 bytes (includes `recv_errors`) **Total Frame Size:** 26 bytes (legacy) or 30 bytes (includes `recv_errors`)
| Offset | Size | Type | Field Name | Description | Range/Notes | | Offset | Size | Type | Field Name | Description | Range/Notes |
|--------|------|------|------------|-------------|-------------| |--------|------|----------|---------------|--------------------------------------------------------------|-------------------|
| 0 | 1 | uint8_t | response_code | Always `0x18` (24) | - | | 0 | 1 | uint8_t | response_code | Always `0x18` (24) | - |
| 1 | 1 | uint8_t | stats_type | Always `0x02` (STATS_TYPE_PACKETS) | - | | 1 | 1 | uint8_t | stats_type | Always `0x02` (STATS_TYPE_PACKETS) | - |
| 2 | 4 | uint32_t | recv | Total packets received | 0 - 4,294,967,295 | | 2 | 4 | uint32_t | recv | Total packets received | 0 - 4,294,967,295 |

Write Preview
Loading…
Cancel
Save