mirror of
https://github.com/esphome/esphome-docs.git
synced 2024-12-26 17:27:47 +01:00
67e445bc06
Example updates so it better represents how it should be used for novice users and work as expected.
374 lines
10 KiB
ReStructuredText
374 lines
10 KiB
ReStructuredText
Select Component
|
|
================
|
|
|
|
.. seo::
|
|
:description: Instructions for setting up select components in ESPHome.
|
|
:image: folder-open.svg
|
|
|
|
ESPHome has support for components to create a select entity. A select entity is
|
|
basically an option list that can be set by either yaml, hardware or the user/frontend.
|
|
|
|
.. note::
|
|
|
|
Home Assistant Core 2021.8 or higher is required for ESPHome select entities to work.
|
|
|
|
.. _config-select:
|
|
|
|
Base Select Configuration
|
|
-------------------------
|
|
|
|
All selects in ESPHome have a name and an optional icon.
|
|
|
|
.. code-block:: yaml
|
|
|
|
# Example select configuration
|
|
name: Livingroom Mood
|
|
id: my_select
|
|
|
|
# Optional variables:
|
|
icon: "mdi:emoticon-outline"
|
|
|
|
Configuration variables:
|
|
|
|
- **name** (**Required**, string): The name for the select.
|
|
- **icon** (*Optional*, icon): Manually set the icon to use for the select 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``.
|
|
- **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. Requires Home Assistant 2021.11 or newer.
|
|
Set to ``""`` to remove the default entity category.
|
|
|
|
Automations:
|
|
|
|
- **on_value** (*Optional*, :ref:`Automation <automation>`): An automation to perform
|
|
when a new value is published. See :ref:`select-on_value`.
|
|
|
|
MQTT Options:
|
|
|
|
- All other options from :ref:`MQTT Component <config-mqtt-component>`.
|
|
|
|
Select Automation
|
|
-----------------
|
|
|
|
You can access the most recent state of the select in :ref:`lambdas <config-lambda>` using
|
|
``id(select_id).state``.
|
|
For more information on using lambdas with select, see :ref:`select-lambda_calls`.
|
|
|
|
.. _select-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`` and the index offset of the selected value with ``i``.
|
|
|
|
.. code-block:: yaml
|
|
|
|
select:
|
|
- platform: template
|
|
# ...
|
|
on_value:
|
|
then:
|
|
- logger.log:
|
|
format: "Chosen option: %s (index %d)"
|
|
args: ["x.c_str()", "i"]
|
|
|
|
Configuration variables: See :ref:`Automation <automation>`.
|
|
|
|
.. _select-set_action:
|
|
|
|
``select.set`` Action
|
|
*********************
|
|
|
|
This is an :ref:`Action <config-action>` for setting the active option using an option value.
|
|
|
|
.. code-block:: yaml
|
|
|
|
- select.set:
|
|
id: my_select
|
|
option: "Happy"
|
|
|
|
Configuration variables:
|
|
|
|
- **id** (**Required**, :ref:`config-id`): The ID of the select to set.
|
|
- **option** (**Required**, string, :ref:`templatable <config-templatable>`):
|
|
The option to set the select to.
|
|
|
|
When a non-existing option value is used, a warning is logged and the state of
|
|
the select is left as-is.
|
|
|
|
.. _select-set_index_action:
|
|
|
|
``select.set_index`` Action
|
|
***************************
|
|
|
|
This is an :ref:`Action <config-action>` for setting the active option using its index offset.
|
|
|
|
.. code-block:: yaml
|
|
|
|
- select.set_index:
|
|
id: my_select
|
|
index: 3
|
|
|
|
Configuration variables:
|
|
|
|
- **id** (**Required**, :ref:`config-id`): The ID of the select to set.
|
|
- **index** (**Required**, int, :ref:`templatable <config-templatable>`):
|
|
The index offset of the option to be activated.
|
|
|
|
When a non-existing index value is used, a warning is logged and the state of
|
|
the select is left as-is.
|
|
|
|
.. _select-next_action:
|
|
|
|
``select.next`` Action
|
|
**********************
|
|
|
|
This is an :ref:`Action <config-action>` for selecting the next option in a select component.
|
|
|
|
.. code-block:: yaml
|
|
|
|
- select.next:
|
|
id: my_select
|
|
cycle: false
|
|
|
|
# Shorthand
|
|
- select.next: my_select
|
|
|
|
Configuration variables:
|
|
|
|
- **id** (**Required**, :ref:`config-id`): The ID of the select to set.
|
|
- **cycle** (*Optional*, boolean): Whether or not to jump back to the first option
|
|
of the select when the last option is currently selected. Defaults to ``true``.
|
|
|
|
.. _select-previous_action:
|
|
|
|
``select.previous`` Action
|
|
**************************
|
|
|
|
This is an :ref:`Action <config-action>` for selecting the previous option in
|
|
a select component.
|
|
|
|
.. code-block:: yaml
|
|
|
|
- select.previous:
|
|
id: my_select
|
|
cycle: true
|
|
|
|
# Shorthand
|
|
- select.previous: my_select
|
|
|
|
Configuration variables:
|
|
|
|
- **id** (**Required**, :ref:`config-id`): The ID of the select to set.
|
|
- **cycle** (*Optional*, boolean): Whether or not to jump to the last option
|
|
of the select when the first option is currently selected. Defaults to ``true``.
|
|
|
|
.. _select-first_action:
|
|
|
|
``select.first`` Action
|
|
***********************
|
|
|
|
This is an :ref:`Action <config-action>` for selecting the first option in
|
|
a select component.
|
|
|
|
.. code-block:: yaml
|
|
|
|
- select.first:
|
|
id: my_select
|
|
|
|
# Shorthand
|
|
- select.first: my_select
|
|
|
|
Configuration variables:
|
|
|
|
- **id** (**Required**, :ref:`config-id`): The ID of the select to set.
|
|
|
|
.. _select-last_action:
|
|
|
|
``select.last`` Action
|
|
**********************
|
|
|
|
This is an :ref:`Action <config-action>` for selecting the last option in
|
|
a select component.
|
|
|
|
.. code-block:: yaml
|
|
|
|
- select.last:
|
|
id: my_select
|
|
|
|
# Shorthand
|
|
- select.last: my_select
|
|
|
|
Configuration variables:
|
|
|
|
- **id** (**Required**, :ref:`config-id`): The ID of the select to set.
|
|
|
|
.. _select-operation_action:
|
|
|
|
``select.operation`` Action
|
|
***************************
|
|
|
|
This is an :ref:`Action <config-action>` that can be used to change the active
|
|
option in a select component (first, last, previous or next), using a generic
|
|
templatable action call.
|
|
|
|
.. code-block:: yaml
|
|
|
|
# Using values
|
|
- select.operation:
|
|
id: my_select
|
|
operation: Next
|
|
cycle: true
|
|
|
|
# Or templated (lambdas)
|
|
- select.operation:
|
|
id: my_select
|
|
operation: !lambda "return SELECT_OP_NEXT;"
|
|
cycle: !lambda "return true;"
|
|
|
|
Configuration variables:
|
|
|
|
- **id** (**Required**, :ref:`config-id`): The ID of the select to set.
|
|
- **operation** (**Required**, string, :ref:`templatable <config-templatable>`): The
|
|
operation to perform. One of ``FIRST``, ``LAST``, ``PREVIOUS`` or
|
|
``NEXT`` (case insensitive). When writing a lambda for this field, then return
|
|
one of the following enum values: ``SELECT_OP_FIRST``, ``SELECT_OP_LAST``,
|
|
``SELECT_OP_PREVIOUS`` or ``SELECT_OP_NEXT``.
|
|
- **cycle** (*Optional*, bool, :ref:`templatable <config-templatable>`):
|
|
Can be used for options ``NEXT`` and ``PREVIOUS`` to specify whether or not to
|
|
wrap around the options list when respectively the last or first option in
|
|
the select is currently active.
|
|
|
|
.. _select-lambda_calls:
|
|
|
|
lambda calls
|
|
************
|
|
|
|
From :ref:`lambdas <config-lambda>`, you can call several methods on all selects to do some
|
|
advanced stuff (see the full API Reference for more info).
|
|
|
|
- ``.make_call()``: Create a call for changing the select state.
|
|
|
|
.. code-block:: cpp
|
|
|
|
// Within lambda, select the "Happy" option.
|
|
auto call = id(my_select).make_call();
|
|
call.set_option("Happy");
|
|
call.perform();
|
|
|
|
Check the API reference for information on the methods that are available for
|
|
the ``SelectCall`` object. You can for example also use ``call.select_first()``
|
|
to select the first option or ``call.select_next(true)`` to select the next
|
|
option with the cycle feature enabled.
|
|
|
|
- ``.state``: Retrieve the currently selected option of the select.
|
|
|
|
.. code-block:: cpp
|
|
|
|
// For example, create a custom log message when an option is selected:
|
|
auto state = id(my_select).state.c_str();
|
|
ESP_LOGI("main", "Option of my select: %s", state);
|
|
|
|
- ``.size()``: Retrieve the number of options in the select.
|
|
|
|
.. code-block:: cpp
|
|
|
|
auto size = id(my_select).size();
|
|
ESP_LOGI("main", "Select has %d options", size);
|
|
|
|
- ``.index_of(<option value>)``: Retrieve the index offset for an option value.
|
|
|
|
.. code-block:: cpp
|
|
|
|
auto index = id(my_select).index_of("Happy");
|
|
if (index.has_value()) {
|
|
ESP_LOGI("main", "'Happy' is at index: %d", index.value());
|
|
} else {
|
|
ESP_LOGE("main", "There is no option 'Happy'");
|
|
}
|
|
|
|
- ``.active_index()``: Retrieve the index of the currently active option.
|
|
|
|
.. code-block:: cpp
|
|
|
|
auto index = id(my_select).active_index();
|
|
if (index.has_value()) {
|
|
ESP_LOGI("main", "Option at index %d is active", index.value());
|
|
} else {
|
|
ESP_LOGI("main", "No option is active");
|
|
}
|
|
|
|
- ``.at(<index offset>)``: Retrieve the option value at a given index offset.
|
|
|
|
.. code-block:: cpp
|
|
|
|
auto index = 1;
|
|
auto option = id(my_select).at(index);
|
|
if (option.has_value()) {
|
|
auto value = option.value();
|
|
ESP_LOGI("main", "Option at %d is: %s", index, value);
|
|
} else {
|
|
ESP_LOGE("main", "Index %d does not exist", index);
|
|
}
|
|
|
|
- ``.has_option(<option value>)``: Check if the select contains the given option value.
|
|
|
|
.. code-block:: cpp
|
|
|
|
auto option = "Happy";
|
|
if (id(my_select).has_option(option)) {
|
|
ESP_LOGI("main", "Select has option '%s'", option);
|
|
}
|
|
|
|
- ``.has_index(<index offset>)``: Check if the select contains an option value for the given index offset.
|
|
|
|
.. code-block:: cpp
|
|
|
|
auto index = 3;
|
|
if (id(my_select).has_index(index)) {
|
|
ESP_LOGI("main", "Select has index offset %d", index);
|
|
}
|
|
|
|
|
|
Example
|
|
-------
|
|
|
|
Setting up three options and set component state to selected option value.
|
|
|
|
.. code-block:: yaml
|
|
|
|
select:
|
|
- platform: template
|
|
name: Mode
|
|
id: mode
|
|
options:
|
|
- "Option1"
|
|
- "Option2"
|
|
- "Option3"
|
|
initial_option: "OFF"
|
|
optimistic: true
|
|
set_action:
|
|
- logger.log:
|
|
format: "Chosen option: %s"
|
|
args: ["x.c_str()"]
|
|
|
|
|
|
See Also
|
|
--------
|
|
|
|
- :apiref:`Select <select/select.h>`
|
|
- :apiref:`SelectCall <select/select_call.h>`
|
|
- :ghedit:`Edit`
|
|
|
|
.. toctree::
|
|
:maxdepth: 1
|
|
:glob:
|
|
|
|
*
|