MQTT eng: Unterschied zwischen den Versionen
Lh (Diskussion | Beiträge) (Die Seite wurde neu angelegt: „<br /> Datei:MQTT.png <br /><u>Enable MQTT:</u>Enables MQTT support. <br /><u>Broker:</u>DNS or IP address of the MQTT broker. <br /><u>TLS:</u>Turns on TL…“) |
Lh (Diskussion | Beiträge) |
||
Zeile 1: | Zeile 1: | ||
− | + | This device supports MQTT 3.1.1 to send configured messages and also to receive commands. This chapter is general for all Gude devices, some Gude models do not have switchable ports. | |
− | + | <br />* Default port for an unencrypted connection is port 1883. | |
− | <br /> | + | <br />* Default port for a TLS secured connection is port 8883. |
− | <br /> | + | <br />* If the broker allows anonymous login, username and password are arbitrary, but a username must be specified. |
− | <br /> | + | <br />* If multiple MQTT clients are connected to a broker, the names of the clients must be different. For this reason, "client_xxxx" is generated as the default name. Here "xxxx" are the last 4 digits of the MAC address. |
− | <br /> | + | |
− | + | =Message format= | |
− | <br / | + | <br />The MQTT messages of the device are always sent in JSON format. E.G.. |
<br /> | <br /> | ||
− | <br /> | + | <br />{"type": "portswitch", "idx": 2, "port": "2", "state": 1, "cause": {"id": 2, "txt": "http"}, "ts": 1632} |
<br /> | <br /> | ||
− | <br /> | + | <br />This is a switching of the second port to the state on. The source of the switching command is CGI ("http"). The index is always numeric, "port" can also be alphanumeric for devices with multiple banks, e.g. "A2". At the end follows a timestamp ("ts"), which indicates the number of seconds the device is on, or unixtime if the device has synchronized with an NTP server. |
− | <br />< | + | |
− | <br />< | + | =MQTT Topic Prefix= |
− | <br />< | + | <br />The topic prefix for the messages can be set in the MQTT configuration. A default would be e.g. "de/gudesystems/epc/[mac]". Here "[mac]" is a placeholder for the MAC address of the device, another possible placeholder is "[host]", which contains the host name. An example topic for a switching message of the second port would then be: |
− | <br /> [[Datei: | + | <br /> |
− | <br />< | + | <br />"de/gudesystems/epc/00:19:32:01:16:41/switch/2". |
− | <br />< | + | |
+ | =Executing console commands= | ||
+ | <br />The device can be controlled remotely via MQTT using console commands. A list of all commands can be found in the Console chapter. Depending on the topic, the commands are accepted in different formats. | ||
+ | <br /> [[Datei:Wichtig_zeichen.png]] As default the execution of commands is not allowed, but must be enabled in the MQTT configuration! ("Permit CLI commands") | ||
+ | <br /> | ||
+ | <br />'''Format 1: Command in JSON Syntax''' | ||
+ | <br /> | ||
+ | <br />Publish Topic: "de/gudesystems/epc/00:19:32:01:16:41/cmd" | ||
+ | <br /> | ||
+ | <br />Publish Message: "{"type": "cli", "cmd": "port 2 state set 1", "id": 10}" | ||
+ | <br /> | ||
+ | <br />Response from device to "de/gudesystems/epc/00:19:32:01:16:41/cmdres" | ||
+ | <br /> | ||
+ | <br />"{"type": "cli", "cmdres": ["OK."], "result": {"num": 0, "hint": "ok"}, "id": 10}" | ||
+ | <br /> [[Datei:Wichtig_zeichen.png]] The JSON object "result" returns whether the command was valid. The object "id" in the command is optional and is passed through in the response from the device. The passed number can help to establish a synchronicity between command and response via the broker. | ||
+ | <br /> | ||
+ | <br />'''Format 2: Raw Text''' | ||
+ | <br /> | ||
+ | <br />Publish Topic: "de/gudesystems/epc/00:19:32:01:16:41/cmd/cli" | ||
+ | <br />Publish Message: "port 2 state set 1". | ||
+ | <br /> | ||
+ | <br />Response from device to "de/gudesystems/epc/00:19:32:01:16:41/cmdres/cli" | ||
+ | <br />"OK." | ||
+ | <br /> | ||
+ | <br />'''Format 3: Simplified port switching''' | ||
+ | <br /> | ||
+ | <br />Publish Topic: "de/gudesystems/epc/00:19:32:01:16:41/cmd/port/2" | ||
+ | <br />Publish Message: "0" or "1". | ||
+ | <br /> | ||
+ | <br />Response from device to "de/gudesystems/epc/00:19:32:01:16:41/cmdres/port/2" | ||
+ | <br />"0" or "1" | ||
+ | <br /> | ||
+ | <br /> [[Datei:Wichtig_zeichen.png]] This special form exists only for the port switching commands. | ||
+ | |||
+ | =Device Data Summary= | ||
+ | <br />In the '''Device Data Summary''' the most important data of the device are summarized in a JSON object and sent periodically in a configurable time interval. This summary depends on the properties of the device and the connected sensors, and could look like this: | ||
+ | <br /> | ||
+ | <br />Topic: en/gudesystems/epc/00:19:32:01:16:41/device/telemetry | ||
+ | <br /> | ||
+ | <br />Message: | ||
+ | <br /> [[Datei:MQTT1.png]] |
Version vom 26. März 2024, 14:50 Uhr
This device supports MQTT 3.1.1 to send configured messages and also to receive commands. This chapter is general for all Gude devices, some Gude models do not have switchable ports.
* Default port for an unencrypted connection is port 1883.
* Default port for a TLS secured connection is port 8883.
* If the broker allows anonymous login, username and password are arbitrary, but a username must be specified.
* If multiple MQTT clients are connected to a broker, the names of the clients must be different. For this reason, "client_xxxx" is generated as the default name. Here "xxxx" are the last 4 digits of the MAC address.
Message format
The MQTT messages of the device are always sent in JSON format. E.G..
{"type": "portswitch", "idx": 2, "port": "2", "state": 1, "cause": {"id": 2, "txt": "http"}, "ts": 1632}
This is a switching of the second port to the state on. The source of the switching command is CGI ("http"). The index is always numeric, "port" can also be alphanumeric for devices with multiple banks, e.g. "A2". At the end follows a timestamp ("ts"), which indicates the number of seconds the device is on, or unixtime if the device has synchronized with an NTP server.
MQTT Topic Prefix
The topic prefix for the messages can be set in the MQTT configuration. A default would be e.g. "de/gudesystems/epc/[mac]". Here "[mac]" is a placeholder for the MAC address of the device, another possible placeholder is "[host]", which contains the host name. An example topic for a switching message of the second port would then be:
"de/gudesystems/epc/00:19:32:01:16:41/switch/2".
Executing console commands
The device can be controlled remotely via MQTT using console commands. A list of all commands can be found in the Console chapter. Depending on the topic, the commands are accepted in different formats.
As default the execution of commands is not allowed, but must be enabled in the MQTT configuration! ("Permit CLI commands")
Format 1: Command in JSON Syntax
Publish Topic: "de/gudesystems/epc/00:19:32:01:16:41/cmd"
Publish Message: "{"type": "cli", "cmd": "port 2 state set 1", "id": 10}"
Response from device to "de/gudesystems/epc/00:19:32:01:16:41/cmdres"
"{"type": "cli", "cmdres": ["OK."], "result": {"num": 0, "hint": "ok"}, "id": 10}"
The JSON object "result" returns whether the command was valid. The object "id" in the command is optional and is passed through in the response from the device. The passed number can help to establish a synchronicity between command and response via the broker.
Format 2: Raw Text
Publish Topic: "de/gudesystems/epc/00:19:32:01:16:41/cmd/cli"
Publish Message: "port 2 state set 1".
Response from device to "de/gudesystems/epc/00:19:32:01:16:41/cmdres/cli"
"OK."
Format 3: Simplified port switching
Publish Topic: "de/gudesystems/epc/00:19:32:01:16:41/cmd/port/2"
Publish Message: "0" or "1".
Response from device to "de/gudesystems/epc/00:19:32:01:16:41/cmdres/port/2"
"0" or "1"
This special form exists only for the port switching commands.
Device Data Summary
In the Device Data Summary the most important data of the device are summarized in a JSON object and sent periodically in a configurable time interval. This summary depends on the properties of the device and the connected sensors, and could look like this:
Topic: en/gudesystems/epc/00:19:32:01:16:41/device/telemetry
Message: