Fix USB radio stalls and add durable replay timestamp recovery
This commit is contained in:
1 parent
f2c15225cc
commit
a8cf4fd12f
44 files changed
+4339
-148
No files matched your search
@@ -2605,6 +2605,73 @@ eviction like administrators.
|
||||
|
||||
---
|
||||
|
||||
#### Recover a repeater's future-dated replay timestamp
|
||||
|
||||
This is an explicit recovery operation after correcting a bad clock, not a
|
||||
contact deletion. It lowers selected replay timestamps to the repeater's
|
||||
current UTC epoch only when they are later than that epoch. Earlier values,
|
||||
public keys, permissions, stored paths, and historical identity records remain.
|
||||
The replay file is committed before the live table changes. No extra 60-second
|
||||
login reservation is added by this command.
|
||||
|
||||
First set/synchronize and verify the repeater's clock (`clock`); a build-default
|
||||
clock without a manual or observed synchronization is not accepted. Also fix
|
||||
the companion's clock before its next login.
|
||||
|
||||
USB console:
|
||||
|
||||
```text
|
||||
replay reset <full-64-hex-public-key>
|
||||
replay reset all CONFIRM
|
||||
```
|
||||
|
||||
Authenticated LoRa admin, including a resumed admin session:
|
||||
|
||||
```text
|
||||
replay reset <full-64-hex-public-key>
|
||||
```
|
||||
|
||||
The reply shows `now=<epoch>`, `ttl=<remaining-seconds>s`, and a confirmation command containing the same
|
||||
full key and a one-use 32-hex-character token. Verify the displayed time and send
|
||||
that command before the original 300-second deadline. During the first 120
|
||||
seconds, repeated requests for the same key by the same admin return the same
|
||||
token without restarting either timer. From 120 through 300 seconds, the token
|
||||
is retained for confirmation only: requests do not resend or replace it. This
|
||||
leaves at least 180 seconds to deliver a confirmation after the last permitted
|
||||
token response is generated (radio transit time still counts toward expiry).
|
||||
At 300 seconds it expires and a new request can receive a new token. Confirmation
|
||||
can succeed immediately; there is no requirement to wait for the resend window
|
||||
to close. The displayed TTL decreases on retries and is measured when the reply
|
||||
is generated, not when it reaches the companion.
|
||||
|
||||
It can target the caller's own key or another
|
||||
exact key; prefixes, `self`, wildcards, and `all` are not allowed over LoRa.
|
||||
Tokens are bound to both the requesting admin and target, expire on reboot,
|
||||
and are invalid after use or a clock correction outside the five-second
|
||||
confirmation tolerance. A failed write requires a new confirmation. Challenge
|
||||
requests consult live token state instead of replaying cached challenge text;
|
||||
completed confirmation results remain cacheable without executing the reset
|
||||
again. Normal packet freshness checks still apply to retries.
|
||||
|
||||
Only the physical serial console grants `all` access. Ethernet, browser and
|
||||
internal command callbacks do not count as USB. Guest, read-only, region-manager
|
||||
and filter-manager roles cannot reset replay state. This command is implemented
|
||||
in repeater firmware; room-server and sensor CLI are unchanged.
|
||||
|
||||
Normal login and command admission checks remain in force: a fully locked-out
|
||||
caller that cannot send an accepted admin command needs another working admin
|
||||
or USB access. A corrupt/unreadable replay file fails closed and is not erased
|
||||
or formatted by this operation. Unknown keys do not create records.
|
||||
|
||||
Security trade-off: lowering a replay boundary can admit previously captured
|
||||
future-dated login/command packets above the new boundary, including packets
|
||||
that could raise it again. The one-use token prevents the recovery command
|
||||
itself from being repeatedly executed; it does not replace the protocol's
|
||||
timestamp-based replay protection. Use recovery only after verifying clocks.
|
||||
Setting a clock alone never automatically resets this table.
|
||||
|
||||
---
|
||||
|
||||
#### View or change this room server's 'read-only' flag
|
||||
**Usage:**
|
||||
- `get allow.read.only`
|
||||
|
||||
@@ -0,0 +1,63 @@
|
||||
# SPIFFS regular-file reads and login replay state
|
||||
|
||||
Arduino-ESP32 SPIFFS can return a truthy directory handle from a read-open of a
|
||||
nonexistent filename. `File::operator bool()` alone does not prove that a
|
||||
regular file exists. A directory's `size()` and `read()` are zero.
|
||||
|
||||
The first privileged login on an upgraded G2 encountered this in
|
||||
`ClientACL::writeClientLoginReplayCeiling()`: opening the not-yet-created
|
||||
`/s_login_replay` appeared successful, then subtracting the eight-byte trailer
|
||||
from size zero underflowed. Copying the supposed records failed and login was
|
||||
rejected. Waiting or changing the repeater clock cannot fix that file-open bug.
|
||||
|
||||
## Fix
|
||||
|
||||
Use `mesh::openFileRead()` for regular-file reads. It checks existence and
|
||||
rejects directory handles, while preserving real empty files. Replay record
|
||||
counts also validate the minimum trailer size, record alignment, and maximum
|
||||
count before subtraction. An existing replay file that becomes unreadable is
|
||||
not treated as a new store.
|
||||
|
||||
No replay records are cleared and authentication is not weakened. Invalid or
|
||||
unwritable replay state still fails closed. The first successful privileged
|
||||
login creates a 44-byte file: one 36-byte identity/ceiling record plus its
|
||||
eight-byte integrity trailer.
|
||||
|
||||
Setting the repeater clock must not clear this file. Admission compares the
|
||||
sender's timestamp with that sender's saved boundary, not with the repeater's
|
||||
current time. Clearing the boundary could make captured requests reusable. A
|
||||
sender clock rollback is a separate condition and remains subject to the saved
|
||||
boundary after this fix.
|
||||
|
||||
Companion directory enumeration uses the separate `openDirectory()` API,
|
||||
which deliberately permits SPIFFS virtual directories. Regular-file reads are
|
||||
also enforced for companion data, repeater/room logs, flood-rule verification,
|
||||
and HTTP packet-log downloads (missing logs return 404; real empty logs 200).
|
||||
|
||||
## Audit boundary
|
||||
|
||||
The audit covered file opens and size arithmetic in `src` and `examples`.
|
||||
Identity, region, clock, and common preference loaders already gate reads with
|
||||
filesystem existence checks; SPIFFS's `exists()` explicitly excludes directory
|
||||
handles. Relevant MQTT length subtraction follows validated headers and exact
|
||||
reads. ESP32 OTA staging uses partition APIs, not these SPIFFS file handles.
|
||||
Intentional directory enumeration must not be changed to a regular-file read.
|
||||
|
||||
## Regression checks
|
||||
|
||||
- `test/test_client_acl_spiffs.py` compiles the actual `ClientACL.cpp` against
|
||||
a filesystem that reproduces the misleading missing-file directory handle.
|
||||
It covers first creation, fresh/stale login, reboot ceilings, corrupt and
|
||||
unreadable state, short writes, failed publication, and truncated sources.
|
||||
- `test/test_regular_file_reads.py` executes production companion readers,
|
||||
flood-file verification, and HTTP log delivery with the same filesystem
|
||||
behavior, including platform-specific file API differences.
|
||||
- `test/test_esp32_tinyusb_cooperative_output.py` exercises both real role log
|
||||
pumps, including missing logs and bounded output.
|
||||
- Native ACL transaction, login persistence, and client-path persistence suites
|
||||
retain the existing security and recovery coverage.
|
||||
|
||||
The pre-fix actual ACL code was reproduced as `first_login=rejected`, one
|
||||
missing read-open, and no replay file. The fixed code accepted that identical
|
||||
scenario without a missing read-open and created the valid 44-byte record.
|
||||
Host simulations do not replace a post-flash LoRa login test on the G2.
|
||||
@@ -0,0 +1,74 @@
|
||||
# Native USB backpressure and radio liveness
|
||||
|
||||
ESP32-S2/S3 builds using native TinyUSB CDC (`ARDUINO_USB_MODE=0` and
|
||||
CDC-on-boot) must not wait for a computer to read USB output. In the bundled
|
||||
Arduino-ESP32 2.0.17 core, `USBCDC::write()` can wait indefinitely for transmit
|
||||
space; its configured timeout bounds a mutex, not that wait. This can stop the
|
||||
same loop that services LoRa, even while the USB connection still appears open.
|
||||
|
||||
## Firmware behavior
|
||||
|
||||
- Native CDC output uses a single FIFO attempt, not Arduino's wait-for-space
|
||||
write or flush. TinyUSB's internal short mutex operations still apply; this
|
||||
is a no-host-progress-wait guarantee, not a lock-free driver replacement.
|
||||
- Functional text and diagnostics share one ordered 4 KiB queue. Diagnostics
|
||||
leave 3 KiB reserved for commands. A diagnostic backlog alone does not prevent
|
||||
command input. A stalled host may lose diagnostic records; radio work continues.
|
||||
- A connected terminal that exceeds its bounded output capacity gets an explicit
|
||||
dropped-byte notice when transmission resumes. Large local file dumps and
|
||||
recent-repeater listings advance between radio service passes instead.
|
||||
- File dumps stop at their initial file size and emit `-> EOF` only after the
|
||||
final accepted record. Corrupt stored lines exceeding 640 bytes are omitted
|
||||
with a visible notice. Recent-repeater output is a live, bounded-cursor view;
|
||||
incoming packets can change its ordering while it is being printed.
|
||||
- Disconnects discard pending old-session text and reset the role's partial
|
||||
command/listing state. Binary/mOTA transitions suppress pending text notices.
|
||||
Bytes already transmitted cannot be recalled.
|
||||
- Companion frames retain and retry short writes. An mOTA request is admitted
|
||||
only when its complete, at-most-11-byte record fits.
|
||||
- nRF52, UART, and USB-Serial-JTAG behavior is not changed by this native-CDC path.
|
||||
|
||||
Host software must also keep reading independently of command writes. A serial
|
||||
relay should start its reader before the first command, use finite write and
|
||||
response deadlines, avoid discarding received packet logs, and cancel I/O during
|
||||
shutdown. A response timeout must not allow a late reply to satisfy another
|
||||
command: the CLI has no transaction identifiers. Updating firmware alone does
|
||||
not correct an indefinite host-side serial write.
|
||||
|
||||
## Regression checks
|
||||
|
||||
Run only one PlatformIO process in the checkout at a time.
|
||||
|
||||
```sh
|
||||
python test/test_esp32_tinyusb_nonblocking.py
|
||||
python test/test_esp32_tinyusb_role_hygiene.py
|
||||
python test/test_esp32_tinyusb_cooperative_output.py
|
||||
python test/test_esp32_usb_serial_hygiene.py
|
||||
python test/test_nrf52_usb_logging_contract.py
|
||||
pio test -e native -f test_nrf52_debug_output -f test_serial_packet_log -f test_serial_mode_switch -f test_mesh_tables
|
||||
```
|
||||
|
||||
The first test compiles the real USB facade against a simulated 64-byte FIFO,
|
||||
including stopped readers, reconnects, protocol transitions, and other-platform
|
||||
fallbacks. Host simulations cannot establish that every real USB driver or
|
||||
endpoint failure has recovered.
|
||||
|
||||
A Full Station G2 validation build with USA Cascadia radio settings and the Cascade
|
||||
profile can be made using the normal build entry point. The portable `standard`
|
||||
recipe preserves the deployed partition layout but omits LoRa OTA; it still has
|
||||
the browser firmware uploader. The `auto`/`full` recipe instead enables the
|
||||
expanded feature set and partition layout: its merged image is **not** an
|
||||
app-only update for a device with the legacy layout.
|
||||
|
||||
```sh
|
||||
MESHDEBUG_OVERRIDE=on PACKET_LOGGING_OVERRIDE=on \
|
||||
bash build.sh build-firmware Station_G2_repeater --build-profile full \
|
||||
--radio-preset usa-cascadia --profile cascade
|
||||
```
|
||||
|
||||
Before installing on hardware, preserve the device identity, preferences, and
|
||||
existing partition layout. Then verify USB command responses and repeated LoRa
|
||||
logins with the relay running, paused, and stopped, including a host that leaves
|
||||
USB open without reading. Check LoRa recovery separately from USB OUT recovery;
|
||||
fixing transmit backpressure does not prove an unrelated OUT endpoint fault is
|
||||
resolved. Do not erase or repartition the radio as part of this test.
|
||||
Reference in new issue
Block a user