|
| 1 | +--- |
| 2 | +title: "MQTT Lawn Mower" |
| 3 | +description: "Instructions on how to integrate MQTT lawn mowers into Home Assistant." |
| 4 | +ha_category: |
| 5 | + - Lawn Mower |
| 6 | +ha_release: 2023.9 |
| 7 | +ha_iot_class: Configurable |
| 8 | +ha_domain: mqtt |
| 9 | +--- |
| 10 | + |
| 11 | +The `mqtt` `lawn_mower` platform allows controlling a lawn mower over MQTT. |
| 12 | + |
| 13 | +## Configuration |
| 14 | + |
| 15 | +To enable MQTT Lawn Mower in your installation, add the following to your `configuration.yaml` file: |
| 16 | + |
| 17 | +```yaml |
| 18 | +# Example configuration.yaml entry |
| 19 | +mqtt: |
| 20 | + - lawn_mower: |
| 21 | + command_topic: topic |
| 22 | + name: "Test Lawn Mower" |
| 23 | +``` |
| 24 | +
|
| 25 | +{% configuration %} |
| 26 | +activity_state_topic: |
| 27 | + description: The MQTT topic subscribed to receive an update of the activity. Valid activities are `mowing`, `paused`, `docked`, and `error`. Use `value_template` to extract the activity state from a custom payload. When payload `none` is received, the activity state will be reset to `unknown`. |
| 28 | + required: false |
| 29 | + type: string |
| 30 | +activity_value_template: |
| 31 | + description: "Defines a [template](/docs/configuration/templating/#using-templates-with-the-mqtt-integration) to extract the value." |
| 32 | + required: false |
| 33 | + type: template |
| 34 | +availability: |
| 35 | + description: A list of MQTT topics subscribed to receive availability (online/offline) updates. Must not be used together with `availability_topic`. |
| 36 | + required: false |
| 37 | + type: list |
| 38 | + keys: |
| 39 | + payload_available: |
| 40 | + description: The payload that represents the available state. |
| 41 | + required: false |
| 42 | + type: string |
| 43 | + default: online |
| 44 | + payload_not_available: |
| 45 | + description: The payload that represents the unavailable state. |
| 46 | + required: false |
| 47 | + type: string |
| 48 | + default: offline |
| 49 | + topic: |
| 50 | + description: An MQTT topic subscribed to receive availability (online/offline) updates. |
| 51 | + required: true |
| 52 | + type: string |
| 53 | + value_template: |
| 54 | + 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 device's availability, the result of this template will be compared to `payload_available` and `payload_not_available`." |
| 55 | + required: false |
| 56 | + type: template |
| 57 | +availability_topic: |
| 58 | + description: The MQTT topic subscribed to receive availability (online/offline) updates. Must not be used together with `availability`. |
| 59 | + required: false |
| 60 | + type: string |
| 61 | +availability_mode: |
| 62 | + 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. |
| 63 | + required: false |
| 64 | + type: string |
| 65 | + default: latest |
| 66 | +availability_template: |
| 67 | + 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, the result of this template will be compared to `payload_available` and `payload_not_available`." |
| 68 | + required: false |
| 69 | + type: template |
| 70 | +device: |
| 71 | + description: "Information about the device this lawn mower 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 the [`unique_id`](#unique_id) is set. At least one of the identifiers or connections must be present to identify the device." |
| 72 | + required: false |
| 73 | + type: map |
| 74 | + keys: |
| 75 | + configuration_url: |
| 76 | + 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.' |
| 77 | + required: false |
| 78 | + type: string |
| 79 | + connections: |
| 80 | + 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"]`.' |
| 81 | + required: false |
| 82 | + type: list |
| 83 | + hw_version: |
| 84 | + description: The hardware version of the device. |
| 85 | + required: false |
| 86 | + type: string |
| 87 | + identifiers: |
| 88 | + description: 'A list of IDs that uniquely identify the device. For example, a serial number.' |
| 89 | + required: false |
| 90 | + type: [list, string] |
| 91 | + manufacturer: |
| 92 | + description: The manufacturer of the device. |
| 93 | + required: false |
| 94 | + type: string |
| 95 | + model: |
| 96 | + description: The model of the device. |
| 97 | + required: false |
| 98 | + type: string |
| 99 | + name: |
| 100 | + description: The name of the device. |
| 101 | + required: false |
| 102 | + type: string |
| 103 | + suggested_area: |
| 104 | + description: 'Suggest an area if the device isn’t in one yet.' |
| 105 | + required: false |
| 106 | + type: string |
| 107 | + sw_version: |
| 108 | + description: The firmware version of the device. |
| 109 | + required: false |
| 110 | + type: string |
| 111 | + via_device: |
| 112 | + 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 the device topology in Home Assistant.' |
| 113 | + required: false |
| 114 | + type: string |
| 115 | +dock_command_template: |
| 116 | + description: Defines a [template](/docs/configuration/templating/#using-templates-with-the-mqtt-integration) to generate the payload to send to `dock_command_topic`. The `value` parameter in the template will be set to `dock`. |
| 117 | + required: false |
| 118 | + type: template |
| 119 | +dock_command_topic: |
| 120 | + description: The MQTT topic that publishes commands when the service `lawn_mower.dock` service call is executed. The value `dock` is published when the service is called. Use a `dock_command_template` to publish a custom format. |
| 121 | + required: false |
| 122 | + type: string |
| 123 | +enabled_by_default: |
| 124 | + description: Flag which defines if the entity should be enabled when first added. |
| 125 | + required: false |
| 126 | + type: boolean |
| 127 | + default: true |
| 128 | +encoding: |
| 129 | + description: The encoding of the payloads received and published messages. Set to `""` to disable decoding of the incoming payload. |
| 130 | + required: false |
| 131 | + type: string |
| 132 | + default: "utf-8" |
| 133 | +entity_category: |
| 134 | + description: The [category](https://developers.home-assistant.io/docs/core/entity#generic-properties) of the entity. |
| 135 | + required: false |
| 136 | + type: string |
| 137 | + default: None |
| 138 | +icon: |
| 139 | + description: "[Icon](/docs/configuration/customizing-devices/#icon) for the entity." |
| 140 | + required: false |
| 141 | + type: icon |
| 142 | +json_attributes_template: |
| 143 | + 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`." |
| 144 | + required: false |
| 145 | + type: template |
| 146 | +json_attributes_topic: |
| 147 | + description: The MQTT topic subscribed to receive a JSON dictionary payload and then set as entity attributes. Implies `force_update` of the current activity state when a message is received on this topic. |
| 148 | + required: false |
| 149 | + type: string |
| 150 | +name: |
| 151 | + description: The name of the lawn mower. Can be set to `null` if only the device name is relevant. |
| 152 | + required: false |
| 153 | + type: string |
| 154 | +object_id: |
| 155 | + description: Used instead of `name` for automatic generation of `entity_id` |
| 156 | + required: false |
| 157 | + type: string |
| 158 | +optimistic: |
| 159 | + description: Flag that defines if the lawn mower works in optimistic mode. |
| 160 | + required: false |
| 161 | + type: boolean |
| 162 | + default: "`true` if no `state_topic` defined, else `false`." |
| 163 | +pause_command_template: |
| 164 | + description: Defines a [template](/docs/configuration/templating/#using-templates-with-the-mqtt-integration) to generate the payload to send to `pause_command_topic`. The `value` parameter in the template will be set to `pause`. |
| 165 | + required: false |
| 166 | + type: template |
| 167 | +pause_command_topic: |
| 168 | + description: The MQTT topic that publishes commands when the service `lawn_mower.pause` service call is executed. The value `pause` is published when the service is called. Use a `pause_command_template` to publish a custom format. |
| 169 | + required: false |
| 170 | + type: string |
| 171 | +qos: |
| 172 | + description: The maximum QoS level to be used when receiving and publishing messages. |
| 173 | + required: false |
| 174 | + type: integer |
| 175 | + default: 0 |
| 176 | +start_mowing_template: |
| 177 | + description: Defines a [template](/docs/configuration/templating/#using-templates-with-the-mqtt-integration) to generate the payload to send to `dock_command_topic`. The `value` parameter in the template will be set to `dock`. |
| 178 | + required: false |
| 179 | + type: template |
| 180 | +start_mowing_command_topic: |
| 181 | + description: The MQTT topic that publishes commands when the service `lawn_mower.start_mowing` service call is executed. The value `start_mowing` is published when the service is called. Use a `start_mowing_command_template` to publish a custom format. |
| 182 | + required: false |
| 183 | + type: string |
| 184 | +retain: |
| 185 | + description: If the published message should have the retain flag on or not. |
| 186 | + required: false |
| 187 | + type: boolean |
| 188 | + default: false |
| 189 | +unique_id: |
| 190 | + description: An ID that uniquely identifies this lawn mower. If two lawn mowers have the same unique ID, Home Assistant will raise an exception. |
| 191 | + required: false |
| 192 | + type: string |
| 193 | +{% endconfiguration %} |
| 194 | + |
| 195 | +<div class='note warning'> |
| 196 | + |
| 197 | +Make sure that your topic matches exactly. `some-topic/` and `some-topic` are different topics. |
| 198 | + |
| 199 | +</div> |
| 200 | + |
| 201 | +## Example |
| 202 | + |
| 203 | +The example below shows how to use a single command topic with a command template. |
| 204 | + |
| 205 | +{% raw %} |
| 206 | + |
| 207 | +```yaml |
| 208 | +# Example configuration.yaml entry |
| 209 | +mqtt: |
| 210 | + - alarm_control_panel: |
| 211 | + name: "Lawn Mower Plus" |
| 212 | + activity_state_topic: "lawn_mower_plus/state" |
| 213 | + activity_value_template: "{{ value_json.activity }}" |
| 214 | + pause_command_topic: "lawn_mower_plus/set" |
| 215 | + pause_command_template: '{"activity": "{{ value }}"}' |
| 216 | + dock_command_topic: "lawn_mower_plus/set" |
| 217 | + dock_command_template: '{"activity": "{{ value }}"}' |
| 218 | + start_mowing_command_topic: "lawn_mower_plus/set" |
| 219 | + start_mowing_command_template: '{"activity": "{{ value }}"}' |
| 220 | +``` |
| 221 | + |
| 222 | +{% endraw %} |
0 commit comments