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-18 23:06:58 +00:00
Code Issues Packages Projects Releases Wiki Activity

Merge branch 'current' into rc

Browse Source
This commit is contained in:
Franck Nijhof 2025-07-02 13:47:07 +00:00
commit 0baef16f89
No known key found for this signature in database
GPG Key ID: AB33ADACE7101952
41 changed files with 1508 additions and 546 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

16
.textlintrc.json
View File

@ -1,6 +1,20 @@
{
"filters": {
"comments": true
"comments": true,
"allowlist": {
"allow": [
"2fa:",
"alexa:",
"homeassistant:",
"homekit:",
"led:",
"sms:",
"sql:",
"ssl:",
"twitter:",
"url:"
]
}
},
"rules": {
"common-misspellings": {

2
Gemfile.lock
View File

@ -159,7 +159,7 @@ GEM
rack-protection (= 4.1.1)
rack-session (>= 2.0.0, < 3)
tilt (~> 2.0)
sorbet-runtime (0.5.12201)
sorbet-runtime (0.5.12216)
stringex (2.8.6)
terminal-table (3.0.2)
unicode-display_width (>= 1.1.1, < 3)

749
package-lock.json generated
View File

File diff suppressed because it is too large Load Diff

5
package.json
View File

@ -15,10 +15,11 @@
"remark-lint-prohibited-strings": "^4.0.0",
"remark-lint-unordered-list-marker-style": "^4.0.1",
"remark-stringify": "^11.0.0",
"textlint": "^15.0.1",
"textlint": "^15.1.0",
"textlint-filter-rule-allowlist": "^4.0.0",
"textlint-filter-rule-comments": "^1.2.2",
"textlint-rule-common-misspellings": "^1.0.1",
"textlint-rule-terminology": "^5.0.13"
"textlint-rule-terminology": "^5.2.13"
},
"resolutions": {
"minimist": ">=1.2.5"

4
source/_dashboards/light.markdown
View File

@ -2,7 +2,7 @@
type: card
title: "Light card"
sidebar_label: Light
description: "The light card allows you to change the brightness of the light."
description: "The light card allows you to change the brightness of a light."
related:
- docs: /dashboards/actions/
title: Card actions
@ -12,7 +12,7 @@ related:
title: Dashboard cards
---
The light card allows you to change the brightness of the light.
The light card allows you to change the brightness of a light.
<p class='img'>
<img src='/images/dashboards/light_card.png' alt='Screenshot of the Light card'>

4
source/_dashboards/sensor.markdown
View File

@ -2,7 +2,7 @@
type: card
title: "Sensor card"
sidebar_label: Sensor
description: "The sensor card gives you a quick overview of your sensors state with an optional graph to visualize change over time."
description: "The sensor card gives you a quick overview of a sensor's state with an optional graph to visualize change over time."
related:
- docs: /integrations/frontend/
title: Themes
@ -10,7 +10,7 @@ related:
title: Dashboard cards
---
The sensor card gives you a quick overview of your sensors state with an optional graph to visualize change over time.
The sensor card gives you a quick overview of a sensor's state with an optional graph to visualize change over time.
<p class='img'>
<img src='/images/dashboards/sensor.png' alt='Screenshot of the sensor card'>

4
source/_dashboards/tile.markdown
View File

@ -2,7 +2,7 @@
type: card
title: "Tile card"
sidebar_label: Tile
description: "The tile card gives you a quick overview of your entity. The card allows you to toggle the entity, show the more-info dialog, or custom actions."
description: "The tile card gives you a quick overview of an entity. The card allows you to toggle the entity, show the more-info dialog, or custom actions."
related:
- docs: /dashboards/actions/
title: Card actions
@ -12,7 +12,7 @@ related:
title: Dashboard cards
---
The tile card gives you a quick overview of your {% term entity %}. The card allows you to add tap actions, and features to control the entity. You can also select the {% term entity %} to open the more info dialog. A badge is shown for some {% term entities %} like the [climate](/integrations/climate) or [person](/integrations/person) {% term entities %}.
The tile card gives you a quick overview of an {% term entity %}. The card allows you to add tap actions, and features to control the entity. You can also select the {% term entity %} to open the more info dialog. A badge is shown for some {% term entities %} like the [climate](/integrations/climate) or [person](/integrations/person) {% term entities %}.
<p class='img'>
<img src='/images/dashboards/tile_card_tap_action.webp' alt='Screenshot of tile cards'>

6
source/_dashboards/weather-forecast.markdown
View File

@ -61,6 +61,11 @@ name:
description: Overwrites the friendly name.
type: string
default: Entity name
show_current:
required: false
description: Show the current weather conditions above the forecast.
type: boolean
default: true
show_forecast:
required: false
description: Show next hours/days forecast.
@ -70,7 +75,6 @@ forecast_type:
required: true
description: Type of forecast to display, one of `daily`, `hourly` or `twice_daily`.
type: string
default: Automatically selects in order of `daily`, `hourly` and `twice_daily`.
secondary_info_attribute:
required: false
description: Which attribute to display under the temperature.

37
source/_docs/backend/database.markdown
View File

@ -74,7 +74,7 @@ CREATE TABLE statistics_meta (
unit_of_measurement VARCHAR(255),
has_mean BOOLEAN,
has_sum BOOLEAN,
name VARCHAR(255),
name VARCHAR(255), mean_type INTEGER NOT NULL DEFAULT 0,
PRIMARY KEY (id)
)
@ -87,14 +87,6 @@ CREATE TABLE recorder_runs (
PRIMARY KEY (run_id)
)
CREATE TABLE migration_changes (
migration_id VARCHAR(255) NOT NULL,
version SMALLINT NOT NULL,
PRIMARY KEY (migration_id)
)
CREATE TABLE schema_changes (
change_id INTEGER NOT NULL,
schema_version INTEGER,
@ -137,7 +129,6 @@ CREATE TABLE states (
event_id SMALLINT,
last_changed CHAR(0),
last_changed_ts FLOAT,
last_reported_ts FLOAT,
last_updated CHAR(0),
last_updated_ts FLOAT,
old_state_id INTEGER,
@ -149,7 +140,7 @@ CREATE TABLE states (
context_id_bin BLOB,
context_user_id_bin BLOB,
context_parent_id_bin BLOB,
metadata_id INTEGER,
metadata_id INTEGER, last_reported_ts FLOAT,
PRIMARY KEY (state_id),
FOREIGN KEY(old_state_id) REFERENCES states (state_id),
FOREIGN KEY(attributes_id) REFERENCES state_attributes (attributes_id),
@ -169,7 +160,7 @@ CREATE TABLE statistics (
last_reset CHAR(0),
last_reset_ts FLOAT,
state FLOAT,
sum FLOAT,
sum FLOAT, mean_weight FLOAT,
PRIMARY KEY (id),
FOREIGN KEY(metadata_id) REFERENCES statistics_meta (id) ON DELETE CASCADE
)
@ -187,7 +178,7 @@ CREATE TABLE statistics_short_term (
last_reset CHAR(0),
last_reset_ts FLOAT,
state FLOAT,
sum FLOAT,
sum FLOAT, mean_weight FLOAT,
PRIMARY KEY (id),
FOREIGN KEY(metadata_id) REFERENCES statistics_meta (id) ON DELETE CASCADE
)
@ -212,27 +203,33 @@ CREATE INDEX ix_events_data_id ON events (data_id)
CREATE INDEX ix_events_event_type_id_time_fired_ts ON events (event_type_id, time_fired_ts)
CREATE INDEX ix_events_context_id_bin ON events (context_id_bin)
CREATE INDEX ix_events_time_fired_ts ON events (time_fired_ts)
CREATE INDEX ix_events_context_id_bin ON events (context_id_bin)
CREATE INDEX ix_states_context_id_bin ON states (context_id_bin)
CREATE INDEX ix_states_attributes_id ON states (attributes_id)
CREATE INDEX ix_states_last_updated_ts ON states (last_updated_ts)
CREATE INDEX ix_states_metadata_id_last_updated_ts ON states (metadata_id, last_updated_ts)
CREATE INDEX ix_states_old_state_id ON states (old_state_id)
CREATE INDEX ix_states_context_id_bin ON states (context_id_bin)
CREATE INDEX ix_states_last_updated_ts ON states (last_updated_ts)
CREATE INDEX ix_statistics_start_ts ON statistics (start_ts)
CREATE UNIQUE INDEX ix_statistics_statistic_id_start_ts ON statistics (metadata_id, start_ts)
CREATE INDEX ix_statistics_start_ts ON statistics (start_ts)
CREATE UNIQUE INDEX ix_statistics_short_term_statistic_id_start_ts ON statistics_short_term (metadata_id, start_ts)
CREATE INDEX ix_statistics_short_term_start_ts ON statistics_short_term (start_ts)
CREATE UNIQUE INDEX ix_statistics_short_term_statistic_id_start_ts ON statistics_short_term (metadata_id, start_ts)
CREATE TABLE migration_changes (
migration_id VARCHAR(255) NOT NULL,
version SMALLINT NOT NULL,
PRIMARY KEY (migration_id)
)
```
To only show the details about the `states` table (since we are using that one in the next examples):

241
source/_integrations/adguard.markdown
View File

@ -9,7 +9,7 @@ ha_release: 0.95
ha_iot_class: Local Polling
ha_config_flow: true
ha_codeowners:
- '@frenck'
- "@frenck"
ha_domain: adguard
ha_platforms:
- sensor
@ -17,15 +17,38 @@ ha_platforms:
ha_integration_type: service
---
AdGuard Home is a network-wide DNS server that supports ad, tracker,
and adult content blocking. The **AdGuard** integration allows you to control and
monitor your AdGuard Home instance in Home Assistant.
The **AdGuard Home** {% term integration %} allows you to control and monitor your [AdGuard Home](https://adguard.com/adguard-home/overview.html) instance in Home Assistant.
AdGuard Home is a network-wide software for blocking advertisements and tracking. It provides DNS-level protection, automatically covering all home devices without requiring client-side software. When you use AdGuard Home as your DNS server, it blocks advertisements, trackers, and malicious domains for all devices on your network.
## Prerequisites
Before setting up the AdGuard Home integration, ensure you have:
1. AdGuard Home installed and running on your network
2. The IP address or hostname of your AdGuard Home instance
3. Admin access to AdGuard Home
{% include integrations/config_flow.md %}
## Sensors
{% configuration_basic %}
Host:
description: "The IP address or hostname of your AdGuard Home instance. For example: `192.168.1.100` or `adguard.local`."
Port:
description: "The port AdGuard Home is running on. Default is `3000` for the web interface."
Username:
description: "Your AdGuard Home admin username."
Password:
description: "Your AdGuard Home admin password."
Verify SSL certificate:
description: "Enable SSL certificate verification when connecting via HTTPS."
{% endconfiguration_basic %}
This integration provides {% term sensors %} for the following information from AdGuard Home:
## Supported functionality
### Sensors
This integration provides sensors for the following information from AdGuard Home:
- Number of DNS queries.
- Number of blocked DNS queries.
@ -36,77 +59,193 @@ This integration provides {% term sensors %} for the following information from
- Total number of active filter rules loaded.
- Average response time of AdGuard's DNS server in milliseconds.
## Switches
### Switches
The integration will create a number of switches:
The integration provides switches to control AdGuard Home features:
- AdGuard Protection (master switch).
- Filtering.
- Safe Browsing.
- Parental Control.
- Safe Search.
- Query Log.
- **AdGuard protection**: Master switch that controls all AdGuard features
- **Filtering**: Enables DNS filtering using blocklists
- **Safe browsing**: Blocks known phishing and malware sites
- **Parental control**: Blocks adult content
- **Safe search**: Enforces safe search on search engines
- **Query log**: Records DNS queries for statistics
These switches allow you to automate things easily. For example, one could
write an automation to turn off Safe Search after the kids' bedtime.
These switches enable powerful automations. For example, you could automatically enable parental controls during school hours or disable ad blocking for specific time periods.
The "AdGuard Protection" switch is a master switch. It will turn off and
bypass all AdGuard features, regardless of whether they are switched on or not.
The **AdGuard protection** switch acts as a master control. When turned off, it bypasses all AdGuard features regardless of individual switch states.
{% important %}
Turning off Query Log will result in all sensors not receiving updates anymore.
AdGuard relies on Query Log to provide stats.
Turning off **Query log** stops all sensor updates. AdGuard requires query logging to provide statistics.
{% endimportant %}
## Actions
These {% term actions %} allow one to manage filter subscriptions in AdGuard Home.
Using these actions in automations could be helpful to block certain
sites/domains at certain times.
The integration provides {% term actions %} to manage filter subscriptions in AdGuard Home. Use these actions in automations to dynamically control content filtering based on time, presence, or other conditions.
For example, you could create a custom filter list that blocks social media sites
during the day and releases them during the evening.
For example, you could create automations that:
### Action `add_url`
- Block social media during work hours
- Enable strict filtering when guests connect to your network
- Temporarily disable filtering for specific downloads
Add a new filter subscription to AdGuard Home.
### Action `adguard.add_url`
| Data attribute | Optional | Description |
| ---------------------- | -------- | ------------------------------------------------------------ |
| `name` | No | The name of the filter subscription. |
| `url` | No | The filter URL to subscribe to, containing the filter rules. |
Adds a new filter subscription to AdGuard Home.
### Action `remove_url`
| Data attribute | Optional | Description |
| -------------- | -------- | --------------------------------------------- |
| `name` | No | The name of the filter subscription |
| `url` | No | The filter list URL containing blocking rules |
### Action `adguard.remove_url`
Removes a filter subscription from AdGuard Home.
| Data attribute | Optional | Description |
| ---------------------- | -------- | -------------------------------------- |
| `url` | No | The filter subscription URL to remove. |
| Data attribute | Optional | Description |
| -------------- | -------- | ------------------------------------- |
| `url` | No | The filter subscription URL to remove |
### Action `enable_url`
### Action `adguard.enable_url`
Enables a filter subscription in AdGuard Home.
Enables a previously disabled filter subscription.
| Data attribute | Optional | Description |
| -------------- | -------- | ------------------------------------- |
| `url` | No | The filter subscription URL to enable |
### Action `adguard.disable_url`
Temporarily disables a filter subscription without removing it.
| Data attribute | Optional | Description |
| ---------------------- | -------- | -------------------------------------- |
| `url` | No | The filter subscription URL to enable. |
| -------------- | -------- | -------------------------------------- |
| `url` | No | The filter subscription URL to disable |
### Action `disable_url`
### Action `adguard.refresh`
Disables a filter subscription in AdGuard Home.
Refreshes all filter subscriptions to get the latest blocking rules.
| Data attribute | Optional | Description |
| ---------------------- | -------- | --------------------------------------- |
| `url` | No | The filter subscription URL to disable. |
| Data attribute | Optional | Description |
| -------------- | -------- | ----------------------------------------------- |
| `force` | Yes | Force update (bypasses AdGuard Home throttling) |
### Action `refresh`
By default, `force` is `false`. AdGuard Home normally throttles filter updates to reduce server load. Use forced updates sparingly.
Refresh all filter subscriptions in AdGuard Home.
## Examples
| Data attribute | Optional | Description |
| ---------------------- | -------- | ------------------------------------------------- |
| `force` | Yes | Force update (bypasses AdGuard Home throttling). |
### Block social media during work hours
By default, `force` is set to `false`. Forcing an update bypasses AdGuard Home's
throttling logic, so use with care.
This automation blocks social media sites during business hours:
```yaml
automation:
- alias: "Block social media during work"
triggers:
- trigger: time
at: "09:00:00"
actions:
- action: adguard.add_url
data:
name: "Social media blocklist"
url: "https://raw.githubusercontent.com/example/social-media-blocklist/main/list.txt"
- action: adguard.refresh
- alias: "Unblock social media after work"
triggers:
- trigger: time
at: "17:00:00"
actions:
- action: adguard.remove_url
data:
url: "https://raw.githubusercontent.com/example/social-media-blocklist/main/list.txt"
```
### Enable strict filtering when guests arrive
Automatically enable all protection features when guests connect to your network:
```yaml
automation:
- alias: "Enable strict filtering for guests"
triggers:
- trigger: state
entity_id: group.guest_devices
from: "not_home"
to: "home"
actions:
- action: switch.turn_on
target:
entity_id:
- switch.adguard_parental_control
- switch.adguard_safe_browsing
- switch.adguard_safe_search
```
### Monitor DNS performance
Send a notification if DNS response time exceeds threshold:
{% raw %}
```yaml
automation:
- alias: "Alert on slow DNS"
triggers:
- trigger: numeric_state
entity_id: sensor.adguard_average_processing_speed
above: 50
actions:
- action: notify.mobile_app
data:
title: "DNS Performance Alert"
message: "AdGuard DNS response time is {{ states('sensor.adguard_average_processing_speed') }}ms"
```
{% endraw %}
## Data updates
The AdGuard Home integration polls for updates every 10 seconds to provide near real-time statistics and ensure switch states remain synchronized.
## Troubleshooting
### Integration fails to connect
#### Symptom: "Cannot connect to AdGuard Home"
When setting up the integration, you receive a connection error.
##### Resolution
1. Verify AdGuard Home is running:
- Access the AdGuard Home web interface at `http://YOUR_IP:3000`.
- Check the service status on your server.
2. Check network connectivity:
- Ensure Home Assistant can reach the AdGuard Home instance.
- Verify no firewall rules block port 3000.
3. Confirm credentials:
- Test login via the AdGuard Home web interface.
- Ensure you're using admin credentials.
### Sensors show unavailable
If sensors display as unavailable:
1. Check that **Query log** switch is enabled.
2. Verify AdGuard Home is processing DNS queries.
3. Ensure at least one device uses AdGuard Home as DNS server.
### Actions fail with "Filter URL not found"
This error occurs when trying to enable, disable, or remove a non-existent filter URL. Verify the exact URL using the AdGuard Home web interface under **Filters** > **DNS blocklists**.
## Removing the integration
This integration follows standard integration removal. After removal, your AdGuard Home instance continues running with its current configuration.
{% include integrations/remove_device_service.md %}

7
source/_integrations/airthings.markdown
View File

@ -46,3 +46,10 @@ Upon saving the settings, you will be presented with a generated id and secret.
The Airthings integration can now be activated using the generated id and secret that you have just created.
{% include integrations/config_flow.md %}
## Troubleshooting
### The radon sensor does not show up
Initially, the radon sensor may not be published by the Airthings API (at device startup, the value is considered "unknown"), and so you may have to wait for the radon sensor to appear for a new device.

2
source/_integrations/alexa.intent.markdown
View File

@ -65,7 +65,7 @@ Next you need to create a Lambda function.
- **US West (Oregon)** region for Japanese and English (AU) skills.
- Click `Functions` in the left navigation bar, display list of your Lambda functions.
- Click `Create function`, select `Author from scratch`, then input a `Function name`.
- Select *Python 3.* as `Runtime` (Python 3.9 was available at this time).
- Select `Python 3.x` as the `Runtime` (choose the latest available Python 3 version).
- Select *Use an existing role* as `Execution role`, then select the role you just created from the `Existing role` list.
- Click `Create function`, then you can configure the details of the Lambda function.
- Under the `Configuration` tab, expand `Designer`, then click on `+ Add trigger` in the left part of the panel and select `Alexa Skills Kit` from the dropdown list to add an Alexa Skills Kit trigger to your Lambda function.

2
source/_integrations/alexa.smart_home.markdown
View File

@ -157,7 +157,7 @@ Next you need create a Lambda function.
- Click `Functions` in the left navigation bar, to display the list of your Lambda functions.
- Click `Create function`, select `Author from scratch`, then input a `Function name`.
- Select *Python 3.9*, *Python 3.8* or *Python 3.7* as `Runtime`.
- Select `Python 3.x` as the `Runtime` (choose the latest available Python 3 version).
- Expand the `Change default execution role` dropdown and make sure to select *Use an existing role* as `Execution role`, then select the role you just created from `Existing role` list.
- Click `Create function`, then you can configure the details of Lambda function.
- Expand the `Function overview` (if it isn't already expanded), then click `+ Add trigger` in the left part of the panel, then click `Alexa Smart Home` from the drop down list to add an Alexa Smart Home trigger to your Lambda function.

23
source/_integrations/alexa_devices.markdown
View File

@ -85,29 +85,6 @@ automation:
entity_id: notify.echo_dot_livingroom_announce
```
### Automation: Start Radio on all Echo dots
```yaml
automation:
- alias: Start Radio B.B.C.
id: "start_radio_bbc"
trigger:
- platform: sun
event: sunset
condition:
conditions:
- alias: "condition alias (home)"
condition: state
entity_id: group.person_family
state: "home"
action:
- action: notify.send_message
data:
message: Play B.B.C. on Tunein
target:
entity_id: notify.everywhere_announce
```
## Data updates
This integration {% term polling polls %} data from the device every 30 seconds by default.

13
source/_integrations/androidtv_remote.markdown
View File

@ -156,7 +156,7 @@ media_player:
## Remote
The remote allows you to send key commands to your Android TV device with the `remote.send_command` action.
The remote allows you to send key commands and text as input to your Android TV device with the `remote.send_command` action.
The entity has the `current_activity` attribute that shows the current foreground app on the Android TV.
You can pass the application ID shown in this `current_activity` as `activity` in the `remote.turn_on` action to launch that app.
@ -242,6 +242,8 @@ Other:
{% enddetails %}
To send text as keyboard input use the `remote.send_command` and prefix the text to send with `text:`, e.g. `command: text:hello world` to type "hello world" in the selected input field.
If `activity` is specified in `remote.turn_on` it will open the specified URL or the application with the given package name. See [Launching apps section](#launching-apps).
Example actions:
@ -265,6 +267,15 @@ target:
entity_id: remote.living_room_tv
```
```yaml
# Send "Never Gonna Give You Up" as keyboard input text to the selected input field
action: remote.send_command
data:
command: text:Never Gonna Give You Up
target:
entity_id: remote.living_room_tv
```
```yaml
# Launch YouTube
action: remote.turn_on

5
source/_integrations/button.markdown
View File

@ -42,7 +42,10 @@ In addition, the entity can have the following states:
- **Unknown**: The state is not yet known.
Because the {% term state %} of a button entity in Home Assistant is a timestamp, it
means we can use it in our automations. For example:
changes every time the button is pressed. This means we can trigger automations on
any state change of the button entity, which effectively captures when the button
is pressed. We don't need to use the actual timestamp value; we only care that the
state changed, indicating a button press:
```yaml
triggers:

1
source/_integrations/html5.markdown
View File

@ -30,7 +30,6 @@ The `html5` platform can only function if all of the following requirements are
- You are using Chrome and/or Firefox on any desktop platform, ChromeOS or Android. Or you added your Home Assistant instance to your home screen on iOS 16.4 or higher.
- Your Home Assistant instance is accessible from outside your network over HTTPS or can perform an alternative [Domain Name Verification Method](https://support.google.com/webmasters/answer/9008080#domain_name_verification) on the domain used by Home Assistant.
- If using a proxy, HTTP basic authentication must be disabled to register or deregister push notifications. It can be re-enabled afterwards.
- If you don't run Hass.io: `pywebpush` must be installed. `libffi-dev`, `libpython-dev` and `libssl-dev` must be installed prior to `pywebpush` (i.e., `pywebpush` probably won't automatically install).
- You have configured SSL/TLS for your Home Assistant. It doesn't need to be configured in Home Assistant though, e.g., you can be running NGINX in front of Home Assistant and this will still work. The certificate must be trustworthy (i.e., not self-signed).
- You are willing to accept the notification permission in your browser.

6
source/_integrations/mqtt.markdown
View File

@ -370,7 +370,7 @@ Supported shared options are:
- `qos`
- `encoding`
The component specific options are placed as mappings under the `components` key (abbreviated as `cmp`) like:
The component specific options are placed as mappings under the `components` key (abbreviated as `cmps`) like:
```json
{
@ -409,7 +409,7 @@ The component specific options are placed as mappings under the `components` key
}
```
The components id's under the `components` (`cmp`) key, are used as part of the discovery identification. A `platform` (`p`) config option is required for each component config that is added to identify the component platform. Also required is a `unique_id` for entity-based components.
The components id's under the `components` (`cmps`) key, are used as part of the discovery identification. A `platform` (`p`) config option is required for each component config that is added to identify the component platform. Also required is a `unique_id` for entity-based components.
To remove the components, publish an empty (retained) string payload to the discovery topic. This will remove the component and clear the published discovery payload. It will also remove the device entry if there are no further references to it.
@ -569,7 +569,7 @@ Check the logs to ensure this step is executed correctly.
**Step 3: Publish the new device-based discovery configuration:**
Discovery topic device: `homeassistant/device/0AFFD2/config`
Discovery id: `0AFFD2 bla` *(`0AFFD2`from discovery topic, `bla`: The key under `cmp` in the discovery payload)*
Discovery id: `0AFFD2 bla` *(`0AFFD2`from discovery topic, `bla`: The key under `cmps` in the discovery payload)*
Discovery payload device:
```json

6
source/_integrations/nina.markdown
View File

@ -72,3 +72,9 @@ Areas: `gemeinde oberreichenbach, gemeinde neuweiler, stadt nagold`
| `sent` | *(time)* Transmission time and date (UTC) of the issued warning. |
| `start` | *(time)* Starting time and date (UTC) of the issued warning. Can be empty. |
| `expires` | *(time)* Expiration time and date (UTC) of the issued warning. Can be empty. |
## Removing the integration
This integration follows standard integration removal. No extra steps are required.
{% include integrations/remove_device_service.md %}

1
source/_integrations/opower.markdown
View File

@ -50,6 +50,7 @@ More than 175 utilities use Opower. Currently only the following utilities are s
- National Grid NY Metro
- National Grid NY Upstate
- Pacific Gas & Electric (PG&E)
> **Note:** Currently only works with PG&E accounts created **before June 2025** that do not require multi-factor authentication (MFA).
- Portland General Electric (PGE)
- Puget Sound Energy (PSE)
- Sacramento Municipal Utility District (SMUD)

2
source/_integrations/pi_hole.markdown
View File

@ -22,7 +22,7 @@ ha_integration_type: integration
---
The Pi-hole integration allows you to retrieve statistics and interact with a
[Pi-hole](https://pi-hole.net/) system.
[Pi-hole](https://pi-hole.net/) system (version < 6.0).
{% include integrations/config_flow.md %}

1
source/_integrations/rehlko.markdown
View File

@ -105,6 +105,7 @@ These are the generator models that have been tested:
- [20RESA](https://resources.kohler.com/power/kohler/residential/pdf/tp6804.pdf)
- [20RCA](https://www.kohlerhomeenergy.rehlko.com/products/home+generators/20rca)
- [14RESA](https://www.kohler.com/content/dam/kohler-com-NA/Lifestyle/PDF/PDF-tp6803.pdf)
- [30RCL](https://www.kohlerhomeenergy.rehlko.com/products/home+generators/30rcla)
## Removing the integration

2
source/_integrations/sensor.rest.markdown
View File

@ -314,7 +314,7 @@ rest:
{% endraw %}
[JSONPlaceholder](https://jsonplaceholder.typicode.com/) provides sample JSON data for testing. In the below example, JSONPath locates the attributes in the JSON document. [JSONPath Online Evaluator](https://jsonpath.com/) provides a tool to test your JSONPath. If the endpoint returns XML, it will be converted to JSON using `xmltodict` before searching for attributes. You may find the [XMLtoDict debug tool](https://xmltodict-debugger.glitch.me/) helpful for testing how your XML converts to JSON.
[JSONPlaceholder](https://jsonplaceholder.typicode.com/) provides sample JSON data for testing. In the below example, JSONPath locates the attributes in the JSON document. [JSONPath Online Evaluator](https://jsonpath.com/) provides a tool to test your JSONPath. If the endpoint returns XML, it will be converted to JSON using `xmltodict` before searching for attributes. You may find this [XML to JSON Converter](https://www.freeformatter.com/xml-to-json-converter.html) helpful for testing how your XML converts to JSON.
{% raw %}

6
source/_integrations/sonos.markdown
View File

@ -464,3 +464,9 @@ sonos:
media_player:
advertise_addr: 192.0.2.1
```
## Removing the integration
This integration follows the standard integration removal process; no extra steps are required.
{% include integrations/remove_device_service.md %}

70
source/_integrations/switchbot.markdown
View File

@ -21,6 +21,8 @@ ha_codeowners:
- '@dsypniewski'
- '@zerzhang'
ha_domain: switchbot
works_with:
- bluetooth
ha_bluetooth: true
ha_platforms:
- binary_sensor
@ -169,6 +171,27 @@ For instructions on how to obtain the encryption key, see README in [PySwitchbot
- [Air Purifier](https://www.switch-bot.com/products/switchbot-air-purifier)
- [Air Purifier Table](https://www.switch-bot.com/products/switchbot-air-purifier-table)
## Works with Home Assistant
SwitchBot is committed to making sure their products are up-to-date and ready to use in Home Assistant.
Devices are certified for both Bluetooth and Matter.
The following devices are certified for Bluetooth:
- [SwitchBot Lock Ultra](https://www.switch-bot.com/products/switchbot-lock-ultra)
- [SwitchBot Air Purifier](https://www.switch-bot.com/products/switchbot-air-purifier)
- [SwitchBot Air Purifier Table](https://www.switch-bot.com/products/switchbot-air-purifier-table)
- [SwitchBot Leak Detector](https://www.switch-bot.com/products/switchbot-water-leak-detector)
- [SwitchBot Meter](https://www.switch-bot.com/products/switchbot-meter)
- [SwitchBot Meter Pro](https://www.switch-bot.com/products/switchbot-meter-pro)
- [SwitchBot Meter Pro CO2](https://www.switch-bot.com/products/switchbot-meter-pro-co2-monitor)
- [SwitchBot Indoor/Outdoor Thermo-Hygrometer](https://www.switch-bot.com/products/switchbot-indoor-outdoor-thermo-hygrometer)
- [SwitchBot Curtain 3](https://www.switch-bot.com/products/switchbot-curtain-3)
- [SwitchBot Contact Sensor](https://www.switch-bot.com/products/contact-sensor)
- [SwitchBot Roller Shade](https://www.switch-bot.com/products/switchbot-roller-shade)
- [SwitchBot Lock Pro](https://www.switch-bot.com/products/switchbot-lock-pro)
To see the list of SwitchBot Matter certified devices, visit the [SwitchBot Matter](switchbot_matter.markdown) page.
## Supported functionality
### Common
@ -466,6 +489,12 @@ Features:
- calibration state
- get battery level
Options:
1. To enable nightlatch operation mode, go to {% my integrations title="**Settings** > **Devices & services**" %}.
2. Under **Integration entries**, find the lock and select **Configure**.
3. In the **Options** dialog, configure the nightlatch operation mode.
#### Lock Pro
This is an encrypted device.
@ -478,6 +507,14 @@ Features:
- calibration state
- get battery level
Options:
1. To enable nightlatch operation mode, go to {% my integrations title="**Settings** > **Devices & services**" %}.
2. Under **Integration entries**, find the lock and select **Configure**.
3. In the **Options** dialog, configure the nightlatch operation mode.
#### Lock Ultra
This is an encrypted device.
@ -490,6 +527,12 @@ Features:
- calibration state
- get battery level
Options:
1. To enable nightlatch operation mode, go to {% my integrations title="**Settings** > **Devices & services**" %}.
2. Under **Integration entries**, find the lock and select **Configure**.
3. In the **Options** dialog, configure the nightlatch operation mode.
#### Lock Lite
This is an encrypted device.
@ -497,8 +540,6 @@ This is an encrypted device.
Features:
- Lock or unlock
- open or closed state
- auto-lock paused state
- calibration state
- get battery level
@ -532,17 +573,17 @@ Features:
### Fans
Fan entities are added for Circulator Fan, Air Purifier, and Air Purifier Table
Fan entities are added for Battery Circulator Fan/Circulator Fan, Air Purifier, and Air Purifier Table
#### Circulator Fan
#### Battery Circulator Fan/Circulator Fan
Features:
- turn on
- turn off
- set speed
- set mode
- oscillate left and right
- get battery level (Battery Circulator Fan only)
#### Air Purifier
@ -569,7 +610,7 @@ Features:
Vacuum entities are added for K10+, K10+ Pro, K10+ Pro Combo, K20, S10.
Features:
- get states, including `cleaning`, `docked`, `idle`, `paused`, `returning`, and `error`; refer to Known limitations for more details
- start
- return to base
- get battery
@ -614,10 +655,25 @@ Move the device closer, or replace the Bluetooth adapter with a faster one. See
Device names configured in the SwitchBot app are not transferred into Home Assistant.
### Battery level
Due to firmware limitations, early models such as **Lock** and **Lock Lite** report the battery level in coarse ranges rather than an exact value:
- < 10 % → 10
- 10 % – 20 % → 20
- 20 % – 60 % → 60
- ≥ 60 % → 100
Refer to the latest version of the [OpenAPI doc](https://github.com/OpenWonderLabs/SwitchBotAPI) for precise definitions.
### Lock state
The integration currently only uses the primary lock state; in dual lock mode, not all things might work properly.
### Vacuum state
For robot vacuum K10+ and K10+ Pro, due to firmware implementation, it only returns these states, `cleaning` and `docked`
## Troubleshooting
The SwitchBot integration will automatically discover devices once the [Bluetooth](/integrations/bluetooth) integration is enabled and functional.
@ -630,8 +686,6 @@ Possible custom integration conflict, using a different version of PySwitchbot;
Make sure your devices are powered on and are in range.
{% enddetails %}
## Examples
### Automation ideas

165
source/_integrations/switchbot_cloud.markdown
View File

@ -40,25 +40,160 @@ Please note, device names configured in the SwitchBot app are transferred into H
{% include integrations/config_flow.md %}
## Supported devices
### Plugs and switches
- [Bot (WoHand)](https://switch-bot.com/pages/switchbot-bot)
- [Relay Switch 1](https://www.switch-bot.com/products/switchbot-relay-switch-1)
- [Relay Switch 1PM](https://www.switch-bot.com/products/switchbot-relay-switch-1pm)
- [Plug Mini (WoPlug)](https://www.switch-bot.com/products/switchbot-plug-mini)
- [Plug Mini (HomeKit Enabled)](https://www.switch-bot.com/products/switchbot-plug-mini-homekit-enabled)
- Plug (Wi-Fi only, only available in Japan)
- Plug Mini, both the original and HomeKit-enabled
### Locks
- [Lock (WoLock)](https://switch-bot.com/pages/switchbot-lock)
- [Lock Pro (WoLockPro)](https://www.switch-bot.com/pages/switchbot-lock-pro)
### Sensors
- [Meter](https://switch-bot.com/pages/switchbot-meter)
- [Meter Plus](https://switch-bot.com/pages/switchbot-meter-plus)
- [Indoor/Outdoor Meter (WoIOSensorTH)](https://switch-bot.com/pages/switchbot-indoor-outdoor-thermo-hygrometer)
- [Meter Pro](https://www.switch-bot.com/products/switchbot-meter-pro)
- [Meter Pro CO2 Monitor](https://www.switch-bot.com/products/switchbot-meter-pro-co2-monitor)
### Hubs
- [Hub 2 (WoHub2)](https://switch-bot.com/pages/switchbot-hub-2) (currently only supports retrieving sensor data, does not yet support device control)
- IR appliances exposed through the different hubs:
- ON/OFF for all appliance types excepted "Others"
- Air Conditioner
- Lock
- Lock Pro
- Meter
- MeterPlus
- MeterPro
- MeterPro (C02)
- Outdoor Meter
- Vacuum K10+, K10+ pro, S1, S1 Plus
- Hub 2
- Relay Switch 1
- Relay Switch 1PM
- Bot (as a Switch in `switchMode` and `customizeMode`, as a Button in `pressMode`)
- ON/OFF for all appliance types except for *Others*
- Change temperature and mode for *Air Conditioner*
### Vacuums
- [K10+](https://www.switch-bot.com/products/switchbot-mini-robot-vacuum-k10)
- [K10+ Pro](https://www.switch-bot.com/products/switchbot-mini-robot-vacuum-k10-pro)
- [S1](https://www.switchbot.jp/products/switchbot-robot-vacuum-cleaner?&variant=41850919420079)
- [S1 Plus](https://www.switchbot.jp/products/switchbot-robot-vacuum-cleaner)
## Supported functionality
### Plugs and switches
#### Bot
Features:
- acted as a Switch in `switchMode` and `customizeMode`, as a Button in `pressMode`
- turn on or off
- press
- get battery level
#### Plug Mini
Features:
- turn on or off
- get power consumption readings
#### Relay Switch 1
Features:
- turn on or off
#### Relay Switch 1PM
Features:
- turn on or off
- get power
- get voltage
- get current
#### Plug
Features:
- turn on or off
### Sensors
#### Meter
Features:
- get temperature
- get humidity
- get battery level
#### Meter Plus
Features:
- get temperature
- get humidity
- get battery level
#### Indoor/Outdoor Meter
Features:
- get temperature
- get humidity
- get battery level
#### Meter Pro
Features:
- get temperature
- get humidity
- get battery level
#### Meter Pro CO2 Monitor
Features:
- get temperature
- get humidity
- get carbon dioxide
- get battery level
### Locks
#### Lock
Features:
- Lock or unlock
- open or closed state
- calibration state
- get battery level
#### Lock Pro
Features:
- Lock or unlock
- open or closed state
- calibration state
- get battery level
### Hubs
Some of the hubs can be served as a bridge while the sensor data can be retrieved. Hub 2 displays temperature and humidity through a sensor cable. Without a digital display, Hub Mini Matter Enabled can also read from a sensor cable.
#### Hub 2
Features:
- get temperature
- get humidity
### Vacuums
Vacuum entities are added for K10+, K10+ Pro, S1, S1 Plus.
Features:
- get states
- start/clean
- pause
- set cleaning mode
- return to base
- get battery
## Important considerations

47
source/_integrations/switchbot_matter.markdown Normal file
View File

@ -0,0 +1,47 @@
---
title: SwitchBot Matter
description: Connect and control your SwitchBot Matter devices using the Matter integration
ha_release: '2025.6'
ha_iot_class: Local Push
ha_category:
- Cover
- Lock
- Sensor
- Switch
ha_domain: switchbot
ha_integration_type: brand
works_with:
- matter
ha_platforms:
- binary_sensor
- cover
- lock
- sensor
- switch
ha_iot_standard: matter
ha_brand: true
---
{% include integrations/wwha.md url="https://www.switchbot.com/" %}
## Supported devices
SwitchBot also has Matter devices that are certified for use via one of their Matter hubs: either the [SwitchBot Hub 2](https://www.switch-bot.com/products/switchbot-hub-2) or the [Hub 3](https://www.switch-bot.com/products/switchbot-hub-3). Some are also certified via Matter-over-WiFi as standalone devices.
### Via a Matter Hub
- [SwitchBot Lock Ultra](https://www.switch-bot.com/products/switchbot-lock_ultra)
- [SwitchBot Meter](https://www.switch-bot.com/products/switchbot-meter)
- [SwitchBot Meter Pro](https://www.switch-bot.com/products/switchbot-meter-pro)
- [SwitchBot Meter Pro CO2](https://www.switch-bot.com/products/switchbot-meter-pro-co2-monitor)
- [SwitchBot Indoor/Outdoor Thermo-Hygrometer](https://www.switch-bot.com/products/switchbot-indoor-outdoor-thermo-hygrometer)
- [SwitchBot Curtain 3](https://www.switch-bot.com/products/switchbot-curtain-3)
- [SwitchBot Contact Sensor](https://www.switch-bot.com/products/contact-sensor)
- [SwitchBot Roller Shade](https://www.switch-bot.com/products/switchbot-roller-shade)
- [SwitchBot Lock Pro](https://www.switch-bot.com/products/switchbot-lock-pro)
### Matter-Over-WiFi (standalone, without requiring a hub)
- [SwitchBot Air Purifier](https://www.switch-bot.com/products/switchbot-air-purifier)
- [SwitchBot Air Purifier Table](https://www.switch-bot.com/products/switchbot-air-purifier-table)
- [SwitchBot Multitasking Robot K20 + Pro](https://www.switch-bot.com/products/switchbot-multitasking-household-robot-k20-pro)

12
source/_integrations/synology_dsm.markdown
View File

@ -173,6 +173,18 @@ To find the `<album_id>` you need to go to the album in your photos instance, an
For performance reasons, a maximum of 1000 images will be shown in the Media Browser.
## UPS support
This integration does not directly support the UPS systems connected to the NAS, but it can be achieved with the [Network UPS Tools (NUT)](/integrations/nut) integration. You need to enable UPS support in your NAS settings, as described in the official Synology [UPS](https://kb.synology.com/en-me/DSM/help/DSM/AdminCenter/system_hardware_ups) documentation, and then integrate the NAS as a UPS server via the NUT integration. Here is a rough step-by-step guide:
1. Activate **Enable UPS support** in the NAS settings under **Control Panel** > **Hardware & Power** > **UPS**.
2. Activate **Enable network UPS server**.
3. Select **Permitted Synology NAS Devices** and add the IP address of your Home Assistant instance.
4. Set up the [Network UPS Tools (NUT)](/integrations/nut) integration.
- **Host**: the IP address or hostname of your NAS.
- **Port**: keep the default (_3493_).
- **Username** and **Password**: keep empty as the NAS doesn't support credentials for the NUT server.
## 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 re-occurs 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.

134
source/_integrations/tailscale.markdown
View File

@ -18,26 +18,134 @@ ha_platforms:
ha_integration_type: hub
---
The Tailscale integration integrates the [Tailscale](https://www.tailscale.com) API
with Home Assistant; giving you the possibility to monitor and automate on
the state of the devices in your Tailscale VPN network (Tailnet).
The **Tailscale** {% term integration %} connects to the [Tailscale](https://www.tailscale.com) API to monitor devices in your Tailscale network (Tailnet). Use this integration to create automations based on device connectivity, track usage patterns, or receive notifications when devices go online or offline.
Tailscale is a VPN service that creates secure point-to-point connections between your devices using WireGuard technology. This integration monitors your Tailnet but doesn't provide VPN connectivity itself.
{% important %}
This integration **DOES NOT** make your Home Assistant accessible via
Tailscale VPN remotely!
This integration monitors your Tailscale network but **does not provide VPN access** to Home Assistant.
If you want to access your Home Assistant instance remotely, you will
need to install Tailscale itself on your own. For instructions on how to do
this, please consult the [Tailscale documentation](https://tailscale.com/kb/).
To access Home Assistant remotely via Tailscale:
1. Install Tailscale directly on your Home Assistant device
2. Follow the [Tailscale installation guide](https://tailscale.com/kb/)
3. Configure port forwarding or use Tailscale's subnet routes if needed
{% endimportant %}
## Prerequisites
To use the Tailscale integration, you will need to obtain an API access token,
you can create one in the [Tailscale Admin Panel](https://login.tailscale.com/admin/settings/keys).
**Required information:**
Additionally, you will need to know the Tailnet name of your Tailscale network.
You can find it in the top left corner in the [Tailscale Admin Panel](https://login.tailscale.com/admin/settings/keys)
(beside the Tailscale logo).
1. **API Access Token**: Create one in the [Tailscale Admin Panel](https://login.tailscale.com/admin/settings/keys)
- Navigate to **Settings** > **Keys**
- Click **Generate auth key** or **Generate API key**
- Select appropriate expiration and permissions
2. **Tailnet Name**: Found in the top-left corner of the [Admin Panel](https://login.tailscale.com/admin/machines)
- Usually in the format: `user@domain.com` or `organization-name`
- Also visible in the URL when browsing your admin panel
{% include integrations/config_flow.md %}
{% configuration_basic %}
API Key:
description: "Your Tailscale API access token from the Admin Panel."
Tailnet:
description: "Your Tailnet name (organization name or email address)."
{% endconfiguration_basic %}
## Supported functionality
### Sensors
The integration provides sensors for monitoring your Tailscale network:
#### Device information sensors
- **Device count**: Total number of devices in your Tailnet
- **Connected devices**: Number of currently online devices
- **Disconnected devices**: Number of currently offline devices
#### Per-device sensors
For each device in your Tailnet:
- **Connection status**: Whether the device is online or offline
- **Last seen**: Timestamp when the device was last active
- **Operating system**: Device OS (Windows, macOS, Linux, iOS, Android)
- **Tailscale version**: Version of Tailscale client running
- **IP addresses**: Both Tailscale IP and external IP
- **Location**: Approximate geographic location (if available)
### Binary sensors
The integration creates binary sensors for:
#### Network status
- **Tailnet health**: Overall network connectivity status
- **Device reachability**: Per-device online/offline status
#### Security monitoring
- **Key expiration warnings**: Alerts when auth keys are approaching expiration
- **Unauthorized access**: Notifications for new device connections (if configured)
## Examples
### Automated backups based on device availability
Start backups when specific devices are online:
```yaml
automation:
- alias: "Start backup when work laptop connects"
triggers:
- trigger: state
entity_id: binary_sensor.work_laptop_tailscale
from: "off"
to: "on"
conditions:
- condition: time
after: "18:00:00" # Only after work hours
before: "23:00:00"
actions:
- action: script.start_network_backup
- action: notify.admin
data:
message: "Starting automated backup - work laptop detected"
```
## Data updates
The Tailscale integration polls the Tailscale API every minute to check device status and network information.
## Troubleshooting
### Integration fails to connect
#### Symptom: "Unable to connect to Tailscale API" error
**Solutions:**
1. **Verify API key**:
- Ensure the key is copied correctly (no extra spaces)
- Check key hasn't expired in the Tailscale admin panel
- Verify key has appropriate permissions
2. **Network connectivity**:
- Ensure Home Assistant can reach Tailscale's API servers
- Check firewall rules if running in restricted environments
## Removing the integration
This integration follows standard integration removal.
{% include integrations/remove_device_service.md %}
After removal:
1. Your Tailscale API key remains active
2. Consider revoking the key in the Tailscale admin panel if no longer needed
3. Your Tailscale network and devices continue operating normally

19
source/_integrations/tuya.markdown
View File

@ -56,6 +56,10 @@ All Home Assistant platforms are supported by the Tuya integration, except the l
You need to have the Tuya Smart or Smart Life app installed, with an account created and
at least one device added to that account.
During the setup process, you will need:
- A second screen (such as a phone, tablet, or another computer) to display the QR code that appears during configuration
- The Smart Life or Tuya Smart app installed on your mobile device to scan the QR code
### Obtaining User Code for sign-in
To sign-in, you will need to get your **User Code** from the Smart Life /
@ -68,6 +72,21 @@ Tuya Smart app. You can find it by opening the app and:
{% include integrations/config_flow.md %}
### Scanning the QR code
To scan the QR code in the Smart Life app:
1. Open the Smart Life app
2. Tap the **+** button or **Add Device**
3. Select **Scan** or look for the QR code scanner option
4. Scan the QR code displayed on your Home Assistant screen
After adding new devices to your Tuya account through the Smart Life or Tuya Smart app, you need to reload the Tuya integration in Home Assistant for the new devices to appear:
1. Go to **{% my integrations title="Settings > Devices & Services" %}**
2. Find the Tuya integration
3. Click the three dots menu
4. Select **Reload**
## Scenes
Tuya supports scenes in their app. These allow triggering some of the more complex modes of various devices such as light changing effects. Scenes created in the Tuya app will automatically appear in the Scenes list in Home Assistant the next time the integration updates.

2
source/_integrations/weather.markdown
View File

@ -115,7 +115,7 @@ The response data field is a mapping of called target entities, each containing
{% details "Example template sensor using get_forecasts" %}
Example template sensor that contains the hourly forecast
Example [template sensor](/integrations/template#yaml-configuration) that contains the hourly forecast
{% raw %}

36
source/_integrations/zwave_js.markdown
View File

@ -132,7 +132,8 @@ While your Z-Wave mesh is permanently stored on your dongle, the additional meta
### Adding a new device to the Z-Wave network
1. In Home Assistant, go to {% my integrations title="**Settings** > **Devices & services**" %}.
2. Select the Z-Wave integration. Then select **Configure**.
2. Select the Z-Wave integration.
- Then, on the entry of the hub, select {% icon "ic:baseline-arrow-forward-ios" %} to open the device info page.
3. Select **Add device**.
- The Z-Wave controller is now in inclusion mode.
4. Check, if your device supports SmartStart:
@ -161,8 +162,9 @@ While your Z-Wave mesh is permanently stored on your dongle, the additional meta
Do this before using the device with another controller, or when you don't use the device anymore. It removes the device from the Z-Wave network stored on the controller. It also removes the device and all its entities from Home Assistant. You can not join a device to a new network if it is still paired with a controller.
1. In Home Assistant, go to {% my integrations title="**Settings** > **Devices & services**" %}.
2. Select the **Z-Wave** integration. Then, select **Configure**.
3. Select **Remove device**, then **Start exclusion**.
2. Select the **Z-Wave** integration.
- Then, select the cogwheel {% icon "mdi:cog-outline" %}.
3. Select **Remove a device**, then **Start exclusion**.
- The Z-Wave controller is now in exclusion mode.
4. Put the device you want to remove in exclusion mode. Refer to its manual how this is done.
5. The UI should confirm that the device was removed and the device and entities will be removed from Home Assistant.
@ -181,7 +183,8 @@ Do this if you have an existing Z-Wave network and want to use a new controller.
### To migrate a Z-Wave network to a new controller
1. In Home Assistant, go to {% my integrations title="**Settings** > **Devices & services**" %}.
2. Select the **Z-Wave** integration. Then, select **Configure**.
2. Select the **Z-Wave** integration.
- Then, select the cogwheel {% icon "mdi:cog-outline" %}.
3. Under **Backup and restore**, select **Migrate controller**.
4. Select **Migrate to a new controller**.
- To confirm device reset, select **Submit**.
@ -223,7 +226,8 @@ It's recommended to create a backup before making any major changes to your Z-Wa
### To backup your Z-Wave network
1. In Home Assistant, go to {% my integrations title="**Settings** > **Devices & services**" %}.
2. Select the **Z-Wave** integration. Then, select **Configure**.
2. Select the **Z-Wave** integration.
- Then, select the cogwheel {% icon "mdi:cog-outline" %}.
3. Under **Backup and restore**, select **Download backup**.
- **Result**: The backup file is downloaded to the device from which you initiated the download.
4. Done! Store the backup file somewhere safe in case you need it later to restore your Z-Wave network.
@ -232,7 +236,7 @@ It's recommended to create a backup before making any major changes to your Z-Wa
Controllers and devices with the Firmware Update Metadata Command Class allow you to update the firmware by uploading a firmware file. In those cases, you can start the firmware update from the device page in Home Assistant. Refer to the documentation of the device manufacturer to find the corresponding firmware file. An example is the [firmware page by Zooz](https://www.support.getzooz.com/kb/article/1158-zooz-ota-firmware-files/).
{% caution %}
{% note %}
**Risk of damage to the device due to firmware update**
A firmware update can damage your Z-Wave device.
@ -241,7 +245,7 @@ A firmware update can damage your Z-Wave device.
- Once you have started the update process, you must not interrupt the update process but let it complete.
The Home Assistant and Z-Wave JS teams do not take any responsibility for any damages to your device as a result of the firmware update and will not be able to help you if you render your device useless due to firmware update.
{% endcaution %}
{% endnote %}
### Prerequisites
@ -251,10 +255,11 @@ The Home Assistant and Z-Wave JS teams do not take any responsibility for any da
### To update firmware of a Z-Wave device
1. In Home Assistant, go to {% my integrations title="**Settings** > **Devices & services**" %}.
2. Select the **Z-Wave** integration. Then, select **Configure** and select the controller.
2. Select the **Z-Wave** integration.
- Then, on the entry of the hub, select {% icon "ic:baseline-arrow-forward-ios" %} to open the device info page.
3. Under **Device info**, select **Update**.
4. Select the firmware file that you previously downloaded to your computer.
- **Caution: Risk of damage to the device**
- **Notice: Risk of damage to the device**
- Make sure you select the correct firmware file.
- An incorrect firmware file can damage your device.
- Once you start the update process, you must wait for the update to complete.
@ -267,18 +272,22 @@ It is recommended to back up your Z-Wave network before resetting the device.
- The controller will forget all devices it is paired with.
- All Z-Wave devices for this network will be removed from Home Assistant.
- If there are any devices still paired with the controller when it is reset, they will have to go through the exclusion process before they can be re-paired.
- If there are any devices still paired with the controller when it is reset, they will have to be removed from their old network before they can be re-paired.
- The device firmware will remain on the device.
### Prerequisites
- Administrator rights on Home Assistant
- [Backup your Z-Wave network](#backing-up-your-z-wave-network)
- [Remove all devices that are paired with your controller from the network](#removing-a-device-from-the-z-wave-network).
- Removing can be done by any controller, not just the one that originally managed the network. In theory, this could also be done later.
### To reset a Z-Wave controller
1. In Home Assistant, go to {% my integrations title="**Settings** > **Devices & services**" %}.
2. Select the **Z-Wave** integration. Then, select the controller.
3. Under **Device info**, select the three-dot {% icon "mdi:dots-vertical" %} menu, then select **Factory reset**.
2. Select the **Z-Wave** integration.
- Then, on the entry of the hub, select {% icon "ic:baseline-arrow-forward-ios" %} to open the device info page.
3. Under **Device info**, select the three dots {% icon "mdi:dots-vertical" %} menu, then select **Factory reset**.
![Screenshot showing the device panel of a Z-Wave controller](/images/integrations/z-wave/z-wave-controller-commands.png)
4. Once the process is finished, you can use this controller to start a new network, or pass it on to someone else.
@ -1054,7 +1063,8 @@ If the interview is complete, then the device does not yet have a device file fo
When trying to determine why something isn't working as you expect, or when reporting an issue with the integration, it is helpful to know what Z-Wave JS sees as the current state of your Z-Wave network. To get a dump of your current network state, follow these steps:
1. Go to {% my integrations title="**Settings** > **Devices & services**" %}.
2. Select the **Z-Wave** integration. Then, select the three-dot {% icon "mdi:dots-vertical" %} menu.
2. Select the **Z-Wave** integration.
- Then, select the three dots {% icon "mdi:dots-vertical" %} menu.
3. From the dropdown menu, select **Download diagnostics**.
### How do I address interference issues?

167
source/_posts/2025-06-25-voice-chapter-10.markdown Normal file
View File

@ -0,0 +1,167 @@
---
layout: post
title: "Next iteration of our Voice Assistant is here - Voice chapter 10"
description: "This new tool brings fast, local speech processing to low-end hardware, along with some useful new voice and AI features"
date: 2025-06-25 00:00:01
date_formatted: "June 25, 2025"
author: Mike Hansen
comments: true
categories: Assist
og_image: /images/blog/2025-06-voice-chapter-10/art.png
---
<img src='/images/blog/2025-06-voice-chapter-10/art.png' style='border: 0;box-shadow: none;' alt="Chapter 10 of our ongoing voice series">
Welcome to Voice chapter 10 🎉, [a series](/blog/categories/assist/) where we share all the key developments in Open Voice. This chapter includes improvements across every element of Open Voice. Improvements that allow it to support more languages, be used on more hardware, make it easier to contribute to, all while making it faster and more reliable.
## Help steer Open Voice
Before we get going, we just want to say that Voice Chapter 10 isn't just a broadcast; **it's an invitation** ✉️. Our **public Voice project board** lives on GitHub, and it shows what we're fixing, currently building, and what we'll work on next. Every card is open for comments, so please feel free to have a look and participate in the discussion.
👉 **Project board**: [https://github.com/orgs/OHF-Voice/projects/2](https://github.com/orgs/OHF-Voice/projects/2)<!--more-->
## ESPHome gains a voice
When we began designing and building the firmware for our open voice assistant hardware, the [Home Assistant Voice Preview Edition](/voice-pe/), we had several specific features in mind:
1. Run wake words on the device.
2. Use a fully open-sourced media player platform that can decode music from high-quality sources.
3. Wake words can be enabled and disabled on the fly; for example, "stop" is only activated when a long-running announcement is playing or when a timer is ringing.
4. Mix voice assistant announcements on top of reduced volume (a.k.a. "ducked") music.
These features needed to run within ESPHome, the software that powers the device. In the beginning, ESPHome could only do 1 and 2, but not even at the same time!
To include all these features, we initially built them as external components, allowing us to iterate fast (and of course break many things along the way). We always intended to bring these components into ESPHome, and the process of bringing them in is called *upstreaming*. This would allow anyone to easily build a voice assistant that includes all the features of Voice Preview Edition, and that's what we've been working on since its launch last December.
<p class="img"><img src='/images/blog/2025-06-voice-chapter-10/devices.jpg' alt="S3 Box 3 next to Voice Preview Edition"/>No device left behind!</p>
ESPHome version 2025.5.0 has all these components included!  We didn't just spend this time copying the code over, but we also worked hard to improve it by making it more generalizable, easier to configure, and much faster.
As an example of these speed improvements, the highest CPU load on the Voice Preview Edition happens when music is being mixed with a long announcement. In this situation, it is decoding two different FLAC audio streams while also running three microWakeWord models (a Voice Activity Detector, "Okay Nabu", and "Stop"). With the original December firmware, this used 72% of the CPU 😅. With the new optimizations, which are all now available in ESPHome, the current Voice Preview Edition firmware only uses 35%❗ These improvements even allow the extremely resource-constrained ATOM Echo to support many of these features, including media playback and continuing conversations.
## Make your own Voice Preview Edition
<p class="img"><img src='/images/blog/2025-06-voice-chapter-10/circuits.png' alt="Circuit schematics to help display how components work together"/>I'll just pretend I understand all this</p>
Speaking of voice hardware becoming more like Voice Preview Edition, why not use that class-leading hardware as the basis for your own creations? We've now got the KiCad project files, which include the electrical schematic and circuit board layout, along with other helpful documents [available for download on GitHub](https://github.com/NabuCasa/home-assistant-voice-pe). Combined with our open source firmware files, this will allow anyone to build on the work we've done and make the open voice assistant of their dreams. Bigger speaker, built-in presence sensor, a display featuring a smiling Nabu mascot --- the options are nearly endless. Building Voice Preview Edition was always meant to bootstrap an entire ecosystem of voice hardware, and we're already seeing some amazing creations with this open technology.
## Now you're speaking my language
### Speech-to-Phrase gets more fluent
[In case you missed it](/blog/2025/02/13/voice-chapter-9-speech-to-phrase/#voice-for-the-masses), we built our own locally run speech-to-text (STT) tool that can run fast even on hardware-constrained devices. [Speech-to-Phrase](https://github.com/OHF-Voice/speech-to-phrase) works slightly differently from other STT tools, as it only accepts specific predetermined phrases, hence the name. We have been making large strides in making this the best option for local and private voice control in the home.
The sentence format for Speech-to-Phrase is getting an upgrade! Besides making it simpler for community members to contribute, it now allows for more thorough testing to ensure compatibility with existing Home Assistant commands.
We have also begun experimenting with more precise sentence generation, restricting sentences like "set the {light} to red" only to lights that support setting color. Another improvement is making Speech-to-Phrase more careful about combining names and articles in certain languages. For instance, in French, a device or entity that starts with a vowel or an "h" will have an "l" apostrophe at its beginning, such as l'humidificateur or l'entrée. Allowing Speech-to-Phrase to understand this avoids it guessing pronunciations for nonsensical combinations.
Speech-to-Phrase currently supports **six languages**, namely English, French, German, Dutch, Spanish, and Italian. We are now engaging with language leaders to add support for Russian, Czech, Catalan, Greek, Romanian, Portuguese, Polish, Hindi, Basque, Finnish, Mongolian, Slovenian, Swahili, Thai, and Turkish --- this takes our language support to **21 languages** 🥳!
These new models were originally trained by community members from the [Coqui STT](https://github.com/coqui-ai/STT-models) project (which is now defunct, but luckily their work was open source --- *another example of FOSS saving the day*), and we are very grateful for the chance to use them! Performance and accuracy vary heavily by language, and we may need to train our own models based on feedback from our community.
### Piper is growing in volume
[Piper](https://github.com/OHF-Voice/piper1-gpl) is another tool we built for local and private voice in the home, and it quickly turns text into natural-sounding speech. Piper is becoming one of the most comprehensive open source text-to-speech options available and has really been building momentum. Recently, we have added support for new languages and provided additional voices for existing ones, including,
- **Dutch** - Pim and Ronnie - *new voices*
- **Portuguese (Brazilian)** - Cadu and Jeff - *new voices*
- **Persian/Farsi** - Reza_ibrahim and Ganji - *new language*
- **Welsh** - Bu_tts - *new voices*
- **Swedish** - Lisa - *new voices*
- **Malayalam** - Arjun and Meera - *new language*
- **Nepali** - Chitwan - *new voices*
- **Latvian** - aivar- *new voices*
- **Slovenian** - artur - *new voices*
- **Slovak** - lili - *new voices*
- **English** - Sam (non-binary) and Reza_ibrahim - *new voices*
This brings Piper's supported languages and dialects from 34 to now 39 🙌! This allows a nice majority of the world's population (give or take 3 billion people) the ability to generate speech in their native tongue 😎!
### Scoring language support
<p class="img"><img src='/images/blog/2025-06-voice-chapter-10/intents.png' alt="Scoring table of our supported intents by language"/>This is the score sheet for just intents... it can get complicated</p>
Home Assistant users, when starting their voice journey, typically ask one question first: "Is my language supported?" Due to how flexible voice assistants in Home Assistant are, this seemingly simple question is quite complicated to answer! At a high level, a voice assistant needs to convert your spoken audio into text (speech-to-text), figure out what you want it to do (intent recognition), and then respond back to you (text-to-speech). Each part of this pipeline can be mixed and matched, and intent recognition can even be augmented with a fallback to a large language model (LLM), which is great at untangling misunderstood words or complex queries.
Considering the whole pipeline, the question "Is my language supported?" becomes "How well does each part support my language?" For Home Assistant Cloud, which uses Microsoft Azure for voice services, we can be confident that all supported languages work well.
Local options like [Whisper](https://github.com/openai/whisper) (speech-to-text) and, to a lesser extent, Piper (text-to-speech), may technically support a language but perform poorly in practice or within the limits of a user's hardware. Whisper, for example, has models with different sizes that require more powerful hardware to run as they get larger. A language like French may work well enough with the largest Whisper model (which requires a GPU), but is unusable on a Raspberry Pi or even an N100-class PC.
Our own Speech-to-Phrase system supports French well and runs well on a Raspberry Pi 4 or [Home Assistant Green](/green/). The trade-off is that only a limited set of pre-defined voice commands are supported, so you can't use an LLM as a fallback (because unexpected commands can't be converted into text for the LLM to process).
Finally, of course, not everyone wants to (or can) be reliant on the cloud, and they need a fully local voice assistant. This means that language support depends as much on the user's preferences as their hardware and the available voice services. For these reasons, we have split out language support into three categories based on specific combinations of services:
- ***Cloud*** - Home Assistant Cloud
- ***Focused Local*** - Speech-to-Phrase and Piper
- ***Full Local*** - Whisper and Piper
Each category is given a score from 0 to 3, with 0 meaning it is unsupported and 3 meaning it is fully supported. Users who choose Home Assistant Cloud can look at the Cloud score to determine the level of language support. For users wanting a local voice assistant, they will need to decide between Focused Local (limited commands for low-powered hardware) and Fully Local (open-ended commands for high-powered hardware). Importantly, these scores take into account the availability of voice commands translated by our language leaders. A language's score in every category will be lowered if it has minimal coverage of useful voice commands.
With these language scores, we hope users will be able to make informed decisions when starting on their voice journeys in Home Assistant. They're currently featured in our voice setup wizard in Home Assistant, and on our [language support page](/voice_control/#supported-languages-and-sentences).
## What's in a name
Voice commands in Home Assistant trigger *intents*, which are flexible actions that use names instead of IDs. Intents handle things like turning devices on or off, or adjusting the color of lights. Until now, sentence translations focused on whether a language supported an intent (like turning devices on/off) but didn't clearly show whether the command supported device names, areas names, or both. This can change from language to language, which made gaps hard to spot. We're switching to a new format that highlights these combinations, making it easier for contributors to see what names are supported, which should make for simpler translations.
## Continued conversation updates
Since the last voice chapter, the voice team has worked on making Assist more conversational for LLM-based agents. We started with LLM-based agents because it was simpler to iterate on. If the LLM returns with a question, we will detect that and keep the conversation going, without the need for you to say "Ok Nabu" again.
On top of that, you can now initiate a conversation with a new action called `start_conversation` directly from an automation, or a dashboard. This provides the full spectrum of conversation to LLM-based agents.
Here is a quick demonstration of two features working hand-in-hand:
<lite-youtube videoid="dq7--T_pVNA" videotitle="Continued conversations demo"></lite-youtube>
## Media Search and Play intent
What's great about Home Assistant and open source is that sometimes the best ideas come from other projects in the community. Early on, many people were interested in driving Music Assistant with voice, but central pieces were missing on Home Assistant, such as the ability to search a media library.
We worked hard on bringing this functionality to the core experience of Home Assistant and created a new intent, the **Search and Play** intent. You can now speak to your voice assistant and ask it to play music in any room in your home.
<lite-youtube videoid="bPMXz2nI-6w" videotitle="Media search and play demo"></lite-youtube>
The intent can be used by an LLM-based conversation agent, but we also have sentences that work without any LLM magic. You can find the [English sentences here](https://github.com/OHF-Voice/intents/tree/main/sentences/en/HassMediaSearchAndPlay). As it's a new feature, support may vary based on your language, and please be patient while our amazing language leaders make these translations.
## Future work - Assist will have something to say
Talking to your home should feel as natural as chatting with a friend across the kitchen counter. Large-language models (LLMs) already prove how smooth that back-and-forth can be, now we want every Home Assistant installation to enjoy the same experience. We're therefore zeroing in on three key use-cases for the default conversation agent, which include critical confirmations, follow-ups, and custom conversations. Just note these are still at the early stages of development and it may be some time before you see some of these features.
### Critical confirmations
Some actions are too important to execute without a quick double-check. Unlocking the front door, closing shutters, or running a "leaving home" script. We want you to be able to mark those entities as **protected**. Whenever you speak a command that touches one of those entities, Assist will ask for verbal confirmation before acting:
<blockquote style="font-style: normal;">
Ok Nabu, unlock the front door<br>
<i>Are you sure?</i><br>
Yes<br>
<i>Unlocked</i>
</blockquote>
Because every household is different, we are thinking about managing these confirmations **per entity** and making them fully user-configurable.
### Follow-up on missing parameters
Sometimes Assist grasps what you want, but needs more detail to carry it out. Instead of failing, we want Assist to ask for the missing piece proactively. Here is an example to illustrate.
<blockquote style="font-style: normal;">
Ok Nabu, set a timer<br>
<i>For how long?</i><br>
15 minutes<br>
<i>Timer started</i>
</blockquote>
For now, we are still assessing the relevant sentences for that use case. We're implementing follow-ups with timers, though finding more is not currently our top priority. We are, however, open to suggestions.
### Custom conversations
As with any other part of Home Assistant, we want the conversation aspect of Assist to be personalized. Simple voice transactions can already be created with our automation engine using the `conversation` trigger and the `set_conversation_response` action.
We want to bring the same level of customization to conversations, allowing you to create fully local, predefined conversations to be triggered whenever you need them, such as when you enter a room, start your bedtime routine, etc.
We are focusing first on making custom conversations possible, so that you can show us what you are building with this new powerful tool. We will then tackle the critical confirmations use case, and finally, the follow-ups when parameters are missing.
## Let's keep moving Open Voice forward
Only a couple of years ago, voice control was the domain of data-hungry corporations, and basically none of this open technology existed. Now, as a community, we've built all the parts needed to have a highly functional voice assistant, which is completely open and free for anyone to use (or even build on top of).\
Every chapter, we make steady progress, which is only possible with your support. Whether from those who fund its development by supporting the Open Home Foundation (by subscribing to [Home Assistant Cloud](/cloud/), and buying [official Home Assistant hardware](/voice-pe/)) or those who contribute their time to improving it. As always, we want to support every language possible, and if you don't see your native tongue on our supported list, please consider [contributing to this project](/voice_control/contribute-voice).

85
source/_posts/2025-06-26-switchbot-joins-works-with-home-assistant.markdown Normal file
View File

@ -0,0 +1,85 @@
---
layout: post
title: "SwitchBot joins Works with Home Assistant"
description: "The first air purifiers and cleaning robots join the program, with options for Matter and Bluetooth connectivity."
date: 2025-06-26 00:00:01
date_formatted: "June 26, 2025"
author: Miranda Bishop
comments: true
categories: Works-with-Home-Assistant
og_image: /images/blog/2025-06-switchbot/art.jpg
---
<img src='/images/blog/2025-06-switchbot/art.jpg' style='border: 0;box-shadow: none;' alt="SwitchBot Joins Works with Home Assistant">
Please welcome the latest addition to the [Works with Home Assistant](https://works-with.home-assistant.io/) program, [SwitchBot!](https://www.switch-bot.com/) This year has seen a lot of 'firsts' within the program, and this launch certainly keeps up this trend. Read on to see the first *Air Purifiers* and *Vacuums / Cleaning Robots*! What's more, SwitchBot is bringing this first set of devices into the program with multiple connectivity options. Pick from their [Bluetooth integration](/integrations/switchbot/), Matter via a hub, or standalone Matter devices as well. All this gives you even more choice in how you set up your smart home, while providing the best experience with Home Assistant.<!--more-->
## Making the Switch...Bot
SwitchBot quickly gained traction in the smart home industry with their original finger bots, which sit over non-smart switches and physically press them down on your behalf. Since then, they've expanded to include many other smart home devices like curtain robots, hubs, air purifiers, and cleaning robots. We were excited to see these new products in person at CES earlier this year and meet up with their team.
SwitchBot even got involved with [Community Day](/blog/2025/06/24/community-day-2025-wrap-up/), hosting a meet-up in Shenzhen, China. We love that the 'Works with' partners show that they're passionate about engaging with our community, taking the partnership much further than just a label on a box.
<div class="alert">
<p>"At SwitchBot, we're committed to empowering users with seamless and intelligent home automation. By collaborating with Home Assistant's passionate, tech-savvy community, we're able to push boundaries and deliver more integrated, intuitive experiences. Together, we aim to expand what's possible, offering users greater flexibility to connect, control, optimize their homes, and to make it simple."</p>
<em style="text-align: right; display: block;">- Richard Mou - Co-Founder, SwitchBot</em>
</div>
## Devices
In case you didn't know, Works with Home Assistant differs from other certification programs as products are rigorously tested in-house to ensure they work seamlessly out of the box with Home Assistant. Any company joining also commits to providing long-term support and firmware updates while being a positive force in the Home Assistant community. Works with Home Assistant is operated by the [Open Home Foundation](https://www.openhomefoundation.org/), and the support of [Home Assistant Cloud](/cloud/) subscribers funds this work.
The SwitchBot team have put special focus on integrating specifically for Home Assistant and have been working hard on their [Bluetooth integration](/integrations/switchbot/). Though the community played a central role in the development of the integration, and SwitchBot is very thankful for this work, they took a more active role in its development.
One of the terms of the 'Works with' program is that Bluetooth devices must connect over an integration that is kept up to a certain code quality (we call this our ['Gold tier'](/docs/quality_scale/) on our quality scale). It also must be maintained by the manufacturers themselves, rather than overly relying on community members to do the hard work. This puts the responsibility on the shoulders of the manufacturers to make sure they're responding to bugs and keeping the integration up long term. If you’re interested in SwitchBot’s Bluetooth products but your Home Assistant system doesn’t have built-in Bluetooth, the easiest way to connect them is by using a [Bluetooth Proxy](/integrations/bluetooth/#remote-adapters-bluetooth-proxies).
If you prefer Matter, SwitchBot also has devices that are certified for use with one of their Matter hubs: either the [SwitchBot Hub 2](https://www.switch-bot.com/products/switchbot-hub-2) or the [Hub 3](https://www.switch-bot.com/products/switchbot-hub-3). There are also some that can work via Matter-over-WiFi as standalone devices. We are currently testing even more of SwitchBot’s Matter devices for the program.
**Bluetooth**
- [SwitchBot Lock Ultra](https://www.switch-bot.com/products/switchbot-lock-ultra)
- [SwitchBot Air Purifier](https://www.switch-bot.com/products/switchbot-air-purifier)
- [SwitchBot Air Purifier Table](https://www.switch-bot.com/products/switchbot-air-purifier-table)
- [SwitchBot Leak Detector](https://www.switch-bot.com/products/switchbot-water-leak-detector) - also works using Matter via a hub
- [SwitchBot Meter](https://www.switch-bot.com/products/switchbot-meter)  - also works using Matter via a hub 
- [SwitchBot Meter Pro](https://www.switch-bot.com/products/switchbot-meter-pro) - also works using Matter via a hub
- [SwitchBot Meter Pro CO2](https://www.switch-bot.com/products/switchbot-meter-pro-co2-monitor) - also works using Matter via a hub
- [SwitchBot Indoor/Outdoor Thermo-Hygrometer](https://www.switch-bot.com/products/switchbot-indoor-outdoor-thermo-hygrometer) - also works using Matter via a hub
- [SwitchBot Curtain 3](https://www.switch-bot.com/products/switchbot-curtain-3) - also works using Matter via a hub
- [SwitchBot Contact Sensor](https://www.switch-bot.com/products/contact-sensor) - also works using Matter via a hub
- [SwitchBot Roller Shade](https://www.switch-bot.com/products/switchbot-roller-shade) - also works using Matter via a hub
- [SwitchBot Lock Pro](https://www.switch-bot.com/products/switchbot-lock-pro) - also works using Matter via a hub
**Matter-Over-WiFi (standalone, without requiring a hub)**
- [SwitchBot Air Purifier](https://www.switch-bot.com/products/switchbot-air-purifier)
- [SwitchBot Air Purifier Table](https://www.switch-bot.com/products/switchbot-air-purifier-table)
- [SwitchBot Multitasking Robot K20 + Pro](https://www.switch-bot.com/products/switchbot-multitasking-household-robot-k20-pro)
***Note:*** *Home Assistant Container does not support Matter, and requires Home Assistant OS.*
## A smart home is a clean home
<p class='img'><img src='/images/blog/2025-06-switchbot/vacuum.jpg' style='border: 0;box-shadow: none;' alt="SwitchBot's cleaning robot with an air purifier">Eat your heart out Wall-E</p>
SwitchBot's K20 is the first cleaning robot in the Works with Home Assistant program as well as the world's first multi-tasking household robot. This wacky robot can be paired with lots of other items in the range, including the certified air purifiers, to make some really cool Home Assistant use cases. Just imagine, you're making some delicious dinner, but oh no, you've left a pan alone for too long and it starts to smell and burn. You could summon the K20 with an air purifier on top using the Home Assistant Voice Preview Edition. A few moments later, it's found its way to you and gets started on clearing the air in your kitchen. Plus, as these can both work via Matter, there's no need for cloud involvement. Some of the items also come with a table top so this device has some great applications for anyone with limited mobility.
## Bot to the future
These devices are the first certified items, but SwitchBot is working to get many more tested and fully feature-rich with Home Assistant. We're excited to keep expanding this list over time, but if you can't wait (and this work is only possible with the support of our [Home Assistant Cloud](/cloud/) subscribers), you can see the list of the other devices they are working on [here](https://www.switch-bot.com/pages/home-assistant).
## FAQs
***Q: If I have a device that is not listed under 'Works with Home Assistant' does this mean it's not supported?***
A: No! It just means that it hasn't gone through a testing schedule with our team or doesn't fit the requirements of the program. It might work fine and be added to our testing later down the road. Though it might only have limited functions that are being worked on, or use a connectivity type we don't currently test for in the program.
***Q: Ok, so what's the point of the Works with program?***
A: It highlights the devices we know work well with Home Assistant and the brands that make a long-term commitment to keeping support for these devices going. The certification agreement specifies that the devices must have full functionality within Home Assistant, operate locally without the need for cloud, and will continue to do so long-term.
***Q: How were these devices tested?***
A: The Bluetooth devices in this list were tested using a standard Home Assistant Green Hub, the SwitchBot Bluetooth Integration, a USB Bluetooth adapter, and an ESPHome Bluetooth Proxy. The Matter-over-WiFi devices were also tested with Home Assistant Green and our [certified Matter Integration](/integrations/matter/). If you have another hardware setup or integration, that is often not a problem, but we test against these as they are the most effective way for our team to certify within our ecosystem.
***Q: Will you be adding more SwitchBot devices to the program?***
A: Absolutely! SwitchBot has a quickly growing set of product lines that we're working to certify together, subject to the integrations fully covering all the functions.

BIN
source/images/blog/2025-06-switchbot/art.jpg Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 80 KiB

BIN
source/images/blog/2025-06-switchbot/vacuum.jpg Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 70 KiB

BIN
source/images/blog/2025-06-voice-chapter-10/art.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 168 KiB

BIN
source/images/blog/2025-06-voice-chapter-10/circuits.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 121 KiB

BIN
source/images/blog/2025-06-voice-chapter-10/devices.jpg Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 56 KiB

BIN
source/images/blog/2025-06-voice-chapter-10/intents.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 210 KiB

172
source/installation/index.html
View File

@ -13,7 +13,80 @@ toc: true
kinds of skill levels.
</p>
</div>
<h2>About installation methods</h2>
<p>
Home Assistant offers two different installation methods. Home Assistant Operating System is the recommended installation method.
</p>
<ul>
<li><b>Home Assistant Operating System</b>: An embedded,
minimalistic operating system designed to run the Home Assistant ecosystem
on single board computers (like the Home Assistant Green or a Raspberry Pi) or Virtual Machines. It
is the most convenient option in terms of installation and maintenance and it supports
{% term "add-ons" %}. Home Assistant Operating System is
the recommended installation method for most users.</li>
<li>
<b>Home Assistant Container:</b> Container-based installation of Home Assistant. You need to bring your own system (such as Linux) with container orchestration (like Docker), and manually handle updates. Home Assistant Container installations don’t have access to {% term "add-ons" %}.
</li>
</ul>
<div class="compare-installations">
<table>
<thead>
<tr>
<th></th>
<th>HA OS<sup>1</sup></th>
<th>Container<sup>1</sup></th>
</tr>
</thead>
<tbody>
<tr>
<td><a href="/docs/automation" target="_blank">Automations</a></td>
<td>{% icon "openmoji:check-mark" %}</td>
<td>{% icon "openmoji:check-mark" %}</td>
</tr>
<tr>
<td><a href="/dashboards" target="_blank">Dashboards</a></td>
<td>{% icon "openmoji:check-mark" %}</td>
<td>{% icon "openmoji:check-mark" %}</td>
</tr>
<tr>
<td><a href="/integrations" target="_blank">Integrations</a></td>
<td>{% icon "openmoji:check-mark" %}</td>
<td>{% icon "openmoji:check-mark" %}</td>
</tr>
<tr>
<td><a href="/addons" target="_blank">Add-ons</a></td>
<td>{% icon "openmoji:check-mark" %}</td>
<td>{% icon "openmoji:cross-mark" %}</td>
</tr>
<tr>
<td><a href="/docs/blueprint" target="_blank">Blueprints</a></td>
<td>{% icon "openmoji:check-mark" %}</td>
<td>{% icon "openmoji:check-mark" %}</td>
</tr>
<tr>
<td>
One-click updates
</td>
<td>{% icon "openmoji:check-mark" %}</td>
<td>{% icon "openmoji:cross-mark" %}</td>
</tr>
<tr>
<td><a href="/common-tasks/general/#backups" target="_blank">Backups</a></td>
<td>{% icon "openmoji:check-mark" %}</td>
<td>{% icon "openmoji:check-mark" %}</td>
</tr>
</table>
</div>
<sub
>1: Names are abbreviated. The full names of the installation methods are:
<ul>
<li style="margin-top: 0.4em">Home Assistant Operating System</li>
<li style="margin-top: 15px">Home Assistant Container</li>
</ul></sub
>
<p>
<div class="installations">
<span class="label easiest">Easiest</span>
@ -254,90 +327,6 @@ toc: true
<span class="label expert">Expert</span>
<h2>About installation methods</h2>
<p>
Home Assistant offers two different installation methods:
</p>
<ul>
<li><b>Home Assistant Operating System</b>: An embedded,
minimalistic operating system designed to run the Home Assistant ecosystem
on single board computers (like the Home Assistant Green or a Raspberry Pi) or Virtual Machines. It
is the most convenient option in terms of installation and maintenance and it supports
{% term "add-ons" %}. Home Assistant Operating System is
the recommended installation method for most users.</li>
<li>
<b>Home Assistant Container:</b>Container-based installation of Home Assistant. You need to bring your own system (such as Linux) with container orchestration (like Docker), and manually handle updates. Home Assistant Container installations don’t have access to {% term "add-ons" %}.
</li>
</ul>
<div class="compare-installations">
<table>
<th></th>
<th>HA OS<sup>1</sup></th>
<th>Container<sup>1</sup></th>
<tr>
<td><a href="/docs/automation" target="_blank">Automations</a></td>
<td>{% icon "openmoji:check-mark" %}</td>
<td>{% icon "openmoji:check-mark" %}</td>
</tr>
<tr>
<td><a href="/dashboards" target="_blank">Dashboards</a></td>
<td>{% icon "openmoji:check-mark" %}</td>
<td>{% icon "openmoji:check-mark" %}</td>
</tr>
<tr>
<td><a href="/integrations" target="_blank">Integrations</a></td>
<td>{% icon "openmoji:check-mark" %}</td>
<td>{% icon "openmoji:check-mark" %}</td>
</tr>
<tr>
<td><a href="/addons" target="_blank">Add-ons</a></td>
<td>{% icon "openmoji:check-mark" %}</td>
<td>{% icon "openmoji:cross-mark" %}</td>
</tr>
<tr>
<td><a href="/docs/blueprint" target="_blank">Blueprints</a></td>
<td>{% icon "openmoji:check-mark" %}</td>
<td>{% icon "openmoji:check-mark" %}</td>
</tr>
<tr>
<td>
One-click updates
</td>
<td>{% icon "openmoji:check-mark" %}</td>
<td>{% icon "openmoji:cross-mark" %}</td>
</tr>
<tr>
<td><a href="/common-tasks/general/#backups" target="_blank">Backups</a></td>
<td>{% icon "openmoji:check-mark" %}</td>
<td>{% icon "openmoji:check-mark" %}</td>
</tr>
</table>
</div>
<sub
>1: Names are abbreviated. The full names of the installation methods are:
<ul>
<li style="margin-top: 0.4em">Home Assistant Operating System</li>
<li style="margin-top: 15px">Home Assistant Container</li>
</ul></sub
>
<p>
</p>
<h3>Deprecated installation methods</h3>
<p>
Home Assistant used to offer two additional installation methods for advanced users: <b>{% term "Home Assistant Core" %}</b> and <b>{% term "Home Assistant Supervised" %}</b>. These two methods are now <a href="https://www.home-assistant.io/blog/2025/05/22/deprecating-core-and-supervised-installation-methods-and-32-bit-systems/">deprecated and no longer recommended for new users</a>.
</p>
<ul>
<li>
<b>Home Assistant Supervised:</b> Manual installation of the Supervisor.
</li>
<li>
<b>Home Assistant Core:</b> Manual installation using Python virtual
environment.
</li>
</ul>
<p></p>
<div class="installations-card">
<div class="material-card text">
<div class="content-container">
@ -521,3 +510,18 @@ toc: true
</div>
</div>
</div>
<h3>Deprecated installation methods</h3>
<p>
Home Assistant used to offer two additional installation methods for advanced users: <b>{% term "Home Assistant Core" %}</b> and <b>{% term "Home Assistant Supervised" %}</b>. These two methods are now <a href="https://www.home-assistant.io/blog/2025/05/22/deprecating-core-and-supervised-installation-methods-and-32-bit-systems/">deprecated and no longer recommended for new users</a>.
</p>
<ul>
<li>
<b>Home Assistant Supervised:</b> Manual installation of the Supervisor.
</li>
<li>
<b>Home Assistant Core:</b> Manual installation using Python virtual
environment.
</li>
</ul>
<p></p>