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-29 12:17:01 +00:00
Code Issues Packages Projects Releases Wiki Activity

Merge branch 'next' of github.com:home-assistant/home-assistant.io into github-Adjust-wording

Browse Source
This commit is contained in:
Ludeeus 2022-02-04 18:02:47 +00:00
commit cb267f0b34
9 changed files with 315 additions and 50 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

5
source/_docs/mqtt/discovery.markdown
View File

@ -24,6 +24,7 @@ Supported by MQTT discovery:
- [Scenes](/integrations/scene.mqtt/)
- [Selects](/integrations/select.mqtt/)
- [Sensors](/integrations/sensor.mqtt/)
- [Sirens](/integrations/siren.mqtt/)
- [Switches](/integrations/switch.mqtt/)
- [Tag Scanners](/integrations/tag.mqtt/)
- [Vacuums](/integrations/vacuum.mqtt/)
@ -83,6 +84,7 @@ Supported abbreviations:
'aux_cmd_t': 'aux_command_topic',
'aux_stat_tpl': 'aux_state_template',
'aux_stat_t': 'aux_state_topic',
'av_tones': 'available_tones',
'avty' 'availability',
'avty_mode': 'availability_mode',
'avty_t': 'availability_topic',
@ -252,7 +254,10 @@ Supported abbreviations:
'stat_tpl': 'state_template',
'stat_val_tpl': 'state_value_template',
'stype': 'subtype',
'sup_duration': 'support_duration',
'sup_vol': 'support_volume_set',
'sup_feat': 'supported_features',
'sup_off': 'supported_turn_off',
'swing_mode_cmd_tpl': 'swing_mode_command_template',
'swing_mode_cmd_t': 'swing_mode_command_topic',
'swing_mode_stat_tpl': 'swing_mode_state_template',

4
source/_integrations/binary_sensor.mqtt.markdown
View File

@ -8,9 +8,9 @@ ha_iot_class: Configurable
ha_domain: mqtt
---
The `mqtt` binary sensor platform uses an MQTT message received to set the binary sensor's state to `on` or `off`.
The `mqtt` binary sensor platform uses an MQTT message received to set the binary sensor's state to `on`, `off` or `unknown`.
The state will be updated only after a new message is published on `state_topic` matching `payload_on` or `payload_off`. If these messages are published with the `retain` flag set,
The state will be updated only after a new message is published on `state_topic` matching `payload_on`, `payload_off` or `None`. If these messages are published with the `retain` flag set,
the binary sensor will receive an instant state update after subscription and Home Assistant will display the correct state on startup.
Otherwise, the initial state displayed in Home Assistant will be `unknown`.

4
source/_integrations/fan.mqtt.markdown
View File

@ -12,9 +12,9 @@ The `mqtt` fan platform lets you control your MQTT enabled fans.
## Configuration
In an ideal scenario, the MQTT device will have a `state_topic` to publish state changes. If these messages are published with a `RETAIN` flag, the MQTT fan will receive an instant state update after subscription and will start with the correct state. Otherwise, the initial state of the fan will be `false` / `off`.
In an ideal scenario, the MQTT device will have a `state_topic` to publish state changes. If these messages are published with a `RETAIN` flag, the MQTT fan will receive an instant state update after subscription and will start with the correct state. Otherwise, the initial state of the fan will be `unknown`. A MQTT device can reset the current state to `unknown` using a `None` payload.
When a `state_topic` is not available, the fan will work in optimistic mode. In this mode, the fan will immediately change state after every command. Otherwise, the fan will wait for state confirmation from the device (message from `state_topic`).
When a `state_topic` is not available, the fan will work in optimistic mode. In this mode, the fan will immediately change state after every command. Otherwise, the fan will wait for state confirmation from the device (message from `state_topic`). The initial state is set to `False` / `off` in optimistic mode.
Optimistic mode can be forced even if a `state_topic` is available. Try to enable it if you are experiencing incorrect fan operation.

6
source/_integrations/hue.markdown
View File

@ -6,12 +6,12 @@ ha_category:
- Light
ha_iot_class: Local Push
featured: true
ha_release: '0.60'
ha_release: "0.60"
ha_config_flow: true
ha_quality_scale: platinum
ha_codeowners:
- '@balloob'
- '@marcelveldt'
- "@balloob"
- "@marcelveldt"
ha_domain: hue
ha_ssdp: true
ha_homekit: true

4
source/_integrations/humidifier.mqtt.markdown
View File

@ -12,9 +12,9 @@ The `mqtt` humidifier platform lets you control your MQTT enabled humidifiers.
## Configuration
In an ideal scenario, the MQTT device will have a `state_topic` to publish state changes. If these messages are published with a `RETAIN` flag, the MQTT humidifier will receive an instant state update after subscription and will start with the correct state. Otherwise, the initial state of the humidifier will be `false` / `off`.
In an ideal scenario, the MQTT device will have a `state_topic` to publish state changes. If these messages are published with a `RETAIN` flag, the MQTT humidifier will receive an instant state update after subscription and will start with the correct state. Otherwise, the initial state of the humidifier will be `unknown`. A MQTT device can reset the current state to `unknown` using a `None` payload.
When a `state_topic` is not available, the humidifier will work in optimistic mode. In this mode, the humidifier will immediately change state after every command. Otherwise, the humidifier will wait for state confirmation from the device (message from `state_topic`).
When a `state_topic` is not available, the humidifier will work in optimistic mode. In this mode, the humidifier will immediately change state after every command. Otherwise, the humidifier will wait for state confirmation from the device (message from `state_topic`). The initial state is set to `False` / `off` in optimistic mode.
Optimistic mode can be forced even if a `state_topic` is available. Try to enable it if you are experiencing incorrect humidifier operation.

28
source/_integrations/light.mqtt.markdown
View File

@ -13,18 +13,18 @@ The `mqtt` light platform lets you control your MQTT enabled lights through one
## Comparison of light MQTT schemas
| Function | [`default`](#default-schema) | [`json`](#json-schema) | [`template`](#template-schema) |
|-------------------|------------------------------------------------------------|----------------------------------------------------------------------|------------------------------------------------------------------------------|
| Brightness | ✔ | ✔ | ✔ |
| Color mode | ✔ | ✔ | ✘ |
| Color temperature | ✔ | ✔ | ✔ |
| Effects | ✔ | ✔ | ✔ |
| Flashing | ✘ | ✔ | ✔ |
| HS Color | ✔ | ✔ | ✔ |
| RGB Color | ✔ | ✔ | ✔ |
| RGBW Color | ✔ | ✔ | ✘ |
| RGBWW Color | ✔ | ✔ | ✘ |
| Transitions | ✘ | ✔ | ✔ |
| XY Color | ✔ | ✔ | ✘ |
| ----------------- | ---------------------------- | ---------------------- | ------------------------------ |
| Brightness | ✔ | ✔ | ✔ |
| Color mode | ✔ | ✔ | ✘ |
| Color temperature | ✔ | ✔ | ✔ |
| Effects | ✔ | ✔ | ✔ |
| Flashing | ✘ | ✔ | ✔ |
| HS Color | ✔ | ✔ | ✔ |
| RGB Color | ✔ | ✔ | ✔ |
| RGBW Color | ✔ | ✔ | ✘ |
| RGBWW Color | ✔ | ✔ | ✘ |
| Transitions | ✘ | ✔ | ✔ |
| XY Color | ✔ | ✔ | ✘ |
## Default schema
@ -33,9 +33,9 @@ The `mqtt` light platform with default schema lets you control your MQTT enabled
## Default schema - Configuration
In an ideal scenario, the MQTT device will have a state topic to publish state changes. If these messages are published with a `RETAIN` flag, the MQTT light will receive an instant state update after subscription and will start with the correct state. Otherwise, the initial state of the switch will be `false` / `off`.
In an ideal scenario, the MQTT device will have a state topic to publish state changes. If these messages are published with a `RETAIN` flag, the MQTT light will receive an instant state update after subscription and will start with the correct state. Otherwise, the initial state of the switch will be `unknown`. A MQTT device can reset the current state to `unknown` using a `None` payload.
When a state topic is not available, the light will work in optimistic mode. In this mode, the light will immediately change state after every command. Otherwise, the light will wait for state confirmation from the device (message from `state_topic`).
When a state topic is not available, the light will work in optimistic mode. In this mode, the light will immediately change state after every command. Otherwise, the light will wait for state confirmation from the device (message from `state_topic`). The initial state is set to `False` / `off` in optimistic mode.
Optimistic mode can be forced, even if the `state_topic` is available. Try to enable it, if experiencing incorrect light operation.

12
source/_integrations/shelly.markdown
View File

@ -6,6 +6,7 @@ ha_category:
- Cover
- Energy
- Light
- Number
- Sensor
- Switch
ha_release: 0.115
@ -26,6 +27,7 @@ ha_platforms:
- climate
- cover
- light
- number
- sensor
- switch
---
@ -236,6 +238,16 @@ Trigger reboot of device.
- Reboot
- triggers the reboot
## Shelly Thermostatic Radiator Valve (TRV)
Shelly TRV generates 2 entities that can be used to control the device behavior: `climate` and `number`.
The first will allow specifying a temperature, the second instead of a percentage of the valve position.
**Note**: that if you change the valve position then automatic temperature control
will be disabled.
As soon as you change the temperature, it gets enabled again.
## CoAP port (generation 1)
In some cases, it may be needed to customize the CoAP port (default: `5683`) your Home Assistant instance is listening to.

273
source/_integrations/siren.mqtt.markdown Normal file
View File

@ -0,0 +1,273 @@
---
title: "MQTT Siren"
description: "Instructions on how to integrate MQTT sirens into Home Assistant."
ha_category:
- Siren
ha_release: 2022.3
ha_iot_class: Configurable
ha_domain: mqtt
---
The `mqtt` siren platform lets you control your MQTT enabled sirens and text based notification devices.
## Configuration
In an ideal scenario, the MQTT device will have a `state_topic` to publish state changes. If these messages are published with a `RETAIN` flag, the MQTT siren will receive an instant state update after subscription, and will start with the correct state. Otherwise, the initial state of the siren will be `false` / `off`.
When a `state_topic` is not available, the siren will work in optimistic mode. In this mode, the siren will immediately change state after every command. Otherwise, the siren will wait for state confirmation from the device (message from `state_topic`).
Optimistic mode can be forced, even if the `state_topic` is available. Try to enable it, if experiencing incorrect operation.
To enable this siren in your installation, add the following to your `configuration.yaml` file:
```yaml
# Example configuration.yaml entry
siren:
- platform: mqtt
command_topic: "home/bedroom/siren/set"
```
{% configuration %}
availability:
description: A list of MQTT topics subscribed to receive availability (online/offline) updates. Must not be used together with `availability_topic`.
required: false
type: list
keys:
payload_available:
description: The payload that represents the available state.
required: false
type: string
default: online
payload_not_available:
description: The payload that represents the unavailable state.
required: false
type: string
default: offline
topic:
description: An MQTT topic subscribed to receive availability (online/offline) updates.
required: true
type: string
value_template:
description: "Defines a [template](/docs/configuration/templating/#processing-incoming-data) to extract device's availability from the `topic`. To determine the devices's availability result of this template will be compared to `payload_available` and `payload_not_available`."
required: false
type: template
availability_mode:
description: When `availability` is configured, this controls the conditions needed to set the entity to `available`. Valid entries are `all`, `any`, and `latest`. If set to `all`, `payload_available` must be received on all configured availability topics before the entity is marked as online. If set to `any`, `payload_available` must be received on at least one configured availability topic before the entity is marked as online. If set to `latest`, the last `payload_available` or `payload_not_available` received on any configured availability topic controls the availability.
required: false
type: string
default: latest
availability_template:
description: "Defines a [template](/docs/configuration/templating/#processing-incoming-data) to extract device's availability from the `availability_topic`. To determine the devices's availability result of this template will be compared to `payload_available` and `payload_not_available`."
required: false
type: template
availability_topic:
description: The MQTT topic subscribed to receive availability (online/offline) updates. Must not be used together with `availability`.
required: false
type: string
available_tones:
description: A list of available tones the siren supports. When configured, this enables the support for setting a `tone` and enables the `tone` state attribute.
required: false
type: list
command_template:
description: Defines a [template](/docs/configuration/templating/#processing-incoming-data) to generate the payload to send to `command_topic`. The variable `value` will be assigned with the configured `payload_on` or `payload_off` setting. The siren turn on service parameters `tone`, `volume_level` or `duration` can be used as variables in the template. When operation in optimistic mode the corresponding state attributes will be set. Turn parameters will be filtered if a device misses the support.
required: false
type: template
command_off_template:
description: Defines a [template](/docs/configuration/templating/#processing-incoming-data) to generate the payload to send to `command_topic` when the siren turn off service is called. By default `command_template` will be used as template for service turn off. The variable `value` will be assigned with the configured `payload_off` setting.
required: false
type: template
command_topic:
description: The MQTT topic to publish commands to change the siren state. Without command template a JSON payload is published. When the siren turn on service is called, the startup parameters will be added to the JSON payload. The `state` value of the JSON payload will be set to the the `payload_on` or `payload_off` configured payload.
required: false
type: string
device:
description: "Information about the device this siren is a part of to tie it into the [device registry](https://developers.home-assistant.io/docs/en/device_registry_index.html). Only works through [MQTT discovery](/docs/mqtt/discovery/) and when [`unique_id`](#unique_id) is set. At least one of identifiers or connections must be present to identify the device."
required: false
type: map
keys:
configuration_url:
description: 'A link to the webpage that can manage the configuration of this device. Can be either an HTTP or HTTPS link.'
required: false
type: string
connections:
description: 'A list of connections of the device to the outside world as a list of tuples `[connection_type, connection_identifier]`. For example the MAC address of a network interface: `"connections": [["mac", "02:5b:26:a8:dc:12"]]`.'
required: false
type: list
identifiers:
description: A list of IDs that uniquely identify the device. For example a serial number.
required: false
type: [string, list]
manufacturer:
description: The manufacturer of the device.
required: false
type: string
model:
description: The model of the device.
required: false
type: string
name:
description: The name of the device.
required: false
type: string
suggested_area:
description: 'Suggest an area if the device isn’t in one yet.'
required: false
type: string
sw_version:
description: The firmware version of the device.
required: false
type: string
via_device:
description: 'Identifier of a device that routes messages between this device and Home Assistant. Examples of such devices are hubs, or parent devices of a sub-device. This is used to show device topology in Home Assistant.'
required: false
type: string
enabled_by_default:
description: Flag which defines if the entity should be enabled when first added.
required: false
type: boolean
default: true
encoding:
description: The encoding of the payloads received and published messages. Set to `""` to disable decoding of incoming payload.
required: false
type: string
default: "utf-8"
entity_category:
description: The [category](https://developers.home-assistant.io/docs/core/entity#generic-properties) of the entity.
required: false
type: string
default: None
icon:
description: "[Icon](/docs/configuration/customizing-devices/#icon) for the entity."
required: false
type: icon
json_attributes_template:
description: "Defines a [template](/docs/configuration/templating/#processing-incoming-data) to extract the JSON dictionary from messages received on the `json_attributes_topic`. Usage example can be found in [MQTT sensor](/integrations/sensor.mqtt/#json-attributes-template-configuration) documentation."
required: false
type: template
json_attributes_topic:
description: The MQTT topic subscribed to receive a JSON dictionary payload and then set as sensor attributes. Usage example can be found in [MQTT sensor](/integrations/sensor.mqtt/#json-attributes-topic-configuration) documentation.
required: false
type: string
name:
description: The name to use when displaying this siren.
required: false
type: string
default: MQTT Siren
object_id:
description: Used instead of `name` for automatic generation of `entity_id`
required: false
type: string
optimistic:
description: Flag that defines if siren works in optimistic mode.
required: false
type: boolean
default: "`true` if no `state_topic` defined, else `false`."
payload_available:
description: The payload that represents the available state.
required: false
type: string
default: online
payload_not_available:
description: The payload that represents the unavailable state.
required: false
type: string
default: offline
payload_off:
description: The payload that represents `off` state. If specified, will be used for both comparing to the value in the `state_topic` (see `value_template` and `state_off` for details) and sending as `off` command to the `command_topic`.
required: false
type: string
default: "OFF"
payload_on:
description: The payload that represents `on` state. If specified, will be used for both comparing to the value in the `state_topic` (see `value_template` and `state_on` for details) and sending as `on` command to the `command_topic`.
required: false
type: string
default: "ON"
qos:
description: The maximum QoS level of the state topic. Default is 0 and will also be used to publishing messages.
required: false
type: integer
default: 0
retain:
description: If the published message should have the retain flag on or not.
required: false
type: boolean
default: false
state_off:
description: The payload that represents the `off` state. Used when value that represents `off` state in the `state_topic` is different from value that should be sent to the `command_topic` to turn the device `off`.
required: false
type: string
default: "`payload_off` if defined, else `'OFF'`"
state_on:
description: The payload that represents the `on` state. Used when value that represents `on` state in the `state_topic` is different from value that should be sent to the `command_topic` to turn the device `on`.
required: false
type: string
default: "`payload_on` if defined, else `'ON'`"
state_topic:
description: "The MQTT topic subscribed to receive state updates. When a JSON payload is detected, the `state` value of the JSON payload should supply the `payload_on` or `payload_off` defined payload to turn the siren on or off. Additional the state attributes `duration`, `tone` and `volume_level` can be updated. Use `value_template` to update render custom payload to a compliant JSON payload. Attributes will only be set if the function is supported by the device and a valid value is supplied. The initial state will be `unknown`. The state will be reset to `unknown` if a `None` payload or `null` JSON value is received as a state update."
required: false
type: string
state_value_template:
description: "Defines a [template](/docs/configuration/templating/#processing-incoming-data) to extract device's state from the `state_topic`. To determine the siren's state result of this template will be compared to `state_on` and `state_off`. Alternatively `value_template` can be used to render to a valid JSON payload."
required: false
type: string
support_duration:
description: Set to `true` if the MQTT siren supports the `duration` service turn on parameter and enables the `duration` state attribute.
required: false
type: boolean
default: true
support_volume_set:
description: Set to `true` if the MQTT siren supports the `volume_set` service turn on parameter and enables the `volume_level` state attribute.
required: false
type: boolean
default: true
unique_id:
description: An ID that uniquely identifies this siren device. If two sirens have the same unique ID, Home Assistant will raise an exception.
required: false
type: string
{% endconfiguration %}
<div class='note warning'>
Make sure that your topic matches exactly. `some-topic/` and `some-topic` are different topics.
</div>
## Examples
In this section, you will find an example of how to use this siren platform.
### Full configuration
The example below shows a full configuration for a siren.
{% raw %}
```yaml
# Example configuration.yaml entry
siren:
- platform: mqtt
unique_id: custom_siren
name: "Intrusion siren"
state_topic: "home/alarm/siren1"
command_topic: "home/alarm/siren1/set"
available_tones:
- ping
- siren
availability:
- topic: "home/alarm/siren1/available"
payload_on: "ON"
payload_off: "OFF"
state_on: "ON"
state_off: "OFF"
optimistic: false
qos: 0
retain: true
```
{% endraw %}
For a check, you can use the command line tools `mosquitto_pub` shipped with `mosquitto` to send MQTT messages. This allows you to operate your siren manually:
```bash
mosquitto_pub -h 127.0.0.1 -t home/alarm/siren1 -m "ON"
```

29
source/_integrations/tradfri.markdown
View File

@ -23,34 +23,14 @@ ha_platforms:
The `tradfri` integration allows you to connect your IKEA Trådfri Gateway to Home Assistant. The gateway can control compatible Zigbee-based lights (certified Zigbee Light Link products) connected to it. Home Assistant will automatically discover the gateway's presence on your local network if `discovery:` is present in your `configuration.yaml` file.
{% include integrations/config_flow.md %}
You will be prompted to configure the gateway through the Home Assistant interface. The configuration process is very simple: when prompted, enter the security key printed on the sticker on the bottom of the IKEA Trådfri Gateway, then click *configure*.
<div class='note'>
If you see an "Unable to connect" message, restart the gateway and try again. Don't forget to assign a permanent IP address to your IKEA Trådfri Gateway on your router or DHCP server.
</div>
## Configuration
You can add the following to your `configuration.yaml` file if you are not using the [`discovery:`](/integrations/discovery/) component:
```yaml
# Example configuration.yaml entry
tradfri:
host: IP_ADDRESS
```
{% configuration %}
host:
description: "The IP address or hostname of your IKEA Trådfri Gateway."
required: true
type: string
allow_tradfri_groups:
description: "Set this to `true` to allow Home Assistant to import the groups defined on the IKEA Trådfri Gateway."
required: false
type: boolean
default: false
{% endconfiguration %}
## Troubleshooting
### Incorrect security key
@ -61,7 +41,6 @@ allow_tradfri_groups:
After updating your IKEA Trådfri Gateway firmware it might be necessary to repeat the configuration process. One error you might experience after a firmware update is `Fatal DTLS error: code 115`. If you encounter problems:
- when configured using the integration: remove the integration through Settings > Integrations > Tradfri > delete (trash can icon)
- with manual configuration: delete the `.tradfri_psk.conf` file in your `/config` directory (`/.homeassistant` directory if using Home Assistant Core)
Then restart Home Assistant. When prompted, enter the security key and click *configure*, just like during initial setup.
@ -73,10 +52,6 @@ Then restart Home Assistant. When prompted, enter the security key and click *co
Please make sure you have `autoconf` installed (`$ sudo apt-get install autoconf`) if you want to use this component. Also, installing some dependencies might take considerable time (more than one hour) on slow devices.
### Setting the `api_key`
Do not use the `api_key` variable in `configuration.yaml`. The API key is only needed once at initial setup and will be stored.
## Known limitations
- The TRÅDFRI Shortcut button, Remotes and motion sensor only send information about their battery status, no events, to Home Assistant and thus can't be used to automate with. If you want to automate with these devices, you need to use something like [ZHA](/integrations/zha/).