Skip to content

Improve MQTT device_tracker documentation #23359

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
frenck merged 1 commit into from
Jul 11, 2022
Merged

Improve MQTT device_tracker documentation #23359

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
82 changes: 5 additions & 77 deletions source/_docs/mqtt/discovery.markdown
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -363,7 +363,7 @@ mosquitto_pub -h 127.0.0.1 -p 1883 -t "homeassistant/binary_sensor/garden/config

For more details please refer to the [MQTT testing section](/docs/mqtt/testing/).

### Sensors with multiple values
### Sensors

Setting up a sensor with multiple measurement values requires multiple consecutive configuration topic submissions.

Expand All @@ -373,9 +373,9 @@ Setting up a sensor with multiple measurement values requires multiple consecuti
- Configuration payload no2: `{"device_class": "humidity", "name": "Humidity", "state_topic": "homeassistant/sensor/sensorBedroom/state", "unit_of_measurement": "%", "value_template": "{% raw %}{{ value_json.humidity}}{% endraw %}" }`
- Common state payload: `{ "temperature": 23.20, "humidity": 43.70 }`

### Switches
### Entities with command topics

Setting up a switch is similar but requires a `command_topic` as mentioned in the [MQTT switch documentation](/integrations/switch.mqtt/).
Setting up a light, switch etc. is similar but requires a `command_topic` as mentioned in the [MQTT switch documentation](/integrations/switch.mqtt/).

- Configuration topic: `homeassistant/switch/irrigation/config`
- State topic: `homeassistant/switch/irrigation/state`
Expand All @@ -394,7 +394,7 @@ Set the state.
mosquitto_pub -h 127.0.0.1 -p 1883 -t "homeassistant/switch/irrigation/set" -m ON
```

### Abbreviating topic names
### Using abbreviations and base topic

Setting up a switch using topic prefix and abbreviated configuration variable names to reduce payload length.

Expand All @@ -403,7 +403,7 @@ Setting up a switch using topic prefix and abbreviated configuration variable na
- State topic: `homeassistant/switch/irrigation/state`
- Configuration payload: `{"~": "homeassistant/switch/irrigation", "name": "garden", "cmd_t": "~/set", "stat_t": "~/state"}`

### Lighting
### Another example using abbreviations topic name and base topic

Setting up a [light that takes JSON payloads](/integrations/light.mqtt/#json-schema), with abbreviated configuration variable names:

Expand All @@ -425,78 +425,6 @@ Setting up a [light that takes JSON payloads](/integrations/light.mqtt/#json-sch
}
```

### Climate control

Setting up a climate integration (heat only):

- Configuration topic: `homeassistant/climate/livingroom/config`
- Configuration payload:

```json
{
"name":"Livingroom",
"mode_cmd_t":"homeassistant/climate/livingroom/thermostatModeCmd",
"mode_stat_t":"homeassistant/climate/livingroom/state",
"mode_stat_tpl":"{{value_json.mode}}",
"avty_t":"homeassistant/climate/livingroom/available",
"pl_avail":"online",
"pl_not_avail":"offline",
"temp_cmd_t":"homeassistant/climate/livingroom/targetTempCmd",
"temp_stat_t":"homeassistant/climate/livingroom/state",
"temp_stat_tpl":"{{value_json.target_temp}}",
"curr_temp_t":"homeassistant/climate/livingroom/state",
"curr_temp_tpl":"{{value_json.current_temp}}",
"min_temp":"15",
"max_temp":"25",
"temp_step":"0.5",
"modes":["off", "heat"]
}
```

- State topic: `homeassistant/climate/livingroom/state`
- State payload:

```json
{
"mode":"off",
"target_temp":"21.50",
"current_temp":"23.60"
}
```

### Presence detection (device tracker)

Setting up a device tracker:

- Configuration topic: `homeassistant/device_tracker/paulus/config`
- Example configuration payload:

```json
{
"name":"Paulus",
"state_topic": "homeassistant/device_tracker/paulus/state",
"payload_home": "home",
"payload_not_home": "not_home",
"source_type": "bluetooth"
}
```

- State topic: `homeassistant/device_tracker/paulus/state`
- Example state payload: `home` or `not_home` or `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: `homeassistant/device_tracker/paulus/attributes`
- Example attributes payload:

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

### Use object_id to influence the entity id


Expand Down
34 changes: 33 additions & 1 deletion source/_integrations/device_tracker.mqtt.markdown
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -234,7 +234,7 @@ You can use the command line tool `mosquitto_pub` shipped with `mosquitto` or th
To create the device_tracker:

```bash
mosquitto_pub -h 127.0.0.1 -t home-assistant/device_tracker/a4567d663eaf/config -m '{"state_topic": "a4567d663eaf/state", "name": "My Tracker", "payload_home": "home", "payload_not_home": "not_home"}'
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":
Expand All @@ -243,6 +243,38 @@ 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:

```bash
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:

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

To create the device_tracker with GPS coordinates support:

```bash
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", "json_attributes_topic": "a4567d663eaf/attributes"}'
```

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

```bash
mosquitto_pub -h 127.0.0.1 -t a4567d663eaf/state -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
Expand Down