Release v3.3.0 - April 30, 2026

[jnilo1]

A reliability release for Thread / OT-RCP users: closes #89 (HandleRcpTimeout() after ~1 h at 460800 baud) at the operating-system layer. Bundles two unrelated 8250 driver hardenings from an out-of-band audit, and a substantial refactor of flash_efr32.sh that resolves long-standing UX issues around switching radio modes.

In-place upgrade — no fullflash needed. radio.conf, network, password, Thread credentials, SSH keys are all preserved. Use flash_install_rtl8196e.sh -y <gateway-IP> as usual.

Hardware UART flow control — the actual fix for #89

If you saw repeated HandleRcpTimeout() / Failed to communicate with RCP errors in otbr-agent logs after roughly an hour at 460800 baud, this release fixes that.

Root cause: S70otbr was opening /dev/ttyS1 with default termios — no CRTSCTS — so the 8250 kernel driver never engaged its hardware flow-control bit. The gateway therefore ran without RTS/CTS at all. At 460800 the 16-byte RX FIFO fills in ~280 µs; under bursty Spinel traffic — Matter commissioning attestation in particular — the kernel could not drain it fast enough and the FIFO would overrun. Lost bytes corrupted HDLC frames, otbr-agent lost sync, eventually gave up.

@olivluca's 14-h baseline at 115200 was clean because at that rate the FIFO budget is ~1.1 ms — enough to absorb burst latency without flow control. That data point split the search space and pointed straight at flow-control configuration as the culprit.

The fix is one line in S70otbr: append &uart-flow-control=true to the spinel radio URL. otbr-agent now sets CRTSCTS, the 8250 core sets MCR_AFE (bit 29 of the 32-bit MCR alias on this SoC), and the hardware auto-asserts RTS when the FIFO approaches full, throttling the EFR32. Validated with a 3 h+ continuous run, two Matter sleepy devices paired, two consecutive commissioning bursts: zero overruns.

To verify the fix landed on a running v3.3.0 gateway:

ssh root@<gw> "stty -F /dev/ttyS1 -a | grep -o '\bcrtscts\b.\?'"
# expected: crtscts (no leading dash)

ssh root@<gw> "devmem 0x18002110 32"
# expected: 0x2B000000  (AFE bit 29 is set)

ssh root@<gw> "cat /proc/tty/driver/serial | grep ttyS1"
# expected: no 'oe:' field after sustained 460800 traffic

Kernel 8250_rtl819x.c — defensive layers + audit hardening

Four changes in the custom RTL8196E UART driver. Two are belt-and-suspenders for #89, two are unrelated audit findings bundled in because we were touching the same file.

Defensive layers for #89. With MCR_AFE engaged the FIFO can't overrun by spec, but the path is now hardened so a future config drift can't reintroduce the failure mode silently:

• RX FIFO trigger lowered from 8 to 4 bytes (UART_FCR_R_TRIG_01). Gives the kernel ~210 µs of IRQ latency budget at 460800 instead of ~140 µs, absorbing scheduling spikes on the single-core 200 MHz Lexra.
• The SoC-specific AFE bit RMW is now wrapped in port->lock (irqsave). Closes a race where the 8250 core's byte-level MCR writes (serial8250_set_mctrl, em485_stop_tx) could clobber the AFE bit between our readl() and writel(). Audit finding 8250RTL-003.

Audit hardening, orthogonal to #89:

• The realtek,syscon device-tree phandle is now mandatory (audit 8250RTL-001). If it's missing at probe time, the driver fails explicitly instead of registering a ttyS1 that looks usable but has no signal on the EFR32 pins.
• The driver now refuses to register on a line other than ttyS1 (audit 8250RTL-002). The kernel UART bridge, S50uart_bridge, S70otbr, and radio.conf all assume /dev/ttyS1 — accepting an opportunistic line would silently mis-wire the bridge.

flash_efr32.sh — switch-mode UX, baud sweep, hardening

Substantial robustness pass on the EFR32 over-the-air flash script. Resolves three UX items that had piled up over the v3.0–v3.2 cycle:

• Bridge ↔ radio.conf reconciliation. Editing /userdata/etc/radio.conf to switch modes (Zigbee ↔ OTBR) used to require a manual sysfs rearm before the script would work. Now the script disarms + rearms the in-kernel UART bridge at the new baud and flow_control automatically.
• Symmetric baud-fallback sweep. When the standard probe at the radio.conf baud fails, the script now tries {115200, 230400, 460800, 691200, 892857} in turn (skipping the one already tried) before giving up. The previous code only tried 115200, missing the inverse case (radio.conf=115200 but chip really at 460800 from a prior test).
• ./flash_efr32.sh -g IP otrcp Just Works on a Zigbee-installed gateway. Combination of the two changes above with the existing post-flash radio.conf write-back means no more manual radio.conf edits or sysfs gymnastics to switch radio mode.

Plus a handful of smaller robustness wins, bundled here while the script was being touched:

• --firmware-file PATH option for explicit GBL selection — useful for testing custom builds outside the repo's firmware/ tree. Refuses ambiguous matches (the old ls -t … | head -1 silently picked the most recent by mtime, which could hide a stale or wrong image).
• USF venv version pin sanity check — if universal-silabs-flasher in the pinned venv is not 1.0.3, reinstall before use; abort if reinstall didn't take. Prevents the probe-method CLI drift bugs that motivated the venv pin in the first place (Usage: universal-silabs-flasher [OPTIONS] COMMAND [ARGS]... #92).
• assert_bridge_idle() race protection: rechecks that no TCP client has grabbed :8888 between detection and the actual flash.
• Sysfs writes now read back the value to catch silent failures.
• tail -1 defensive parse on FIRMWARE_BAUD lookup, so duplicate keys in radio.conf (manual edits, stale migrations) resolve to the last value rather than the first. The same defensive pattern was added to S70otbr and S50uart_bridge.

Known issue — S40button SIGSEGV (intermittent)

S40button may receive a SIGSEGV from busybox after some hours of idle polling — observed once in ~1 h 21 m of dev-box uptime, not reproducible on demand. The shell process dies; the long-press → recover_efr32 recovery surface is silently lost until the next reboot. The radio path (otbr-agent, S50uart_bridge, S70otbr) is independent and unaffected. Pre-existing — not introduced by v3.3.0. A follow-up release will add a supervisor that respawns S40button if it exits unexpectedly.

If you want to check whether your gateway has lost the long-press handler:

ssh root@<gw> "[ -f /var/run/S40button.pid ] && kill -0 \$(cat /var/run/S40button.pid) && echo alive || echo DEAD"

A reboot brings it back; the long-press itself still works for you in the meantime via ssh root@<gw> recover_efr32 or via flash_install_rtl8196e.sh for full re-flash.

Upgrade

./flash_install_rtl8196e.sh -y <gateway-IP>

In-place upgrade — no fullflash required from v3.2.x. Existing radio.conf is preserved across the upgrade, so no migration friction. The uart-flow-control=true flag activates on the first reboot after userdata is updated.

If you'd rather not type the password during an unattended upgrade:

SSH_PASSWORD=<root password> ./flash_install_rtl8196e.sh -y <gateway-IP>

(Requires sudo apt install sshpass.)

Acknowledgments

• @olivluca — the 14 h baseline at 115200 vs the failure at 460800 was the data point that pointed the investigation in the right direction.
• @skinkie — the earlier radio.conf mandatory work (radio.conf not written #93, v3.2.1) made this release simpler to ship.

Full changelogs

• RTL8196E platform CHANGELOG
• EFR32 firmware CHANGELOG