Difference between revisions of "MQTT-flex"

From wiki.netio-products.com
Jump to navigation Jump to search
Line 7: Line 7:
 
PowerCable MQTT, PowerCable OEM (DevKit), PowerPDU 4PS, PowerDIN 4PZ, PowerBox 3Px  
 
PowerCable MQTT, PowerCable OEM (DevKit), PowerPDU 4PS, PowerDIN 4PZ, PowerBox 3Px  
  
=== Simple MQTT-flex configuration example ===
+
= Simple MQTT-flex configuration example =
 
 
==== Client Configuration (broker section) ====
 
This configuration example set NETIO device to connect to <b>broker.hivemq.com</b> with <b>mqtt</b> protocol, <b>no ssl</b> connection with credetials <b>freedom/peace|love|empathy4ALL</b>.
 
 
 
==== Device Control (subscribe section) ====
 
Device <b>output 1</b> is controlled with <b>action</b> received by subscription to <b>netio/${DEVICE_NAME}/output/1/action</b> topic with <b>QOS 0</b>
 
 
 
==== Output State monitoring (publish section) ====
 
Device send every <b>1000 ms</b> message to topic <b></b> with <b>QOS 0</b>, <b>retain true</b> information with <b>output 1 state</b>
 
 
 
 
  {
 
  {
 
       "config":{
 
       "config":{
Line 51: Line 41:
 
     }
 
     }
 
  }
 
  }
 +
== Client Configuration (broker section) ==
 +
This configuration example set NETIO device to connect to <b>broker.hivemq.com</b> with <b>mqtt</b> protocol, <b>no ssl</b> connection with credetials <b>freedom/peace|love|empathy4ALL</b>.
 +
 +
== Device Control (subscribe section) ==
 +
Device <b>output 1</b> is controlled with <b>action</b> received by subscription to <b>netio/${DEVICE_NAME}/output/1/action</b> topic with <b>QOS 0</b>
  
=== Config sections ===
+
== Output State monitoring (publish section) ==
 +
Device send every <b>1000 ms</b> message to topic <b></b> with <b>QOS 0</b>, <b>retain true</b> information with <b>output 1 state</b>
  
==== Broker ====
+
 
 +
 
 +
= 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
 
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
 
<br />
 
<br />
 
+
=== Attributes table overview ===
 
{| class="wikitable"
 
{| class="wikitable"
 
! style="font-weight:bold; background-color:#9b9b9b;" | Item
 
! style="font-weight:bold; background-color:#9b9b9b;" | Item
Line 113: Line 113:
 
| style="background-color:#efefef;" | "keepalive":90
 
| style="background-color:#efefef;" | "keepalive":90
 
|}
 
|}
 +
=== Attributes list ===
 +
====  ====
  
 
+
== Subscribe ==
 
+
=== Attributes table overview ===
==== Subscribe ====
 
 
 
 
{| class="wikitable"
 
{| class="wikitable"
 
! style="font-weight:bold; background-color:#9b9b9b;" | Item
 
! style="font-weight:bold; background-color:#9b9b9b;" | Item
Line 156: Line 156:
  
  
==== Publish ====
+
== 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)
 
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)
  
 +
=== Attributes table overview ===
 
{| class="wikitable"
 
{| class="wikitable"
 
! style="font-weight:bold; background-color:#9b9b9b;" | Item
 
! style="font-weight:bold; background-color:#9b9b9b;" | Item
Line 207: Line 208:
  
  
=== Parameters ===
+
= Parameters =
 
* source
 
* source
 
* target
 
* target
Line 218: Line 219:
 
* actiondef
 
* actiondef
  
=== Target / Source ===
+
= 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.
 
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.
  
Line 224: Line 225:
 
* <b>target</b> - specifies where the data should be sent or command applied (e.g. specifies the target for ACTION)
 
* <b>target</b> - specifies where the data should be sent or command applied (e.g. specifies the target for ACTION)
  
==== INPUT / OUTPUT (Target) selection ====
+
== 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 <b>"/"</b> separator. See the steps below how to compose source or target.
 
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 <b>"/"</b> separator. See the steps below how to compose source or target.
Line 238: Line 239:
 
<b>Note2:</b> INPUTS not yet implemented
 
<b>Note2:</b> INPUTS not yet implemented
  
==== Examples: ====
+
== Examples: ==
  
 
adressing controll of output 3
 
adressing controll of output 3
Line 245: Line 246:
 
  OUTPUTS/1/VOLTAGE
 
  OUTPUTS/1/VOLTAGE
  
=== Commands ===
+
= Commands =
 
   
 
   
=== Variables ===
+
= Variables =
 
In some parameters is nescessary to use variables to get current state and measurements. <b>Variables are separated in  two categories:</b>
 
In some parameters is nescessary to use variables to get current state and measurements. <b>Variables are separated in  two categories:</b>
  
Line 253: Line 254:
 
* System variables
 
* System variables
  
==== Target Source Variables ====
+
== Target Source Variables ==
  
 
The list of available variables for each  
 
The list of available variables for each  
Line 259: Line 260:
  
  
===== OUTPUTS variables =====
+
=== OUTPUTS variables ===
  
 
* OUTPUTS/X/VOLTAGE" [V]
 
* OUTPUTS/X/VOLTAGE" [V]
Line 274: Line 275:
 
* OUTPUTS/X/ENERGY_START_FMT [YYYY-MM-DD]
 
* OUTPUTS/X/ENERGY_START_FMT [YYYY-MM-DD]
  
===== INPUT variables =====
+
=== INPUT variables ===
 
Not yet implemented
 
Not yet implemented
  
===== TOTALs - for future use with devices having more than 1 measured output=====
+
=== TOTALs - for future use with devices having more than 1 measured output ===
  
 
* OUTPUTS/TOTAL/ENERGY
 
* OUTPUTS/TOTAL/ENERGY
Line 285: Line 286:
 
* OUTPUTS/TOTAL/POWER_FACTOR
 
* OUTPUTS/TOTAL/POWER_FACTOR
 
* OUTPUTS/TOTAL/FREQUENCY
 
* OUTPUTS/TOTAL/FREQUENCY
==== System variables ====
+
== System variables ==
  
 
* DEVICE_NAME
 
* DEVICE_NAME
Line 293: Line 294:
  
  
=== Basic MQTT flex JSON config example ===
+
= Basic MQTT flex JSON config example =
  
 
  <nowiki> </nowiki>  {
 
  <nowiki> </nowiki>  {
Line 348: Line 349:
  
  
=== MQTT flex JSON config philosophy ===
+
= MQTT flex JSON config philosophy =
  
 
Configuration of MQTT in devices supporting <i>MQTT flex</i> is done by {{JSON (JavaScript Object Notation)|https://en.wikipedia.org/wiki/JSON}}. The file is separated into <b>3 sections according to their meaning</b>:
 
Configuration of MQTT in devices supporting <i>MQTT flex</i> is done by {{JSON (JavaScript Object Notation)|https://en.wikipedia.org/wiki/JSON}}. The file is separated into <b>3 sections according to their meaning</b>:

Revision as of 16:21, 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 oportunity to integrate NETIO device with any system with different data approach.

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

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

Subscribe

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}"


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)

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)






Parameters

  • source
  • target
  • payload
  • event
  • delta
  • timer
  • type
  • period
  • actiondef

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.

  1. At first specify if requested variable is from/for INPUT or OUTPUT using keywords "OUTPUTS" or "INPUTS" .
  2. Add "/" separator
  3. Specify the number of INPUT/OUTPUT to 1(or TOTAL for summary statistics if available)
  4. Add "/" separator
  5. 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
  • System variables

Target Source Variables

The list of available variables for each


OUTPUTS variables

  • 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]

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

System variables

  • DEVICE_NAME
  • DEVICE_MAC
  • BRAND_NAME
  • BRAND_TYPE


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
                     }      
                 ]
             }
         ]
     }
 }


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...
                      }
                  ]
              }
          ]
  }
}