From 0f630328a36a1791b5741b8a9688794898cc02ae Mon Sep 17 00:00:00 2001 From: jbouwh Date: Sun, 31 May 2026 14:22:01 +0000 Subject: [PATCH 1/5] Deprecate `state_stopic` and `value_template` for MQTT `device_tracker` --- .../device_tracker.mqtt.markdown | 53 +++++++------------ 1 file changed, 19 insertions(+), 34 deletions(-) diff --git a/source/_integrations/device_tracker.mqtt.markdown b/source/_integrations/device_tracker.mqtt.markdown index 7aa0927776d7..edfb5fce6cf5 100644 --- a/source/_integrations/device_tracker.mqtt.markdown +++ b/source/_integrations/device_tracker.mqtt.markdown @@ -140,14 +140,27 @@ json_attributes_template: required: false type: template json_attributes_topic: - description: "The MQTT topic subscribed to receive a JSON dictionary message containing device tracker attributes. - This topic can be used to set the location of the device tracker under the following conditions: + description: "The MQTT topic is subscribed to receive a JSON dictionary containing device tracker attributes and is used to update the location of the device tracker.\n +The JSON message must include either:\n -- If the attributes in the JSON message include `longitude`, `latitude`, and `gps_accuracy` (optional).\n -- If the device tracker is within a configured [zone](/integrations/zone/).\n +- `in_zones`, **or**\n +- `longitude`, `latitude`, and optionally `gps_accuracy`. - If these conditions are met, it is not required to configure `state_topic`.\n\n - Be aware that any location message received at `state_topic` overrides the location received via `json_attributes_topic` until a message configured with `payload_reset` is received at `state_topic`. For a more generic usage example of the `json_attributes_topic`, refer to the [MQTT sensor](/integrations/sensor.mqtt/#json-attributes-topic-configuration) documentation." +A device tracker is considered to be located *within a zone* when the `in_zones` attribute is provided.\n + +You can provide location information in one of two ways:\n + +1. **Coordinates** — by including `longitude`, `latitude`, and optionally `gps_accuracy`.\n +2. **Zone reference** — by setting `in_zones` to the zone’s `friendly_name`, `object_id`, or `entity_id`.\n + +The `in_zones` attribute may be a single string or a list of strings. +Each value must match a Home Assistant zone’s `entity_id`, `object_id`, or `friendly_name`.\n +For example, the default zone with entity_id `zone.home` typically has:\n + +- `friendly_name`: **Home** (depending on language settings and customization)\n +- `object_id`: **home**\n + +For a more general usage example of `json_attributes_topic`, refer to the [MQTT sensor](/integrations/sensor.mqtt/#json-attributes-topic-configuration) documentation." required: false type: string name: @@ -159,26 +172,6 @@ payload_available: required: false type: string default: online -payload_home: - description: The payload value that represents the 'home' state for the device. - required: false - type: string - default: home -payload_not_available: - description: The payload that represents the unavailable state. - required: false - type: string - default: offline -payload_not_home: - description: The payload value that represents the 'not_home' state for the device. - required: false - type: string - default: not_home -payload_reset: - description: The payload value that will have the device's location automatically derived from Home Assistant's zones. - required: false - type: string - default: '"None"' platform: description: Must be `device_tracker`. Only allowed and required in [MQTT auto discovery device messages](/integrations/mqtt/#device-discovery-payload). required: true @@ -192,18 +185,10 @@ source_type: description: Attribute of a device tracker that affects state when being used to track a [person](/integrations/person/). Valid options are `gps`, `router`, `bluetooth`, or `bluetooth_le`. required: false type: string -state_topic: - description: The MQTT topic subscribed to receive device tracker state changes. The states defined in `state_topic` override the location states defined by the `json_attributes_topic`. This state override is turned inactive if the `state_topic` receives a message containing `payload_reset`. The `state_topic` can only be omitted if `json_attributes_topic` is used. An empty payload is ignored. Valid payloads are `not_home`, `home` or any other custom location or zone name. Payloads for `not_home`, `home` can be overridden with the `payload_not_home`and `payload_home` config options. - required: false - type: string unique_id: description: "An ID that uniquely identifies this device_tracker. If two device_trackers have the same unique ID, Home Assistant will raise an exception. Required when used with device-based discovery." required: false type: string -value_template: - description: "Defines a [template](/docs/templating/where-to-use/#mqtt) that returns a device tracker state." - required: false - type: template {% endconfiguration %} ## Examples From fbcabaf5e4783d3438c40400870c0f351feb48a2 Mon Sep 17 00:00:00 2001 From: jbouwh Date: Mon, 1 Jun 2026 10:15:27 +0000 Subject: [PATCH 2/5] Update after core PR review --- source/_integrations/device_tracker.mqtt.markdown | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/_integrations/device_tracker.mqtt.markdown b/source/_integrations/device_tracker.mqtt.markdown index edfb5fce6cf5..1f089e8da619 100644 --- a/source/_integrations/device_tracker.mqtt.markdown +++ b/source/_integrations/device_tracker.mqtt.markdown @@ -153,7 +153,7 @@ You can provide location information in one of two ways:\n 1. **Coordinates** — by including `longitude`, `latitude`, and optionally `gps_accuracy`.\n 2. **Zone reference** — by setting `in_zones` to the zone’s `friendly_name`, `object_id`, or `entity_id`.\n -The `in_zones` attribute may be a single string or a list of strings. +The `in_zones` attribute must be list of strings. Each value must match a Home Assistant zone’s `entity_id`, `object_id`, or `friendly_name`.\n For example, the default zone with entity_id `zone.home` typically has:\n From d3327494896e517cf96bc53c5f49a0a478add47b Mon Sep 17 00:00:00 2001 From: jbouwh Date: Wed, 3 Jun 2026 19:38:18 +0000 Subject: [PATCH 3/5] Remove examples with `state_topic` and add example with `in_zones` state attribute --- .../device_tracker.mqtt.markdown | 49 +++++++------------ 1 file changed, 18 insertions(+), 31 deletions(-) diff --git a/source/_integrations/device_tracker.mqtt.markdown b/source/_integrations/device_tracker.mqtt.markdown index 1f089e8da619..3b30738966d7 100644 --- a/source/_integrations/device_tracker.mqtt.markdown +++ b/source/_integrations/device_tracker.mqtt.markdown @@ -197,32 +197,17 @@ unique_id: The device_tracker can be created via publishing to a discovery topic that follows the following [MQTT Discovery](/integrations/mqtt/#mqtt-discovery#discovery-topic) topic name format: `/device_tracker/[/]/config`. -You can use the command line tool `mosquitto_pub` shipped with `mosquitto` or the `mosquitto-clients` package to send MQTT messages. - -To create the device_tracker: - -```bash -mosquitto_pub -h 127.0.0.1 -t homeassistant/device_tracker/a4567d663eaf/config -m '{"state_topic": "homeassistant/device_tracker/a4567d663eaf/state", "name": "My Tracker", "payload_home": "home", "payload_not_home": "not_home"}' -``` - -To set the state of the device tracker to "home": - -```bash -mosquitto_pub -h 127.0.0.1 -t homeassistant/device_tracker/a4567d663eaf/state -m 'home' -``` - -To set the state of the device tracker to a named location: - -```bash -mosquitto_pub -h 127.0.0.1 -t homeassistant/device_tracker/a4567d663eaf/state -m 'location_name' -``` - If the device supports GPS coordinates then they can be sent to Home Assistant by specifying an attributes topic (that is, `json_attributes_topic`) in the configuration payload: -- Attributes topic: `homeassistant/device_tracker/a4567d663eaf/attributes` +- Attributes topic: `homeassistant/device_tracker/a4567d663eaf/location_attrs` - Example attributes payload: -Example message to be received at topic `homeassistant/device_tracker/a4567d663eaf/attributes`: +Device tracker can link to a zone with: + +1. Use GPS based coordinates +2. A list of zones (either zone entity IDs, object IDs or names) the device tracker is linked to. + +Example message with GPS based coordinates to be received at topic `homeassistant/device_tracker/a4567d663eaf/location_attrs`: ```json { @@ -232,17 +217,21 @@ Example message to be received at topic `homeassistant/device_tracker/a4567d663e } ``` -To create the device_tracker with GPS coordinates support: +Example message with GPS based coordinates to be received at topic `homeassistant/device_tracker/a4567d663eaf/location_attrs`: -```bash -mosquitto_pub -h 127.0.0.1 -t homeassistant/device_tracker/a4567d663eaf/config -m '{"json_attributes_topic": "homeassistant/device_tracker/a4567d663eaf/attributes", "name": "My Tracker"}' +```json +{ + "in_zones": ["home"] +} ``` -{% note %} +You can use the command line tool `mosquitto_pub` shipped with `mosquitto` or the `mosquitto-clients` package to send MQTT messages. -Using `state_topic` is optional when using `json_attributes_topic` to determine the state of the device tracker. +To create the device_tracker with GPS coordinates support: -{% endnote %} +```bash +mosquitto_pub -h 127.0.0.1 -t homeassistant/device_tracker/a4567d663eaf/config -m '{"json_attributes_topic": "homeassistant/device_tracker/a4567d663eaf/location_attrs", "name": "My Tracker"}' +``` To set the state of the device tracker to specific coordinates: @@ -261,8 +250,6 @@ The following example shows how to configure the same device tracker through con mqtt: - device_tracker: name: "My Tracker" - state_topic: "a4567d663eaf/state" - payload_home: "home" - payload_not_home: "not_home" + json_attributes_topic: "a4567d663eaf/location_attrs" ``` From d9a2c3485ebe7105d6215316120c751b5af194e3 Mon Sep 17 00:00:00 2001 From: jbouwh Date: Wed, 3 Jun 2026 19:41:49 +0000 Subject: [PATCH 4/5] Revert unintender removal of payload_not_available --- source/_integrations/device_tracker.mqtt.markdown | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/source/_integrations/device_tracker.mqtt.markdown b/source/_integrations/device_tracker.mqtt.markdown index 3b30738966d7..a3a128616eaf 100644 --- a/source/_integrations/device_tracker.mqtt.markdown +++ b/source/_integrations/device_tracker.mqtt.markdown @@ -172,6 +172,11 @@ payload_available: required: false type: string default: online +payload_not_available: + description: The payload that represents the unavailable state. + required: false + type: string + default: offline platform: description: Must be `device_tracker`. Only allowed and required in [MQTT auto discovery device messages](/integrations/mqtt/#device-discovery-payload). required: true From dc5404428ddd0518e8dd7a6a9c51e5873d15a0d0 Mon Sep 17 00:00:00 2001 From: jbouwh Date: Wed, 3 Jun 2026 19:50:49 +0000 Subject: [PATCH 5/5] Improve --- .../device_tracker.mqtt.markdown | 26 +++++++++---------- 1 file changed, 12 insertions(+), 14 deletions(-) diff --git a/source/_integrations/device_tracker.mqtt.markdown b/source/_integrations/device_tracker.mqtt.markdown index a3a128616eaf..6bef82f31671 100644 --- a/source/_integrations/device_tracker.mqtt.markdown +++ b/source/_integrations/device_tracker.mqtt.markdown @@ -202,14 +202,17 @@ unique_id: The device_tracker can be created via publishing to a discovery topic that follows the following [MQTT Discovery](/integrations/mqtt/#mqtt-discovery#discovery-topic) topic name format: `/device_tracker/[/]/config`. -If the device supports GPS coordinates then they can be sent to Home Assistant by specifying an attributes topic (that is, `json_attributes_topic`) in the configuration payload: +You can use the command line tool `mosquitto_pub` shipped with `mosquitto` or the `mosquitto-clients` package to send MQTT messages. + +To create the device_tracker: -- Attributes topic: `homeassistant/device_tracker/a4567d663eaf/location_attrs` -- Example attributes payload: +```bash +mosquitto_pub -h 127.0.0.1 -t homeassistant/device_tracker/a4567d663eaf/config -m '{"json_attributes_topic": "homeassistant/device_tracker/a4567d663eaf/location_attrs", "name": "My Tracker"}' +``` -Device tracker can link to a zone with: +An MQTT device tracker can link to a zone with: -1. Use GPS based coordinates +1. GPS based coordinates 2. A list of zones (either zone entity IDs, object IDs or names) the device tracker is linked to. Example message with GPS based coordinates to be received at topic `homeassistant/device_tracker/a4567d663eaf/location_attrs`: @@ -230,26 +233,22 @@ Example message with GPS based coordinates to be received at topic `homeassistan } ``` -You can use the command line tool `mosquitto_pub` shipped with `mosquitto` or the `mosquitto-clients` package to send MQTT messages. - -To create the device_tracker with GPS coordinates support: +To set the state of the device tracker to specific coordinates: ```bash -mosquitto_pub -h 127.0.0.1 -t homeassistant/device_tracker/a4567d663eaf/config -m '{"json_attributes_topic": "homeassistant/device_tracker/a4567d663eaf/location_attrs", "name": "My Tracker"}' +mosquitto_pub -h 127.0.0.1 -t homeassistant/device_tracker/a4567d663eaf/attributes -m '{"latitude": 32.87336, "longitude": -117.22743, "gps_accuracy": 1.2}' ``` -To set the state of the device tracker to specific coordinates: +To set the state of the device tracker with linked zones: ```bash -mosquitto_pub -h 127.0.0.1 -t homeassistant/device_tracker/a4567d663eaf/attributes -m '{"latitude": 32.87336, "longitude": -117.22743, "gps_accuracy": 1.2}' +mosquitto_pub -h 127.0.0.1 -t homeassistant/device_tracker/a4567d663eaf/attributes -m '{"in_zones": ["home"]}' ``` - ### YAML configuration The following example shows how to configure the same device tracker through configuration.yaml - ```yaml # Example configuration.yaml entry mqtt: @@ -257,4 +256,3 @@ mqtt: name: "My Tracker" json_attributes_topic: "a4567d663eaf/location_attrs" ``` -