mirror of
https://github.com/esphome/esphome-docs.git
synced 2024-06-29 11:06:02 +02:00
136 lines
3.8 KiB
ReStructuredText
136 lines
3.8 KiB
ReStructuredText
Text Sensor Component
|
|
=====================
|
|
|
|
.. seo::
|
|
:description: Instructions for setting up text sensors that represent their state as a string of text.
|
|
:image: folder-open.png
|
|
|
|
Text sensors are a lot like normal :doc:`sensors </components/sensor/index>`.
|
|
But where the "normal" sensors only represent sensors that output **numbers**, this
|
|
component can represent any *text*.
|
|
|
|
.. _config-text_sensor:
|
|
|
|
Base Text Sensor Configuration
|
|
------------------------------
|
|
|
|
.. code-block:: yaml
|
|
|
|
# Example sensor configuration
|
|
name: Livingroom Temperature
|
|
|
|
# Optional variables:
|
|
icon: "mdi:water-percent"
|
|
|
|
Configuration variables:
|
|
|
|
- **name** (**Required**, string): The name for the sensor.
|
|
- **icon** (*Optional*, icon): Manually set the icon to use for the sensor in the frontend.
|
|
- **internal** (*Optional*, boolean): Mark this component as internal. Internal components will
|
|
not be exposed to the frontend (like Home Assistant). Only specifying an ``id`` without
|
|
a ``name`` will implicitly set this to true.
|
|
- **disabled_by_default** (*Optional*, boolean): If true, then this entity should not be added to any client's frontend,
|
|
(usually Home Assistant) without the user manually enabling it (via the Home Assistant UI).
|
|
Requires Home Assistant 2021.9 or newer. Defaults to ``false``.
|
|
- If MQTT enabled, All other options from :ref:`MQTT Component <config-mqtt-component>`.
|
|
|
|
Automations:
|
|
|
|
- **on_value** (*Optional*, :ref:`Automation <automation>`): An automation to perform
|
|
when a new value is published. See :ref:`text_sensor-on_value`.
|
|
|
|
Text Sensor Automation
|
|
----------------------
|
|
|
|
You can access the most recent state of the sensor in :ref:`lambdas <config-lambda>` using
|
|
``id(sensor_id).state``.
|
|
|
|
.. _text_sensor-on_value:
|
|
|
|
``on_value``
|
|
************
|
|
|
|
This automation will be triggered when a new value is published.
|
|
In :ref:`Lambdas <config-lambda>` you can get the value from the trigger with ``x``.
|
|
|
|
.. code-block:: yaml
|
|
|
|
text_sensor:
|
|
- platform: version
|
|
# ...
|
|
on_value:
|
|
then:
|
|
- lambda: |-
|
|
ESP_LOGD("main", "The current version is %s", x.c_str());
|
|
|
|
Configuration variables: See :ref:`Automation <automation>`.
|
|
|
|
.. _text_sensor-state_condition:
|
|
|
|
``text_sensor.state`` Condition
|
|
-------------------------------
|
|
|
|
This :ref:`Condition <config-condition>` allows you to check if a given text sensor
|
|
has a specific state.
|
|
|
|
.. code-block:: yaml
|
|
|
|
on_...:
|
|
- if:
|
|
condition:
|
|
# Checks if "my_text_sensor" has state "Hello World"
|
|
text_sensor.state:
|
|
id: my_text_sensor
|
|
state: 'Hello World'
|
|
|
|
Configuration variables:
|
|
|
|
- **id** (**Required**, :ref:`config-id`): The text sensor ID.
|
|
- **state** (**Required**, :ref:`templatable <config-templatable>`, string): The state to compare
|
|
to.
|
|
|
|
.. note::
|
|
|
|
This condition can also be expressed in :ref:`lambdas <config-lambda>`:
|
|
|
|
.. code-block:: cpp
|
|
|
|
if (id(my_text_sensor).state == "Hello World") {
|
|
// do something
|
|
}
|
|
|
|
.. _text_sensor-lambda_calls:
|
|
|
|
lambda calls
|
|
************
|
|
|
|
From :ref:`lambdas <config-lambda>`, you can call several methods on all text sensors to do some
|
|
advanced stuff (see the full API Reference for more info).
|
|
|
|
- ``publish_state()``: Manually cause the sensor to push out a value.
|
|
|
|
.. code-block:: cpp
|
|
|
|
// Within lambda, push a value of "Hello World"
|
|
id(my_sensor).publish_state("Hello World");
|
|
|
|
- ``.state``: Retrieve the current value of the sensor as an ``std::string`` object.
|
|
|
|
.. code-block:: cpp
|
|
|
|
// For example, create a custom log message when a value is received:
|
|
std::string val = id(my_sensor).state;
|
|
ESP_LOGI("main", "Value of my sensor: %s", val.c_str());
|
|
|
|
See Also
|
|
--------
|
|
|
|
- :apiref:`text_sensor/text_sensor.h`
|
|
- :ghedit:`Edit`
|
|
|
|
.. toctree::
|
|
:maxdepth: 1
|
|
:glob:
|
|
|
|
*
|