Discovery - MQTT

Discovery

Mit der Discovery können die erhältlichen Informationen zu einem Topic abgerufen werden. Diese Informationen werden dann als JSON-Nachricht zurückgesendet.

Das Discovery kann auch für ein gesamtes System oder für alle Elemente des Geräts angefordert werden.

Um ein Discovery anzufragen, muss einfach „/discovery“ an das gewünschte Topic angehängt werden. Als Anwort wird das Topic mit „/info“ am Ende als Antwort gesendet. Beispiele:

12XY-X34Z-XY12-3XZ4/lights/item0/discovery
12XY-X34Z-XY12-3XZ4/lights/discovery  
12XY-X34Z-XY12-3XZ4/discovery

Die Antwort wird ein JSON Objekt enthalten, mit einer JSON-Node für jedes Element.

Beispiel weiter unten

Discovery und Berechtigungen

Wenn das Gerät im „Read+Write“-Modus ist, sobald das Discovery ausgeführt wird, wird das Gerät zurück in then „Read“-Modus versetzt.

Dies passiert, um das Gerät vor unbefugten Zugriff zu schützen, da das Discovery auf diese Weise auch die Kommandos preisgibt.

Discovery mit Topic Präfix

Wenn der Topic Präfix aktiviert ist, kann auch über diesen ein Discovery ausgeführt werden.

mybuilding_1/discovery

Als Antwort erhält man in diesem Falle eine Nachricht pro verbundenem Controller, die jeweils nur die ID enthält. Mit der ID können dann weitere Discoveries auf deren Elemente durchgeführt werden. In diesem Fall muss bekannt sein, welche ID zu welchem Controller gehört, da das Payload nur die ID und keine Namen oder sonstige Informationen enthält

Beispiel weiter unten

Eigenschaften im Discovery

  • Permission (Bereichtigungen): gibt an, ob das Element ein Zustand („READ“) oder ein Befehl („WRITE“) ist.
  • Description (Beschreibung): enthält eine kurze Erläuterung der Bedeutung des Zustands. Falls erforderlich, wird auch ein Beispiel angeführt.
  • Format: hat immer die gleiche Struktur: datatype[range](unit). Zunächst wird der Datentyp angegeben (int, float, string, enum...). Dann wird innerhalb des [ ] der Bereich angegeben, die Grenzen sind getrennt durch ein Komma (zum Beispiel [-100.00,100.00]). Und schließlich die Einheit, die innerhalb der Klammern angegeben wird. Zum Beispiel werden Meter als (m) angegeben, wobei immer das Internationale System (IS) verwendet wird.
  • Type (Typ): gibt den Typ der Variablen aus der Sicht des Controllers an. Es kann AI (Analogeingang, von außen zum Controller), AO (Analogausgang: vom Controller nach außen), AV (Analogwert, wird als Eingangsparameter beim Senden von Befehlen verwendet) oder STRING sein.

Beispiel - Element-Discovery

Gesendet:

Topic: 

12XY-X34Z-XY12-3XZ4/lights/item0/discovery

Payload: 

""


Erhalten:

Topic: 

12XY-X34Z-XY12-3XZ4/lights/item0/info

Payload: 

{  
    "dimLevel": {  
        "permission": "READ",  
        "description": "Current value of the intensity of the light, where 0.00% means completely off, and 100.00% means completely on", 
        “format”: ”float[0.00,100.00](%)”,  
        "type": "AO"  
    },  
    "setDimLevel": {  
        "permission": " WRITE ",  
        "description": "Set the current value of the dimLevel",  
        “format”: ”float[0.00,100.00](%)”,  
        "type": " AV"  
    },  
    "currentState": {  
        "permission": " READ ",  
        "description": "Current state of the light",  
        “format”: “enum[0=off,1=on]()”, 
        "type": "AO"  
    },  
    "setRGBColor": {  
        "permission": " WRITE ",  
        "description": "Modify the current RGB color of the RGB light. Example: green color is desired --> R=0, G=255, B=0 --> R=0x00, G=0xFF, B=0x00 --> colorRGB=0x00FF00 --> colorRGB=65280", 
        “format”: “int[24bit->R:23-16|G:15-8|B:7-0]()”,  
        "type": "AV"  
    },  
    "setCurrentState": {  
        "permission": " WRITE ",  
        "description": "Set the current state of the light", 
        “format”: “enum[0=off,1=on]()”,  
        "type": " AV"  
    },  
    "toggleCurrentState ": {  
        "permission": "WRITE",  
        "description": "Toggle the current state of the light", 
        “format”: “enum[1=toggle]()”,  
        "type": " AV"  
    },  
    "rgbColor": {  
        "permission": " READ ",  
        "description": "Current RGB color of the light. Example: colorRGB=16721246 --> colorRGB=0xFF255E --> R=0xFF, G=0x25, B=0x5E --> R=255, G=37, B=94",  
        “format”: “int[24bit->R:23-16|G:15-8|B:7-0]()”, 
        "type": "AO"  
    }  
}

Beispiel - Discovery des Topic Präfix

Gesendet:

Topic: 

myBuilding-01/discovery

Payload: 

""


Erhalten:

Topic: 

myBuilding-01/info

Payload: 

{ 
	"myGEKKO_ID":	"12XY-X34Z-XY12-3XZ4" 
}