From 3ef463102ae22f98e9ca0966aa0fe07361e621f5 Mon Sep 17 00:00:00 2001 From: Tathar Date: Thu, 27 Jan 2022 11:03:21 +0100 Subject: [PATCH 01/13] three litle bug in modbus doc (#21356) --- source/_integrations/modbus.markdown | 11 +++++------ 1 file changed, 5 insertions(+), 6 deletions(-) diff --git a/source/_integrations/modbus.markdown b/source/_integrations/modbus.markdown index f259ac0eb38..64369d6e597 100644 --- a/source/_integrations/modbus.markdown +++ b/source/_integrations/modbus.markdown @@ -483,7 +483,6 @@ modbus: device_class: door input_type: coil address: 117 - device_class: door state_open: 1 state_opening: 2 state_closed: 0 @@ -491,7 +490,7 @@ modbus: status_register: 119 status_register_type: holding - name: "Door2" - address: 117 + address: 118 ``` {% configuration %} @@ -1033,10 +1032,10 @@ switches: required: false default: same as command_off type: integer - unique_id: - description: An ID that uniquely identifies this sensor. If two sensors have the same unique ID, Home Assistant will raise an exception. - required: false - type: string + unique_id: + description: An ID that uniquely identifies this sensor. If two sensors have the same unique ID, Home Assistant will raise an exception. + required: false + type: string {% endconfiguration %} ## Opening an issue From 1dfdfe63f1773b76eb7ad5db428d37c9c4c511bc Mon Sep 17 00:00:00 2001 From: Simon Hansen <67142049+DurgNomis-drol@users.noreply.github.com> Date: Fri, 28 Jan 2022 10:52:11 +0100 Subject: [PATCH 02/13] Add a note about starship sensors to launchlibrary (#21358) --- source/_integrations/launch_library.markdown | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/_integrations/launch_library.markdown b/source/_integrations/launch_library.markdown index 41afe10ae53..d9f5b280131 100644 --- a/source/_integrations/launch_library.markdown +++ b/source/_integrations/launch_library.markdown @@ -13,7 +13,7 @@ ha_platforms: - sensor --- -The `launch_library` sensor will provide you with information about the next planned space launch. +The `launch_library` sensor will provide you with information about the next planned space launch and SpaceX Starship event. {% include integrations/config_flow.md %} From 8628e105b1210d1edd96a28655bdfdd196582025 Mon Sep 17 00:00:00 2001 From: Christopher Masto Date: Fri, 28 Jan 2022 14:31:12 -0500 Subject: [PATCH 03/13] Update list of tested devices (#21368) --- source/_integrations/oncue.markdown | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/source/_integrations/oncue.markdown b/source/_integrations/oncue.markdown index 79d1feab126..c141cd59653 100644 --- a/source/_integrations/oncue.markdown +++ b/source/_integrations/oncue.markdown @@ -17,8 +17,9 @@ ha_platforms: The Oncue by Kohler integration will allow you to monitor the state of your [Oncue enabled Kohler generator](https://api.kohler.com/oncueplus/#/auth). -## Supported Devices +## Tested Devices +- [24RCL](https://kohlerpower.com/en/residential/generators/product/24rcl) - [38RCLB](https://kohlerpower.com/en/residential/generators/product/38rclb) - [48RCLB](https://kohlerpower.com/en/residential/generators/product/48rclb) - [60RCLA](https://kohlerpower.com/en/residential/generators/product/60rcla) From d7cbfef9923656ab25f50404852de57b38e723db Mon Sep 17 00:00:00 2001 From: Patrik Lindgren <21142447+ggravlingen@users.noreply.github.com> Date: Sun, 30 Jan 2022 22:47:38 +0100 Subject: [PATCH 04/13] Remove reference to tradfri groups and manual configuration (#21403) Co-authored-by: Martin Hjelmare --- source/_integrations/tradfri.markdown | 29 ++------------------------- 1 file changed, 2 insertions(+), 27 deletions(-) diff --git a/source/_integrations/tradfri.markdown b/source/_integrations/tradfri.markdown index 522d0e78c79..c314b391abd 100644 --- a/source/_integrations/tradfri.markdown +++ b/source/_integrations/tradfri.markdown @@ -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*.
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.
-## 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/). From 2e3c56f986934f225e0dcb2a4a6b4dd146d7b76b Mon Sep 17 00:00:00 2001 From: Dave T <17680170+davet2001@users.noreply.github.com> Date: Mon, 31 Jan 2022 10:36:35 +0000 Subject: [PATCH 05/13] Add instructions for SALUS device OTA upgrade (#21384) --- source/_integrations/zha.markdown | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/source/_integrations/zha.markdown b/source/_integrations/zha.markdown index 8c14b2c5b0f..2139bcae312 100644 --- a/source/_integrations/zha.markdown +++ b/source/_integrations/zha.markdown @@ -206,7 +206,7 @@ custom_quirks_path: ZHA component has the ability to automatically download and perform OTA (Over-The-Air) firmware updates of Zigbee devices if the OTA firmware provider source URL for updates is available. OTA firmware updating is set to disabled (`false`) in the configuration by default. -Currently, OTA providers for firmware updates are only available for IKEA and LEDVANCE devices. OTA updates for device of other manufactures could also be supported by ZHA dependencies in the future, if these manufacturers publish their firmware publicly. +Online OTA providers for firmware updates are currently only available for IKEA, LEDVANCE and SALUS devices. Support for OTA updates from other manufacturers could be supported in the future, if they publish their firmware images publicly. To enable OTA firmware updates for the ZHA integration you need to add the following configuration to your `configuration.yaml` and restart Home Assistant: @@ -216,10 +216,11 @@ zha: ota: ikea_provider: true # Auto update Trådfri devices ledvance_provider: true # Auto update LEDVANCE devices + salus_provider: true # Auto update SALUS devices #otau_directory: /path/to/your/ota/folder # Utilize .ota files to update everything else ``` -You can choose if the IKEA or LEDVANCE provider should be set to enabled (`true`) or disabled (`false`) individually. After the OTA firmware upgrades are finished, you can set these to `false` again if you do not want ZHA to automatically download and perform OTA firmware upgrades in the future. +You can choose if the IKEA, LEDVANCE or SALUS provider should be set to enabled (`true`) or disabled (`false`) individually. After the OTA firmware upgrades are finished, you can set these to `false` again if you do not want ZHA to automatically download and perform OTA firmware upgrades in the future. Note that the `otau_directory` setting is optional and can be used for any firmware files you have downloaded yourself, for any device type and manufacturer. For example, Philips Hue firmwares manually downloaded from [here](https://github.com/dresden-elektronik/deconz-rest-plugin/wiki/OTA-Image-Types---Firmware-versions) and/or [here](https://github.com/Koenkk/zigbee-OTA/blob/a02a4cb33f7c46b4d2916805bfcad582124ec975/index.json) added to the `otau_directory` can be flashed, although a manual `zha.issue_zigbee_cluster_command` command currently (as of 2021.3.3) must be issued against the IEEE of the Philips Hue device under Developer Tools->Services, e.g.: From 4caf8cd0f985352a345963152ad9e2b0d8ba8a82 Mon Sep 17 00:00:00 2001 From: "J. Nick Koston" Date: Mon, 31 Jan 2022 04:43:29 -0600 Subject: [PATCH 06/13] Add dhcp discovery to oncue (#21386) --- source/_integrations/oncue.markdown | 1 + 1 file changed, 1 insertion(+) diff --git a/source/_integrations/oncue.markdown b/source/_integrations/oncue.markdown index c141cd59653..cebe209b133 100644 --- a/source/_integrations/oncue.markdown +++ b/source/_integrations/oncue.markdown @@ -9,6 +9,7 @@ ha_release: 2022.2 ha_config_flow: true ha_codeowners: - '@bdraco' +ha_dhcp: true ha_domain: oncue ha_platforms: - binary_sensor From 69abae8b9f8d4e7bb2bd91700699c833d65a50fa Mon Sep 17 00:00:00 2001 From: Simone Chemelli Date: Mon, 31 Jan 2022 22:18:08 +0100 Subject: [PATCH 07/13] Add info on management for Shelly Valve (#21266) * Add info on number platform for Shelly Valve * Tweaks Co-authored-by: Franck Nijhof --- source/_integrations/shelly.markdown | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/source/_integrations/shelly.markdown b/source/_integrations/shelly.markdown index 1f79b32e213..19534242b40 100644 --- a/source/_integrations/shelly.markdown +++ b/source/_integrations/shelly.markdown @@ -6,6 +6,7 @@ ha_category: - Cover - Energy - Light + - Number - Sensor - Switch ha_release: 0.115 @@ -25,6 +26,7 @@ ha_platforms: - climate - cover - light + - number - sensor - switch --- @@ -235,6 +237,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. From b4d3de2eb966ab3e39d48d8d1a7e374c7606b32f Mon Sep 17 00:00:00 2001 From: Jan Bouwhuis Date: Mon, 31 Jan 2022 22:51:48 +0100 Subject: [PATCH 08/13] Mqtt binary sensor allow processing unavailable state (#21388) --- source/_integrations/binary_sensor.mqtt.markdown | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/source/_integrations/binary_sensor.mqtt.markdown b/source/_integrations/binary_sensor.mqtt.markdown index ef9b3d92de8..2ce84fdea51 100644 --- a/source/_integrations/binary_sensor.mqtt.markdown +++ b/source/_integrations/binary_sensor.mqtt.markdown @@ -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`. From ce8a4394a12f065d5860203025eb888cb7d9003f Mon Sep 17 00:00:00 2001 From: Marcel van der Veldt Date: Tue, 1 Feb 2022 16:13:08 +0100 Subject: [PATCH 09/13] Update Hue docs (#21339) Co-authored-by: Franck Nijhof --- source/_integrations/hue.markdown | 31 ++++++++++++++++++++++++++----- 1 file changed, 26 insertions(+), 5 deletions(-) diff --git a/source/_integrations/hue.markdown b/source/_integrations/hue.markdown index 95c56b490d5..6c7ea5eedb1 100644 --- a/source/_integrations/hue.markdown +++ b/source/_integrations/hue.markdown @@ -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 @@ -36,20 +36,41 @@ There is currently support for the following device types within Home Assistant: ## Lights for Hue zones and rooms -The Hue concept is based on Rooms and zones. Although the underlying Hue lights are exposed directly to Home Assistant it might also be useful to interact with the `grouped lights` of the Hue ecosystem, for example to turn all lights in a Hue group on/off at the same time. +The Hue concept is based on Rooms and Zones. Although the underlying Hue lights are exposed directly to Home Assistant it might also be useful to interact with the `grouped lights` of the Hue ecosystem, for example to turn all lights in a Hue group on/off at the same time. Home Assistant creates lights for each Hue zone/room automatically but disables them by default. If you'd like to use those `grouped lights`, you can enable them from Configuration --> Integrations --> Hue --> entities. ## Scenes -In the Hue concept you can create (dynamic) scenes for the lights within rooms and zones. These Hue scenes are automatically imported in Home Assistant and available as scene entities. Creating or editing Hue scenes in Home Assistant is not supported. +In the Hue concept you can create (dynamic) scenes for the lights within rooms and zones. You can create, edit and delete Hue scenes from the (official) Hue app on iOS and Android. Each Zone/Room can have it's own scenes assigned and there is a large library of precreated scenes for specific moods. These Hue scenes are automatically imported in Home Assistant and they're available as `scene entities`. Creating or editing Hue scenes in Home Assistant is not supported. +It is advised to use Hue scenes for controlling multiple lights at once for a smooth experience. If you individually control multiple lights and/or use Home Assistant scenes, each light command will be sent to each light one by one which doesn't give a very good user experience, while using a Hue scene sends commands to all lights at once in an optimized way, resulting in a smooth experience. + +### Service `hue.activate_scene` + +To have more control over Hue scenes we've implemented a secondary, more advanced service to activate a Hue scene and set some properties at the same time, such as the Dynamic mode and/or brightness. + +| Service Data Attribute | Required | Description | +| ---------------------- | -------- | --------------------------------------------------------------------------------------------- | +| `entity_id` | yes | Entity ID of the Hue Scene entity you want to activate. | +| `transition` | no | Transition duration (in seconds) it takes to bring devices to the state defined in the scene. | +| `dynamic` | no | Enable (true) or Disable (false) dynamic mode for the scene. | +| `speed` | no | Set the speed (of the dynamic palette) for this scene. | +| `brightness` | no | Set the brightnes for this scene. | + +You can use this service for example if you'd like to start/stop Dynamic Mode. ## Hue remotes and switches Hue remotes such as the Dimmer Switch are stateless devices, meaning that they do not have a on/off state like regular entities in Home Assistant. Instead, such devices emit the event `hue_event` when a button is pressed. You can test what events come in using the event {% my developer_events title="developer tools in Home Assistant" %} and subscribe to the `hue_event`. Once you know what the event data looks like, you can use this to create automations. +
+ +At the time of writing, there's a limitation on the Hue API that each device can only send one event per second. This means that button events are rate-limited to 1 per second. This is brought to the attention of Signify and it will hopefully be fixed soon. + +
+ ## Support for legacy (V1) Hue bridges Philips/Signify released a new version of their Hue bridge (square shape) and their legacy/V1 bridge (round shape) is now end of life and no longer supported by them. Home Assistant will continue to support the V1 Hue bridge as long as it is technically possible, although with a few limitations: From 55f2d5f57d2a5ea8e47cedcabb437608cc035768 Mon Sep 17 00:00:00 2001 From: Jan Bouwhuis Date: Tue, 1 Feb 2022 16:28:32 +0100 Subject: [PATCH 10/13] Add MQTT siren platform (#21254) --- source/_docs/mqtt/discovery.markdown | 5 + source/_integrations/siren.mqtt.markdown | 273 +++++++++++++++++++++++ 2 files changed, 278 insertions(+) create mode 100644 source/_integrations/siren.mqtt.markdown diff --git a/source/_docs/mqtt/discovery.markdown b/source/_docs/mqtt/discovery.markdown index 77ce66f2a1c..a292748e876 100644 --- a/source/_docs/mqtt/discovery.markdown +++ b/source/_docs/mqtt/discovery.markdown @@ -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', diff --git a/source/_integrations/siren.mqtt.markdown b/source/_integrations/siren.mqtt.markdown new file mode 100644 index 00000000000..855e90c8fde --- /dev/null +++ b/source/_integrations/siren.mqtt.markdown @@ -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 %} + +
+ +Make sure that your topic matches exactly. `some-topic/` and `some-topic` are different topics. + +
+ +## 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" +``` From 3573ac2ebdbc102c6003655c4362923b36ed8584 Mon Sep 17 00:00:00 2001 From: Jan Bouwhuis Date: Thu, 3 Feb 2022 16:52:10 +0100 Subject: [PATCH 11/13] Mqtt fan support unknown state (#21415) --- source/_integrations/fan.mqtt.markdown | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/source/_integrations/fan.mqtt.markdown b/source/_integrations/fan.mqtt.markdown index 3a1ae169fb1..a871d2e41cb 100644 --- a/source/_integrations/fan.mqtt.markdown +++ b/source/_integrations/fan.mqtt.markdown @@ -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. From 5f240a53f4ff7720218d0dbadfcbbdc615b6688b Mon Sep 17 00:00:00 2001 From: Jan Bouwhuis Date: Thu, 3 Feb 2022 16:52:29 +0100 Subject: [PATCH 12/13] MQTT humidifier support unknown state (#21418) --- source/_integrations/humidifier.mqtt.markdown | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/source/_integrations/humidifier.mqtt.markdown b/source/_integrations/humidifier.mqtt.markdown index 59d780546cb..5445422b5b6 100644 --- a/source/_integrations/humidifier.mqtt.markdown +++ b/source/_integrations/humidifier.mqtt.markdown @@ -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. From fa4ba2f8b0195698302e7969a402291a0a9f2593 Mon Sep 17 00:00:00 2001 From: Jan Bouwhuis Date: Thu, 3 Feb 2022 16:52:44 +0100 Subject: [PATCH 13/13] MQTT light support unknown state (#21419) --- source/_integrations/light.mqtt.markdown | 28 ++++++++++++------------ 1 file changed, 14 insertions(+), 14 deletions(-) diff --git a/source/_integrations/light.mqtt.markdown b/source/_integrations/light.mqtt.markdown index 2689d1e840a..823d513d5df 100644 --- a/source/_integrations/light.mqtt.markdown +++ b/source/_integrations/light.mqtt.markdown @@ -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.