Add MQTT mapping draft and pub topic

Author: martinjaeger

docs/.vuepress/config.js

@@ -60,7 +60,8 @@ module.exports = {
                 collapsable: false,
                 children: [
                     '4a_http',
-                    '4b_coap'
+                    '4b_coap',
+                    '4c_mqtt'
                 ]
             }],
             '/v0.2/': [{

docs/2a_general.md

@@ -55,10 +55,10 @@ For explanation of the protocol, the following simplified data structure of an M
     "info": {
         "DeviceType": "MPPT 1210 HUS",
     },
-    "conf": {
+    "conf": {                                       // data stored in NVM
         "BatCharging_V": 14.4,
     },
-    "input": {
+    "input": {                                      // data stored in RAM
         "EnableCharging": true
     },
     "output": {
@@ -70,19 +70,33 @@ For explanation of the protocol, the following simplified data structure of an M
         "BatChgDay_Wh": 1984,
     },
     "exec": {
-        "reset": null,
+        "reset": null,                              // void function
     },
-    "auth": ["Password"],
-    "pub": {
+    "auth": ["Password"],                           // function with 1 parameter
+    "pub": {                                        // publication channels
         "serial": {
             "Enable": true,
             "Interval": 1.0,
-            "IDs": ["Bat_V", "Bat_A"]
+            "Topic": "",                            // default: empty topic
+            "IDs": ["Bat_V", "Bat_A"]               // array of node names
         },
         "can": {
             "Enable": false,
             "Interval": 0.1,
+            "Topic": 12345,                         // e.g. CAN ID
             "IDs": ["Bat_V"]
+        },
+        "mqtt": {
+            "Enable": true,
+            "Interval": 3600,
+            "Topic": "chargers/device-id/pub",
+            "IDs": ["Bat_V", "Bat_A"]
+        }
+    },
+    "sub": {                                        // subscription channels
+        "mqtt": {                                   // may have callback attached
+            "Topic": "chargers/device-id/sub",
+            "IDs": ["EnableCharging"]
         }
     }
 }

docs/2b_text_mode.md

@@ -48,7 +48,10 @@ The bytes after the dot contain the requested data.
 
 The publication message is very simple and consists of a hash sign and a whitespace at the beginning, followed by a map of data node name/value pairs.
 
-    txt-pubmsg = "# " json-map                      ; publication message
+    txt-pubmsg = "#" [ topic ] " " json-map         ; publication message
+
+    topic = path                                    ; same format as path, used to
+                                                    ; distinguish pub msg origins
 
 ## Read data
 
@@ -154,4 +157,6 @@ With this setting, the following message is automatically sent by the device onc
 
 Publication messages are broadcast to all connected devices. No response is sent from devices receiving the message.
 
-The data nodes to be published in each message can be configured using POST and DELETE requests to the pub/serial/IDs endpoint, as shown in the examples above.
+A publication message can have a dedicated topic which is chosen depending on the application. With CAN as a lower layer it could be the device ID of the sender so that the application can select the device of highest priority if multiple devices publish the same data node.
+
+The data nodes to be published in each channel can be configured using POST and DELETE requests to the pub/serial/IDs endpoint, as shown in the examples above.

docs/2c_binary_mode.md

@@ -19,7 +19,7 @@ Each request message consists of a first byte as the request method identifier,
 
     bin-fetch  = %x05 endpoint cbor-array     ; returns only values, no keys
 
-    bin-ipatch = %x07 endpoint cbor-map       ; map containing
+    bin-ipatch = %x07 endpoint cbor-map
 
     bin-nameid = %x1E endpoint cbor-array     ; get names of ids or vice versa
 
@@ -41,7 +41,9 @@ Responses in binary mode start with the error/status code as specified before, f
 
 Binary publication messages follow the same concept as in text mode.
 
-    bin-pubmsg = %x1F cbor-map                ; map containing node IDs and values
+    bin-pubmsg = %x1F bin-topic cbor-map      ; map containing node IDs and values
+
+    bin-topic = cbor-string                   ; empty string 0x60 if not specified
 
 ## Name and ID mapping
 

docs/4c_mqtt.md

@@ -0,0 +1,23 @@
+---
+title: "MQTT"
+---
+
+# ThingSet to MQTT mapping
+
+The MQTT protocol doesn't support the request/response part of the ThingSet protocol, but the publish/subscribe messaging pattern can be easily mapped.
+
+## Publication
+
+The topic used to publish to the MQTT server may contain the path of the data nodes.
+
+It is possible to publish a single measurement value to a single topic or publish multiple child nodes of a path to the same MQTT topic. The selected approach depends on the application. For the ThingSet protocol less configuration nodes are needed if multiple data nodes are gathered under one MQTT topic.
+
+It is recommended that only the JSON or CBOR payload data is stored in the MQTT payload and the path of the ThingSet endpoint is contained in the topic.
+
+## Subscription
+
+Content fetched from a specific topic is forwarded to the ThingSet protocol as a publication message (containing the topic or parts of it). If the ThingSet device has the subscription to the specified topic enabled, it will parse the incoming data similar to a PATCH request. Unknown data nodes contained in the subscribed payload are silently ignored.
+
+If the application requires some processing of incoming data before applying them to actual nodes, temporary data nodes can be created where the subscribed content is written to. Afterwards a function is called (assigned as a callback to the sub channel node) to process the incoming data and pass it on to the actual nodes.
+
+This approach can also be used to determine if the received data has changed compared to already existing state and avoid too many storage operations in EEPROM for regularly published messages.