text sensor filter documentation (#1497)

* text sensor filter documentation

* document on raw value automation

* Apply suggestions from code review

thanks Oxan!

Co-authored-by: Oxan van Leeuwen <oxan@oxanvanleeuwen.nl>

Co-authored-by: Oxan van Leeuwen <oxan@oxanvanleeuwen.nl>
This commit is contained in:
WeekendWarrior1 2021-09-30 07:25:11 +10:00 committed by GitHub
parent 08d76a66aa
commit 479acf411b
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23

View File

@ -38,6 +38,121 @@ Automations:
- **on_value** (*Optional*, :ref:`Automation <automation>`): An automation to perform - **on_value** (*Optional*, :ref:`Automation <automation>`): An automation to perform
when a new value is published. See :ref:`text_sensor-on_value`. when a new value is published. See :ref:`text_sensor-on_value`.
- **on_raw_value** (*Optional*, :ref:`Automation <automation>`): An automation to perform
when a new value is received that hasn't passed through any filters. See :ref:`text_sensor-on_raw_value`.
.. _text_sensor-filters:
Text Sensor Filters
-------------------
ESPHome allows you to do some basic pre-processing of
text_sensor values before theyre sent to Home Assistant. This is for example
useful if you want to manipulate the text_sensor string in some fashion.
There are a lot of filters that sensors support. You define them by adding a ``filters``
block in the text_sensor configuration (at the same level as ``platform``; or inside each text_sensor block
for platforms with multiple sensors).
Filters are processed in the order they are defined in your configuration.
.. code-block:: yaml
# Example filters:
filters:
- to_upper:
- to_lower:
- append: "_prefix"
- prepend: "suffix_"
- substitute:
- "suf -> foo"
- "pre -> bar"
- lambda: return {"Hello World"};
``to_upper``
************
Converts all characters within a string to uppercase (only the English alphabet is supported at this time).
.. code-block:: yaml
# Example configuration entry
- platform: template
# ...
filters:
- to_upper:
``to_lower``
************
Converts all characters within a string to lowercase (only the English alphabet is supported at this time).
.. code-block:: yaml
# Example configuration entry
- platform: template
# ...
filters:
- to_lower:
``append``
**********
Adds a string to the end of the current string.
.. code-block:: yaml
# Example configuration entry
- platform: template
# ...
filters:
- append: "_prefix"
``prepend``
***********
Adds a string to the start of the current string.
.. code-block:: yaml
# Example configuration entry
- platform: template
# ...
filters:
- prepend: "suffix_"
``substitute``
**************
Search the current value of the text sensor for a string, and replace it with another string.
.. code-block:: yaml
# Example configuration entry
- platform: template
# ...
filters:
- substitute:
- "suf -> foo"
- "pre -> bar"
The arguments are a list of substitutions, each in the form ``TO_FIND -> REPLACEMENT``.
``lambda``
**********
Perform a advanced operations on the text sensor value. The input string is ``x`` and
the result of the lambda is used as the output (use ``return``).
.. code-block:: yaml
filters:
- lambda: |-
if (x == "Hello") {
return x + "bar";
} else {
return x + "foo";
}
Text Sensor Automation Text Sensor Automation
---------------------- ----------------------
@ -65,6 +180,26 @@ In :ref:`Lambdas <config-lambda>` you can get the value from the trigger with ``
Configuration variables: See :ref:`Automation <automation>`. Configuration variables: See :ref:`Automation <automation>`.
.. _text_sensor-on_raw_value:
``on_raw_value``
****************
This automation will be triggered when a new value is received that hasn't passed
through any filters. In :ref:`Lambdas <config-lambda>` you can get the value from the trigger with ``x``.
.. code-block:: yaml
text_sensor:
- platform: version
# ...
on_raw_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:
``text_sensor.state`` Condition ``text_sensor.state`` Condition