From f25e069bb99980f8b11ebe2c8b329582ca3ea23f Mon Sep 17 00:00:00 2001 From: Jesse Hills <3060199+jesserockz@users.noreply.github.com> Date: Tue, 30 Nov 2021 14:25:33 +1300 Subject: [PATCH] Create docs for Button core, restart, template (#1681) Co-authored-by: Franck Nijhof --- components/button/index.rst | 118 +++++++++++++++++++++++++++++++++ components/button/restart.rst | 31 +++++++++ components/button/template.rst | 32 +++++++++ components/index.rst | 1 + components/switch/restart.rst | 2 +- index.rst | 9 +++ 6 files changed, 192 insertions(+), 1 deletion(-) create mode 100644 components/button/index.rst create mode 100644 components/button/restart.rst create mode 100644 components/button/template.rst diff --git a/components/button/index.rst b/components/button/index.rst new file mode 100644 index 000000000..deafe84f0 --- /dev/null +++ b/components/button/index.rst @@ -0,0 +1,118 @@ +Button Component +================ + +.. seo:: + :description: Instructions for setting up button components in ESPHome. + :image: folder-open.svg + +ESPHome has support for components to create a button entity. A button entity is +basically a momentary switch with no state and can be triggered by either YAML or +the user/frontend. + +.. note:: + + Home Assistant Core 2021.12 or higher is required for ESPHome button entities to work. + +.. _config-button: + +Base Button Configuration +------------------------- + +All buttons in ESPHome have a name and an optional icon. + +.. code-block:: yaml + + # Example button configuration + button: + - platform: ... + name: Livingroom Lazy Mood + id: my_button + + # Optional variables: + icon: "mdi:emoticon-outline" + on_press: + - logger.log: "Button pressed" + +Configuration variables: + +- **name** (**Required**, string): The name for the button. +- **icon** (*Optional*, icon): Manually set the icon to use for the button 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). +- **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. + +Automations: + +- **on_press** (*Optional*, :ref:`Automation `): An automation to perform + when the button is pressed. See :ref:`button-on_press`. + +MQTT options: + +- All other options from :ref:`MQTT Component `. + +Button Automation +----------------- + +.. _button-on_press: + +``on_press`` +************ + +This automation will be triggered when the button is pressed. + +.. code-block:: yaml + + button: + - platform: template + # ... + on_press: + then: + - logger.log: Button Pressed + +Configuration variables: see :ref:`Automation `. + +.. _button-press_action: + +``button.press`` Action +*********************** + +This is an :ref:`Action ` for pressing a button in an Automation. + +.. code-block:: yaml + + - button.press: my_button + +Configuration variables: + +- **id** (**Required**, :ref:`config-id`): The ID of the button to set. + +.. _button-lambda_calls: + +lambda calls +************ + +From :ref:`lambdas `, you can press a button. + +- ``press()``: Press the button. + + .. code-block:: cpp + + // Within lambda, press the button. + id(my_button).press(); + +See Also +-------- + +- :apiref:`button/button.h` +- :ghedit:`Edit` + +.. toctree:: + :maxdepth: 1 + :glob: + + * diff --git a/components/button/restart.rst b/components/button/restart.rst new file mode 100644 index 000000000..9f7f1ce2f --- /dev/null +++ b/components/button/restart.rst @@ -0,0 +1,31 @@ +Restart Button +============== + +.. seo:: + :description: Instructions for setting up buttons that can remotely reboot the ESP in ESPHome. + :image: restart.svg + +The ``restart`` button platform allows you to restart your node remotely +through Home Assistant. + +.. code-block:: yaml + + # Example configuration entry + button: + - platform: restart + name: "Living Room Restart" + +Configuration variables: +------------------------ + +- **name** (**Required**, string): The name for the button. +- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation. +- All other options from :ref:`Button `. + +See Also +-------- + +- :doc:`/components/switch/restart` +- :doc:`template` +- :apiref:`restart/button/restart_button.h` +- :ghedit:`Edit` diff --git a/components/button/template.rst b/components/button/template.rst new file mode 100644 index 000000000..959edfa91 --- /dev/null +++ b/components/button/template.rst @@ -0,0 +1,32 @@ +Template Button +=============== + +.. seo:: + :description: Instructions for setting up template buttons that can execute arbitrary actions when pressed. + :image: description.svg + +The ``template`` button platform allows you to create simple buttons out of just actions. Once defined, +it will automatically appear in Home Assistant as a button and can be controlled through the frontend. + +.. code-block:: yaml + + # Example configuration entry + button: + - platform: template + name: "Template Button" + on_press: + - logger.log: Button Pressed + +Configuration variables: +------------------------ + +- **name** (**Required**, string): The name of the switch. +- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation. +- All other options from :ref:`Button `. + +See Also +-------- + +- :doc:`/guides/automations` +- :doc:`/components/button/index` +- :ghedit:`Edit` diff --git a/components/index.rst b/components/index.rst index 94727541d..3bc1dc371 100644 --- a/components/index.rst +++ b/components/index.rst @@ -14,6 +14,7 @@ Components select/index sensor/index switch/index + button/index display/index text_sensor/index stepper/index diff --git a/components/switch/restart.rst b/components/switch/restart.rst index 5ab846890..15dcabb65 100644 --- a/components/switch/restart.rst +++ b/components/switch/restart.rst @@ -32,5 +32,5 @@ See Also - :doc:`shutdown` - :doc:`safe_mode` - :doc:`template` -- :apiref:`restart/restart_switch.h` +- :apiref:`restart/switch/restart_switch.h` - :ghedit:`Edit` diff --git a/index.rst b/index.rst index 6b4cd2ec8..44158b5bf 100644 --- a/index.rst +++ b/index.rst @@ -458,6 +458,15 @@ Switch Components BLE Client Switch, components/switch/ble_client, bluetooth.svg Nextion Switch, components/switch/nextion, nextion.jpg +Button Components +----------------- + +.. imgtable:: + + Button Core, components/button/index, folder-open.svg + Template Button, components/button/template, description.svg + Restart Button, components/button/restart, restart.svg + Fan Components --------------