From f2a339e4399fe71d6f0ed8f3fdc4c7531eb4944b Mon Sep 17 00:00:00 2001 From: Jan Bouwhuis Date: Sun, 13 Mar 2022 13:52:02 +0100 Subject: [PATCH] Add mqtt notify service and update example page (#21344) --- source/_docs/mqtt/discovery.markdown | 3 + source/_examples/notify.mqtt.markdown | 10 +- source/_integrations/notify.mqtt.markdown | 111 ++++++++++++++++++++++ 3 files changed, 123 insertions(+), 1 deletion(-) create mode 100644 source/_integrations/notify.mqtt.markdown diff --git a/source/_docs/mqtt/discovery.markdown b/source/_docs/mqtt/discovery.markdown index 4f5c224db31..4e54dc5b0b2 100644 --- a/source/_docs/mqtt/discovery.markdown +++ b/source/_docs/mqtt/discovery.markdown @@ -21,6 +21,7 @@ Supported by MQTT discovery: - [Lights](/integrations/light.mqtt/) - [Locks](/integrations/lock.mqtt/) - [Numbers](/integrations/number.mqtt/) +- [Notify](/integrations/notify.mqtt/) - [Scenes](/integrations/scene.mqtt/) - [Selects](/integrations/select.mqtt/) - [Sensors](/integrations/sensor.mqtt/) @@ -282,6 +283,8 @@ Supported abbreviations: 'tilt_opt': 'tilt_optimistic', 'tilt_status_t': 'tilt_status_topic', 'tilt_status_tpl': 'tilt_status_template', + 'title': 'title', + 'trgts': 'targets', 't': 'topic', 'uniq_id': 'unique_id', 'unit_of_meas': 'unit_of_measurement', diff --git a/source/_examples/notify.mqtt.markdown b/source/_examples/notify.mqtt.markdown index 527f9e1622b..77a08e520de 100644 --- a/source/_examples/notify.mqtt.markdown +++ b/source/_examples/notify.mqtt.markdown @@ -6,7 +6,15 @@ ha_category: Notifications ha_iot_class: Configurable --- -The MQTT notification support is different than the other [notification](/integrations/notify/) platforms. It is a service. This means that you don't have to create a configuration entry but you need to provide more details when calling the service. +The MQTT notification support is different than the other [notification](/integrations/notify/) platforms. It is a service. + +## Use the the MQTT notify platform + +The [MQTT notify service platform](/integrations/notify.mqtt/) allows you to use [MQTT discovery](/docs/mqtt/discovery/), or manual setup through `configuration.yaml` to enable a custom MQTT notify service. The notify platform helps to implement notification services on IoT notification screens, notification gateways, or for digital signage applications. An example is showing a text alert message on a climate control unit, e.g. an error, alert or informal message. The device can advertize the notification message service through discovery. + +## Direct publishing + +You can also publish directly, this means that you don't have to create a configuration entry but you need to provide more details when calling the service. **Call Service** section from **Developer Tools** -> **Services** allows you to send MQTT messages. Choose *mqtt.publish* from the list of **Available services:** and enter something like the sample below into the **Service Data** field and hit **CALL SERVICE**. diff --git a/source/_integrations/notify.mqtt.markdown b/source/_integrations/notify.mqtt.markdown new file mode 100644 index 00000000000..f45655580bc --- /dev/null +++ b/source/_integrations/notify.mqtt.markdown @@ -0,0 +1,111 @@ +--- +title: "MQTT Notify service" +description: "Instructions on how to integrate MQTT notify service within Home Assistant." +ha_category: + - Notify service +ha_release: 2022.3 +ha_iot_class: Configurable +ha_domain: mqtt +--- + +The `mqtt` notify service uses MQTT to notify targets. + +## Configuration + +MQTT notify services are supported through [MQTT discovery](/docs/mqtt/discovery/), and manual setup through `configuration.yaml`. +The discovery topic needs to be: `/notify/[/]/config`. This integration does not create entities like other `mqtt` platforms, it will register a notify service. A `device` context is only supported through MQTT discovery. The device will automatically be created, updated and removed following discovery updates. If a discovered device is removed from Home Assistant the corresponding service will be removed as well. + +As alternative you can also choose to [publish notifications directly](/examples/notify.mqtt). + +{% configuration %} +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 `message` parameter that was given when calling the notify service. The service parameters `message`, `name`, `service`, `title` and `target` can be used as variables in the template. Use the `data` service parameter to add additional variables. + required: false + type: template +command_topic: + description: The MQTT topic to publish the notification message. To use `title`, `target` config or `data` service parameters in the payload, use `command_template` to format the payload. + required: true + type: string +device: + description: "Information about the device this device trigger is a part of to tie it into the [device registry](https://developers.home-assistant.io/docs/en/device_registry_index.html). 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, map] + identifiers: + description: A list of IDs that uniquely identify the device. For example a serial number. + required: false + type: [list, string] + 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 +name: + description: "The name for the notify service. The name will be available as variable `name` in the `command_template`. The actual `service_name` will be derived from the name and cannot contain other then lowercase characters numbers and `_`. The notify service will be exposed as service `notify.{service_name}`. The `service_name` must be unique. If a service with the specified name already is registered, the setup will fail." + required: true + type: string + default: "mqtt" +targets: + description: An optional of list targets that are supported by the notify service. When configured additional services in the format `notify.{service_name}_{target}` will be registered to be able to notify the targets directly. When calling the base notify service `notify.{service_name}` the `target` parameter should can used to specify a list of addressed targets. The `target` (`list`) is available for use in the `command_template`. When a target parameter is not specified when calling the base notify service `notify.{service_name}` all configured targets will be included in the `target` variable. + required: false + type: list +title: + description: The default title to be assigned to the `title` variable in `command_template`. If `title` is specified with the service call, this will override this default title. + required: false + type: string + default: "Home Assistant" +{% endconfiguration %} + +## Examples + +In this section, you will find some real-life examples of how to use the notify service. + +### Full configuration + +The example below shows a full configuration for a MQTT notify service. The example will register a service `notify.intrusion_text_notification`, `notify.intrusion_text_notification_panel1` and `notify.intrusion_text_notification_panel2` that will publish at topic `home/alarm/notify/message`. + +{% raw %} + +```yaml +# Example configuration.yaml entry +notify: + - platform: mqtt + name: "Intrusion text notification" + command_topic: "home/alarm/notify/message" + command_template: "{{ title }}: {{ message }}" + targets: + - "panel1" + - "panel2" + title: "Intrusion detected" + qos: 0 + retain: true +``` + +{% endraw %}