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.

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>

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

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 bitmask.

• Button type results in a different events set:
  • 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, reports eithr pressed or released, depending on the BUTTON_DEFAULT_... flag for the default pin state.
• Default state of the button, used to determine whether it's pressed or released:
  • BUTTON_DEFAULT_LOW (default)
  • BUTTON_DEFAULT_HIGH
  • BUTTON_DEFAULT_BOOT (read at firmware startup)
• Internal pull-up / pull-down resistors. When not specified, pin is left floating.
  • BUTTON_SET_PULLUP
  • BUTTON_SET_PULLDOWN (WARNING! ESP8266 only supports pull-down on GPIO16, which in turn does not support pull-up)

For example, using the following build flags:

#define BUTTON3_PIN 2
#define BUTTON3_CONFIG BUTTON_PUSHBUTTON | BUTTON_DEFAULT_LOW

Will set up a pushbutton on GPIO2 (externally pulled-down), which will be pressed when it is connected to the VCC.

Or, using the following flags we will set up a switch on GPIO5 (with internal pull-up), which will read the current pin status on boot. Doing that allows us to leave the external switch in any position. In case firmware reboots, we don't trigger the pressed / released event.

#define BUTTON1_PIN 5
#define BUTTON1_CONFIG BUTTON_SWITCH | BUTTON_SET_PULLUP | BUTTON_DEFAULT_BOOT
#define BUTTON1_PRESS BUTTON_ACTION_TOGGLE
#define BUTTON1_RELEASE BUTTON_ACTION_TOGGLE

Available since version 1.15.0

By default, buttons can only use ESP8266 GPIOs. However, we support additional 'providers' by setting BUTTONx_PROVIDER build flag or changing btnProvX, replacing x with the correct button index and setting it at runtime with the corresponding integer value of the provider:

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

enum class button_event_t {
    None,
    Pressed,
    Released,
    Click,
    DoubleClick,
    LongClick,
    LongLongClick,
    TripleClick
};

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_RELEASE   (specific to switch)
#define BUTTONx_CLICK
#define BUTTONx_DBLCLICK
#define BUTTONx_LNGCLICK
#define BUTTONx_LNGLNGCLICK

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

Button 1 has the following defaults:

#define BUTTONx_PRESS           BUTTON_ACTION_NONE
#define BUTTONx_RELEASE         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.

Settings are loaded on the firmware boot.

By default, MQTT client will report the button event only when it has an associated action. The following build flags control this behaviour:

Or, to control this at runtime:

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).

For example, relay 1 is connected to GPIO4:

#define RELAY1_PIN        4

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 (defaults to 0)
• RELAYx_DELAY_OFF (defaults to 0)

Pulse mode and time can also be set at build time:

• RELAYx_PULSE_MODE (defaults to RELAY_PULSE_MODE)
• RELAYx_PULSE_TIME (float, time in seconds. defaults to 0.0)

Unlike build flag, pulse time string can be either be

• floating-point number of seconds. For example, 0.5 for 500 milliseconds
• number followed by s (seconds) for integer number of seconds. For example, 60s for 60 seconds
• number followed by h (hours) for integer number of hours. For example, 2h for 2 hours
• a combination of both s and h, for example 5h30s for 5 hours and 30 seconds

Available since version 1.15.0

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.

See LED Configuration & Modes.

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.

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)

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.