esphome-docs/components/sensor/template.rst

92 lines
2.5 KiB
ReStructuredText
Raw Normal View History

2018-06-01 18:10:00 +02:00
Template Sensor
===============
2018-11-14 22:12:27 +01:00
.. seo::
2019-02-16 23:25:23 +01:00
:description: Instructions for setting up template sensors with ESPHome.
:image: description.svg
2018-11-14 22:12:27 +01:00
2018-06-01 18:10:00 +02:00
The ``template`` sensor platform allows you to create a sensor with templated values
using :ref:`lambdas <config-lambda>`.
.. code-block:: yaml
2018-06-01 18:10:00 +02:00
# Example configuration entry
sensor:
- platform: template
name: "Template Sensor"
2019-01-06 18:56:14 +01:00
lambda: |-
if (id(some_binary_sensor).state) {
2018-06-01 18:10:00 +02:00
return 42.0;
} else {
return 0.0;
}
2019-01-06 18:56:14 +01:00
update_interval: 60s
2018-06-01 18:10:00 +02:00
Possible return values for the lambda:
- ``return <FLOATING_POINT_NUMBER>;`` the new value for the sensor.
- ``return NAN;`` if the state should be considered invalid to indicate an error (advanced).
- ``return {};`` if you don't want to publish a new state (advanced).
Configuration variables:
2018-08-24 22:44:01 +02:00
------------------------
2018-06-01 18:10:00 +02:00
2018-10-20 15:21:24 +02:00
- **name** (**Required**, string): The name of the sensor.
2018-06-01 18:10:00 +02:00
- **lambda** (*Optional*, :ref:`lambda <config-lambda>`):
Lambda to be evaluated every update interval to get the new value of the sensor
- **update_interval** (*Optional*, :ref:`config-time`): The interval to publish the value of the
sensor, either the result of the lambda function or if no lambda function the last value
published using the publish action. Defaults to ``60s``.
2019-02-07 18:07:16 +01:00
- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation.
2019-02-17 12:28:17 +01:00
- All other options from :ref:`Sensor <config-sensor>`.
2018-06-01 18:10:00 +02:00
2019-02-16 23:25:23 +01:00
.. _sensor-template-publish_action:
``sensor.template.publish`` Action
----------------------------------
You can also publish a state to a template sensor from elsewhere in your YAML file
with the ``sensor.template.publish`` action.
.. code-block:: yaml
# Example configuration entry
sensor:
- platform: template
name: "Template Sensor"
id: template_sens
# in some trigger
on_...:
- sensor.template.publish:
id: template_sens
state: 42.0
# Templated
- sensor.template.publish:
id: template_sens
state: !lambda 'return 42.0;'
Configuration options:
- **id** (**Required**, :ref:`config-id`): The ID of the template sensor.
- **state** (**Required**, float, :ref:`templatable <config-templatable>`):
The state to publish.
2018-11-14 22:12:27 +01:00
.. note::
2019-02-16 23:25:23 +01:00
This action can also be written in lambdas:
2018-11-14 22:12:27 +01:00
.. code-block:: cpp
2018-11-14 22:12:27 +01:00
2019-02-16 23:25:23 +01:00
id(template_sens).publish_state(42.0);
2018-11-14 22:12:27 +01:00
2018-06-01 18:10:00 +02:00
See Also
2018-08-24 22:44:01 +02:00
--------
2018-06-01 18:10:00 +02:00
- :ref:`sensor-filters`
- :ref:`automation`
2019-05-12 22:44:59 +02:00
- :apiref:`template/sensor/template_sensor.h`
- :ghedit:`Edit`