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.

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:

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

Geräteinformationen

Publish — /Pub/MAM

Richtung: Gerät publiziert.

{
  "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.

{
  "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.

{
    "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.

{
  "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.

Implementiert in FW V0.2.5.

Subscribe — /Set/Data/Smc

Richtung: Gerät abonniert.

{
  "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:

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

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)

hinweis

Ä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.
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:

{
  "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:

{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

hinweis

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:

{
  "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:

{
  "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:

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

Longpress-Zeit auf 1 Sekunde setzen:

{
  "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:

{
  "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.

{
  "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.

{
    "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.

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

Startet den Update-Prozess.

hinweis

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:

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

{
  "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.

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

Diagnosemeldungen (für SEHx01-Geräte)

Diagnosemeldungen werden auf dem Syslog-Topic publiziert.

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