mirror of
https://github.com/home-assistant/home-assistant.io.git
synced 2025-07-26 10:46:51 +00:00
Merge branch 'current' into zha-introduction
This commit is contained in:
kylehakala
GitHub
commit
4fd1386eb5
@ -53,6 +53,9 @@ The following entities can be grouped:
|
||||
- [event (events)](/integrations/event/)
|
||||
- [media player (media players)](/integrations/media_player/)
|
||||
- [notify (notifications)](/integrations/notify/)
|
||||
- [sensor (sensors)](/integrations/sensor/)
|
||||
- [number (numbers)](/integrations/number/)
|
||||
- [input_number (input_numbers)](/integrations/input_number/)
|
||||
|
||||
{% include integrations/config_flow.md %}
|
||||
|
||||
@ -136,7 +139,7 @@ In short, when any group member entity is `unlocked`, the group will also be `un
|
||||
- Otherwise, the group state is `on` if at least one group member is not `off`, `unavailable` or `unknown`.
|
||||
- Otherwise, the group state is `off`.
|
||||
|
||||
### Sensor groups
|
||||
### Sensor, number, and input_number groups
|
||||
|
||||
- The group state is combined / calculated based on `type` selected to determine the minimum, maximum, latest (last), mean, median, range, product, standard deviation, or sum of the collected states.
|
||||
- Members can be any `sensor`, `number` or `input_number` holding numeric states.
|
||||
|
||||
@ -22,7 +22,7 @@ ha_integration_type: integration
|
||||
## Prerequisites
|
||||
|
||||
- Minecraft Java Edition servers must be version 1.7 or newer, since older versions don't expose any information.
|
||||
- The `enable-status` and `enable-query` must be set to `true` in the Minecraft `server.properties`.
|
||||
- The configuration parameter `enable-status` must be set to `true` in the server configuration file (`server.properties`).
|
||||
|
||||
{% include integrations/config_flow.md %}
|
||||
|
||||
|
||||
@ -1,6 +1,6 @@
|
||||
---
|
||||
title: pyLoad
|
||||
description: Instructions on how to integrate pyLoad download sensor within Home Assistant.
|
||||
description: Instructions on how to integrate pyLoad download manager with Home Assistant.
|
||||
ha_category:
|
||||
- Downloading
|
||||
ha_release: 0.58
|
||||
@ -19,8 +19,54 @@ ha_config_flow: true
|
||||
|
||||
The [**pyLoad**](https://pyload.net/) {% term integration %} enables monitoring your downloads directly in Home Assistant. This integration provides various sensors to keep track of your download activities and allows creating automations based on the sensor information, alongside button and switch controls for performing specific tasks such as aborting downloads and managing file restarts.
|
||||
|
||||
## About pyLoad
|
||||
|
||||
**pyLoad** is an open-source download manager designed for always-on devices like home servers, NAS systems, and routers. It supports various file hosts, container formats, and web standards, enabling fully automated, unattended downloads. With its web interface, pyLoad allows for easy remote management from any device.
|
||||
|
||||
## How you can use this integration
|
||||
|
||||
The **pyLoad** integration allows you to monitor and control your downloads directly from Home Assistant. Here are some ways you can use it:
|
||||
|
||||
- **Track active downloads** – Send a notification when all downloads are complete or if the queue is empty.
|
||||
- **Free space alerts** – Set up an automation to alert you when disk space is low, ensuring downloads don’t fail due to storage issues.
|
||||
- **Pause downloads** – Automatically pause downloads when streaming or gaming to avoid bandwidth congestion, then resume them later.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
To set up the pyLoad integration, you must have a running pyLoad instance on your home server, NAS, or any other device. An always-on device is recommended. Ensure that pyLoad's web interface is accessible for Home Assistant.
|
||||
|
||||
If you haven't set up pyLoad yet, an easy way to get it up and running is by installing the [pyLoad-ng add-on for Home Assistant](https://github.com/tr4nt0r/pyload-ng).
|
||||
|
||||
- During the setup process in Home Assistant, you will need:
|
||||
- pyLoad account credentials – A valid *username* and *password* to authenticate with pyLoad.
|
||||
- The {% term host %} of the device running pyLoad.
|
||||
- The port number that pyLoad is listening on (default is usually `8000`).
|
||||
|
||||
{% note %}
|
||||
|
||||
The account used for integration must either be an admin account or one with at least the following permissions: `DELETE`, `STATUS`, `LIST`, and `MODIFY`. You can set up and manage users and permissions under **Settings -> Users** in the pyLoad web interface.
|
||||
|
||||
{% endnote %}
|
||||
|
||||
{% include integrations/config_flow.md %}
|
||||
|
||||
### Configuration parameters
|
||||
|
||||
{% configuration_basic %}
|
||||
Host:
|
||||
description: "The hostname or IP address of the device running your pyLoad instance."
|
||||
Port:
|
||||
description: "The port of the pyLoad instance. pyLoad uses port 8000 by default."
|
||||
Uses an SSL Certificate:
|
||||
description: "If enabled, the connection to the pyLoad instance will use HTTPS."
|
||||
Verify SSL certificate:
|
||||
description: "If checked, the SSL certificate will be validated to ensure a secure connection."
|
||||
Username:
|
||||
description: "The username used to access the pyLoad instance."
|
||||
Password:
|
||||
description: "The password associated with the pyLoad account."
|
||||
{% endconfiguration_basic %}
|
||||
|
||||
## Sensors
|
||||
|
||||
- **Speed:** Monitors the current download speed.
|
||||
@ -40,3 +86,89 @@ The [**pyLoad**](https://pyload.net/) {% term integration %} enables monitoring
|
||||
|
||||
- **Pause/Resume Queue:** Pauses or resumes the download queue. When paused, active downloads will continue, but new downloads in the queue will not start.
|
||||
- **Auto-reconnect:** If configured, enables pyLoad to automatically reconnect the internet connection.
|
||||
|
||||
## Automations
|
||||
|
||||
Get started with these example {% term automations %}.
|
||||
|
||||
### Pause downloads when disk space is low
|
||||
|
||||
This automation will pause new downloads when your available disk space falls below 5 GB.
|
||||
|
||||
{% details "Example YAML configuration" %}
|
||||
|
||||
{% raw %}
|
||||
|
||||
```yaml
|
||||
alias: "Monitor pyLoad download queue"
|
||||
description: "Pause new downloads when the disk space is low."
|
||||
triggers:
|
||||
- trigger: numeric_state
|
||||
entity_id: sensor.pyload_free_space
|
||||
below: 5000000000 # Trigger when free space drops below 5 GB (in bytes)
|
||||
actions:
|
||||
- action: switch.turn_off
|
||||
target:
|
||||
entity_id: switch.pyload_pause_resume_queue
|
||||
- service: notify.persistent_notification
|
||||
data:
|
||||
message: "Free space is low, pausing pyLoad queue."
|
||||
mode: single
|
||||
```
|
||||
|
||||
{% endraw %}
|
||||
|
||||
{% enddetails %}
|
||||
|
||||
### Halt pyLoad downloads when watching Netflix
|
||||
|
||||
This automation halts all active pyLoad downloads when watching Netflix on your media player.
|
||||
|
||||
{% details "Example YAML configuration" %}
|
||||
|
||||
{% raw %}
|
||||
|
||||
```yaml
|
||||
alias: "Halt pyLoad downloads when watching Netflix"
|
||||
description: "Halt all pyLoad downloads when Netflix streaming starts on the media player."
|
||||
triggers:
|
||||
- trigger: state
|
||||
entity_id: media_player.android_tv
|
||||
to: playing
|
||||
conditions:
|
||||
- condition: state
|
||||
entity_id: media_player.android_tv
|
||||
attribute: app_id
|
||||
state: com.netflix.ninja
|
||||
actions:
|
||||
- action: button.press
|
||||
target:
|
||||
entity_id: button.pyload_abort_all_running_downloads
|
||||
- action: notify.persistent_notification
|
||||
data:
|
||||
message: "pyLoad downloads have been halted because Netflix streaming started."
|
||||
mode: single
|
||||
```
|
||||
|
||||
{% endraw %}
|
||||
|
||||
{% enddetails %}
|
||||
|
||||
## Data updates
|
||||
|
||||
This integration {% term polling polls %} your **pyLoad** instance every 20 seconds. If you prefer a different update frequency, you can define a **custom polling interval** — see [Defining a custom polling interval](/common-tasks/general/#defining-a-custom-polling-interval) for details.
|
||||
|
||||
## Known limitations
|
||||
|
||||
- **Paused downloads**: When the download queue is paused, active downloads will continue, but new downloads in the queue will not start until the queue is resumed.
|
||||
- **Halt all downloads**: To completely halt downloading, use the `Abort all running downloads` action. The `Restart failed files/packages` action will also resume any aborted downloads.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
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
|
||||
|
||||
This integration can be removed by following these steps:
|
||||
|
||||
{% include integrations/remove_device_service.md %}
|
||||
|
||||
@ -79,6 +79,7 @@ This {% term integration %} supports devices controllable by the VeSync App. Th
|
||||
|
||||
- Classic200S: Classic 200S Smart Ultrasonic Cool Mist Humidifier
|
||||
- Classic300S: Classic 300S Ultrasonic Smart Humidifier
|
||||
- Superior6000S: Superior 6000S Smart Evaporative Humidifier
|
||||
|
||||
## Prerequisite
|
||||
|
||||
|
||||
@ -102,8 +102,6 @@ Note! Zigbee 3.0 support or not in zigpy, depends primarily on your Zigbee coord
|
||||
|
||||
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.
|
||||
|
||||
### Known working Zigbee radio modules
|
||||
|
||||
### Recommended Zigbee radio adapters and modules
|
||||
|
||||
- Silicon Labs EmberZNet based radios using the EZSP protocol (via the [bellows](https://github.com/zigpy/bellows) library for zigpy)
|
||||
@ -235,7 +233,7 @@ Some devices can be auto-discovered, which can simplify the ZHA setup process. T
|
||||
| [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. |
|
||||
|
||||
Additional devices in the [Known working Zigbee radio modules](#known-working-zigbee-radio-modules) list may be discoverable, however, only devices that have been confirmed discoverable are listed above.
|
||||
Additional devices in the [Compatible hardware](#compatible-hardware) section may be discoverable, however, only devices that have been confirmed discoverable are listed above.
|
||||
|
||||
### OTA updates of Zigbee device firmware
|
||||
|
||||
@ -244,6 +242,7 @@ The ZHA integration has the ability to perform OTA (over-the-air) firmware updat
|
||||
To see OTA updates for a device, it must support OTA updates and firmware images for the device must be publicly provided by the manufacturer. ZHA currently only includes OTA providers for a few manufacturers that provide these updates publicly.
|
||||
|
||||
**Included manufacturers:**
|
||||
|
||||
- IKEA
|
||||
- Inovelli
|
||||
- Ledvacnce/OSRAM
|
||||
@ -298,7 +297,7 @@ Refer to the [zigpy documentation for OTA configuration](https://github.com/zigp
|
||||
|
||||
#### Defining Zigbee channel to use
|
||||
|
||||
Tip! Before considering to change to an other Zigbee channel on an existing Zigbee network, it is highly recommended that you read through the two segments under the [troubleshooting](#troubleshooting) section below about "*Best practices to avoid pairing/connection difficulties*" and "*Zigbee interference avoidance and network range/coverage optimization*". These sections provide prerequisite information and advice on how to achieve the best possible Zigbee network in your environment.
|
||||
Tip! Before considering to change to an other Zigbee channel on an existing Zigbee network, it is highly recommended that you read through the two segments under the [troubleshooting](#troubleshooting) section below about _Best practices to avoid pairing/connection difficulties_ and _Zigbee interference avoidance and network range/coverage optimization_. These sections provide prerequisite information and advice on how to achieve the best possible Zigbee network in your environment.
|
||||
|
||||
ZHA prefers to use Zigbee channel 15 by default. You can change this using YAML configuration, but this only works
|
||||
if there's no existing network. To change the channel for an existing network, radio has to be factory reset and a new network to be formed. This requires re-pairing of all the devices.
|
||||
@ -311,9 +310,13 @@ zha:
|
||||
channels: [15, 20, 25] # Channel mask
|
||||
```
|
||||
|
||||
Note! The best practice is to not change the Zigbee channel from the ZHA default. Also, the related troubleshooting segments mentioned in the tip above will, among other things, inform that if you have issues with overlapping frequencies between Wi-Fi and Zigbee, then it is usually better to first only try changing and setting a static Wi-Fi channel on your Wi-Fi router or all your Wi-Fi access points (instead of just changing to another Zigbee channel).
|
||||
{% note %}
|
||||
The best practice is to not change the Zigbee channel from the ZHA default.
|
||||
{% endnote %}
|
||||
|
||||
MetaGeek Support has a good reference article about channel selection for [Zigbee and WiFi coexistance](https://support.metageek.com/hc/en-us/articles/203845040-ZigBee-and-WiFi-Coexistence).
|
||||
The related troubleshooting segments mentioned above will, among other things, inform that if you have issues with overlapping frequencies between Wi-Fi and Zigbee, then it is usually better to first only try changing and setting a static Wi-Fi channel on your Wi-Fi router or all your Wi-Fi access points (instead of just changing to another Zigbee channel).
|
||||
|
||||
MetaGeek Support has a good reference article about channel selection for [Zigbee and WiFi coexistence](https://support.metageek.com/hc/en-us/articles/203845040-ZigBee-and-WiFi-Coexistence).
|
||||
|
||||
The Zigbee specification standards divide the 2.4 GHz ISM radio band into 16 Zigbee channels (i.e. distinct radio frequencies for Zigbee). For all Zigbee devices to be able to communicate, they must support the same Zigbee channel (i.e. Zigbee radio frequency) that is set on the Zigbee Coordinator as the channel to use for its Zigbee network. Not all Zigbee devices support all Zigbee channels. Channel support usually depends on the age of the hardware and firmware, as well as on the device's power ratings.
|
||||
|
||||
@ -358,11 +361,10 @@ from the same group:
|
||||
|
||||
{% note %}
|
||||
Currently `qr_code` supports QR Install Codes from:
|
||||
|
||||
- Aqara
|
||||
- Bosch
|
||||
- Consciot
|
||||
- Embrighten
|
||||
- Aqara
|
||||
- Bosch
|
||||
- Consciot
|
||||
- Embrighten
|
||||
{% endnote %}
|
||||
|
||||
### Action `zha.remove`
|
||||
@ -408,7 +410,7 @@ This action disables a lock code on a Zigbee lock.
|
||||
|
||||
## Adding devices
|
||||
|
||||
Tip! It is highly recommended that you read through the two segments under the troubleshooting section below about "*Best practices to avoid pairing/connection difficulties*" and "*Zigbee interference avoidance and network range/coverage optimization*" for general prerequisite knowledge and advice on how to achieve the best possible Zigbee network in your environment.
|
||||
Tip! It is highly recommended that you read through the two segments under the troubleshooting section below about _Best practices to avoid pairing/connection difficulties_ and _Zigbee interference avoidance and network range/coverage optimization_ for general prerequisite knowledge and advice on how to achieve the best possible Zigbee network in your environment.
|
||||
|
||||
**To add a new Zigbee device:**
|
||||
|
||||
@ -555,8 +557,8 @@ If you do not want to develop such a "quirk" Python script yourself, you can sub
|
||||
|
||||
1. Sign in to GitHub.
|
||||
2. Select **New issue** and follow the instructions.
|
||||
- New device support requests require the device signature + diagnostic information.
|
||||
- You may also need to actively help in further testing or provide additional information to the volunteering developers.
|
||||
- New device support requests require the device signature + diagnostic information.
|
||||
- You may also need to actively help in further testing or provide additional information to the volunteering developers.
|
||||
|
||||
Note that submitting a new "device support request" does not guarantee that someone else will develop a custom "quirk" for ZHA. The project relies on volunteering developers. However, without "device support requests", the developers may not be aware that your specific Zigbee device is not working correctly in ZHA.
|
||||
|
||||
@ -567,15 +569,15 @@ If you experience problems pairing a device, verify that you follow best practic
|
||||
- Check that your setup and environment are optimized to avoid interference.
|
||||
- As interference avoidance is an extremely important topic on its own, please read and follow the tips in the separate section below about Zigbee interference avoidance and network range/coverage optimization.
|
||||
- Check that you have enough Zigbee router devices (also known as Zigbee signal repeaters or range extenders) and if you do not have any, invest and add some mains-powered devices that will work as Zigbee routers.
|
||||
- Aim to start out with mains-powered devices before adding battery-operated devices as a "weak" Zigbee network mesh (e.g., the device is too far from the Zigbee coordinator or a Zigbee router) may prevent some devices from being paired. Zigbee router devices are also needed to increase the maximum of devices that can be connected to your Zigbee mesh network.
|
||||
- Note that some Zigbee devices are not fully compatible with all brands of Zigbee router devices. Xiaomi/Aqara devices are for example known not to work with Zigbee router devices from Centralite, General Electrics, Iris, Ledvance/OSRAM, LIGHTIFY/Sylvania, Orvibo, PEQ, Securifi, and SmartThings/Samsung. Better results can usually be achieved by using mains-powered devices IKEA and Nue/3A Home or dedicated DIY routing devices based on Texas Instruments CC253x/CC26x2 and XBee Series 2/3 Zigbee radios.
|
||||
- Aim to start out with mains-powered devices before adding battery-operated devices as a "weak" Zigbee network mesh (e.g., the device is too far from the Zigbee coordinator or a Zigbee router) may prevent some devices from being paired. Zigbee router devices are also needed to increase the maximum of devices that can be connected to your Zigbee mesh network.
|
||||
- Note that some Zigbee devices are not fully compatible with all brands of Zigbee router devices. Xiaomi/Aqara devices are for example known not to work with Zigbee router devices from Centralite, General Electrics, Iris, Ledvance/OSRAM, LIGHTIFY/Sylvania, Orvibo, PEQ, Securifi, and SmartThings/Samsung. Better results can usually be achieved by using mains-powered devices IKEA and Nue/3A Home or dedicated DIY routing devices based on Texas Instruments CC253x/CC26x2 and XBee Series 2/3 Zigbee radios.
|
||||
- If possible try to pair your Zigbee devices in their intended final location, (and not pair it next to the Zigbee coordinator and then need to move it after).
|
||||
- Pairing a Zigbee device next to the Zigbee coordinator and then moving it later can result in dropped/lost connections or other issues.
|
||||
- If the device you want to add is not brand new and as such never paired before then you always have to make sure to first manually reset the device to its factory default settings before you will be able to add/pair it.
|
||||
- Some battery-operated Zigbee devices are known to have problems with pairing if they have Low battery voltage.
|
||||
- Some people have reported replacing the battery on their newly received Xiaomi/Aqara devices solved pairing issues.
|
||||
- Some people have reported replacing the battery on their newly received Xiaomi/Aqara devices solved pairing issues.
|
||||
- Be patient as the pairing of some Zigbee devices may require multiple attempts and you may sometimes need to try again and again.
|
||||
- Some devices, like example those from Xiaomi/Aqara, are known to not be 100% compliant with the standard Zigbee specifications and may therefore require many paring attempts over 10-20 minutes or longer.
|
||||
- Some devices, like example those from Xiaomi/Aqara, are known to not be 100% compliant with the standard Zigbee specifications and may therefore require many paring attempts over 10-20 minutes or longer.
|
||||
|
||||
### Zigbee interference avoidance and network range/coverage optimization
|
||||
|
||||
@ -644,6 +646,7 @@ Missing links between Zigbee end devices (often battery-powered devices) in the
|
||||
Some end devices (for example, Xiaomi door sensors) sleep for an extended period, causing the parent Zigbee Router to remove them from its child table via a feature called router child aging. Since using child aging and removing them from the child table is a Zigbee 3.0 feature, this does not always occur because not all Zigbee router devices use child aging.
|
||||
|
||||
This is what causes devices to show a missing link. Even though the device is no longer in the child table, the end device can still communicate via the parent Zigbee router.
|
||||
|
||||
#### How to interpret RSSI and LQI values
|
||||
|
||||
Interpreting RSSI and LQI values can be complex, as metrics of network health and communication quality are provided by the devices themselves, and each device could get to its results in different ways. Unless you are a Zigbee specialist yourself or are guided by one, please ignore those values. They can be misleading. If you delve into this, it is important to understand not to judge RSSI or LQI values on their own. When troubleshooting Zigbee messages that are being dropped, you must interpret the combination of both RSSI and LQI.
|
||||
@ -670,7 +673,7 @@ When reporting potential bugs related to the ZHA integration on the issues track
|
||||
1. Debug logs for the issue, see [debug logging](#debug-logging).
|
||||
2. Exact model and firmware of the Zigbee radio (Zigbee Coordinator adapter) being used.
|
||||
3. If the issue is related to a specific Zigbee device, provide both the **Zigbee Device Signature** and the **Diagnostics** information.
|
||||
- Both the **Zigbee Device Signature** and the **Diagnostics** information can be found under {% my integrations title="**Settings** > **Devices & services**" %}. Select the **Zigbee Home Automation** integration. Then, select **Configure** > **Devices** (pick your device). Select **Zigbee Device Signature** and **Download Diagnostics**, respectively.
|
||||
- Both the **Zigbee Device Signature** and the **Diagnostics** information can be found under {% my integrations title="**Settings** > **Devices & services**" %}. Select the **Zigbee Home Automation** integration. Then, select **Configure** > **Devices** (pick your device). Select **Zigbee Device Signature** and **Download Diagnostics**, respectively.
|
||||
|
||||
Note: Please also make sure you give it your best effort to follow the recommended best practices for avoiding both [pairing/connection difficulties](#best-practices-to-avoid-pairingconnection-difficulties) and [Zigbee interference](#zigbee-interference-avoidance-and-network-rangecoverage-optimization), (which helps free up time for developers).
|
||||
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user