Expand companion offline queues
This commit is contained in:
1 parent
8c9b827807
commit
67ed933a67
30 files changed
+213
-64
No files matched your search
@@ -0,0 +1,51 @@
|
||||
# Companion Offline Message Queue
|
||||
|
||||
Companion firmware keeps received channel data, channel messages, and direct
|
||||
messages in one pending queue until a Companion client requests them with the
|
||||
sync-next-message command. This is volatile RAM, not message history in flash.
|
||||
A reboot clears it.
|
||||
|
||||
## Default capacities
|
||||
|
||||
| Platform or memory profile | Pending frames |
|
||||
| --- | ---: |
|
||||
| ESP32 with configured PSRAM | 512 |
|
||||
| ESP32 without PSRAM | 256 |
|
||||
| nRF52840 | 256 |
|
||||
| RP2040 | 256 |
|
||||
| STM32 | 16 |
|
||||
| Known constrained classic ESP32 target override | 128 |
|
||||
| Constrained Full ESP32 fallback | 16 |
|
||||
|
||||
An explicit target `OFFLINE_QUEUE_SIZE` overrides the platform default. The
|
||||
Heltec V2 and TLora V2 Full Companion profiles, for example, use 16 frames so
|
||||
their combined WiFi, BLE, and LoRa mOTA image retains enough internal DRAM.
|
||||
Standard, logging, MQTT, and Cascade build overlays retain the selected target
|
||||
capacity; they do not silently shrink the queue.
|
||||
|
||||
Each queue slot currently costs 177 bytes. A 256-frame queue reserves 45,312
|
||||
bytes, while a 512-frame queue reserves 90,624 bytes. There is no 256-frame
|
||||
protocol limit: the queue length and indexes can represent 512 or more. The
|
||||
practical limit is available RAM and the heap and stack headroom required by
|
||||
the transports and display.
|
||||
|
||||
On ESP32 boards marked with `BOARD_HAS_PSRAM`, the queue is allocated from
|
||||
PSRAM before WiFi and BLE start. A failed 512-frame allocation retries at 256,
|
||||
then 128, and finally uses a 16-frame internal fallback. Full Companion prints
|
||||
the capacity actually allocated in its startup memory line as
|
||||
`offline_queue=<frames>`.
|
||||
|
||||
## Full queue behavior
|
||||
|
||||
The capacity is shared across Public, other channels, channel data, and direct
|
||||
messages. It is not a per-channel count. When the queue is full, firmware
|
||||
replaces the oldest queued channel frame so newer traffic can still arrive. If
|
||||
the full queue contains only direct messages, a new frame is dropped rather
|
||||
than deleting a direct message.
|
||||
|
||||
Queue order is preserved. Removal uses a ring index, so delivering one pending
|
||||
message no longer copies every remaining frame; only the less-common removal
|
||||
of an old channel frame from a full queue may shift entries.
|
||||
|
||||
Capacity is selected when firmware is compiled. There is no CLI or Companion
|
||||
protocol setting to resize it at runtime.
|
||||
@@ -146,6 +146,16 @@ layout. Other boards with 8 MB or more retain dual application partitions.
|
||||
Heltec V2 and TLora V2 use 100 contacts, 8 group channels, and a 16-frame offline
|
||||
queue in this combined profile because of internal DRAM limits.
|
||||
|
||||
Full Companions normally retain 256 pending Companion message frames. ESP32
|
||||
boards with configured PSRAM retain 512 and allocate that queue from PSRAM
|
||||
before WiFi and BLE start. If PSRAM is unavailable at runtime, allocation falls
|
||||
back through 256 and 128 frames, then to a 16-frame internal buffer. The Full
|
||||
Companion startup memory line reports the capacity actually allocated as
|
||||
`offline_queue=<frames>`. The queue is volatile and shared by all channels and
|
||||
direct messages; it is not flash-backed history. See
|
||||
[Companion offline message queue](./companion_offline_queue.md) for all platform
|
||||
defaults and full-queue behavior.
|
||||
|
||||
The nRF52 target inherits the board's ordinary USB Companion installation
|
||||
format and adds BLE plus the serial mOTA source. It does not enable an SD cache
|
||||
or any other board-specific storage behavior; host files are streamed as they
|
||||
|
||||
+4
-1
@@ -135,7 +135,10 @@ Companion radios connect MeshCore client software to LoRa. Depending on the
|
||||
board and build profile, the companion protocol can be exposed over BLE, USB
|
||||
serial, Wi-Fi, or Ethernet. Some boards also provide a Full Companion profile
|
||||
with additional local administration features. Check the exact build name and
|
||||
transport before flashing. See <https://meshcore.io> and the web client at
|
||||
transport before flashing. Pending messages are held in a volatile shared queue;
|
||||
capacity depends on the platform and memory profile. See the
|
||||
[Companion offline message queue](./companion_offline_queue.md) for the exact
|
||||
defaults and limitations. See <https://meshcore.io> and the web client at
|
||||
<https://app.meshcore.nz>.
|
||||
|
||||
#### 1.2.4. Repeater
|
||||
|
||||
@@ -14,6 +14,7 @@ Below are a few quick start guides.
|
||||
- [MeshTower V2 microSD self-updates](./ota_meshtower_v2_sdcard.md)
|
||||
- [GPS Tracking](./gps_tracking.md)
|
||||
- [Companion Protocol](./companion_protocol.md)
|
||||
- [Companion Offline Message Queue](./companion_offline_queue.md)
|
||||
- [Full Companion: ESP32 and nRF52](./companion_radio_full.md)
|
||||
- [Packet Format](./packet_format.md)
|
||||
- [QR Codes](./qr_codes.md)
|
||||
|
||||
+1
-1
@@ -89,7 +89,7 @@ FULL ESP32 roles include the required transport. A
|
||||
serves host images but cannot stage or install one for itself. ESP32 full
|
||||
combines USB, BLE, and WiFi; nRF52 full combines USB and BLE because nRF52840
|
||||
has no WiFi.
|
||||
A small set of high-capacity classic ESP32 companions
|
||||
A small set of high-capacity, non-PSRAM classic ESP32 companions
|
||||
keep their normal image and provide a separate `-full-ota-` image with 100 contacts, 8 group channels, and
|
||||
a 16-frame offline queue. Install that variant's merged image over USB once before using it. Connect the
|
||||
source by USB serial or, when supported, by WiFi. For an ordinary raw-text USB
|
||||
|
||||
@@ -112,7 +112,7 @@ The "reconstructed image" referenced by the manifest is the full `BODY || EndF`
|
||||
|
||||
ESP32 companion firmware is exempt from the portable-slot limit. USB and WiFi companion artifacts retain
|
||||
LoRa OTA and carry `-ota-` in their filenames so they can seed a host folder over serial or TCP; they keep
|
||||
their target partition table rather than using the FULL profile. A small set of high-capacity classic ESP32
|
||||
their target partition table rather than using the FULL profile. A small set of high-capacity, non-PSRAM classic ESP32
|
||||
companions cannot combine their configured contact, group-channel, and offline-queue capacities with LoRa
|
||||
OTA in internal DRAM. Their normal artifacts remain unchanged, and option 3 also emits `-full-ota-` and
|
||||
`-full-logging-ota-` variants with 100 contacts, 8 group channels, and a 16-frame offline queue. MQTT
|
||||
|
||||
Reference in new issue
Block a user