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:

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:

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.

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 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:

rs232 resetstats
get rs232.transport
get rs232.stats test

On A, send one probe:

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:

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 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.