MQTT-flex
MQTT is implemented as M2M API protocol, where NETIO device is publisher providing output status and its measurements and subscriber is allowing to control NETIO power outputs via public or internal MQTT brokers.
With MQTT-flex the user can easily define the MQTT topics and payloads by himself via text configuration in JSON object format. Since there is then lot of possibilities with such freestyle flexibility allowed, you can find bellow full set of all implemented attributes and at the end of this article are some examples and links to configurations, which can be used towards public brokers as HiveMQ, IBM Watson, Azure, which you can sometimes directly, sometimes with slight modification (as putting yours Bluemix/Azure credentials) just copy&paste and see data flying between the computers, draw some sexy graphs and have big party with this feature :) ENJOY!
Contents
requirements:
PowerCable family – MQTT flex supported from 2.1.0 firmware release.
MQTT flex JSON config philosophy
Configuration of MQTT in devices supporting MQTT flex is done by Template:JSON (JavaScript Object Notation). The file is separated into 3 sections according to their meaning:
- broker (client connection setup)
- publish (array of topics where to publish)
- subscribe (array of topics where to subscribe)
{
"config":{
"broker":{
config atribute 1 separated by comma... ,
config atribute 2 separated by comma... ,
config atribute 3 separated by comma... ,
... ,
config atribute LAST not separated by comma...
},
"subscribe":[
{
config atribute 1 separated by comma... ,
config atribute 2 separated by comma... ,
config atribute 3 separated by comma... ,
... ,
config atribute LAST not separated by comma...
}
],
"publish":[
{
first publish config atribute 1 separated by comma... ,
first publish config atribute 3 separated by comma... ,
... ,
"events":[
{
first publish events config atribute 1 separated by comma... ,
first publish events config atribute 2 separated by comma... ,
... ,
first publish events config atribute LAST not separated by comma...
}
]
},
{
second publish config atribute 1 separated by comma... ,
second publish config atribute 3 separated by comma... ,
... ,
"events":[
{
second publish events config atribute 1 separated by comma... ,
second publish events config atribute 2 separated by comma... ,
... ,
second publish events config atribute LAST not separated by comma...
}
]
}
]
}
}
Broker section
here you have to define URL or IP address of machine hosting MQTT broker, level of security used for protocol, auth data and optionally some specific MQTT attributes, which are in the spec, but not mandatory required
| Item | Presence | Possible Values | Description | JSON Config Usage |
|---|---|---|---|---|
| url | mandatory | MQTT broker URL | "url":"broker.hivemq.com" | |
| port | mandatory | 1 - 65535 | MQTT broker port | "port":1883 |
| ssl | mandatory | true, false | Use SSL crypted communication selector | "ssl":false |
| type | mandatory | generic | Communication/setup type option | "type":"generic" |
| username | mandatory | regexp+len | Credentials for MQTT broker | "username":"freedom" |
| password | mandatory | regexp+len | Credentials for MQTT broker | "password":"peace|LOVE|empathy4ALL" |
| clientid | optional | regexp+len | MQTT clientid. Max. 32 characters. Variables ${DEVICE_MAC} or ${DEVICE_NAME} can be used | "clientid":"myEcoTable01" |
| keepalive | optional | 1 - 65535? | MQTT keep alive period in seconds | "keepalive":90 |
Subscriber section
| Item | Presence | Possible Values | Description | JSON Config Usage |
|---|---|---|---|---|
| topic | mandatory | see table below | specification of the topic, which MQTT-flex device listens from broker and act accordingly | "topic":"netio/${DEVICE_NAME}/output/1/action" |
| qos | mandatory | 0, 1 or 2 | MQTT's Quality of Sevice - definition {here|http://docs.oasis-open.org/mqtt/mqtt/v3.1.1/errata01/os/mqtt-v3.1.1-errata01-os-complete.html#_Toc442180912} | "qos":0 |
Subscribe topic for control of the output:
• netio/<DEVICE_NAME>/output/1/action with payload for output control : (0 – off, 1 – on, 2 – short off, 3 – short on, 4 – toggle, 5 – no change)
Publish section
when you need to send some data from device towards the broker, you have to specify it in the publish section - you can send measurement data as they are implemented, or you can use translation tables to send some pre-defined strings or even send JSON object. these attributes can be send periodicaly every time the timer reached specified value in seconds or based on value change (something like delta principle, but using only value differrence within defined period)
| Item | Presence | Possible Values | Description | JSON Config Usage |
|---|---|---|---|---|
| topic | mandatory | see table below | definition of the topic, how it is registered towards MQTT broker | "topic":"netio/${DEVICE_NAME}/output/1/load" |
| qos | mandatory | see table below | MQTT's Quality of Sevice - definition {here|http://docs.oasis-open.org/mqtt/mqtt/v3.1.1/errata01/os/mqtt-v3.1.1-errata01-os-complete.html#_Toc442180912} | |
| retain | mandatory | boolean: true or false | MQTT's attribute to specify to broker how to store last received information - section 3.3.1.3 of {MQTT doc|http://docs.oasis-open.org/mqtt/mqtt/v3.1.1/errata01/os/mqtt-v3.1.1-errata01-os-complete.html#_Toc442180841} | "retain":true |
| payload | mandatory | see table below | definition of the topic, how it is registered towards MQTT broker | "topic":"netio/${DEVICE_NAME}/output/1/load", |
| events | mandatory | see table below | definition of events used for triggering sending of data via mqtt (change, delta, timer) |
Basic MQTT flex JSON config example
{
"config":{
"broker":{
"url":"broker.hivemq.com",
"protocol":"mqtt",
"port":1883,
"ssl":false,
"type":"generic",
"username":"freedom",
"password":"peace|LOVE|empathy4ALL"
},
"subscribe":[{
"topic":"netio/${DEVICE_NAME}/output/1/action",
"qos":0,
"target":"OUTPUTS/1/ACTION",
"action":"${payload}"
}
],
"publish":[
{
"topic":"netio/${DEVICE_NAME}/output/1/state",
"qos":0,
"retain":true,
"payload":"${OUTPUTS/1/STATE}",
"events":[
{
"type":"change",
"source":"OUTPUTS/1/STATE"
}
]
},
{
"topic":"netio/${DEVICE_NAME}/output/1/load",
"qos":0,
"retain":false,
"payload":"${OUTPUTS/1/LOAD}",
"events":[
{
"type":"timer",
"period":1111
},
{
"type":"delta",
"source":"OUTPUTS/1/LOAD",
"delta":1
}
]
}
]
}
}
Publish topics for monitoring of the output state and load:
• netio/<DEVICE_NAME>/output/1/state with payload providing output 1 state value - published when the output state change • netio/<DEVICE_NAME>/output/1/load with payload providing actual load of output 1 – published every 1111 seconds or when load change by 1W
possible source:
OUTPUTS/X/VOLTAGE" [V] OUTPUTS/X/CURRENT" [mA] OUTPUTS/X/POWER_FACTOR [1] OUTPUTS/X/LOAD mW OUTPUTS/X/STATE [1] OUTPUTS/X/ACTION OUTPUTS/X/DELAY unsigned int [ms] OUTPUTS/X/NAME [string] OUTPUTS/X/FREQUENCY [Hz] two decimals OUTPUTS/X/ENERGY [Wh] OUTPUTS/X/ENERGY_START [epoch] OUTPUTS/X/ENERGY_START_FMT [YYYY-MM-DD]
TOTALs - for future use with devices having more than 1 measured output OUTPUTS/TOTAL/ENERGY OUTPUTS/TOTAL/LOAD OUTPUTS/TOTAL/CURRENT OUTPUTS/TOTAL/VOLTAGE OUTPUTS/TOTAL/POWER_FACTOR OUTPUTS/TOTAL/FREQUENCY
available variables for definitions in MQTT-flex:
DEVICE_NAME DEVICE_MAC BRAND_NAME BRAND_TYPE
