Add runtime RS232 bridge diagnostics and wired link probes
This commit is contained in:
1 parent
e7b863494c
commit
281f1a5199
22 files changed
+1468
-24
No files matched your search
+99
-2
@@ -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
|
||||
|
||||
@@ -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.
|
||||
Reference in new issue
Block a user