Merge remote-tracking branch 'origin/keymindCascade' into keymindCascade
This commit is contained in:
commit
666150ab2f
20 files changed
+1307
-24
No files matched your search
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
|
||||
@@ -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 |
|
||||
|
||||
Reference in new issue
Block a user