openthread-br: locate the RCP dongle through otbr-rcp

The protocol handler required a hand-written radio_url, so pointing the
border router at its dongle meant knowing which ttyACM the kernel had
picked, and a replug that renumbered the device broke the interface
until someone edited the config.

Bring over the otbr-rcp wrapper from the matter-openwrt packaging: when
no radio_url is set, the handler resolves the dongle by its USB
properties (a cdc_acm interface on a device whose product string names
OpenThread), with an rcp option to pin a bus position or a fixed serial
device, and optional firmware install and update through handler
plugins. Discovery runs in the setup phase rather than under the
launched command, since a flash can take minutes and must not race the
bounded wait for the agent's ubus object.

Firmware install and update are off by default: flashing is an explicit act,
and with the radio no longer required to be named, a configuration that
mentions no RCP at all now reaches this path. The one value the handler needs
is picked out of otbr-rcp's output rather than evaluated, since otbr-rcp
sources every firmware handler plugin and stdout from one of those would
otherwise run as root in the proto handler.

A missing dongle fails setup with the restart block every failure
needs, netifd retrying immediately and without backoff otherwise. The
USB hotplug handler brings such interfaces up again when a device
binds, keyed on the recorded RCP_NOT_FOUND error so interfaces an
administrator took down on purpose stay down. An explicit radio_url
keeps today's behaviour.

Assisted-By: Claude Fable 5
Signed-off-by: Christian Glombek <c.glombek@cosa.systems>

Author: LorbusChris

net/openthread-br/Makefile

@@ -6,7 +6,7 @@ include $(TOPDIR)/rules.mk
 PKG_NAME:=openthread-br
 PKG_VERSION:=2026.08.0
 PKG_SOURCE_VERSION:=v$(PKG_VERSION)
-PKG_RELEASE:=1
+PKG_RELEASE:=2
 
 PKG_SOURCE_PROTO:=git
 PKG_SOURCE_URL=https://github.com/openthread/ot-br-posix.git
@@ -91,10 +91,13 @@ endef
 
 define Package/openthread-br/install
 	$(INSTALL_DIR) \
+		$(1)/etc/hotplug.d/usb \
 		$(1)/etc/init.d \
 		$(1)/lib/netifd/proto \
 		$(1)/usr/sbin
 	$(INSTALL_BIN) ./files/openthread-proto.sh $(1)/lib/netifd/proto/openthread.sh
+	$(INSTALL_BIN) ./files/otbr-rcp $(1)/usr/sbin
+	$(INSTALL_DATA) ./files/otbr-rcp.hotplug $(1)/etc/hotplug.d/usb/50-otbr-rcp
 	$(INSTALL_BIN) $(PKG_INSTALL_DIR)/usr/sbin/* $(1)/usr/sbin
 endef
 

net/openthread-br/README.md

@@ -126,17 +126,57 @@ config interface 'thread'
         option device 'wpan0'
         option proto 'openthread'
         option backbone_network 'lan'
-        option radio_url 'spinel+hdlc+uart:///dev/ttyACM0?uart-baudrate=460800'
+        option rcp '2-1'
+        option uart_baudrate '460800'
         list prefix 'fd6f:5772:5468:7200::/64 paros'
         option verbose '0'
 ```
 
-Only backbone_network, device and radio_url are required; the protocol handler
-fails the interface if one of them is missing, or if backbone_network names an
-interface that has no device. Everything else — dataset, prefix, verbose,
+Only backbone_network and device are required. A radio need not be named at
+all: with neither rcp nor radio_url set the handler behaves as if `rcp 'any'`
+were given and auto-discovers a dongle, failing the interface with
+RCP_NOT_FOUND only when none is found. It also fails if backbone_network names
+an interface that has no device. Everything else — dataset, prefix, verbose,
 rest_listen_address and rest_listen_port — is optional. See
 [REST Server](#rest-server) before moving the REST API off the loopback
-default. If something isn't working, check ifstatus for the OpenThread
+default.
+
+### Finding the RCP
+
+The radio is named with the `rcp` option rather than a full radio URL. It takes
+one of three forms:
+
+| value | meaning |
+| --- | --- |
+| `/dev/ttyACM0` | a fixed serial device; no discovery is done |
+| `2-1` | a USB bus position, resolved to whatever serial device it currently exposes |
+| `any` (the default) | pick a dongle automatically |
+
+`uart_baudrate` and `uart_flow_control` are appended to the resulting URL, and
+the port is always opened exclusively. `uart_baudrate` is unset by default,
+leaving the port at otbr-agent's own default; `uart_flow_control` defaults to
+1, so hardware flow control is on unless it is set to 0. Turn it off for a
+3-wire UART, or for a dongle that never asserts CTS. Setting `radio_url`
+directly still works and overrides all of this.
+
+Discovery resolves USB dongles, which requires the cdc_acm driver: only an
+interface bound to it is accepted, and the `/dev/ttyACM*` node does not exist
+without it. Install `kmod-usb-acm` if it is not already present. A
+UART-attached radio named through `/dev/tty*` or `radio_url` needs none of
+this.
+
+Prefer a bus position to `any` unless the dongle advertises itself. Unattended
+selection only accepts a device whose USB product string contains the word
+"OpenThread", which many dongles — the Home Assistant Connect ZBT-2 among them
+— do not. Naming the bus position is the operator saying "this one is the RCP",
+so no product string is needed. `ls /sys/bus/usb/devices/` shows the positions.
+
+`otbr-rcp` also has a plugin point for installing or updating dongle firmware,
+used when `rcp_firmware_update` is set. It is off by default, and no handlers
+ship with this package, so nothing is flashed unless you both add a handler and
+ask for it.
+
+If something isn't working, check ifstatus for the OpenThread
 interface:
 
 ```
@@ -234,7 +274,8 @@ config interface 'thread'
         option backbone_network 'lan'
         option dataset '0e080000000000010000000300000f35060004001fffe0020836b86cd9746ab3080708fd9850cbe719b1d205101f11a11320828c7a6ebc2f2e675c0dca030e686f6d652d617373697374616e740102716f041025804ed78614258ebedf4e2db37b3b6e0c0402a0f7f8'
         list prefix 'fd6f:5772:5468:7200::/64 paros'
-        option radio_url 'spinel+hdlc+uart:///dev/ttyACM0?uart-baudrate=460800'
+        option rcp '2-1'
+        option uart_baudrate '460800'
         option verbose '0'
 ```
 

net/openthread-br/files/openthread-proto.sh

@@ -5,6 +5,7 @@
 
 OTCTL="/usr/sbin/ot-ctl"
 PROG="/usr/sbin/otbr-agent"
+RCP_PROG="/usr/sbin/otbr-rcp"
 
 [ -x "$PROG" ] || exit 0
 
@@ -27,6 +28,10 @@ proto_openthread_init_config() {
 	proto_config_add_string backbone_network
 	proto_config_add_string dataset
 	proto_config_add_string radio_url
+	proto_config_add_string rcp
+	proto_config_add_boolean rcp_firmware_update
+	proto_config_add_int uart_baudrate
+	proto_config_add_boolean uart_flow_control
 	proto_config_add_string rest_listen_address
 	proto_config_add_int rest_listen_port
 
@@ -44,21 +49,60 @@ proto_openthread_setup_error() {
 	exit 1
 }
 
+proto_openthread_setup_retry() {
+	# A missing RCP dongle is not a configuration error, but the interface
+	# must still be blocked: netifd re-runs a failed setup immediately and
+	# without backoff, which would busy-loop until a dongle appears. The
+	# hotplug handler's ifup lifts the block, so recovery is unaffected;
+	# this helper differs from proto_openthread_setup_error only in intent.
+	proto_openthread_setup_error "$@"
+}
+
 proto_openthread_setup() {
 	interface="$1"
 	device="$2"
 
 	mkdir -p /var/lib/thread
 
-	json_get_vars backbone_network dataset device radio_url rest_listen_address rest_listen_port verbose:0
+	json_get_vars backbone_network dataset device radio_url rcp \
+		rcp_firmware_update:0 uart_baudrate:0 uart_flow_control:1 \
+		rest_listen_address rest_listen_port verbose:0
 
 	[ -n "$backbone_network" ] || proto_openthread_setup_error "$interface" MISSING_BACKBONE_NETWORK
 	proto_add_host_dependency "$interface" "" "$backbone_network"
 	network_get_device backbone_ifname "$backbone_network"
 
 	[ -n "$backbone_ifname" ] || proto_openthread_setup_error "$interface" MISSING_BACKBONE_IFNAME
 	[ -n "$device" ] || proto_openthread_setup_error "$interface" MISSING_DEVICE
-	[ -n "$radio_url" ] || proto_openthread_setup_error "$interface" MISSING_RADIO_URL
+	if [ -z "$radio_url" ]; then
+		case "$rcp" in
+		/dev/*)
+			# A fixed serial device needs no discovery.
+			radio_url="spinel+hdlc+uart://$rcp"
+			;;
+		*)
+			# Let otbr-rcp locate the dongle by its USB properties and,
+			# when a handler knows how, install or update its firmware.
+			# This runs here rather than under the launched command: a
+			# flash can take minutes, and it must not race the bounded
+			# wait for the agent's ubus object below.
+			#
+			# Pick the one value we need out of the output rather than
+			# evaluating it: otbr-rcp sources every firmware handler in
+			# /usr/share/openthread-rcp/, and a handler that prints to
+			# stdout would otherwise have its output run as root here.
+			RCPTTY="$("$RCP_PROG" \
+				$([ "$rcp_firmware_update" -eq 0 ] || echo --update) \
+				"${rcp:-any}" | sed -n 's/^RCPTTY=//p')"
+			[ -n "$RCPTTY" ] || \
+				proto_openthread_setup_retry "$interface" RCP_NOT_FOUND
+			radio_url="spinel+hdlc+uart://$RCPTTY"
+			;;
+		esac
+		radio_url="${radio_url}?uart-exclusive"
+		[ "$uart_baudrate" -eq 0 ] || radio_url="${radio_url}&uart-baudrate=${uart_baudrate}"
+		[ "$uart_flow_control" -eq 0 ] || radio_url="${radio_url}&uart-flow-control"
+	fi
 
 	opts="--auto-attach=0"
 	[ "$verbose" -eq 0 ] || append opts -v