Upstream
/
esphome-docs
mirror of https://github.com/esphome/esphome-docs.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity
esphome-docs/esphomeyaml/components/mqtt.rst

505 lines
18 KiB
ReStructuredText
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

MQTT Client Component
=====================
.. seo::
:description: Instructions for setting up the MQTT client to communicate with the local network in esphomelib.
:image: mqtt.png
:keywords: MQTT
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 ``5min``.
- **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`.
- **on_json_message** (*Optional*, :ref:`Automation <automation>`): An action to be
performed when a JSON message on a specific MQTT topic is received. See :ref:`mqtt-on_json_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``.
The ``log_topic`` has an additional configuration option:
- **level** (*Optional*, string): The log level to use for MQTT logs. See
:ref:`logger-log_levels` for options.
.. _mqtt-using_with_home_assistant:
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
esphomeyaml 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`` Trigger
----------------------
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: 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.
- **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:
- # ...
.. note::
This action can also be used in :ref:`lambdas <config-lambda>`:
.. code:: cpp
App.get_mqtt_client()->subscribe("the/topic", [=](const std::string &payload) {
// do something with payload
});
.. _mqtt-on_json_message:
``on_json_message`` Trigger
---------------------------
With this configuration option you can write complex automations whenever a JSON-encoded MQTT
message is received. To use the message content, use a :ref:`lambda <config-lambda>`
template, the decoded message payload is available under the name ``x`` inside that lambda.
The ``x`` object is of type ``JsonObject`` by the `ArduinoJson <https://github.com/bblanchon/ArduinoJson>`__
library, and you can use all of the methods of that library to access data.
Basically, you can access elements by typing ``x["THE_KEY"]`` and save them into local variables.
Please note that it's a good idea to check if the key exists in the Json Object by calling
``containsKey`` first as the ESP will crash if an element that does not exist is accessed.
.. code:: yaml
mqtt:
# ...
on_json_message:
topic: the/topic
then:
- light.turn_on:
id: living_room_lights
transition_length: !lambda |-
int length = 1000;
if (x.containsKey("length"))
length = x["length"];
return length;
brightness: !lambda "return x["bright"];"
effect: !lambda |-
const char *effect = "None";
if (x.containsKey("effect"))
effect = x["effect"];
return effect;
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.
- **qos** (*Optional*, integer): The MQTT Quality of Service to subscribe to the topic with. Defaults
to 0.
.. note::
Due to the way this trigger works internally it is incompatible with certain actions and will
trigger a compile failure. For example with the ``delay`` action.
.. note::
This action can also be used in :ref:`lambdas <config-lambda>`:
.. code:: cpp
App.get_mqtt_client()->subscribe_json("the/topic", [=](JsonObject &root) {
// do something with JSON-decoded value root
});
.. _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).state) return "topic1";
else return "topic2";
payload: !lambda >-
return id(reed_switch).state ? "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``.
.. note::
This action can also be written in :ref:`lambdas <config-lambda>`:
.. code:: yaml
mqtt:
# Give the mqtt component an ID
id: mqtt_client
.. code:: cpp
id(mqtt_client).publish("the/topic", "The Payload");
.. _mqtt-publish_json_action:
``mqtt.publish_json`` Action
----------------------------
Publish a JSON-formatted MQTT message on a topic using this action in automations.
The JSON message will be constructed using the `ArduinoJson <https://github.com/bblanchon/ArduinoJson>`__ library.
In the ``payload`` option you have access to a ``root`` object which will represents the base object
of the JSON message. You can assign values to keys by using the ``root["KEY_NAME"] = VALUE;`` syntax
as seen below.
.. code:: yaml
on_...:
then:
- mqtt.publish_json:
topic: the/topic
payload: |-
root["key"] = id(my_sensor).value;
root["greeting"] = "Hello World";
# Will produce:
# {"key": 42.0, "greeting": "Hello World"}
Configuration options:
- **topic** (*Required*, string, :ref:`templatable <config-templatable>`):
The MQTT topic to publish the message.
- **payload** (*Required*, :ref:`lambda <config-lambda>`): The message content.
- **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 ``False``.
.. note::
This action can also be written in :ref:`lambdas <config-lambda>`:
.. code:: yaml
mqtt:
# Give the mqtt component an ID
id: mqtt_client
.. code:: cpp
id(mqtt_client).publish_json("the/topic", [=](JsonObject &root) {
root["something"] = id(my_sensor).value;
});
See Also
--------
- :doc:`API Reference </api/core/mqtt>`
- `Edit this page on GitHub <https://github.com/OttoWinter/esphomedocs/blob/current/esphomeyaml/components/mqtt.rst>`__
.. disqus::
Reference in New Issue View Git Blame Copy Permalink