Software features

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
• System features
• Debugging support
• InfluxDB settings
• IR
• mDNS
• MQTT settings
• NoFUSS
• NTP
• RF
• Scheduler
• SSDP
• Telnet
• Thingspeak
• Serial to MQTT
• Web

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)
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 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)
RF	RFB_SUPPORT	433Mhz RF Bridge (default: 0 - off)
Scheduler	SCHEDULER_SUPPORT
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

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_PROVIDER	RFB_PROVIDER=RFB_PROVIDER_RCSWITCH	"Direct" variant of the RFBRIDGE, using RCSwitch library (default)
RFB_PROVIDER	RFB_PROVIDER=RFB_PROVIDER_EFM8BB1	To be used with the Itead Sonoff RFBridge hardware
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)
	RFB_RECEIVE_DELAY	(default: 500 ms)
	RFB_SEND_DELAY	(default: 500ms)
	RFB_SEND_REPEATS	(default: 1)

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 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 ...";

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 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='...'