Integrate & Build with SUPLA

Connect SUPLA with Home Assistant, use MQTT and the REST API, run your own server, or build your own devices.

SUPLA is an open platform. You can use ready-made integration mechanisms, build solutions of your own, and contribute to the project.

View on GitHub Discussion forum

What do you want to do?

Choose where you want to start.

Home Assistant & MQTT

Connect SUPLA with Home Assistant through MQTT. MQTT Discovery can automatically discover most supported device functions.

Explore the integration

Build your own device

Build your own smart home devices using the supla-device SDK.

Start building a device

REST API

Build apps, automations, and connections to other systems using the REST API, OAuth 2.0, and MQTT.

Explore the API

Run your own SUPLA server

Run your own SUPLA instance and manage the infrastructure in your own environment.

Explore self-hosting

Integrate SUPLA with other systems

SUPLA provides MQTT and a REST API for connecting devices and data with other automation systems, applications, and services of your own.

Home Assistant via MQTT

SUPLA recommends MQTT as the primary way to integrate with Home Assistant.

SUPLA supports two MQTT scenarios: account-wide MQTT provided by the SUPLA server, and direct local MQTT available on supported devices.

Account-wide MQTT exposes devices and channels from your SUPLA account through the SUPLA server and supports MQTT Discovery.

Some SUPLA devices can also connect directly to your own MQTT broker for local communication.

account-wide SUPLA MQTT
MQTT Discovery
Home Assistant
local MQTT on supported devices

Learn more about Home Assistant and MQTT in the FAQ

Build your own devices with supla-device

supla-device is an open SDK for building devices that work with the SUPLA ecosystem.

Use ready-made components, examples, and communication mechanisms instead of building SUPLA integration from scratch.

ESP32ESP8266ArduinoLinux

The library provides ready-made components for relays, buttons, sensors, and other common smart home device functions.

View supla-device on GitHub

Example: device logic for a simple Wi-Fi switch

The excerpt below shows the relay and button logic. The complete example also includes Wi-Fi and network configuration.

#include <SuplaDevice.h>
#include <supla/control/button.h>
#include <supla/control/relay.h>

void setup() {
    auto relay = new Supla::Control::Relay(12);
    relay->setDefaultFunction(SUPLA_CHANNELFNC_POWERSWITCH);

    auto button = new Supla::Control::Button(0, true, true);
    button->addAction(Supla::TOGGLE, relay, Supla::ON_CLICK_1);

    SuplaDevice.begin();
}

void loop() {
    SuplaDevice.iterate();
}

See the complete example with Wi-Fi configuration

REST API

REST API & OAuth

Use the REST API to read device and channel states, control supported functions, access measurements and build applications or integrations around your SUPLA account.

Access can be authorized using OAuth 2.0, and API documentation is available in OpenAPI format.

REST API
OAuth 2.0
OpenAPI
custom apps and automations

View API documentation

Run your own SUPLA server

Want to manage the infrastructure yourself? You can run your own SUPLA instance in your own environment.

The recommended basis for self-hosting is the supla-docker project, which lets you run the required components using Docker Compose. Running your own server gives you more control over infrastructure and data, but also means taking responsibility for maintaining it.

Docker Compose
your own infrastructure and domain
updates and monitoring
TLS certificates
backup and restore
server security

Do not assume that every external service will work on a private instance exactly as it does with the official cloud. Some features may require additional keys, certificates, or configuration.

supla-docker on GitHub

SUPLA is open source

The source code of the main platform components is publicly available. You can inspect, run, modify, and contribute to it under the licenses of the individual projects.

Main repositories

supla-device

SDK for building IoT and smart home devices (Arduino, ESP32, ESP8266, Linux)

C++

supla-cloud

Web application for management (PHP, Symfony)

PHP, JavaScript, Vue.js, Symfony

supla-core

Main communication server (C++)

C++

supla-docker

Recommended self-hosting solution (Docker)

Docker

supla-android

Native Android application

Java/Kotlin

supla-ios

Native iOS application

Swift, Objective-C

See all projects on GitHub

Technology stack

Main technologies used across SUPLA projects

Firmware

C/C++

Primary programming language

Arduino IDE, PlatformIO, Visual Studio Code

Development environments

ESP-IDF

Native ESP32 framework

Server

C++

Primary language of the communication server (supla-core)

PHP/Symfony, JavaScript/Vue.js

Web application (supla-cloud)

MySQL/MariaDB

Main database

TimescaleDB

Database for historical data storage

Docker

Containerization

Client Apps

Java, Kotlin

Android app

Objective-C, Swift

iOS app

C++

Client libraries

Contribute to SUPLA

SUPLA is developed as an open-source project. You can report bugs, suggest changes, submit pull requests, or develop projects of your own using SUPLA. The forum brings together users, developers, hobbyists, and people building their own devices and integrations.

SUPLA on GitHub Visit the forum