Learn how to configure a single switch to handle multiple actions (single-click, double-click, long-press) in ESPHome on boneIO devices.

Multi-click Configuration in ESPHome

The multi-click feature is one of the most powerful automation capabilities. It allows a single physical wall switch to trigger different actions depending on how it's pressed.

Example Use Cases:

Single-click: Turn the main room light on/off.
Double-click: Activate a "relax" scene (e.g., main light at 30%, turn on a floor lamp).
Long-press: Smoothly dim the lights up or down.

This guide will show you how to configure this in two different ways.

Prerequisites

Before you begin, make sure you have:

A working ESPHome add-on installed.
Your boneIO device is adopted in your ESPHome dashboard.
You know how to edit your device's YAML configuration file.
You are using momentary (bell-press) switches, which are required for multi-click to work.

Method 1: Logic Directly in ESPHome (Recommended for Simple Actions)

This method is the quickest and is ideal when the actions you want to trigger involve entities available directly within ESPHome (e.g., toggling relays on the same device).

Step 1: Prepare Your `light` Entities

For this example, let's assume you have three lighting circuits connected to outputs OUT01, OUT02, and OUT03. Your configuration should include a block similar to this:

light:
  - platform: binary
    name: 'Main Light'
    output: out_01
    id: light_01
  - platform: binary
    name: 'Wall Sconce'
    output: out_02
    id: light_02
  - platform: binary
    name: 'Floor Lamp'
    output: out_03
    id: light_03

Step 2: Find and Modify Your binary_sensor

In your configuration, find the input (binary_sensor) you want to program, for example, IN_01. A standard configuration looks like this:

binary_sensor:
  - platform: gpio
    name: 'Living Room Switch'
    pin:
      # ... (pcf8574, number, mode, inverted)
    # This section handles a simple click
    on_press:
      then:
        - light.toggle: light_01

Delete the entire on_press section. It's too basic for our needs. We need to replace it with more advanced logic.

Step 3: Add the `on_multi_click` Action

In place of the deleted on_press section, add a new one called on_multi_click. This is where we'll define our actions.

binary_sensor:
  - platform: gpio
    name: 'Living Room Switch'
    id: in_01
    pin:
      pcf8574: pcf_inputs_1to14
      number: 0 # Corresponds to IN01
      mode:
        input: true
      inverted: true
    # The new, advanced section
    on_multi_click:
    # IMPORTANT: Order matters! ESPHome evaluates conditions from top to bottom.
    # Define the most complex clicks (e.g., triple, double) first.
      - timing: # Double-click
          - ON for at most 1s   # The press lasted less than 1 second
          - OFF for at most 0.5s # The release lasted less than 0.5 seconds
          - ON for at most 1s   # The second press lasted less than 1 second
          - OFF for at least 0.2s# The final release
        then:
          - light.toggle: light_02 # Action: toggle the wall sconce
      - timing: # Long-press
          - ON for at least 1s   # The press lasted LONGER than 1 second
        then:
          - light.toggle: light_03 # Action: toggle the floor lamp
      - timing: # Single-click
          - ON for at most 1s   # The press lasted less than 1 second
          - OFF for at least 0.5s# The release lasted LONGER than 0.5 seconds
        then:
          - light.toggle: light_01 # Action: toggle the main light

Tip: You can adjust the timing values (e.g., 1s, 0.5s) to your preference to make the clicks more or less sensitive.

After saving the file, upload the new configuration to your device. Your switch now supports three different actions!

Method 2: Sending Events to Home Assistant (For Advanced Users)

This method is perfect when you want a button press to trigger a complex automation in Home Assistant that controls many different devices (not just those connected to the boneIO).

Step 1: Create an event Entity in ESPHome

First, we need to create a "channel" to send events to Home Assistant. Add the following code to the top of your YAML configuration.

event:
  - platform: template
    name: "living room button events"
    id: "in_01_events"
    event_types:
      - "single"
      - "double"
      - "long"

Step 2: Modify the `on_multi_click` Actions

Now, in addition to toggling the light, we'll add an action to send an event to Home Assistant for each click type.

# ... (the binary_sensor section remains the same, we only modify the 'then' sections)

    on_multi_click:
      - timing: # Double-click
          # ... (timing definition is unchanged)
        then:
          - light.toggle: light_02 # Local action (optional)
          - event.trigger:
              id: in_01_events
              event_type: "double" # Send a "double" event
      - timing: # Long-press
          # ... (timing definition is unchanged)
        then:
          - light.toggle: light_03
          - event.trigger:
              id: in_01_events
              event_type: "long" # Send a "long" event
      - timing: # Single-click
          # ... (timing definition is unchanged)
        then:
          - light.toggle: light_01
          - event.trigger:
              id: in_01_events
              event_type: "single" # Send a "single" event

Step 3: Create an Automation in Home Assistant

After uploading the new configuration, a new entity event.in01_events will appear in Home Assistant. You can now use this to trigger automations.

Go to Settings > Automations & Scenes > Create Automation and choose "Create new automation." In YAML mode, the trigger will look like this:

# Example automation for a double-click
trigger:
  - platform: event
    event_type: esphome.in_01_events # Event name, matches the ID in ESPHome
    event_data:
      type: "double" # Listen only for the "double" event
condition: []
action:
  # Define what should happen in Home Assistant here
  - service: scene.turn_on
    target:
      entity_id: scene.movie_night
mode: single

Multi-click Configuration

On this page