Add mqtt valve platform (#30344)

* Add mqtt value platform

* Fix formatting.

* Improve documentation

* Add reference on integration page and abbreviations

* State topic will accept both state and position updates plus JSON

* Add stop_command_topic

* Update after review core PR

* Tiny tweaks

* Update source/_integrations/valve.mqtt.markdown

* Tweak to kick the CI

* Apply suggestions from code review

Co-authored-by: Klaas Schoute <klaas_schoute@hotmail.com>

* Update source/_integrations/valve.mqtt.markdown

Co-authored-by: Klaas Schoute <klaas_schoute@hotmail.com>

* Update source/_integrations/valve.mqtt.markdown

* Apply suggestions from code review

Co-authored-by: Klaas Schoute <klaas_schoute@hotmail.com>

* Update source/_integrations/valve.mqtt.markdown

* Fix

---------

Co-authored-by: c0ffeeca7 <38767475+c0ffeeca7@users.noreply.github.com>
Co-authored-by: Klaas Schoute <klaas_schoute@hotmail.com>
This commit is contained in:
Jan Bouwhuis 2023-12-20 13:50:54 +01:00 committed by GitHub
parent b7063b0e1e
commit 4ef6c55e62
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
2 changed files with 376 additions and 0 deletions

View File

@ -37,6 +37,7 @@ ha_platforms:
- text
- update
- vacuum
- valve
- water_heater
ha_integration_type: integration
ha_quality_scale: gold
@ -240,6 +241,7 @@ The discovery of MQTT devices will enable one to use MQTT devices with only mini
- [Tag scanner](/integrations/tag.mqtt/)
- [Text](/integrations/text.mqtt/)
- [Vacuum](/integrations/vacuum.mqtt/)
- [Valve](/integrations/valve.mqtt/)
- [Water heater](/integrations/water_heater.mqtt/)
{% enddetails %}
@ -457,6 +459,7 @@ support_url:
'pl_ton': 'payload_turn_on',
'pl_trig': 'payload_trigger',
'pl_unlk': 'payload_unlock',
'pos': 'reports_position',
'pos_clsd': 'position_closed',
'pos_open': 'position_open',
'pr_mode_cmd_t': 'preset_mode_command_topic',
@ -993,6 +996,7 @@ mqtt:
- [Text](/integrations/text.mqtt/)
- [Update](/integrations/update.mqtt/)
- [Vacuum](/integrations/vacuum.mqtt/)
- [Valve](/integrations/valve.mqtt/)
- [Water heater](/integrations/water_heater.mqtt/)
{% enddetails %}

View File

@ -0,0 +1,372 @@
---
title: "MQTT Valve"
description: "Instructions on how to integrate MQTT valves into Home Assistant."
ha_category:
- Valve
ha_iot_class: Configurable
ha_release: 2024.1
ha_domain: mqtt
---
The `mqtt` valve platform allows you to control an MQTT valve (such a gas or water valve).
## Configuration
A valve entity can be have the following states: `open`, `opening`, `closed` or `closing`.
### Valve controlled by states
If a `state_topic` is configured, the entity's state will be updated only after an MQTT message is received on `state_topic` matching `state_open`, `state_opening`, `state_closed` or `state_closing`. Commands configured through `payload_open`, `payload_closed`, and `payload_stop` will be published to `command_topic` to control the valve.
To use your MQTT valve in your installation, add the following to your `configuration.yaml` file:
```yaml
# Example configuration.yaml entry for a value that is set by open or close command
mqtt:
- valve:
command_topic: "home-assistant/valve/set"
state_topic: "home-assistant/valve/state"
```
### Valve controlled by position
If the valve supports reporting its position (the `reports_position` config option is set to `true`), a numeric state is expected on `state_topic`, but state updates are still allowed for `state_opening` and `state_closing`. Also, a JSON format is supported. It allows both `state` and `position` to be reported together.
Example of a JSON state update:
```json
{"state": "opening", "position": 10}
```
The wanted position value or `payload_stop` will be published to `command_topic` to control the valve when the services `valve.open`, `value.close`, or `value.set_position` are called.
To use your MQTT valve in your installation, add the following to your `configuration.yaml` file:
```yaml
# Example configuration.yaml entry for a valve that reports position
mqtt:
- valve:
command_topic: "home-assistant/valve/set"
state_topic: "home-assistant/valve/state"
reports_position: true
```
### Optimistic operation
If a `state_topic` is not defined, the valve will work in optimistic mode. In this mode, the valve will immediately change state (`open` or `closed`) after every command sent by Home Assistant. It won't wait for an update from the device. Optimistic mode can be forced by setting `optimistic` to `true`, even if a `state_topic` is defined. Try to enable it if you are experiencing an incorrect valve operation.
{% 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 the device's availability from the `topic`. To determine the devices's availability, the 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/#using-templates-with-the-mqtt-integration) to extract the device's availability from the `availability_topic`. To determine the devices's availability, the 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 birth and LWT messages from the MQTT valve device. If an `availability` topic is not defined, the valve availability state will always be `available`. If an `availability` topic is defined, the valve availability state will be `unavailable` by default. Must not be used together with `availability`."
required: false
type: string
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 commands to control the valve. The value sent can be a value defined by `payload_open`, `payload_close` or `payload_stop`. If `reports_position` is set to `true`, a numeric value will be published instead.
required: false
type: string
device:
description: "Information about the device this valve is a part of to tie it into the [device registry](https://developers.home-assistant.io/docs/en/device_registry_index.html). Only works when [`unique_id`](#unique_id) is set. At least one of the 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://`, `https://` or an internal `homeassistant://` URL."
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 isnt 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
device_class:
description: Sets the [class of the device](/integrations/valve/), changing the device state and icon that is displayed on the frontend. The `device_class` can be `null`.
default: None
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/#using-templates-with-the-mqtt-integration) to extract the JSON dictionary from messages received on the `json_attributes_topic`. A usage example can be found in the [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. A usage example can be found in [MQTT sensor](/integrations/sensor.mqtt/#json-attributes-topic-configuration) documentation.
required: false
type: string
name:
description: The name of the valve. Can be set to `null` if only the device name is relevant.
required: false
type: string
default: MQTT valve
object_id:
description: Used instead of `name` to have the `entity_id` generated automatically.
required: false
type: string
optimistic:
description: Flag that defines if a switch works in optimistic mode.
required: false
type: boolean
default: "`false` if the state or position topic is defined; `true` otherwise."
payload_available:
description: The payload that represents the online state.
required: false
type: string
default: online
payload_close:
description: The command payload that closes the valve. Is only used when `reports_position` is set to `false` (default). The `payload_close` is not allowed if `reports_position` is set to `true`. Can be set to `null` to disable the valve's close option.
required: false
type: string
default: CLOSE
payload_not_available:
description: The payload that represents the offline state.
required: false
type: string
default: offline
payload_open:
description: The command payload that opens the valve. Is only used when `reports_position` is set to `false` (default). The `payload_open` is not allowed if `reports_position` is set to `true`. Can be set to `null` to disable the valve's open option.
required: false
type: string
default: OPEN
payload_stop:
description: The command payload that stops the valve. When not configured, the valve will not support the `valve.stop` service.
required: false
type: string
position_closed:
description: Number which represents closed position. The valve's position will be scaled to the(`position_closed`...`position_open`) range when a service is called and scaled back when a value is received.
required: false
type: integer
default: 0
position_open:
description: Number which represents open position. The valve's position will be scaled to (`position_closed`...`position_open`) range when a service is called and scaled back when a value is received.
required: false
type: integer
default: 100
qos:
description: The maximum QoS level to be used when receiving and publishing messages.
required: false
type: integer
default: 0
reports_position:
description: "Set to `true` if the value reports the position or supports setting the position. Enabling the `reports_position` option will cause the position to be published instead of a payload defined by `payload_open`, `payload_close` or `payload_stop`. When receiving messages, `state_topic` will accept numeric payloads or one of the following state messages: `open`, `opening`, `closed`, or `closing`."
required: false
type: boolean
default: false
retain:
description: Defines if published messages should have the retain flag set.
required: false
type: boolean
default: false
state_closed:
description: The payload that represents the closed state. Is only allowed when `reports_position` is set to `False` (default).
required: false
type: string
default: closed
state_closing:
description: The payload that represents the closing state.
required: false
type: string
default: closing
state_open:
description: The payload that represents the open state. Is only allowed when `reports_position` is set to `False` (default).
required: false
type: string
default: open
state_opening:
description: The payload that represents the opening state.
required: false
type: string
default: opening
state_topic:
description: The MQTT topic subscribed to receive valve state messages. State topic accepts a state payload (`open`, `opening`, `closed`, or `closing`) or, if `reports_position` is supported, a numeric value representing the position. In a JSON format with variables `state` and `position` both values can received together.
required: false
type: string
unique_id:
description: An ID that uniquely identifies this valve. If two valves 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) that can be used to extract the payload for the `state_topic` topic. The rendered value should be a defined state payload or, if reporting a `position` is supported and `reports_position` is set to `true`, a numeric value is expected representing the position. See also `state_topic`."
required: false
type: template
{% endconfiguration %}
<div class="note">
MQTT valve expects position values to be in the range of 0 to 100, where 0 indicates a closed position and 100 indicates a fully open position.
If `position_open` or `position_closed` are set to a different range (for example, 40 to 140), when sending a command to the device, the range will be adjusted to the device range. For example, position 0 will send a value of 40 to device. When the device receives a position payload, it will be adjusted back to the 0 to 100 range. In our example, the device value of 40 will report valve position 0.
`position_open` and `position_closed` can also be used to reverse the direction of the device: If `position_closed` is set to 100 and `position_open` is set to `0`, the device operation will be inverted. For example, when setting the position to 40, a value of 60 will be sent to the device.
</div>
## Examples
This section provides some examples showing how you can use this platform.
### Full configuration for a value that does not report position
The example below shows a full configuration for a valve that does not report position.
{% raw %}
```yaml
# Example configuration.yaml entry
mqtt:
- valve:
name: "MQTT valve"
command_template: '{"x": {{ value }} }'
command_topic: "home-assistant/valve/set"
state_topic: "home-assistant/valve/state"
availability:
- topic: "home-assistant/valve/availability"
qos: 0
reports_position: false
retain: true
payload_open: "OPEN"
payload_close: "CLOSE"
payload_stop: "STOP"
state_open: "open"
state_opening: "opening"
state_closed: "closed"
state_closing: "closing"
payload_available: "online"
payload_not_available: "offline"
optimistic: false
value_template: "{{ value_json.x }}"
```
{% endraw %}
### Sample configuration of a valve that reports the position
The example below shows a sample configuration for a valve that reports the position using JSON messages.
{% raw %}
```yaml
# Example configuration.yaml entry
mqtt:
- valve:
name: "MQTT valve"
command_template: '{"x": {{ value }} }'
command_topic: "home-assistant/valve/set"
state_topic: "home-assistant/valve/state"
availability:
- topic: "home-assistant/valve/availability"
reports_position: true
value_template: "{{ value_json.x }}"
```
{% endraw %}
### Configuration for disabling valve commands
The example below shows a configuration for a valve that does not have a close command.
Setting the `payload_close` to empty or to `null` disables the close command and will not show the close button.
{% raw %}
```yaml
# Example configuration.yaml entry
mqtt:
- valve:
payload_open: "on"
payload_close:
payload_stop: "on"
```
{% endraw %}
An MQTT valve will support `open` and `close` commands if a `command_topic` is set. The MQTT valve supports `stop` if `payload_stop` is set.
### Testing your configuration
To test, you can use the command line tool `mosquitto_pub` shipped with `mosquitto` or the `mosquitto-clients` package to send MQTT messages. This allows you to operate your valve manually:
```bash
mosquitto_pub -h 127.0.0.1 -t home-assistant/valve/set -m "CLOSE"
```