How do I add onvis hs2 to HA without homekit hub

Configuration Matter/Thread
1

I am trying to add a Onvis hs2 set up with my Home Assistant green. Ive seen several other threads on here asking a similar question, but there seems to be some critical assumptions that are being left out of the guidance. I have read the docs many times and have had no luck. I was hoping someone could clarify my issues.

First off, I’ve not done anything with home automation. I got HA green and it was able to find various things easily. The terminology of all this seems to be going over my head so sorry if my questions are muddled.

The precise setup i have:

  • home assistant green + zbt-1 (with thread firmware and openthread border set up as the preferred thread network)
  • pixel 7 with home assistant companion installed (with thread creds synced)
  • onvis “Switch HS2”
  • I have no other apple/google Home automation devices/speakers/whatever.

What I’m confused about:

  • What is this HS2 thing (or what instructions should i be following)? HomeKit device? HomeKit bridge? Thread device? matter device? bluetooth device?

  • The first step seems to be adding thread devices is to first connect with bluetooth. It seems neither the green nor ZBT-1 provide a bluetooth adapter. Am i connecting it to my phone? (tried the normal way and i see the HS2 but it fails to pair as soon as i click it.) If so how?

  • if a bluetooth adaptor is required, why is the ZBT-1 advertised as a thread capable without at least a note in description?

Side questions:

I have added and deleted homekit bridge several times now(still no clue if its needed), and it seems to be duplicating the list of devices it finds every time so something isn’t getting deleted. how do i clear that junk out? I am not afraid of editing files directly.

THanks

2

Welcome to the HA community.

Looking at the manual for HS2, it appears to support control using the HomeKit protocol, using either Bluetooth or a Thread network for underlying wireless transport.

In Home Assistant, this will appear as a “HomeKit Device” where HA (instead of Apple) serves as the HomeKit protocol Hub/Controller. (conversely, “HomeKit Bridge” is for devices already controlled by HA but that you also want to see and control in the Apple Home app).

Thread networking, like WiFI, uses “keys” for security encryption and credentials. All current Thread devices on the market rely on an initial Bluetooth connection to transmit these credentials to the device in order to join the Thread network. Typically with HomeKit- and Matter-over-Thread devices, a mobile device is used because they have local Bluetooth along with cameras to scan the QR code.

Looking at the documentation for adding a HomeKit-over-Thread device to Home Assistant, it appears HA decided to implement a 2-stage process. First stage you have to add the device to either Home Assistant (via Bluetooth), or to Apple Home (via Thread); and the second stage recommissions the device to HA HomeKit-over-Thread.

Unless you have another Apple Home controller (HomePod or Apple TV), you are stuck with the Bluetooth option, which means you need to add Bluetooth capability to your HA Green. You cannot use your phone for this step. The docs suggest a “bluetooth proxy” option instead of a bluetooth dongle, which might solve range/coverage issues but requires you to compile and flash your own firmware to a small device. Both will work, the decision is up to you. After the recommissioning step, you no longer need any Bluetooth for operations, so I completely understand how this could be frustrating.

I’m not aware of any technical reason mandating this 2-stage approach — there is a HA companion app for both iOS and Android that could be programmed to commission a Thread-over-HomeKit devices directly to HA using the mobile bluetooth and camera — this is the approach for Matter-over-Thread, which does not require a bluetooth dongle. However HomeKit being an Apple-proprietary protocol (unlike Matter) and Thread being relatively new, I suppose other features are taking priority right now, so these workarounds remain the only options.

3

Thanks for the clear description, the weird difference between matter and homekit thread provisioning was the missing piece. bluetooth must be on the HA device. No cellphone/app is needed. I went with the ESP Bluetooth proxy route as it seemed to be the cheapest and easiest method.

I will try to write out what i did exactly for anyone else that drops by. This was performed 9/11/2024. A lot of little things have become easier/more automatic since the original documents were written and i expect things to continue to evolve. Below reflects my experience at this time.

(I had to disable some of the links due to the 2-link max for new users.)

Here are all the devices you need:

  • home assist green with zbt-1
  • an ESP32dev device. I used an AITRIP ESP-WROOM-32 (-https-://www.amazon.com/dp/B0CR5Y2JVD)
  • onvis “Switch HS2” ( -https-://www.amazon.com/dp/B0C7BLSMMW)
  • a computer with a web browser and usb port. I used windows 11.

NO android/ios device will be used…

The full title of the esp32 board in case the amazon link goes stale:
AITRIP 3PCS Type c 30pins CP2102 ESP-WROOM-32 ESP32 ESP-32S Development Board 2.4GHz Dual-Mode WiFi + Bluetooth Dual Cores Microcontroller Processor Integrated with Antenna RF AMP Filter AP STA

Step 1: configuring ZBT-1 for thread.

  1. Plug in ZBT-1 device
  2. Home Assist will detect the device.
  3. Click the notification and click configure.
  4. Choose thread firmware
  5. Wait… HA will automatically install the Open Thread Border Proxy and the Thread device.
  6. Under the Thread device (not to be confused with the Open Thread Border Proxy Device) click configure.
  7. You should see the local openthread border router in list. Click it and it will be set to the preferred network. if you don’t see it wait a bit (maybe refresh page). The router seems to take longer to get booted than the thread install UI would indicate.

Original instructions: Home Assistant Connect ZBT-1

Step 2: Create/Configure ESP32 Bluetooth proxy

  1. Go here in chrome or edge browser: -https-://esphome.io/projects/
  2. Select Bluetooth Proxy
  3. Select Generic ESP32
  4. Click connect. If you do not see Connect there should be a message approximately where the button should be explaining why (ex: not using chrome or edge).
  5. Click Install Bluetooth Proxy. Wait for it to finish.
  6. Click Set up WiFi. Configure it with a 2.4gz network credentials.

At this point, the ESP32 should be ready to go. You may disconnect from computer and power some other way if desired.

  1. Install ESPHome Add-on. Select Watchdog and Show in Sidebar. Note: it takes a bit to startup so the UI might not work for a minute or so.

  2. Once everything is Running (ESP32 device and the addon) you should see the device on the main ESPHome UI. Click Adopt, Give it a new name (if desired), Select update over wifi, and wait… it will do a full compile of the ESP firmware. The HA green cpu isn’t that beefy so it will take 10-15 min.

  3. Once updated and device restarts you will see a notification to add the proxy device. Do so…

Step 3: Add HS2 via Bluetooth.
This one is easy. Put the battery in and you should immediately see a notification in HA to add it. Do so and wait (took longer than normal for me). It will add the proper Homekit device, etc.

Step 3b (optional) test device in bluetooth mode.

  1. Open device page via the HomeKit Device Integration or master device list.
  2. Note the button status and log. Note how incredibly slow and flaky it is to update the button status as you push things.

Step 4: Transition device to thread
This was also easy. Click configure thread on device and your done.

Note how quickly it now responds to input.

Once transferred, bluetooth is no longer needed and you can unplug the proxy and stick it in a drawer until the next time, loan it to friends, etc.

Original instructions: HomeKit Device - Home Assistant

Step 5: INTEGRATE!
Now you have the button in HA, you have to figure out what use it for. Click “add integration” on the button device and set up as you desire. My plans involve controlling lights and creating a one-click-clean for my shark vac if the integration can be fixed (Shark recently killed the API it was using :frowning: ).

TL;DR: You need bluetooth on the HA green device one way or the other. ESP32 bluetooth proxy was the cheapest and easiest option for me. After that the rest falls into place.

2 Likes