mirror of
https://github.com/esphome/esphome-docs.git
synced 2025-01-13 20:11:53 +01:00
Add MQTT publish JSON action and subscribe JSON trigger (#60)
* Add MQTT publish JSON action and subscribe JSON trigger * Add lambda note * Cleanup
This commit is contained in:
parent
017a2a567b
commit
21780efc51
@ -55,6 +55,8 @@ Configuration variables:
|
||||
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:
|
||||
@ -270,8 +272,8 @@ Configuration variables:
|
||||
|
||||
.. _mqtt-on_message:
|
||||
|
||||
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>`
|
||||
@ -293,11 +295,6 @@ 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.
|
||||
|
||||
@ -316,6 +313,59 @@ Configuration variables:
|
||||
then:
|
||||
- # ...
|
||||
|
||||
.. _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.
|
||||
|
||||
.. _mqtt-publish_action:
|
||||
|
||||
``mqtt.publish`` Action
|
||||
@ -350,6 +400,58 @@ Configuration options:
|
||||
- **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
|
||||
|
||||
// in lambda, parameters: <TOPIC>, <PAYLOAD>, <QoS>, <retain>
|
||||
id(mqtt_client).publish("the/topic", "The Payload", 0, false);
|
||||
|
||||
.. _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``.
|
||||
|
||||
See Also
|
||||
--------
|
||||
|
||||
|
@ -293,6 +293,7 @@ All Triggers
|
||||
------------
|
||||
|
||||
- :ref:`mqtt.on_message <mqtt-on_message>`
|
||||
- :ref:`mqtt.on_json_message <mqtt-on_json_message>`
|
||||
- :ref:`sensor.on_value <sensor-on_value>`
|
||||
- :ref:`sensor.on_value_range <sensor-on_value_range>`
|
||||
- :ref:`sensor.on_raw_value <sensor-on_raw_value>`
|
||||
@ -312,6 +313,7 @@ All Actions
|
||||
- :ref:`lambda <lambda_action>`
|
||||
- :ref:`if <if_action>`
|
||||
- :ref:`mqtt.publish <mqtt-publish_action>`
|
||||
- :ref:`mqtt.publish_json <mqtt-publish_json_action>`
|
||||
- :ref:`switch.toggle <switch-toggle_action>`
|
||||
- :ref:`switch.turn_off <switch-turn_off_action>`
|
||||
- :ref:`switch.turn_on <switch-turn_on_action>`
|
||||
|
Loading…
Reference in New Issue
Block a user