From 8be8f565be4f417d350c2684f45740d3b72aba8c Mon Sep 17 00:00:00 2001 From: Jan Bouwhuis Date: Tue, 29 Nov 2022 20:31:14 +0100 Subject: [PATCH] Add MQTT text platform (#25091) --- source/_integrations/mqtt.markdown | 3 + source/_integrations/text.mqtt.markdown | 214 ++++++++++++++++++++++++ 2 files changed, 217 insertions(+) create mode 100644 source/_integrations/text.mqtt.markdown diff --git a/source/_integrations/mqtt.markdown b/source/_integrations/mqtt.markdown index 035b961017e..d53a71b1834 100644 --- a/source/_integrations/mqtt.markdown +++ b/source/_integrations/mqtt.markdown @@ -29,6 +29,7 @@ ha_platforms: - siren - switch - tag + - text - update - vacuum ha_integration_type: integration @@ -189,6 +190,7 @@ The discovery of MQTT devices will enable one to use MQTT devices with only mini - [Switch](/integrations/switch.mqtt/) - [Update](/integrations/update.mqtt/) - [Tag Scanner](/integrations/tag.mqtt/) +- [Text](/integrations/text.mqtt/) - [Vacuum](/integrations/vacuum.mqtt/) {% enddetails %} @@ -633,6 +635,7 @@ For most platforms it is also possible to manual set up MQTT items in `configura - [Sensor](/integrations/sensor.mqtt/) - [Siren](/integrations/siren.mqtt/) - [Switch](/integrations/switch.mqtt/) +- [Text](/integrations/text.mqtt/) - [Vacuum](/integrations/vacuum.mqtt/) {% enddetails %} diff --git a/source/_integrations/text.mqtt.markdown b/source/_integrations/text.mqtt.markdown new file mode 100644 index 00000000000..82476e0630b --- /dev/null +++ b/source/_integrations/text.mqtt.markdown @@ -0,0 +1,214 @@ +--- +title: "MQTT Update" +description: "Instructions on how to interact with a device exposing text capability through MQTT from within Home Assistant." +ha_category: + - Text +ha_release: "2021.12" +ha_iot_class: Configurable +ha_domain: mqtt +--- + +The `mqtt` Text platform allows you to integrate devices that show text that can be set remotely. Optionally the text state can be monitored too using MQTT. + +## Configuration + +To enable MQTT text platform in your installation, add the following to your `configuration.yaml` file: + +```yaml +# Example configuration.yaml entry +mqtt: + text: + - command_topic: command-topic +``` + +{% 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/#using-templates-with-the-mqtt-integration) 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_topic: + description: The MQTT topic subscribed to receive availability (online/offline) updates. Must not be used together with `availability`. + required: false + type: string +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/#using-templates-with-the-mqtt-integration) 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 +command_template: + description: Defines a [template](/docs/configuration/templating/#using-templates-with-the-mqtt-integration) to generate the payload to send to `command_topic`. + required: false + type: template +command_topic: + description: The MQTT topic to publish the text value that is set. + required: true + type: string +device: + description: "Information about the device this of text capability 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 + hw_version: + description: The hardware version of the device. + required: false + type: string + 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 +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 +json_attributes_template: + description: "Defines a [template](/docs/configuration/templating/#using-templates-with-the-mqtt-integration) to extract the JSON dictionary from messages received on the `json_attributes_topic`." + required: false + type: template +json_attributes_topic: + description: The MQTT topic subscribed to receive a JSON dictionary payload and then set as entity attributes. Implies `force_update` of the current select state when a message is received on this topic. + required: false + type: string +max: + description: The maximum size of a text being set or received (maximum is 255). + required: false + type: integer + default: 255 +min: + description: The minimum size of a text being set or received. + required: false + type: integer + default: 0 +mode: + description: "The mode off the text entity. Must be either `text` or `password`." + required: false + type: string + default: text +name: + description: The name of the text entity. + required: false + type: string + default: "MQTT Text" +object_id: + description: Used instead of `name` for automatic generation of `entity_id` + required: false + type: string +pattern: + description: A valid regular expression the text being set or received must match with. + required: false + type: string +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_topic: + description: "The MQTT topic subscribed to receive text state updates. Text state updates should match the `pattern` (if set) and meet the size constraints `min` and `max`. Can be used with `value_template` to render the incoming payload to a text update." + required: false + type: string +unique_id: + description: An ID that uniquely identifies this Select. If two Selects have the same unique ID Home Assistant will raise an exception. + required: false + type: string +value_template: + description: "Defines a [template](/docs/configuration/templating/#using-templates-with-the-mqtt-integration) to extract the text state value from the payload received on `state_topic`." + required: false + type: template +{% endconfiguration %} + +
+ +Make sure that your topic matches exactly. `some-topic/` and `some-topic` are different topics. + +
+ +## Examples + +This is an example of a manual configured MQTT `text` item. + +{% raw %} + +```yaml +# Example configuration.yaml entry +mqtt: + text: + - name: "Remote LCD screen" + icon: mdi:ab-testing + mode: "text" + command_topic: "txt/cmd" + state_topic: "txt/state" + min: 2 + max: 20 +``` + +{% endraw %}