MQTT device tracker


The mqtt device tracker platform allows you to define new device_trackers through manual YAML configuration in configuration.yaml and also to automatically discover device_trackers using the MQTT Discovery protocol.

Configuration

To use this device tracker in your installation, add the following to your configuration.yaml file:

# Example configuration.yaml entry
mqtt:
  - device_tracker:
      name: "annetherese_n4"
      state_topic: "location/annetherese"
  - device_tracker:
      name: "paulus_oneplus"
      state_topic: "location/paulus"

Configuration Variables

availability list (Optional)

A list of MQTT topics subscribed to receive availability (online/offline) updates. Must not be used together with availability_topic.

payload_available string (Optional, default: online)

The payload that represents the available state.

payload_not_available string (Optional, default: offline)

The payload that represents the unavailable state.

topic string Required

An MQTT topic subscribed to receive availability (online/offline) updates.

value_template template (Optional)

Defines a template 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.

availability_mode string (Optional, default: latest)

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.

availability_template template (Optional)

Defines a template 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.

availability_topic string (Optional)

The MQTT topic subscribed to receive availability (online/offline) updates. Must not be used together with availability.

device map (Optional)

Information about the device this device tracker is a part of that ties it into the device registry. At least one of identifiers or connections must be present to identify the device.

configuration_url string (Optional)

A link to the webpage that can manage the configuration of this device. Can be either an http://, https:// or an internal homeassistant:// URL.

connections list (Optional)

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"]].

hw_version string (Optional)

The hardware version of the device.

identifiers list | string (Optional)

A list of IDs that uniquely identify the device. For example a serial number.

manufacturer string (Optional)

The manufacturer of the device.

model string (Optional)

The model of the device.

name string (Optional)

The name of the device.

suggested_area string (Optional)

Suggest an area if the device isn’t in one yet.

sw_version string (Optional)

The firmware version of the device.

via_device string (Optional)

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.

icon icon (Optional)

Icon for the entity.

json_attributes_template template (Optional)

Defines a template to extract the JSON dictionary from messages received on the json_attributes_topic. Usage example can be found in MQTT sensor documentation.

json_attributes_topic string (Optional)

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:

  • If the attributes in the JSON message include longitude, latitude, and gps_accuracy (optional).
  • If the device tracker is within a configured zone.

If these conditions are met, it is not required to configure state_topic.

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 documentation.

name string (Optional)

The name of the MQTT device_tracker.

object_id string (Optional)

Used instead of name for automatic generation of entity_id

payload_available string (Optional, default: online)

The payload that represents the available state.

payload_home string (Optional, default: home)

The payload value that represents the ‘home’ state for the device.

payload_not_available string (Optional, default: offline)

The payload that represents the unavailable state.

payload_not_home string (Optional, default: not_home)

The payload value that represents the ‘not_home’ state for the device.

payload_reset string (Optional, default: “None”)

The payload value that will have the device’s location automatically derived from Home Assistant’s zones.

qos integer (Optional, default: 0)

The maximum QoS level to be used when receiving and publishing messages.

source_type string (Optional)

Attribute of a device tracker that affects state when being used to track a person. Valid options are gps, router, bluetooth, or bluetooth_le.

state_topic string (Optional)

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.

unique_id string (Optional)

An ID that uniquely identifies this device_tracker. If two device_trackers have the same unique ID, Home Assistant will raise an exception.

value_template template (Optional)

Defines a template that returns a device tracker state.

Examples

Using the discovery protocol

The device_tracker can be created via publishing to a discovery topic that follows the following MQTT Discovery topic name format: <discovery_prefix>/device_tracker/[<node_id>/]<object_id>/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:

mosquitto_pub -h 127.0.0.1 -t homeassistant/device_tracker/a4567d663eaf/config -m '{"state_topic": "a4567d663eaf/state", "name": "My Tracker", "payload_home": "home", "payload_not_home": "not_home"}'

To set the state of the device tracker to “home”:

mosquitto_pub -h 127.0.0.1 -t a4567d663eaf/state -m 'home'

To set the state of the device tracker to a named location:

mosquitto_pub -h 127.0.0.1 -t a4567d663eaf/state -m 'location_name'

If the device supports GPS coordinates then they can be sent to Home Assistant by specifying an attributes topic (i.e. “json_attributes_topic”) in the configuration payload:

  • Attributes topic: a4567d663eaf/attributes
  • Example attributes payload:

Example message to be received at topic a4567d663eaf/attributes:

{
  "latitude": 32.87336,
  "longitude": -117.22743,
  "gps_accuracy": 1.2
 }

To create the device_tracker with GPS coordinates support:

mosquitto_pub -h 127.0.0.1 -t homeassistant/device_tracker/a4567d663eaf/config -m '{"json_attributes_topic": "a4567d663eaf/attributes", "name": "My Tracker"}'

Using state_topic is optional when using json_attributes_topic to determine the state of the device tracker.

To set the state of the device tracker to specific coordinates:

mosquitto_pub -h 127.0.0.1 -t a4567d663eaf/attributes -m '{"latitude": 32.87336, "longitude": -117.22743, "gps_accuracy": 1.2}'

YAML configuration

The following example shows how to configure the same device tracker through configuration.yaml

# Example configuration.yaml entry
mqtt:
  - device_tracker:
      name: "My Tracker"
      state_topic: "a4567d663eaf/state"
      payload_home: "home"
      payload_not_home: "not_home"