mirror of
https://github.com/esphome/esphome-docs.git
synced 2024-08-31 00:19:54 +02:00
353 lines
13 KiB
ReStructuredText
353 lines
13 KiB
ReStructuredText
MQTT Client Component
|
||
=====================
|
||
|
||
The MQTT Client Component sets up the MQTT connection to your broker and
|
||
is currently required for esphomelib to work. In most cases, you will
|
||
just be able to copy over the `MQTT
|
||
section <https://www.home-assistant.io/components/mqtt/>`__ of your Home
|
||
Assistant configuration.
|
||
|
||
.. code:: yaml
|
||
|
||
# Example configuration entry
|
||
mqtt:
|
||
broker: 10.0.0.2
|
||
username: livingroom
|
||
password: MyMQTTPassword
|
||
|
||
Configuration variables:
|
||
------------------------
|
||
|
||
- **broker** (**Required**, string): The host of your MQTT broker.
|
||
- **port** (*Optional*, int): The port to connect to. Defaults to 1883.
|
||
- **username** (*Optional*, string): The username to use for
|
||
authentication. Empty (the default) means no authentication.
|
||
- **password** (*Optional*, string): The password to use for
|
||
authentication. Empty (the default) means no authentication.
|
||
- **client_id** (*Optional*, string): The client id to use for opening
|
||
connections. See :ref:`mqtt-defaults` for more information.
|
||
- **discovery** (*Optional*, boolean): If Home Assistant automatic
|
||
discovery should be enabled. Defaults to ``True``.
|
||
- **discovery_retain** (*Optional*, boolean): Whether to retain MQTT
|
||
discovery messages so that entities are added automatically on Home
|
||
Assistant restart. Defaults to ``True``.
|
||
- **discovery_prefix** (*Optional*, string): The prefix to use for Home
|
||
Assistant’s MQTT discovery. Should not contain trailing slash.
|
||
Defaults to ``homeassistant``.
|
||
- **topic_prefix** (*Optional*, string): The prefix used for all MQTT
|
||
messages. Should not contain trailing slash. Defaults to
|
||
``<APP_NAME>``.
|
||
- **log_topic** (*Optional*, :ref:`mqtt-message`) The topic to send MQTT log
|
||
messages to.
|
||
- **birth_message** (*Optional*, :ref:`mqtt-message`): The message to send when
|
||
a connection to the broker is established. See :ref:`mqtt-last_will_birth` for more information.
|
||
- **will_message** (*Optional*, :ref:`mqtt-message`): The message to send when
|
||
the MQTT connection is dropped. See :ref:`mqtt-last_will_birth` for more information.
|
||
- **shutdown_message** (*Optional*, :ref:`mqtt-message`): The message to send when
|
||
the node shuts down and the connection is closed cleanly. See :ref:`mqtt-last_will_birth` for more information.
|
||
- **ssl_fingerprints** (*Optional*, list): Only on ESP8266. A list of SHA1 hashes used
|
||
for verifying SSL connections. See :ref:`mqtt-ssl_fingerprints`
|
||
for more information.
|
||
- **reboot_timeout** (*Optional*, :ref:`time <config-time>`): The amount of time to wait before rebooting when no
|
||
MQTT connection exists. Can be disabled by setting this to ``0s``. Defaults to ``60s``.
|
||
- **keepalive** (*Optional*, :ref:`config-time`): The time
|
||
to keep the MQTT socket alive, decreasing this can help with overall stability due to more
|
||
WiFi traffic with more pings. Defaults to 15 seconds.
|
||
- **on_message** (*Optional*, :ref:`Automation <automation>`): An action to be
|
||
performed when a message on a specific MQTT topic is received. See :ref:`mqtt-on_message`.
|
||
- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation.
|
||
|
||
.. _mqtt-message:
|
||
|
||
MQTTMessage
|
||
-----------
|
||
|
||
With the MQTT Message schema you can tell esphomeyaml how a specific MQTT message should be sent.
|
||
It is used in several places like last will and birth messages or MQTT log options.
|
||
|
||
.. code:: yaml
|
||
|
||
# Simple:
|
||
some_option: topic/to/send/to
|
||
|
||
# Disable:
|
||
some_option:
|
||
|
||
# Advanced:
|
||
some_option:
|
||
topic: topic/to/send/to
|
||
payload: online
|
||
qos: 0
|
||
retain: True
|
||
|
||
|
||
Configuration options:
|
||
|
||
- **topic** (*Required*, string): The MQTT topic to publish the message.
|
||
- **payload** (*Required*, string): The message content. Will be filled by the actual payload with some
|
||
options, like log_topic.
|
||
- **qos** (*Optional*, int): The `Quality of
|
||
Service <https://www.hivemq.com/blog/mqtt-essentials-part-6-mqtt-quality-of-service-levels>`__
|
||
level of the topic. Defaults to 0.
|
||
- **retain** (*Optional*, boolean): If the published message should
|
||
have a retain flag on or not. Defaults to ``True``.
|
||
|
||
|
||
Using with Home Assistant
|
||
-------------------------
|
||
|
||
Using esphomelib with Home Assistant is easy, simply setup an MQTT
|
||
broker (like `mosquitto <https://mosquitto.org/>`__) and point both your
|
||
Home Assistant installation and esphomelib to that broker. Next, enable
|
||
discovery in your Home Assistant configuration with the following:
|
||
|
||
.. code:: yaml
|
||
|
||
# Example Home Assistant configuration.yaml entry
|
||
mqtt:
|
||
broker: ...
|
||
discovery: True
|
||
|
||
And that should already be it 🎉 All devices defined through
|
||
esphomelib/esphomeyaml should show up automatically in the entities
|
||
section of Home Assistant.
|
||
|
||
When adding new entities, you might run into trouble with old entities
|
||
still appearing in Home Assistant’s front-end. This is because in order
|
||
to have Home Assistant “discover” your devices on restart, all discovery
|
||
MQTT messages need to be retained. Therefore the old entities will also
|
||
re-appear on every Home Assistant restart even though they’re in
|
||
eshomeyaml anymore.
|
||
|
||
To fix this, esphomeyaml has a simple helper script that purges stale
|
||
retained messages for you:
|
||
|
||
.. code:: bash
|
||
|
||
esphomeyaml configuration.yaml clean-mqtt
|
||
|
||
This will remove all retained messages with the topic
|
||
``<DISCOVERY_PREFIX>/+/NODE_NAME/#``. If you want to purge on another
|
||
topic, simply add ``--topic <your_topic>`` to the command.
|
||
|
||
.. _mqtt-defaults:
|
||
|
||
Defaults
|
||
--------
|
||
|
||
By default, esphomelib will prefix all messages with your node name or
|
||
``topic_prefix`` if you have specified it manually. The client id will
|
||
automatically be generated by using your node name and adding the MAC
|
||
address of your device to it. Next, discovery is enabled by default with
|
||
Home Assistant’s default prefix ``homeassistant``.
|
||
|
||
If you want to prefix all MQTT messages with a different prefix, like
|
||
``home/living_room``, you can specify a custom ``topic_prefix`` in the
|
||
configuration. That way, you can use your existing wildcards like
|
||
``home/+/#`` together with esphomelib. All other features of esphomelib
|
||
(like availability) should still work correctly.
|
||
|
||
.. _mqtt-last_will_birth:
|
||
|
||
Last Will And Birth Messages
|
||
----------------------------
|
||
|
||
esphomelib (and esphomeyaml) uses the `last will
|
||
testament <https://www.hivemq.com/blog/mqtt-essentials-part-9-last-will-and-testament>`__
|
||
and birth message feature of MQTT to achieve availability reporting for
|
||
Home Assistant. If the node is not connected to MQTT, Home Assistant
|
||
will show all its entities as unavailable (a feature 😉).
|
||
|
||
.. figure:: /esphomeyaml/components/images/mqtt-availability.png
|
||
:align: center
|
||
:width: 50.0%
|
||
|
||
By default, esphomelib will send a retained MQTT message to
|
||
``<TOPIC_PREFIX>/status`` with payload ``online``, and will tell the
|
||
broker to send a message ``<TOPIC_PREFIX>/status`` with payload
|
||
``offline`` if the connection drops.
|
||
|
||
You can change these messages by overriding the ``birth_message`` and
|
||
``will_message`` with the following options.
|
||
|
||
.. code:: yaml
|
||
|
||
mqtt:
|
||
# ...
|
||
birth_message:
|
||
topic: myavailability/topic
|
||
payload: online
|
||
will_message:
|
||
topic: myavailability/topic
|
||
payload: offline
|
||
|
||
- **birth_message** (*Optional*, :ref:`mqtt-message`)
|
||
- **will_message** (*Optional*, :ref:`mqtt-message`)
|
||
|
||
If the birth message and last will message have empty topics or topics
|
||
that are different from each other, availability reporting will be
|
||
disabled.
|
||
|
||
.. _mqtt-ssl_fingerprints:
|
||
|
||
SSL Fingerprints
|
||
----------------
|
||
|
||
On the ESP8266 you have the option to use SSL connections for MQTT. This feature
|
||
will get expanded to the ESP32 once the base library, AsyncTCP, supports it. Please
|
||
note that the SSL feature only checks the SHA1 hash of the SSL certificate to verify
|
||
the integrity of the connection, so every time the certificate changes, you'll have to
|
||
update the fingerprints variable. Additionally, SHA1 is known to be partially insecure
|
||
and with some computing power the fingerprint can be faked.
|
||
|
||
To get this fingerprint, first put the broker and port options in the configuration and
|
||
then run the ``mqtt-fingerprint`` script of esphomeyaml to get the certificate:
|
||
|
||
.. code:: bash
|
||
|
||
esphomeyaml livingroom.yaml mqtt-fingerprint
|
||
> SHA1 Fingerprint: a502ff13999f8b398ef1834f1123650b3236fc07
|
||
> Copy above string into mqtt.ssl_fingerprints section of livingroom.yaml
|
||
|
||
.. code:: yaml
|
||
|
||
mqtt:
|
||
# ...
|
||
ssl_fingerprints:
|
||
- a502ff13999f8b398ef1834f1123650b3236fc07
|
||
|
||
.. _config-mqtt-component:
|
||
|
||
MQTT Component Base Configuration
|
||
---------------------------------
|
||
|
||
All components in esphomelib that do some sort of communication through
|
||
MQTT can have some overrides for specific options.
|
||
|
||
.. code:: yaml
|
||
|
||
name: "Component Name"
|
||
# Optional variables:
|
||
retain: True
|
||
discovery: True
|
||
availability:
|
||
topic: livingroom/status
|
||
payload_available: online
|
||
payload_not_available: offline
|
||
state_topic: livingroom/custom_state_topic
|
||
command_topic: livingroom/custom_command_topic
|
||
|
||
Configuration variables:
|
||
|
||
- **name** (**Required**, string): The name to use for the MQTT
|
||
Component.
|
||
- **retain** (*Optional*, boolean): If all MQTT state messages should
|
||
be retained. Defaults to ``True``.
|
||
- **discovery** (*Optional*, boolean): Manually enable/disable
|
||
discovery for a component. Defaults to the global default.
|
||
- **availability** (*Optional*): Manually set what should be sent to
|
||
Home Assistant for showing entity availability. Default derived from
|
||
:ref:`global birth/last will message <mqtt-last_will_birth>`.
|
||
- **state_topic** (*Optional*, string): The topic to publish state
|
||
updates to. Defaults to
|
||
``<TOPIC_PREFIX>/<COMPONENT_TYPE>/<COMPONENT_NAME>/state``.
|
||
- **command_topic** (*Optional*, string): The topic to subscribe to for
|
||
commands from the remote. Defaults to
|
||
``<TOPIC_PREFIX>/<COMPONENT_TYPE>/<COMPONENT_NAME>/command``.
|
||
- **internal** (*Optional*, boolean): Mark this component as internal. Internal components will
|
||
not send any MQTT messages and can be used for :ref:`on-device automations <automation>`. Only
|
||
specifying an ``id`` without a ``name`` will implicitly set this to true.
|
||
|
||
.. warning::
|
||
|
||
When changing these options and you're using MQTT discovery, you will need to restart Home Assistant.
|
||
This is because Home Assistant only discovers a device once in every Home Assistant start.
|
||
|
||
.. _mqtt-on_message:
|
||
|
||
on_message
|
||
----------
|
||
|
||
With this configuration option you can write complex automations whenever an MQTT
|
||
message on a specific topic is received. To use the message content, use a :ref:`lambda <config-lambda>`
|
||
template, the message payload is available under the name ``x`` inside that lambda.
|
||
|
||
.. code:: yaml
|
||
|
||
mqtt:
|
||
# ...
|
||
on_message:
|
||
topic: my/custom/topic
|
||
qos: 0
|
||
then:
|
||
- switch.turn_on:
|
||
id: some_switch
|
||
|
||
Configuration variables:
|
||
|
||
- **topic** (**Required**, string): The MQTT topic to subscribe to and listen for MQTT
|
||
messages on. Every time a message with **this exact topic** is received, the automation will trigger.
|
||
|
||
|
||
.. note::
|
||
|
||
Currently the topic does not support MQTT wildcards like ``+`` or ``#``.
|
||
|
||
- **qos** (*Optional*, integer): The MQTT Quality of Service to subscribe to the topic with. Defaults
|
||
to 0.
|
||
|
||
.. note::
|
||
|
||
You can even specify multiple ``on_message`` triggers by using a YAML list:
|
||
|
||
.. code:: yaml
|
||
|
||
mqtt:
|
||
on_message:
|
||
- topic: some/topic
|
||
then:
|
||
- # ...
|
||
- topic: some/other/topic
|
||
then:
|
||
- # ...
|
||
|
||
.. _mqtt-publish_action:
|
||
|
||
``mqtt.publish`` Action
|
||
-----------------------
|
||
|
||
Publish an MQTT message on a topic using this action in automations.
|
||
|
||
.. code:: yaml
|
||
|
||
on_...:
|
||
then:
|
||
- mqtt.publish:
|
||
topic: some/topic
|
||
payload: "Something happened!"
|
||
|
||
# Templated:
|
||
- mqtt.publish:
|
||
topic: !lambda >-
|
||
if (id(reed_switch).value) return "topic1";
|
||
else return "topic2";
|
||
payload: !lambda >-
|
||
return id(reed_switch).value ? "YES" : "NO";
|
||
|
||
Configuration options:
|
||
|
||
- **topic** (*Required*, string, :ref:`templatable <config-templatable>`):
|
||
The MQTT topic to publish the message.
|
||
- **payload** (*Required*, string, :ref:`templatable <config-templatable>`): The message content.
|
||
- **qos** (*Optional*, int, :ref:`templatable <config-templatable>`): The `Quality of
|
||
Service <https://www.hivemq.com/blog/mqtt-essentials-part-6-mqtt-quality-of-service-levels>`__
|
||
level of the topic. Defaults to 0.
|
||
- **retain** (*Optional*, boolean, :ref:`templatable <config-templatable>`): If the published message should
|
||
have a retain flag on or not. Defaults to ``False``.
|
||
|
||
See Also
|
||
--------
|
||
|
||
- :doc:`API Reference </api/core/mqtt>`
|
||
- `Edit this page on GitHub <https://github.com/OttoWinter/esphomedocs/blob/current/esphomeyaml/components/mqtt.rst>`__
|