<!-- Source: https://docs.captron.com/de/trms/seh/mqtt-interface -->

# MQTT Communication

SENSORhub SEH-Geräte werden über MQTT gesteuert und überwacht. Diese Seite beschreibt die MQTT-Topics und deren Nachrichten-Payloads. Parallel dazu steht eine Modbus-TCP-Schnittstelle zur Verfügung — siehe [Modbus Interface](./modbus-interface.md).

## Definitionen

- `{product}` ist der Name des Produkts, z. B. `SEH101` oder `SEH201`.
- `{device-id}` ist der eindeutige Name des Geräts und besteht aus einer zufällig generierten Wortkombination wie `GroovySquareTongue` oder `TinyHappyGroup`. Diese ID wird zum Aufbau der Topics verwendet und ist auf dem Gerät aufgedruckt.
- `{Content definition}` ist der Teil des Topics nach der `{device-id}`, z. B. `/Pub/MAM`.

Alle Topics folgen diesem Muster:

```text
captron.com/{product}/nd/{device-id}/{Content definition}
```

## Geräteinformationen

### Publish — `/Pub/MAM`

Richtung: Gerät publiziert.

```json
{
  "Content": "/Pub/MAM",
  "BoardName": "lucky_python",
  "Manufacturer": "CAPTRON",
  "Model": "PYTHON-Head",
  "ProductCode": "123456789",
  "SoftwareVersion": "v0.0.1"
}
```

Das Gerät sendet Daten, die generisch und geräteindividuell sind, die Konfiguration, die dem Gerät während des Onboarding-Prozesses übergeben wurde, sowie alle Methoden, die aufgerufen werden können.

### Subscribe — `/Get/MAM`

Richtung: Gerät abonniert. Payload: keine.

Geräteinformationen anfordern. Das Gerät antwortet auf dem entsprechenden Topic `/Pub/MAM`.

## Konfiguration

### Subscribe — `/Set/Config/MQTT`

Richtung: Gerät abonniert.

```json
{
  "Content": "/Set/Config/MQTT",
  "Vendor": "captron",
  "Port": 1883,
  "MQTTServer": "update.oneGrid.captron.com",
  "MQTTUsername": "Captron2022",
  "MQTTPassword": "qwxYT321!",
  "Encryption": false
}
```

Übermittelt die Verbindungsinformationen, die spezifisch für den Betreiber der Anwendung sind, wie z. B. die Serverkonfiguration. Werden keine Anmeldedaten benötigt, ist `null` als Wert für `MQTTUsername` und `MQTTPassword` zu verwenden.

Diese Nachricht wird während des automatischen Onboarding-Prozesses verwendet. Beachten Sie, dass das Gerät nach einem Stromzyklus diese Informationen erneut vom Onboarding-System anfordert.

### Subscribe — `/Set/Config/LedStrip`

Richtung: Gerät abonniert.

```json
{
    "Content": "/Set/Config/LedStrip",
    "Demo": false,
    "LED_STRIP_1":{
        "ColorAlignment": {"Active": true, "R": 255, "G": 180, "B": 255}
    },
    "LED_STRIP_2":{
        "ColorAlignment": {"Active": true, "R": 255, "G": 180, "B": 255}
    },
    etc...
}
```

Anwendungsfallspezifische Konfiguration der LED-Streifen (z. B. Länge als Anzahl der LEDs).

- Ab FW v0.2.10 ist diese Nachricht nicht mehr zwingend erforderlich. Standardmäßig werden 180 LEDs pro Streifen verwendet.
- Der boolesche Wert `Demo` aktiviert/deaktiviert den Demo-Modus. Ist dieser aktiviert, spielt das Gerät unterschiedliche Farben und Effekte auf Ausgang 1 und 2 ab. Diese Einstellung wird dauerhaft im Speicher abgelegt — wird der Demo-Modus aktiviert, bleibt er auch nach einem Stromzyklus aktiv.
- Ab FW V0.3.10-13-G225F748 ist die Farbausrichtung für jeden LED-Streifen möglich. Setzen Sie das Flag `Active` auf `true` und stellen Sie die entsprechenden RGB-Werte im Bereich 0–255 ein.

## LED-Streifen aktivieren

### Subscribe — `/Set/Data/LedStrip`

Richtung: Gerät abonniert.

```json
{
  "Content": "/Set/Data/LedStrip",
  "LED_STRIP_1": {
    "Active": true,
    "Segments": [
      {
        "StartLED": 0,
        "StopLED": 30,
        "Speed": 190,
        "Effect": 1,
        "Colors": [
          {
            "R": 0,
            "G": 150,
            "B": 0
          },
          {
            "R": 0,
            "G": 150,
            "B": 0
          }
        ]
      }
    ]
  }
}
```

Schaltet die LEDs ein.

- Verwenden Sie das Flag `Active`, um den Streifen ein- oder auszuschalten.
- Effekte:
  - 1: FX_MODE_STATIC
  - 2: FX_MODE_BLINK
  - 3: FX_MODE_FLASH
  - 4: FX_MODE_LEADING_LINES
  - 5: FX_MODE_LEADING_LINES_REVERSE
  - 6: FX_MODE_MULTIPICKER
  - 7: FX_MODE_PICK (benötigt mind. FW-Version V0.3.7)
  - 8: FX_MODE_PLACE (benötigt mind. FW-Version V0.3.7)
  - 200: FX_MODE_CUSTOM_KNIGHT_RIDER
- Geschwindigkeit von 1 (langsam) bis 250 (schnell).
- Mehrere Farben gelten nur für bestimmte Effekte wie FX_MODE_MULTIPICKER. In diesem Fall wechseln die Farben zwischen den im Array `Colors` angegebenen RGB-Werten. Bei allen anderen Effekten gilt nur die erste Farbe im Array.
- Es können 6 Segmente mit unterschiedlichen Farben/Effekten gesetzt werden. Je nach maximaler MQTT-Nachrichtengröße können weitere Segmente gesetzt werden. Die MQTT-Nachrichtengröße muss unter 4k liegen.
- Dieser Befehl kann ignoriert werden, wenn eine Leistungsgrenze erreicht wird. In diesem Fall wird eine Fehlermeldung protokolliert, um den Benutzer zu informieren.

## Steuerung der SMC-Taster (Geräte SEH20x/SEH11)

Die Steuerung der SMC-Taster (SENSORswitches) ist bei SEH11 und SEH201 verfügbar. Die an den Hub angeschlossenen SMC-Taster werden über ein einziges Topic gesteuert. Die Modbus-Schnittstelle bietet dieselbe SMC-Steuerung parallel an — siehe [Modbus Interface](./modbus-interface.md).

Implementiert in FW V0.2.5.

### Subscribe — `/Set/Data/Smc`

Richtung: Gerät abonniert.

```json
{
  "Content": "/Set/Data/Smc",
  "Address": "{Button address, HUB or ALL_SENSORS}",
  "CommandType": "{Command Type}",
  "Offset": "{Offset}",
  "Payload": "{Payload}"
}
```

- **Address** — eine bestimmte Taster-Adresse, `HUB` (der SEH selbst) oder `ALL_SENSORS` (Broadcast an alle Taster).
- **CommandType** und **Offset** bestimmen gemeinsam, welcher Befehl ausgeführt wird und wie die Zeichenkette `Payload` interpretiert wird.

Folgende Befehle stehen zur Verfügung:

<table>
  <colgroup>
    <col style={{ minWidth: '160px' }} />
    <col />
    <col />
    <col />
  </colgroup>
  <thead>
    <tr>
      <th>Befehl</th>
      <th>CommandType</th>
      <th>Offset</th>
      <th>Payload</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>LED-Ring und Anzeige setzen</td>
      <td>SET_PARAMETER</td>
      <td>PRE_BUTTON_MODE oder POST_BUTTON_MODE</td>
      <td><code>&#123;ENABLED, DISABLED or LONGPRESS_ENABLED&#125;/&#123;Quantity&#125;/&#123;LED ring color&#125;/&#123;LED ring effect&#125;/&#123;Display text&#125;</code></td>
    </tr>
    <tr>
      <td>Tasterausrichtung setzen</td>
      <td>SET_PARAMETER</td>
      <td>BUTTON_ROTATE</td>
      <td><code>BUTTON_ROTATION_NORMAL</code> oder <code>BUTTON_ROTATION_UPSIDEDOWN</code></td>
    </tr>
    <tr>
      <td>Longpress-Zeit setzen</td>
      <td>SET_PARAMETER</td>
      <td>LONGPRESS_TIME</td>
      <td>Millisekunden geteilt durch 10 (max. 2,55 Sekunden)</td>
    </tr>
    <tr>
      <td>Taster-Adresse zuweisen</td>
      <td>SET_STATUS</td>
      <td>ADDRESS_TO_BE_ASSIGNED</td>
      <td>Zuzuweisende Nummer</td>
    </tr>
    <tr>
      <td>Spezialbefehle (Pre-/Post-Zustand umschalten, Neustart usw.)</td>
      <td>SET_STATUS</td>
      <td>SPECIAL_COMMANDS</td>
      <td><code>PRE_PRESSED_STATE</code>, <code>POST_PRESSED_STATE</code>, <code>REBOOT</code>, <code>SHOW_CURRENT_ADDRESS</code> oder <code>LONG_PRESSED_STATE</code></td>
    </tr>
    <tr>
      <td>Polling-Funktion (Address = HUB)</td>
      <td>SET_PARAMETER</td>
      <td>(keiner)</td>
      <td>Polling-Adressen getrennt durch <code>/</code> (bis zu 6), z. B. <code>1002/1003/1004</code>; <code>0000</code> schaltet das Polling aus</td>
    </tr>
  </tbody>
</table>

**Spezialbefehle** (Offset `SPECIAL_COMMANDS`):

- `PRE_PRESSED_STATE` — in den Pre-Zustand setzen
- `POST_PRESSED_STATE` — in den Post-Zustand setzen
- `REBOOT` — Taster neu starten
- `SHOW_CURRENT_ADDRESS` — Taster-Adresse anzeigen
- `LONG_PRESSED_STATE` — in den Longpress-Zustand setzen (benötigt mind. SEH-Firmware V0.2.27-3)

:::note
Ältere Firmware-Versionen übernehmen die Einstellung der **Tasterausrichtung** nach einem Power-Cycle nicht. In diesem Fall muss der Befehl nach jedem Power-Cycle des SMC-Tasters erneut gesendet werden.<br/>
Der Befehl **Longpress-Zeit** benötigt mind. Firmware V5.3.9 auf dem SMC-Taster.
:::

### Publish — `/Pub/Data/Smc`

Richtung: Gerät publiziert.

Wenn das Polling für eine Taster-Adresse aktiv ist, wird eine Tasterberührung auf diesem Topic gemeldet:

```json
{
  "Content": "/Pub/Data/Smc",
  "Address": "{touched button address}",
  "CommandType": "SET_STATUS",
  "Payload": "POST_PRESSED_STATE"
}
```

### LED-Ring und Anzeige setzen

Für den Befehl **LED-Ring und Anzeige setzen** (CommandType `SET_PARAMETER`, Offset `PRE_BUTTON_MODE` oder `POST_BUTTON_MODE`) ist die `Payload` eine durch `/` getrennte Zeichenkette:

```text
{ENABLED, DISABLED or LONGPRESS_ENABLED}/{Quantity}/{LED ring color}/{LED ring effect}/{Display text}
```

**Button-Modus** (erstes Feld):

- `ENABLED` — Taster kann bestätigt werden; LED-Ring und Anzeige können gesteuert werden.
- `DISABLED` — Taster kann NICHT bestätigt werden; LED-Ring und Anzeige können gesteuert werden.
- `LONGPRESS_ENABLED` — der Taster geht nach einer bestimmten Berührungsdauer (Standard 2 Sekunden) in den Longpress-Zustand; LED-Ring und Anzeige für diesen Zustand werden über den Offset `POST_BUTTON_MODE` gesetzt.

**Quantity** — eine Zahl von 1 bis 9999. Sie wird automatisch mittig auf der Anzeige ausgerichtet.

**LED-Ring-Farbe:**

- `COLOFF`
- `COLRED`
- `COLGREEN`
- `COLBLUE`
- `COLYELLOW`
- `COLMAGENTA`
- `COLCYAN`
- `COLWHITE`

**LED-Ring-Effekt:**

- `SOLID_RING`
- `FLASH_RING`
- `CONFIRM`
- `POINT_ANIMATED_CLOCK`
- `CIRCLE_ANIMATED_CLOCK`
- `SOLID_ARROW_UP`, `SOLID_ARROW_DOWN`, `SOLID_ARROW_LEFT`, `SOLID_ARROW_RIGHT`
- `FLASH_ARROW_UP`, `FLASH_ARROW_DOWN`, `FLASH_ARROW_LEFT`, `FLASH_ARROW_RIGHT`
- `ANIMATED_ARROW_UP`, `ANIMATED_ARROW_DOWN`, `ANIMATED_ARROW_LEFT`, `ANIMATED_ARROW_RIGHT`
- Diagonale Pfeile: `SOLID_ARROW_UP_LEFT`, `SOLID_ARROW_UP_RIGHT`, `SOLID_ARROW_DOWN_LEFT`, `SOLID_ARROW_DOWN_RIGHT`, `FLASH_ARROW_UP_LEFT`, `FLASH_ARROW_UP_RIGHT`, `FLASH_ARROW_DOWN_LEFT`, `FLASH_ARROW_DOWN_RIGHT`

:::note
Die diagonalen Pfeileffekte benötigen mind. Firmware V5.3.7 auf dem SMC-Taster.
:::

**Display text** — max. 4 Zeichen. Einige Zeichen können aufgrund der 7-Segment-Beschränkungen nicht dargestellt werden. Verwenden Sie `@` als Leerzeichen (Beispiele: `@Go@`, `donE`).

Wenn sowohl **Quantity** als auch **Display text** definiert sind, wird **Quantity** verwendet. Wird **Display text** verwendet, erfolgt keine automatische Ausrichtung — der Benutzer muss sich selbst darum kümmern (z. B. eine linksbündige Zahl als `42@@`, eine rechtsbündige Zahl als `@@42`). Wird **Quantity** verwendet, erfolgt die Ausrichtung automatisch.

### Beispiele

Senden an den SMC-Taster mit der Adresse `1000`.

LED-Ring-Farbe auf Grün (blinkend) setzen und eine Menge von `42` anzeigen:

```json
{
  "Content": "/Set/Data/Smc",
  "Address": "1000",
  "CommandType": "SET_PARAMETER",
  "Offset": "PRE_BUTTON_MODE",
  "Payload": "ENABLED/42/COLGREEN/FLASH_RING"
}
```

LED-Ring-Farbe auf Blau setzen und `donE` im Post-Pressed-/Longpress-Zustand anzeigen:

```json
{
  "Content": "/Set/Data/Smc",
  "Address": "1000",
  "CommandType": "SET_PARAMETER",
  "Offset": "POST_BUTTON_MODE",
  "Payload": "ENABLED//COLBLUE/SOLID_RING/donE"
}
```

Taster in den Pre-Pressed-Zustand umschalten:

```json
{
  "Content": "/Set/Data/Smc",
  "Address": "1000",
  "CommandType": "SET_STATUS",
  "Offset": "SPECIAL_COMMANDS",
  "Payload": "PRE_PRESSED_STATE"
}
```

Longpress-Zeit auf 1 Sekunde setzen:

```json
{
  "Content": "/Set/Data/Smc",
  "Address": "1000",
  "CommandType": "SET_PARAMETER",
  "Offset": "LONGPRESS_TIME",
  "Payload": "100"
}
```

Senden an alle angeschlossenen SMC-Taster — alle Taster in den Pre-Pressed-Zustand umschalten:

```json
{
  "Content": "/Set/Data/Smc",
  "Address": "ALL_SENSORS",
  "CommandType": "SET_STATUS",
  "Offset": "SPECIAL_COMMANDS",
  "Payload": "PRE_PRESSED_STATE"
}
```

## Health und Status

### Publish — `/Pub/Health/LedStrip`

Richtung: Gerät publiziert.

```json
{
  "Content": "/Pub/Health/LedStrip",
  "Firmware": "V0.1.0",
  "LED_STRIP_1": {
    "Length": 42,
    "Active": true,
    "CheckPassed": true
  },
  "LED_STRIP_2": {
    "Length": 42,
    "Active": false,
    "CheckPassed": true
  },
  "LED_STRIP_3": {
    "Length": 42,
    "Active": false,
    "CheckPassed": true
  },
  "LED_STRIP_4": {
    "Length": 0,
    "Active": false,
    "CheckPassed": true
  },
  "LED_STRIP_5": {
    "Length": 0,
    "Active": false,
    "CheckPassed": true
  }
}
```

Der Zustand der an das Board angeschlossenen LED-Streifen. Diese Nachricht wird nach dem Einschalten des Geräts publiziert.

### Subscribe — `/Get/Health/LedStrip`

Richtung: Gerät abonniert. Payload: keine.

Status und Informationen der LED-Streifen anfordern. Das Gerät antwortet auf dem entsprechenden Topic `/Pub/Health/LedStrip`.

### Publish — `/Pub/Health/SysLog`

Richtung: Gerät publiziert.

Payload: Ereignisprotokollierung (Info, Warnung, Fehler usw.), Version, Betriebszeit, IP-Adresse usw.

Das Syslog eines Geräts. Diese Nachricht wird alle 6 h sowie bei einer Anfrage zum Status der LED-Streifen publiziert. Diagnosemeldungen (z. B. erkannte Verdrahtungsfehler, Überlastungen usw.) werden ebenfalls auf diesem Topic publiziert — diese Meldungen sind mit `[DIAGNOSIS]` gekennzeichnet.

## Allgemeine Einstellungen

### Subscribe — `/Set/Config/Common`

Richtung: Gerät abonniert.

```json
{
    "Content": "/Set/Config/Common",
    "LogLevel": {1 to 6},
    "StartDiagnosis": true
}
```

**LogLevel** — legt die Log-Stufe fest. Die Standardeinstellung ist `3` (Warning). Folgende Stufen können eingestellt werden:

- 1 – Fatal
- 2 – Error
- 3 – Warning (Standard)
- 4 – Notice (protokolliert z. B. die Antwort, wenn ein LED-Segment aktiviert wird)
- 5 – Info
- 6 – Trace

Log-Meldungen mit der gewählten und niedrigeren Nummer (höherer Schweregrad) werden auf dem Syslog-Topic publiziert. Wird die Log-Stufe z. B. auf 4 gesetzt, publiziert das Gerät Log-Meldungen der Stufen Fatal, Error, Warning und Notice. Die Log-Stufen-Einstellung wird nicht im Flash gespeichert — das Gerät startet immer mit der Standardeinstellung.

**StartDiagnosis** (nur für die Geräte SEH101 und SEH201) — startet die Diagnose an den Ausgangsklemmen und prüft z. B. auf Verdrahtungsfehler. Mögliche Fehler werden auf dem Syslog-Topic publiziert. Die Diagnose wird beim Start automatisch ausgeführt; dieses Flag löst die Funktion einmalig aus.

## Firmware-Update

### Subscribe — `/Call/FirmwareUpdate`

Richtung: Gerät abonniert.

```json
{
  "Content": "/Call/FirmwareUpdate",
  "Url": "http://onegrid-fwupd.germanywestcentral.cloudapp.azure.com:80/ota/firmware_V0.3.9-pythonhB.img"
}
```

Startet den Update-Prozess.

:::note
Der SEH201 verwendet Firmware-Dateien mit dem Namen `firmware_V0.x.y-pythonhB_smc.img`.
:::

## Zeitverteilung

### Subscribe — `/Set/Config/Time`

Richtung: Gerät abonniert. Topics:

```text
captron.com/Time
captron.com/{product}/nd/{device-id}/Set/Config/Time
```

```json
{
  "Content": "/Set/Config/Time",
  "DateTime": "%Y-%m-%d %H:%M:%S"
}
```

Verteilt die Zeit an jedes Gerät. Zeichenkette im Format `%Y-%m-%d %H:%M:%S`, z. B. `2023-02-28T11:18:30`.

## Statussignalisierung

Beim Start wird der Gerätestatus über die angeschlossenen LED-Streifen signalisiert. Um die Installation zu erleichtern (Zuordnung der Streifen zu den Ausgängen), leuchtet an jedem Ausgang eine unterschiedliche Anzahl von LEDs auf: An Ausgang 1 leuchtet eine LED, an Ausgang 2 leuchten zwei LEDs usw. Die Signalisierungsfarben werden bis zum ersten `/Set/Data`-Befehl angezeigt.

<table>
  <thead>
    <tr>
      <th>Farbe</th>
      <th>Status</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>Red</td>
      <td>Ethernet-/WLAN-Verbindungsversuch, keine Ethernet-/WLAN-Verbindung</td>
    </tr>
    <tr>
      <td>Yellow</td>
      <td>MQTT-Verbindungsversuch, keine MQTT-Verbindung</td>
    </tr>
    <tr>
      <td>Blue</td>
      <td>Fallback-Mechanismus aktiv (geplant ab V0.2.33/V0.3.6), Konfiguration und/oder Netzwerkverbindung prüfen</td>
    </tr>
    <tr>
      <td>Cyan/Green-Blue</td>
      <td>Verbindung hergestellt — zum Onboarding-Dienst (falls kein Anwender-MQTT konfiguriert ist) oder zum Anwender-MQTT (falls konfiguriert)</td>
    </tr>
  </tbody>
</table>

## Diagnosemeldungen (für SEHx01-Geräte)

Diagnosemeldungen werden auf dem Syslog-Topic publiziert.

<table>
  <thead>
    <tr>
      <th>Fehler</th>
      <th>Meldung</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>Spannung für LEDs außerhalb des Bereichs (4,5 V – 5,5 V), z. B. schwaches USB-Netzteil</td>
      <td><code>[DIAGNOSIS] led voltage outside range</code></td>
    </tr>
    <tr>
      <td>LED-Strom unterhalb des erwarteten Stroms für aktivierte Segmente, z. B. LED-Streifen beschädigt, LEDs außerhalb der Streifenlänge aktiviert</td>
      <td><code>[DIAGNOSIS] expected current not in range</code></td>
    </tr>
    <tr>
      <td>
        Verdrahtungsfehler oder Überstrom, Details in ERROR_BITS:
        <ul>
          <li>1: Verdrahtungsfehler am Pin Data/GND</li>
          <li>2, 4: Verdrahtungsfehler am Pin Vled/GND</li>
          <li>32: LED-Leistung hat die Grenze des Netzteils erreicht</li>
        </ul>
      </td>
      <td><code>[DIAGNOSIS] failed: &#123;ERROR_BITS&#125;</code></td>
    </tr>
  </tbody>
</table>