Skip to content

Software features

Jump to bottom Edit New page
Maxim Prokhorov edited this page May 26, 2020 · 36 revisions

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)
Broker BROKER_SUPPORT
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)
LLMNR LLMNR_SUPPORT Support for Link-Local Multicast Name Resolution (default: 0 - off)
mDNS discovery MDNS_CLIENT_SUPPORT Use mDNS to discover endpoints (like MQTT or InfluxDB) (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
NTP NTP_SUPPORT
RF RF_SUPPORT 433Mhz RF Bridge (default: 0 - off)
Scheduler SCHEDULER_SUPPORT
SPIFFS SPIFFS_SUPPORT (Note: not implemented!)
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.
Serial to MQTT support UART_MQTT_SUPPORT
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: 5 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.

Debugging

Feature Build flag Description
Debug over serial DEBUG_SERIAL_SUPPORT Enable debug mode on serial interface (default: 1 - on)
DEBUG_PORT (default: Serial), can also be set to Serial1 to enable Output-only mode on GPIO2 to free up GPIO1 and GPIO3 for other use.
Serial port speed SERIAL_BAUDRATE (default: 115200)
Add timestamp to debug messages? DEBUG_ADD_TIMESTAMP (default: 1 - on)
SERIAL_RX_BAUDRATE (default: 115200
Debug over UDP (Syslog) DEBUG_UDP_SUPPORT Enable debugging mode over UDP (default: 0 - off)
Debug over Telnet DEBUG_TELNET_SUPPORT Use Telnet output for debugging (default: same as TELNET_SUPPORT)
Debug panel in WebUI DEBUG_WEB_SUPPPORT Use ws connection for debugging (default: same as WEB_SUPPORT)

InfluxDB settings

Feature Build flag Description
INFLUXDB_DATABASE
INFLUXDB_HOST
INFLUXDB_PASSWORD
INFLUXDB_PORT
INFLUXDB_USERNAME

Infrared - IR

Feature Build flag Description
IR Receiver GPIO IR_RX_PIN #define IR_RX_PIN 4
IR Transmit GPIO IR_TX_PIN #define IR_RX_PIN 5
IR_BUTTON_SET Which of the predefined IR button sets to use. One of:
- 1 - Original MagicLed controller (default)
- 2 - Alternative controller shipped with another variant of MagicLed controllers

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

RF

Feature Build flag Description
RFB_DIRECT RFB_DIRECT Direct mode of RFBRIDGE , using RCSwitch library (default: 0 - off)
433Mhz RF Transmitter GPIO RFB_TX_PIN GPIO where RF transmitter is connected (default: GPIO_NONE, unset)
RFB_RX_PIN GPIO where RF receiver is connected (default: GPIO_NONE, unset)
RF_RECEIVE_DELAY (default: 500 ms)
RF_SEND_DELAY (default: 500ms)
RF_SEND_TIMES (default: 4 for Itead-Sonoff-RFBridge, 1 for RFB_DIRECT mode)

Scheduler

Feature Build flag Description
SCHEDULER_MAX_SCHEDULES Maximum amount of schedules that will be stored on the device
SCHEDULER_RESTORE_LAST_SCHEDULE 0 (disabled, default) or 1 (enable) to attempt to trigger last missed schedule when device syncs time for the very first time.

SSDP

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

Telnet

Feature Build flag Description
TELNET_STA Only accept connections when in softAP mode
TELNET_MAX_CLIENTS Default: 1, maximum connections to accept. Every other connection will be dropped.
TELNET_SERVER TELNET_SERVER_ASYNC (default) or TELNET_SERVER_WIFISERVER
TELNET_AUTHENTICATION Show a password prompt when connecting
TELNET_REVERSE_SUPPORT Adds 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 OTA announcements and UDP OTA server. Used by both ArduinoIDE and PlatformIO OTA mechanisms. 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 ...";

Serial to MQTT

Feature Build flag Description
UART_MQTT_BAUDRATE
UART_MQTT_HW_PORT
UART_MQTT_RX_PIN
UART_MQTT_SUPPORT
UART_MQTT_TX_PIN
UART_MQTT_USE_SOFT

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 ADMIN_PASS to something else when accessing WebUI.
WEB_PORT (default: 80)
WEB_SSL_ENABLED (default: 0)
WEB_USERNAME (default: admin)
HTTP Digest Auth Username

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

export PLATFORMIO_BUILD_FLAGS='-DTHINGSPEAK_SUPPORT=0'

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.

Home
Change log

Getting started

Supported hardware and options

Configuration

Integrations

Network

Developers

More around ESPurna

Clone this wiki locally