Expand companion offline queues

This commit is contained in:
mikecarper committed 2026-08-19 17:32:05 -07:00
1 parent 8c9b827807
commit 67ed933a67
30 files changed
+213 -64

No files matched your search

+51
View File
@@ -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.
+10
View File
@@ -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
View File
@@ -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
+1
View File
@@ -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
View File
@@ -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
+1 -1
View File
@@ -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