MQTT

Broker

Host	mqtt.finishing2026.sw2e-lab.de:11883
Auth	Passwort-basiert, kein Anonymous
Backend-User	backend — Vollzugriff
ESP-User	esp_device (geteilt) — Client-ID = MAC

Topics

Topic	Richtung	Retained	Beschreibung
devices/register	ESP → Backend	Nein	Thing Model bei Boot
devices/{mac}/telemetry	ESP → Backend	Nein	Sensordaten
devices/{mac}/status	ESP → Backend	Ja	online / offline, LWT = offline
devices/{mac}/command	Backend → ESP	Nein	Commands (via REST ausgelöst)

{mac} = MAC-Adresse des ESP (AA:BB:CC:DD:EE:FF).

ACL (Mosquitto)

ESP-Geräte nutzen esp_device als Username und ihre MAC als MQTT-Client-ID. %c im ACL-Pattern wird zur Client-ID — so kann jeder ESP nur seine eigenen Topics beschreiben und lesen.

user backend
topic readwrite #

user esp_device
topic write devices/register
pattern write devices/%c/telemetry
pattern read  devices/%c/command/#
pattern write devices/%c/status

user gateway
topic write devices/register
topic write devices/+/telemetry
topic write devices/+/status
topic read  devices/+/command

Payloads

Registration (devices/register)

{
  "device_id": "motor-poc-01",
  "mac": "AA:BB:CC:DD:EE:FF",
  "metadata": { "label": "Motor PoC", "category": "Motor" },
  "capabilities": [
    { "id": "power", "type": "ON_OFF", "label": "Motor", "direction": "both" },
    { "id": "speed", "type": "NUMBER", "label": "Geschwindigkeit",
      "direction": "both", "min": 0, "max": 255, "unit": "PWM" }
  ],
  "state": { "power": "OFF", "speed": 180 }
}

Das Backend generiert beim ersten Empfang eine UUID und legt den Gerätedatensatz an. Bei erneutem Boot wird der Datensatz per UPSERT (Konflikt auf mac) aktualisiert.

Telemetry (devices/{mac}/telemetry)

{
  "timestamp": "2026-05-13T10:00:00.000Z",
  "data": { "power": "ON", "speed": 200, "solar_v": 2.1 }
}

timestamp ist optional — fällt er weg, setzt das Backend die Serverzeit. data akzeptiert beliebige Key-Value-Paare.

Status (devices/{mac}/status)

{ "status": "online" }

Retained. LWT publiziert { "status": "offline" } bei unerwartetem Verbindungsabbruch.

Command (devices/{mac}/command)

{
  "command_id": "550e8400-e29b-41d4-a716-446655440000",
  "capability": "power",
  "value": "ON",
  "timestamp": "2026-05-13T10:00:00.000Z"
}

Wird vom Backend publiziert wenn POST /api/v1/devices/:uuid/command aufgerufen wird. Das Backend löst uuid → mac auf und published auf dem korrekten Topic.

ESP-Verbindung (Arduino/PlatformIO)

const char* MQTT_USER = "esp_device";
const char* MQTT_PASS = "...";
String MAC_ADDR;  // nach WiFi.begin() befüllen

// Topics nach MAC aufbauen
snprintf(TOPIC_TELEM, sizeof(TOPIC_TELEM), "devices/%s/telemetry", MAC_ADDR.c_str());

// Verbinden: client_id = MAC, username = esp_device
mqtt.connect(MAC_ADDR.c_str(), MQTT_USER, MQTT_PASS, TOPIC_STATUS, 0, true, lwt_payload);