Make Apple Thread Network Preferred Thread Network - Full Process

Community Guides
1

Alright, so after many hours finding different tidbits of how to do this in different threads (none of which fully explained what to do) I figured it would be nice if there was a full process on how to give us the option of making the Apple Thread Network our preferred thread network. So without further ado, below are full requirements/steps to make the Apple Thread network your preferred network in Home Assistant. I’m reading the new release of the HA Companion App will allow us to combine the HA Thread with Apple Thread but I can’t confirm that as I’m not part of beta testing.

Pre-requisites

Steps to Integrate

  • Take a backup of your Home Assistant instance so that if anything goes wrong you can easily revert to the backup as we will be making a lot of configuration changes as part of this setup. Backup can be created from “Settings”, “System”, “Backups”, “Create Backup” inside Home Assistant.
  • Configure your Home Assistant Thread capable device and Apple Thread Border Router per documentation.
  • Add your Nanoleaf thread device via the Apple Home App (do NOT use the Nanoleaf App to deploy).
    • This will add the device to your Apple Thread Network.
  • Perform all the steps below in the Nanoleaf app.
    • Open the Nanoleaf app and it should automatically see the device you added in Apple Home.
    • Click the 3 dots on the bottom right and select “Thread Network”.
    • You’ll see the device you added in an “Unknown Network” stating “Complete Setup” under it. Click the device and continue to complete setup (you’ll need to scan the QR code again). This fully integrates the device into the Nanoleaf app.
    • Update firmware of device if prompted. This isn’t required but I would always recommend doing this for any new device.
    • Go back into the Thread Network menu and you’ll now see the device you added and the Apple Border Router in a Thread Network named something like “MyHome……”. Click the name of the network and copy all of the following details. I emailed them to myself from my phone so I could copy/paste from my PC where I was setting everything up. It may not be obvious, but you CAN copy directly from this screen - long press the item you want to copy, and the copy option will pop up.
      • Name
      • Channel
      • PAN ID
      • Extended PAN ID
      • Network Key
      • PSKc
  • Configure your Home Assistant Thread network to use the same Channel as the Apple Thread Network. I use Home Assistant Yellow so these steps will outline that. I do not know if the steps are the same for other devices, but you should be able to google how to verify/change the channel the thread network uses for other devices.
    • Click “Settings”, “System”, “Hardware”, “Configure”, “Configure IEEE 802.15.4 radio multiprotocol support”, “Reconfigure IEEE 802.15.4 radio multiprotocol support”. If the Channel doesn’t match what your Apple Thread network is using, then update the Channel to match that. If it already does (Channel 25 is common default for thread) you don’t need to make a change and can cancel out.
    • As Home Assistant Yellow allows you to have your Zigbee network share the same channel as thread be sure to update the Zigbee channel if needed. Go to “Settings”, “Devices & Services”, “Zigbee Home Automation”, “Configure”, and click the edit icon (pencil) next to the channel and update it to mirror the channel used above.
    • If you had to change the channel restart your Home Assistant device by clicking “Developer Tools”, “Restart”.
    • After restarting you may get 2 errors stating Zigbee is no longer using the correct channel, click on the first one and say to accept the new configuration. Wait 5-10 minutes before proceeding to be sure the channel changes are fully complete. Verify they are complete by going into Zigbee and confirming it shows the correct channel. You may need to restart one more time to get rid of the other error so do that now, confirm no errors after restart, and proceed.
  • Configure the script needed to get the TLV you need for Home Assistant to allow you to make the Apple Thread Network your primary. Huge thanks to Veldkornet in the Home Assistant community for creating and providing this script in various threads. I had nothing to do with the creation of this script.
    • Copy the script below into a notepad file and replace the Channel, PAN ID, Extended PAN ID, Network Key, Network Name, and PSKc with information you copied out of the Nanoleaf app. Do not remove the quotations around the data you’re copying into the script or it will fail to run.
import python_otbr_api
from python_otbr_api import PENDING_DATASET_DELAY_TIMER, tlv_parser
from python_otbr_api.pskc import compute_pskc
from python_otbr_api.tlv_parser import MeshcopTLVType, MeshcopTLVItem

# Apple Thread Network Info
CHANNEL = <Channel>
PANID = “<PAN ID>“
EXTPANID = “<Extended PAN ID>“
NETWORK_KEY = “<Network Key>“
NETWORK_NAME = “<Network Name>“
PSKC = “<PSKc>“
TIMESTAMP = b'\x00\x00\x00\x00\x00\x03\x00\x00'

channel = MeshcopTLVItem(tag=0, data=CHANNEL.to_bytes(length=3, byteorder='big'))
pan_id= MeshcopTLVItem(tag=1, data=bytes.fromhex(PANID))
ext_pan_id = MeshcopTLVItem(tag=2, data=bytes.fromhex(EXTPANID))
network_name = MeshcopTLVItem(tag=3, data=str.encode(NETWORK_NAME))
pre_shared_key = MeshcopTLVItem(tag=4, data=bytes.fromhex(PSKC))
network_key = MeshcopTLVItem(tag=5, data=bytes.fromhex(NETWORK_KEY))
timestamp = MeshcopTLVItem(tag=14, data=TIMESTAMP)
tlv_new = {0: channel, 1: pan_id, 2: ext_pan_id, 3: network_name, 4: pre_shared_key, 5: network_key, 14: timestamp}
tlv = tlv_parser.encode_tlv(tlv_new)
print(tlv)
  • Save the script and rename it to change the extension from .txt to .py. If you can’t see the extension to change it just google how to show file extensions for whatever OS you’re using and then rename it.
    • I named it “apple-ha-thread.py” so will refer to it this way going forward.
  • Copy the apple-ha-thread.py script to your Home Assistant instance. I put it in config/custom_components location.
    • This can be done using the Samba share add-on listed as a pre-requisite so if you’re unsure how to do this please complete the setup of that add-on and read the documentation.
  • Configure Advanced SSH & Web Terminal.
    • On the “Info” tab of the add-on enable “Show in sidebar” and disable Protection Mode.

Important: This allows you to run commands in a virtualbox when using the add-on to connect to the cli which is required to install the requirements for running the script in the next step. If you skip this step the commands won’t work.

  • Run the script.
    • Within Home Assistant click the “Terminal” link on the sidebar.
    • Run the command “pip install python-otbr-api”.
      • This will fail if you did not disable Protection Mode in the previous step.
    • Change directory into the location you saved the script. For me I run the command “cd config/custom_components”.
    • Type “ls” (lowercase L) to verify the script is in this location.
    • Run “python apple-ha-thread.py”.
    • Copy the result which is the TLV of the Thread Network.
    • To copy hold SHIFT, highlight what you need to copy, right click and click copy (holding shift the whole time). Note: I had issues getting copy to work in Edge but was able to with Firefox.
  • Go to the Thread integration, click Configure, in the top right click the 3 dots, and select “Add dataset from TLV”. Paste the TLV obtained in the previous step here and click “Add Dataset”.
  • You will now have the option to make the Apple Thread network your preferred Thread network by clicking “MAKE PREFERRED NETWORK”.
4 Likes
2

This needs to be added to the Home Assistant documentation. Worked flawlessly using a Nanoleaf Secret Lab MAGRGB light strip as the Thread-enabled device.

1 Like
3

UGH!!! I messed this up some how and now I’m stuck with Apple thread network showing the wrong channel in HA. It says channel 15 in HA but shows as 25 in Nanoleaf app. I have completely removed all of the add-ons and integrations related to thread and zigbee and tried to start over but it still has the apple network listed with the wrong channel. I even reset the skyconnect back to original firmware and retried but it’s still showing the wrong channel.

image
image687×761 50.6 KB

image
image599×1286 51.7 KB

4

You should be able to run the python script again, this time with the data you show at the end in the NanoLeaf App (Name MyHome 1956380123, channel 25, PANID 77cf, etc).
(Note: I’m only following this thread, I don’t have an Apple Network, so haven’t tried this myself)

1 Like
5

This is now an easy process that can be completed using the iOS app - see here: Thread - Home Assistant

1 Like
6

It doesn’t appear to be possible. I still get a “No preferred network” error.

7

@exorr thank you for the above, i am relatively new to thread and hompods. i am struggling to understand how HA and Homepods work togeather. i was wondering if you can clarify a few things.

can you run multiple thread networks at the same time, ie can lights be on multiple networks
if ha is using homepods network as the preferred network, does that mean HA sends a data signal to the homepods and the homepods then send out the thread signal or is ha using the skyconnect dongle to talk directly to the lights.
what have you found works best when changing light settings?

thanks in advance

ryan

8

Hi Ryan, what this process allowed us to do was to consolidate our HA Thread Network with the Apple Thread Network to make a single Thread Network. This can now be done without going through all this craziness though as it’s been added to the HA iOS Companion app.

You can run multiple thread networks, but I would recommend having all your devices in a single Thread Network. Having them in multiple adds unnecessary complexity and also limits the overall coverage of your thread network in your home (as every device in the network also acts as an extender for the thread network).

To be clear; HA is not “using your Homepods thread network”, it is an extension of your HomePods thread network. When you merge the 2 networks together, you’re really just allowing HA to be a second Border Router for your existing Apple Thread network, thus allowing you to add devices from the HA Companion App into your existing Apple Thread network.

Try and think of a thread network as similar to your WiFi network. Your Apple Homepod and HA Yellow are core routers in the network and when a device connects to the network, they can connect to either of these devices to communicate in the network. Each individual thread device you add to this network also acts as a repeater for you thread network, thus extending the range (similar to if you have WiFi extenders throughout your home to remove dead spots). If you install a Thread device 500 feet away from your thread border router it won’t be able to connect to the thread network, but if you have devices every 10 feet from your border router to the thread device 500 feet it will be able to connect as the 49 devices between the border router and new device act as extenders.

I hope this helps. If you have other questions don’t hesitate to ask. I’m by no means an expert :slight_smile:

1 Like
9

great thank you much appreciated, i just now need to work out how to get both systems to go on the same channel, i cant seam to get my skyconnect to change or find out a way to get the home pods to change

10

You shouldn’t need to do that manually anymore. Follow the “ TO CREATE A HA BORDER ROUTER WHEN THERE IS AN EXISTING NETWORK” section at the URL below.

11

And again, like I said before… “No preferred network” when hitting “Send credentials to Home Assistant”.

12

Hi! Try to follow these steps: Thread - Home Assistant
Full process requires a couple of additional steps after sending credentials.
And it seems like you should select specific thread border router in case you have more than one in the network.

image
image875×449 25.5 KB