Select docs (#1343)

components/index.rst

@@ -11,6 +11,7 @@ Components
     light/index
     number/index
     output/index
+    select/index
     sensor/index
     switch/index
     display/index

components/select/index.rst

@@ -0,0 +1,128 @@
+Select Component
+================
+
+.. seo::
+    :description: Instructions for setting up select components in ESPHome.
+    :image: folder-open.png
+
+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.
+
+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``.
+
+.. _select-on_value:
+
+``on_value``
+************
+
+This automation will be triggered when a new option is published. In :ref:`Lambdas <config-lambda>`
+you can get the value from the trigger with ``x``.
+
+.. code-block:: yaml
+
+    select:
+      - platform: template
+        # ...
+        on_value:
+          then:
+            - logger.log:
+                format: "Chosen option: %s"
+                args: ["x.c_str()"]
+
+Configuration variables: See :ref:`Automation <automation>`.
+
+.. _select-set_action:
+
+``select.set`` Action
+*********************
+
+This is an :ref:`Action <config-action>` for setting a select state.
+
+.. 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.
+
+.. _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()``: Set the select option.
+
+  .. code-block:: cpp
+
+      // Within lambda, select the "Happy" option.
+      auto call = id(my_select).make_call();
+      call.set_option("Happy");
+      call.perform();
+
+- ``.state``: Retrieve the current option of the select.
+
+  .. code-block:: cpp
+
+      // For example, create a custom log message when an option is selected:
+      ESP_LOGI("main", "Option of my select: %f", id(my_select).state);
+
+See Also
+--------
+
+- :apiref:`select/select.h`
+- :ghedit:`Edit`
+
+.. toctree::
+    :maxdepth: 1
+    :glob:
+
+    *

components/select/template.rst

@@ -0,0 +1,58 @@
+Template Select
+===============
+
+.. seo::
+    :description: Instructions for setting up template selects with ESPHome.
+    :image: description.png
+
+The ``template`` select platform allows you to create a select with templated values
+using :ref:`lambdas <config-lambda>`.
+
+.. code-block:: yaml
+
+    # Example configuration entry
+    select:
+      - platform: template
+        name: "Template select"
+        update_interval: never
+        options:
+          - one
+          - two
+          - three
+        initial_option: two
+
+
+Configuration variables:
+------------------------
+
+- **name** (**Required**, string): The name of the select.
+- **options** (**Required**, list): The list of options this select has.
+- **lambda** (*Optional*, :ref:`lambda <config-lambda>`):
+  Lambda to be evaluated every update interval to get the new option of the select.
+- **set_action** (*Optional*, :ref:`Action <config-action>`): The action that should
+  be performed when the remote (like Home Assistant's frontend) requests to set the select option.
+- **update_interval** (*Optional*, :ref:`config-time`): The interval to check the
+  select ``lambda``. Defaults to ``60s``.
+- **optimistic** (*Optional*, boolean): Whether to operate in optimistic mode - when in this mode,
+  any command sent to the template select 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_option** (*Optional*, string): The option to set the option to on setup if not
+  restored with ``restore_value``.
+  Cannot be used with ``lambda``. Defaults to the first option in the ``options`` list.
+- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation.
+- All other options from :ref:`Select <config-select>`.
+
+``select.set`` Action
+----------------------------------
+
+You can also set an option to a template select from elsewhere in your YAML file
+with the :ref:`select-set_action`.
+
+See Also
+--------
+
+- :ref:`automation`
+- :apiref:`template/select/template_select.h`
+- :ghedit:`Edit`

index.rst

@@ -423,6 +423,14 @@ Number Components
     Number Core, components/number/index, folder-open.svg
     Template Number, components/number/template, description.svg
 
+Select Components
+-----------------
+
+.. imgtable::
+
+    Select Core, components/select/index, folder-open.svg
+    Template Select, components/select/template, description.svg
+
 Misc Components
 ---------------