Difference between revisions of "MQTT-flex"
Line 274: | Line 274: | ||
=== OUTPUTS variables === | === OUTPUTS variables === | ||
==== List ==== | ==== List ==== | ||
− | + | ===== VOLTAGE [V] ===== | |
− | + | ===== CURRENT [mA] ===== | |
− | + | ===== POWER_FACTOR ===== | |
− | + | ===== LOAD mW ===== | |
− | + | ===== STATE ===== | |
− | + | ===== ACTION ===== | |
− | + | ===== DELAY [ms] ===== | |
− | + | ===== NAME ===== | |
− | + | ===== FREQUENCY [Hz] ===== | |
− | + | ===== ENERGY [Wh] ===== | |
− | + | ===== ENERGY_START ===== | |
− | + | ===== ENERGY_START_FMT ===== | |
==== Examples ==== | ==== Examples ==== | ||
"payload":"${OUTPUTS/1/STATE}" | "payload":"${OUTPUTS/1/STATE}" | ||
Line 308: | Line 308: | ||
== Payload/topic variables == | == Payload/topic variables == | ||
=== List === | === List === | ||
− | + | ===== DEVICE_NAME ===== | |
− | + | ===== MAC ===== | |
− | + | ===== BRAND_NAME ===== | |
− | + | ===== BRAND_TYPE ===== | |
− | + | ===== UPTIME ===== | |
− | + | ===== PAYLOAD ===== | |
− | + | ===== OUTPUT_ID ===== | |
− | + | ===== WIFI_SIGNAL<sup>Not yet implemented</sup> ===== | |
=== Examples === | === Examples === | ||
"payload":"${PAYLOAD}" | "payload":"${PAYLOAD}" |
Revision as of 17:07, 16 August 2019
There is a lot of approaches in integration of MQTT in devices and systems. One vendor prefer one topic with structured data payload, the another one prefer tree topic structure with simple value in data payload. MQTT-flex is a standard MQTT with specific configuration approach. The goal of MQTT-flex is to give a user opportunity to integrate NETIO device with any system with different data approach.
Configuration of MQTT in devices supporting MQTT flex is done by JSON (JavaScript Object Notation). With MQTT-flex you can easily define the MQTT topics, payloads and device behaviour 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.
Supported devices:
PowerCable MQTT, PowerCable OEM (DevKit), PowerPDU 4PS, PowerDIN 4PZ, PowerBox 3Px
Contents
- 1 Simple MQTT-flex configuration example
- 2 Config sections
- 3 Target / Source
- 4 Commands
- 5 Variables
- 6 Extended MQTT flex JSON config example
- 7 MQTT flex JSON config philosophy
Simple MQTT-flex configuration 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":"timer", "period":"1000" } ] } ] } }
Client Configuration (broker section)
This configuration example set NETIO device to connect to broker.hivemq.com with mqtt protocol, no ssl connection with credetials freedom/peace|love|empathy4ALL.
Device Control (subscribe section)
Device output 1 is controlled with action received by subscription to netio/${DEVICE_NAME}/output/1/action topic with QOS 0
Output State monitoring (publish section)
Device send every 1000 ms message to topic with QOS 0, retain true information with output 1 state
Config sections
Broker
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
Attributes table overview
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 |
Attributes list
url
port
ssl
type
username
password
clientid
keepalive
Subscribe
Hints to usage
When receive message in topic do action on target.
actiondef: When message in topic match actiondef payload do action on target.
Attributes table overview
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 |
target | mandatory | internal definition of action, which can be performed above the specified output | "target":"OUTPUTS/1/ACTION" | |
action | mandatory | a payload or a value the action attribute needs to have passed to | "action":"${payload}" |
Attributes list
topic
qos
target
action
actiondefNot supported yet
jsonNot supported yet
Subscribe topic payload values specification 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
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)
Hints to usage
When event send message with payload to topic.
Attributes table overview
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) |
Attributes list
topic
qos
retain
payload
events
type
source
delta
period
payloaddefNot supported yet
Target / Source
In MQTT-flex we use targets and sources specify where to apply some change or get value. Practically it means addressing of INPUTS/OUTPUTS and adding command or variable.
- source - specifies from where the value will be read (specifies the source of data for payload, change detection, delta calculation)
- target - specifies where the data should be sent or command applied (e.g. specifies the target for ACTION)
INPUT / OUTPUT (Target) selection
NETIO Devices can have inputs and outputs which can be different type. When you want to work with some variable you have to specify on which I/O. For doing that in MQTT-flex is implemented structured addressing with "/" separator. See the steps below how to compose source or target.
- At first specify if requested variable is from/for INPUT or OUTPUT using keywords "OUTPUTS" or "INPUTS" .
- Add "/" separator
- Specify the number of INPUT/OUTPUT to 1(or TOTAL for summary statistics if available)
- Add "/" separator
- Specify requested variable or command
Note: Not all of OUTPUTS/INPUTS support all variables. Available variables are closely connected with the device functions and I/O features.
Note2: INPUTS not yet implemented
Examples:
adressing controll of output 3
OUTPUTS/3/ACTION
getting voltage on output 1
OUTPUTS/1/VOLTAGE
Commands
Variables
In some parameters is nescessary to use variables to get current state and measurements. Variables are separated in two categories:
- Target/Source variables
- Payload Topic variables
Target Source Variables
The list of available variables for each
OUTPUTS variables
List
VOLTAGE [V]
CURRENT [mA]
POWER_FACTOR
LOAD mW
STATE
ACTION
DELAY [ms]
NAME
FREQUENCY [Hz]
ENERGY [Wh]
ENERGY_START
ENERGY_START_FMT
Examples
"payload":"${OUTPUTS/1/STATE}"
"target":"OUTPUTS/1/ACTION"
"source":"${OUTPUTS/1/ENERGY}"
INPUT variables
Not yet implemented
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
Payload/topic variables
List
DEVICE_NAME
MAC
BRAND_NAME
BRAND_TYPE
UPTIME
PAYLOAD
OUTPUT_ID
WIFI_SIGNALNot yet implemented
Examples
"payload":"${PAYLOAD}"
"topic":"netio/${DEVICE_NAME}/output/1/action"
Extended 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 } ] } ] } }
MQTT flex JSON config philosophy
- 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... } ] } ] } }