# supla/supla-device architecture

> Architecture diagram of the GitHub repository supla/supla-device, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/supla/supla-device
- Repository: https://github.com/supla/supla-device

## Overview

supla-device is an SDK for implementing SUPLA-compatible smart-home devices, not a complete firmware or server. The main workflow is that a firmware developer configures device logic and channels, runs the device lifecycle, and connects it to SUPLA Server through the protocol layer. The framework also supports sensor/control elements, scheduled behavior, persistent configuration and state, and multiple platform ports. Relationships are limited to README statements and visible SOURCE INDEX references; unsampled implementation details are not inferred.

Main entry points: [`src/SuplaDevice.cpp`](https://github.com/supla/supla-device/blob/main/src/SuplaDevice.cpp) (Device API), [`src/supla/channel_element.cpp`](https://github.com/supla/supla-device/blob/main/src/supla/channel_element.cpp) (Elements), [`src/supla/storage/storage.cpp`](https://github.com/supla/supla-device/blob/main/src/supla/storage/storage.cpp) (Storage framework), [`src/supla-common/srpc.c`](https://github.com/supla/supla-device/blob/main/src/supla-common/srpc.c) (SRPC)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_device_framework["Device framework"]
  node_device_api["Device API<br/>[SuplaDevice.cpp]"]
  node_elements["Elements"]
  node_channels["Channels<br/>[channel.cpp]"]
  node_storage_api["Storage framework<br/>[storage.cpp]"]
  node_state_storage["State storage"]
  node_config_storage["Config storage<br/>[config.h]"]
end

subgraph group_device_features["Device features"]
  node_device_services["Device services"]
  node_controls["Controls<br/>[relay.cpp]"]
  node_sensors["Sensor handlers"]
  node_weekly_schedule["Weekly schedules"]
  node_modbus["Modbus integration"]
  node_weekly_components["Schedule components"]
end

subgraph group_protocol["Protocol"]
  node_protocol_defs["Protocol definitions<br/>[proto.h]"]
  node_srpc["SRPC<br/>[srpc.c]"]
  node_mqtt_registry["MQTT handlers"]
end

subgraph group_platform["Platform ports"]
  node_linux_port["Linux port<br/>[linux_client.cpp]"]
  node_linux_storage["Linux file storage"]
  node_esp_port["ESP-IDF port<br/>[esp_idf_client.cpp]"]
  node_spiffs_storage["SPIFFS storage<br/>[spiffs_storage.cpp]"]
end

node_developer(("Firmware developer"))
node_server(("SUPLA Server"))

node_developer -->|"uses"| node_device_api
node_device_api -->|"runs lifecycle"| node_elements
node_elements -->|"may expose"| node_channels
node_device_api -->|"connects device"| node_server
node_device_services -.->|"supports device"| node_device_api
node_controls -->|"implements logic"| node_elements
node_sensors -->|"implements logic"| node_elements
node_weekly_schedule -->|"uses"| node_weekly_components
node_modbus -.->|"integrates device"| node_elements
node_storage_api -->|"creates state store"| node_state_storage
node_storage_api -->|"uses config"| node_config_storage
node_srpc -->|"uses definitions"| node_protocol_defs
node_device_api -.->|"uses protocol"| node_srpc
node_mqtt_registry -.->|"supports MQTT"| node_server
node_linux_port -->|"connects device"| node_server
node_esp_port -->|"connects device"| node_server
node_linux_storage -->|"implements backend"| node_storage_api
node_spiffs_storage -->|"implements backend"| node_storage_api

click node_device_api "https://github.com/supla/supla-device/blob/main/src/SuplaDevice.cpp"
click node_elements "https://github.com/supla/supla-device/blob/main/src/supla/channel_element.cpp"
click node_channels "https://github.com/supla/supla-device/blob/main/src/supla/channels/channel.cpp"
click node_device_services "https://github.com/supla/supla-device/blob/main/src/supla/device/register_device.cpp"
click node_controls "https://github.com/supla/supla-device/blob/main/src/supla/control/relay.cpp"
click node_sensors "https://github.com/supla/supla-device/blob/main/src/supla/sensor/multi_ds_handler_base.cpp"
click node_weekly_schedule "https://github.com/supla/supla-device/blob/main/src/supla/control/weekly_schedule_storage.cpp"
click node_modbus "https://github.com/supla/supla-device/blob/main/src/supla/modbus/modbus_client_handler.cpp"
click node_storage_api "https://github.com/supla/supla-device/blob/main/src/supla/storage/storage.cpp"
click node_state_storage "https://github.com/supla/supla-device/blob/main/src/supla/storage/state_storage_interface.cpp"
click node_config_storage "https://github.com/supla/supla-device/blob/main/src/supla/storage/config.h"
click node_weekly_components "https://github.com/supla/supla-device/blob/main/src/supla/control/weekly_schedule_component.h"
click node_protocol_defs "https://github.com/supla/supla-device/blob/main/src/supla-common/proto.h"
click node_srpc "https://github.com/supla/supla-device/blob/main/src/supla-common/srpc.c"
click node_mqtt_registry "https://github.com/supla/supla-device/blob/main/src/supla/protocol/mqtt_handler_registry.cpp"
click node_linux_port "https://github.com/supla/supla-device/blob/main/extras/porting/linux/linux_client.cpp"
click node_linux_storage "https://github.com/supla/supla-device/blob/main/extras/porting/linux/linux_file_storage.cpp"
click node_esp_port "https://github.com/supla/supla-device/blob/main/extras/porting/esp-idf/esp_idf_client.cpp"
click node_spiffs_storage "https://github.com/supla/supla-device/blob/main/extras/porting/esp-idf/spiffs_storage.cpp"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_device_api,node_elements,node_channels,node_storage_api,node_state_storage,node_config_storage toneBlue
class node_device_services,node_controls,node_sensors,node_weekly_schedule,node_modbus,node_weekly_components toneAmber
class node_protocol_defs,node_srpc,node_mqtt_registry,node_server toneMint
class node_linux_port,node_linux_storage,node_esp_port,node_spiffs_storage toneRose
class node_developer toneIndigo
```

## Components

### Device framework

- [Device API](https://github.com/supla/supla-device/blob/main/src/SuplaDevice.cpp): `src/SuplaDevice.cpp`
- [Elements](https://github.com/supla/supla-device/blob/main/src/supla/channel_element.cpp): `src/supla/channel_element.cpp`
- [Channels](https://github.com/supla/supla-device/blob/main/src/supla/channels/channel.cpp): `src/supla/channels/channel.cpp`
- [Storage framework](https://github.com/supla/supla-device/blob/main/src/supla/storage/storage.cpp): `src/supla/storage/storage.cpp`
- [State storage](https://github.com/supla/supla-device/blob/main/src/supla/storage/state_storage_interface.cpp): `src/supla/storage/state_storage_interface.cpp`
- [Config storage](https://github.com/supla/supla-device/blob/main/src/supla/storage/config.h): `src/supla/storage/config.h`

### Device features

- [Device services](https://github.com/supla/supla-device/blob/main/src/supla/device/register_device.cpp): `src/supla/device/register_device.cpp`
- [Controls](https://github.com/supla/supla-device/blob/main/src/supla/control/relay.cpp): `src/supla/control/relay.cpp`
- [Sensor handlers](https://github.com/supla/supla-device/blob/main/src/supla/sensor/multi_ds_handler_base.cpp): `src/supla/sensor/multi_ds_handler_base.cpp`
- [Weekly schedules](https://github.com/supla/supla-device/blob/main/src/supla/control/weekly_schedule_storage.cpp): `src/supla/control/weekly_schedule_storage.cpp`
- [Modbus integration](https://github.com/supla/supla-device/blob/main/src/supla/modbus/modbus_client_handler.cpp): `src/supla/modbus/modbus_client_handler.cpp`
- [Schedule components](https://github.com/supla/supla-device/blob/main/src/supla/control/weekly_schedule_component.h): `src/supla/control/weekly_schedule_component.h`

### Protocol

- [Protocol definitions](https://github.com/supla/supla-device/blob/main/src/supla-common/proto.h): `src/supla-common/proto.h`
- [SRPC](https://github.com/supla/supla-device/blob/main/src/supla-common/srpc.c): `src/supla-common/srpc.c`
- [MQTT handlers](https://github.com/supla/supla-device/blob/main/src/supla/protocol/mqtt_handler_registry.cpp): `src/supla/protocol/mqtt_handler_registry.cpp`

### Platform ports

- [Linux port](https://github.com/supla/supla-device/blob/main/extras/porting/linux/linux_client.cpp): `extras/porting/linux/linux_client.cpp`
- [Linux file storage](https://github.com/supla/supla-device/blob/main/extras/porting/linux/linux_file_storage.cpp): `extras/porting/linux/linux_file_storage.cpp`
- [ESP-IDF port](https://github.com/supla/supla-device/blob/main/extras/porting/esp-idf/esp_idf_client.cpp): `extras/porting/esp-idf/esp_idf_client.cpp`
- [SPIFFS storage](https://github.com/supla/supla-device/blob/main/extras/porting/esp-idf/spiffs_storage.cpp): `extras/porting/esp-idf/spiffs_storage.cpp`

### Other components

- **Firmware developer**
- **SUPLA Server**

## Connections

- Firmware developer → Device API: uses
- Device API → Elements: runs lifecycle
- Elements → Channels: may expose
- Device API → SUPLA Server: connects device
- Device services → Device API: supports device
- Controls → Elements: implements logic
- Sensor handlers → Elements: implements logic
- Weekly schedules → Schedule components: uses
- Modbus integration → Elements: integrates device
- Storage framework → State storage: creates state store (evidence: `src/supla/storage/storage.cpp`)
- Storage framework → Config storage: uses config (evidence: `src/supla/storage/storage.cpp`)
- SRPC → Protocol definitions: uses definitions (evidence: `src/supla-common/srpc.c`)
- Device API → SRPC: uses protocol
- MQTT handlers → SUPLA Server: supports MQTT
- Linux port → SUPLA Server: connects device
- ESP-IDF port → SUPLA Server: connects device
- Linux file storage → Storage framework: implements backend (evidence: `extras/porting/linux/linux_file_storage.cpp`)
- SPIFFS storage → Storage framework: implements backend (evidence: `extras/porting/esp-idf/spiffs_storage.cpp`)