Skip to content

Commit 66f03a5

Browse files
committed
Add MQTT mapping draft and pub topic
1 parent 950dc66 commit 66f03a5

File tree

5 files changed

+56
-11
lines changed

5 files changed

+56
-11
lines changed

docs/.vuepress/config.js

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -60,7 +60,8 @@ module.exports = {
6060
collapsable: false,
6161
children: [
6262
'4a_http',
63-
'4b_coap'
63+
'4b_coap',
64+
'4c_mqtt'
6465
]
6566
}],
6667
'/v0.2/': [{

docs/2a_general.md

Lines changed: 20 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -55,10 +55,10 @@ For explanation of the protocol, the following simplified data structure of an M
5555
"info": {
5656
"DeviceType": "MPPT 1210 HUS",
5757
},
58-
"conf": {
58+
"conf": { // data stored in NVM
5959
"BatCharging_V": 14.4,
6060
},
61-
"input": {
61+
"input": { // data stored in RAM
6262
"EnableCharging": true
6363
},
6464
"output": {
@@ -70,19 +70,33 @@ For explanation of the protocol, the following simplified data structure of an M
7070
"BatChgDay_Wh": 1984,
7171
},
7272
"exec": {
73-
"reset": null,
73+
"reset": null, // void function
7474
},
75-
"auth": ["Password"],
76-
"pub": {
75+
"auth": ["Password"], // function with 1 parameter
76+
"pub": { // publication channels
7777
"serial": {
7878
"Enable": true,
7979
"Interval": 1.0,
80-
"IDs": ["Bat_V", "Bat_A"]
80+
"Topic": "", // default: empty topic
81+
"IDs": ["Bat_V", "Bat_A"] // array of node names
8182
},
8283
"can": {
8384
"Enable": false,
8485
"Interval": 0.1,
86+
"Topic": 12345, // e.g. CAN ID
8587
"IDs": ["Bat_V"]
88+
},
89+
"mqtt": {
90+
"Enable": true,
91+
"Interval": 3600,
92+
"Topic": "chargers/device-id/pub",
93+
"IDs": ["Bat_V", "Bat_A"]
94+
}
95+
},
96+
"sub": { // subscription channels
97+
"mqtt": { // may have callback attached
98+
"Topic": "chargers/device-id/sub",
99+
"IDs": ["EnableCharging"]
86100
}
87101
}
88102
}

docs/2b_text_mode.md

Lines changed: 7 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -48,7 +48,10 @@ The bytes after the dot contain the requested data.
4848

4949
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.
5050

51-
txt-pubmsg = "# " json-map ; publication message
51+
txt-pubmsg = "#" [ topic ] " " json-map ; publication message
52+
53+
topic = path ; same format as path, used to
54+
; distinguish pub msg origins
5255

5356
## Read data
5457

@@ -154,4 +157,6 @@ With this setting, the following message is automatically sent by the device onc
154157

155158
Publication messages are broadcast to all connected devices. No response is sent from devices receiving the message.
156159

157-
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.
160+
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.
161+
162+
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

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,7 @@ Each request message consists of a first byte as the request method identifier,
1919

2020
bin-fetch = %x05 endpoint cbor-array ; returns only values, no keys
2121

22-
bin-ipatch = %x07 endpoint cbor-map ; map containing
22+
bin-ipatch = %x07 endpoint cbor-map
2323

2424
bin-nameid = %x1E endpoint cbor-array ; get names of ids or vice versa
2525

@@ -41,7 +41,9 @@ Responses in binary mode start with the error/status code as specified before, f
4141

4242
Binary publication messages follow the same concept as in text mode.
4343

44-
bin-pubmsg = %x1F cbor-map ; map containing node IDs and values
44+
bin-pubmsg = %x1F bin-topic cbor-map ; map containing node IDs and values
45+
46+
bin-topic = cbor-string ; empty string 0x60 if not specified
4547

4648
## Name and ID mapping
4749

docs/4c_mqtt.md

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
---
2+
title: "MQTT"
3+
---
4+
5+
# ThingSet to MQTT mapping
6+
7+
The MQTT protocol doesn't support the request/response part of the ThingSet protocol, but the publish/subscribe messaging pattern can be easily mapped.
8+
9+
## Publication
10+
11+
The topic used to publish to the MQTT server may contain the path of the data nodes.
12+
13+
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.
14+
15+
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.
16+
17+
## Subscription
18+
19+
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.
20+
21+
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.
22+
23+
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.

0 commit comments

Comments
 (0)