From 2815f5a163db5dff1650f1864b2786244067ee8a Mon Sep 17 00:00:00 2001 From: Jesse Hills <3060199+jesserockz@users.noreply.github.com> Date: Wed, 25 Oct 2023 22:00:37 +1300 Subject: [PATCH] Add text component docs (#3293) --- components/copy.rst | 18 +++++ components/index.rst | 1 + components/text/index.rst | 144 +++++++++++++++++++++++++++++++++++ components/text/template.rst | 50 ++++++++++++ index.rst | 8 ++ 5 files changed, 221 insertions(+) create mode 100644 components/text/index.rst create mode 100644 components/text/template.rst diff --git a/components/copy.rst b/components/copy.rst index 3e4fe4a46..93f21c6d4 100644 --- a/components/copy.rst +++ b/components/copy.rst @@ -193,6 +193,24 @@ Configuration variables: - **name** (**Required**, string): The name of the text sensor. - All other options from :ref:`Text Sensor `. +Copy Text +--------- + +.. code-block:: yaml + + # Example configuration entry + text: + - platform: copy + source_id: source_text + name: "Copy of source_text" + +Configuration variables: +************************ + +- **source_id** (**Required**, :ref:`config-id`): The text that should be mirrored. +- **name** (**Required**, string): The name of the number. +- All other options from :ref:`Text `. + See Also -------- diff --git a/components/index.rst b/components/index.rst index d26885a1a..30de83969 100644 --- a/components/index.rst +++ b/components/index.rst @@ -27,4 +27,5 @@ Components speaker/index time/index alarm_control_panel/index + text/index * diff --git a/components/text/index.rst b/components/text/index.rst new file mode 100644 index 000000000..b5f86806c --- /dev/null +++ b/components/text/index.rst @@ -0,0 +1,144 @@ +Text Component +============== + +.. seo:: + :description: Instructions for setting up text components in ESPHome. + :image: folder-open.svg + +ESPHome has support for components to create a text entity. A text entity is +like a ``text_sensor`` that can read a value from a device, but is useful when that value +can be set by the user/frontend. + +.. note:: + + Home Assistant Core 2023.11 or higher is required for ESPHome text entities to work. + +.. _config-text: + +Base Text Configuration +----------------------- + +All texts in ESPHome have a name and an optional icon. + +.. code-block:: yaml + + # Example text configuration + name: Livingroom Text + + # Optional variables: + icon: "mdi:cursor-text" + +Configuration variables: + +- **id** (*Optional*, string): Manually specify the ID for code generation. At least one of **id** and **name** must be specified. +- **name** (**Required**, string): The name for the text. + + .. note:: + + If you have a :ref:`friendly_name ` set for your device and + you want the text to use that name, you can set ``name: None``. + +- **icon** (*Optional*, icon): Manually set the icon to use for the text 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). + Defaults to ``false``. +- **entity_category** (*Optional*, string): The category of the entity. + See https://developers.home-assistant.io/docs/core/entity/#generic-properties + for a list of available options. Set to ``""`` to remove the default entity category. +- **mode** (**Required**, string): Defines how the text should be displayed in the frontend. + One of ``text`` or ``password``. + +Automations: + +- **on_value** (*Optional*, :ref:`Automation `): An automation to perform + when a new value is published. See :ref:`text-on_value`. + +MQTT Options: + +- All other options from :ref:`MQTT Component `. + +Text Automation +--------------- + +You can access the most recent state of the text in :ref:`lambdas ` using +``id(text_id).state``. + +.. _text-on_value: + +``on_value`` +************ + +This automation will be triggered when a new value is published. In :ref:`Lambdas ` +you can get the value from the trigger with ``x``. + +.. code-block:: yaml + + text: + - platform: template + # ... + on_value: + then: + - logger.log: + format: "%s" + args: ["x.c_str()"] + +Configuration variables: See :ref:`Automation `. + +.. _text-set_action: + +``text.set`` Action +******************* + +This is an :ref:`Action ` for setting a text state. + +.. code-block:: yaml + + - text.set: + id: my_text + value: "Hello World" + +Configuration variables: + +- **id** (**Required**, :ref:`config-id`): The ID of the text to set. +- **value** (**Required**, string, :ref:`templatable `): + The value to set the text to. + +.. _text-lambda_calls: + +lambda calls +************ + +From :ref:`lambdas `, you can call certain methods on all texts to do some +advanced stuff (see the full API Reference for more info). + +- ``.make_call()``: Make a call for updating the text value. + + .. code-block:: cpp + + // Within lambda, push a value of 42 + auto call = id(my_text).make_call(); + call.set_value("Hello World"); + call.perform(); + +- ``.state``: Retrieve the current value of the text. + + .. code-block:: cpp + + // For example, create a custom log message when a value is received: + ESP_LOGI("main", "Value of my text: %s", id(my_text).state.c_str()); + +See Also +-------- + +- :apiref:`Text ` +- :apiref:`TextCall ` +- :ghedit:`Edit` + +.. toctree:: + :maxdepth: 1 + :glob: + + * diff --git a/components/text/template.rst b/components/text/template.rst new file mode 100644 index 000000000..cb174bfdf --- /dev/null +++ b/components/text/template.rst @@ -0,0 +1,50 @@ +Template Text +============= + +.. seo:: + :description: Instructions for setting up template texts with ESPHome. + :image: description.svg + +The ``template`` text platform allows you to create a text with templated values +using :ref:`lambdas `. + +.. code-block:: yaml + + # Example configuration entry + text: + - platform: template + name: "Template text" + optimistic: true + min_length: 0 + max_length: 100 + mode: text + +Configuration variables: +------------------------ + +- **min_lenngth** (**Required**, float): The minimum length this text can be. +- **max_length** (**Required**, float): The maximum length this text can be. +- **lambda** (*Optional*, :ref:`lambda `): + Lambda to be evaluated every update interval to get the current value of the text. +- **set_action** (*Optional*, :ref:`Action `): The action that should + be performed when the remote (like Home Assistant's frontend) requests to set the + text value. The new value is available to lambdas in the ``x`` variable. +- **update_interval** (*Optional*, :ref:`config-time`): The interval on which to update the text + by executing the ``lambda``. Defaults to ``60s``. +- **optimistic** (*Optional*, boolean): Whether to operate in optimistic mode - when in this mode, + any command sent to the template text will immediately update the reported state. + Cannot be used with ``lambda``. Defaults to ``false``. +- **restore_value** (*Optional*, boolean): Saves and loads the state to RTC/Flash. + Cannot be used with ``lambda``. Defaults to ``false``. +- **initial_value** (*Optional*, float): The value to set the state to on setup if not + restored with ``restore_value``. + Cannot be used with ``lambda``. +- All other options from :ref:`Text `. + + +See Also +-------- + +- :ref:`automation` +- :apiref:`template/text/template_text.h` +- :ghedit:`Edit` diff --git a/index.rst b/index.rst index d16fdcdec..5d48c9171 100644 --- a/index.rst +++ b/index.rst @@ -746,6 +746,14 @@ Lock Components Generic Output Lock, components/lock/output, upload.svg, dark-invert Template Lock, components/lock/template, description.svg, dark-invert +Text Components +--------------- + +.. imgtable:: + + Text Core, components/text/index, folder-open.svg, dark-invert + Template Text, components/text/template, description.svg, dark-invert + Media Player Components -----------------------