Release v2.1.2 — March 23, 2026

[jnilo1]

Bug fix release addressing community feedback. Upgrade path:

./flash_install_rtl8196e.sh gateway_ip

Bug fixes

• Skeleton cross-contamination between flashes: build and flash scripts injected gateway config (passwd, eth0.conf, radio.conf, dropbear keys, Thread credentials) directly into the skeleton/ directory, leaving residual files between runs. Flashing one device in OTBR mode then another in Zigbee mode leaked radio.conf — the second device started in OTBR mode. All scripts now work on a temporary copy of the skeleton via SKELETON_DIR; the original is never modified. Credit: @olivluca (#73).

• S70otbr redundant flash writes: the sync daemon wrote to flash on every boot (first poll compared against an empty string) and unconditionally on shutdown. Fixed: last_dataset is now seeded from the REST API before entering the poll loop, and the shutdown trap no longer copies — the daemon syncs on dataset change only. Frame counters are ephemeral (OpenThread recovers by jumping ahead). Credit: @olivluca (#66).

• Serial console backspace: replaced askfirst + login with getty -L 38400 ttyS0 vt100 in rootfs inittab — backspace now works at the login prompt.

Full changelog

• RTL8196E CHANGELOG

[olivluca]

Great work, thank you, I flashed both devices with no issue whatsoever (well, apart from forgetting, as always, to add /usr/sbin to my PATH 🤣)

[MaxRower]

New test scenario: I added the second gateway running otbr to HA with the existing/first gateway with OTBR on the host. It seemed to integrate fine, HA showed both instances of OTBR in my OpenThread network. The topogly view in OTBR Web GUI displayed it as an additional router. The network was stable for a long time, until I made a test by disconnecting the first gateway (with OTBR on the host). Then everything stopped working, even after several minutes, it did not start to work again.
Running ot-ctl debug on the second/new gateway showed, it had aquired the matter services (srp server service). But nothing was functional, no more data from the ALPSTUGA sensor.
After reconnecting the first gateway, and later restarting all HA, matter and otbr, still nothing worked. Finally after disconnecting the second gateway, things started to work again after some time.

[jnilo1]

This looks like a Thread border router failover issue, most likely caused by conflicting Thread datasets between the two gateways.

In a multi-BR Thread network, when one border router goes down the remaining one should take over seamlessly. The fact that it didn't — and that even reconnecting the first BR + restarting everything didn't help until the second was physically removed — strongly suggests the two gateways were not sharing the exact same active dataset (network key, PAN ID, channel, etc.).

What probably happened:

1. Both gateways appeared to be on the same Thread network, but their datasets had subtle differences (e.g., different partition IDs or stale commissioning data)
2. When the first gateway went down, the second became leader and acquired the SRP services, but the end devices (ALPSTUGA) could not route through it properly
3. When the first was reconnected, both BRs competed with conflicting state, causing a network split that couldn't heal

To fix this, ensure both gateways share the exact same Thread dataset before joining:

1. Reset the Thread data on the second gateway:

   If running OTBR on the host (Docker):

   docker compose down
   docker volume rm otbr_data
   docker compose up -d

   If running OTBR on the gateway (native):

   ssh root@<gateway_ip> "rm -rf /userdata/thread && reboot"

2. In Home Assistant, go to Settings → Devices & Services → Thread and check that both border routers show the same network name and credentials. HA should provision the second BR automatically with the correct dataset from the first one.

3. Once both are confirmed on the same network, try the failover test again (disconnect the first gateway).

Could you check what ot-ctl dataset active shows on each gateway? If the datasets differ, that confirms the diagnosis.

[MaxRower]

I think, none of the border routers was a leader, it was the ALPSTUGA device.
When I added the second gateway to HA, it was not configured, so HA synced the configuration to it. I wil test it again in the next days.
With only the first gateway running, the state is still "router".

[MaxRower]

Current status:


So the ALPSTUGA is still the leader, am I right?

[jnilo1]

Yes, the ALPSTUGA is the leader — that's perfectly normal. The ALPSTUGA is a mains-powered device, so it acts as a Full Thread Device (router) and can be elected leader. The leader role is a Thread mesh management function (address allocation, router ID assignment) and is independent from the border router role (IP routing to the backbone network). Any router in the mesh can become leader.

So your topology is healthy: the ALPSTUGA is the leader, and your border router is a router — that's a valid and common configuration.

Regarding the failover issue, I'm interested in your retest results. Since HA synced the dataset automatically to the second gateway, the credentials should have been correct. The problem might be on the backbone (Ethernet/Wi-Fi) side rather than the Thread side — when the first BR went down, HA may have kept trying to route through its IP address instead of switching to the second BR's address.

[MaxRower]

I now tried to change the channel (from 11 to 25) on the other location, but it did not work.

~ # ot-ctl channel
11
Done
~ # ot-ctl channel 25
Error 13: InvalidState
~ # ot-ctl channel manager
Error 7: InvalidArgs

Channel manager is not enabled in this build.

[jnilo1]

ot-ctl channel 25 does not work when the node is already attached to a Thread network (state: router/child/leader) — hence the InvalidState error. This is expected behavior.

To change the channel on a live Thread network, you need to use a pending dataset, which schedules the channel change across all nodes in the mesh:

ot-ctl dataset init active
ot-ctl dataset channel 25
ot-ctl dataset commit active

However, the recommended way is to do it through Home Assistant → Settings → Devices & Services → Thread, which handles the pending dataset migration properly and ensures all border routers and devices switch together.

Regarding the channel manager: it was not enabled in v2.1.2 but I just added it to the next release (+14 KB, negligible). In the meantime, if you want it now, rebuild otbr-agent with two extra flags:

cd 3-Main-SoC-Realtek-RTL8196E/34-Userdata/ot-br-posix
./build_otbr.sh main -DOT_CHANNEL_MANAGER=ON -DOT_CHANNEL_MONITOR=ON

Then copy the binary to the gateway:

cat build/src/agent/otbr-agent | ssh root@<gateway_ip> "cat> /userdata/usr/bin/otbr-agent"

Then

restart /userdata/etc/init.d/S70otbr

After that, ot-ctl channel manager should work.

[MaxRower]

However, the recommended way is to do it through Home Assistant → Settings → Devices & Services → Thread, which handles the pending dataset migration properly and ensures all border routers and devices switch together.

Does not work either.

[MaxRower]

rebuild otbr-agent with two extra flags

On laptop I'm currently working, it sadly fails, can't even install_deps.sh without errors. But it's the current Beta of Ubuntu 26.04, which probably is the cause. Maybe I should switch to the older laptop, with 24.04.

[jnilo1]

Fixed in v2.1.3 — otbr-agent is now built with OT_CHANNEL_MANAGER and OT_CHANNEL_MONITOR.

Two ways to change the channel:

From Home Assistant UI:
Settings → Devices & Services → Thread → Configure → select the border router → change channel. The change propagates across the mesh automatically (takes ~5 minutes).

From the gateway CLI:

ssh root@<gateway_ip>
ot-ctl channel manager change 20

You can check the status with:

ot-ctl channel manager    # shows requested channel
ot-ctl channel             # shows current channel

Note: ot-ctl channel 20 (without manager) won't work when the node is attached — that's expected (InvalidState). The channel manager command is the correct way to change the channel on a running network.

Technical note: We also had to patch the ot-br-posix REST API at build time. The upstream project recently switched its JSON keys from PascalCase (ActiveTimestamp, NetworkKey...) to camelCase (activeTimestamp, networkKey...), but Home Assistant's python-otbr-api library (< 2.9.0) still expects PascalCase. Without the patch, HA reports "Failed to call OTBR API" and cannot interact with the border router (channel change, dataset display, etc.). Our build_otbr.sh detects the camelCase format and converts it back to PascalCase automatically. This patch will be skipped when the upstream reverts or when HA updates its library.

Upgrade with:

./flash_install_rtl8196e.sh gateway_ip

See Release v2.1.3 for all changes.

[MaxRower]

Could you add an sftp-server module and/or scp on the next release? Just tried to copy my thread dir before running an update. It would make automatic backups simpler as well.
Edit: just realized, this is the one I use for otbr on the host, so in that case, not necessary.
another edit: oh no, this had an old version of the firmware running, now I need to connect the serial port to the device hidden in a box.

[jnilo1]

Hi,

Thanks for the suggestion! However, adding native SCP support to the RTL8196E gateway would add a complexity to the build (SFTP/SCP2 protocol stack, OpenSSH sftp-server, etc.) that I'd rather avoid on such a constrained target.

You can already achieve the same result with a simple shell wrapper around cat + ssh, which only requires the binaries already present on the BusyBox rootfs. Since the gateway only runs as root, the wrapper is straightforward:

#!/bin/sh
# myscp - scp-like wrapper using cat + ssh (root only)
# By default, sets +x on uploaded files. Use -n to skip.

usage() {
    echo "Usage: myscp [-n] <src> <host>:<dst>"
    echo "       myscp <host>:<src> <dst>"
    exit 1
}

EXEC=1

while getopts "n" opt; do
    case $opt in
        n) EXEC=0 ;;
        *) usage ;;
    esac
done
shift $((OPTIND - 1))

[ $# -ne 2 ] && usage

if echo "$1" | grep -q ':'; then
    # Download: host:src -> dst
    HOST="${1%%:*}"
    SRC="${1#*:}"
    DST="$2"
    ssh "root@$HOST" "cat '$SRC'" > "$DST"
else
    # Upload: src -> host:dst
    SRC="$1"
    HOST="${2%%:*}"
    DST="${2#*:}"
    if [ "$EXEC" -eq 1 ]; then
        cat "$SRC" | ssh "root@$HOST" "cat > '$DST'; chmod +x '$DST'"
    else
        cat "$SRC" | ssh "root@$HOST" "cat > '$DST'"
    fi
fi

Usage:

myscp firmware.bin 192.168.1.1:/tmp/firmware.bin     # chmod +x applied (default)
myscp -n config.txt 192.168.1.1:/etc/config.txt      # no chmod +x
myscp 192.168.1.1:/etc/config.txt ./config.txt       # download, unchanged

A word on permissions: cat > file creates the file with the current session umask (typically 644), so original permissions are not preserved. The default chmod +x behaviour covers the most common use case on this gateway (uploading scripts or firmware). For plain config files, just pass -n.

Hope this helps!

[olivluca]

Wouldn't it be enough to add "scp" here (and the relevant symlink)?