Merge remote-tracking branch 'origin/keymindCascade' into keymindCascade

This commit is contained in:
mikecarper committed 2026-09-28 17:46:45 -07:00
commit 666150ab2f
20 files changed
+1307 -24

No files matched your search

+4
View File
@@ -1191,6 +1191,10 @@ capacity. Remote use follows the existing administrator-command permissions.
**Default:** `869.618,62.5,8,5`
`get radio` returns exactly four comma-separated fields for compatibility with
existing Companion apps. On dual-radio builds, use `get radio2` and
`get radio.timing` for profile and timing diagnostics.
**Note:** Requires reboot to apply. If RXPS is enabled and the saved minimum
level/preamble cannot safely cover the new radio timing, the command reply
reports the effective level and preamble, or `RXPS continuous-fast` when no
+7 -4
View File
@@ -1,6 +1,7 @@
# Full Companion contact caches
# Companion contact caches
Full Companions on ESP32 and nRF52 without PSRAM now keep 16 outgoing paths
Full Companions on ESP32 and nRF52 without PSRAM, plus the high-contact RAK4631
USB/BLE profiles, keep 16 outgoing paths
and 16 shared secrets in RAM. Every contact remains in the contact table;
selecting a different contact loads its saved path as needed. This recovers
about 25.4 KiB of internal RAM in the 350-contact ESP32 qualification builds.
@@ -9,8 +10,10 @@ See the [qualification results](companion_contact_cache_results.md) for the
six-board RAM comparison, physical tests, and shared-secret timings.
PSRAM boards retain their existing complete contact table in external RAM.
Legacy USB/BLE/WiFi Companion profiles also retain their inline paths and
secrets. The build flag `MESH_CONTACT_CACHE=0` or `1` overrides this policy for
Most legacy USB/BLE/WiFi Companion profiles retain inline paths and secrets.
The high-contact RAK4631 USB/BLE profiles also enable the same cache,
keeping all 350 contacts while making room for the shared 256-frame offline/DM
pool. The build flag `MESH_CONTACT_CACHE=0` or `1` overrides this policy for
qualification; it is not a runtime feature switch.
## Paths and persistence
+13 -3
View File
@@ -11,10 +11,12 @@ A reboot clears it.
| --- | ---: |
| ESP32 with configured PSRAM | 512 |
| ESP32 without PSRAM | 256 |
| nRF52840 | 256 |
| nRF52840 with at most 300 contact slots | 256 |
| nRF52840 with more than 300 contacts and the contact cache (non-mOTA-shared queue) | 256 total: up to 15 held DMs use slots until accepted |
| nRF52840 with more than 300 contacts but no contact cache | 208 ordinary frames plus a separate 15-DM queue |
| nRF52 Full Companion with the memory correction | 256 normally; 128 while mOTA owns shared storage |
| RP2040 | 256 |
| STM32 | 16 |
| STM32 | 16 (one-key DM holding is omitted on flash-constrained STM32WL builds) |
| Known constrained classic ESP32 target override | 128 |
| Meshadventurer Full Companion | 16 |
| Constrained Full ESP32 fallback | 16 |
@@ -44,7 +46,15 @@ Full profiles require at least 72 KiB of heap space at link time; OLED and
headless profiles use their own [memory budgets](firmware_memory_budget.md).
Standard, logging, MQTT, and Cascade build overlays retain the selected target
capacity; they do not silently shrink the queue.
capacity. On cache-enabled high-contact nRF52 Companions, including the RAK4631
USB and BLE profiles, ordinary messages and consent-pending DMs share one
256-frame RAM pool. With no held DMs, all 256 slots are available to ordinary
messages; with 15 held DMs, up to 241 are. The app sees only ordinary messages
until a sender is accepted. The oldest held DM rolls off when a sixteenth
decryptable DM arrives. The shared pool is still volatile and clears on reboot.
Uncached high-contact profiles keep the conservative 208-frame default and
separate held queue. An explicit target `OFFLINE_QUEUE_SIZE` still takes
precedence.
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
+47 -1
View File
@@ -242,6 +242,51 @@ catalog; bytes `0x2C`-`0x31` are parked and `0x35` is unused.
The sections below detail the most common frames. Refer to the source named
above for command bodies that are not expanded here.
### Private text when only the sender knows the recipient
Clients continue to send an ordinary `CMD_SEND_TXT_MSG` (`0x02`) with
`TXT_TYPE_PLAIN`; no client protocol change is needed. For a chat contact
without a recent confirmed DM, Companion firmware first sends a signed,
encrypted [one-key introduction](payloads.md#companion-one-key-dm-introduction)
that includes its full public key, then queues the normal private text after
the introduction. It sends the introduction again on an application retry,
which recovers if the recipient removed the sender contact. An ACK confirms
that the recipient can decrypt normal DMs, so subsequent first attempts omit
the extra packet until the sender reboots or the small recent-ACK cache is
replaced.
The receiving Companion verifies the introduction signature. By default,
`dm.one_key` is `off`: the sender is offered to the app as a synthetic
`PUSH_CODE_NEW_ADVERT` (`0x8A`) but is not added as a contact. The app/user
accepts through the normal add-contact command. Up to 15 verified, decryptable
plain DMs are held in RAM and delivered after acceptance; the oldest rolls
off first. The queue is lost on reboot. Cache-enabled high-contact nRF52
Companions share a 256-frame pool between ordinary offline messages and up to
15 held DMs, so ordinary capacity is 256 when none are held and 241 when all
15 are held. The held frames are not exposed by ordinary message sync before
acceptance. Uncached high-contact nRF52 builds retain 208 ordinary frames and
a separate held queue. The device sends a signed `DMR1`
refusal, and the sender pushes `0x91` plus the full rejecting key to a
connected app, then stops further introductions for that peer until reboot.
Directly attached clients may use `get dm.one_key` or `set dm.one_key on|off`;
`get dm.held` reports the number of held DMs. `on` auto-accepts verified senders.
The flash-constrained STM32WL Companion builds omit one-key DM support to
preserve their existing filesystem boundary; these commands report
`Error: one-key DMs unsupported on this build` there. Ordinary contact-based
private messages remain available.
A recipient running older firmware still
needs the sender contact before it can decrypt a normal DM. This flow uses
a second radio packet for the initial DM; `RESP_CODE_SENT` includes that
scheduling delay in its timeout.
For a two-radio regression test, run `tools/hil/one_key_dm.py` with the USB
serial paths for `--sender` and `--recipient`. `--reset-contact` removes the
sender from recipient contacts, and `--zero-hop` sets the sender's route to
zero hop when the devices are nearby. The test checks the synthetic advert,
refusal, manual acceptance, held-message delivery, and matching ACK.
`--invalid-signature-first` also checks that a decryptable introduction with
an invalid Ed25519 signature does not add a contact.
`CMD_RUN_CLI_COMMAND` is followed by the local CLI text without a terminating
NUL. The device returns `RESP_CODE_CLI_REPLY` (`0x1D`) followed by the reply
text. This is separate from sending a remote on-air CLI command with
@@ -948,13 +993,14 @@ Byte values are authoritative; names are aliases. When reading firmware source,
| `0x87` | `PUSH_CODE_STATUS_RESPONSE` | Server status response. |
| `0x88` | `PUSH_CODE_LOG_RX_DATA` | Radio receive log data. |
| `0x89` | `PUSH_CODE_TRACE_DATA` | Completed trace data. |
| `0x8A` | `PUSH_CODE_NEW_ADVERT` | Newly stored contact advertisement. |
| `0x8A` | `PUSH_CODE_NEW_ADVERT` | New advert; a verified one-key DM may use this as an addable synthetic advert without storing the contact. |
| `0x8B` | `PUSH_CODE_TELEMETRY_RESPONSE` | Telemetry response. |
| `0x8C` | `PUSH_CODE_BINARY_RESPONSE` | Binary request response. |
| `0x8D` | `PUSH_CODE_PATH_DISCOVERY_RESPONSE` | Path-discovery response. |
| `0x8E` | `PUSH_CODE_CONTROL_DATA` | Control/discovery data. |
| `0x8F` | `PUSH_CODE_CONTACT_DELETED` | Oldest contact was deleted while making room. |
| `0x90` | `PUSH_CODE_CONTACTS_FULL` | Contact storage is full. |
| `0x91` | `PUSH_CODE_ONE_KEY_DM_REJECTED` | One-key DM refused; bytes 1–32 contain the refusing contact's full public key. |
### Parsing Responses
+30
View File
@@ -231,6 +231,36 @@ same-timestamp mismatches are rejected.
| cipher MAC | 2 | MAC for encrypted data in next field |
| ciphertext | rest of payload | encrypted message, see below for details |
### Companion one-key DM introduction
A Companion may send this request immediately before a normal private text
packet when it has not received an ACK from that chat contact, and on each
application retry. It lets the recipient learn the sender's full public key
without a broadcast advert. The ciphertext contains:
| Field | Size (bytes) | Description |
|---|---:|---|
| tag | 4 | unique sender timestamp |
| marker | 4 | ASCII `DMK1` |
| name | 1–32 | sender name followed by NUL |
| signature | 64 | Ed25519 signature by the sender |
The signed bytes are the recipient's full public key followed by the tag,
marker, and NUL-terminated name. The recipient verifies that signature against
the 32-byte sender key in the anonymous request header before offering a chat
contact for manual acceptance, or auto-adding it if `dm.one_key` is enabled.
A receiver that does not implement `DMK1` ignores the introduction;
the following normal text packet still works when it already has the sender's
key. The recipient's manual advert auto-add setting does not suppress the
synthetic advert for a verified, addressed `DMK1` introduction. The sender's
full public key remains
visible in the radio packet header, as with other anonymous requests.
With `dm.one_key` off, the recipient replies with an encrypted `DMR1` response:
the original 4-byte tag, ASCII `DMR1`, then its 64-byte Ed25519 signature
over the sender's full key followed by that tag and marker. Only a matching
pending introduction and verified signature stops repeat introductions.
### Room server login
| Field | Size (bytes) | Description |