How to use a momentary switch in ESPHome

Wiring a physical switch or button to an ESP8266 or ESP32 is a crucial step that opens the door to endless possibilities with ESPHome. By connecting a switch, you have the power to control various devices linked to your ESPHome node, such as LEDs, relays, or motors. Moreover, you can pass on the switch or button status to Home Assistant, which then can control any of your integrated devices. For example, you can create a central light switch using multiple buttons to control all connected light bulbs in your smart home.

Properly configuring a physical switch or button in ESPHome is a must-have skill when planning projects. This guide will provide you with a comprehensive understanding of the process, making it easy for even ESPHome beginners to wire up a switch or button and configure it using YAML. I aim to make sure you get it right the first time.

Types of switches and buttons

Switches come in various shapes and types, including tactile or momentary switches, which are push buttons that only function when pressed. Once you release the button, the circuit is interrupted. In contrast, toggle switches remain in a fixed position, either on or off, and can be flipped by moving a lever to open or close the electrical circuit.

A light switch is a toggle switch — A light switch, such as the one above, is a toggle switch

A video game controller, which has momentary switches — A video game controller has momentary switches

The problem with toggle switches

I love toggle switches, but they are not ideal for use with ESPHome and Home Assistant. If the toggle switch is the only way to control the connected device, it is not a problem. However, if you want to control the device through the Home Assistant dashboard as well, things can get out of sync.

ESP32 Board

Sale

ESP8266 NodeMCU

D1 mini ESP8266 Board (clone)

For example, if you turn the software switch on, but the physical switch is off, you would have to first turn the physical switch off, then on, to turn the device on again. This can lead to confusion and frustration. Therefore, I would not recommend using toggle switches in ESPHome projects, even though they can be fun to play with.

Wiring up a switch to an ESP8266 or ESP32

Wiring a switch is straightforward. Simply connect one terminal of the switch to the ground on the ESP8266 or ESP32 board (denoted with a “G” on the board) and the other terminal to a GPIO pin. The aim is for the pin to read LOW when the switch is pressed and HIGH when it's not.

A scetch showing how a button can be connected to a LOLIN D1 mini, a popular ESP8266 board.

Once the button is wired, we can create a GPIO binary sensor in our configuration using the code provided in the documentation. In this example, the device class is set to “window”. You can choose from any of the device classes supported by Home Assistant.

binary_sensor:
  - platform: gpio
    pin: D2
    name: "Living Room Window"
    device_class: window

Configuring the internal pull-up resistor in ESPHome

There's one issue with this setup. If we read the input on the pin and press the momentary button, the pin will read LOW, but when the switch is released, there's no guarantee the pin will read HIGH. This can be resolved either by using a physical pull-up resistor, which ensures a known state for the signal, or by enabling the built-in pull-up resistor on the ESP8266 or ESP32 boards in the ESPHome configuration. This only requires adding one line of YAML in the configuration:

binary_sensor:
  - platform: gpio
    pin:
      number: D2
      mode: INPUT_PULLUP
    name: "Living Room Window"
    device_class: window

Inverting the switch in ESPHome

With the above setup, ESPHome will report the switch as off when pressed and on when not pressed. If you wish to invert these options, you can do so by adding another line to your code:

binary_sensor:
  - platform: gpio
    pin:
      number: D2
      mode: INPUT_PULLUP
      inverted: True
    name: "Living Room Window"
    device_class: window

Sale

Momentary Push Buttons

Momentary push button

Momentary tactile push button

Debouncing in ESPHome

Releasing a momentary switch, as used in our scenario, will not instantly switch from LOW to HIGH as expected. It will instead briefly oscillate before settling. This can cause ESPHome to read incorrect values, such as rapid switching between values, before it finally settles. The oscillation occurs in the microseconds range and can be filtered out using a few lines of code, a process known as debouncing in electronics.

binary_sensor:
  - platform: gpio
    pin:
      number: D2
      mode: INPUT_PULLUP
      inverted: True
    name: "Living Room Window"
    device_class: window
    filters:
      - delayed_on: 10ms

With this filter in place, the signal will only register as high if the button remains high for more than 10ms, effectively filtering out the oscillation.

Frequently asked questions

What is a GPIO pin?

GPIO stands for General Purpose Input/Output, which are digital pins in a microcontroller (such as the ESP8266 or ESP32) that can be used for both input and output operations. These pins can be used to interact with external devices, such as sensors, actuators, or switches, by either reading data from them or sending data to them.

What is the purpose of wiring a switch or button to an ESP8266 or ESP32 running ESPHome?

The purpose of wiring a switch or button to an ESP8266 or ESP32 is to have the power to control various devices linked to your ESPHome node and to pass on the switch to Home Assistant.

Why are toggle switches not ideal for use with ESPHome and Home Assistant?

Toggle switches can cause confusion and frustration because if the software switch is on, but the physical switch is off, you have to first turn off and then turn on the physical switch to turn the device on again. This can lead to the software switch and physical switch being out of sync.

What is the difference between a tactile or momentary switch and a toggle switch?

A tactile or momentary switch is a push button that only functions when pressed, and the circuit is interrupted when released. On the other hand, a toggle switch remains in a fixed position either on or off and can be flipped by moving a lever to open or close the electrical circuit.

About Liam Alexander Colman

Liam Alexander Colman is an experienced Home Assistant user who has been utilizing the platform for a variety of projects over an extended period. His journey began with a Raspberry Pi, which quickly grew to three Raspberry Pis and eventually a full-fledged server. Liam's current operating system of choice is Unraid, with Home Assistant comfortably running in a Docker container.

With a deep understanding of the intricacies of Home Assistant, Liam has an impressive setup, consisting of various Zigbee devices, and seamless integrations with existing products such as his Android TV box. For those interested in learning more about Liam's experience with Home Assistant, he shares his insights on how he first started using the platform and his subsequent journey.

How to use a physical switch or button in ESPHome with GPIO binary sensor