Dokumentace · Pro výrobce zařízení

Vlastní zařízení s ESP32: příklad a pomoc s integrací

Poslední změna: Verze textu 1 z 13. 11. 2026English version

Obsah

Tato stránka je pro výrobce, kteří chtějí onlineWatt zabudovat do vlastního zařízení, nebo si postavit vlastní převodník s mikrokontrolérem ESP32. Ukazuje nejkratší cestu od prázdné desky k hodnotám v portálu. Úplný popis rozhraní je na stránce Připojení zařízení: MQTT a HTTP API.

Co budete potřebovat

  • Účet výrobce v onlineWattu – zřizuje se po dohodě, viz Portál pro výrobce zařízení.
  • Typ zařízení s komunikací MQTT a mappingem a v něm jedno založené zařízení na zkoušku. Z jeho detailu opíšete MQTT uživatele, MQTT heslo a číslo zařízení z MQTT topiků.
  • Adresu MQTT brokeru – dostanete ji od onlineWattu při zřízení účtu.
  • Desku s ESP32 (příklad je přeložený pro ESP32-S3) a vývojové prostředí pro Arduino core 3.x, například PlatformIO; knihovnu ArduinoJson 7.

Postup

1. Založte typ a zařízení v portálu

V menu Typy zařízení klikněte na Přidat typ zařízení, zvolte Technologie a Komunikace MQTT a do pole Mapping zapište hodnoty, které budete posílat. Potom v menu Zařízení klikněte na Přidat zařízení.

2. Opište přístupové údaje

Zařízení → tři tečky → Editovat: MQTT uživatel, MQTT heslo a MQTT topiky. Číslo v topiku onlinewatt/devices/123/metrics je číslo zařízení (DEVICE_ID).

3. Nahrajte příklad

Doplňte údaje na začátku souboru a příklad nahrajte do desky.

4. Zkontrolujte portál

V seznamu Zařízení se u vašeho kusu do minuty změní čas ve sloupci Poslední metriky. Hodnoty uvidí zákazník nebo instalační firma, která si zařízení zaregistruje sériovým číslem a registračním tokenem. Ty patří na výrobní štítek zařízení; pro zařízení s ESP32 vám můžeme dodat připravené štítky se sériovým číslem a tokenem – napište na info@onlinewatt.com.

Příklad

Příklad se připojí k Wi-Fi a k brokeru přes TLS, jednou za minutu pošle průměr naměřených hodnot, přijímá příkazy z portálu a odpovídá na ně.

// onlineWatt – minimální příklad pro ESP32 (Arduino core 3.x, ESP-IDF 5)
// Posílá metriky jednou za minutu, přijímá příkazy z portálu a odpovídá na ně.
#include <Arduino.h>
#include <WiFi.h>
#include <ArduinoJson.h>
#include <esp_crt_bundle.h>
#include <mqtt_client.h>

// --- Doplňte. V ostrém zařízení ukládejte údaje do NVS, ne do zdrojového kódu. ---
static const char* WIFI_SSID  = "vase-wifi";
static const char* WIFI_PASS  = "heslo-wifi";
static const char* BROKER_URI = "mqtts://ADRESA_BROKERU:PORT";  // sdělí onlineWatt
static const char* DEVICE_ID  = "123";            // číslo z MQTT topiků v detailu zařízení
static const char* MQTT_USER  = "mqtt-uzivatel";  // MQTT uživatel z detailu zařízení
static const char* MQTT_PASS  = "mqtt-heslo";     // MQTT heslo z detailu zařízení

static esp_mqtt_client_handle_t client = nullptr;
static volatile bool mqttConnected = false;
static QueueHandle_t commands = nullptr;
static String topicBase, clientId;

static bool publishJson(const char* suffix, JsonDocument& doc) {
  if (!mqttConnected) return false;
  String topic = topicBase + "/" + suffix, payload;
  serializeJson(doc, payload);
  // QoS 1, bez retain
  return esp_mqtt_client_enqueue(client, topic.c_str(), payload.c_str(), payload.length(), 1, 0, true) >= 0;
}

static void onMqttEvent(void*, esp_event_base_t, int32_t eventId, void* data) {
  auto* ev = static_cast<esp_mqtt_event_handle_t>(data);
  switch ((esp_mqtt_event_id_t)eventId) {
    case MQTT_EVENT_CONNECTED: {
      mqttConnected = true;
      String t = topicBase + "/commands";
      esp_mqtt_client_subscribe(client, t.c_str(), 1);
      break;
    }
    case MQTT_EVENT_DISCONNECTED:
      mqttConnected = false;
      break;
    case MQTT_EVENT_DATA: {
      if (ev->data_len != ev->total_data_len) break;      // příkazy jsou krátké, fragmenty neřešíme
      char* copy = strndup(ev->data, ev->data_len);       // zpracujeme v loop(), ne v obsluze události
      if (copy && xQueueSend(commands, &copy, 0) != pdTRUE) free(copy);
      break;
    }
    default:
      break;
  }
}

static void startMqtt() {
  topicBase = String("onlinewatt/devices/") + DEVICE_ID;
  clientId = "esp32-" + String((uint32_t)(ESP.getEfuseMac() >> 16), HEX);  // musí být jedinečné

  esp_mqtt_client_config_t cfg = {};
  cfg.broker.address.uri = BROKER_URI;
  cfg.broker.verification.crt_bundle_attach = esp_crt_bundle_attach;  // ověření certifikátu serveru (TLS)
  cfg.credentials.client_id = clientId.c_str();
  cfg.credentials.username = MQTT_USER;
  cfg.credentials.authentication.password = MQTT_PASS;
  cfg.session.disable_clean_session = true;  // trvalá relace: příkazy se při výpadku neztratí
  cfg.session.keepalive = 60;
  cfg.network.reconnect_timeout_ms = 10000;

  client = esp_mqtt_client_init(&cfg);
  esp_mqtt_client_register_event(client, MQTT_EVENT_ANY, onMqttEvent, nullptr);
  esp_mqtt_client_start(client);
}

// Sem patří čtení vašeho zařízení (Modbus, čidla…). Příklad vrací smyšlené hodnoty.
static float readPvPowerKw()   { return 2.0f + (float)random(0, 100) / 100.0f; }
static float readBatterySoc()  { return 64.5f; }

static void handleCommand(const char* json) {
  JsonDocument cmd, resp;
  if (deserializeJson(cmd, json)) return;
  const char* name = cmd["command"] | "";
  resp["uid"] = cmd["uid"];                       // uid vraťte beze změny, portál podle něj spáruje odpověď
  bool button = strncmp(name, "IndoorTemp", 10) == 0;   // tlačítka portálu: IndoorTemp-2 … IndoorTemp+2
  if (button || strcmp(name, "set_temperature") == 0) {
    int offset = button ? atoi(name + 10) : (cmd["temperature_offset"] | 0);
    // Zde nastavte zařízení. Potom pošlete událost se speciální akcí pro daný posun
    // (topik events, {"id": číslo události}) a nový stav v dalších metrikách.
    resp["response"]["success"] = true;
    resp["response"]["message"] = String("Posun teploty nastaven na ") + offset + " °C";
  } else {
    resp["response"]["success"] = false;
    resp["response"]["message"] = String("Neznámý příkaz: ") + name;
  }
  publishJson("commands_response", resp);
}

void setup() {
  Serial.begin(115200);
  commands = xQueueCreate(8, sizeof(char*));
  WiFi.begin(WIFI_SSID, WIFI_PASS);
  while (WiFi.status() != WL_CONNECTED) delay(500);
  startMqtt();
}

void loop() {
  static uint32_t lastSample = 0, lastSend = 0, samples = 0;
  static float sumPower = 0;

  char* json = nullptr;
  if (xQueueReceive(commands, &json, 0) == pdTRUE && json) {
    handleCommand(json);
    free(json);
  }

  if (millis() - lastSample >= 1000) {            // vzorek každou sekundu
    lastSample = millis();
    sumPower += readPvPowerKw();
    samples++;
  }

  if (millis() - lastSend >= 60000 && samples) {  // jednou za minutu průměr vzorků
    lastSend = millis();
    JsonDocument m;                               // plochý JSON, názvy podle mappingu typu zařízení
    m["mppt1_power"] = sumPower / samples;
    m["battery_soc"] = readBatterySoc();
    m["sw_version"]  = "1.0.0";
    if (publishJson("metrics", m)) { sumPower = 0; samples = 0; }
  }
  delay(10);
}

Pravidla, která musí zařízení dodržet

  • Jen šifrované spojení (TLS) s ověřením certifikátu serveru.
  • Jedinečné client_id pro každý kus, například odvozené z výrobního čísla čipu.
  • Trvalá relace: vypnutý clean session. Stačí MQTT 3.1.1; u MQTT 5 nastavte Session Expiry Interval.
  • Metriky jednou za minutu, QoS 1, bez příznaku retain. Posílejte průměr vzorků od minulého odeslání; zpětné doposílání starších dat portál nepřijímá.
  • Když metriky asi 5 minut nepřijdou, portál zařízení označí jako offline. Zvláštní zprávu o stavu (last will, heartbeat) neposílejte.
  • Jedno zařízení v portálu je buď fotovoltaika, nebo tepelné čerpadlo. Více střídačů v jednom místě sečtěte do jedněch hodnot.
  • Znaménka: minus znamená vybíjení baterie a dodávku do distribuční sítě; plus výrobu, nabíjení a odběr ze sítě.
  • Verze posílejte v polích hw_version a sw_version.
  • Na každý příkaz odpovězte se stejným uid. Po změně teploty pošlete událost se speciální akcí pro daný posun a nový stav v dalších metrikách.
  • Přístupové údaje neukládejte do zdrojového kódu. Zapisujte je do zařízení až při výrobě, do chráněné paměti.

Jiné mikrokontroléry a jazyky

Rozhraní je obyčejné MQTT s JSON, takže stejně poslouží jiný mikrokontrolér, jednodeskový počítač nebo PLC s klientem MQTT a podporou TLS. Platí stejná pravidla jako výše. Pro PLC Tecomat je samostatný příklad v prostředí Mosaic.

Vývoj s pomocí umělé inteligence

AI asistenti umějí firmware pro ESP32 psát dobře. Dejte asistentovi odkaz na tuto stránku a na stránku Připojení zařízení: MQTT a HTTP API a napište mu:

  • jakou desku máte a jak čte data (Modbus RTU nebo TCP, čidla, vlastní sběrnice),
  • které hodnoty chcete posílat a pod jakými názvy polí,
  • zda má zařízení přijímat příkazy,
  • že má dodržet pravidla z této stránky.

Přístupové údaje zařízení do konverzace s AI nevkládejte; doplňte je až do hotového zařízení.

Pomůžeme vám

S integrací pomáháme: s návrhem mappingu a typů událostí, se zkušebním zařízením i s kontrolou, že data do portálu chodí správně. Napište na info@onlinewatt.com, jaké zařízení vyrábíte a jak komunikuje.

Limity příkladu

  • Příklad je výchozí bod, ne hotový firmware: neřeší nastavení Wi-Fi uživatelem, vzdálené aktualizace, ukládání údajů do chráněné paměti ani čtení skutečného zařízení.
  • Hodnoty v příkladu jsou smyšlené.

← Celá dokumentace · Našli jste chybu nebo vám něco chybí? Napište na info@onlinewatt.com.