Software features - xoseperez/espurna GitHub Wiki

This page describes software features of ESPurna.

Enabling features

You can enable or disable some of the features by using C preprocessor build flags (-D), during build time ie: -DMQTT_SUPPORT=0 will not include MQTT support, as per below tables.
Similar effect can be achieved by editing code/espurna/config/custom.h and adding #define MQTT_SUPPORT 0.

Tables list all options that can be supplied during runtime. Some are not documented well - feel free to enhance this page.

Table of contents

Overview of the feature groups

For each functional group, ESPurna uses two flags:

  • *_SUPPORT - to compile code for that functionality. Feature code will be present in the image, but will not necessary be enabled by default.
  • *_ENABLED - to activate particular feature per default. In most (but not all) cases, functionality can be turned on and off in the WebUI or using Telnet commands. Changing this flag will set the default behavior of a new device, but will not override the saved configuration of old device.

Many of the feature groups have special options, as highlighted in tables below.

Below is a list of all *_SUPPORT flags that ESPurna supports (sorted alphabetically):

Feature Build flag Description
Amazon Alexa ALEXA_SUPPORT Enable Alexa discovery and support (default: 1 - on)
Uses ESPAsyncTCP library (see below)
BUTTON BUTTON_SUPPORT Generic switch and push-button support (default: 1 - on)
Domoticz DOMOTICZ_SUPPORT Enable Domoticz-specific layout of MQTT topics (default: same as MQTT_SUPPORT)
Home Assistant HOMEASSISTANT_SUPPORT Enable Home Assistant-specific support (default: same as MQTT_SUPPORT)
InfluxDB INFLUXDB_SUPPORT Enable InfluxDB HTTP interface (default: 0 - off)
Uses ESPAsyncTCP library (see below)
IR Rx/Tx IR_SUPPORT Enable IR Receiver support (default: 0 - off)
LED LED_SUPPORT Digital GPIO LED output (default: 1 - on)
LLMNR LLMNR_SUPPORT Support for Link-Local Multicast Name Resolution (default: 0 - off)
mDNS announcements MDNS_SERVER_SUPPORT Announce device via mDNS (default: 1 - on)
MQTT MQTT_SUPPORT Enable MQTT client (default: 1 - on)
NetBIOS NETBIOS_SUPPORT NetBIOS (default: 0 - off)
Nofuss NOFUSS_SUPPORT Enable auto-updates using NOFUSS server (default: 0 - off)
NTP NTP_SUPPORT Enable network time sync (default: 1 - on)
RELAY RELAY_SUPPORT Generic output switch support (default: 1 - on)
RF RFB_SUPPORT 433Mhz RF Bridge (default: 0 - off)
Scheduler SCHEDULER_SUPPORT Wall-clock based time scheduler (default: 1 - on)
SSDP SSDP_SUPPORT Simple Service Discovery protocol (default: 0 - off)
Telnet TELNET_SUPPORT Enable Telnet support (default: 1 - on)
Uses ESPAsyncTCP library (see below)
Thingspeak THINGSPEAK_SUPPORT ThingSpeak (default: 1 - on)
Uses ESPAsyncTCP library (see below)
Thermostat THERMOSTAT_SUPPORT (default: 0 - off)
Enable thermostat module with SSD1306 display support. Depends on at least one temperature sensor enabled.
UART support UART_SUPPORT General support for serial logging, sensors, terminal and etc. modules (default: 1 - on)
UART <-> MQTT support UART_MQTT_SUPPORT Send messages using MQTT and UART port (default: 0 - off)
Web WEB_SUPPORT Web (default: 1 - on)
Uses ESPAsyncTCP library (see below)

System features

Feature Build flag Description
Auto-saving of settings SETTINGS_AUTOSAVE Automatically save any changed settings? (default: 1 - on)
SYSTEM_CHECK_ENABLED (default: 1 - on) Enable internal stability checks. If system does not pass it's tests, disable all but essential modules on boot.
SYSTEM_CHECK_TIME (default: 60000 ms) Time after which system is deemed stable.
SYSTEM_CHECK_MAX (default: 3 times) Amount of times that system check is allowed to fail before triggering "unstable" mode
LIGHT_SAVE_ENABLED (default: 1 - on)
ADMIN_PASS (default: fibonacci)
Password for softAP, Telnet and Web Interface

Heartbeat

Feature Build flag Description
HEARTBEAT_ENABLED (default: 1 - on) Enable periodic status messages (delivered via MQTT_SUPPORT or INFLUXDB_SUPPORT)
HEARTBEAT_REPORT_STATUS (default: 1)
HEARTBEAT_REPORT_SSID (default: 1)
HEARTBEAT_REPORT_IP (default: 1)
HEARTBEAT_REPORT_MAC (default: 1)
HEARTBEAT_REPORT_RSSI (default: 1)
HEARTBEAT_REPORT_UPTIME (default: 1)
HEARTBEAT_REPORT_DATETIME (default: 1)
HEARTBEAT_REPORT_FREEHEAP (default: 1)
HEARTBEAT_REPORT_VCC (default: 1)
HEARTBEAT_REPORT_RELAY (default: 1)
HEARTBEAT_REPORT_LIGHT (default: 1)
HEARTBEAT_REPORT_HOSTNAME (default: 1)
HEARTBEAT_REPORT_DESCRIPTION (default: 1)
HEARTBEAT_REPORT_APP (default: 1)
HEARTBEAT_REPORT_VERSION (default: 1)
HEARTBEAT_REPORT_BOARD (default: 1)
HEARTBEAT_REPORT_LOADAVG (default: 1)
HEARTBEAT_REPORT_INTERVAL (default: 0)
HEARTBEAT_REPORT_RANGE (default: 0) (depends on THERMOSTAT_SUPPORT)
HEARTBEAT_REPORT_REMOTE_TEMP (default: 1) (depends on THERMOSTAT_SUPPORT)

At run-time, it is possible to configure each individual REPORT setting by setting hbReport bitmask. Every flag is mapped to a respective bit in a number, starting from STATUS that equals to 1 << 1, SSID equals to 1 << 2 etc. When hbReport first bit is set 1, every other bit is treated as set to 1.

InfluxDB settings

Feature Build flag Description
INFLUXDB_DATABASE
INFLUXDB_HOST
INFLUXDB_PASSWORD
INFLUXDB_PORT
INFLUXDB_USERNAME

MQTT settings

Feature Build flag Description
MQTT_LIBRARY MQTT_LIBRARY_ASYNCMQTTCLIENT (default), MQTT_LIBRARY_ARDUINOMQTT (at the moment of writing this, required for SECURE_CLIENT) or MQTT_LIBRARY_PUBSUBCLIENT
MQTT_AUTOCONNECT
MQTT_TOPIC
MQTT_GETTER Subtopic for getting a value from an object (default: "")
MQTT_SETTER Subtopic for setting a value to an object (default: "/set")
MQTT_KEEPALIVE
MQTT_USER
MQTT_PASS
MQTT_PORT
MQTT_QOS
MQTT_RECONNECT_DELAY_MAX
MQTT_RECONNECT_DELAY_MIN
MQTT_RECONNECT_DELAY_STEP
MQTT_RETAIN
MQTT_SERVER
MQTT_SKIP_RETAINED
MQTT_SKIP_TIME
JSON data
MQTT_USE_JSON (default: 0)
Instead of using plain topics, send message inside of JSON object to a <root>/data topic.
MQTT_USE_JSON_DELAY
MQTT_QUEUE_MAX_SIZE
MQTT_ENQUEUE_DATETIME
MQTT_ENQUEUE_HOSTNAME
MQTT_ENQUEUE_IP
MQTT_ENQUEUE_MAC
MQTT_ENQUEUE_MESSAGE_ID
Secure client
MQTT_SSL_ENABLED (default: 0)
MQTT_SSL_FINGERPRINT SHA1 fingerprint of the server's certificate
MQTT_SECURE_CLIENT_CHECK SECURE_CLIENT_CHECK_NONE, SECURE_CLIENT_CHECK_FINGERPRINT or SECURE_CLIENT_CHECK_CA
MQTT_SECURE_CLIENT_MFLN Depends on server support. One of 0, 512, 1024, 2048 or 4096
MQTT_SECURE_CLIENT_INCLUDE_CA Include Root CA from espurna/static/mqtt_client_trusted_root_ca.h defined as const char _mqtt_client_trusted_root_ca[] PROGMEM = "... .pem data ...";

NoFUSS

Feature Build flag Description
NOFUSS_INTERVAL
NOFUSS_SERVER

SSDP

Feature Build flag Description
SSDP device class SSDP_DEVICE_TYPE (default: "upnp:rootdevice")

Telnet

Feature Build flag Description
TELNET_STA (default: 0) Enable telnet server when connected to an access point. By default, only accept connections when connected to the device in softAP mode.
TELNET_MAX_CLIENTS (default: 1) maximum number of active connections. Any new client will be dropped, until any of the existing ones disconnect.
TELNET_AUTHENTICATION (default: 1) Show a password prompt when connecting (ADMIN_PASSWORD / adminPass)
TELNET_REVERSE_SUPPORT telnet.reverse <host> <port> terminal command to initiate raw TCP connection to the specified host. Before using this command you would need to setup the host to accept such connections, e.g. run ncat -vlp <port>

Thingspeak

OTA

Feature Build flag Description
OTA_ARDUINOOTA_SUPPORT (default:0)
Enable mDNS OTA announcements and the Arduino IDE OTA server. Used by both Arduino IDE (remote port) and PlatformIO OTA (-t upload). Depends on MDNS_SERVER_SUPPORT.
OTA_MQTT_SUPPORT (default: 0)
Enable <root>/ota topic that accepts any http / https url to a proper firmware .bin file. Depends on the OTA_CLIENT
OTA_CLIENT (default: OTA_CLIENT_ASYNCTCP, other option is OTA_CLIENT_HTTPUPDATE)
Add support for ota <url> Terminal command and provide support for the OTA_MQTT_SUPPORT
OTA_SECURE_CLIENT_CHECK SECURE_CLIENT_CHECK_NONE, SECURE_CLIENT_CHECK_FINGERPRINT or SECURE_CLIENT_CHECK_CA.
Depends on the OTA_CLIENT supporting SECURE_CLIENT configuration options. At the time of this writing, the only such client is OTA_CLIENT_HTTUPDATE.
OTA_SECURE_CLIENT_MFLN Depends on server support. One of 0, 512, 1024, 2048 or 4096
OTA_SECURE_CLIENT_INCLUDE_CA Include Root CA from espurna/static/ota_client_trusted_root_ca.h defined as const char _ota_client_trusted_root_ca[] PROGMEM = "... .pem data ...";

Web

Feature Build flag Description
WEB_EMBEDDED (default: 1) Include pre-built index.html with the web interface. The resulting firmware size increases by about 40 or 60KB
WEB_FORCE_PASS_CHANGE (default: 1) Force the user to change default ADMIN_PASS when accessing WebUI.
WEB_PORT (default: 80)
WEB_SSL_ENABLED (default: 0)
WEB_USERNAME (default: admin)

Button configuration

Feature Build flag Description
Debounce delay BUTTON_DEBOUNCE_DELAY (default: 50)
Double-click delay BUTTON_DBLCLICK_DELAY (default: 500)
Long-click delay BUTTON_LNGCLICK_DELAY (default: 1000)
Loooooong-click delay BUTTON_LNGLNGCLICK_DELAY (default: 10000)

Setting as environment variables

You can set the build flags as environment variables, e.g.:

env PLATFORMIO_SRC_BUILD_FLAGS='-DTHINGSPEAK_SUPPORT=0' pio run -e ...

Or, persist them for the current shell session (applies to every pio run call, without the env):

export PLATFORMIO_SRC_BUILD_FLAGS='...'

Support

If you're looking for support:

  • Issues: this is the most dynamic channel at the moment, you might find an answer to your question by searching open or closed issues.
  • Wiki pages: might not be as up-to-date as we all would like (hey, you can also contribute in the documentation!).
  • Gitter channel: you have better chances to get fast answers from project contributors or other ESPurna users. (also available with any Matrix client!)
  • Issue a question: as a last resort, you can open new question issue on GitHub. Just remember: the more info you provide the more chances you'll have to get an accurate answer.
⚠️ **GitHub.com Fallback** ⚠️