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
• InfraRed - IR
• 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)
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
SSDP	SSDP_SUPPORT	Simple Service Discovery protocol (default: 0 - off)
Telnet	TELNET_SUPPORT	Enable Telnet support (default: 1 - on) Uses ESPAsyncTCP library (see below)
	TERMINAL_SUPPORT	(default: 1 - on)
Thingspeak	THINGSPEAK_SUPPORT	ThingSpeak (default: 1 - on) Uses ESPAsyncTCP library (see below)
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
	HEARTBEAT_ENABLED	(default: 1 - on)
	LIGHT_SAVE_ENABLED	(default: 1 - on)

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

NTP

Feature	Build flag	Description
	NTP_DAY_LIGHT
	NTP_DST_REGION
	NTP_SERVER
	NTP_START_DELAY
	NTP_SYNC_INTERVAL
	NTP_TIMEOUT
	NTP_TIME_OFFSET
	NTP_UPDATE_INTERVAL
Wait for NTP synchronization	NTP_WAIT_FOR_SYNC	Normally, ESPurna will wait for NTP to sync over wifi before enabling the scheduler. This is so it ensures that the schedules will never run outside their specified times, even if that means they don't run at all. If, instead, you want them to always run, even if the time is not correct, you can set this build flag to 0, which will cause ESPurna to act as if the time is correct when it boots up. That way, schedules will run even if NTP has not synced (but obviously at potentially the wrong times). If the network becomes available at some point, NTP will sync and resume running at the correct times.

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

Feature	Build flag	Description
	THINGSPEAK_APIKEY

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
	WEB_FORCE_PASS_CHANGE
	WEB_PORT
	WEB_SSL_ENABLED
	WEB_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)