Add runtime RS232 bridge diagnostics and wired link probes

This commit is contained in:
mikecarper committed 2026-10-22 11:51:56 -07:00
1 parent e7b863494c
commit 281f1a5199
22 files changed
+1468 -24

No files matched your search

+99 -2
View File
@@ -5568,8 +5568,9 @@ still overrides the first-boot default after an update.
### Bridge (When bridge support is compiled in)
For a complete two-repeater setup with each option explained, see the
[ESP-NOW bridge setup guide](espnow_bridge_setup.md).
For a two-repeater setup and diagnostic flow, see the
[ESP-NOW bridge setup guide](espnow_bridge_setup.md) or
[RS-232/UART bridge guide](rs232_bridge_setup.md).
#### View the compiled bridge type
**Usage:** `get bridge.type`
@@ -5687,6 +5688,102 @@ MQTT preferences and retains explicit settings across reboots.
---
#### Diagnose the RS232 bridge
Available on repeater builds containing the optional RS-232 bridge. These
runtime diagnostics require no `BRIDGE_DEBUG` build flag. Builds without the
transport do not gain UART support from these commands.
**Read-only commands:**
```text
get rs232.transport
get rs232.stats
get rs232.stats rx
get rs232.stats tx
get rs232.stats drops
get rs232.stats test
```
The existing `get rs232.status` keeps its heartbeat/automatic-standby report.
If no UART bridge object exists, such as after explicitly disabling it,
the transport and counter commands report `RS232 diagnostics unavailable`;
use `rs232.enabled`, `rs232.running` and `rs232.status` to check saved intent
and power state.
`get rs232.transport` reports the local transport state (`ready`, `off`,
`standby`, `probing` or `retrying`) and these fields:
| Field | Meaning |
| --- | --- |
| `baud` | Configured serial baud rate. |
| `pins` | Selected RX/TX pin numbers. |
| `src` | Configured LoRa packet source, `rx` or `tx`. |
| `rxpart`, `rxready` | Bytes held in the current RX frame and whether a complete frame awaits mesh-pool space. |
| `tx` | Bytes remaining in the owned TX frame. |
| `heartbeat` | `on` initiates heartbeats; `passive` can still answer a valid ping. |
| `last` | Last recorded diagnostic error: `none`, `pins`, `driver`, `test.stopped`, `test.busy` or `test.timeout`. It can remain after recovery. |
A running UART means local initialization succeeded, not that a peer is
reachable. Counter pages separate ordinary mesh traffic from explicit probes:
| Page | Keys and meaning |
| --- | --- |
| Default | `rx`: received data frames; `mesh`: inbound packets admitted to mesh processing; `tx`: outbound mesh packets queued; `sent`: mesh frames fully accepted by the local UART. |
| `rx` | `bytes`: all consumed UART bytes; `frames`: checksum-valid data frames; `crc`: checksum failures; `length`: invalid lengths; `parse`: mesh-packet parse failures; `timeout`: incomplete-frame expiry; `pool`: complete frames held for mesh-pool space. |
| `tx` | `req`: mesh TX requests; `queued`: mesh frames accepted into the owned buffer; `sent`: fully UART-accepted mesh frames; `bytes`: all UART-accepted bytes; `stall`, `short`: blocked drain attempts or short-write events. |
| `drops` | `noise`: synchronization rejects; `filter`/`dupe`: inbound filter/duplicate drops; `busy`/`stopped`: mesh TX rejected by transport state; `txfilter`/`txdupe`: outbound filter/duplicate drops; `big`: invalid or oversize TX packets. |
| `test` | `queued`, `sent`, `fail`: probe TX stages and recorded failures; a late write can count as both failed and sent; `rx`, `bad`: valid/invalid probes received; `txid`, `rxid`: last queued/received IDs in hexadecimal. |
Mesh admission means queued for normal processing, not confirmed LoRa
forwarding or end-to-end delivery. Local write acceptance does not prove the
bytes reached the peer. Byte totals include data, heartbeat and test traffic;
RX bytes also include discarded noise. A frame can cause several write stalls.
Counters survive same-object UART stop/start, including
automatic standby. Disabling or reconfiguring the bridge can delete and replace
that object, starting a new window; reboot and explicit reset also clear the
counters. Stopping a transport can discard unfinished work without determining
delivery, so the pages are not a complete delivery ledger.
**Local-only actions:**
```text
rs232 test
rs232 test A1B2C3D4
rs232 resetstats
```
The optional ID is exactly eight hexadecimal digits, case-insensitive, without
`0x`, spaces or trailing arguments. Omitting it uses uptime in milliseconds.
`OK - test queued id=...; confirm on peer` confirms local queueing only. On
the other updated board, `get rs232.stats test` must show an increased `rx`
and matching `rxid`. Use a different ID in the reverse direction.
Probes use a reserved UART-local control frame. They do not allocate a mesh
packet, enter duplicate tracking, refresh peer liveness, authenticate a peer,
or get forwarded onto LoRa. There is no automatic echo or retransmission.
A probe that misses its write deadline records one failure. If no byte was
accepted by the UART, it is cancelled. If a prefix was already accepted, the
bridge retains and drains only the original suffix, with bounded work per
main-loop pass, before another frame can start. This preserves framing for
older receivers. A later completion also increments `sent`; the historical
failure is retained and neither result proves peer receipt.
A stopped, transitioning
or busy UART, including a due heartbeat, rejects the test rather than waking or
taking over the port. Older
firmware ignores the extension. The test and counter reset do not write
preferences and are rejected over LoRa; use a local console.
For a short USB capture, record both `get usb.logging` and `get usb.debug`,
then enable both `set usb.logging on` and `set usb.debug on`. The ordinary
image emits bounded `RS232:` updates from its main loop at most once per
second when diagnostic state changes. Busy USB output can skip updates; use
the counter pages for exact values. Restore both original settings afterward.
The CLI pages and test probes need neither logging gate.
See the [two-board serial diagnostic flow](rs232_bridge_setup.md#test-each-serial-direction-without-lora-forwarding).
---
#### RS232 heartbeat and automatic standby
Available on repeater builds with an RS232 bridge. This is a UART-local control
+157
View File
@@ -0,0 +1,157 @@
<!-- meshcore-hosted-doc-link:start -->
<p class="meshcore-hosted-doc-link"><a href="https://mikecarper.github.io/MeshCore/rs232_bridge_setup/">View this page on MeshCore Docs</a>.</p>
<!-- meshcore-hosted-doc-link:end -->
# RS-232/UART bridge: setup and diagnostics
Two supported repeaters can exchange MeshCore packets over a wired UART link.
Each repeater can use the LoRa settings of the network on its side:
```text
LoRa network A <--> Repeater A <-- serial link --> Repeater B <--> LoRa network B
```
Use the exact board's repeater image with RS-232 support. Check
`get bridge.type`: its answer must include `rs232`. This transport is optional;
its presence in an image does not mean its UART is enabled. A Companion image
or a room-server build without RS-232 does not gain the transport from these
commands.
## Configure the serial link
Use the UART and pin map for the exact board and image. Connect the two sides
with the appropriate serial wiring and any required line drivers; a board's
UART pins do not automatically provide RS-232 voltage levels. Avoid a UART
already occupied by another peripheral.
Open each board's USB console. Run the following on both boards, using the same
baud rate:
```text
set rs232.enabled off
set bridge.baud 115200
set bridge.source tx
set bridge.delay 500
set repeat on
set rs232.enabled on
get rs232.enabled
get rs232.running
get rs232.status
get rs232.transport
```
Use `bridge.uart` only where the board offers a supported choice, while RS-232
is stopped. Canonical GPS-enabled RAK4631 builds use UART2
(`set bridge.uart 2`); UART1 requires a compatible GPS-free image. The command
rejects UART choices unavailable in the build or unsafe for an active peripheral.
`rs232.enabled` selects the UART independently of MQTT and ESP-NOW in combined
images. The historical `bridge.enabled` alias can select ESP-NOW in MQTT images,
so use the transport-specific `rs232.enabled` control for these checks.
`bridge.source tx` bridges packets transmitted on LoRa after the repeater's
forwarding decisions. An existing `bridge.source rx` setup is also valid: it
bridges received packets before those decisions. Normal scope, filters,
duplicate suppression and repeat settings still affect mesh delivery. Configure
each side's LoRa network separately; see the [bridge CLI reference](cli_commands.md#bridge-when-bridge-support-is-compiled-in).
## Distinguish power state from transport activity
`get rs232.status` retains the existing heartbeat and automatic-standby report.
It separates saved intent, actual UART state, standby/probe phase and confirmed
versus legacy/unknown peer liveness. `get rs232.transport` adds the serial
transport diagnostic view. A running UART means local startup succeeded; it
does not prove the other board received a frame. With RS-232 explicitly
disabled, its transport/counter commands may report diagnostics unavailable
because there is no current UART bridge object.
Heartbeat and negotiated automatic standby are on by default. A fresh,
session-matched heartbeat reply proves bidirectional communication with a
supporting peer. Ordinary incoming mesh data proves only inbound reachability.
See [heartbeat and automatic standby](cli_commands.md#rs232-heartbeat-and-automatic-standby)
before changing power settings. A diagnostic probe does not replace heartbeat
negotiation, enable a disabled UART or establish peer authentication.
## Test each serial direction without LoRa forwarding
Updated RS-232 bridge images include runtime diagnostics without a
`BRIDGE_DEBUG` build flag or continuous USB logging. On both boards:
```text
rs232 resetstats
get rs232.transport
get rs232.stats test
```
On A, send one probe:
```text
rs232 test A1B2C3D4
```
`OK - test queued id=A1B2C3D4; confirm on peer` confirms local queueing only.
On B, read `get rs232.stats test`: `rx` must increase and `rxid` must match
`A1B2C3D4`. Then send `rs232 test B1C2D3E4` on B and confirm that ID on A.
These are two one-way tests. Local UART write completion alone is not peer
receipt.
The optional ID is exactly eight hexadecimal digits, without `0x`; omitting
it uses uptime in milliseconds. Probes are transport diagnostics, not security
tokens or MeshCore packets. They do not prove normal mesh delivery or
authenticate a peer. There is no automatic echo, retry or LoRa forwarding.
Older firmware ignores the extension and cannot report a received ID; use an
updated peer on both sides. Sending a test and resetting counters require a
local console and do not save preferences.
A write deadline records one failure. An entirely unsent probe is cancelled;
if the UART already accepted a prefix, the bridge retains and drains the
original suffix before starting another frame. Each main-loop pass does
bounded work, without retransmitting the prefix. This avoids leaving an older
receiver partway through a control frame. A late completion can increment
`sent` while the earlier `fail` remains; confirm receipt using the other board's
`rx` change and matching `rxid`.
## Locate a mesh forwarding failure
If both probe directions work, send one fresh identifiable message from a
Companion on network A and compare these pages on both repeaters:
```text
get rs232.stats
get rs232.stats rx
get rs232.stats tx
get rs232.stats drops
```
Repeat in the other direction with a different message. Compare counter
changes for the attempt rather than treating old totals as its result. Admission
to the mesh means queued for normal processing; it does not prove a completed
LoRa transmission or end-to-end delivery. If both repeaters already heard a
message directly on LoRa, duplicate suppression can reject a later serial copy.
The RX page separates framing, checksum, packet parsing, partial-frame timeout
and mesh-pool pressure. The TX and drops pages distinguish UART backpressure
from stopped/busy state, filters and duplicate suppression. Byte counters include
heartbeat and diagnostic traffic as well as mesh frames; they do not measure
mesh payload alone.
Counters belong to the current bridge object. They survive automatic standby,
but disabling or reconfiguring RS-232 can replace the object and clear them.
Reboot and `rs232 resetstats` also start a new observation window.
The [RS-232 diagnostic CLI reference](cli_commands.md#diagnose-the-rs232-bridge)
describes the status fields, counter pages and their observation window.
## Optional short USB debug capture
Record both `get usb.logging` and `get usb.debug`, then enable both gates with
`set usb.logging on` and `set usb.debug on`. Send the probes or one fresh mesh
message and restore both original settings afterward. The ordinary image emits
bounded `RS232:` updates from its main loop at most once per second when
diagnostic state changes. A busy USB console can skip an update; use the counter
pages for exact values. Neither logging gate is required for the CLI counters
or test probes.
These diagnostics identify local serial activity and rejection stages. They do
not certify a physical cable, line driver, or end-to-end LoRa path without the
corresponding peer and message checks.