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