From 190d5d7b9a6c7bf0ff12f280df8a3a035222971c Mon Sep 17 00:00:00 2001 From: tube0013 Date: Tue, 21 Jul 2026 20:34:42 -0400 Subject: [PATCH] Add network_address option to connect to the RCP over TCP Adds a network_address config option (tcp://host:port) that takes priority over the device serial-port picker when set, wired through to ziggurat-server's --device flag (zigpy/ziggurat#39, merged). Wi-Fi-connected radios are not recommended. The device field is still required by the add-on's config form even when network_address is set (the form won't validate otherwise), but its value is functionally ignored in that case. Retains upstream's pinned Ziggurat revision and minimum Home Assistant version. Bumps the add-on to 0.5.0 for the new TCP configuration option. Co-Authored-By: Claude Sonnet 4.6 --- ziggurat/CHANGELOG.md | 7 +++++ ziggurat/DOCS.md | 29 +++++++++++++++---- ziggurat/config.yaml | 6 ++-- .../etc/s6-overlay/s6-rc.d/ziggurat/run | 8 +++-- ziggurat/translations/en.yaml | 15 ++++++++-- 5 files changed, 52 insertions(+), 13 deletions(-) diff --git a/ziggurat/CHANGELOG.md b/ziggurat/CHANGELOG.md index 6588be2..8aaaa38 100644 --- a/ziggurat/CHANGELOG.md +++ b/ziggurat/CHANGELOG.md @@ -1,5 +1,12 @@ # Changelog +## 0.5.0 + + - Adds a `network_address` option to connect to the RCP over a raw TCP socket + (`tcp://host:port`, e.g. a network-attached RCP or a `ser2net`-style + serial-to-TCP bridge) instead of a local serial device. Wi-Fi-connected radios + are not recommended — see [zigpy/ziggurat#39](https://github.com/zigpy/ziggurat/pull/39). + ## 0.4.0 - Bump ziggurat to 1e319a4c. diff --git a/ziggurat/DOCS.md b/ziggurat/DOCS.md index 734c28a..3cf1d10 100644 --- a/ziggurat/DOCS.md +++ b/ziggurat/DOCS.md @@ -17,29 +17,41 @@ losing the network. ## Installation -1. Flash the radio with OpenThread RCP firmware (460800 baud, hardware flow control). +1. Flash the radio with OpenThread RCP firmware (460800 or higher baud, hardware flow control). 2. Install the app and select the radio under **Device**. 3. Start the app. 4. Configure ZHA with radio type `ziggurat` and device path - `socket://local_ziggurat:9999`. An existing EmberZNet or Z-Stack network can be + `ws://local-ziggurat:9999`. An existing EmberZNet or Z-Stack network can be migrated by restoring its network backup. ## Configuration -### Option: `device` (required) +### Option: `device` -The serial port the 802.15.4 RCP radio is attached to. +The serial port the 802.15.4 RCP radio is attached to. The add-on's configuration +form requires a selection here even when using `network_address` — it won't validate +otherwise — but the value is functionally ignored once `network_address` is set. +Pick any attached serial device; it won't actually be used. + +### Option: `network_address` + +Connect to the RCP over a raw TCP socket instead of a local serial port, e.g. +`tcp://192.168.1.50:6638` — for a network-attached RCP or a `ser2net`-style +serial-to-TCP bridge. Takes priority over `device` when set. WiFi connected +devices are not recommended. ### Option: `baudrate` The serial baudrate of the RCP firmware. The default (460800) matches the -firmware shipped for the ZBT-1/ZBT-2. +firmware shipped for the ZBT-1/ZBT-2. This setting is ignored if `network_address` +is set. ### Option: `flow_control` The serial flow control mode (`hardware`, `software`, `none`). The RCP UART drops bytes under load without hardware flow control, corrupting frames; only -change this if the radio's firmware was built without it. +change this if the radio's firmware was built without it. This setting is ignored +if `network_address` is set. ### Option: `log_level` @@ -94,3 +106,8 @@ services: `--cap-add SYS_NICE` lets the stack raise its scheduling priority. It is optional but recommended. + +To connect to the RCP over TCP instead of a serial device, set +`ZIGGURAT_NETWORK_ADDRESS` (e.g. `tcp://192.168.1.50:6638`) instead of +`ZIGGURAT_DEVICE`; `--device` and the `devices:`/`--cap-add SYS_NICE` serial-port +plumbing are then unnecessary. diff --git a/ziggurat/config.yaml b/ziggurat/config.yaml index 940181b..9db0d0d 100644 --- a/ziggurat/config.yaml +++ b/ziggurat/config.yaml @@ -1,5 +1,5 @@ --- -version: 0.4.0 +version: 0.5.0 slug: ziggurat name: Ziggurat Zigbee Server description: Open source host-side Zigbee stack written in Rust @@ -17,11 +17,13 @@ privileged: - SYS_NICE options: device: null + network_address: null baudrate: 460800 flow_control: hardware log_level: info schema: - device: device(subsystem=tty) + device: device(subsystem=tty)? + network_address: str? baudrate: int flow_control: list(hardware|software|none) log_level: list(error|warn|info|debug|trace) diff --git a/ziggurat/rootfs/etc/s6-overlay/s6-rc.d/ziggurat/run b/ziggurat/rootfs/etc/s6-overlay/s6-rc.d/ziggurat/run index bae1a91..70b1aa7 100755 --- a/ziggurat/rootfs/etc/s6-overlay/s6-rc.d/ziggurat/run +++ b/ziggurat/rootfs/etc/s6-overlay/s6-rc.d/ziggurat/run @@ -12,13 +12,17 @@ declare listen if bashio::fs.file_exists '/data/options.json'; then # Addon mode: Supervisor provides /data/options.json - device=$(bashio::config 'device') + if bashio::config.has_value 'network_address'; then + device=$(bashio::config 'network_address') + else + device=$(bashio::config 'device') + fi baudrate=$(bashio::config 'baudrate' '460800') flow_control=$(bashio::config 'flow_control' 'hardware') log_level=$(bashio::config 'log_level' 'info') else # Plain Docker mode: configuration comes from the environment variables - device="${ZIGGURAT_DEVICE}" + device="${ZIGGURAT_NETWORK_ADDRESS:-${ZIGGURAT_DEVICE}}" baudrate="${ZIGGURAT_BAUDRATE:-460800}" flow_control="${ZIGGURAT_FLOW_CONTROL:-hardware}" log_level="${ZIGGURAT_LOG_LEVEL:-info}" diff --git a/ziggurat/translations/en.yaml b/ziggurat/translations/en.yaml index 2aedf44..b44d2ac 100644 --- a/ziggurat/translations/en.yaml +++ b/ziggurat/translations/en.yaml @@ -2,16 +2,25 @@ configuration: device: name: Device - description: The serial port where the OpenThread RCP radio is attached. + description: >- + The serial port where the OpenThread RCP radio is attached. Required by this + form even when Network Address is set (it won't validate otherwise), but the + value is ignored once Network Address is set — pick any attached device. + network_address: + name: Network Address + description: >- + Connect to the RCP over TCP instead of a local serial port, e.g. + tcp://192.168.1.50:6638. Takes priority over Device when set. baudrate: name: Baudrate - description: The serial baudrate of the RCP firmware. + description: >- + The serial baudrate of the RCP firmware. Ignored if Network Address is set. flow_control: name: Flow control description: >- The serial flow control mode. The RCP UART drops bytes under load without hardware flow control; only change this if the radio's firmware was built - without it. + without it. Ignored if Network Address is set. log_level: name: Log level description: >-