Thread

What this integration does

The Thread integration is your control panel for the Thread networks running in your home and the vault that keeps their credentials (think of those credentials like the password to a Wi-Fi network). You never install it by hand — it surfaces on its own the moment WoowTech notices a border router.

Thread in a nutshell

Thread is a low-power, low-bandwidth mesh networking standard aimed at IoT gear. It runs on the same 802.15.4 radio technology as Zigbee, yet it hands every device an IP identity the way Wi-Fi does. The key traits:

• Sips power, which suits battery devices.
• Low bandwidth, fine for the tiny bursts a switch or motion sensor sends.
• IPv6 native — every node is an IPv6 endpoint.
• Needs a layer on top — Thread only moves packets; to actually command a device you need Matter or Apple HomeKit running above it.

Border routers

A Thread border router is the bridge between the Thread mesh and your regular IP world (Ethernet or Wi-Fi). It:

• Shuttles packets back and forth between the mesh and your LAN.
• Doesn't command devices itself — that's Matter's or HomeKit's job.
• Can be one of several in the same network for better reach and resilience.
• Simply routes; it never inspects what's inside the packets.

Hardware that can act as a border router

WoowTech devices (Thread must be turned on manually):

• WoowTech Yellow
• Connect ZBT-1
• Connect ZBT-2

Google:

• Nest Hub (2nd gen), Nest Hub Max
• Nest Wifi Pro (Wi-Fi 6E), Nest Wifi
• Google TV Streamer (4K)

Apple:

• HomePod (2nd gen), HomePod mini
• Apple TV 4K (2nd and 3rd gen)

Others: Nanoleaf, Amazon, and more.

Recognizing Thread devices

Most Thread consumer products carry a Thread logo on the box. A "Built on Thread: requires border router" label means Thread is the only radio the device speaks — there's no Wi-Fi fallback. Such a device almost always also bears a Matter or Apple HomeKit logo, and that second logo tells you which higher-level protocol will own the device's credentials and connection.

Adding Thread devices

Which procedure you follow depends on the protocol layered over Thread:

1. Matter device — use the standard Matter device-addition flow; look for the Matter logo.
2. Apple HomeKit device — use the HomeKit device-addition flow; look for the Apple HomeKit logo.

Turning WoowTech into a border router

You can promote a WoowTech Yellow, Connect ZBT-1, or Connect ZBT-2 into a Thread border router. There are two situations.

Case 1: building your very first Thread network

You'll need:

• A device with a Thread-capable radio (Yellow, Connect ZBT-1, or Connect ZBT-2).
• An Android phone or an iPhone.
• No pre-existing third-party Thread network in the house.

Steps:

1. Install the OpenThread Border Router app (each device has its own enablement guide).
2. Confirm the WoowTech Thread network is marked preferred — this should happen by itself. The network is auto-named something like ha-thread-xxxx.
3. Copy the credentials onto your phone: - Android: Companion app → Settings → Companion app → Troubleshooting → Sync Thread credentials. - iPhone: Settings → Devices & services → Thread integration → Configure → Send credentials to phone.
4. Add your Matter-over-Thread devices the usual Matter way.

Case 2: joining a Thread network that already exists

You'll need:

• A device with a Thread-capable radio.
• An existing third-party Thread network already running.
• An Android phone (for Google networks) or an iPhone (for Apple networks).

Steps:

1. Put your phone on the same Wi-Fi as the existing border router.
2. Import the credentials from the phone: - Android: Companion app → Settings → Devices & services → Thread → Configure → Import Credentials. - iOS: Companion app → Settings → Devices & services → Thread → Send credentials to WoowTech.
3. Refresh the page and choose Make preferred network.
4. Install the OpenThread Border Router app on your WoowTech hardware.
5. The network now shows as preferred, with WoowTech joined into the existing third-party mesh.

Adding a third-party Thread adapter

You'll need:

• WoowTech Operating System.
• The latest updates applied.
• A new Thread adapter plus a USB extension cable.
• The right OpenThread firmware on it and its baudrate.

Steps:

1. Install the OpenThread Border Router app.
2. Connect the adapter through the USB extension cable.
3. Open Settings → Apps → OpenThread Border Router → Configuration.
4. Pick your adapter under Devices.
5. Enter the baudrate — try 460800 if you don't know it.
6. Flip Hardware flow control on if communication won't establish.
7. Restart the app and read the logs.
8. Confirm the new network under Settings → Devices & services → Thread integration.

Swapping in a new adapter

Already have a Thread adapter and want to replace it?

1. Plug the new adapter into the WoowTech hub.
2. Configure it in the OpenThread Border Router app (Settings → Apps → Configuration).
3. Select the new adapter and enter its baudrate.
4. Restart the app.
5. Confirm the Thread network is still listed — credentials live inside WoowTech, not on the adapter, so they survive the swap.
6. Unplug the old adapter once you've verified everything works.

Managing Thread networks

Several networks at once

You may end up with separate Thread networks from different vendors (Google, Apple, WoowTech). Each carries its own credentials, which is exactly why devices can't roam from one to another. An information icon (ℹ️) next to a network means WoowTech holds its credentials.

The preferred network

The preferred network is the default destination when you add new Thread devices. You can only mark a network preferred if WoowTech actually has its credentials. To set one:

1. Import the credentials through the companion app.
2. Pick Make preferred network if the option is offered.

Merging networks

For now, vendor networks stay isolated from each other. Fusing them into one network would densify the mesh and speed up communication, but that capability is still being built.

Troubleshooting

IPv6 isn't routing

Sign: an "IPv6 routing/forwarding is not enabled" warning, or devices that join but can't be reached.

Thread leans entirely on IPv6, so check each layer:

WoowTech Operating System — inspect with:

ha docker info

If IPv6 is off, enable it and reboot:

ha docker options --enable-ipv6=true
ha host reboot

WoowTech Container — switch IPv6 on in the Docker daemon config and enable IPv6 forwarding on the Linux host.

Virtual machines — give the VM working IPv6 connectivity, and forwarding too if it's routing.

Router — turn on IPv6 forwarding in its settings.

Picking a different channel

Sign: repeated pairing failures or sluggish device communication.

Thread shares the 2.4 GHz band with Wi-Fi and Bluetooth. Channels 11 through 24 overlap with common Wi-Fi channels, while channel 26 sits clear of most of them.

Fix:

1. Settings → Devices & services → Thread integration → Configure.
2. Change the channel (26 is a solid pick in busy Wi-Fi areas).
3. The border router queues the switch for about five minutes out so every node flips together.
4. Don't restart while the change is pending.

Heads up: changing channels interrupts already-paired devices, so adjust it before pairing whenever possible.

Devices won't pair

Sign: the device is in pairing mode but never finishes commissioning.

Likely causes:

• The device dropped out of pairing mode (many close their pairing window quickly).
• A mesh Wi-Fi system is dropping multicast traffic.
• A Matter prerequisite isn't satisfied.

Try:

• Reset the device back into pairing mode and go again.
• Check the mesh Wi-Fi for multicast or IGMP-snooping filters.
• Re-verify every Matter prerequisite.

Reading common OTBR log lines

• ChannelAccessFailure — the radio wanted to transmit but the channel was occupied. The odd one is fine; a flood of them points to interference, so consider channel 25 or 26.
• NoAck — no acknowledgement came back. Expected from battery (sleepy) devices that wake only now and then; from a powered device it may mean it's out of range or has a hardware fault.
• mDNSPlatformSendUDP errors — cosmetic noise on Docker's virtual interfaces; they don't affect the border router.

Related topics

• Matter integration (for device control)
• HomeKit integration (for Apple devices)
• Adding Matter devices
• Adding HomeKit devices over Thread

Further reading

• Enabling Thread on Connect ZBT-1
• Enabling Thread on Connect ZBT-2
• Enabling Thread on Yellow