esphome-docs/components/switch/index.rst

191 lines
6.3 KiB
ReStructuredText
Raw Normal View History

2018-05-13 11:37:02 +02:00
Switch Component
================
2018-11-14 22:12:27 +01:00
.. seo::
2019-02-16 23:25:23 +01:00
:description: Instructions for setting up generic switches in ESPHome.
:image: folder-open.svg
2018-11-14 22:12:27 +01:00
2018-05-13 11:37:02 +02:00
The ``switch`` domain includes all platforms that should show up like a
switch and can only be turned ON or OFF.
2018-06-01 18:10:00 +02:00
.. _config-switch:
2018-05-13 11:37:02 +02:00
Base Switch Configuration
-------------------------
.. code-block:: yaml
2018-05-13 11:37:02 +02:00
switch:
- platform: ...
name: "Switch Name"
icon: "mdi:restart"
Configuration variables:
2019-02-17 12:28:17 +01:00
- **name** (**Required**, string): The name of the switch.
- **icon** (*Optional*, icon): Manually set the icon to use for the
sensor in the frontend.
- **inverted** (*Optional*, boolean): Whether to invert the binary
state, i.e. report ON states as OFF and vice versa. Defaults
to ``false``.
2019-02-17 12:28:17 +01:00
- **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.
- **restore_mode** (*Optional*): Control how the switch attempts to restore state on bootup.
**NOTE** : Not all components consider **restore_mode**. Check the documentation of the specific component to understand how
this feature works for a particular component or device.
For restoring on ESP8266s, also see ``restore_from_flash`` in the
:doc:`esp8266 section </components/esp8266>`.
- ``RESTORE_DEFAULT_OFF`` - Attempt to restore state and default to OFF if not possible to restore.
- ``RESTORE_DEFAULT_ON`` - Attempt to restore state and default to ON.
- ``RESTORE_INVERTED_DEFAULT_OFF`` - Attempt to restore state inverted from the previous state and default to OFF.
- ``RESTORE_INVERTED_DEFAULT_ON`` - Attempt to restore state inverted from the previous state and default to ON.
- ``ALWAYS_OFF`` - Always initialize the switch as OFF on bootup.
- ``ALWAYS_ON`` - Always initialize the switch as ON on bootup.
- ``DISABLED`` - Does nothing and leaves it up to the downstream platform component to decide. For example, the component could read hardware and determine the state, or have a specific configuration option to regulate initial state.
Unless a specific platform defines another default value, the default is ``RESTORE_DEFAULT_OFF``.
2019-02-17 19:09:52 +01:00
- **on_turn_on** (*Optional*, :ref:`Action <config-action>`): An automation to perform
when the switch is turned on. See :ref:`switch-on_turn_on_off_trigger`.
- **on_turn_off** (*Optional*, :ref:`Action <config-action>`): An automation to perform
when the switch is turned off. See :ref:`switch-on_turn_on_off_trigger`.
- **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``.
2021-11-07 19:24:55 +01:00
- **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.
- **device_class** (*Optional*, string): The device class for the switch.
See https://developers.home-assistant.io/docs/core/entity/switch/#available-device-classes
for a list of available options. Requires Home Assistant 2022.3 or newer.
2019-02-17 12:28:17 +01:00
- If MQTT enabled, All other options from :ref:`MQTT Component <config-mqtt-component>`.
2018-06-01 18:10:00 +02:00
.. _switch-toggle_action:
``switch.toggle`` Action
2018-08-24 22:44:01 +02:00
************************
2018-06-01 18:10:00 +02:00
This action toggles a switch with the given ID when executed.
.. code-block:: yaml
2018-06-01 18:10:00 +02:00
on_...:
then:
2018-11-10 14:33:24 +01:00
- switch.toggle: relay_1
2018-06-01 18:10:00 +02:00
.. _switch-turn_on_action:
``switch.turn_on`` Action
2018-08-24 22:44:01 +02:00
*************************
2018-06-01 18:10:00 +02:00
This action turns a switch with the given ID on when executed.
.. code-block:: yaml
2018-06-01 18:10:00 +02:00
on_...:
then:
2018-10-26 22:30:24 +02:00
- switch.turn_on: relay_1
2018-06-01 18:10:00 +02:00
.. _switch-turn_off_action:
``switch.turn_off`` Action
2018-08-24 22:44:01 +02:00
**************************
2018-06-01 18:10:00 +02:00
This action turns a switch with the given ID off when executed.
.. code-block:: yaml
2018-06-01 18:10:00 +02:00
on_...:
then:
2018-10-26 22:30:24 +02:00
- switch.turn_off: relay_1
2018-06-01 18:10:00 +02:00
2019-01-06 18:56:14 +01:00
.. _switch-is_on_condition:
.. _switch-is_off_condition:
``switch.is_on`` / ``switch.is_off`` Condition
**********************************************
This :ref:`Condition <config-condition>` checks if the given switch is ON (or OFF).
.. code-block:: yaml
# In some trigger:
on_...:
if:
condition:
# Same syntax for is_off
switch.is_on: my_switch
.. _switch-lambda_calls:
2018-06-07 15:55:31 +02:00
lambda calls
2018-08-24 22:44:01 +02:00
************
2018-06-07 15:55:31 +02:00
From :ref:`lambdas <config-lambda>`, you can call several methods on all switches to do some
advanced stuff (see the full API Reference for more info).
2018-06-07 15:55:31 +02:00
- ``publish_state()``: Manually cause the switch to publish a new state and store it internally.
If it's different from the last internal state, it's additionally published to the frontend.
.. code-block:: yaml
2018-06-07 15:55:31 +02:00
// Within lambda, make the switch report a specific state
id(my_switch).publish_state(false);
id(my_switch).publish_state(true);
- ``state``: Retrieve the current state of the switch.
.. code-block:: yaml
2018-06-07 15:55:31 +02:00
// Within lambda, get the switch state and conditionally do something
if (id(my_switch).state) {
2018-06-07 15:55:31 +02:00
// Switch is ON, do something here
} else {
// Switch is OFF, do something else here
}
- ``turn_off()``/``turn_on()``: Manually turn the switch ON/OFF from code.
2018-06-07 15:55:31 +02:00
Similar to the ``switch.turn_on`` and ``switch.turn_off`` actions,
but can be used in complex lambda expressions.
.. code-block:: yaml
2018-06-07 15:55:31 +02:00
2019-01-06 18:56:14 +01:00
id(my_switch).turn_off();
id(my_switch).turn_on();
2018-06-07 15:55:31 +02:00
// Toggle the switch
2019-01-06 18:56:14 +01:00
id(my_switch).toggle();
2018-06-07 15:55:31 +02:00
2019-02-17 19:09:52 +01:00
.. _switch-on_turn_on_off_trigger:
``switch.on_turn_on`` / ``switch.on_turn_off`` Trigger
******************************************************
This trigger is activated each time the switch is turned on. It becomes active
right after the switch component has acknowledged the state (e.g. after it switched
ON/OFF itself).
.. code-block:: yaml
switch:
- platform: gpio # or any other platform
# ...
on_turn_on:
- logger.log: "Switch Turned On!"
on_turn_off:
- logger.log: "Switch Turned Off!"
2018-06-01 18:10:00 +02:00
See Also
2018-08-24 22:44:01 +02:00
--------
2018-06-01 18:10:00 +02:00
2019-05-12 22:44:59 +02:00
- :apiref:`switch/switch.h`
- :ghedit:`Edit`
2018-06-01 18:10:00 +02:00
.. toctree::
:maxdepth: 1
:glob:
2018-06-01 18:10:00 +02:00
*