Use homeassistant/ as discovery prefix in mqtt examples (#27563)

Co-authored-by: c0ffeeca7 <38767475+c0ffeeca7@users.noreply.github.com>
This commit is contained in:
Jan Bouwhuis 2023-05-29 17:41:02 +02:00 committed by GitHub
parent 3361ce43c2
commit 2c00066325
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23

View File

@ -109,7 +109,7 @@ With a secure broker connection it is possible to use a client certificate for a
#### Using WebSockets as transport
You can select `websockets` as transport method if your MQTT broker supports it. When you select `websockets` and click `NEXT` you will be able to add a WebSockets path (default = `/` and WebSockets headers (optional). The target WebSockets URI: `ws://{broker}:{port}{WebSockets path}` is built with `broker`, `port` and `ws_path` (WebSocket path) settings.
You can select `websockets` as transport method if your MQTT broker supports it. When you select `websockets` and click `NEXT`, you will be able to add a WebSockets path (default = `/`) and WebSockets headers (optional). The target WebSockets URI: `ws://{broker}:{port}{WebSockets path}` is built with `broker`, `port` and `ws_path` (WebSocket path) settings.
To configure the WebSocketS headers supply a valid JSON dictionary string. E.g. `{ "Authorization": "token" , "x-header": "some header"}`. The default transport method is `tcp`. The WebSockets transport can be secured using TLS and optionally using user credentials or a client certificate.
<div class='note'>
@ -140,13 +140,13 @@ MQTT Birth and Last Will messages can be customized or disabled from the UI. To
The `mosquitto` broker package ships commandline tools (often as `*-clients` package) to send and receive MQTT messages. For sending test messages to a broker running on `localhost` check the example below:
```bash
mosquitto_pub -h 127.0.0.1 -t home-assistant/switch/1/on -m "Switch is ON"
mosquitto_pub -h 127.0.0.1 -t homeassistant/switch/1/on -m "Switch is ON"
```
Another way to send MQTT messages manually is to use the "MQTT" integration in the frontend. Choose "Settings" on the left menu, click "Devices & Services", and choose "Configure" in the "Mosquitto broker" tile. Enter something similar to the example below into the "topic" field under "Publish a packet" and press "PUBLISH" .
```bash
home-assistant/switch/1/power
homeassistant/switch/1/power
```
and in the Payload field
@ -155,23 +155,23 @@ and in the Payload field
ON
```
In the "Listen to a topic" field, type `#` to see everything, or "home-assistant/switch/#" to just follow a published topic, then press "START LISTENING". The messages should appear similar to the text below:
In the "Listen to a topic" field, type `#` to see everything, or "homeassistant/switch/#" to just follow a published topic, then press "START LISTENING". The messages should appear similar to the text below:
```bash
Message 23 received on home-assistant/switch/1/power/stat/POWER at 12:16 PM:
Message 23 received on homeassistant/switch/1/power/stat/POWER at 12:16 PM:
ON
QoS: 0 - Retain: false
Message 22 received on home-assistant/switch/1/power/stat/RESULT at 12:16 PM:
Message 22 received on homeassistant/switch/1/power/stat/RESULT at 12:16 PM:
{
"POWER": "ON"
}
QoS: 0 - Retain: false
```
For reading all messages sent on the topic `home-assistant` to a broker running on localhost:
For reading all messages sent on the topic `homeassistant` to a broker running on localhost:
```bash
mosquitto_sub -h 127.0.0.1 -v -t "home-assistant/#"
mosquitto_sub -h 127.0.0.1 -v -t "homeassistant/#"
```
## MQTT Discovery
@ -218,6 +218,7 @@ The discovery topic needs to follow a specific format:
<discovery_prefix>/<component>/[<node_id>/]<object_id>/config
```
- `<discovery_prefix>`: The Discovery Prefix defaults to `homeassistant`. This prefix can be [changed](#discovery-options).
- `<component>`: One of the supported MQTT components, eg. `binary_sensor`.
- `<node_id>` (*Optional*): ID of the node providing the topic, this is not used by Home Assistant but may be used to structure the MQTT topic. The ID of the node must only consist of characters from the character class `[a-zA-Z0-9_-]` (alphanumerics, underscore and hyphen).
- `<object_id>`: The ID of the device. This is only to allow for separate topics for each device and is not used for the `entity_id`. The ID of the device must only consist of characters from the character class `[a-zA-Z0-9_-]` (alphanumerics, underscore and hyphen).
@ -784,14 +785,14 @@ You must include either `topic` or `topic_template`, but not both. If providing
</p>
```yaml
topic: home-assistant/light/1/command
topic: homeassistant/light/1/command
payload: on
```
{% raw %}
```yaml
topic: home-assistant/light/1/state
topic: homeassistant/light/1/state
payload_template: "{{ states('device_tracker.paulus') }}"
```
@ -800,7 +801,7 @@ payload_template: "{{ states('device_tracker.paulus') }}"
{% raw %}
```yaml
topic_template: "home-assistant/light/{{ states('sensor.light_active') }}/state"
topic_template: "homeassistant/light/{{ states('sensor.light_active') }}/state"
payload_template: "{{ states('device_tracker.paulus') }}"
```
@ -811,7 +812,7 @@ If you want to send JSON using the YAML editor then you need to format/escape
it properly. Like:
```yaml
topic: home-assistant/light/1/state
topic: homeassistant/light/1/state
payload: "{\"Status\":\"off\", \"Data\":\"something\"}"`
```
@ -844,7 +845,7 @@ data:
Example of how to use `qos` and `retain`:
```yaml
topic: home-assistant/light/1/command
topic: homeassistant/light/1/command
payload: on
qos: 2
retain: true