Add bounded Morse receive and negotiated RS232 autosleep

Add native narrow-band CW capture, ACK-first remote sessions, retained LoRa-readable pages, checked restoration and transport-safe progress. Add stock-compatible negotiated heartbeat/autosleep and recovery. Include host regressions and identity-bound HIL runners; keep unverified faster tuning HIL-only and document outstanding hardware validation.
This commit is contained in:
mikecarper committed 2026-10-13 01:24:39 -07:00
1 parent d2bea5fb10
commit ca9caece53
152 files changed
+12631 -149

No files matched your search

+178
View File
@@ -4,6 +4,184 @@
# Carrier-wave RF checks
## TX-only Morse messages
Morse TX mode keys an unmodulated carrier into dots and dashes. It does not send
LoRa packets or automatically retransmit channel chat or
private messages. **The default is 902.100 MHz at 25 words per minute (WPM).**
Nothing transmits until an explicit `morse send` command is accepted.
| Command | Action |
| --- | --- |
| `morse send TEST DE N0CALL` | Send the text once using the saved Morse frequency and speed. |
| `morse stop` | Stop Morse immediately and restore packet reception. |
| `get morse` | Show idle/active state, frequency, WPM and remaining time. |
| `get morse.freq` | Show the Morse TX frequency in MHz. |
| `set morse.freq 902.100` | Save the separate Morse TX frequency, rounded to 1 kHz. |
| `get morse.wpm` | Show the saved sending speed. |
| `set morse.wpm 12` | Slow transmission for easier hand decoding; supported range is 1–60 WPM. |
The default 25 WPM can be changed; for an easy-to-copy test, set 10–12 WPM.
Standard timing uses one unit for a dot, three for a dash, one between elements,
three between letters and seven between words, with a dot of `1200 / WPM`
milliseconds. Letters are sent case-insensitively. Messages are bounded to
80 ASCII characters, must contain supported Morse characters, and must fit
within 180 seconds at the chosen speed. Supported punctuation is
`. , ? ' ! / ( ) & : ; = + - _ " $ @`; tabs, newlines and non-ASCII text are
rejected. Invalid messages are rejected before
the transmitter is keyed. There is no automatic callsign insertion.
The Morse frequency is independent of `radio`, `tempradio`, `radio2` and
`tempradio2`. Before sending, the firmware rejects a frequency that overlaps
either packet-radio profile, including a guard outside its occupied bandwidth.
It does **not** automatically find another channel or change your mesh settings.
Choose another `morse.freq` if 902.100 MHz overlaps either profile. A frequency
accepted as a saved value must still be supported by the actual radio at send
time. Morse frequency/speed changes are rejected while Morse or CW is active.
There is one physical transceiver: packet reception and transmission pause
throughout the message, including the spaces between dots and dashes. Normal
receive/profile scanning is restored afterward. Use local USB/BLE for immediate
status and stopping; a reply to a remote LoRa CLI command waits until the
message finishes. Changing either packet profile during Morse can abort it to
preserve the frequency-separation safety checks.
An unmodulated carrier has no selectable LoRa bandwidth. This uses native CW
on SX1262/SX1268/LLCC68/STM32WLx and LR1110/LR1121/LR2021 radios, and
zero-deviation FSK CW on SX1276-family radios with reset/recovery support, rather
than pretending the narrowest receive filter sets the transmitted bandwidth.
Morse sidebands depend on keying speed and transmitter edges. This is not a
guarantee of a particular occupied RF bandwidth or freedom from interference.
Unsupported radios reject the command without beginning transmission.
The chips' configured TX ramps use 3400 microseconds on the SX126x-family and
304 microseconds on the LR-family to reduce keying splatter. These are driver
settings, not measured occupied-bandwidth results. Direct FEM gain changes are
blocked while Morse owns the radio.
Frequency and speed are saved in a separate checked `/morse_prefs` file;
identity, contacts and existing radio preferences are unchanged. An active
message is never restored after reboot. TX uses the board's existing `set tx`
power setting and hardware power limits.
Unreadable or corrupt saved Morse settings without a usable backup block
sending rather than silently
transmitting on the default frequency. After storage recovers, verify and save
`morse.freq` (and the desired WPM); a verified save makes sending available again.
Use an appropriate antenna or dummy load, lawful frequency/power and any
required operator identification. The default frequency is a convenience, not
permission to transmit or a claim that the channel is clear. Check the local
band plan and listen first.
## Timed Morse reception and retained captures
Supported radios can temporarily listen for keyed carriers and decode the
power envelope into text. This is a separate manual session, not another
MeshCore packet channel or an authenticated sender. Nothing decoded is
automatically transmitted, relayed or inserted into a channel/DM inbox.
| Command | Action |
| --- | --- |
| `morse listen 1` | Listen for one minute at the saved `morse.freq`, using `morse.wpm` as the timing hint. |
| `morse listen 0.5` | Listen for 30 seconds. Fractions are allowed. |
| `morse listen 5` | Listen for the maximum five minutes, then restore packet reception. |
| `morse stop` | End TX or listening early. A received capture is retained. |
| `get morse` | Show TX/RX state, actual RX filter bandwidth, remaining time and capture length/truncation. |
| `morse stats` | Show retained receiver sample counts, noise/min/max/last power, timing unit, largest sample gap and read failures. |
| `morse read` | Read the first retained capture page. |
| `morse read 128` | Read beginning at character offset 128; use the offset returned by your previous page. |
| `morse clear` | Clear the retained capture when no Morse session is active. |
Listening is bounded to **1–300 seconds** for every role. Keep the first
0.5 seconds quiet while the receiver learns its noise floor; start the sending
radio at least one second after listening begins. Start with matching WPM on
the sender and receiver. Noise, fading, interference and timing mismatch can
produce errors; decoded text has no sender identity or integrity check.
The receiver uses a continuous native FSK receive filter and live received
signal strength (RSSI) to follow the carrier's on/off envelope. It does not
transmit or require a packet preamble, sync word, CRC or direct-data pin:
| Radio family | Current Morse RX filter |
| --- | ---: |
| SX1276-family | 2.6 kHz |
| SX1262/SX1268/STM32WLx, LLCC68 | 4.8 kHz |
| LR1110/LR1121, LR2021 | 4.8 kHz |
Small-flash STM32 production builds disable Morse reception by default
(`MESH_ENABLE_MORSE_RX=0`) because the receiver does not fit alongside their
existing features. Morse TX, frequency/WPM settings and stopping remain
available. Their listen/read/stats/clear commands return an unsupported-RX
error. The STM32 filter above describes an explicitly enabled custom build,
not RX support in those default production images.
`get morse` reports the actual configured bandwidth; this is not a measured
selectivity or decoder-speed guarantee. Unsupported hardware rejects listening
without changing the radio. A board also needs a proven complete LoRa-modem
restoration path before native FSK RX is enabled. Narrow filters require
sufficiently aligned oscillator frequencies. Passive listening may use either packet profile's
frequency because it does not transmit; TX overlap protections still apply.
FEM and saved Morse settings cannot be changed while a session owns the radio.
Morse sessions defer periodic sensor/GPS processing, screen redraws and
background storage work so they do not interrupt envelope timing. Pending
work and its deadlines are retained and resume when the session ends. Buttons,
command connections, watchdogs and battery shutdown checks remain active.
`morse stats` reports `gap` in milliseconds: the largest observed gap between
receiver samples, including unavoidable safety work. Large gaps can limit
reliable speed even when the RF signal is strong.
Repeater, Room, Sensor and Companion roles retain a bounded **4096-character
RAM capture** after their normal packet receiver resumes. A successful new
listening session replaces it; a failed start does not. `morse clear` or a
reboot removes it. If the capture fills, listening stops early and
`truncated=1`/capture-quota status is shown instead of continuing to discard
incoming text. This does not change node keys, ACLs, stored radio
settings or other files.
Capture replies fit one CLI response and begin with a page header such as
`> 0000/0250 next=0125 truncated=0 ` followed by text. Send `morse read 125` to
continue at the returned offset; `next=END` means the last page. Exact page
length depends on the requesting transport's reply capacity, so follow `next`
rather than assuming a fixed page size. Captures remain readable until you
start another listening session or clear them.
A Full Companion's owned buffered USB ASCII terminal or browser terminal shows
decoded progress as `[Morse RX] ...`, paused while USB input is being edited or
an earlier reply is draining. Complete records use that terminal's existing
ordered output queue. Raw UART/HWCDC/TCP terminals use `get morse`/`morse read`
instead of unsolicited progress. Binary Companion USB/BLE frames never receive
raw text.
Companion apps and other clients can request the same capture through their
CLI using `morse read`; it is not presented as an authenticated chat message.
There is no automatic LCD/inbox injection.
One transceiver cannot listen for Morse and MeshCore LoRa simultaneously.
During listening, normal packet reception/transmission is paused. An authorized
remote `morse listen` first queues its reply on the existing packet-radio
settings and starts only after the exact reply copies finish transmitting,
with at least one successful transmission. It does not infer that the remote
client received the reply. Failed queue admission/all-copy failure, permission
revocation, changed Morse settings or a 30-second handoff deadline cancel the
request without starting RX. A briefly busy radio can retry admission for up
to 10 seconds after reply transmission, within that same handoff deadline.
For remote captures, send `morse listen 1`, start the Morse sender after the
queued reply and initial quiet learning interval, wait beyond the selected
minute (plus any admission delay), then request
`get morse` and `morse read` over LoRa. Use a local console to stop early.
Hardware recovery failures hold exclusive ownership until the receiver can
be safely restored; `get morse` reports recovery pending.
Lab images compiled with `MESH_MORSE_HIL=1` additionally provide
`morse trace [offset]`. A page begins `> offset/length t=total n=next x=wrapped`
and contains up to eight `elapsed_ms,rssi_dbm,flags;` records. `n=END` ends the
retained window; `x=1` means earlier entries were overwritten. Offsets address
the oldest of the latest 512 retained records; retrieve after stopping or
check that `t` stays unchanged between pages. Flags are raw key 1, committed
key 2, debounce candidate 4 and noise learning 8. This diagnostic command and
its trace storage are absent from ordinary production builds.
## Continuous carrier checks
`cw` and `cw2` transmit a continuous, unmodulated carrier at the selected
profile's frequency and the configured TX power. They are available in the
shared ASCII CLI on SX1276-family, SX1262-family, and LR1110 builds, including repeaters,
+88
View File
@@ -14,6 +14,26 @@ Chat remains plain text; NodeInfo is sent only when that command is requested.
See [carrier-wave RF checks](carrier_wave.md) for `cw on [seconds]`,
`cw2 on [seconds]`, and stopping a carrier with `off`.
For keyed Morse TX, use `morse send TEST DE N0CALL` and `morse stop`.
Defaults are **902.100 MHz and 25 WPM**; `set morse.freq <MHz>` and
`set morse.wpm <1–60>` save separate frequency/speed settings.
Small-flash STM32 production builds retain Morse TX but do not include Morse
RX by default; listen/read/stats/clear return an unsupported-RX error there.
`get morse` shows status. See [TX-only Morse messages](carrier_wave.md#tx-only-morse-messages)
for supported characters, limits, overlap checks and the temporary pause in
packet reception. Nothing transmits automatically.
For timed Morse RX, use `morse listen <minutes>` (fractions allowed, 1 second
through 5 minutes). `morse stop` ends TX or RX. All roles retain the bounded
capture in RAM for `morse read [offset]`; follow each page's `next` value until
`next=END`. `morse clear` removes it when idle. A new successful session or
reboot replaces/removes the capture. Full Companion ASCII terminals show
decoded progress; binary clients request it through the CLI, without adding
unidentified text to authenticated channel/chat messages. Normal LoRa is paused
during listening, so a remote administrator must wait for the selected session
to end before reading the capture over LoRa. See [timed reception](carrier_wave.md#timed-morse-reception-and-retained-captures)
for arming time, real chip bandwidths and truncation behavior.
For copy/paste on/off recipes and the differences from Full Companion, see
[feature switches by role](role_feature_switches.md). The
[USB web console](https://flasher.meshcore.io/console) opens the default ASCII
@@ -2370,6 +2390,8 @@ on battery. `set powersaving on` still enables sensor/GPS power-saving policies;
the CPU continues normal idle yielding while keeping the console available.
A running MQTT, RS232 or ESP-NOW bridge keeps infrastructure awake even when
`get powersaving` reports `on`; that readback alone does not prove MCU sleep.
Negotiated RS232 standby can stop an unresponsive UART owner without changing
its saved enabled flag; see `rs232.autosleep` below. Other sleep blockers still apply.
Adding UART wake alone would still discard the characters that trigger wake,
so it cannot preserve an unmodified web console's first command. See the
[ESP-IDF UART wake documentation](https://docs.espressif.com/projects/esp-idf/en/v4.4.7/esp32s3/api-reference/system/sleep_modes.html#uart-wakeup-light-sleep-only).
@@ -4853,6 +4875,72 @@ MQTT preferences and retains explicit settings across reboots.
---
#### RS232 heartbeat and automatic standby
Available on repeater builds with an RS232 bridge. This is a UART-local control
exchange, not an advert or a LoRa packet. Room builds without RS232 are unaffected.
**Usage:**
- `get rs232.status`
- `get rs232.heartbeat`
- `set rs232.heartbeat on|off`
- `get rs232.autosleep`
- `set rs232.autosleep on|off|force`
- `get rs232.idle`
- `set rs232.idle <seconds>` (60 through 3600; default 300)
Heartbeat and negotiated automatic standby are **on by default**, including
upgrades. An active UART pings every 30 seconds (52 bytes per ping).
Stock bridges ignore that traffic and still receive the original data frames;
they are not automatically put to sleep: standby is armed only after a fresh
heartbeat reply proves support. Fresh, session/challenge-matched replies
prove a bidirectional peer;
ordinary valid incoming data can keep a legacy link awake but cannot prove
heartbeat support. The status separates saved intent, actual UART state,
standby/probe phase, and confirmed versus legacy/unknown peer liveness.
Enable on both updated peers:
```text
set rs232.enabled on
set rs232.heartbeat on
set powersaving on
set rs232.idle 300
set rs232.autosleep on
get rs232.status
```
With heartbeat, autosleep, and global powersaving all on and the peer's heartbeat
support confirmed, when no peer responds for the idle interval the UART is soft-stopped while
`rs232.enabled` stays `on`. It wakes after 30 seconds for a 2-second probe;
every eighth probe listens for 40 seconds. That longer window spans the other
side's sleep interval, so two sleeping updated peers can reconnect without
manual intervention (normally within about five minutes with working wiring
and timely loop servicing). Healthy peers remain running; this is dead-link
power saving, not an idle-data duty cycle.
Stock receivers ignore these control frames; they are deliberately invalid
zero-length stock frames with an ASCII-only remainder. They do not allocate a
mesh packet or enter LoRa forwarding. Stock peers do **not** answer heartbeats,
so default negotiated standby never arms on a stock-only link. Valid legacy
data after heartbeat replies cease also disarms negotiated standby, allowing
a replacement stock peer to stay awake. Use `set rs232.autosleep force` only
to sleep an absent/unconfirmed UART peer; this explicitly bypasses stock
protection and can miss one-off stock packets.
If a previously confirmed updated peer is silently replaced with stock while
the local UART is already sleeping, its first packet can be missed before
replacement is detected. Set autosleep off before that change, or restart the
local bridge to clear the old negotiated session.
While the UART is stopped it cannot receive a wake byte; mesh traffic
during standby is not queued for later UART delivery. Turning autosleep or
global powersaving off resumes the saved-enabled UART; `rs232.enabled off`
remains an explicit off and never automatically wakes.
`rs232.heartbeat off` stops initiating heartbeats and prevents standby. An
updated active peer can still answer a valid incoming ping in passive mode.
---
#### Add a delay to packets routed through this bridge
**Usage:**
- `get bridge.delay`
@@ -0,0 +1,120 @@
# Morse receive hardware checkpoint - 12 October 2026
Status: **incomplete hardware validation**. The release default remains
25 WPM / 902.100 MHz and the public limit remains 60 WPM. Experimental
255-WPM builds are not a validated release limit.
## Implementation and host verification
- Companion, repeater, room and sensor command paths support bounded receive
sessions, a volatile 4096-character capture, paged reads and checked LoRa
recovery. Receive duration is one second through five minutes.
- Remote receive starts only after its acknowledgement has actually transmitted.
- Fresh focused Morse run: 56/56 passed. Additional high-speed HIL OFF-debounce
tests and decoder matrix: 3/3 passed, including 188 synthetic waveform cases.
- Radio/role regression run: 390/390. RS232 overlap: 19/19. USB/BLE/logging:
222 test methods with no functional failures; eight optional DFU emulation
subcases skipped because the host lacks Unicorn.
- Build checks passed for the tested nRF52 companions/repeater, ESP32 room and
sensor, and compact STM32 builds. Compact STM32 retains TX but excludes RX
by default to respect its existing flash boundary.
## Hardware identities and isolation
The Mercerwood Pi was reached at `100.78.195.38`. Only identity-verified
application DFU packages were written through the existing `mcfirmware.sh`
path. No bootloader or SoftDevice was replaced, no services were stopped,
and the Pi was not rebooted by this test.
| Board | USB chip serial |
| --- | --- |
| RAK4631 | `9AB3B64C641BA927` |
| Heltec T096 | `651F8E496197F882` |
| Heltec MeshPocket | `93DA83ADF7B2092B` |
The RAK3401 service radio and MeshTower were left alone.
Early tests put CW at 909.5 MHz and packet profiles elsewhere. This was
corrected: the requested CW default is **902.100 MHz**, separate from the
LoRa lab control tuple **909.5 MHz / 500 kHz / SF5 / CR5**. Results from the
early layout are not proof of packet-spectrum isolation.
`set radio` only saves Companion primary settings. The test runners now use
`set tempradio` and poll the exact active tuple; saved or pending settings
do not satisfy the check. The USB-only HIL recipes explicitly include the
existing temporary-radio capability. Names and saved primary settings are
not changed by the corrected runners.
## Observations, not a new maximum
- With experimental warm-XOSC TX, 800-us PA ramp, RSSI window 2 and 1-ms
polling, MeshPocket-to-RAK decoded the alphabet/digit, word-spacing and
punctuation messages correctly in one 120-WPM sweep at 902.100 MHz.
- Reverse-direction captures contained additional noise characters. At
200/240 WPM, there were real character errors in both directions. Strict
comparison includes extra characters; matching only a substring is not
accepted.
- Keeping ordinary FSK packet preamble/sync/CRC did not establish a reliable
faster limit. That experiment is not enabled in production.
- A no-transmitter control can produce extra characters; the source of those
RSSI excursions is not established. Noise, another carrier and a radio
measurement artifact must not be conflated without further evidence.
- Sample-gap diagnostics confirmed mostly 1/2-ms cadence after noncritical
sensor, display and filesystem work was deferred during capture. The
protection of voltage cutoffs, GPIO expiry, watchdogs, transport input and
stop commands remains active.
- Integer-millisecond timing maps 219-255 WPM to the same nominal five-ms dot.
SPI/PA overhead further slows the envelope. USB-observed TX duration is
not a precision measurement of physical on-air WPM.
## Remote acknowledgement and retained-capture evidence
A 30-second LoRa-controlled test physically demonstrated:
1. A six-minute request was rejected in 0.682 seconds.
2. The valid request was acknowledged in 0.684 seconds before RX started.
3. The timed receiver returned to LoRa after 30.889 seconds as observed by
the host.
4. All 34 retained characters read locally were returned byte-for-byte in
the remote LoRa read.
The decoded RF text was not equal to the transmitted message, so this run
failed overall. It used the early shared CW/control frequency and is not a
clean decoder validation. The full five-minute and multiple-page remote
tests remain outstanding.
## Why hardware work stopped
At approximately 22:43 Pacific the RAK USB connection disappeared during the
zero-gate isolated-frequency sweep. It subsequently reported
`v1.17.1.10-halo-keymind-cascade-preview3-9ce2a076`, with `get morse` unknown,
instead of the just-verified Morse application. Another concurrent job had
flashed the shared RAK. This is not evidence of a Morse firmware crash.
The affected sweep is incomplete and must not be counted as a completed
speed test. Hardware writes were stopped for user coordination.
## Ready-to-resume experiment
An isolated HIL-only `MESH_MORSE_HIL_FAST_OFF_DEBOUNCE=1` experiment keeps
ON confirmation at two ms and permits OFF confirmation at one ms for fast
nominal dots. Default/production behavior, capture size and low-speed timing
are unchanged. Synthetic tests pass; physical results are still pending.
The following application-only packages were compiled and staged on the Pi
but **not installed**:
| Package | SHA-256 |
| --- | --- |
| `RAK_4631_companion_radio_usb-morse-fastoff.zip` | `0340b6135c36c7d6cb61be45ac28555ead5a2f6529feb3702466b284d2abd204` |
| `Mesh_pocket_companion_radio_usb-morse-fastoff.zip` | `e0d94389310244655136564a1dbd55d5e4d4d18a17bbae6e1c7ae018f5bc7952` |
Pi run directory: `/home/mikec/hwtest/runs/morse-20261012.3Lp6jA`.
Local raw evidence is retained in the ignored `out/morse-rx/` directory;
the strict test runners are in `tools/hil/morse_bench.py` and
`tools/hil/morse_remote.py`.
Before resuming, coordinate exclusive use of those three radios, verify the
installed images and exact USB identities, and run the isolated timing A/B,
repeated mixed-message speed boundary tests, and the five-minute multipage
LoRa capture/recovery test. Only then choose and verify any production cap
or tuning changes. No commit or push was performed for this checkpoint.