Buttons and switches

This page is about general options you can compile-in into your ESPurna. Predefined board settings can be found in header file espurna/config/hardware.h and will take precedence over command line flags (-DFLAG=VALUE) and any additional configuration in espurna/config/custom.h. It is recommended to define a custom unique board instead of modifying hardware.h directly, either by using custom.h or manually specifying command line flags. See PlatformIO documentation for more information and the comments on top of the custom.h.

Buttons and switches

Headers configuration and run-time settings

Various C preprocessor flags that are used to configure multiple entities are numbered starting from 1. However, internal logging, MQTT & HTTP API, Terminal commands, Settings, etc., reference each entity using zero-based numbering.

For example, when modifying boot mode for the first relay - in headers it is defined as #define RELAY1_BOOT_MODE <flag>, while the equivalent settings command is set relayBoot0 <number>

Buttons

ESPurna supports up to 8 buttons connected to various GPIO pins. These buttons are defined using C preprocessor flag BUTTONx_PIN (x being a number from 1 to 8). Some buttons might be onboard, and you might have the option of connecting some additional, depending on the board you are using.

Each button can operate in number of different modes, configured using BUTTONx_CONFIG flag:

• BUTTON_PUSHBUTTON - connected button is of push-button type, possible events are: pressed, released, double clicked, long clicked and long-long clicked).
• BUTTON_SWITCH - connected button is actually a flip-switch, only reports the click event on both transitions.

NOTICE!: Since version 1.14.2 BUTTON[1-8]_CONFIG is used instead of BUTTON[1-8]_MODE

In addition, each button can have additional options that are logically ORed with type of button:

• BUTTON_DEFAULT_HIGH - what should be default state of a button.
• BUTTON_SET_PULLUP - should internal pull-up be enabled for a given GPIO (note that not all GPIOs support pullup)

For example -DBUTTON3_PIN=2 -DBUTTON3_CONFIG=9 (9 is the result of BUTTON_PUSHBUTTON | BUTTON_SET_PULLUP, or 0b1001 in binary form) will configure Button3 on a GPIO02, will treat it as Push-button and will set the internal pull-up.

Providers

Available since version 1.15.0

By default, buttons can only use ESP8266 GPIOs. However, we support additional 'providers' by setting BUTTON#_PROVIDER build flag or changing btnProv setting at runtime with the corresponding integer value:

Build flag	Description
BUTTON_PROVIDER_GENERIC	Generic GPIO (value: 0)
BUTTON_PROVIDER_MCP23S08	MCP23S08 - SPI-driven GPIO expander (value: 1). Requires MCP23S08_SUPPORT=1.
BUTTON_PROVIDER_ANALOG	Resistor ladder support. For more info, see #2357 (value: 2). Specific analogRead() value that will trigger the button press can be configured via BUTTON#_ANALOG_LEVEL

Event codes

Event codes (as reported via MQTT) are (note that released and click have the same code but are generated by different types of buttons)

As seen in https://github.com/xoseperez/espurna/blob/b289c77021c4d3fcd70feb25ca14178929f31e6c/code/espurna/button.h#L19-L27:

enum class button_event_t {
    None = 0,
    Pressed = 1,
    Click = 2,
    DoubleClick = 3,
    LongClick = 4,
    LongLongClick = 5,
    TripleClick = 6
};

To every button event an action can be assigned by setting the corresponding value to the button event define. The following button events are available

#define BUTTONx_PRESS
#define BUTTONx_CLICK     (what is the also used for _released_ event)
#define BUTTONx_DBLCLICK
#define BUTTONx_LNGCLICK
#define BUTTONx_LNGLNGCLICK

NOTE: When button is configured as BUTTON_SWITCH, only the click event is available.

To every event, one of the following actions can be assigned:

Flag	Description
BUTTON_ACTION_NONE
BUTTON_ACTION_TOGGLE	Toggle relay
BUTTON_ACTION_ON	Turn relay ON
BUTTON_ACTION_OFF	Turn relay OFF
BUTTON_ACTION_AP	Access point mode
BUTTON_ACTION_RESET	Reboot the device
BUTTON_ACTION_FACTORY	Erase settings and reboot
BUTTON_ACTION_WPS	Save new WiFi connection settings via WPS
BUTTON_ACTION_SMART_CONFIG	Save new WiFi connection settings via SmartConfig
BUTTON_ACTION_DIM_UP	Lights: increase brightness
BUTTON_ACTION_DIM_DOWN	Lights: decrease brightness
BUTTON_ACTION_DISPLAY_ON	Thermostat: toggle display

Button 1 has the following defaults:

#define BUTTONx_PRESS           BUTTON_ACTION_NONE
#define BUTTONx_CLICK           BUTTON_ACTION_TOGGLE
#define BUTTONx_DBLCLICK        BUTTON_ACTION_AP
#define BUTTONx_LNGCLICK        BUTTON_ACTION_RESET
#define BUTTONx_LNGLNGCLICK     BUTTON_ACTION_FACTORY

NOTE: If you plan using button1, please make sure you override these settings.

NOTE: You can always test out configuration by setting btnClick0 (CLICK), btnDclk0 (DBLCLICK), btnLLclk0 (LNGLNGCLICK) etc. from runtime with the correct numeric representation of an action.

NOTE: Since version 1.14.2 BUTTON_ACTION_ is used instead of BUTTON_MODE_

Buttons 2 to 8 BUTTONx_CLICK event is set to BUTTON_ACTION_TOGGLE, while every other event is set to BUTTON_ACTION_NONE.

LEDs

ESPurna supports up to 8 connected LEDs to various GPIO pins. These LEDs are defined using C preprocessor flag LEDx_PIN (x being a number from 1 to 8). Some LEDs might be onboard, and you might have the option of connecting some additional, depending on the board you are using.

Each LED can be bound to a relay state (see below), or operate in one of following modes, defined by LED_MODE:

• LED_MODE_MANUAL: LED will be managed from MQTT (OFF by default)
• LED_MODE_WIFI: LED will blink according to the WIFI status
• LED_MODE_FOLLOW: LED will follow the state of the linked relay (check RELAY#_LED)
• LED_MODE_FOLLOW_INVERSE: LED will follow the opposite state of the linked relay (check RELAY#_LED)
• LED_MODE_FINDME: LED will be ON if all relays are OFF
• LED_MODE_FINDME_WIFI: A mixture of WIFI and FINDME
• LED_MODE_ON: LED always ON
• LED_MODE_OFF: LED always OFF
• LED_MODE_RELAY: If any relay is ON, LED will be ON, otherwise OFF
• LED_MODE_RELAY_WIFI: A mixture of WIFI and RELAY, the reverse of FINDME_WIFI

You can invert the LED status by set LEDx_PIN_INVERSE to 1

Relays

ESPurna supports up to 8 connected relays to various GPIO pins. These relays are defined using C preprocessor flag RELAYx_PIN (x being a number from 1 to 8).

Example:

#define RELAY1_PIN 4 defines that relay 1 is connected to GPIO4

Each relay can operate in one of the following modes defined by RELAYx_TYPE:

• RELAY_TYPE_NORMAL - High-level-trigger, normally open relay.
• RELAY_TYPE_INVERSE - Either low-level-trigger, or normally closed relay.
• RELAY_TYPE_LATCHED- Relay is controlled with two normally-low GPIOs, if set GPIO goes up the relay will turn on, if reset GPIO goes up the relay will turn off
• RELAY_TYPE_LATCHED_INVERSE- Relay is controlled with two normally-high GPIOs, if set GPIO goes down the relay will turn on, if reset GPIO goes down the relay will turn off

#define RELAY1_TYPE RELAY_TYPE_NORMAL defines that relay 1 is RELAY_TYPE_NORMAL

ON and OFF actions can be delayed for a specified time in milliseconds:

• RELAYx_DELAY_ON
• RELAYx_DELAY_OFF

Tasmota templates

As we cannot use templates directly, we need to translate names given by the Tasmota Device Templates Repository (see top right) into something ESPurna configuration can understand.

Template flag	ESPurna Build flag	Description
<pin> Relay#	RELAY#_PIN <pin>, RELAY#_TYPE RELAY_TYPE_NORMAL
<pin> Relay#i	RELAY#_PIN <pin>, RELAY#_TYPE RELAY_TYPE_INVERSE
<pin> Led#	LED#_PIN <pin>, LED#_PIN_INVERSE 0,	(for other configuration, see LED#_MODE)
<pin> Led#i	LED#_PIN <pin>, LED#_PIN_INVERSE 1
<pin> Button#	BUTTON#_PIN <pin>, BUTTON#_CONFIG with BUTTON_SET_PULLUP | BUTTON_DEFAULT_HIGH
<pin> Button#i	BUTTON#_PIN <pin>, BUTTON#_CONFIG with BUTTON_SET_PULLUP	(implicit default LOW)
<pin> Button#in	BUTTON#_PIN <pin>, BUTTON#_CONFIG without BUTTON_SET_PULLUP	(implicit default LOW)
<pin> Switch#	BUTTON#_PIN <pin>, BUTTON#_CONFIG with BUTTON_SWITCH | BUTTON_SET_PULLUP | BUTTON_DEFAULT_HIGH
<pin> Switch#n	BUTTON#_PIN <pin>, BUTTON#_CONFIG without BUTTON_SET_PULLUP

Note that not every configuration option is 1-to-1. For more information, see:

• Tasmota Hardware Components list)
• Component ID <-> Names (html page source of the GPIO table)

Binding buttons, relays and LEDs

ESPurna has ability to change relay state based on the event coming from a button and set a LED status accordingly.

To do that, one should define BUTTONx_RELAY with a relay number that's "bound" to a switch. So, for example -DBUTTON1_PIN=10 -DRELAY2_PIN=11 -DBUTTON1_RELAY=2 will configure Button1 on GPIO10, Relay2 on GPIO11, and will connect Button1 to Relay2.

To also reflect Relay2 state (as defined above) on a LED1 connected to GPIO02, one should configure: -DLED1_PIN=2 -DLED1_RELAY=2 in addition to the above line.