esp-libsupla

esp-libsupla is an embedded C component for creating SUPLA devices on ESP32 and ESP8266. It bundles the libsupla device and channel API with ESP platform support, NVS-backed configuration, Wi-Fi state helpers, and HTTP configuration handlers.

SUPLA is an open smart-home platform. Its apps let users monitor and control compatible devices remotely, including lighting, gates, blinds, heating, and energy-related equipment. SUPLA supports both ready-made products and DIY integrations.

This component is for developers building custom ESP-based devices that communicate with SUPLA Cloud. For the platform, apps, and user information, visit supla.org; for integration resources, see Integrate & Build.

Compatibility

• ESP-IDF component projects. The component manifest currently declares ESP-IDF >=5.0.
• ESP8266 RTOS-SDK projects using the legacy Make-based component system.

The repository includes examples/default and examples/webserver. The default example uses credentials entered in menuconfig; the webserver example provides an access-point configuration page when no SUPLA email is stored.

Install

ESP Component Registry

From an ESP-IDF project directory, add the dependency:

idf.py add-dependency "qb4-dev/esp-libsupla=*"

Add to components

Clone the repository into your project's components directory:

mkdir -p components
git clone --recursive https://github.com/QB4-dev/esp-libsupla components/esp-libsupla

Include the component headers in application code with #include <libsupla/device.h> and, for ESP helpers, #include <esp-supla.h>.

Build an Example

Use an ESP-IDF 5.x environment for the CMake/idf.py project flow. The default example is the CMake quick start:

cd examples/default
idf.py set-target esp32
idf.py menuconfig
idf.py build
idf.py flash monitor

Choose a supported ESP32 target in place of esp32 when needed. The webserver example uses the built-in HTTP configuration handler. The current component CMake source list does not include esp-supla-httpd.c, so that example may fail to link with CMake until the source is added there. The legacy Make component list does include it.

To build with ESP8266 RTOS-SDK, activate that SDK's environment and use its legacy Make-based project flow:

cd examples/webserver
make menuconfig
make
make flash monitor

The default example is in examples/default and follows the same project build flow. In its menuconfig, set the Wi-Fi SSID/password, SUPLA email, and server. In the webserver example, first boot without a configured SUPLA email starts the configuration access point; connect to it, open the device's configuration page, and enter Wi-Fi and SUPLA settings. Once configured, add the device through the SUPLA app.

Application Setup

Initialize NVS, load or generate the SUPLA credentials, and set the config on a device before starting it. supla_esp_nvs_config_init() loads settings from NVS and generates a GUID and auth key when they are unset. The account email and SUPLA server still need to be configured. The device should be started after network connectivity is available, and supla_dev_iterate() should be called regularly from the application's task or loop.

#include <esp_err.h>
#include <freertos/FreeRTOS.h>
#include <freertos/task.h>
#include <nvs_flash.h>
#include <libsupla/device.h>
#include <esp-supla.h>

static struct supla_config config = {
	.email = "user@example.com",
	.server = "svrX.supla.org",
	.port = 2016,
	.ssl = 1,
};

void app_main(void)
{
	ESP_ERROR_CHECK(nvs_flash_init());
	ESP_ERROR_CHECK(supla_esp_nvs_config_init(&config));

	supla_dev_t *dev = supla_dev_create("My device", NULL);
	supla_dev_set_config(dev, &config);

	/* Initialize Wi-Fi and add channels before starting the device. */
	supla_dev_start(dev);
	for (;;) {
		supla_dev_iterate(dev);
		vTaskDelay(pdMS_TO_TICKS(100));
	}
}

Add channels with supla_channel_create() and supla_dev_add_channel(). See the example applications for complete Wi-Fi, channel, and event-loop setup. The HTTP helpers are declared in esp-supla.h; register supla_dev_basic_httpd_handler on the / GET and POST routes to use the built-in configuration page.

TLS

The component exposes the ESP_LIBSUPLA_USE_ESP_TLS Kconfig option. The project Kconfig notes that ESP8266 SSL handshakes may be unstable at 80 MHz and recommends 160 MHz. Check the selected target and SDK configuration when enabling TLS.

License

See LICENSE for the project license. The bundled libsupla library has its own license.