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.

NOTE: 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.

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

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

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_PULSE (-> NOT IMPLEMENTED)
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)

NOTE: For button mode BUTTON_SWITCH. only the click event is available currently, therefore configuration of other events will not make any difference.

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_MODE_TOGGLE, while every other event is set to BUTTON_MODE_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:

• 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

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

• RELAYx_DELAY_ON
• RELAYx_DELAY_OFF

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.