mirror of
https://github.com/esphome/esphome-docs.git
synced 2024-12-25 17:17:54 +01:00
380 lines
10 KiB
ReStructuredText
380 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.
|
|
|
|
.. note::
|
|
|
|
If you have a :ref:`friendly_name <esphome-configuration_variables>` set for your device and
|
|
you want the select to use that name, you can set ``name: None``.
|
|
|
|
- **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: "Option1"
|
|
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:
|
|
|
|
*
|