jeans/home-assistant.io
jeans/home-assistant.io
1
0
Fork 0
mirror of https://github.com/home-assistant/home-assistant.io.git synced 2025-07-27 19:26:50 +00:00
Code Issues Packages Projects Releases Wiki Activity

Merge branch 'current' into zha-introduction

Browse Source
This commit is contained in:
kylehakala 2025-02-25 11:39:58 -06:00 committed by GitHub
commit 3b678da381
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
8 changed files with 281 additions and 92 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
Gemfile
View File

@ -10,7 +10,7 @@ group :development do
gem 'stringex', '2.8.6'
# > 2.1.0 causes slowdowns https://github.com/sass/sassc-ruby/issues/189
gem 'sassc', '2.1.0'
gem 'sass-embedded', '1.85.0'
gem 'sass-embedded', '1.85.1'
gem 'rubocop', '1.72.2'
gem 'ruby-lsp', '0.23.11'
gem 'rackup', '2.2.1'

8
Gemfile.lock
View File

@ -141,9 +141,9 @@ GEM
ruby2_keywords (0.0.5)
safe_yaml (1.0.5)
sass (3.4.25)
sass-embedded (1.85.0-arm64-darwin)
sass-embedded (1.85.1-arm64-darwin)
google-protobuf (~> 4.29)
sass-embedded (1.85.0-x86_64-linux-gnu)
sass-embedded (1.85.1-x86_64-linux-gnu)
google-protobuf (~> 4.29)
sass-globbing (1.1.5)
sass (>= 3.1)
@ -158,7 +158,7 @@ GEM
rack-protection (= 4.1.1)
rack-session (>= 2.0.0, < 3)
tilt (~> 2.0)
sorbet-runtime (0.5.11851)
sorbet-runtime (0.5.11856)
stringex (2.8.6)
terminal-table (3.0.2)
unicode-display_width (>= 1.1.1, < 3)
@ -186,7 +186,7 @@ DEPENDENCIES
rake (= 13.2.1)
rubocop (= 1.72.2)
ruby-lsp (= 0.23.11)
sass-embedded (= 1.85.0)
sass-embedded (= 1.85.1)
sass-globbing (= 1.1.5)
sassc (= 2.1.0)
sinatra (= 4.1.1)

4
source/_integrations/dexcom.markdown
View File

@ -18,7 +18,9 @@ The Dexcom integration allows you to view your CGM data from [Dexcom](https://ww
## Prerequisites
You will need to set up the [Dexcom Share](https://provider.dexcom.com/education-research/cgm-education-use/videos/setting-dexcom-share-and-follow) feature in your Dexcom G6 App to use this integration. Enabling the Dexcom Share service requires setup of at least one follower. The integration will use the Dexcom user's credentials, not the follower's credentials.
You will need to set up the Dexcom Share feature in your Dexcom [G6](https://provider.dexcom.com/education-research/cgm-education-use/videos/setting-dexcom-share-and-follow) or [G7](https://www.dexcom.com/faqs/how-do-i-share-my-dexcom-g7-glucose-data-with-followers) app to use this integration. Enabling the Dexcom Share service requires setup of at least one follower. The integration will use the Dexcom user's credentials, not the follower's credentials.
Your Dexcom account must have an email address—not a phone number—as its primary user ID. If you normally log into your Dexcom account using a phone number, then this integration will not work. It is unfortunately not possible to change from a phone to email user ID after an account is created, so you will need to create a new Dexcom account in this case.
{% include integrations/config_flow.md %}

36
source/_integrations/habitica.markdown
View File

@ -114,8 +114,8 @@ The following Habitica tasks are available as to-do lists in Home Assistant. You
## Calendars
- **To-Do calendar:** Lists the due dates for all active to-do tasks. Each event on this calendar represents a to-do item that has a set due date, making it easy to track upcoming deadlines and plan accordingly.
- **Dailies calendar:** Displays all daily tasks that are scheduled for today and are still active. It also shows all tasks scheduled for future dates, helping you stay organized and track upcoming routines. The calendar sensor will be active if there are unfinished tasks for today and display the next due daily (based on sort order if there are multiple tasks due for that day).
- **To-Do calendar**: Lists the due dates for all active to-do tasks. Each event on this calendar represents a to-do item that has a set due date, making it easy to track upcoming deadlines and plan accordingly.
- **Dailies calendar**: Displays all daily tasks that are scheduled for today and are still active. It also shows all tasks scheduled for future dates, helping you stay organized and track upcoming routines. The calendar sensor will be active if there are unfinished tasks for today and display the next due daily (based on sort order if there are multiple tasks due for that day).
- **To-Do reminders calendar**: Lists events for reminders associated with your to-dos in Habitica, helping you track when notifications for specific to-dos are expected.
- **Dailies reminders calendar**: Shows events for reminders linked to your Habitica dailies, ensuring you know when notifications for your dailies will occur.
@ -134,13 +134,13 @@ If you've unlocked the class system, button controls for casting player and part
- **Ethereal surge**: You sacrifice Mana so the rest of your party, except for other mages, gains MP. (based on: INT)
- **Earthquake**: Your mental power shakes the earth and buffs your party's intelligence. (based on: unbuffed INT)
- **Chilling frost:** With one cast, ice freezes all your streaks so they won't reset to zero tomorrow.
- **Chilling frost**: With one cast, ice freezes all your streaks so they won't reset to zero tomorrow.
### Warrior
- **Defensive stance**: You crouch low and gain a buff to constitution. (based on: unbuffed CON)
- **Valorous presence**: Your boldness buffs your whole party's strength. (based on: unbuffed STR)
- **Intimidating gaze:** Your fierce stare buffs your whole Party's constitution. (based on: unbuffed CON)
- **Intimidating gaze**: Your fierce stare buffs your whole Party's constitution. (based on: unbuffed CON)
### Rogue
@ -172,9 +172,9 @@ Use a skill or spell from your Habitica character on a specific task to affect i
#### Available skills
- **Rogue:** `pickpocket`, `backstab`
- **Warrior:** `smash`
- **Mage:** `fireball`
- **Rogue**: `pickpocket`, `backstab`
- **Warrior**: `smash`
- **Mage**: `fireball`
To use task aliases, make sure **Developer Mode** is enabled under [**Settings -> Site Data**](https://habitica.com/user/settings/siteData). Task aliases can only be edited via the **Habitica** web client.
@ -211,7 +211,9 @@ Terminate your party's ongoing quest. All progress will be lost, and the quest r
| `config_entry` | no | Config entry of the character to abort the quest. |
{% note %}
Actions marked with 🔒 have usage restrictions. See action descriptions for details.
{% endnote %}
### Action `habitica.start_quest` 🔒
@ -264,20 +266,20 @@ Use a transformation item from your Habitica character's inventory on a member o
- **Snowball**: `snowball` (transforms into a snowfriend)
- **Spooky sparkles**: `spooky_sparkles` (transforms into a ghost)
- **Seafoam**: `seafoam` (transforms into a starfish)
- **Shiny seed** `shiny_seed` (transforms into flower)
- **Shiny seed**: `shiny_seed` (transforms into flower)
### Action `habitica.get_tasks`
Fetch tasks from your Habitica account, with optional filters to narrow down the results for more precise task retrieval.
| Data attribute | Optional | Description |
| -------------- | -------- | -------------------------------------------------------------------------------------------------------- |
| config_entry | no | Choose the Habitica character to retrieve tasks from. |
| type | yes | Filter tasks by type. Valid types: "habits", "dailies", "todos", "rewards". |
| priority | yes | Filter tasks by difficulty. Valid values: "trivial", "easy", "medium", "hard". |
| task | yes | Select specific tasks by matching their name (or task ID). |
| tag | yes | Filter tasks that have one or more of the selected tags. |
| keyword | yes | Filter tasks by keyword, searching across titles, notes, and checklists. |
| Data attribute | Optional | Description |
| ---------------- | -------- | -------------------------------------------------------------------------------------------------------- |
| `config_entry` | no | Choose the Habitica character to retrieve tasks from. |
| `type` | yes | Filter tasks by type. Valid types: `habits`, `dailies`, `todos`, `rewards`. |
| `priority` | yes | Filter tasks by difficulty. Valid values: `trivial`, `easy`, `medium`, `hard`. |
| `task` | yes | Select specific tasks by matching their name (or task ID). |
| `tag` | yes | Filter tasks that have one or more of the selected tags. |
| `keyword` | yes | Filter tasks by keyword, searching across titles, notes, and checklists. |
## Automations
@ -419,7 +421,7 @@ Please keep these limits in mind to avoid exceeding Habitica's request allowance
The Habitica integration relies on an active internet connection to communicate with **Habitica**. If you encounter issues, verify that your network connection is stable. Additionally, the Habitica service itself may experience downtime, whether unexpected or due to scheduled maintenance. In these trying times of uncertainty and challenge, when fate tests your resolve, seek guidance from the [Habitica Outage Instructions](https://habitica.fandom.com/wiki/Outage_Instructions) on the community-maintained Habitica wiki — wisdom shared by adventurers who have faced such trials before.
In any case, when reporting an issue, please enable [debug logging](/docs/configuration/troubleshooting/#debug-logs-and-diagnostics), restart the integration, and as soon as the issue reoccurs stop the debug logging again (_download of debug log file will start automatically_). Further _if still possible_, please also download the [diagnostics](/integrations/diagnostics) data. If you have collected the debug log and the diagnostics data, provide them with the issue report.
In any case, when reporting an issue, please enable [debug logging](/docs/configuration/troubleshooting/#debug-logs-and-diagnostics), restart the integration, and as soon as the issue reoccurs stop the debug logging again (*download of debug log file will start automatically*). Further, if still possible, please also download the [diagnostics](/integrations/diagnostics) data. If you have collected the debug log and the diagnostics data, provide them with the issue report.
## Remove integration

80
source/_integrations/home_connect.markdown
View File

@ -31,6 +31,14 @@ ha_integration_type: integration
The Home Connect integration allows users to integrate their home appliances supporting the Home Connect standard for Bosch and Siemens using the [official cloud API](https://developer.home-connect.com).
## Use cases
- Monitor the multiple sensors of the appliance and trigger automations based on these sensors.
- Start programs on your appliances from your dashboard.
- Monitor the program status of the appliances.
- Control the light of your appliances.
- Adjust the appliance settings.
The integration will add one Home Assistant device for each connected home appliance which will have the following entities:
- A power switch
@ -185,3 +193,75 @@ Changes a setting.
| `device_id` | no | Id of a device associated with the home appliance. |
| `key` | no | Key of the setting. |
| `value` | no | Value of the setting. |
## Troubleshooting
### I could not configure the Home Connect integration
#### Symptom: I tried to configure the Home Connect integration, but it failed with the message `Error while obtaining access token.`
##### Description
This problem might occur when the application credentials are not correctly configured.
##### Solution
To solve the above issue, follow these steps:
1. Go to {% my integrations title="**Settings** > **Devices & services**" %}.
2. In the top right corner, select the three dots {% icon "mdi:dots-vertical" %} menu and select **Application credentials**.
![Devices and services overflow menu](/images/integrations/application_credentials/devices-and-services-menu.png)
![Application credential list](/images/integrations/application_credentials/application-credentials.png)
3. Select the three dots {% icon "mdi:dots-vertical" %} menu from the application credentials you created for the Home Connect integration and select **Delete**.
4. Add the Home Connect integration again under {% my integrations title="**Settings** > **Devices & services**" %}
### Unavailable entities for a device
#### Symptom: "The entities related to an appliance were available but no longer are"
After reloading the Home Connect integration, the entities related to an appliance that used to be available are no longer available.
Also, when downloading the diagnostics data from the device entry, the following data is obtained:
```json
{
"data": {
"connected": false,
"status": {},
"programs": null
}
}
```
##### Description
Unavailable entities can have multiple causes:
- The appliance is turned off. When it is turned off, the appliance is disconnected and the API does not retrieve information about the appliance.
- The appliance is experiencing a network issue.
- The Home Connect API is experiencing issues.
##### Solution
To try to solve the above issues, follow these steps:
1. Turn on the appliance and reload the Home Connect integration.
2. If the appliance is turned on and the issue persists, check the network connection of the appliance and perform a soft reset on the appliance.
3. If the issue persists, check the connection of the appliance with the Home Connect API by checking it in the Home Connect app.
1. Open the Home Connect app.
2. Go to the appliance that is experiencing the issue.
3. At the bottom of the screen, open the settings menu.
4. Go to the **Network** section.
5. Verify if the appliance is connected to the cloud:
- If the line between the appliance and the cloud is red and with a red warning icon {% icon "mdi:alert-outline" %}, the appliance is not connected to the Home Connect API.
- If the line between the appliance and the cloud is green, the appliance is connected to the cloud.
4. If everything is correct and the issue persists, contact Home Connect support.
- [Home Connect service and contact](https://www.home-connect.com/us/en/support/contact-and-service)
- [Home Connect developer Help & Support](https://developer.home-connect.com/support)
## Known limitations
- The Home Connect API does not fully match the Home Connect app. Some programs, options, or settings available in the app may not be accessible or usable via the API.
- This integration supports only one integration entry, as the Home Connect API does not allow for the unique identification of an account.

6
source/_integrations/minecraft_server.markdown
View File

@ -77,3 +77,9 @@ For Bedrock Edition servers following sensors are provided additionally:
{% note %}
Player names are only available on Java Edition servers. Depending on the server, the player names list may not be shown completely. Some servers and plugins limit or completely hide this list or even replace the player names with fake ones to show some custom messages there.
{% endnote %}
## Removing the integration
This integration follows standard integration removal. No extra steps are required.
{% include integrations/remove_device_service.md %}

2
source/_integrations/slide_local.markdown
View File

@ -74,7 +74,7 @@ The integration fetches data from the device every 15 seconds.
## Known limitations
The integration only provides connection with Slide devices via the local API. For connecting via the cloud API, please use the [Slide](./slide) integration.
The integration only provides connection with Slide devices via the local API. The cloud API is no longer available.
## Remove integration

235
source/_integrations/zha.markdown
View File

@ -94,13 +94,15 @@ ZHA uses an open-source Python library called [zigpy](https://github.com/zigpy/z
## Compatible hardware
ZHA {% term integration %} uses a hardware independent Zigbee stack implementation with modular design, which means that it can support any one of the many Zigbee coordinator radio modules/adapters available from different manufacturers, as long as that module/adapter is compatible with [zigpy](https://github.com/zigpy/zigpy).
The hardware-independent design of this integration provides support for many Zigbee coordinators available from different manufacturers, as long as the coordinator is compatible with the [zigpy](https://github.com/zigpy/zigpy) library.
Not all functionality may be supported or exposed for every device out-of-the-box. Refer to the documentation on [knowing which devices are supported](#knowing-which-devices-are-supported) for additional information. Some devices using manufacturer-specific extensions to add non-standard functionality may need [device-specific code to fully work with ZHA](#how-to-add-support-for-new-and-unsupported-devices).
### Zigbee 3.0 support
Note! Zigbee 3.0 support or not in zigpy, depends primarily on your Zigbee coordinator hardware and its firmware. Some Zigbee coordinator hardware supports Zigbee 3.0 but might be shipped with an older firmware which does not. In such a case you may want to upgrade the firmware manually yourself.
Some coordinators may not support firmware capable of Zigbee 3.0, but they can still be fully functional and feature-complete for your needs. Support for Zigbee 3.0 depends primarily on your coordinator hardware and firmware.
Some other Zigbee coordinator hardware may not support a firmware that is capable of Zigbee 3.0 at all but can still be fully functional and feature-complete for your needs. This is very common as many, if not most, Zigbee devices do not yet Zigbee 3.0. As a general rule, newer Zigbee coordinator hardware generally supports Zigbee 3.0 firmware and it is up to its manufacturer to make such firmware available for them.
{% note %}
Newer coordinators generally support Zigbee 3.0 firmware, but it is up to the manufacturer to make such firmware available to them. If your coordinator was shipped with an older firmware version, you may want to manually upgrade the firmware.
{% endnote %}
### Recommended Zigbee radio adapters and modules
@ -117,31 +119,62 @@ Some other Zigbee coordinator hardware may not support a firmware that is capabl
### Other supported but not recommended Zigbee radio adapters or modules
- Silicon Labs EmberZNet based radios using legacy hardware using the EZSP protocol (via the [bellows](https://github.com/zigpy/bellows) library for zigpy)
- [Elelabs Zigbee USB Adapter](https://elelabs.com/products/elelabs-usb-adapter.html)/POPP ZB-Stick (Note! Not a must but recommend [upgrade the EmberZNet NCP application firmware](https://github.com/Elelabs/elelabs-zigbee-ezsp-utility))
- [Elelabs Zigbee Raspberry Pi Shield](https://elelabs.com/products/elelabs-zigbee-shield.html) (Note! Not a must but recommend [upgrade the EmberZNet NCP application firmware](https://github.com/Elelabs/elelabs-zigbee-ezsp-utility))
- [ITead Sonoff ZBBridge](https://itead.cc/product/sonoff-zbbridge/) (Note! [WiFi-based bridges are not recommended for ZHA with EZSP radios](https://github.com/home-assistant/home-assistant.io/issues/17170). Also, this first has to be flashed with [Tasmota firmware and Silabs EmberZNet NCP EZSP UART Host firmware to use as Serial-to-IP adapter](https://www.digiblur.com/2020/07/how-to-use-sonoff-zigbee-bridge-with.html))
- [Nortek GoControl QuickStick Combo Model HUSBZB-1 (Z-Wave & Zigbee Ember 3581 USB Adapter)](https://www.nortekcontrol.com/products/2gig/husbzb-1-gocontrol-quickstick-combo/) (Note! Not a must but recommend [upgrade the EmberZNet NCP application firmware](https://github.com/walthowd/husbzb-firmware))
- [Bitron Video/Smabit BV AV2010/10 USB-Stick](https://manuals.smabit.eu/len/av2010_10.html) with Silicon Labs Ember 3587
- Telegesis ETRX357USB/ETRX357USB-LR/ETRX357USB-LRS+8M (Note! These first have to be [flashed with other EmberZNet firmware](https://github.com/walthowd/husbzb-firmware))
- Texas Instruments based radios using legacy hardware (via the [zigpy-znp](https://github.com/zigpy/zigpy-znp) library for zigpy)
- [CC2538 USB stick, module, or dev board hardware flashed with Z-Stack coordinator firmware](https://www.zigbee2mqtt.io/information/supported_adapters) (no longer recommended as only got deprecated old end-of-life firmware)
- [CC2530/CC2531 USB stick, module, or dev board hardware flashed with Z-Stack coordinator firmware](https://www.zigbee2mqtt.io/information/supported_adapters) (no longer recommended as uses deprecated hardware and very old end-of-life firmware, plus will not work properly at all if the whole Zigbee network has more than 15-20 devices)
- dresden elektronik deCONZ based Zigbee radios using legacy hardware (via the [zigpy-deconz](https://github.com/zigpy/zigpy-deconz) library for zigpy)
- [ConBee II (a.k.a. ConBee 2) USB adapter from dresden elektronik](https://phoscon.de/conbee2)
- [RaspBee II (a.k.a. RaspBee 2) Raspberry Pi Shield from dresden elektronik](https://phoscon.de/raspbee2)
- [ConBee USB adapter from dresden elektronik](https://phoscon.de/conbee)
- [RaspBee Raspberry Pi Shield from dresden elektronik](https://phoscon.de/raspbee)
- Digi XBee Zigbee based radios (via the [zigpy-xbee](https://github.com/zigpy/zigpy-xbee) library for zigpy)
- [Digi XBee Series 3 (xbee3-24)](https://www.digi.com/products/embedded-systems/digi-xbee/rf-modules/2-4-ghz-rf-modules/xbee3-zigbee-3) and [Digi XBee Series S2C](https://www.digi.com/products/embedded-systems/digi-xbee/rf-modules/2-4-ghz-rf-modules/xbee-zigbee) modules
- Note! While not a must, [it is recommend to upgrade XBee Series 3 and S2C to newest firmware using XCTU](https://www.digi.com/resources/documentation/Digidocs/90002002/Default.htm#Tasks/t_load_zb_firmware.htm)
- [Digi XBee Series 2 (S2)](https://www.digi.com/support/productdetail?pid=3430) modules (Note! This first have to be [flashed with Zigbee Coordinator API firmware](https://www.digi.com/support/productdetail?pid=3430))
- ZiGate based radios (via the [zigpy-zigate](https://github.com/zigpy/zigpy-zigate) library for zigpy and require firmware 3.1d or later)
- [ZiGate USB](https://zigate.fr/produit/zigate-usb/)
- [ZiGate USB-DIN](https://zigate.fr/produit/zigatev2-usb-din/)
- [PiZiGate (ZiGate Raspberry Pi module)](https://zigate.fr/produit/pizigatev2/)
- [ZiGate-Ethernet (Ethernet gateway board for PiZiGate)](https://zigate.fr/produit/zigate-ethernet/)
- [ZiGate + WiFi Pack](https://zigate.fr/produit/zigatev2-pack-wifi/)
{% details "List of hardware that is not recommended" %}
{% warning %}
The following hardware is supported, but _not recommended_. Specific models and details are noted where available in each section.
{% endwarning %}
**Silicon Labs EmberZNet based radios using legacy hardware using the EZSP protocol (via the [bellows](https://github.com/zigpy/bellows) library for zigpy)**
- [Elelabs Zigbee USB Adapter](https://elelabs.com/products/elelabs-usb-adapter.html)/POPP ZB-Stick
- It is suggested to [upgrade the EmberZNet NCP application firmware](https://github.com/Elelabs/elelabs-zigbee-ezsp-utility)
- [Elelabs Zigbee Raspberry Pi Shield](https://elelabs.com/products/elelabs-zigbee-shield.html)
- It is suggested to [upgrade the EmberZNet NCP application firmware](https://github.com/Elelabs/elelabs-zigbee-ezsp-utility)
- [ITead Sonoff ZBBridge](https://itead.cc/product/sonoff-zbbridge/)
- Note: [WiFi-based bridges are not recommended for ZHA with EZSP radios](https://github.com/home-assistant/home-assistant.io/issues/17170).
- These first need to be flashed with [Tasmota firmware and Silabs EmberZNet NCP EZSP UART Host firmware to use as Serial-to-IP adapter](https://www.digiblur.com/2020/07/how-to-use-sonoff-zigbee-bridge-with.html)
- [Nortek GoControl QuickStick Combo Model HUSBZB-1 (Z-Wave & Zigbee Ember 3581 USB Adapter)](https://www.nortekcontrol.com/products/2gig/husbzb-1-gocontrol-quickstick-combo/)
- It is suggested to [upgrade the EmberZNet NCP application firmware](https://github.com/walthowd/husbzb-firmware)
- [Bitron Video/Smabit BV AV2010/10 USB-Stick](https://manuals.smabit.eu/len/av2010_10.html) with Silicon Labs Ember 3587
- Telegesis ETRX357USB/ETRX357USB-LR/ETRX357USB-LRS+8M
- These first need to be [flashed with other EmberZNet firmware](https://github.com/walthowd/husbzb-firmware)
**Texas Instruments based radios using legacy hardware (via the [zigpy-znp](https://github.com/zigpy/zigpy-znp) library for zigpy)**
- [CC2538 USB stick, module, or dev board hardware flashed with Z-Stack coordinator firmware](https://www.zigbee2mqtt.io/information/supported_adapters)
- This is no longer recommended as it can only run deprecated (old/end-of-life) firmware.
- [CC2530/CC2531 USB stick, module, or dev board hardware flashed with Z-Stack coordinator firmware](https://www.zigbee2mqtt.io/information/supported_adapters)
- This is no longer recommended as it uses deprecated hardware and very old, end-of-life firmware.
- This will not work properly if the Zigbee network has more than 15-20 devices.
**dresden elektronik deCONZ based Zigbee radios using legacy hardware (via the [zigpy-deconz](https://github.com/zigpy/zigpy-deconz) library for zigpy)**
- [ConBee II (a.k.a. ConBee 2) USB adapter from dresden elektronik](https://phoscon.de/conbee2)
- [RaspBee II (a.k.a. RaspBee 2) Raspberry Pi Shield from dresden elektronik](https://phoscon.de/raspbee2)
- [ConBee USB adapter from dresden elektronik](https://phoscon.de/conbee)
- [RaspBee Raspberry Pi Shield from dresden elektronik](https://phoscon.de/raspbee)
**Digi XBee Zigbee based radios (via the [zigpy-xbee](https://github.com/zigpy/zigpy-xbee) library for zigpy)**
- [Digi XBee Series 3 (xbee3-24)](https://www.digi.com/products/embedded-systems/digi-xbee/rf-modules/2-4-ghz-rf-modules/xbee3-zigbee-3) and [Digi XBee Series S2C](https://www.digi.com/products/embedded-systems/digi-xbee/rf-modules/2-4-ghz-rf-modules/xbee-zigbee) modules
- It is suggested to [upgrade XBee Series 3 and S2C to newest firmware using XCTU](https://www.digi.com/resources/documentation/Digidocs/90002002/Default.htm#Tasks/t_load_zb_firmware.htm)
- [Digi XBee Series 2 (S2)](https://www.digi.com/support/productdetail?pid=3430) modules
- These first need to be [flashed with Zigbee Coordinator API firmware](https://www.digi.com/support/productdetail?pid=3430)
**ZiGate based radios (via the [zigpy-zigate](https://github.com/zigpy/zigpy-zigate) library for zigpy and require firmware 3.1d or later)**
- [ZiGate USB](https://zigate.fr/produit/zigate-usb/)
- [ZiGate USB-DIN](https://zigate.fr/produit/zigatev2-usb-din/)
- [PiZiGate (ZiGate Raspberry Pi module)](https://zigate.fr/produit/pizigatev2/)
- [ZiGate-Ethernet (Ethernet gateway board for PiZiGate)](https://zigate.fr/produit/zigate-ethernet/)
- [ZiGate + WiFi Pack](https://zigate.fr/produit/zigatev2-pack-wifi/)
{% enddetails %}
If you find an opportunity to improve this information, refer to the section on how to [add support for new and unsupported devices](#how-to-add-support-for-new-and-unsupported-devices).
{% caution %}
@ -211,29 +244,68 @@ If you are use ZiGate or Sonoff ZBBridge you have to use some special usb_path c
### Discovery via USB or Zeroconf
Some devices can be auto-discovered, which can simplify the ZHA setup process. The following devices have been tested with discovery and offer a quick setup experience:
Some devices can be auto-discovered, which can simplify the ZHA setup process. The following devices have been tested with discovery and offer a quick setup experience.
| Device | Discovery Method | Identifier |
| ------------------------------------------------------------------------------------------------------------------------------------------- | ---------------- | ------------------------------ |
| [ITead SONOFF Zigbee 3.0 USB Dongle Plus V2 Model "ZBDongle-E" (EFR32MG21 variant)](https://itead.cc/product/zigbee-3-0-usb-dongle/) | USB | 1A86:55D4 |
| [ITead SONOFF Zigbee 3.0 USB Dongle Plus Model "ZBDongle-P" (CC2652P variant)](https://itead.cc/product/sonoff-zigbee-3-0-usb-dongle-plus/) | USB | 10C4:EA60 |
| [Bitron Video/SMaBiT BV AV2010/10](https://manuals.smabit.eu/len/av2010_10.html) | USB | 10C4:8B34 |
| [ConBee II](https://phoscon.de/conbee2) | USB | 1CF1:0030 |
| [ConBee III](https://phoscon.de/conbee3) | USB | 0403:6015 |
| [Nortek HUSBZB-1](https://www.nortekcontrol.com/products/2gig/husbzb-1-gocontrol-quickstick-combo/) | USB | 10C4:8A2A |
| [slae.sh CC2652RB development stick](https://slae.sh/projects/cc2652/) | USB | 10C4:EA60 |
| [SMLIGHT SLZB-07](https://smlight.tech/product/slzb-07/) | USB | 10C4:EA60 |
| [ZigStar Stick (CC2652 + CH340B variant)](https://zig-star.com/projects/zigbee-stick-v4/) | USB | 1A86:7523 |
| [Tube’s EFR32 Pro Ethernet/Serial Coordinator](https://www.tubeszb.com/) | USB | 10C4:EA60 |
| [ZigStar Coordinators](https://zig-star.com/) | USB | 1A86:7523 |
| [XZG - Universal Firmware for Zigbee Gateway](https://xzg.xyzroe.cc/) | Zeroconf | xzg.local. |
| [SMLIGHT SLZB-06 POE Zigbee LAN WiFi USB Adapter](https://smlight.tech/product/slzb-06/) | Zeroconf | slzb-06.local. |
| [ZigStar UZG Universal Zigbee Gateway (UZG-01)](https://uzg.zig-star.com) | Zeroconf | uzg-01._tcp.local. |
| [cod.m Zigbee Coordinator](https://docs.codm.de/zigbee/coordinator/) | Zeroconf | czc._tcp.local. |
| [ZigStar LAN/POE Coordinators](https://zig-star.com/projects/zigbee-gw-lan/) | Zeroconf | zigstargw.local. |
| [Tube's CC2652P2 USB-powered Zigbee to Ethernet Serial Coordinator)](https://www.tubeszb.com/) | Zeroconf | tube_zb_gw_cc2652p2.local. |
| [Tube's CC2652P2 PoE-powered Zigbee to Ethernet Serial Coordinator)](https://www.tubeszb.com/) | Zeroconf | tube_zb_gw_cc2652p2_poe.local. |
| [Tube's EFR32 Based Zigbee to Ethernet Serial Coordinator)](https://www.tubeszb.com/) | Zeroconf | tube_zb_gw_efr32.local. |
{% details "USB discovery devices" %}
- **Bitron**
- [Bitron Video/SMaBiT BV AV2010/10](https://manuals.smabit.eu/len/av2010_10.html)
- Identifier: `10C4:8B34`
- **ConBee**
- [ConBee II](https://phoscon.de/conbee2)
- Identifier: `1CF1:0030`
- [ConBee III](https://phoscon.de/conbee3)
- Identifier: `0403:6015`
- **ITead**
- [ITead SONOFF Zigbee 3.0 USB Dongle Plus V2 Model "ZBDongle-E" (EFR32MG21 variant)](https://itead.cc/product/zigbee-3-0-usb-dongle/)
- Identifier: `1A86:55D4`
- [ITead SONOFF Zigbee 3.0 USB Dongle Plus Model "ZBDongle-P" (CC2652P variant)](https://itead.cc/product/sonoff-zigbee-3-0-usb-dongle-plus)
- Identifier: `10C4:EA60`
- **Nortek**
- [Nortek HUSBZB-1](https://www.nortekcontrol.com/products/2gig/husbzb-1-gocontrol-quickstick-combo/)
- Identifier: `10C4:8A2A`
- **slae.sh**
- [slae.sh CC2652RB development stick](https://slae.sh/projects/cc2652/)
- Identifier: `10C4:EA60`
- **SMLIGHT**
- [SMLIGHT SLZB-07](https://smlight.tech/product/slzb-07/)
- Identifier: `10C4:EA60`
- **Tube**
- [Tube’s EFR32 Pro Ethernet/Serial Coordinator](https://www.tubeszb.com/)
- Identifier: `10C4:EA60`
- **ZigStar**
- [ZigStar Stick (CC2652 + CH340B variant)](https://zig-star.com/projects/zigbee-stick-v4/)
- Identifier: `1A86:7523`
- [ZigStar Coordinators](https://zig-star.com/)
- Identifier: `1A86:7523`
{% enddetails %}
{% details "Zeroconf discovery devices" %}
- **cod.m**
- [cod.m Zigbee Coordinator](https://docs.codm.de/zigbee/coordinator/)
- Identifier: `czc._tcp.local.`
- **SMLIGHT**
- [SMLIGHT SLZB-06 POE Zigbee LAN WiFi USB Adapter](https://smlight.tech/product/slzb-06/)
- Identifier: `slzb-06.local.`
- **Tube**
- [Tube's CC2652P2 USB-powered Zigbee to Ethernet Serial Coordinator](https://www.tubeszb.com/)
- Identifier: `tube_zb_gw_cc2652p2.local.`
- [Tube's CC2652P2 PoE-powered Zigbee to Ethernet Serial Coordinator](https://www.tubeszb.com/)
- Identifier: `tube_zb_gw_cc2652p2_poe.local.`
- [Tube's EFR32 Based Zigbee to Ethernet Serial Coordinator](https://www.tubeszb.com/)
- Identifier: `tube_zb_gw_efr32.local.`
- **XZG**
- [XZG - Universal Firmware for Zigbee Gateway](https://xzg.xyzroe.cc/)
- Identifier: `xzg.local.`
- **ZigStar**
- [ZigStar UZG Universal Zigbee Gateway (UZG-01)](https://uzg.zig-star.com)
- Identifier: `uzg-01._tcp.local.`
- [ZigStar LAN/POE Coordinators](https://zig-star.com/projects/zigbee-gw-lan/)
- Identifier: `zigstargw.local.`
{% enddetails %}
Additional devices in the [Compatible hardware](#compatible-hardware) section may be discoverable, however, only devices that have been confirmed discoverable are listed above.
@ -550,7 +622,7 @@ ZHA does not currently support devices that can only use the ZSE ("Zigbee Smart
### Knowing which devices are supported
Home Assistant's ZHA {% term integration %} supports all standard Zigbee device types. It should be compatible with most Zigbee devices as long as they fully conform to the official ZCL (Zigbee Cluster Library) specifications defined by the [CSA (Connectivity Standards Alliance, formerly the Zigbee Alliance)](https://csa-iot.org/all-solutions/zigbee/). There is therefore no official compatibility list of devices that will work out-of-the-box with the ZHA {% term integration %}
Not all hardware manufacturers always fully comply with the standard specifications. Sometimes, they may also implement unique features. For this reason, some Zigbee devices pair/join fine with ZHA but then only show none or only a few entities in the {% term integration %}. Developers can work around most such interoperability issues by adding conversion/translation code in custom device handlers. For more information, refer to the section below on _How to add support for new and unsupported devices_.
Not all hardware manufacturers always fully comply with the standard specifications. Sometimes, they may also implement unique features. For this reason, some Zigbee devices pair/join fine with ZHA but then only show none or only a few entities in the {% term integration %}. Developers can work around most such interoperability issues by adding conversion/translation code in custom device handlers. For more information, refer to the section below on [How to add support for new and unsupported devices](#how-to-add-support-for-new-and-unsupported-devices).
For clarification, normally only devices that do not fully conform to CSA's ZCL specifications that will not present all standard attributes as entities for configuration in the ZHA {% term integration %}. Zigbee devices that only use the standard clusters and attributes that are Zigbee specifications set by the Connectivity Standards Alliance should not need custom device handlers.
@ -718,31 +790,58 @@ logger:
### Add Philips Hue bulbs that have previously been added to another bridge
Philips Hue bulbs/lights that have previously been paired/added to another bridge/gateway will not show up during search in ZHA to pair/add a Zigbee device. That is because you have to first manually restore your bulbs/lights back to their factory default settings first, and just removing them from your old bridge/gateway is not enough to do so. Instead to achieve a proper device factory reset you can use one of these methods below.
Philips Hue bulbs that have previously been paired to another bridge/gateway will not show up during search in ZHA to add a Zigbee device. **Bulbs must be restored back to their factory default settings**.
You can use a Philips Hue Dimmer Switch or Lutron Connected Bulb Remote to factory-reset your bulbs. For this to work, the remote does not have to be paired with your previous bridge. Also, make sure there are no other Hue bulbs nearby that have just been turned on when using this method. Otherwise, you risk resetting them too.
{% important %}
**You must factory-reset the device.**
Newer Philips Hue bulbs you can reset via Bluetooth. The official Android app can connect to one of these bulbs even if it is already paired to a bridge. Then, you can reset the bulb in the app.
- Simply "removing" them from your old bridge/gateway is not sufficient.
- Be sure there are no other Hue bulbs nearby that have just been powered-on when using this method or you will risk resetting them in this process.
#### Philips Hue Dimmer Switch
{% endimportant %}
1. Turn on your Hue bulb/light you want to reset. (It is important that the bulb has just been turned).
2. Hold the Philips Hue Dimmer Switch near your bulb (closer than 10 centimeters / 4 inches).
3. Press and hold the (I)/(ON) and (O)/(OFF) buttons on the Philips Hue Dimmer Switch. The bulb should start blinking in 10-20 seconds. The bulb will blink, then turn off, then turn on. You can now release the dimmer buttons.
4. Your bulb is now factor reset and ready for pairing. A green light on the top left of the dimmer remote indicates that your bulb has been successfully reset to factory default settings.
The following reset methods can be used (depending on the bulb version):
Note: If you are unable to reset the bulb, remove it from the Hue Bridge and retry the procedure.
- **Zigbee remote:**
- Steps are outlined below for either the _Philips Hue Dimmer Switch_ or _Lutron Connected Bulb Remote_.
- The remote does not have to be paired with your previous bridge.
- **Bluetooth via Android app:**
- Newer Philips Hue bulbs can reset via Bluetooth using the official Android app.
- This is an option even if the bulb is already paired to a bridge.
- **Hue Thief command-line tool**:
- Advanced users can use a third-party tool called [Hue Thief](https://github.com/vanviegen/hue-thief/).
- This requires an EZSP-based Zigbee USB stick.
#### Lutron Connected Bulb Remote
#### Factory-reset using a Zigbee remote
1. Turn on your Hue bulb/light you want to reset. (It is important that the bulb has just been turned).
2. Hold the Dimmer Switch near your bulb (closer than 10 centimeters / 4 inches)
3. Press and hold the 2nd (up arrow) and 4th (light off) buttons on the Lutron Connected Bulb Remote simultaneously for about 10 seconds continuously until your bulb starts to blink and the green LED on the remote should also start blink slowly.
4. Continue to hold both buttons on the remote until the green LED on it stops blinking. Your bulb should also have stopped blinking and eventually turn on again indicating that your bulb has been successfully reset to factory default settings.
Icons or button names may vary between generations of remotes. The remote used for resetting does not have to be paired with your previous bridge.
#### hue-thief
{% details "To reset using a remote:" %}
Follow the instructions on [https://github.com/vanviegen/hue-thief/](https://github.com/vanviegen/hue-thief/) (EZSP-based Zigbee USB stick required)
1. Identify which buttons will be used later to perform the reset (based on the brand of remote):
- **Philips Hue Dimmer Switch**:
- Use the **(I)/(ON)** and **(O)/(OFF)** buttons.
- Button labels or icons may vary based on the generation of Hue remote.
- **Lutron Connected Bulb Remote:**
- Use the **2nd (up arrow)** and **4th (light off)** buttons.
2. Turn on the Hue bulb you want to reset.
- **It is important that the bulb has _just_ been powered on.**
3. Hold the remote near your bulb, closer than 10cm (about 4 inches).
4. Press-and-hold both buttons identified in the first step and continue holding them once the bulb begins to blink.
- Expect to hold the buttons for about another 10 seconds while the bulb blinks.
- **Lutron Connected Bulb Remote:** The green LED on the remote should also begin to blink slowly.
5. Release both buttons once the bulb turns off.
- **Lutron Connected Bulb Remote:** You can release the buttons after the green LED stops flashing on the remote.
6. The bulb will turn back on immediately after to indicate the factory-reset is complete.
- The bulb is now ready for pairing to ZHA following normal steps for [adding devices](#adding-devices).
{% tip %}
A green light on the top left of the Philips Hue Dimmer Switch remote indicates that your bulb has been successfully reset to factory default settings.
{% endtip %}
{% enddetails %}
If you are unable to reset the bulb using a method above, remove it from the Hue Bridge (if it was re-discovered by the Hue Bridge) and try the procedure again.
### ZHA Start up issue with Home Assistant or Home Assistant Container