diff --git a/ziggurat/CHANGELOG.md b/ziggurat/CHANGELOG.md index b17fd6e..9ddd580 100644 --- a/ziggurat/CHANGELOG.md +++ b/ziggurat/CHANGELOG.md @@ -1,5 +1,15 @@ # Changelog +## 0.3.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). + - Targets the next zigpy/ziggurat release (past the current 0.1.0 on crates.io, + which predates the change above); the `ZIGGURAT_VERSION` build arg will need + confirming against whatever version is actually published. + ## 0.2.0 - Bump ziggurat to the 0.1.0 release on crates.io. 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/Dockerfile b/ziggurat/Dockerfile index 731bbc7..266c9bc 100644 --- a/ziggurat/Dockerfile +++ b/ziggurat/Dockerfile @@ -4,7 +4,12 @@ FROM rust:1-alpine AS builder RUN apk add --no-cache musl-dev -ARG ZIGGURAT_VERSION=0.1.0 +# Targets the next zigpy/ziggurat release (the one including TCP RCP-transport +# support, PR #39) rather than the current 0.1.0 on crates.io, which predates it. +# zigpy/ziggurat's publish workflow stamps the crate version from the release tag at +# publish time, not from its Cargo.toml, so the exact next version number is whatever +# tag its maintainer cuts — confirm/adjust this before merging. +ARG ZIGGURAT_VERSION=0.2.0 ENV CARGO_PROFILE_RELEASE_LTO=true \ CARGO_PROFILE_RELEASE_CODEGEN_UNITS=1 \ diff --git a/ziggurat/config.yaml b/ziggurat/config.yaml index 024173d..97e8850 100644 --- a/ziggurat/config.yaml +++ b/ziggurat/config.yaml @@ -1,5 +1,5 @@ --- -version: 0.2.0 +version: 0.3.0 slug: ziggurat name: Ziggurat Zigbee Server description: Open source host-side Zigbee stack written in Rust @@ -16,11 +16,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: >-