-
Notifications
You must be signed in to change notification settings - Fork 636
Software features
Maxim Prokhorov edited this page May 23, 2024
·
36 revisions
This page describes software features of ESPurna.
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.
- 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
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) |
| 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 |
| 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.
| Feature | Build flag | Description |
|---|---|---|
INFLUXDB_DATABASE |
||
INFLUXDB_HOST |
||
INFLUXDB_PASSWORD |
||
INFLUXDB_PORT |
||
INFLUXDB_USERNAME |
| 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 ...";
|
| Feature | Build flag | Description |
|---|---|---|
NOFUSS_INTERVAL |
||
NOFUSS_SERVER |
| Feature | Build flag | Description |
|---|---|---|
| SSDP device class | SSDP_DEVICE_TYPE |
(default: "upnp:rootdevice") |
| 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>
|
| 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 ...";
|
| 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) |
| 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) |
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='...'
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.
- Backup the stock firmware
- Flash a pre-built binary image
- Flash a virgin Itead Sonoff device without opening
- Flash TUYA-based device without opening
- Flash Shelly device without opening
- Using PlatformIO
- from Visual Studio Code
- Using Arduino IDE
- Build the Web Interface
- Over-the-air updates
- Two-step updates
- ESPurna OTA Manager
- NoFUSS
- Troubleshooting
- MQTT
- REST API
- Domoticz
- Home Assistant
- InfluxDB
- Prometheus metrics
- Thingspeak
- Alexa
- Google Home
- Architecture
- 3rd Party Plugins
- Coding style
- Pull Requests