wiki.netio-products.com - User contributions [en]

Rules Complete Examples

2023-11-29T21:35:07Z

Bbakala: /* 3. Create RULE for output ON */

The concept of NETIO Conditions (PAB & WatchDog) & Rules is a set of prepared detections (Conditions) and Rules that act upon them. They are implemented directly in NETIO PDU devices.

== CR01 - WatchDog (ping) to 1 IP address | default in FW 3.2.3 ==
The WatchDog functionality is used to monitor connectivity to specified IP address (or URL) by sending PING request to it.

The ping in this example is sent every 60s and waits 5s for the device to respond. If the ping fails, Watchdog returns <code>false</code> and restarts (ACTION: 2 = SHORT OFF) device connected to first output. After restart, it waits 120 seconds and starts monitoring again. If the device does not respond, WatchDog remains in ERROR state until next successful ping.

===WatchDog definition===

WatchDog name: '''CR01_WDT'''

<nowiki>
{
"target": "192.168.1.5",
"pingInterval": 60,
"timeout": 5,
"maxTimeouts": 0,
"timeToReboot": 120,
"maxRestarts": -1
}</nowiki>

===Rule definition===

Rule name: '''CR01_RULE'''

<nowiki>
{
"conditions": {
"WDT/CR01_WDT/FAIL": true
},
"actions": {
"OUTPUTS/1/ACTION": 2
}
}</nowiki>

== CR02 - Digital Inputs (Push button to Toggle Outputs 1 and 2) | default in FW 3.2.3 ==

Rule is used for managing outputs in response to change of Digital Inputs (DI) state. Rule monitors state of first DI. When DI switches from OFF (0) to ON (1), Rule switches (toggles) Outputs 1 & 2 to their opposite states (ACTION 4 = TOGGLE).

===Rule definition===

Rule name: '''CR02_RULE'''

<nowiki>
{
"conditions": {
"INPUTS/1/STATE": "on"
},
"actions": {
"OUTPUTS/1/ACTION": 4,
"OUTPUTS/2/ACTION": 4
}
}</nowiki>

== CR03 - Load Watchdog (Restart device if it's more than 2 minutes in IDLE mode) | default in FW 3.2.3 ==
Rule monitors load (Watts) on Output 1. If the load is between 1-20W for at least 2 minutes, it restarts (ACTION 2 = SHORT OFF) the output.
Example uses PAB (Power Analysis Block) functionality to determine if measured value (load in our case) lies in given range for a period of time. When it does, defined Rule triggers device restart.

===PAB definition===

PAB name: '''CR03_PAB'''
<nowiki>
{
"type": "RANGE",
"source": "OUTPUTS/1/LOAD",
"lowerBound": 1,
"upperBound": 20,
"timeHysteresis": 120
}</nowiki>

===Rule definition===

Rule name: '''CR03_RULE'''

<nowiki>
{
"conditions": {
"PAB/CR03_PAB/IN": true
},
"actions": {
"OUTPUTS/1/ACTION": 2
}
}</nowiki>

== CR04 - Load Watchdog with alarm to Cloud ==
Rule monitors load (Watts) on Output 1. If the load is between 1-20W for at least 30 minutes, it restarts (ACTION 2 = SHORT OFF) the output. In addition, it triggers an alarm in NETIO Cloud, which sends a notification to specified email address.
This example needs a NETIO Cloud account with Premium version active for first output. There also has to be email notification enabled for the output.

Example uses PAB (Power Analysis Block) functionality to determine if measured value (load in our case) lies in given range for a period of time. When it does, defined Rule triggers device restart and sends alarm to Cloud.

===PAB definition===

PAB name: '''CR04_PAB'''

<nowiki>
{
"type": "RANGE",
"source": "OUTPUTS/1/LOAD",
"lowerBound": 1,
"upperBound": 20,
"timeHysteresis": 1800
}</nowiki>

===Rule definition===

Rule name: '''CR04_RULE'''

<nowiki>
{
"conditions": {
"PAB/CR04_PAB/IN": true
},
"actions": {
"OUTPUTS/1/ACTION": 2,
"CLOUD/OUTPUT/1/ALARM": "${COND_RESULT}"
}
}</nowiki>

== CR05 - Load Watchdog with zones (indicate OFF / IDLE / RUN mode by switched on output)==
Rule monitors load (Watts) on Output 1. Measured load is then classified to several zones defined with thresholds (limit values). Depending on the zone in which the measured load is currently located, different actions can be triggered. Load value has to be between defined threshold for at least 10seconds in order to be placed to respective zone.
Example is composed of one PAB that classifies the zones and three Rules for 3 separate actions. Actions do the following:
* Output 1 load lower than 1W: Output 2 = ON
* Output 1 load between 1-20W: Output 3 = ON
* Output 1 load between 20-200W: Output 4 = ON

===PAB definition===

PAB name: '''CR05_PAB'''

<nowiki>
{
"type": "ZONES",
"source": "OUTPUTS/2/CURRENT",
"thresholds": [
1,
20,
200
],
"timeHysteresis": 10
}</nowiki>

===Rules definitions===

Rule 1 name: '''CR05_RULE_1'''

<nowiki>
{
"conditions": {
"PAB/NR05_PAB/ZONE": 0
},
"actions": {
"OUTPUTS/2/ACTION": 1,
"OUTPUTS/3/ACTION": 0,
"OUTPUTS/4/ACTION": 0
}
}</nowiki>

Rule 2 name: '''CR05_RULE_2'''

<nowiki>
{
"conditions": {
"PAB/CR05_PAB/ZONE": 1
},
"actions": {
"OUTPUTS/2/ACTION": 0,
"OUTPUTS/3/ACTION": 1,
"OUTPUTS/4/ACTION": 0
}
}</nowiki>

Rule 3 name: '''CR05_RULE_3'''

<nowiki>
{
"conditions": {
"PAB/CR05_PAB/ZONE": 2
},
"actions": {
"OUTPUTS/2/ACTION": 0,
"OUTPUTS/3/ACTION": 0,
"OUTPUTS/4/ACTION": 1
}
}</nowiki>

== CR06 - WatchDog for 2 IPs (Verify IP connectivity outage with 2 IPs)==
The WatchDog functionality is used to monitor connectivity to specified IP address (or URL) by sending PING request to it.

In this example, we monitor two IPs and we want to restart device connected to Output 1 if none of the addresses reply.
The ping for both IPs is sent every 30s and waits 5s for device to respond. There are 5 consecutive timeouts tolerated before the ping is considered as failed. When the ping fails, Watchdog returns <code>false</code> and remains in ERROR state.

In case both of the defined WatchDogs are in ERROR state, the Rule is triggered which then restarts Output 1.

===WatchDogs definition===

WatchDog name: '''CR06_WDT_1'''

<nowiki>
{
"target": "192.168.1.51",
"pingInterval": 30,
"timeout": 5,
"maxTimeouts": 5,
"timeToReboot": 120,
"maxRestarts": -1
}</nowiki>

WatchDog name: '''CR06_WDT_2'''

<nowiki>
{
"target": "192.168.1.52",
"pingInterval": 60,
"timeout": 5,
"maxTimeouts": 5,
"timeToReboot": 120,
"maxRestarts": -1
}</nowiki>

===Rule definition===

Rule name: '''CR06_RULE'''

<nowiki>
{
"conditions": {
"operator": "AND",
"WDT/CR06_WDT_1/FAIL": true,
"WDT/CR06_WDT_2/FAIL": true
},
"actions": {
"OUTPUTS/1/ACTION": 2
}
}</nowiki>

== CR07 - Synchronized outputs states during working hours ==
Rule keeps track of first output state and when it changes, it switches output 2 to the same state. However, we want this synchronization only to work during working hours. We define the time with Schedule functionality and use it as a filter (mask) in Rules. Schedule can be defined manually or imported as a configuration file.

===Schedule definition===

Schedule name: '''CR07_SCHEDULE'''

[[File:NR07_Schedule.png|NR070 Schedule]]

===Rule definition===

Rule name: '''CR07_RULE'''

<nowiki>
{
"conditions": {
"OUTPUTS/1/STATE": "on"
},
"filters": {
"SCHEDULE/CR07_SCHEDULE/ACTIVE": true
},
"actions": {
"OUTPUTS/2/ACTION": "${COND_RESULT}"
}
}</nowiki>

== CR08 - Load Watchdog -> Turn output ON after period of time ==

In this example we want to measure load on output 1 and indicate when the power is abnormally low for a period of time by switching device on Output 2 ON (could be control light, sound alarm etc.).

In PAB we define indication for low power usage (1-20W) that is measured for period of 30 minutes (1800 seconds).
In Rule we define switching Output 2 = ON (ACTION 1 = TURN ON) based on fulfilled PAB condition. This set up counts with human interaction after the Rule action gets processed. (e.g. restarting/replacing device on Output 1 and turning Output 2 OFF).
It is possible to alter this behavior in such a way that the control light (Output 2) turns automatically OFF when load on Output 1 returns to standard values, i.e. higher than 20W (device gets repaired/replaced) or drops to 0W (device was removed or Output 1 turned OFF). This setup is defined in Rule '''NR08_ALT'''

===PAB definition===

PAB name: '''CR08_PAB'''
<nowiki>
{
"type": "RANGE",
"source": "OUTPUTS/1/LOAD",
"lowerBound": 1,
"upperBound": 20,
"timeHysteresis": 1800
}</nowiki>

===Rule definition===

Rule name: '''CR08_RULE'''

<nowiki>
{
"conditions": {
"PAB/CR08_PAB/IN": true
},
"actions": {
"OUTPUTS/2/ACTION": 1
}
}</nowiki>

Rule name: '''CR08_RULE_ALT'''

<nowiki>
{
"conditions": {
"PAB/CR08_PAB/IN": true
},
"actions": {
"OUTPUTS/2/ACTION": "${COND_RESULT}"
}
}</nowiki>

== CR09 - Digital Inputs with Schedule ==

Examples shows usage when we want to detect switching of Digital Input to ON state (1) but to (not) react only during specified hours (e.g. outside of working hours).
Reaction hours are defined with Schedule functionality. Schedule can be defined manually or imported as a configuration file.

===Schedule definition===

Schedule name: '''CR09_SCHEDULE'''

===Rule definition===

Rule name: '''CR09_RULE'''

<nowiki>
{
"conditions": {
"INPUTS/1/STATE": "on"
},
"filters": {
"SCHEDULE/CR09_SCHEDULE/ACTIVE": false
},
"actions": {
"OUTPUTS/1/ACTION": 2
}
}</nowiki>

== CR10 - TURN OFF Output 1 before midnight ==
Rule in a combination with Schedule can be used to ensure a specified output will be turned off at the end of the day (or any other time).
Schedule in this application is '''NOT''' assigned to the output and acts only as a "trigger" for launching the Rule action.

===Schedule definition===

Schedule name: '''off_before_midnight'''

Schedule configuration: Schedule is configured to have '''intervals every day from 23:59 to 24:00'''. In this configuration, the output turns of at 23:59.

[[File:cr10_schedule.png|CR10 Schedule]]

===Rule definition===

Rule name: '''CR10_RULE'''
<nowiki>
{
"conditions": {
"SCHEDULE/off_before_midnight/ACTIVE": true
},
"filters": {
"OUTPUTS/1/STATE": "on"
},
"actions": {
"OUTPUTS/1/ACTION": 0
}
}</nowiki>

== CR11 - Total load (8QS)==
CR11_PAB

<nowiki>
{
"type": "RANGE",
"source": "OUTPUTS/TOTAL/LOAD",
"lowerBound": 30,
"upperBound": 100,
"timeHysteresis": 3
}</nowiki>

<nowiki>
{
"conditions": {
"operator": "OR",
"PAB/total_outputs/IN": true
},
"actions": {
"OUTPUTS/1/ACTION": 4,
"CLOUD/OUTPUT/1/ALARM": 1
}
}</nowiki>

== CR12 - Negative load ==
CR12_PAB

<nowiki>
{
"type": "RANGE",
"source": "OUTPUTS/1/LOAD",
"lowerBound": -400,
"upperBound": 0,
"timeHysteresis": 2
}</nowiki>

<nowiki>
{
"conditions": {
"PAB/negative/IN": true
},
"actions": {
"OUTPUTS/3/ACTION": 4,
"OUTPUTS/4/ACTION": 4
}
}</nowiki>

== CR13 - Actions based on daylight <code>FW 4.0.0+</code>==
Turns output ON/OFF based on sunrise/sunset times of set location.
In this example, output 1 gets turned on one hour before (-60 minutes) sunrise and turns off one hour (60 minutes) after sunset. Location is se for NETIO Products headquarters (U pily 103, Prague, CZ). Elevation is set as 247 meters, above sea level.

=== PAB definition ===
PAB name: '''CR13_PAB'''

<nowiki>
{
"type": "DAYLIGHT",
"longitude": "14.4129433E",
"latitude": "50.0058144N",
"altitude": 247,
"sunriseDelay": -60,
"sunsetDelay": 60
}
</nowiki>

=== Rule definition ===
Rule name: '''CR13_RULE'''

<nowiki>
{
"conditions": {
"PAB/CR13_PAB/DAY": true
},
"actions": {
"OUTPUTS/1/ACTION": "${COND_RESULT}"
}
}
</nowiki>

== CR14 - Actions based on Power-UP <code>FW 4.0.0+</code>==

This example describes rule that evaluates after device start-up. Generally, there are 2 options for setting up conditions:
* SYSTEM/DEVICE_POWER_UP - device boot after power-cut

Condition in rule description below reacts to device boot after power-cut. When device first starts after regaining power, it sends alarm to output 1 in NETIO Cloud service.

=== Rule definition ===
Rule name: '''CR14_RULE'''

<nowiki>
{
"conditions": {
"SYSTEM/DEVICE_POWER_UP": true
},
"actions": {
"CLOUD/OUTPUT/1/ALARM": "${COND_RESULT}"
}
}
</nowiki>

== CR15 - Sunrise/sunset addaptive schedule with deep night off <code>FW 4.0.1+</code>==
Control output ON/OFF based on sunrise/sunset times of set location and combine it with standard schedule using rules.

In this example, output 1 gets turned on every day at 6:00 and switch off 30 minutes after sunrise and gets on again 30 minutes before sunset and turns off at midnight. This is an example of combination PAB output with standard schedule and mask the result of PAB with intervals defined in schedule.

Following combination creates dynamic variable input with static scheduler overlay and the behaviour can be simply chosen by logical equations.

=== 1. Configure schedule ===
Create a schedule with name "christmas_off" and create intervals 00:00 to 06:00 every day. No need to activate the scheduler for any output. Just define it.

[[File:CR15 schedule christmas off.png]]

=== 2. Create sunrise/sunset PAB ===

Following PAB will have <code>true</code> result during the day between sunrise with 30 minutes delay and 30 minutes before sunset set for location of NETIO Products headquarters (U pily 103, Prague, CZ). Elevation is set as 247 meters, above sea level. This result will be used in condition in rules to detect sunrise and sunset.

PAB name: '''daylight'''

<nowiki>
{
"type": "DAYLIGHT",
"longitude": "14.4129433E",
"latitude": "50.0058144N",
"altitude": 247,
"sunriseDelay": 30,
"sunsetDelay": -30
}
</nowiki>

=== 3. Create RULE for output ON ===

In this rule is definition when the output 1 should be enabled (ON). It is combination of two conditions of PAB and scheduler.

'''This code is saying:''' When is night ( day is false = <code>"PAB/daylight/DAY": false,</code>) and in paralel schedule is not active (set to be off = <code>"SCHEDULE/christmas_off/ACTIVE": false</code>) the result is <code>true</code> and following action (set output 1 to ON <code>"OUTPUTS/1/ACTION": 1</code>) is executed.

RULE name: '''outON'''

<nowiki>
{
"conditions": {
"operator": "AND",
"PAB/daylight/DAY": false,
"SCHEDULE/christmas_off/ACTIVE": false
},
"actions": {
"OUTPUTS/1/ACTION": 1
}
}
</nowiki>

=== 4. Create RULE for output OFF ===

In this rule is definition when the output 1 should be disabled (OFF). It is again combination of two conditions of PAB and scheduler.

'''This code is saying:''' When it is day now ( day is true = <code>"PAB/daylight/DAY": true,</code>) or the schedule is active (set to be on = <code>"SCHEDULE/christmas_off/ACTIVE": true</code>) the result is <code>true</code> and following action (set output 1 to OFF <code>"OUTPUTS/1/ACTION": 0</code>) is executed.

RULE name: '''outOFF'''

<nowiki>
{
"conditions": {
"operator": "OR",
"PAB/daylight/DAY": true,
"SCHEDULE/christmas_off/ACTIVE": true
},
"actions": {
"OUTPUTS/1/ACTION": 0
}
}
</nowiki>

Rules Complete Examples

2023-11-29T21:34:56Z

Bbakala: /* 4. Create RULE for output OFF */

The concept of NETIO Conditions (PAB & WatchDog) & Rules is a set of prepared detections (Conditions) and Rules that act upon them. They are implemented directly in NETIO PDU devices.

== CR01 - WatchDog (ping) to 1 IP address | default in FW 3.2.3 ==
The WatchDog functionality is used to monitor connectivity to specified IP address (or URL) by sending PING request to it.

The ping in this example is sent every 60s and waits 5s for the device to respond. If the ping fails, Watchdog returns <code>false</code> and restarts (ACTION: 2 = SHORT OFF) device connected to first output. After restart, it waits 120 seconds and starts monitoring again. If the device does not respond, WatchDog remains in ERROR state until next successful ping.

===WatchDog definition===

WatchDog name: '''CR01_WDT'''

<nowiki>
{
"target": "192.168.1.5",
"pingInterval": 60,
"timeout": 5,
"maxTimeouts": 0,
"timeToReboot": 120,
"maxRestarts": -1
}</nowiki>

===Rule definition===

Rule name: '''CR01_RULE'''

<nowiki>
{
"conditions": {
"WDT/CR01_WDT/FAIL": true
},
"actions": {
"OUTPUTS/1/ACTION": 2
}
}</nowiki>

== CR02 - Digital Inputs (Push button to Toggle Outputs 1 and 2) | default in FW 3.2.3 ==

Rule is used for managing outputs in response to change of Digital Inputs (DI) state. Rule monitors state of first DI. When DI switches from OFF (0) to ON (1), Rule switches (toggles) Outputs 1 & 2 to their opposite states (ACTION 4 = TOGGLE).

===Rule definition===

Rule name: '''CR02_RULE'''

<nowiki>
{
"conditions": {
"INPUTS/1/STATE": "on"
},
"actions": {
"OUTPUTS/1/ACTION": 4,
"OUTPUTS/2/ACTION": 4
}
}</nowiki>

== CR03 - Load Watchdog (Restart device if it's more than 2 minutes in IDLE mode) | default in FW 3.2.3 ==
Rule monitors load (Watts) on Output 1. If the load is between 1-20W for at least 2 minutes, it restarts (ACTION 2 = SHORT OFF) the output.
Example uses PAB (Power Analysis Block) functionality to determine if measured value (load in our case) lies in given range for a period of time. When it does, defined Rule triggers device restart.

===PAB definition===

PAB name: '''CR03_PAB'''
<nowiki>
{
"type": "RANGE",
"source": "OUTPUTS/1/LOAD",
"lowerBound": 1,
"upperBound": 20,
"timeHysteresis": 120
}</nowiki>

===Rule definition===

Rule name: '''CR03_RULE'''

<nowiki>
{
"conditions": {
"PAB/CR03_PAB/IN": true
},
"actions": {
"OUTPUTS/1/ACTION": 2
}
}</nowiki>

== CR04 - Load Watchdog with alarm to Cloud ==
Rule monitors load (Watts) on Output 1. If the load is between 1-20W for at least 30 minutes, it restarts (ACTION 2 = SHORT OFF) the output. In addition, it triggers an alarm in NETIO Cloud, which sends a notification to specified email address.
This example needs a NETIO Cloud account with Premium version active for first output. There also has to be email notification enabled for the output.

Example uses PAB (Power Analysis Block) functionality to determine if measured value (load in our case) lies in given range for a period of time. When it does, defined Rule triggers device restart and sends alarm to Cloud.

===PAB definition===

PAB name: '''CR04_PAB'''

<nowiki>
{
"type": "RANGE",
"source": "OUTPUTS/1/LOAD",
"lowerBound": 1,
"upperBound": 20,
"timeHysteresis": 1800
}</nowiki>

===Rule definition===

Rule name: '''CR04_RULE'''

<nowiki>
{
"conditions": {
"PAB/CR04_PAB/IN": true
},
"actions": {
"OUTPUTS/1/ACTION": 2,
"CLOUD/OUTPUT/1/ALARM": "${COND_RESULT}"
}
}</nowiki>

== CR05 - Load Watchdog with zones (indicate OFF / IDLE / RUN mode by switched on output)==
Rule monitors load (Watts) on Output 1. Measured load is then classified to several zones defined with thresholds (limit values). Depending on the zone in which the measured load is currently located, different actions can be triggered. Load value has to be between defined threshold for at least 10seconds in order to be placed to respective zone.
Example is composed of one PAB that classifies the zones and three Rules for 3 separate actions. Actions do the following:
* Output 1 load lower than 1W: Output 2 = ON
* Output 1 load between 1-20W: Output 3 = ON
* Output 1 load between 20-200W: Output 4 = ON

===PAB definition===

PAB name: '''CR05_PAB'''

<nowiki>
{
"type": "ZONES",
"source": "OUTPUTS/2/CURRENT",
"thresholds": [
1,
20,
200
],
"timeHysteresis": 10
}</nowiki>

===Rules definitions===

Rule 1 name: '''CR05_RULE_1'''

<nowiki>
{
"conditions": {
"PAB/NR05_PAB/ZONE": 0
},
"actions": {
"OUTPUTS/2/ACTION": 1,
"OUTPUTS/3/ACTION": 0,
"OUTPUTS/4/ACTION": 0
}
}</nowiki>

Rule 2 name: '''CR05_RULE_2'''

<nowiki>
{
"conditions": {
"PAB/CR05_PAB/ZONE": 1
},
"actions": {
"OUTPUTS/2/ACTION": 0,
"OUTPUTS/3/ACTION": 1,
"OUTPUTS/4/ACTION": 0
}
}</nowiki>

Rule 3 name: '''CR05_RULE_3'''

<nowiki>
{
"conditions": {
"PAB/CR05_PAB/ZONE": 2
},
"actions": {
"OUTPUTS/2/ACTION": 0,
"OUTPUTS/3/ACTION": 0,
"OUTPUTS/4/ACTION": 1
}
}</nowiki>

== CR06 - WatchDog for 2 IPs (Verify IP connectivity outage with 2 IPs)==
The WatchDog functionality is used to monitor connectivity to specified IP address (or URL) by sending PING request to it.

In this example, we monitor two IPs and we want to restart device connected to Output 1 if none of the addresses reply.
The ping for both IPs is sent every 30s and waits 5s for device to respond. There are 5 consecutive timeouts tolerated before the ping is considered as failed. When the ping fails, Watchdog returns <code>false</code> and remains in ERROR state.

In case both of the defined WatchDogs are in ERROR state, the Rule is triggered which then restarts Output 1.

===WatchDogs definition===

WatchDog name: '''CR06_WDT_1'''

<nowiki>
{
"target": "192.168.1.51",
"pingInterval": 30,
"timeout": 5,
"maxTimeouts": 5,
"timeToReboot": 120,
"maxRestarts": -1
}</nowiki>

WatchDog name: '''CR06_WDT_2'''

<nowiki>
{
"target": "192.168.1.52",
"pingInterval": 60,
"timeout": 5,
"maxTimeouts": 5,
"timeToReboot": 120,
"maxRestarts": -1
}</nowiki>

===Rule definition===

Rule name: '''CR06_RULE'''

<nowiki>
{
"conditions": {
"operator": "AND",
"WDT/CR06_WDT_1/FAIL": true,
"WDT/CR06_WDT_2/FAIL": true
},
"actions": {
"OUTPUTS/1/ACTION": 2
}
}</nowiki>

== CR07 - Synchronized outputs states during working hours ==
Rule keeps track of first output state and when it changes, it switches output 2 to the same state. However, we want this synchronization only to work during working hours. We define the time with Schedule functionality and use it as a filter (mask) in Rules. Schedule can be defined manually or imported as a configuration file.

===Schedule definition===

Schedule name: '''CR07_SCHEDULE'''

[[File:NR07_Schedule.png|NR070 Schedule]]

===Rule definition===

Rule name: '''CR07_RULE'''

<nowiki>
{
"conditions": {
"OUTPUTS/1/STATE": "on"
},
"filters": {
"SCHEDULE/CR07_SCHEDULE/ACTIVE": true
},
"actions": {
"OUTPUTS/2/ACTION": "${COND_RESULT}"
}
}</nowiki>

== CR08 - Load Watchdog -> Turn output ON after period of time ==

In this example we want to measure load on output 1 and indicate when the power is abnormally low for a period of time by switching device on Output 2 ON (could be control light, sound alarm etc.).

In PAB we define indication for low power usage (1-20W) that is measured for period of 30 minutes (1800 seconds).
In Rule we define switching Output 2 = ON (ACTION 1 = TURN ON) based on fulfilled PAB condition. This set up counts with human interaction after the Rule action gets processed. (e.g. restarting/replacing device on Output 1 and turning Output 2 OFF).
It is possible to alter this behavior in such a way that the control light (Output 2) turns automatically OFF when load on Output 1 returns to standard values, i.e. higher than 20W (device gets repaired/replaced) or drops to 0W (device was removed or Output 1 turned OFF). This setup is defined in Rule '''NR08_ALT'''

===PAB definition===

PAB name: '''CR08_PAB'''
<nowiki>
{
"type": "RANGE",
"source": "OUTPUTS/1/LOAD",
"lowerBound": 1,
"upperBound": 20,
"timeHysteresis": 1800
}</nowiki>

===Rule definition===

Rule name: '''CR08_RULE'''

<nowiki>
{
"conditions": {
"PAB/CR08_PAB/IN": true
},
"actions": {
"OUTPUTS/2/ACTION": 1
}
}</nowiki>

Rule name: '''CR08_RULE_ALT'''

<nowiki>
{
"conditions": {
"PAB/CR08_PAB/IN": true
},
"actions": {
"OUTPUTS/2/ACTION": "${COND_RESULT}"
}
}</nowiki>

== CR09 - Digital Inputs with Schedule ==

Examples shows usage when we want to detect switching of Digital Input to ON state (1) but to (not) react only during specified hours (e.g. outside of working hours).
Reaction hours are defined with Schedule functionality. Schedule can be defined manually or imported as a configuration file.

===Schedule definition===

Schedule name: '''CR09_SCHEDULE'''

===Rule definition===

Rule name: '''CR09_RULE'''

<nowiki>
{
"conditions": {
"INPUTS/1/STATE": "on"
},
"filters": {
"SCHEDULE/CR09_SCHEDULE/ACTIVE": false
},
"actions": {
"OUTPUTS/1/ACTION": 2
}
}</nowiki>

== CR10 - TURN OFF Output 1 before midnight ==
Rule in a combination with Schedule can be used to ensure a specified output will be turned off at the end of the day (or any other time).
Schedule in this application is '''NOT''' assigned to the output and acts only as a "trigger" for launching the Rule action.

===Schedule definition===

Schedule name: '''off_before_midnight'''

Schedule configuration: Schedule is configured to have '''intervals every day from 23:59 to 24:00'''. In this configuration, the output turns of at 23:59.

[[File:cr10_schedule.png|CR10 Schedule]]

===Rule definition===

Rule name: '''CR10_RULE'''
<nowiki>
{
"conditions": {
"SCHEDULE/off_before_midnight/ACTIVE": true
},
"filters": {
"OUTPUTS/1/STATE": "on"
},
"actions": {
"OUTPUTS/1/ACTION": 0
}
}</nowiki>

== CR11 - Total load (8QS)==
CR11_PAB

<nowiki>
{
"type": "RANGE",
"source": "OUTPUTS/TOTAL/LOAD",
"lowerBound": 30,
"upperBound": 100,
"timeHysteresis": 3
}</nowiki>

<nowiki>
{
"conditions": {
"operator": "OR",
"PAB/total_outputs/IN": true
},
"actions": {
"OUTPUTS/1/ACTION": 4,
"CLOUD/OUTPUT/1/ALARM": 1
}
}</nowiki>

== CR12 - Negative load ==
CR12_PAB

<nowiki>
{
"type": "RANGE",
"source": "OUTPUTS/1/LOAD",
"lowerBound": -400,
"upperBound": 0,
"timeHysteresis": 2
}</nowiki>

<nowiki>
{
"conditions": {
"PAB/negative/IN": true
},
"actions": {
"OUTPUTS/3/ACTION": 4,
"OUTPUTS/4/ACTION": 4
}
}</nowiki>

== CR13 - Actions based on daylight <code>FW 4.0.0+</code>==
Turns output ON/OFF based on sunrise/sunset times of set location.
In this example, output 1 gets turned on one hour before (-60 minutes) sunrise and turns off one hour (60 minutes) after sunset. Location is se for NETIO Products headquarters (U pily 103, Prague, CZ). Elevation is set as 247 meters, above sea level.

=== PAB definition ===
PAB name: '''CR13_PAB'''

<nowiki>
{
"type": "DAYLIGHT",
"longitude": "14.4129433E",
"latitude": "50.0058144N",
"altitude": 247,
"sunriseDelay": -60,
"sunsetDelay": 60
}
</nowiki>

=== Rule definition ===
Rule name: '''CR13_RULE'''

<nowiki>
{
"conditions": {
"PAB/CR13_PAB/DAY": true
},
"actions": {
"OUTPUTS/1/ACTION": "${COND_RESULT}"
}
}
</nowiki>

== CR14 - Actions based on Power-UP <code>FW 4.0.0+</code>==

This example describes rule that evaluates after device start-up. Generally, there are 2 options for setting up conditions:
* SYSTEM/DEVICE_POWER_UP - device boot after power-cut

Condition in rule description below reacts to device boot after power-cut. When device first starts after regaining power, it sends alarm to output 1 in NETIO Cloud service.

=== Rule definition ===
Rule name: '''CR14_RULE'''

<nowiki>
{
"conditions": {
"SYSTEM/DEVICE_POWER_UP": true
},
"actions": {
"CLOUD/OUTPUT/1/ALARM": "${COND_RESULT}"
}
}
</nowiki>

== CR15 - Sunrise/sunset addaptive schedule with deep night off <code>FW 4.0.1+</code>==
Control output ON/OFF based on sunrise/sunset times of set location and combine it with standard schedule using rules.

In this example, output 1 gets turned on every day at 6:00 and switch off 30 minutes after sunrise and gets on again 30 minutes before sunset and turns off at midnight. This is an example of combination PAB output with standard schedule and mask the result of PAB with intervals defined in schedule.

Following combination creates dynamic variable input with static scheduler overlay and the behaviour can be simply chosen by logical equations.

=== 1. Configure schedule ===
Create a schedule with name "christmas_off" and create intervals 00:00 to 06:00 every day. No need to activate the scheduler for any output. Just define it.

[[File:CR15 schedule christmas off.png]]

=== 2. Create sunrise/sunset PAB ===

Following PAB will have <code>true</code> result during the day between sunrise with 30 minutes delay and 30 minutes before sunset set for location of NETIO Products headquarters (U pily 103, Prague, CZ). Elevation is set as 247 meters, above sea level. This result will be used in condition in rules to detect sunrise and sunset.

PAB name: '''daylight'''

<nowiki>
{
"type": "DAYLIGHT",
"longitude": "14.4129433E",
"latitude": "50.0058144N",
"altitude": 247,
"sunriseDelay": 30,
"sunsetDelay": -30
}
</nowiki>

=== 3. Create RULE for output ON ===

In this rule is definition when the output 1 should be enabled (ON). It is combination of two conditions of PAB and scheduler.

'''This code is saying:''' When is night ( day is false = <code>"PAB/daylight/DAY": false,</code>) and in paralel schedule is not active (set to be off = <code>"SCHEDULE/christmas_off/ACTIVE": false</code>) the result is <code>true</code> and following action (set output 1 to ON <code>"OUTPUTS/1/ACTION": 1</code>)is executed.

RULE name: '''outON'''

<nowiki>
{
"conditions": {
"operator": "AND",
"PAB/daylight/DAY": false,
"SCHEDULE/christmas_off/ACTIVE": false
},
"actions": {
"OUTPUTS/1/ACTION": 1
}
}
</nowiki>

=== 4. Create RULE for output OFF ===

In this rule is definition when the output 1 should be disabled (OFF). It is again combination of two conditions of PAB and scheduler.

'''This code is saying:''' When it is day now ( day is true = <code>"PAB/daylight/DAY": true,</code>) or the schedule is active (set to be on = <code>"SCHEDULE/christmas_off/ACTIVE": true</code>) the result is <code>true</code> and following action (set output 1 to OFF <code>"OUTPUTS/1/ACTION": 0</code>) is executed.

RULE name: '''outOFF'''

<nowiki>
{
"conditions": {
"operator": "OR",
"PAB/daylight/DAY": true,
"SCHEDULE/christmas_off/ACTIVE": true
},
"actions": {
"OUTPUTS/1/ACTION": 0
}
}
</nowiki>

Rules Complete Examples

2023-11-29T21:34:33Z

Bbakala: /* 4. Create RULE for output OFF */

The concept of NETIO Conditions (PAB & WatchDog) & Rules is a set of prepared detections (Conditions) and Rules that act upon them. They are implemented directly in NETIO PDU devices.

== CR01 - WatchDog (ping) to 1 IP address | default in FW 3.2.3 ==
The WatchDog functionality is used to monitor connectivity to specified IP address (or URL) by sending PING request to it.

The ping in this example is sent every 60s and waits 5s for the device to respond. If the ping fails, Watchdog returns <code>false</code> and restarts (ACTION: 2 = SHORT OFF) device connected to first output. After restart, it waits 120 seconds and starts monitoring again. If the device does not respond, WatchDog remains in ERROR state until next successful ping.

===WatchDog definition===

WatchDog name: '''CR01_WDT'''

<nowiki>
{
"target": "192.168.1.5",
"pingInterval": 60,
"timeout": 5,
"maxTimeouts": 0,
"timeToReboot": 120,
"maxRestarts": -1
}</nowiki>

===Rule definition===

Rule name: '''CR01_RULE'''

<nowiki>
{
"conditions": {
"WDT/CR01_WDT/FAIL": true
},
"actions": {
"OUTPUTS/1/ACTION": 2
}
}</nowiki>

== CR02 - Digital Inputs (Push button to Toggle Outputs 1 and 2) | default in FW 3.2.3 ==

Rule is used for managing outputs in response to change of Digital Inputs (DI) state. Rule monitors state of first DI. When DI switches from OFF (0) to ON (1), Rule switches (toggles) Outputs 1 & 2 to their opposite states (ACTION 4 = TOGGLE).

===Rule definition===

Rule name: '''CR02_RULE'''

<nowiki>
{
"conditions": {
"INPUTS/1/STATE": "on"
},
"actions": {
"OUTPUTS/1/ACTION": 4,
"OUTPUTS/2/ACTION": 4
}
}</nowiki>

== CR03 - Load Watchdog (Restart device if it's more than 2 minutes in IDLE mode) | default in FW 3.2.3 ==
Rule monitors load (Watts) on Output 1. If the load is between 1-20W for at least 2 minutes, it restarts (ACTION 2 = SHORT OFF) the output.
Example uses PAB (Power Analysis Block) functionality to determine if measured value (load in our case) lies in given range for a period of time. When it does, defined Rule triggers device restart.

===PAB definition===

PAB name: '''CR03_PAB'''
<nowiki>
{
"type": "RANGE",
"source": "OUTPUTS/1/LOAD",
"lowerBound": 1,
"upperBound": 20,
"timeHysteresis": 120
}</nowiki>

===Rule definition===

Rule name: '''CR03_RULE'''

<nowiki>
{
"conditions": {
"PAB/CR03_PAB/IN": true
},
"actions": {
"OUTPUTS/1/ACTION": 2
}
}</nowiki>

== CR04 - Load Watchdog with alarm to Cloud ==
Rule monitors load (Watts) on Output 1. If the load is between 1-20W for at least 30 minutes, it restarts (ACTION 2 = SHORT OFF) the output. In addition, it triggers an alarm in NETIO Cloud, which sends a notification to specified email address.
This example needs a NETIO Cloud account with Premium version active for first output. There also has to be email notification enabled for the output.

Example uses PAB (Power Analysis Block) functionality to determine if measured value (load in our case) lies in given range for a period of time. When it does, defined Rule triggers device restart and sends alarm to Cloud.

===PAB definition===

PAB name: '''CR04_PAB'''

<nowiki>
{
"type": "RANGE",
"source": "OUTPUTS/1/LOAD",
"lowerBound": 1,
"upperBound": 20,
"timeHysteresis": 1800
}</nowiki>

===Rule definition===

Rule name: '''CR04_RULE'''

<nowiki>
{
"conditions": {
"PAB/CR04_PAB/IN": true
},
"actions": {
"OUTPUTS/1/ACTION": 2,
"CLOUD/OUTPUT/1/ALARM": "${COND_RESULT}"
}
}</nowiki>

== CR05 - Load Watchdog with zones (indicate OFF / IDLE / RUN mode by switched on output)==
Rule monitors load (Watts) on Output 1. Measured load is then classified to several zones defined with thresholds (limit values). Depending on the zone in which the measured load is currently located, different actions can be triggered. Load value has to be between defined threshold for at least 10seconds in order to be placed to respective zone.
Example is composed of one PAB that classifies the zones and three Rules for 3 separate actions. Actions do the following:
* Output 1 load lower than 1W: Output 2 = ON
* Output 1 load between 1-20W: Output 3 = ON
* Output 1 load between 20-200W: Output 4 = ON

===PAB definition===

PAB name: '''CR05_PAB'''

<nowiki>
{
"type": "ZONES",
"source": "OUTPUTS/2/CURRENT",
"thresholds": [
1,
20,
200
],
"timeHysteresis": 10
}</nowiki>

===Rules definitions===

Rule 1 name: '''CR05_RULE_1'''

<nowiki>
{
"conditions": {
"PAB/NR05_PAB/ZONE": 0
},
"actions": {
"OUTPUTS/2/ACTION": 1,
"OUTPUTS/3/ACTION": 0,
"OUTPUTS/4/ACTION": 0
}
}</nowiki>

Rule 2 name: '''CR05_RULE_2'''

<nowiki>
{
"conditions": {
"PAB/CR05_PAB/ZONE": 1
},
"actions": {
"OUTPUTS/2/ACTION": 0,
"OUTPUTS/3/ACTION": 1,
"OUTPUTS/4/ACTION": 0
}
}</nowiki>

Rule 3 name: '''CR05_RULE_3'''

<nowiki>
{
"conditions": {
"PAB/CR05_PAB/ZONE": 2
},
"actions": {
"OUTPUTS/2/ACTION": 0,
"OUTPUTS/3/ACTION": 0,
"OUTPUTS/4/ACTION": 1
}
}</nowiki>

== CR06 - WatchDog for 2 IPs (Verify IP connectivity outage with 2 IPs)==
The WatchDog functionality is used to monitor connectivity to specified IP address (or URL) by sending PING request to it.

In this example, we monitor two IPs and we want to restart device connected to Output 1 if none of the addresses reply.
The ping for both IPs is sent every 30s and waits 5s for device to respond. There are 5 consecutive timeouts tolerated before the ping is considered as failed. When the ping fails, Watchdog returns <code>false</code> and remains in ERROR state.

In case both of the defined WatchDogs are in ERROR state, the Rule is triggered which then restarts Output 1.

===WatchDogs definition===

WatchDog name: '''CR06_WDT_1'''

<nowiki>
{
"target": "192.168.1.51",
"pingInterval": 30,
"timeout": 5,
"maxTimeouts": 5,
"timeToReboot": 120,
"maxRestarts": -1
}</nowiki>

WatchDog name: '''CR06_WDT_2'''

<nowiki>
{
"target": "192.168.1.52",
"pingInterval": 60,
"timeout": 5,
"maxTimeouts": 5,
"timeToReboot": 120,
"maxRestarts": -1
}</nowiki>

===Rule definition===

Rule name: '''CR06_RULE'''

<nowiki>
{
"conditions": {
"operator": "AND",
"WDT/CR06_WDT_1/FAIL": true,
"WDT/CR06_WDT_2/FAIL": true
},
"actions": {
"OUTPUTS/1/ACTION": 2
}
}</nowiki>

== CR07 - Synchronized outputs states during working hours ==
Rule keeps track of first output state and when it changes, it switches output 2 to the same state. However, we want this synchronization only to work during working hours. We define the time with Schedule functionality and use it as a filter (mask) in Rules. Schedule can be defined manually or imported as a configuration file.

===Schedule definition===

Schedule name: '''CR07_SCHEDULE'''

[[File:NR07_Schedule.png|NR070 Schedule]]

===Rule definition===

Rule name: '''CR07_RULE'''

<nowiki>
{
"conditions": {
"OUTPUTS/1/STATE": "on"
},
"filters": {
"SCHEDULE/CR07_SCHEDULE/ACTIVE": true
},
"actions": {
"OUTPUTS/2/ACTION": "${COND_RESULT}"
}
}</nowiki>

== CR08 - Load Watchdog -> Turn output ON after period of time ==

In this example we want to measure load on output 1 and indicate when the power is abnormally low for a period of time by switching device on Output 2 ON (could be control light, sound alarm etc.).

In PAB we define indication for low power usage (1-20W) that is measured for period of 30 minutes (1800 seconds).
In Rule we define switching Output 2 = ON (ACTION 1 = TURN ON) based on fulfilled PAB condition. This set up counts with human interaction after the Rule action gets processed. (e.g. restarting/replacing device on Output 1 and turning Output 2 OFF).
It is possible to alter this behavior in such a way that the control light (Output 2) turns automatically OFF when load on Output 1 returns to standard values, i.e. higher than 20W (device gets repaired/replaced) or drops to 0W (device was removed or Output 1 turned OFF). This setup is defined in Rule '''NR08_ALT'''

===PAB definition===

PAB name: '''CR08_PAB'''
<nowiki>
{
"type": "RANGE",
"source": "OUTPUTS/1/LOAD",
"lowerBound": 1,
"upperBound": 20,
"timeHysteresis": 1800
}</nowiki>

===Rule definition===

Rule name: '''CR08_RULE'''

<nowiki>
{
"conditions": {
"PAB/CR08_PAB/IN": true
},
"actions": {
"OUTPUTS/2/ACTION": 1
}
}</nowiki>

Rule name: '''CR08_RULE_ALT'''

<nowiki>
{
"conditions": {
"PAB/CR08_PAB/IN": true
},
"actions": {
"OUTPUTS/2/ACTION": "${COND_RESULT}"
}
}</nowiki>

== CR09 - Digital Inputs with Schedule ==

Examples shows usage when we want to detect switching of Digital Input to ON state (1) but to (not) react only during specified hours (e.g. outside of working hours).
Reaction hours are defined with Schedule functionality. Schedule can be defined manually or imported as a configuration file.

===Schedule definition===

Schedule name: '''CR09_SCHEDULE'''

===Rule definition===

Rule name: '''CR09_RULE'''

<nowiki>
{
"conditions": {
"INPUTS/1/STATE": "on"
},
"filters": {
"SCHEDULE/CR09_SCHEDULE/ACTIVE": false
},
"actions": {
"OUTPUTS/1/ACTION": 2
}
}</nowiki>

== CR10 - TURN OFF Output 1 before midnight ==
Rule in a combination with Schedule can be used to ensure a specified output will be turned off at the end of the day (or any other time).
Schedule in this application is '''NOT''' assigned to the output and acts only as a "trigger" for launching the Rule action.

===Schedule definition===

Schedule name: '''off_before_midnight'''

Schedule configuration: Schedule is configured to have '''intervals every day from 23:59 to 24:00'''. In this configuration, the output turns of at 23:59.

[[File:cr10_schedule.png|CR10 Schedule]]

===Rule definition===

Rule name: '''CR10_RULE'''
<nowiki>
{
"conditions": {
"SCHEDULE/off_before_midnight/ACTIVE": true
},
"filters": {
"OUTPUTS/1/STATE": "on"
},
"actions": {
"OUTPUTS/1/ACTION": 0
}
}</nowiki>

== CR11 - Total load (8QS)==
CR11_PAB

<nowiki>
{
"type": "RANGE",
"source": "OUTPUTS/TOTAL/LOAD",
"lowerBound": 30,
"upperBound": 100,
"timeHysteresis": 3
}</nowiki>

<nowiki>
{
"conditions": {
"operator": "OR",
"PAB/total_outputs/IN": true
},
"actions": {
"OUTPUTS/1/ACTION": 4,
"CLOUD/OUTPUT/1/ALARM": 1
}
}</nowiki>

== CR12 - Negative load ==
CR12_PAB

<nowiki>
{
"type": "RANGE",
"source": "OUTPUTS/1/LOAD",
"lowerBound": -400,
"upperBound": 0,
"timeHysteresis": 2
}</nowiki>

<nowiki>
{
"conditions": {
"PAB/negative/IN": true
},
"actions": {
"OUTPUTS/3/ACTION": 4,
"OUTPUTS/4/ACTION": 4
}
}</nowiki>

== CR13 - Actions based on daylight <code>FW 4.0.0+</code>==
Turns output ON/OFF based on sunrise/sunset times of set location.
In this example, output 1 gets turned on one hour before (-60 minutes) sunrise and turns off one hour (60 minutes) after sunset. Location is se for NETIO Products headquarters (U pily 103, Prague, CZ). Elevation is set as 247 meters, above sea level.

=== PAB definition ===
PAB name: '''CR13_PAB'''

<nowiki>
{
"type": "DAYLIGHT",
"longitude": "14.4129433E",
"latitude": "50.0058144N",
"altitude": 247,
"sunriseDelay": -60,
"sunsetDelay": 60
}
</nowiki>

=== Rule definition ===
Rule name: '''CR13_RULE'''

<nowiki>
{
"conditions": {
"PAB/CR13_PAB/DAY": true
},
"actions": {
"OUTPUTS/1/ACTION": "${COND_RESULT}"
}
}
</nowiki>

== CR14 - Actions based on Power-UP <code>FW 4.0.0+</code>==

This example describes rule that evaluates after device start-up. Generally, there are 2 options for setting up conditions:
* SYSTEM/DEVICE_POWER_UP - device boot after power-cut

Condition in rule description below reacts to device boot after power-cut. When device first starts after regaining power, it sends alarm to output 1 in NETIO Cloud service.

=== Rule definition ===
Rule name: '''CR14_RULE'''

<nowiki>
{
"conditions": {
"SYSTEM/DEVICE_POWER_UP": true
},
"actions": {
"CLOUD/OUTPUT/1/ALARM": "${COND_RESULT}"
}
}
</nowiki>

== CR15 - Sunrise/sunset addaptive schedule with deep night off <code>FW 4.0.1+</code>==
Control output ON/OFF based on sunrise/sunset times of set location and combine it with standard schedule using rules.

In this example, output 1 gets turned on every day at 6:00 and switch off 30 minutes after sunrise and gets on again 30 minutes before sunset and turns off at midnight. This is an example of combination PAB output with standard schedule and mask the result of PAB with intervals defined in schedule.

Following combination creates dynamic variable input with static scheduler overlay and the behaviour can be simply chosen by logical equations.

=== 1. Configure schedule ===
Create a schedule with name "christmas_off" and create intervals 00:00 to 06:00 every day. No need to activate the scheduler for any output. Just define it.

[[File:CR15 schedule christmas off.png]]

=== 2. Create sunrise/sunset PAB ===

Following PAB will have <code>true</code> result during the day between sunrise with 30 minutes delay and 30 minutes before sunset set for location of NETIO Products headquarters (U pily 103, Prague, CZ). Elevation is set as 247 meters, above sea level. This result will be used in condition in rules to detect sunrise and sunset.

PAB name: '''daylight'''

<nowiki>
{
"type": "DAYLIGHT",
"longitude": "14.4129433E",
"latitude": "50.0058144N",
"altitude": 247,
"sunriseDelay": 30,
"sunsetDelay": -30
}
</nowiki>

=== 3. Create RULE for output ON ===

In this rule is definition when the output 1 should be enabled (ON). It is combination of two conditions of PAB and scheduler.

'''This code is saying:''' When is night ( day is false = <code>"PAB/daylight/DAY": false,</code>) and in paralel schedule is not active (set to be off = <code>"SCHEDULE/christmas_off/ACTIVE": false</code>) the result is <code>true</code> and following action (set output 1 to ON <code>"OUTPUTS/1/ACTION": 1</code>)is executed.

RULE name: '''outON'''

<nowiki>
{
"conditions": {
"operator": "AND",
"PAB/daylight/DAY": false,
"SCHEDULE/christmas_off/ACTIVE": false
},
"actions": {
"OUTPUTS/1/ACTION": 1
}
}
</nowiki>

=== 4. Create RULE for output OFF ===

In this rule is definition when the output 1 should be disabled (OFF). It is again combination of two conditions of PAB and scheduler.

'''This code is saying:''' When it is day now ( day is true = <code>"PAB/daylight/DAY": true,</code>) or the schedule is active (set to be on = <code>"SCHEDULE/christmas_off/ACTIVE": true</code>) the result is <code>true</code> and following action (set output 1 to OFF <code>"OUTPUTS/1/ACTION": 0</code>)is executed.

RULE name: '''outOFF'''

<nowiki>
{
"conditions": {
"operator": "OR",
"PAB/daylight/DAY": true,
"SCHEDULE/christmas_off/ACTIVE": true
},
"actions": {
"OUTPUTS/1/ACTION": 0
}
}
</nowiki>

Rules Complete Examples

2023-11-29T21:31:50Z

Bbakala: /* CR15 - Sunrise/sunset addaptive schedule with deep night off FW 4.0.1+ */

The concept of NETIO Conditions (PAB & WatchDog) & Rules is a set of prepared detections (Conditions) and Rules that act upon them. They are implemented directly in NETIO PDU devices.

== CR01 - WatchDog (ping) to 1 IP address | default in FW 3.2.3 ==
The WatchDog functionality is used to monitor connectivity to specified IP address (or URL) by sending PING request to it.

The ping in this example is sent every 60s and waits 5s for the device to respond. If the ping fails, Watchdog returns <code>false</code> and restarts (ACTION: 2 = SHORT OFF) device connected to first output. After restart, it waits 120 seconds and starts monitoring again. If the device does not respond, WatchDog remains in ERROR state until next successful ping.

===WatchDog definition===

WatchDog name: '''CR01_WDT'''

<nowiki>
{
"target": "192.168.1.5",
"pingInterval": 60,
"timeout": 5,
"maxTimeouts": 0,
"timeToReboot": 120,
"maxRestarts": -1
}</nowiki>

===Rule definition===

Rule name: '''CR01_RULE'''

<nowiki>
{
"conditions": {
"WDT/CR01_WDT/FAIL": true
},
"actions": {
"OUTPUTS/1/ACTION": 2
}
}</nowiki>

== CR02 - Digital Inputs (Push button to Toggle Outputs 1 and 2) | default in FW 3.2.3 ==

Rule is used for managing outputs in response to change of Digital Inputs (DI) state. Rule monitors state of first DI. When DI switches from OFF (0) to ON (1), Rule switches (toggles) Outputs 1 & 2 to their opposite states (ACTION 4 = TOGGLE).

===Rule definition===

Rule name: '''CR02_RULE'''

<nowiki>
{
"conditions": {
"INPUTS/1/STATE": "on"
},
"actions": {
"OUTPUTS/1/ACTION": 4,
"OUTPUTS/2/ACTION": 4
}
}</nowiki>

== CR03 - Load Watchdog (Restart device if it's more than 2 minutes in IDLE mode) | default in FW 3.2.3 ==
Rule monitors load (Watts) on Output 1. If the load is between 1-20W for at least 2 minutes, it restarts (ACTION 2 = SHORT OFF) the output.
Example uses PAB (Power Analysis Block) functionality to determine if measured value (load in our case) lies in given range for a period of time. When it does, defined Rule triggers device restart.

===PAB definition===

PAB name: '''CR03_PAB'''
<nowiki>
{
"type": "RANGE",
"source": "OUTPUTS/1/LOAD",
"lowerBound": 1,
"upperBound": 20,
"timeHysteresis": 120
}</nowiki>

===Rule definition===

Rule name: '''CR03_RULE'''

<nowiki>
{
"conditions": {
"PAB/CR03_PAB/IN": true
},
"actions": {
"OUTPUTS/1/ACTION": 2
}
}</nowiki>

== CR04 - Load Watchdog with alarm to Cloud ==
Rule monitors load (Watts) on Output 1. If the load is between 1-20W for at least 30 minutes, it restarts (ACTION 2 = SHORT OFF) the output. In addition, it triggers an alarm in NETIO Cloud, which sends a notification to specified email address.
This example needs a NETIO Cloud account with Premium version active for first output. There also has to be email notification enabled for the output.

Example uses PAB (Power Analysis Block) functionality to determine if measured value (load in our case) lies in given range for a period of time. When it does, defined Rule triggers device restart and sends alarm to Cloud.

===PAB definition===

PAB name: '''CR04_PAB'''

<nowiki>
{
"type": "RANGE",
"source": "OUTPUTS/1/LOAD",
"lowerBound": 1,
"upperBound": 20,
"timeHysteresis": 1800
}</nowiki>

===Rule definition===

Rule name: '''CR04_RULE'''

<nowiki>
{
"conditions": {
"PAB/CR04_PAB/IN": true
},
"actions": {
"OUTPUTS/1/ACTION": 2,
"CLOUD/OUTPUT/1/ALARM": "${COND_RESULT}"
}
}</nowiki>

== CR05 - Load Watchdog with zones (indicate OFF / IDLE / RUN mode by switched on output)==
Rule monitors load (Watts) on Output 1. Measured load is then classified to several zones defined with thresholds (limit values). Depending on the zone in which the measured load is currently located, different actions can be triggered. Load value has to be between defined threshold for at least 10seconds in order to be placed to respective zone.
Example is composed of one PAB that classifies the zones and three Rules for 3 separate actions. Actions do the following:
* Output 1 load lower than 1W: Output 2 = ON
* Output 1 load between 1-20W: Output 3 = ON
* Output 1 load between 20-200W: Output 4 = ON

===PAB definition===

PAB name: '''CR05_PAB'''

<nowiki>
{
"type": "ZONES",
"source": "OUTPUTS/2/CURRENT",
"thresholds": [
1,
20,
200
],
"timeHysteresis": 10
}</nowiki>

===Rules definitions===

Rule 1 name: '''CR05_RULE_1'''

<nowiki>
{
"conditions": {
"PAB/NR05_PAB/ZONE": 0
},
"actions": {
"OUTPUTS/2/ACTION": 1,
"OUTPUTS/3/ACTION": 0,
"OUTPUTS/4/ACTION": 0
}
}</nowiki>

Rule 2 name: '''CR05_RULE_2'''

<nowiki>
{
"conditions": {
"PAB/CR05_PAB/ZONE": 1
},
"actions": {
"OUTPUTS/2/ACTION": 0,
"OUTPUTS/3/ACTION": 1,
"OUTPUTS/4/ACTION": 0
}
}</nowiki>

Rule 3 name: '''CR05_RULE_3'''

<nowiki>
{
"conditions": {
"PAB/CR05_PAB/ZONE": 2
},
"actions": {
"OUTPUTS/2/ACTION": 0,
"OUTPUTS/3/ACTION": 0,
"OUTPUTS/4/ACTION": 1
}
}</nowiki>

== CR06 - WatchDog for 2 IPs (Verify IP connectivity outage with 2 IPs)==
The WatchDog functionality is used to monitor connectivity to specified IP address (or URL) by sending PING request to it.

In this example, we monitor two IPs and we want to restart device connected to Output 1 if none of the addresses reply.
The ping for both IPs is sent every 30s and waits 5s for device to respond. There are 5 consecutive timeouts tolerated before the ping is considered as failed. When the ping fails, Watchdog returns <code>false</code> and remains in ERROR state.

In case both of the defined WatchDogs are in ERROR state, the Rule is triggered which then restarts Output 1.

===WatchDogs definition===

WatchDog name: '''CR06_WDT_1'''

<nowiki>
{
"target": "192.168.1.51",
"pingInterval": 30,
"timeout": 5,
"maxTimeouts": 5,
"timeToReboot": 120,
"maxRestarts": -1
}</nowiki>

WatchDog name: '''CR06_WDT_2'''

<nowiki>
{
"target": "192.168.1.52",
"pingInterval": 60,
"timeout": 5,
"maxTimeouts": 5,
"timeToReboot": 120,
"maxRestarts": -1
}</nowiki>

===Rule definition===

Rule name: '''CR06_RULE'''

<nowiki>
{
"conditions": {
"operator": "AND",
"WDT/CR06_WDT_1/FAIL": true,
"WDT/CR06_WDT_2/FAIL": true
},
"actions": {
"OUTPUTS/1/ACTION": 2
}
}</nowiki>

== CR07 - Synchronized outputs states during working hours ==
Rule keeps track of first output state and when it changes, it switches output 2 to the same state. However, we want this synchronization only to work during working hours. We define the time with Schedule functionality and use it as a filter (mask) in Rules. Schedule can be defined manually or imported as a configuration file.

===Schedule definition===

Schedule name: '''CR07_SCHEDULE'''

[[File:NR07_Schedule.png|NR070 Schedule]]

===Rule definition===

Rule name: '''CR07_RULE'''

<nowiki>
{
"conditions": {
"OUTPUTS/1/STATE": "on"
},
"filters": {
"SCHEDULE/CR07_SCHEDULE/ACTIVE": true
},
"actions": {
"OUTPUTS/2/ACTION": "${COND_RESULT}"
}
}</nowiki>

== CR08 - Load Watchdog -> Turn output ON after period of time ==

In this example we want to measure load on output 1 and indicate when the power is abnormally low for a period of time by switching device on Output 2 ON (could be control light, sound alarm etc.).

In PAB we define indication for low power usage (1-20W) that is measured for period of 30 minutes (1800 seconds).
In Rule we define switching Output 2 = ON (ACTION 1 = TURN ON) based on fulfilled PAB condition. This set up counts with human interaction after the Rule action gets processed. (e.g. restarting/replacing device on Output 1 and turning Output 2 OFF).
It is possible to alter this behavior in such a way that the control light (Output 2) turns automatically OFF when load on Output 1 returns to standard values, i.e. higher than 20W (device gets repaired/replaced) or drops to 0W (device was removed or Output 1 turned OFF). This setup is defined in Rule '''NR08_ALT'''

===PAB definition===

PAB name: '''CR08_PAB'''
<nowiki>
{
"type": "RANGE",
"source": "OUTPUTS/1/LOAD",
"lowerBound": 1,
"upperBound": 20,
"timeHysteresis": 1800
}</nowiki>

===Rule definition===

Rule name: '''CR08_RULE'''

<nowiki>
{
"conditions": {
"PAB/CR08_PAB/IN": true
},
"actions": {
"OUTPUTS/2/ACTION": 1
}
}</nowiki>

Rule name: '''CR08_RULE_ALT'''

<nowiki>
{
"conditions": {
"PAB/CR08_PAB/IN": true
},
"actions": {
"OUTPUTS/2/ACTION": "${COND_RESULT}"
}
}</nowiki>

== CR09 - Digital Inputs with Schedule ==

Examples shows usage when we want to detect switching of Digital Input to ON state (1) but to (not) react only during specified hours (e.g. outside of working hours).
Reaction hours are defined with Schedule functionality. Schedule can be defined manually or imported as a configuration file.

===Schedule definition===

Schedule name: '''CR09_SCHEDULE'''

===Rule definition===

Rule name: '''CR09_RULE'''

<nowiki>
{
"conditions": {
"INPUTS/1/STATE": "on"
},
"filters": {
"SCHEDULE/CR09_SCHEDULE/ACTIVE": false
},
"actions": {
"OUTPUTS/1/ACTION": 2
}
}</nowiki>

== CR10 - TURN OFF Output 1 before midnight ==
Rule in a combination with Schedule can be used to ensure a specified output will be turned off at the end of the day (or any other time).
Schedule in this application is '''NOT''' assigned to the output and acts only as a "trigger" for launching the Rule action.

===Schedule definition===

Schedule name: '''off_before_midnight'''

Schedule configuration: Schedule is configured to have '''intervals every day from 23:59 to 24:00'''. In this configuration, the output turns of at 23:59.

[[File:cr10_schedule.png|CR10 Schedule]]

===Rule definition===

Rule name: '''CR10_RULE'''
<nowiki>
{
"conditions": {
"SCHEDULE/off_before_midnight/ACTIVE": true
},
"filters": {
"OUTPUTS/1/STATE": "on"
},
"actions": {
"OUTPUTS/1/ACTION": 0
}
}</nowiki>

== CR11 - Total load (8QS)==
CR11_PAB

<nowiki>
{
"type": "RANGE",
"source": "OUTPUTS/TOTAL/LOAD",
"lowerBound": 30,
"upperBound": 100,
"timeHysteresis": 3
}</nowiki>

<nowiki>
{
"conditions": {
"operator": "OR",
"PAB/total_outputs/IN": true
},
"actions": {
"OUTPUTS/1/ACTION": 4,
"CLOUD/OUTPUT/1/ALARM": 1
}
}</nowiki>

== CR12 - Negative load ==
CR12_PAB

<nowiki>
{
"type": "RANGE",
"source": "OUTPUTS/1/LOAD",
"lowerBound": -400,
"upperBound": 0,
"timeHysteresis": 2
}</nowiki>

<nowiki>
{
"conditions": {
"PAB/negative/IN": true
},
"actions": {
"OUTPUTS/3/ACTION": 4,
"OUTPUTS/4/ACTION": 4
}
}</nowiki>

== CR13 - Actions based on daylight <code>FW 4.0.0+</code>==
Turns output ON/OFF based on sunrise/sunset times of set location.
In this example, output 1 gets turned on one hour before (-60 minutes) sunrise and turns off one hour (60 minutes) after sunset. Location is se for NETIO Products headquarters (U pily 103, Prague, CZ). Elevation is set as 247 meters, above sea level.

=== PAB definition ===
PAB name: '''CR13_PAB'''

<nowiki>
{
"type": "DAYLIGHT",
"longitude": "14.4129433E",
"latitude": "50.0058144N",
"altitude": 247,
"sunriseDelay": -60,
"sunsetDelay": 60
}
</nowiki>

=== Rule definition ===
Rule name: '''CR13_RULE'''

<nowiki>
{
"conditions": {
"PAB/CR13_PAB/DAY": true
},
"actions": {
"OUTPUTS/1/ACTION": "${COND_RESULT}"
}
}
</nowiki>

== CR14 - Actions based on Power-UP <code>FW 4.0.0+</code>==

This example describes rule that evaluates after device start-up. Generally, there are 2 options for setting up conditions:
* SYSTEM/DEVICE_POWER_UP - device boot after power-cut

Condition in rule description below reacts to device boot after power-cut. When device first starts after regaining power, it sends alarm to output 1 in NETIO Cloud service.

=== Rule definition ===
Rule name: '''CR14_RULE'''

<nowiki>
{
"conditions": {
"SYSTEM/DEVICE_POWER_UP": true
},
"actions": {
"CLOUD/OUTPUT/1/ALARM": "${COND_RESULT}"
}
}
</nowiki>

== CR15 - Sunrise/sunset addaptive schedule with deep night off <code>FW 4.0.1+</code>==
Control output ON/OFF based on sunrise/sunset times of set location and combine it with standard schedule using rules.

In this example, output 1 gets turned on every day at 6:00 and switch off 30 minutes after sunrise and gets on again 30 minutes before sunset and turns off at midnight. This is an example of combination PAB output with standard schedule and mask the result of PAB with intervals defined in schedule.

Following combination creates dynamic variable input with static scheduler overlay and the behaviour can be simply chosen by logical equations.

=== 1. Configure schedule ===
Create a schedule with name "christmas_off" and create intervals 00:00 to 06:00 every day. No need to activate the scheduler for any output. Just define it.

[[File:CR15 schedule christmas off.png]]

=== 2. Create sunrise/sunset PAB ===

Following PAB will have <code>true</code> result during the day between sunrise with 30 minutes delay and 30 minutes before sunset set for location of NETIO Products headquarters (U pily 103, Prague, CZ). Elevation is set as 247 meters, above sea level. This result will be used in condition in rules to detect sunrise and sunset.

PAB name: '''daylight'''

<nowiki>
{
"type": "DAYLIGHT",
"longitude": "14.4129433E",
"latitude": "50.0058144N",
"altitude": 247,
"sunriseDelay": 30,
"sunsetDelay": -30
}
</nowiki>

=== 3. Create RULE for output ON ===

In this rule is definition when the output 1 should be enabled (ON). It is combination of two conditions of PAB and scheduler.

'''This code is saying:''' When is night ( day is false = <code>"PAB/daylight/DAY": false,</code>) and in paralel schedule is not active (set to be off = <code>"SCHEDULE/christmas_off/ACTIVE": false</code>) the result is <code>true</code> and following action (set output 1 to ON <code>"OUTPUTS/1/ACTION": 1</code>)is executed.

RULE name: '''outON'''

<nowiki>
{
"conditions": {
"operator": "AND",
"PAB/daylight/DAY": false,
"SCHEDULE/christmas_off/ACTIVE": false
},
"actions": {
"OUTPUTS/1/ACTION": 1
}
}
</nowiki>

=== 4. Create RULE for output OFF ===

In this rule is definition when the output 1 should be disabled (OFF). It is again combination of two conditions of PAB and scheduler.

'''This code is saying:''' When is day ( day is true = <code>"PAB/daylight/DAY": true,</code>) or in paralel schedule is active (set to be on = <code>"SCHEDULE/christmas_off/ACTIVE": true</code>) the result is <code>true</code> and following action (set output 1 to OFF <code>"OUTPUTS/1/ACTION": 0</code>)is executed.

RULE name: '''outOFF'''

<nowiki>
{
"conditions": {
"operator": "OR",
"PAB/daylight/DAY": true,
"SCHEDULE/christmas_off/ACTIVE": true
},
"actions": {
"OUTPUTS/1/ACTION": 0
}
}
</nowiki>

Rules Complete Examples

2023-11-29T21:31:31Z

Bbakala: /* CR15 - Sunrise/sunset addaptive schedule with deep night off FW 4.0.1+ */

The concept of NETIO Conditions (PAB & WatchDog) & Rules is a set of prepared detections (Conditions) and Rules that act upon them. They are implemented directly in NETIO PDU devices.

== CR01 - WatchDog (ping) to 1 IP address | default in FW 3.2.3 ==
The WatchDog functionality is used to monitor connectivity to specified IP address (or URL) by sending PING request to it.

The ping in this example is sent every 60s and waits 5s for the device to respond. If the ping fails, Watchdog returns <code>false</code> and restarts (ACTION: 2 = SHORT OFF) device connected to first output. After restart, it waits 120 seconds and starts monitoring again. If the device does not respond, WatchDog remains in ERROR state until next successful ping.

===WatchDog definition===

WatchDog name: '''CR01_WDT'''

<nowiki>
{
"target": "192.168.1.5",
"pingInterval": 60,
"timeout": 5,
"maxTimeouts": 0,
"timeToReboot": 120,
"maxRestarts": -1
}</nowiki>

===Rule definition===

Rule name: '''CR01_RULE'''

<nowiki>
{
"conditions": {
"WDT/CR01_WDT/FAIL": true
},
"actions": {
"OUTPUTS/1/ACTION": 2
}
}</nowiki>

== CR02 - Digital Inputs (Push button to Toggle Outputs 1 and 2) | default in FW 3.2.3 ==

Rule is used for managing outputs in response to change of Digital Inputs (DI) state. Rule monitors state of first DI. When DI switches from OFF (0) to ON (1), Rule switches (toggles) Outputs 1 & 2 to their opposite states (ACTION 4 = TOGGLE).

===Rule definition===

Rule name: '''CR02_RULE'''

<nowiki>
{
"conditions": {
"INPUTS/1/STATE": "on"
},
"actions": {
"OUTPUTS/1/ACTION": 4,
"OUTPUTS/2/ACTION": 4
}
}</nowiki>

== CR03 - Load Watchdog (Restart device if it's more than 2 minutes in IDLE mode) | default in FW 3.2.3 ==
Rule monitors load (Watts) on Output 1. If the load is between 1-20W for at least 2 minutes, it restarts (ACTION 2 = SHORT OFF) the output.
Example uses PAB (Power Analysis Block) functionality to determine if measured value (load in our case) lies in given range for a period of time. When it does, defined Rule triggers device restart.

===PAB definition===

PAB name: '''CR03_PAB'''
<nowiki>
{
"type": "RANGE",
"source": "OUTPUTS/1/LOAD",
"lowerBound": 1,
"upperBound": 20,
"timeHysteresis": 120
}</nowiki>

===Rule definition===

Rule name: '''CR03_RULE'''

<nowiki>
{
"conditions": {
"PAB/CR03_PAB/IN": true
},
"actions": {
"OUTPUTS/1/ACTION": 2
}
}</nowiki>

== CR04 - Load Watchdog with alarm to Cloud ==
Rule monitors load (Watts) on Output 1. If the load is between 1-20W for at least 30 minutes, it restarts (ACTION 2 = SHORT OFF) the output. In addition, it triggers an alarm in NETIO Cloud, which sends a notification to specified email address.
This example needs a NETIO Cloud account with Premium version active for first output. There also has to be email notification enabled for the output.

Example uses PAB (Power Analysis Block) functionality to determine if measured value (load in our case) lies in given range for a period of time. When it does, defined Rule triggers device restart and sends alarm to Cloud.

===PAB definition===

PAB name: '''CR04_PAB'''

<nowiki>
{
"type": "RANGE",
"source": "OUTPUTS/1/LOAD",
"lowerBound": 1,
"upperBound": 20,
"timeHysteresis": 1800
}</nowiki>

===Rule definition===

Rule name: '''CR04_RULE'''

<nowiki>
{
"conditions": {
"PAB/CR04_PAB/IN": true
},
"actions": {
"OUTPUTS/1/ACTION": 2,
"CLOUD/OUTPUT/1/ALARM": "${COND_RESULT}"
}
}</nowiki>

== CR05 - Load Watchdog with zones (indicate OFF / IDLE / RUN mode by switched on output)==
Rule monitors load (Watts) on Output 1. Measured load is then classified to several zones defined with thresholds (limit values). Depending on the zone in which the measured load is currently located, different actions can be triggered. Load value has to be between defined threshold for at least 10seconds in order to be placed to respective zone.
Example is composed of one PAB that classifies the zones and three Rules for 3 separate actions. Actions do the following:
* Output 1 load lower than 1W: Output 2 = ON
* Output 1 load between 1-20W: Output 3 = ON
* Output 1 load between 20-200W: Output 4 = ON

===PAB definition===

PAB name: '''CR05_PAB'''

<nowiki>
{
"type": "ZONES",
"source": "OUTPUTS/2/CURRENT",
"thresholds": [
1,
20,
200
],
"timeHysteresis": 10
}</nowiki>

===Rules definitions===

Rule 1 name: '''CR05_RULE_1'''

<nowiki>
{
"conditions": {
"PAB/NR05_PAB/ZONE": 0
},
"actions": {
"OUTPUTS/2/ACTION": 1,
"OUTPUTS/3/ACTION": 0,
"OUTPUTS/4/ACTION": 0
}
}</nowiki>

Rule 2 name: '''CR05_RULE_2'''

<nowiki>
{
"conditions": {
"PAB/CR05_PAB/ZONE": 1
},
"actions": {
"OUTPUTS/2/ACTION": 0,
"OUTPUTS/3/ACTION": 1,
"OUTPUTS/4/ACTION": 0
}
}</nowiki>

Rule 3 name: '''CR05_RULE_3'''

<nowiki>
{
"conditions": {
"PAB/CR05_PAB/ZONE": 2
},
"actions": {
"OUTPUTS/2/ACTION": 0,
"OUTPUTS/3/ACTION": 0,
"OUTPUTS/4/ACTION": 1
}
}</nowiki>

== CR06 - WatchDog for 2 IPs (Verify IP connectivity outage with 2 IPs)==
The WatchDog functionality is used to monitor connectivity to specified IP address (or URL) by sending PING request to it.

In this example, we monitor two IPs and we want to restart device connected to Output 1 if none of the addresses reply.
The ping for both IPs is sent every 30s and waits 5s for device to respond. There are 5 consecutive timeouts tolerated before the ping is considered as failed. When the ping fails, Watchdog returns <code>false</code> and remains in ERROR state.

In case both of the defined WatchDogs are in ERROR state, the Rule is triggered which then restarts Output 1.

===WatchDogs definition===

WatchDog name: '''CR06_WDT_1'''

<nowiki>
{
"target": "192.168.1.51",
"pingInterval": 30,
"timeout": 5,
"maxTimeouts": 5,
"timeToReboot": 120,
"maxRestarts": -1
}</nowiki>

WatchDog name: '''CR06_WDT_2'''

<nowiki>
{
"target": "192.168.1.52",
"pingInterval": 60,
"timeout": 5,
"maxTimeouts": 5,
"timeToReboot": 120,
"maxRestarts": -1
}</nowiki>

===Rule definition===

Rule name: '''CR06_RULE'''

<nowiki>
{
"conditions": {
"operator": "AND",
"WDT/CR06_WDT_1/FAIL": true,
"WDT/CR06_WDT_2/FAIL": true
},
"actions": {
"OUTPUTS/1/ACTION": 2
}
}</nowiki>

== CR07 - Synchronized outputs states during working hours ==
Rule keeps track of first output state and when it changes, it switches output 2 to the same state. However, we want this synchronization only to work during working hours. We define the time with Schedule functionality and use it as a filter (mask) in Rules. Schedule can be defined manually or imported as a configuration file.

===Schedule definition===

Schedule name: '''CR07_SCHEDULE'''

[[File:NR07_Schedule.png|NR070 Schedule]]

===Rule definition===

Rule name: '''CR07_RULE'''

<nowiki>
{
"conditions": {
"OUTPUTS/1/STATE": "on"
},
"filters": {
"SCHEDULE/CR07_SCHEDULE/ACTIVE": true
},
"actions": {
"OUTPUTS/2/ACTION": "${COND_RESULT}"
}
}</nowiki>

== CR08 - Load Watchdog -> Turn output ON after period of time ==

In this example we want to measure load on output 1 and indicate when the power is abnormally low for a period of time by switching device on Output 2 ON (could be control light, sound alarm etc.).

In PAB we define indication for low power usage (1-20W) that is measured for period of 30 minutes (1800 seconds).
In Rule we define switching Output 2 = ON (ACTION 1 = TURN ON) based on fulfilled PAB condition. This set up counts with human interaction after the Rule action gets processed. (e.g. restarting/replacing device on Output 1 and turning Output 2 OFF).
It is possible to alter this behavior in such a way that the control light (Output 2) turns automatically OFF when load on Output 1 returns to standard values, i.e. higher than 20W (device gets repaired/replaced) or drops to 0W (device was removed or Output 1 turned OFF). This setup is defined in Rule '''NR08_ALT'''

===PAB definition===

PAB name: '''CR08_PAB'''
<nowiki>
{
"type": "RANGE",
"source": "OUTPUTS/1/LOAD",
"lowerBound": 1,
"upperBound": 20,
"timeHysteresis": 1800
}</nowiki>

===Rule definition===

Rule name: '''CR08_RULE'''

<nowiki>
{
"conditions": {
"PAB/CR08_PAB/IN": true
},
"actions": {
"OUTPUTS/2/ACTION": 1
}
}</nowiki>

Rule name: '''CR08_RULE_ALT'''

<nowiki>
{
"conditions": {
"PAB/CR08_PAB/IN": true
},
"actions": {
"OUTPUTS/2/ACTION": "${COND_RESULT}"
}
}</nowiki>

== CR09 - Digital Inputs with Schedule ==

Examples shows usage when we want to detect switching of Digital Input to ON state (1) but to (not) react only during specified hours (e.g. outside of working hours).
Reaction hours are defined with Schedule functionality. Schedule can be defined manually or imported as a configuration file.

===Schedule definition===

Schedule name: '''CR09_SCHEDULE'''

===Rule definition===

Rule name: '''CR09_RULE'''

<nowiki>
{
"conditions": {
"INPUTS/1/STATE": "on"
},
"filters": {
"SCHEDULE/CR09_SCHEDULE/ACTIVE": false
},
"actions": {
"OUTPUTS/1/ACTION": 2
}
}</nowiki>

== CR10 - TURN OFF Output 1 before midnight ==
Rule in a combination with Schedule can be used to ensure a specified output will be turned off at the end of the day (or any other time).
Schedule in this application is '''NOT''' assigned to the output and acts only as a "trigger" for launching the Rule action.

===Schedule definition===

Schedule name: '''off_before_midnight'''

Schedule configuration: Schedule is configured to have '''intervals every day from 23:59 to 24:00'''. In this configuration, the output turns of at 23:59.

[[File:cr10_schedule.png|CR10 Schedule]]

===Rule definition===

Rule name: '''CR10_RULE'''
<nowiki>
{
"conditions": {
"SCHEDULE/off_before_midnight/ACTIVE": true
},
"filters": {
"OUTPUTS/1/STATE": "on"
},
"actions": {
"OUTPUTS/1/ACTION": 0
}
}</nowiki>

== CR11 - Total load (8QS)==
CR11_PAB

<nowiki>
{
"type": "RANGE",
"source": "OUTPUTS/TOTAL/LOAD",
"lowerBound": 30,
"upperBound": 100,
"timeHysteresis": 3
}</nowiki>

<nowiki>
{
"conditions": {
"operator": "OR",
"PAB/total_outputs/IN": true
},
"actions": {
"OUTPUTS/1/ACTION": 4,
"CLOUD/OUTPUT/1/ALARM": 1
}
}</nowiki>

== CR12 - Negative load ==
CR12_PAB

<nowiki>
{
"type": "RANGE",
"source": "OUTPUTS/1/LOAD",
"lowerBound": -400,
"upperBound": 0,
"timeHysteresis": 2
}</nowiki>

<nowiki>
{
"conditions": {
"PAB/negative/IN": true
},
"actions": {
"OUTPUTS/3/ACTION": 4,
"OUTPUTS/4/ACTION": 4
}
}</nowiki>

== CR13 - Actions based on daylight <code>FW 4.0.0+</code>==
Turns output ON/OFF based on sunrise/sunset times of set location.
In this example, output 1 gets turned on one hour before (-60 minutes) sunrise and turns off one hour (60 minutes) after sunset. Location is se for NETIO Products headquarters (U pily 103, Prague, CZ). Elevation is set as 247 meters, above sea level.

=== PAB definition ===
PAB name: '''CR13_PAB'''

<nowiki>
{
"type": "DAYLIGHT",
"longitude": "14.4129433E",
"latitude": "50.0058144N",
"altitude": 247,
"sunriseDelay": -60,
"sunsetDelay": 60
}
</nowiki>

=== Rule definition ===
Rule name: '''CR13_RULE'''

<nowiki>
{
"conditions": {
"PAB/CR13_PAB/DAY": true
},
"actions": {
"OUTPUTS/1/ACTION": "${COND_RESULT}"
}
}
</nowiki>

== CR14 - Actions based on Power-UP <code>FW 4.0.0+</code>==

This example describes rule that evaluates after device start-up. Generally, there are 2 options for setting up conditions:
* SYSTEM/DEVICE_POWER_UP - device boot after power-cut

Condition in rule description below reacts to device boot after power-cut. When device first starts after regaining power, it sends alarm to output 1 in NETIO Cloud service.

=== Rule definition ===
Rule name: '''CR14_RULE'''

<nowiki>
{
"conditions": {
"SYSTEM/DEVICE_POWER_UP": true
},
"actions": {
"CLOUD/OUTPUT/1/ALARM": "${COND_RESULT}"
}
}
</nowiki>

== CR15 - Sunrise/sunset addaptive schedule with deep night off <code>FW 4.0.1+</code>==
Control output ON/OFF based on sunrise/sunset times of set location and combine it with standard schedule using rules.
In this example, output 1 gets turned on every day at 6:00 and switch off 30 minutes after sunrise and gets on again 30 minutes before sunset and turns off at midnight. This is an example of combination PAB output with standard schedule and mask the result of PAB with intervals defined in schedule.

Following combination creates dynamic variable input with static scheduler overlay and the behaviour can be simply chosen by logical equations.

=== 1. Configure schedule ===
Create a schedule with name "christmas_off" and create intervals 00:00 to 06:00 every day. No need to activate the scheduler for any output. Just define it.

[[File:CR15 schedule christmas off.png]]

=== 2. Create sunrise/sunset PAB ===

Following PAB will have <code>true</code> result during the day between sunrise with 30 minutes delay and 30 minutes before sunset set for location of NETIO Products headquarters (U pily 103, Prague, CZ). Elevation is set as 247 meters, above sea level. This result will be used in condition in rules to detect sunrise and sunset.

PAB name: '''daylight'''

<nowiki>
{
"type": "DAYLIGHT",
"longitude": "14.4129433E",
"latitude": "50.0058144N",
"altitude": 247,
"sunriseDelay": 30,
"sunsetDelay": -30
}
</nowiki>

=== 3. Create RULE for output ON ===

In this rule is definition when the output 1 should be enabled (ON). It is combination of two conditions of PAB and scheduler.

'''This code is saying:''' When is night ( day is false = <code>"PAB/daylight/DAY": false,</code>) and in paralel schedule is not active (set to be off = <code>"SCHEDULE/christmas_off/ACTIVE": false</code>) the result is <code>true</code> and following action (set output 1 to ON <code>"OUTPUTS/1/ACTION": 1</code>)is executed.

RULE name: '''outON'''

<nowiki>
{
"conditions": {
"operator": "AND",
"PAB/daylight/DAY": false,
"SCHEDULE/christmas_off/ACTIVE": false
},
"actions": {
"OUTPUTS/1/ACTION": 1
}
}
</nowiki>

=== 4. Create RULE for output OFF ===

In this rule is definition when the output 1 should be disabled (OFF). It is again combination of two conditions of PAB and scheduler.

'''This code is saying:''' When is day ( day is true = <code>"PAB/daylight/DAY": true,</code>) or in paralel schedule is active (set to be on = <code>"SCHEDULE/christmas_off/ACTIVE": true</code>) the result is <code>true</code> and following action (set output 1 to OFF <code>"OUTPUTS/1/ACTION": 0</code>)is executed.

RULE name: '''outOFF'''

<nowiki>
{
"conditions": {
"operator": "OR",
"PAB/daylight/DAY": true,
"SCHEDULE/christmas_off/ACTIVE": true
},
"actions": {
"OUTPUTS/1/ACTION": 0
}
}
</nowiki>

Rules Complete Examples

2023-11-29T21:17:13Z

Bbakala: /* 1. Configure schedule */

The concept of NETIO Conditions (PAB & WatchDog) & Rules is a set of prepared detections (Conditions) and Rules that act upon them. They are implemented directly in NETIO PDU devices.

== CR01 - WatchDog (ping) to 1 IP address | default in FW 3.2.3 ==
The WatchDog functionality is used to monitor connectivity to specified IP address (or URL) by sending PING request to it.

The ping in this example is sent every 60s and waits 5s for the device to respond. If the ping fails, Watchdog returns <code>false</code> and restarts (ACTION: 2 = SHORT OFF) device connected to first output. After restart, it waits 120 seconds and starts monitoring again. If the device does not respond, WatchDog remains in ERROR state until next successful ping.

===WatchDog definition===

WatchDog name: '''CR01_WDT'''

<nowiki>
{
"target": "192.168.1.5",
"pingInterval": 60,
"timeout": 5,
"maxTimeouts": 0,
"timeToReboot": 120,
"maxRestarts": -1
}</nowiki>

===Rule definition===

Rule name: '''CR01_RULE'''

<nowiki>
{
"conditions": {
"WDT/CR01_WDT/FAIL": true
},
"actions": {
"OUTPUTS/1/ACTION": 2
}
}</nowiki>

== CR02 - Digital Inputs (Push button to Toggle Outputs 1 and 2) | default in FW 3.2.3 ==

Rule is used for managing outputs in response to change of Digital Inputs (DI) state. Rule monitors state of first DI. When DI switches from OFF (0) to ON (1), Rule switches (toggles) Outputs 1 & 2 to their opposite states (ACTION 4 = TOGGLE).

===Rule definition===

Rule name: '''CR02_RULE'''

<nowiki>
{
"conditions": {
"INPUTS/1/STATE": "on"
},
"actions": {
"OUTPUTS/1/ACTION": 4,
"OUTPUTS/2/ACTION": 4
}
}</nowiki>

== CR03 - Load Watchdog (Restart device if it's more than 2 minutes in IDLE mode) | default in FW 3.2.3 ==
Rule monitors load (Watts) on Output 1. If the load is between 1-20W for at least 2 minutes, it restarts (ACTION 2 = SHORT OFF) the output.
Example uses PAB (Power Analysis Block) functionality to determine if measured value (load in our case) lies in given range for a period of time. When it does, defined Rule triggers device restart.

===PAB definition===

PAB name: '''CR03_PAB'''
<nowiki>
{
"type": "RANGE",
"source": "OUTPUTS/1/LOAD",
"lowerBound": 1,
"upperBound": 20,
"timeHysteresis": 120
}</nowiki>

===Rule definition===

Rule name: '''CR03_RULE'''

<nowiki>
{
"conditions": {
"PAB/CR03_PAB/IN": true
},
"actions": {
"OUTPUTS/1/ACTION": 2
}
}</nowiki>

== CR04 - Load Watchdog with alarm to Cloud ==
Rule monitors load (Watts) on Output 1. If the load is between 1-20W for at least 30 minutes, it restarts (ACTION 2 = SHORT OFF) the output. In addition, it triggers an alarm in NETIO Cloud, which sends a notification to specified email address.
This example needs a NETIO Cloud account with Premium version active for first output. There also has to be email notification enabled for the output.

Example uses PAB (Power Analysis Block) functionality to determine if measured value (load in our case) lies in given range for a period of time. When it does, defined Rule triggers device restart and sends alarm to Cloud.

===PAB definition===

PAB name: '''CR04_PAB'''

<nowiki>
{
"type": "RANGE",
"source": "OUTPUTS/1/LOAD",
"lowerBound": 1,
"upperBound": 20,
"timeHysteresis": 1800
}</nowiki>

===Rule definition===

Rule name: '''CR04_RULE'''

<nowiki>
{
"conditions": {
"PAB/CR04_PAB/IN": true
},
"actions": {
"OUTPUTS/1/ACTION": 2,
"CLOUD/OUTPUT/1/ALARM": "${COND_RESULT}"
}
}</nowiki>

== CR05 - Load Watchdog with zones (indicate OFF / IDLE / RUN mode by switched on output)==
Rule monitors load (Watts) on Output 1. Measured load is then classified to several zones defined with thresholds (limit values). Depending on the zone in which the measured load is currently located, different actions can be triggered. Load value has to be between defined threshold for at least 10seconds in order to be placed to respective zone.
Example is composed of one PAB that classifies the zones and three Rules for 3 separate actions. Actions do the following:
* Output 1 load lower than 1W: Output 2 = ON
* Output 1 load between 1-20W: Output 3 = ON
* Output 1 load between 20-200W: Output 4 = ON

===PAB definition===

PAB name: '''CR05_PAB'''

<nowiki>
{
"type": "ZONES",
"source": "OUTPUTS/2/CURRENT",
"thresholds": [
1,
20,
200
],
"timeHysteresis": 10
}</nowiki>

===Rules definitions===

Rule 1 name: '''CR05_RULE_1'''

<nowiki>
{
"conditions": {
"PAB/NR05_PAB/ZONE": 0
},
"actions": {
"OUTPUTS/2/ACTION": 1,
"OUTPUTS/3/ACTION": 0,
"OUTPUTS/4/ACTION": 0
}
}</nowiki>

Rule 2 name: '''CR05_RULE_2'''

<nowiki>
{
"conditions": {
"PAB/CR05_PAB/ZONE": 1
},
"actions": {
"OUTPUTS/2/ACTION": 0,
"OUTPUTS/3/ACTION": 1,
"OUTPUTS/4/ACTION": 0
}
}</nowiki>

Rule 3 name: '''CR05_RULE_3'''

<nowiki>
{
"conditions": {
"PAB/CR05_PAB/ZONE": 2
},
"actions": {
"OUTPUTS/2/ACTION": 0,
"OUTPUTS/3/ACTION": 0,
"OUTPUTS/4/ACTION": 1
}
}</nowiki>

== CR06 - WatchDog for 2 IPs (Verify IP connectivity outage with 2 IPs)==
The WatchDog functionality is used to monitor connectivity to specified IP address (or URL) by sending PING request to it.

In this example, we monitor two IPs and we want to restart device connected to Output 1 if none of the addresses reply.
The ping for both IPs is sent every 30s and waits 5s for device to respond. There are 5 consecutive timeouts tolerated before the ping is considered as failed. When the ping fails, Watchdog returns <code>false</code> and remains in ERROR state.

In case both of the defined WatchDogs are in ERROR state, the Rule is triggered which then restarts Output 1.

===WatchDogs definition===

WatchDog name: '''CR06_WDT_1'''

<nowiki>
{
"target": "192.168.1.51",
"pingInterval": 30,
"timeout": 5,
"maxTimeouts": 5,
"timeToReboot": 120,
"maxRestarts": -1
}</nowiki>

WatchDog name: '''CR06_WDT_2'''

<nowiki>
{
"target": "192.168.1.52",
"pingInterval": 60,
"timeout": 5,
"maxTimeouts": 5,
"timeToReboot": 120,
"maxRestarts": -1
}</nowiki>

===Rule definition===

Rule name: '''CR06_RULE'''

<nowiki>
{
"conditions": {
"operator": "AND",
"WDT/CR06_WDT_1/FAIL": true,
"WDT/CR06_WDT_2/FAIL": true
},
"actions": {
"OUTPUTS/1/ACTION": 2
}
}</nowiki>

== CR07 - Synchronized outputs states during working hours ==
Rule keeps track of first output state and when it changes, it switches output 2 to the same state. However, we want this synchronization only to work during working hours. We define the time with Schedule functionality and use it as a filter (mask) in Rules. Schedule can be defined manually or imported as a configuration file.

===Schedule definition===

Schedule name: '''CR07_SCHEDULE'''

[[File:NR07_Schedule.png|NR070 Schedule]]

===Rule definition===

Rule name: '''CR07_RULE'''

<nowiki>
{
"conditions": {
"OUTPUTS/1/STATE": "on"
},
"filters": {
"SCHEDULE/CR07_SCHEDULE/ACTIVE": true
},
"actions": {
"OUTPUTS/2/ACTION": "${COND_RESULT}"
}
}</nowiki>

== CR08 - Load Watchdog -> Turn output ON after period of time ==

In this example we want to measure load on output 1 and indicate when the power is abnormally low for a period of time by switching device on Output 2 ON (could be control light, sound alarm etc.).

In PAB we define indication for low power usage (1-20W) that is measured for period of 30 minutes (1800 seconds).
In Rule we define switching Output 2 = ON (ACTION 1 = TURN ON) based on fulfilled PAB condition. This set up counts with human interaction after the Rule action gets processed. (e.g. restarting/replacing device on Output 1 and turning Output 2 OFF).
It is possible to alter this behavior in such a way that the control light (Output 2) turns automatically OFF when load on Output 1 returns to standard values, i.e. higher than 20W (device gets repaired/replaced) or drops to 0W (device was removed or Output 1 turned OFF). This setup is defined in Rule '''NR08_ALT'''

===PAB definition===

PAB name: '''CR08_PAB'''
<nowiki>
{
"type": "RANGE",
"source": "OUTPUTS/1/LOAD",
"lowerBound": 1,
"upperBound": 20,
"timeHysteresis": 1800
}</nowiki>

===Rule definition===

Rule name: '''CR08_RULE'''

<nowiki>
{
"conditions": {
"PAB/CR08_PAB/IN": true
},
"actions": {
"OUTPUTS/2/ACTION": 1
}
}</nowiki>

Rule name: '''CR08_RULE_ALT'''

<nowiki>
{
"conditions": {
"PAB/CR08_PAB/IN": true
},
"actions": {
"OUTPUTS/2/ACTION": "${COND_RESULT}"
}
}</nowiki>

== CR09 - Digital Inputs with Schedule ==

Examples shows usage when we want to detect switching of Digital Input to ON state (1) but to (not) react only during specified hours (e.g. outside of working hours).
Reaction hours are defined with Schedule functionality. Schedule can be defined manually or imported as a configuration file.

===Schedule definition===

Schedule name: '''CR09_SCHEDULE'''

===Rule definition===

Rule name: '''CR09_RULE'''

<nowiki>
{
"conditions": {
"INPUTS/1/STATE": "on"
},
"filters": {
"SCHEDULE/CR09_SCHEDULE/ACTIVE": false
},
"actions": {
"OUTPUTS/1/ACTION": 2
}
}</nowiki>

== CR10 - TURN OFF Output 1 before midnight ==
Rule in a combination with Schedule can be used to ensure a specified output will be turned off at the end of the day (or any other time).
Schedule in this application is '''NOT''' assigned to the output and acts only as a "trigger" for launching the Rule action.

===Schedule definition===

Schedule name: '''off_before_midnight'''

Schedule configuration: Schedule is configured to have '''intervals every day from 23:59 to 24:00'''. In this configuration, the output turns of at 23:59.

[[File:cr10_schedule.png|CR10 Schedule]]

===Rule definition===

Rule name: '''CR10_RULE'''
<nowiki>
{
"conditions": {
"SCHEDULE/off_before_midnight/ACTIVE": true
},
"filters": {
"OUTPUTS/1/STATE": "on"
},
"actions": {
"OUTPUTS/1/ACTION": 0
}
}</nowiki>

== CR11 - Total load (8QS)==
CR11_PAB

<nowiki>
{
"type": "RANGE",
"source": "OUTPUTS/TOTAL/LOAD",
"lowerBound": 30,
"upperBound": 100,
"timeHysteresis": 3
}</nowiki>

<nowiki>
{
"conditions": {
"operator": "OR",
"PAB/total_outputs/IN": true
},
"actions": {
"OUTPUTS/1/ACTION": 4,
"CLOUD/OUTPUT/1/ALARM": 1
}
}</nowiki>

== CR12 - Negative load ==
CR12_PAB

<nowiki>
{
"type": "RANGE",
"source": "OUTPUTS/1/LOAD",
"lowerBound": -400,
"upperBound": 0,
"timeHysteresis": 2
}</nowiki>

<nowiki>
{
"conditions": {
"PAB/negative/IN": true
},
"actions": {
"OUTPUTS/3/ACTION": 4,
"OUTPUTS/4/ACTION": 4
}
}</nowiki>

== CR13 - Actions based on daylight <code>FW 4.0.0+</code>==
Turns output ON/OFF based on sunrise/sunset times of set location.
In this example, output 1 gets turned on one hour before (-60 minutes) sunrise and turns off one hour (60 minutes) after sunset. Location is se for NETIO Products headquarters (U pily 103, Prague, CZ). Elevation is set as 247 meters, above sea level.

=== PAB definition ===
PAB name: '''CR13_PAB'''

<nowiki>
{
"type": "DAYLIGHT",
"longitude": "14.4129433E",
"latitude": "50.0058144N",
"altitude": 247,
"sunriseDelay": -60,
"sunsetDelay": 60
}
</nowiki>

=== Rule definition ===
Rule name: '''CR13_RULE'''

<nowiki>
{
"conditions": {
"PAB/CR13_PAB/DAY": true
},
"actions": {
"OUTPUTS/1/ACTION": "${COND_RESULT}"
}
}
</nowiki>

== CR14 - Actions based on Power-UP <code>FW 4.0.0+</code>==

This example describes rule that evaluates after device start-up. Generally, there are 2 options for setting up conditions:
* SYSTEM/DEVICE_POWER_UP - device boot after power-cut

Condition in rule description below reacts to device boot after power-cut. When device first starts after regaining power, it sends alarm to output 1 in NETIO Cloud service.

=== Rule definition ===
Rule name: '''CR14_RULE'''

<nowiki>
{
"conditions": {
"SYSTEM/DEVICE_POWER_UP": true
},
"actions": {
"CLOUD/OUTPUT/1/ALARM": "${COND_RESULT}"
}
}
</nowiki>

== CR15 - Sunrise/sunset addaptive schedule with deep night off <code>FW 4.0.1+</code>==
Control output ON/OFF based on sunrise/sunset times of set location and combine it with standard schedule using rules.
In this example, output 1 gets turned on every day at 6:00 and switch off 30 minutes after sunrise and gets on again 30 minutes before sunset and turns off at midnight. This is an example of combination PAB output with standard schedule and mask the result of PAB with intervals defined in schedule.

=== 1. Configure schedule ===
Create a schedule with name "christmas_off" and create intervals 00:00 to 06:00 every day.

[[File:CR15 schedule christmas off.png]]

=== 2. Create sunrise/sunset PAB ===

Following PAB will have <code>true</code> result during the day between sunrise with 30 minutes delay and 30 minutes before sunset set for location of NETIO Products headquarters (U pily 103, Prague, CZ). Elevation is set as 247 meters, above sea level. This result will be used in condition in rules to detect sunrise and sunset.

PAB name: '''daylight'''

<nowiki>
{
"type": "DAYLIGHT",
"longitude": "14.4129433E",
"latitude": "50.0058144N",
"altitude": 247,
"sunriseDelay": 30,
"sunsetDelay": -30
}
</nowiki>

=== 3. Create rule for output ON ===

=== 4. Create rule for output OFF ===

=== PAB definition ===
PAB name: '''CR13_PAB'''

<nowiki>
{
"type": "DAYLIGHT",
"longitude": "14.4129433E",
"latitude": "50.0058144N",
"altitude": 247,
"sunriseDelay": -60,
"sunsetDelay": 60
}
</nowiki>

=== Rule definition ===
Rule name: '''CR13_RULE'''

<nowiki>
{
"conditions": {
"PAB/CR13_PAB/DAY": true
},
"actions": {
"OUTPUTS/1/ACTION": "${COND_RESULT}"
}
}
</nowiki>

Rules Complete Examples

2023-11-29T21:17:04Z

Bbakala: /* CR15 - Sunrise/sunset addaptive schedule with deep night offFW 4.0.1+ */

The concept of NETIO Conditions (PAB & WatchDog) & Rules is a set of prepared detections (Conditions) and Rules that act upon them. They are implemented directly in NETIO PDU devices.

== CR01 - WatchDog (ping) to 1 IP address | default in FW 3.2.3 ==
The WatchDog functionality is used to monitor connectivity to specified IP address (or URL) by sending PING request to it.

The ping in this example is sent every 60s and waits 5s for the device to respond. If the ping fails, Watchdog returns <code>false</code> and restarts (ACTION: 2 = SHORT OFF) device connected to first output. After restart, it waits 120 seconds and starts monitoring again. If the device does not respond, WatchDog remains in ERROR state until next successful ping.

===WatchDog definition===

WatchDog name: '''CR01_WDT'''

<nowiki>
{
"target": "192.168.1.5",
"pingInterval": 60,
"timeout": 5,
"maxTimeouts": 0,
"timeToReboot": 120,
"maxRestarts": -1
}</nowiki>

===Rule definition===

Rule name: '''CR01_RULE'''

<nowiki>
{
"conditions": {
"WDT/CR01_WDT/FAIL": true
},
"actions": {
"OUTPUTS/1/ACTION": 2
}
}</nowiki>

== CR02 - Digital Inputs (Push button to Toggle Outputs 1 and 2) | default in FW 3.2.3 ==

Rule is used for managing outputs in response to change of Digital Inputs (DI) state. Rule monitors state of first DI. When DI switches from OFF (0) to ON (1), Rule switches (toggles) Outputs 1 & 2 to their opposite states (ACTION 4 = TOGGLE).

===Rule definition===

Rule name: '''CR02_RULE'''

<nowiki>
{
"conditions": {
"INPUTS/1/STATE": "on"
},
"actions": {
"OUTPUTS/1/ACTION": 4,
"OUTPUTS/2/ACTION": 4
}
}</nowiki>

== CR03 - Load Watchdog (Restart device if it's more than 2 minutes in IDLE mode) | default in FW 3.2.3 ==
Rule monitors load (Watts) on Output 1. If the load is between 1-20W for at least 2 minutes, it restarts (ACTION 2 = SHORT OFF) the output.
Example uses PAB (Power Analysis Block) functionality to determine if measured value (load in our case) lies in given range for a period of time. When it does, defined Rule triggers device restart.

===PAB definition===

PAB name: '''CR03_PAB'''
<nowiki>
{
"type": "RANGE",
"source": "OUTPUTS/1/LOAD",
"lowerBound": 1,
"upperBound": 20,
"timeHysteresis": 120
}</nowiki>

===Rule definition===

Rule name: '''CR03_RULE'''

<nowiki>
{
"conditions": {
"PAB/CR03_PAB/IN": true
},
"actions": {
"OUTPUTS/1/ACTION": 2
}
}</nowiki>

== CR04 - Load Watchdog with alarm to Cloud ==
Rule monitors load (Watts) on Output 1. If the load is between 1-20W for at least 30 minutes, it restarts (ACTION 2 = SHORT OFF) the output. In addition, it triggers an alarm in NETIO Cloud, which sends a notification to specified email address.
This example needs a NETIO Cloud account with Premium version active for first output. There also has to be email notification enabled for the output.

Example uses PAB (Power Analysis Block) functionality to determine if measured value (load in our case) lies in given range for a period of time. When it does, defined Rule triggers device restart and sends alarm to Cloud.

===PAB definition===

PAB name: '''CR04_PAB'''

<nowiki>
{
"type": "RANGE",
"source": "OUTPUTS/1/LOAD",
"lowerBound": 1,
"upperBound": 20,
"timeHysteresis": 1800
}</nowiki>

===Rule definition===

Rule name: '''CR04_RULE'''

<nowiki>
{
"conditions": {
"PAB/CR04_PAB/IN": true
},
"actions": {
"OUTPUTS/1/ACTION": 2,
"CLOUD/OUTPUT/1/ALARM": "${COND_RESULT}"
}
}</nowiki>

== CR05 - Load Watchdog with zones (indicate OFF / IDLE / RUN mode by switched on output)==
Rule monitors load (Watts) on Output 1. Measured load is then classified to several zones defined with thresholds (limit values). Depending on the zone in which the measured load is currently located, different actions can be triggered. Load value has to be between defined threshold for at least 10seconds in order to be placed to respective zone.
Example is composed of one PAB that classifies the zones and three Rules for 3 separate actions. Actions do the following:
* Output 1 load lower than 1W: Output 2 = ON
* Output 1 load between 1-20W: Output 3 = ON
* Output 1 load between 20-200W: Output 4 = ON

===PAB definition===

PAB name: '''CR05_PAB'''

<nowiki>
{
"type": "ZONES",
"source": "OUTPUTS/2/CURRENT",
"thresholds": [
1,
20,
200
],
"timeHysteresis": 10
}</nowiki>

===Rules definitions===

Rule 1 name: '''CR05_RULE_1'''

<nowiki>
{
"conditions": {
"PAB/NR05_PAB/ZONE": 0
},
"actions": {
"OUTPUTS/2/ACTION": 1,
"OUTPUTS/3/ACTION": 0,
"OUTPUTS/4/ACTION": 0
}
}</nowiki>

Rule 2 name: '''CR05_RULE_2'''

<nowiki>
{
"conditions": {
"PAB/CR05_PAB/ZONE": 1
},
"actions": {
"OUTPUTS/2/ACTION": 0,
"OUTPUTS/3/ACTION": 1,
"OUTPUTS/4/ACTION": 0
}
}</nowiki>

Rule 3 name: '''CR05_RULE_3'''

<nowiki>
{
"conditions": {
"PAB/CR05_PAB/ZONE": 2
},
"actions": {
"OUTPUTS/2/ACTION": 0,
"OUTPUTS/3/ACTION": 0,
"OUTPUTS/4/ACTION": 1
}
}</nowiki>

== CR06 - WatchDog for 2 IPs (Verify IP connectivity outage with 2 IPs)==
The WatchDog functionality is used to monitor connectivity to specified IP address (or URL) by sending PING request to it.

In this example, we monitor two IPs and we want to restart device connected to Output 1 if none of the addresses reply.
The ping for both IPs is sent every 30s and waits 5s for device to respond. There are 5 consecutive timeouts tolerated before the ping is considered as failed. When the ping fails, Watchdog returns <code>false</code> and remains in ERROR state.

In case both of the defined WatchDogs are in ERROR state, the Rule is triggered which then restarts Output 1.

===WatchDogs definition===

WatchDog name: '''CR06_WDT_1'''

<nowiki>
{
"target": "192.168.1.51",
"pingInterval": 30,
"timeout": 5,
"maxTimeouts": 5,
"timeToReboot": 120,
"maxRestarts": -1
}</nowiki>

WatchDog name: '''CR06_WDT_2'''

<nowiki>
{
"target": "192.168.1.52",
"pingInterval": 60,
"timeout": 5,
"maxTimeouts": 5,
"timeToReboot": 120,
"maxRestarts": -1
}</nowiki>

===Rule definition===

Rule name: '''CR06_RULE'''

<nowiki>
{
"conditions": {
"operator": "AND",
"WDT/CR06_WDT_1/FAIL": true,
"WDT/CR06_WDT_2/FAIL": true
},
"actions": {
"OUTPUTS/1/ACTION": 2
}
}</nowiki>

== CR07 - Synchronized outputs states during working hours ==
Rule keeps track of first output state and when it changes, it switches output 2 to the same state. However, we want this synchronization only to work during working hours. We define the time with Schedule functionality and use it as a filter (mask) in Rules. Schedule can be defined manually or imported as a configuration file.

===Schedule definition===

Schedule name: '''CR07_SCHEDULE'''

[[File:NR07_Schedule.png|NR070 Schedule]]

===Rule definition===

Rule name: '''CR07_RULE'''

<nowiki>
{
"conditions": {
"OUTPUTS/1/STATE": "on"
},
"filters": {
"SCHEDULE/CR07_SCHEDULE/ACTIVE": true
},
"actions": {
"OUTPUTS/2/ACTION": "${COND_RESULT}"
}
}</nowiki>

== CR08 - Load Watchdog -> Turn output ON after period of time ==

In this example we want to measure load on output 1 and indicate when the power is abnormally low for a period of time by switching device on Output 2 ON (could be control light, sound alarm etc.).

In PAB we define indication for low power usage (1-20W) that is measured for period of 30 minutes (1800 seconds).
In Rule we define switching Output 2 = ON (ACTION 1 = TURN ON) based on fulfilled PAB condition. This set up counts with human interaction after the Rule action gets processed. (e.g. restarting/replacing device on Output 1 and turning Output 2 OFF).
It is possible to alter this behavior in such a way that the control light (Output 2) turns automatically OFF when load on Output 1 returns to standard values, i.e. higher than 20W (device gets repaired/replaced) or drops to 0W (device was removed or Output 1 turned OFF). This setup is defined in Rule '''NR08_ALT'''

===PAB definition===

PAB name: '''CR08_PAB'''
<nowiki>
{
"type": "RANGE",
"source": "OUTPUTS/1/LOAD",
"lowerBound": 1,
"upperBound": 20,
"timeHysteresis": 1800
}</nowiki>

===Rule definition===

Rule name: '''CR08_RULE'''

<nowiki>
{
"conditions": {
"PAB/CR08_PAB/IN": true
},
"actions": {
"OUTPUTS/2/ACTION": 1
}
}</nowiki>

Rule name: '''CR08_RULE_ALT'''

<nowiki>
{
"conditions": {
"PAB/CR08_PAB/IN": true
},
"actions": {
"OUTPUTS/2/ACTION": "${COND_RESULT}"
}
}</nowiki>

== CR09 - Digital Inputs with Schedule ==

Examples shows usage when we want to detect switching of Digital Input to ON state (1) but to (not) react only during specified hours (e.g. outside of working hours).
Reaction hours are defined with Schedule functionality. Schedule can be defined manually or imported as a configuration file.

===Schedule definition===

Schedule name: '''CR09_SCHEDULE'''

===Rule definition===

Rule name: '''CR09_RULE'''

<nowiki>
{
"conditions": {
"INPUTS/1/STATE": "on"
},
"filters": {
"SCHEDULE/CR09_SCHEDULE/ACTIVE": false
},
"actions": {
"OUTPUTS/1/ACTION": 2
}
}</nowiki>

== CR10 - TURN OFF Output 1 before midnight ==
Rule in a combination with Schedule can be used to ensure a specified output will be turned off at the end of the day (or any other time).
Schedule in this application is '''NOT''' assigned to the output and acts only as a "trigger" for launching the Rule action.

===Schedule definition===

Schedule name: '''off_before_midnight'''

Schedule configuration: Schedule is configured to have '''intervals every day from 23:59 to 24:00'''. In this configuration, the output turns of at 23:59.

[[File:cr10_schedule.png|CR10 Schedule]]

===Rule definition===

Rule name: '''CR10_RULE'''
<nowiki>
{
"conditions": {
"SCHEDULE/off_before_midnight/ACTIVE": true
},
"filters": {
"OUTPUTS/1/STATE": "on"
},
"actions": {
"OUTPUTS/1/ACTION": 0
}
}</nowiki>

== CR11 - Total load (8QS)==
CR11_PAB

<nowiki>
{
"type": "RANGE",
"source": "OUTPUTS/TOTAL/LOAD",
"lowerBound": 30,
"upperBound": 100,
"timeHysteresis": 3
}</nowiki>

<nowiki>
{
"conditions": {
"operator": "OR",
"PAB/total_outputs/IN": true
},
"actions": {
"OUTPUTS/1/ACTION": 4,
"CLOUD/OUTPUT/1/ALARM": 1
}
}</nowiki>

== CR12 - Negative load ==
CR12_PAB

<nowiki>
{
"type": "RANGE",
"source": "OUTPUTS/1/LOAD",
"lowerBound": -400,
"upperBound": 0,
"timeHysteresis": 2
}</nowiki>

<nowiki>
{
"conditions": {
"PAB/negative/IN": true
},
"actions": {
"OUTPUTS/3/ACTION": 4,
"OUTPUTS/4/ACTION": 4
}
}</nowiki>

== CR13 - Actions based on daylight <code>FW 4.0.0+</code>==
Turns output ON/OFF based on sunrise/sunset times of set location.
In this example, output 1 gets turned on one hour before (-60 minutes) sunrise and turns off one hour (60 minutes) after sunset. Location is se for NETIO Products headquarters (U pily 103, Prague, CZ). Elevation is set as 247 meters, above sea level.

=== PAB definition ===
PAB name: '''CR13_PAB'''

<nowiki>
{
"type": "DAYLIGHT",
"longitude": "14.4129433E",
"latitude": "50.0058144N",
"altitude": 247,
"sunriseDelay": -60,
"sunsetDelay": 60
}
</nowiki>

=== Rule definition ===
Rule name: '''CR13_RULE'''

<nowiki>
{
"conditions": {
"PAB/CR13_PAB/DAY": true
},
"actions": {
"OUTPUTS/1/ACTION": "${COND_RESULT}"
}
}
</nowiki>

== CR14 - Actions based on Power-UP <code>FW 4.0.0+</code>==

This example describes rule that evaluates after device start-up. Generally, there are 2 options for setting up conditions:
* SYSTEM/DEVICE_POWER_UP - device boot after power-cut

Condition in rule description below reacts to device boot after power-cut. When device first starts after regaining power, it sends alarm to output 1 in NETIO Cloud service.

=== Rule definition ===
Rule name: '''CR14_RULE'''

<nowiki>
{
"conditions": {
"SYSTEM/DEVICE_POWER_UP": true
},
"actions": {
"CLOUD/OUTPUT/1/ALARM": "${COND_RESULT}"
}
}
</nowiki>

== CR15 - Sunrise/sunset addaptive schedule with deep night off <code>FW 4.0.1+</code>==
Control output ON/OFF based on sunrise/sunset times of set location and combine it with standard schedule using rules.
In this example, output 1 gets turned on every day at 6:00 and switch off 30 minutes after sunrise and gets on again 30 minutes before sunset and turns off at midnight. This is an example of combination PAB output with standard schedule and mask the result of PAB with intervals defined in schedule.

=== 1. Configure schedule ===
Create a schedule with name "christmas_off" and create intervals 00:00 to 06:00 every day.
[[File:CR15 schedule christmas off.png]]

=== 2. Create sunrise/sunset PAB ===

Following PAB will have <code>true</code> result during the day between sunrise with 30 minutes delay and 30 minutes before sunset set for location of NETIO Products headquarters (U pily 103, Prague, CZ). Elevation is set as 247 meters, above sea level. This result will be used in condition in rules to detect sunrise and sunset.

PAB name: '''daylight'''

<nowiki>
{
"type": "DAYLIGHT",
"longitude": "14.4129433E",
"latitude": "50.0058144N",
"altitude": 247,
"sunriseDelay": 30,
"sunsetDelay": -30
}
</nowiki>

=== 3. Create rule for output ON ===

=== 4. Create rule for output OFF ===

=== PAB definition ===
PAB name: '''CR13_PAB'''

<nowiki>
{
"type": "DAYLIGHT",
"longitude": "14.4129433E",
"latitude": "50.0058144N",
"altitude": 247,
"sunriseDelay": -60,
"sunsetDelay": 60
}
</nowiki>

=== Rule definition ===
Rule name: '''CR13_RULE'''

<nowiki>
{
"conditions": {
"PAB/CR13_PAB/DAY": true
},
"actions": {
"OUTPUTS/1/ACTION": "${COND_RESULT}"
}
}
</nowiki>

File:CR15 schedule christmas off.png

2023-11-29T21:09:23Z

Bbakala:

Rules Complete Examples

2023-11-29T21:08:29Z

Bbakala:

The concept of NETIO Conditions (PAB & WatchDog) & Rules is a set of prepared detections (Conditions) and Rules that act upon them. They are implemented directly in NETIO PDU devices.

== CR01 - WatchDog (ping) to 1 IP address | default in FW 3.2.3 ==
The WatchDog functionality is used to monitor connectivity to specified IP address (or URL) by sending PING request to it.

The ping in this example is sent every 60s and waits 5s for the device to respond. If the ping fails, Watchdog returns <code>false</code> and restarts (ACTION: 2 = SHORT OFF) device connected to first output. After restart, it waits 120 seconds and starts monitoring again. If the device does not respond, WatchDog remains in ERROR state until next successful ping.

===WatchDog definition===

WatchDog name: '''CR01_WDT'''

<nowiki>
{
"target": "192.168.1.5",
"pingInterval": 60,
"timeout": 5,
"maxTimeouts": 0,
"timeToReboot": 120,
"maxRestarts": -1
}</nowiki>

===Rule definition===

Rule name: '''CR01_RULE'''

<nowiki>
{
"conditions": {
"WDT/CR01_WDT/FAIL": true
},
"actions": {
"OUTPUTS/1/ACTION": 2
}
}</nowiki>

== CR02 - Digital Inputs (Push button to Toggle Outputs 1 and 2) | default in FW 3.2.3 ==

Rule is used for managing outputs in response to change of Digital Inputs (DI) state. Rule monitors state of first DI. When DI switches from OFF (0) to ON (1), Rule switches (toggles) Outputs 1 & 2 to their opposite states (ACTION 4 = TOGGLE).

===Rule definition===

Rule name: '''CR02_RULE'''

<nowiki>
{
"conditions": {
"INPUTS/1/STATE": "on"
},
"actions": {
"OUTPUTS/1/ACTION": 4,
"OUTPUTS/2/ACTION": 4
}
}</nowiki>

== CR03 - Load Watchdog (Restart device if it's more than 2 minutes in IDLE mode) | default in FW 3.2.3 ==
Rule monitors load (Watts) on Output 1. If the load is between 1-20W for at least 2 minutes, it restarts (ACTION 2 = SHORT OFF) the output.
Example uses PAB (Power Analysis Block) functionality to determine if measured value (load in our case) lies in given range for a period of time. When it does, defined Rule triggers device restart.

===PAB definition===

PAB name: '''CR03_PAB'''
<nowiki>
{
"type": "RANGE",
"source": "OUTPUTS/1/LOAD",
"lowerBound": 1,
"upperBound": 20,
"timeHysteresis": 120
}</nowiki>

===Rule definition===

Rule name: '''CR03_RULE'''

<nowiki>
{
"conditions": {
"PAB/CR03_PAB/IN": true
},
"actions": {
"OUTPUTS/1/ACTION": 2
}
}</nowiki>

== CR04 - Load Watchdog with alarm to Cloud ==
Rule monitors load (Watts) on Output 1. If the load is between 1-20W for at least 30 minutes, it restarts (ACTION 2 = SHORT OFF) the output. In addition, it triggers an alarm in NETIO Cloud, which sends a notification to specified email address.
This example needs a NETIO Cloud account with Premium version active for first output. There also has to be email notification enabled for the output.

Example uses PAB (Power Analysis Block) functionality to determine if measured value (load in our case) lies in given range for a period of time. When it does, defined Rule triggers device restart and sends alarm to Cloud.

===PAB definition===

PAB name: '''CR04_PAB'''

<nowiki>
{
"type": "RANGE",
"source": "OUTPUTS/1/LOAD",
"lowerBound": 1,
"upperBound": 20,
"timeHysteresis": 1800
}</nowiki>

===Rule definition===

Rule name: '''CR04_RULE'''

<nowiki>
{
"conditions": {
"PAB/CR04_PAB/IN": true
},
"actions": {
"OUTPUTS/1/ACTION": 2,
"CLOUD/OUTPUT/1/ALARM": "${COND_RESULT}"
}
}</nowiki>

== CR05 - Load Watchdog with zones (indicate OFF / IDLE / RUN mode by switched on output)==
Rule monitors load (Watts) on Output 1. Measured load is then classified to several zones defined with thresholds (limit values). Depending on the zone in which the measured load is currently located, different actions can be triggered. Load value has to be between defined threshold for at least 10seconds in order to be placed to respective zone.
Example is composed of one PAB that classifies the zones and three Rules for 3 separate actions. Actions do the following:
* Output 1 load lower than 1W: Output 2 = ON
* Output 1 load between 1-20W: Output 3 = ON
* Output 1 load between 20-200W: Output 4 = ON

===PAB definition===

PAB name: '''CR05_PAB'''

<nowiki>
{
"type": "ZONES",
"source": "OUTPUTS/2/CURRENT",
"thresholds": [
1,
20,
200
],
"timeHysteresis": 10
}</nowiki>

===Rules definitions===

Rule 1 name: '''CR05_RULE_1'''

<nowiki>
{
"conditions": {
"PAB/NR05_PAB/ZONE": 0
},
"actions": {
"OUTPUTS/2/ACTION": 1,
"OUTPUTS/3/ACTION": 0,
"OUTPUTS/4/ACTION": 0
}
}</nowiki>

Rule 2 name: '''CR05_RULE_2'''

<nowiki>
{
"conditions": {
"PAB/CR05_PAB/ZONE": 1
},
"actions": {
"OUTPUTS/2/ACTION": 0,
"OUTPUTS/3/ACTION": 1,
"OUTPUTS/4/ACTION": 0
}
}</nowiki>

Rule 3 name: '''CR05_RULE_3'''

<nowiki>
{
"conditions": {
"PAB/CR05_PAB/ZONE": 2
},
"actions": {
"OUTPUTS/2/ACTION": 0,
"OUTPUTS/3/ACTION": 0,
"OUTPUTS/4/ACTION": 1
}
}</nowiki>

== CR06 - WatchDog for 2 IPs (Verify IP connectivity outage with 2 IPs)==
The WatchDog functionality is used to monitor connectivity to specified IP address (or URL) by sending PING request to it.

In this example, we monitor two IPs and we want to restart device connected to Output 1 if none of the addresses reply.
The ping for both IPs is sent every 30s and waits 5s for device to respond. There are 5 consecutive timeouts tolerated before the ping is considered as failed. When the ping fails, Watchdog returns <code>false</code> and remains in ERROR state.

In case both of the defined WatchDogs are in ERROR state, the Rule is triggered which then restarts Output 1.

===WatchDogs definition===

WatchDog name: '''CR06_WDT_1'''

<nowiki>
{
"target": "192.168.1.51",
"pingInterval": 30,
"timeout": 5,
"maxTimeouts": 5,
"timeToReboot": 120,
"maxRestarts": -1
}</nowiki>

WatchDog name: '''CR06_WDT_2'''

<nowiki>
{
"target": "192.168.1.52",
"pingInterval": 60,
"timeout": 5,
"maxTimeouts": 5,
"timeToReboot": 120,
"maxRestarts": -1
}</nowiki>

===Rule definition===

Rule name: '''CR06_RULE'''

<nowiki>
{
"conditions": {
"operator": "AND",
"WDT/CR06_WDT_1/FAIL": true,
"WDT/CR06_WDT_2/FAIL": true
},
"actions": {
"OUTPUTS/1/ACTION": 2
}
}</nowiki>

== CR07 - Synchronized outputs states during working hours ==
Rule keeps track of first output state and when it changes, it switches output 2 to the same state. However, we want this synchronization only to work during working hours. We define the time with Schedule functionality and use it as a filter (mask) in Rules. Schedule can be defined manually or imported as a configuration file.

===Schedule definition===

Schedule name: '''CR07_SCHEDULE'''

[[File:NR07_Schedule.png|NR070 Schedule]]

===Rule definition===

Rule name: '''CR07_RULE'''

<nowiki>
{
"conditions": {
"OUTPUTS/1/STATE": "on"
},
"filters": {
"SCHEDULE/CR07_SCHEDULE/ACTIVE": true
},
"actions": {
"OUTPUTS/2/ACTION": "${COND_RESULT}"
}
}</nowiki>

== CR08 - Load Watchdog -> Turn output ON after period of time ==

In this example we want to measure load on output 1 and indicate when the power is abnormally low for a period of time by switching device on Output 2 ON (could be control light, sound alarm etc.).

In PAB we define indication for low power usage (1-20W) that is measured for period of 30 minutes (1800 seconds).
In Rule we define switching Output 2 = ON (ACTION 1 = TURN ON) based on fulfilled PAB condition. This set up counts with human interaction after the Rule action gets processed. (e.g. restarting/replacing device on Output 1 and turning Output 2 OFF).
It is possible to alter this behavior in such a way that the control light (Output 2) turns automatically OFF when load on Output 1 returns to standard values, i.e. higher than 20W (device gets repaired/replaced) or drops to 0W (device was removed or Output 1 turned OFF). This setup is defined in Rule '''NR08_ALT'''

===PAB definition===

PAB name: '''CR08_PAB'''
<nowiki>
{
"type": "RANGE",
"source": "OUTPUTS/1/LOAD",
"lowerBound": 1,
"upperBound": 20,
"timeHysteresis": 1800
}</nowiki>

===Rule definition===

Rule name: '''CR08_RULE'''

<nowiki>
{
"conditions": {
"PAB/CR08_PAB/IN": true
},
"actions": {
"OUTPUTS/2/ACTION": 1
}
}</nowiki>

Rule name: '''CR08_RULE_ALT'''

<nowiki>
{
"conditions": {
"PAB/CR08_PAB/IN": true
},
"actions": {
"OUTPUTS/2/ACTION": "${COND_RESULT}"
}
}</nowiki>

== CR09 - Digital Inputs with Schedule ==

Examples shows usage when we want to detect switching of Digital Input to ON state (1) but to (not) react only during specified hours (e.g. outside of working hours).
Reaction hours are defined with Schedule functionality. Schedule can be defined manually or imported as a configuration file.

===Schedule definition===

Schedule name: '''CR09_SCHEDULE'''

===Rule definition===

Rule name: '''CR09_RULE'''

<nowiki>
{
"conditions": {
"INPUTS/1/STATE": "on"
},
"filters": {
"SCHEDULE/CR09_SCHEDULE/ACTIVE": false
},
"actions": {
"OUTPUTS/1/ACTION": 2
}
}</nowiki>

== CR10 - TURN OFF Output 1 before midnight ==
Rule in a combination with Schedule can be used to ensure a specified output will be turned off at the end of the day (or any other time).
Schedule in this application is '''NOT''' assigned to the output and acts only as a "trigger" for launching the Rule action.

===Schedule definition===

Schedule name: '''off_before_midnight'''

Schedule configuration: Schedule is configured to have '''intervals every day from 23:59 to 24:00'''. In this configuration, the output turns of at 23:59.

[[File:cr10_schedule.png|CR10 Schedule]]

===Rule definition===

Rule name: '''CR10_RULE'''
<nowiki>
{
"conditions": {
"SCHEDULE/off_before_midnight/ACTIVE": true
},
"filters": {
"OUTPUTS/1/STATE": "on"
},
"actions": {
"OUTPUTS/1/ACTION": 0
}
}</nowiki>

== CR11 - Total load (8QS)==
CR11_PAB

<nowiki>
{
"type": "RANGE",
"source": "OUTPUTS/TOTAL/LOAD",
"lowerBound": 30,
"upperBound": 100,
"timeHysteresis": 3
}</nowiki>

<nowiki>
{
"conditions": {
"operator": "OR",
"PAB/total_outputs/IN": true
},
"actions": {
"OUTPUTS/1/ACTION": 4,
"CLOUD/OUTPUT/1/ALARM": 1
}
}</nowiki>

== CR12 - Negative load ==
CR12_PAB

<nowiki>
{
"type": "RANGE",
"source": "OUTPUTS/1/LOAD",
"lowerBound": -400,
"upperBound": 0,
"timeHysteresis": 2
}</nowiki>

<nowiki>
{
"conditions": {
"PAB/negative/IN": true
},
"actions": {
"OUTPUTS/3/ACTION": 4,
"OUTPUTS/4/ACTION": 4
}
}</nowiki>

== CR13 - Actions based on daylight <code>FW 4.0.0+</code>==
Turns output ON/OFF based on sunrise/sunset times of set location.
In this example, output 1 gets turned on one hour before (-60 minutes) sunrise and turns off one hour (60 minutes) after sunset. Location is se for NETIO Products headquarters (U pily 103, Prague, CZ). Elevation is set as 247 meters, above sea level.

=== PAB definition ===
PAB name: '''CR13_PAB'''

<nowiki>
{
"type": "DAYLIGHT",
"longitude": "14.4129433E",
"latitude": "50.0058144N",
"altitude": 247,
"sunriseDelay": -60,
"sunsetDelay": 60
}
</nowiki>

=== Rule definition ===
Rule name: '''CR13_RULE'''

<nowiki>
{
"conditions": {
"PAB/CR13_PAB/DAY": true
},
"actions": {
"OUTPUTS/1/ACTION": "${COND_RESULT}"
}
}
</nowiki>

== CR14 - Actions based on Power-UP <code>FW 4.0.0+</code>==

This example describes rule that evaluates after device start-up. Generally, there are 2 options for setting up conditions:
* SYSTEM/DEVICE_POWER_UP - device boot after power-cut

Condition in rule description below reacts to device boot after power-cut. When device first starts after regaining power, it sends alarm to output 1 in NETIO Cloud service.

=== Rule definition ===
Rule name: '''CR14_RULE'''

<nowiki>
{
"conditions": {
"SYSTEM/DEVICE_POWER_UP": true
},
"actions": {
"CLOUD/OUTPUT/1/ALARM": "${COND_RESULT}"
}
}
</nowiki>

== CR15 - Sunrise/sunset addaptive schedule with deep night off<code>FW 4.0.1+</code>==
Control output ON/OFF based on sunrise/sunset times of set location and combine it with standard schedule using rules.
In this example, output 1 gets turned on every day at 6:00 and switch off 30 minutes after sunrise and gets on again 30 minutes before sunset and turns off at midnight. This is an example of combination PAB output with standard schedule and mask the result of PAB with intervals defined in schedule.

=== To get this working 4 steps of configuration as to be done ===
==== 1. Configure schedule ====
Create a schedule with name "christmas_off" and create intervals 00:00 to 06:00 every day.

one hour before (-60 minutes) sunrise and turns off one hour (60 minutes) after sunset. Location is se for NETIO Products headquarters (U pily 103, Prague, CZ). Elevation is set as 247 meters, above sea level.

=== PAB definition ===
PAB name: '''CR13_PAB'''

<nowiki>
{
"type": "DAYLIGHT",
"longitude": "14.4129433E",
"latitude": "50.0058144N",
"altitude": 247,
"sunriseDelay": -60,
"sunsetDelay": 60
}
</nowiki>

=== Rule definition ===
Rule name: '''CR13_RULE'''

<nowiki>
{
"conditions": {
"PAB/CR13_PAB/DAY": true
},
"actions": {
"OUTPUTS/1/ACTION": "${COND_RESULT}"
}
}
</nowiki>

Rules

2023-08-28T20:12:36Z

Bbakala: /* CONDITION */

Each Rule define the follow-up actions based on current DI / [https://wiki.netio-products.com/index.php?title=PAB '''PAB''']/ [https://wiki.netio-products.com/index.php?title=Watchdog '''WatchDog'''] function state. There can be several Rules executed based on one PAB function (switch output if Current > 1000 mA + Send Alert to NETIO Cloud IF Current > 500 mA). One Rule can be executed based on combination of several PAB / WatchDog states.

'''Rules examples are available on page:''' https://wiki.netio-products.com/index.php?title=Rules_Complete_Examples

== CONDITION ==
Rule conditions define when the action part of each Rule is executed. There can be multiple conditions for one Rule.
In order to execute the action, all conditions have to be valid (AND operator) / at least one of the conditions have to be valid (OR operator).
<code>bootDelay</code> parameter <code>FW 4.0.0+</code> can be used to delay rule evaluation after power up (or internal periodic restart). This is useful for example for delay condition and alerts evaluation after PAB blocks are stabilized. (e.g. hysteresis or some delays). <code>bootDelay</code> parameter <code>FW 4.0.0+</code> is specified in seconds [s]

Example:
{
"conditions": {
"bootDelay": 20,
"operator": "OR",
"WDT/test2/FAIL": true,
"INPUTS/1/STATE": "off"
},
"actions": {
"OUTPUTS/1/ACTION": 4
}
}

=== Available forms of conditions ===
* <code>"PAB/PAB1_1/IN": true</code> = <code>PAB1_1</code> is in specified interval
* <code>"PAB/PAB_ZONE_1/ZONE": 1</code> = <code>PAB_ZONE_1</code> is in zone 1
* <code>"PAB/CR13_PAB/DAY": true</code> = daylight for current time on defined location (for use with DAYLIGHT-type PAB)
* <code>"WDT/WATCHDOG_1/FAIL": true</code> = <code>WATCHDOG_1</code> is in ERROR state
* <code>"OUTPUTS/1/STATE": "on"</code> = Output 1 is currently ON (1)
* <code>"INPUTS/1/STATE": "off"</code> = DI1 is currently OFF (0)
* <code>"SYSTEM/DEVICE_POWER_UP": true</code> = device boot after power-cut (external power outage, lower-level system (MCU) firmware update)<code>FW 4.0.0+</code>
* <code>"SYSTEM/DEVICE_BOOT": true</code> = device boot after soft restart (internal watchdog or periodic restart) - no Power Outage, state of outputs not changed<code>FW 4.0.0+</code>
* <code>"NETWORK/STATE": "down"</code> = indicates network connection status, states: "up" - device is connected, "down" - device is not connected<code>FW 4.0.0+</code>
* <code>"NETWORK/ETHERNET/STATE": "down"</code> = indicates network connection status, states: "up" - device is connected, "down" - device is not connected<code>FW 4.0.0+</code>
* <code>"NETWORK/WIFI/STATE": "down"</code> = indicates network connection status, states: "up" - device is connected, "down" - device is not connected<code>FW 4.0.0+</code>

== FILTER (mask)==
The filter field specifies when the Rule is active. It acts as a mask If filter in certain time is not true, the action wont be executed even when conditions are fulfilled. Multiple filters can be set for one rule. For the rule to be active all filters must be true.

Above that the FILTER can be applied (scheduler, DI (Digital Input) or DO (Output) state).

=== Available forms of filters ===
* <code>"SCHEDULE/TestSchedule/ACTIVE": true</code> = <code>TestSchedule</code> is active
* <code>"OUTPUTS/1/STATE":"on"</code> = Output 1 is ON

== ACTION ==
ACTIONS part in the Rule contains list of several actions when condition(s) + filter(s) are valid.

The actions can change output states (turn OFF, turn ON, toggle, etc.) or trigger an Alarm state in NETIO Cloud.
There is one Alarm state reserved per each one output in the NETIO Cloud premium (only).
You can verify your configuration and check sending of the Output Alarm in the Device Log.

=== Available forms of actions ===
* <code>"OUTPUTS/1/ACTION": 0</code> = Turn OFF Output 1
* <code>"OUTPUTS/6/ACTION": 2</code> = Short OFF Output 6
* <code>"CLOUD/OUTPUT/1/ALARM": "${COND_RESULT}"</code> = Set condition output value to the alarm (Turns the alarm ON or OFF based on condition evaluation)

''Note: The variable <code>${COND_RESULT}</code> contains output value of the given condition. It takes values 0 (condition not met) or 1 (condition met). It can be used for dynamic switching the alarm in Cloud ON/OFF depending on current state of the PAB.''

=== Standard output actions per each output ===
* 0 = TURN OFF
* 1 = TURN ON
* 2 = SHORT OFF
* 3 = SHORT ON
* 4 = TOGGLE - Changes the status from ON to OFF and vice versa
* 5 = NOTHING (placeholder, DO NOT USE)

== Structure ==

{| class="wikitable"
|-
! Variable
! Value
! Description
|-
| conditions
| Eg: `"PAB/PAB1_1/IN": true`
| Conditions definition. Relationship between conditions is defined by <code>operator</code> (AND/OR)
|-
| operator
| AND/OR
| Optional. Specifies relationship between conditions. <code>AND</code> = all conditions must apply at the same time. <code>OR</code> = at least one condition must apply. If missing, defaults to <code>OR</code>
|-
| filters
| Eg: <code>"SCHEDULE/MY_SCHEDULE/ACTIVE": true<code/>
| Filter definition. For multiple filter conditions, the relationship between them is always <code>AND</code>
|-
| actions
| Eg: <code>"CLOUD/OUTPUT/1/ALARM": "${COND_RESULT}"</code>
| Actions definition. All actions defined here will be triggered when conditions (and filters) are met
|}

Condition names are based on user-specified names and their types:
* For PABs, the name has structure: <code>PAB/pab_name/pab_output_value</code> (TRUE/FALSE or int)
* For WatchDogs, the name has structure: <code>WDT/watchdog_name/FAIL</code>

== Sequence <code>FW 4.0.0+</code> ==

Sequences bring extended usability to ACTIONS. In addition to basic actions that are triggered right after certain condition (conditions) are met, sequence can be defined to enable repetitive actions.

=== Configuration variables ===

{| class="wikitable"
|-
! Variable
! Value
! Description
|-
| repeat
| int (0 to 1-MAX_INT) / true
| How many times should the sequence repeat. Set <code>0</code> or <code>true</code> for indefinitely (can only be turned off by disabling the rule).
|-
| actions
|
| Standard actions as defined in section [[#ACTION| ACTION]]
|-
| delay
| int [ms] in multiples of 100ms
| '''May''' be set along with actions to be executed. Defines time the sequence waits '''after''' performing the action. The value is rounded up to hundreds of miliseconds (e.g. 85ms -> 100ms, 235ms -> 300ms).
|}

=== Example ===
This example triggers one-time action along with sequence of other actions and repeats 10-times after meeting certain condition.
:'''Condition''': WatchDog '''CR01_WDT''' fails (receives timeout from defined address)
:'''One-time action''': Restart output No. 2 (action 2 = short off/restart)
:''' Sequence ''': Following steps repeat 10-times
:# Turn output No. 1 ON
:# Wait 10s
:# Turn output No. 1 OFF
:# Wait 2s
:# Repeat

<nowiki>
{
"conditions": {
"WDT/CR01_WDT/FAIL": true
},
"actions": {
"OUTPUTS/1/ACTION": 2,
"sequence":{
"repeat": 10,
"actions":[
{"OUTPUTS/1/ACTION": 1, "delay":10000},
{"OUTPUTS/1/ACTION": 0, "delay":2000}
]
}
}
}</nowiki>

Watchdog

2023-06-19T18:01:10Z

Bbakala:

[[File:4.0.0-watchdog.png|thumb|Watchdog diagram]]

Watchdog is a function periodically pinging to one defined IP address or URL. It's periodically checking reply from defined IP device by ping (ICMP). You can monitor physical presence of the IP device or Internet connectivity. You can use several WatchDog functions in parallel.

Based on each Watchdog state one or several RULEs can be executed. Each [https://wiki.netio-products.com/index.php?title=Rules '''Rule'''] can perform several actions (Set Output, Short Off (restart) output, Toggle output or send Alarm state to the NETIO Cloud service. Based on this Alarm state can NETIO Cloud send email to defined recipient. All Watchdogs are listed in the JSON protocol wit their current states. It can be used by 3rd party software.

Each Watchdog function state is the <code>FAIL</code> variable.
* Watchdog '''Fail = FALSE''' = ping answer is '''OK'''
* Watchdog '''Fail = TRUE''' = ping answer '''not received'''

<code>FW 4.0.0+</code>Once network connection is not active the watchdog is not in operation. To detect these stater use Connectivity events in RULES.

== Structure ==

{| class="wikitable"
|-
! Variable
! Value
! Description
|-
| target
| IP / URL
| Monitored address
|-
| pingInterval
| int
| '''[s]''' Time interval between pings
|-
| timeout
| int
| '''[s]''' Time waiting for answer
|-
| maxTimeouts
| int
| Number of failed pings required to evaluate to <code>FAIL=TRUE</code>
|-
| timeToReboot
| int
| '''[s]''' Time the Watchdog waits after announcing an error condition before starting a new cycle
|-
| maxRestarts
| int
| Maximum number of restarts when an error condition is declared. After this limit is reached, the WatchDog remains in an <code>FAIL=TRUE</code> state until the next successful ping.
If set to 0, WatchDog will restart output (trigger rule) after each FAIL=TRUE is declared and not only if FAIL status is changed (This can cause indefinite restarts when the ping remains unsuccessful).

If set to -1, WatchDog will restart output (trigger rule) only once and then remains in FAIL=TRUE state until next successful ping.
|-
| startDelay
| int
| Starting delay in seconds at watchdog startup.(Enable or device power up)<code>FW 4.0.0+</code>
|}

Example:
{
"target": "192.168.101.130",
"pingInterval": 5,
"timeout": 1,
"maxTimeouts": 2,
"timeToReboot": 10,
"maxRestarts": -1,
"startDelay": 0
}

Watchdog

2023-06-19T17:37:53Z

Bbakala: /* Structure */

[[File:4.0.0-watchdog.png|thumb|Watchdog diagram]]

Watchdog is a function periodically pinging to one defined IP address or URL. It's periodically checking reply from defined IP device by ping (ICMP). You can monitor physical presence of the IP device or Internet connectivity. You can use several WatchDog functions in parallel.

Based on each Watchdog state one or several RULEs can be executed. Each [https://wiki.netio-products.com/index.php?title=Rules '''Rule'''] can perform several actions (Set Output, Short Off (restart) output, Toggle output or send Alarm state to the NETIO Cloud service. Based on this Alarm state can NETIO Cloud send email to defined recipient. All Watchdogs are listed in the JSON protocol wit their current states. It can be used by 3rd party software.

Each Watchdog function state is the <code>FAIL</code> variable.
* Watchdog '''Fail = FALSE''' = ping answer is '''OK'''
* Watchdog '''Fail = TRUE''' = ping answer '''not received'''

Once network connection is not active the watchdog is not in operation. To detect these stater use Connectivity events in RULES.

== Structure ==

{| class="wikitable"
|-
! Variable
! Value
! Description
|-
| target
| IP / URL
| Monitored address
|-
| pingInterval
| int
| '''[s]''' Time interval between pings
|-
| timeout
| int
| '''[s]''' Time waiting for answer
|-
| maxTimeouts
| int
| Number of failed pings required to evaluate to <code>FAIL=TRUE</code>
|-
| timeToReboot
| int
| '''[s]''' Time the Watchdog waits after announcing an error condition before starting a new cycle
|-
| maxRestarts
| int
| Maximum number of restarts when an error condition is declared. After this limit is reached, the WatchDog remains in an <code>FAIL=TRUE</code> state until the next successful ping.
If set to 0, WatchDog will restart output (trigger rule) after each FAIL=TRUE is declared and not only if FAIL status is changed (This can cause indefinite restarts when the ping remains unsuccessful).

If set to -1, WatchDog will restart output (trigger rule) only once and then remains in FAIL=TRUE state until next successful ping.
|-
| startDelay
| int
| Starting delay in seconds at watchdog startup.(Enable or device power up)<code>FW 4.0.0+</code>
|}

Example:
{
"target": "192.168.101.130",
"pingInterval": 5,
"timeout": 1,
"maxTimeouts": 2,
"timeToReboot": 10,
"maxRestarts": -1,
"startDelay": 0
}

Watchdog

2023-06-19T17:34:52Z

Bbakala:

[[File:4.0.0-watchdog.png|thumb|Watchdog diagram]]

Watchdog is a function periodically pinging to one defined IP address or URL. It's periodically checking reply from defined IP device by ping (ICMP). You can monitor physical presence of the IP device or Internet connectivity. You can use several WatchDog functions in parallel.

Based on each Watchdog state one or several RULEs can be executed. Each [https://wiki.netio-products.com/index.php?title=Rules '''Rule'''] can perform several actions (Set Output, Short Off (restart) output, Toggle output or send Alarm state to the NETIO Cloud service. Based on this Alarm state can NETIO Cloud send email to defined recipient. All Watchdogs are listed in the JSON protocol wit their current states. It can be used by 3rd party software.

Each Watchdog function state is the <code>FAIL</code> variable.
* Watchdog '''Fail = FALSE''' = ping answer is '''OK'''
* Watchdog '''Fail = TRUE''' = ping answer '''not received'''

Once network connection is not active the watchdog is not in operation. To detect these stater use Connectivity events in RULES.

== Structure ==

{| class="wikitable"
|-
! Variable
! Value
! Description
|-
| target
| IP / URL
| Monitored address
|-
| pingInterval
| int
| '''[s]''' Time interval between pings
|-
| timeout
| int
| '''[s]''' Time waiting for answer
|-
| maxTimeouts
| int
| Number of failed pings required to evaluate to <code>FAIL=TRUE</code>
|-
| timeToReboot
| int
| '''[s]''' Time the Watchdog waits after announcing an error condition before starting a new cycle
|-
| maxRestarts
| int
| Maximum number of restarts when an error condition is declared. After this limit is reached, the WatchDog remains in an <code>FAIL=TRUE</code> state until the next successful ping.
If set to 0, WatchDog will restart after each FAIL=TRUE is declared (This can cause indefinite restarts when the ping remains unsuccessful).

If set to -1, WatchDog will NOT restart itself again. E.g. it remains in FAIL=TRUE state after it is declared.
|-
| startDelay
| int
| Starting delay in seconds at watchdog startup.(Enable or device power up)<code>FW 4.0.0+</code>
|}

Example:
{
"target": "192.168.101.130",
"pingInterval": 5,
"timeout": 1,
"maxTimeouts": 2,
"timeToReboot": 10,
"maxRestarts": -1,
"startDelay": 0
}

Watchdog

2023-06-19T17:33:50Z

Bbakala:

[[File:4.0.0-watchdog.png|thumb|Watchdog diagram]]

Watchdog is a function periodically pinging to one defined IP address or URL. It's periodically checking reply from defined IP device by ping (ICMP). You can monitor physical presence of the IP device or Internet connectivity. You can use several WatchDog functions in parallel.

Based on each Watchdog state one or several RULEs can be executed. Each [https://wiki.netio-products.com/index.php?title=Rules '''Rule'''] can perform several actions (Set Output, Short Off (restart) output, Toggle output or send Alarm state to the NETIO Cloud service. Based on this Alarm state can NETIO Cloud send email to defined recipient. All Watchdogs are listed in the JSON protocol wit their current states. It can be used by 3rd party software.

Each Watchdog function state is the <code>FAIL</code> variable.
* Watchdog '''Fail = FALSE''' = ping answer is '''OK'''
* Watchdog '''Fail = TRUE''' = ping answer '''not received'''

== Structure ==

{| class="wikitable"
|-
! Variable
! Value
! Description
|-
| target
| IP / URL
| Monitored address
|-
| pingInterval
| int
| '''[s]''' Time interval between pings
|-
| timeout
| int
| '''[s]''' Time waiting for answer
|-
| maxTimeouts
| int
| Number of failed pings required to evaluate to <code>FAIL=TRUE</code>
|-
| timeToReboot
| int
| '''[s]''' Time the Watchdog waits after announcing an error condition before starting a new cycle
|-
| maxRestarts
| int
| Maximum number of restarts when an error condition is declared. After this limit is reached, the WatchDog remains in an <code>FAIL=TRUE</code> state until the next successful ping.
If set to 0, WatchDog will restart after each FAIL=TRUE is declared (This can cause indefinite restarts when the ping remains unsuccessful).

If set to -1, WatchDog will NOT restart itself again. E.g. it remains in FAIL=TRUE state after it is declared.
|-
| startDelay
| int
| Starting delay in seconds at watchdog startup.(Enable or device power up)<code>FW 4.0.0+</code>
|}

Example:
{
"target": "192.168.101.130",
"pingInterval": 5,
"timeout": 1,
"maxTimeouts": 2,
"timeToReboot": 10,
"maxRestarts": -1,
"startDelay": 0
}

File:4.0.0-watchdog.png

2023-06-19T17:32:53Z

Bbakala: NETIO Watchdog functional diagram

== Summary ==
NETIO Watchdog functional diagram

Rules

2023-06-19T17:19:44Z

Bbakala: /* CONDITION */

Each Rule define the follow-up actions based on current DI / [https://wiki.netio-products.com/index.php?title=PAB '''PAB''']/ [https://wiki.netio-products.com/index.php?title=Watchdog '''WatchDog'''] function state. There can be several Rules executed based on one PAB function (switch output if Current > 1000 mA + Send Alert to NETIO Cloud IF Current > 500 mA). One Rule can be executed based on combination of several PAB / WatchDog states.

'''Rules examples are available on page:''' https://wiki.netio-products.com/index.php?title=Rules_Complete_Examples

== CONDITION ==
Rule conditions define when the action part of each Rule is executed. There can be multiple conditions for one Rule.
In order to execute the action, all conditions have to be valid (AND operator) / at least one of the conditions have to be valid (OR operator).

Example:
{
"conditions": {
"operator": "OR",
"WDT/test2/FAIL": true,
"INPUTS/1/STATE": "off"
},
"actions": {
"OUTPUTS/1/ACTION": 4
}
}

=== Available forms of conditions ===
* <code>"PAB/PAB1_1/IN": true</code> = <code>PAB1_1</code> is in specified interval
* <code>"PAB/PAB_ZONE_1/ZONE": 1</code> = <code>PAB_ZONE_1</code> is in zone 1
* <code>"PAB/CR13_PAB/DAY": true</code> = daylight for current time on defined location (for use with DAYLIGHT-type PAB)
* <code>"WDT/WATCHDOG_1/FAIL": true</code> = <code>WATCHDOG_1</code> is in ERROR state
* <code>"OUTPUTS/1/STATE": "on"</code> = Output 1 is currently ON (1)
* <code>"INPUTS/1/STATE": "off"</code> = DI1 is currently OFF (0)
* <code>"SYSTEM/DEVICE_POWER_UP": true</code> = device boot after power-cut (external power outage, lower-level system (MCU) firmware update)<code>FW 4.0.0+</code>
* <code>"SYSTEM/DEVICE_BOOT": true</code> = device boot after soft restart (internal watchdog or periodic restart) - no Power Outage, state of outputs not changed<code>FW 4.0.0+</code>
* <code>"NETWORK/STATE": "down"</code> = indicates network connection status, states: "up" - device is connected, "down" - device is not connected<code>FW 4.0.0+</code>
* <code>"NETWORK/ETHERNET/STATE": "down"</code> = indicates network connection status, states: "up" - device is connected, "down" - device is not connected<code>FW 4.0.0+</code>
* <code>"NETWORK/WIFI/STATE": "down"</code> = indicates network connection status, states: "up" - device is connected, "down" - device is not connected<code>FW 4.0.0+</code>

== FILTER (mask)==
The filter field specifies when the Rule is active. It acts as a mask If filter in certain time is not true, the action wont be executed even when conditions are fulfilled. Multiple filters can be set for one rule. For the rule to be active all filters must be true.

Above that the FILTER can be applied (scheduler, DI (Digital Input) or DO (Output) state).

=== Available forms of filters ===
* <code>"SCHEDULE/TestSchedule/ACTIVE": true</code> = <code>TestSchedule</code> is active
* <code>"OUTPUTS/1/STATE":"on"</code> = Output 1 is ON

== ACTION ==
ACTIONS part in the Rule contains list of several actions when condition(s) + filter(s) are valid.

The actions can change output states (turn OFF, turn ON, toggle, etc.) or trigger an Alarm state in NETIO Cloud.
There is one Alarm state reserved per each one output in the NETIO Cloud premium (only).
You can verify your configuration and check sending of the Output Alarm in the Device Log.

=== Available forms of actions ===
* <code>"OUTPUTS/1/ACTION": 0</code> = Turn OFF Output 1
* <code>"OUTPUTS/6/ACTION": 2</code> = Short OFF Output 6
* <code>"CLOUD/OUTPUT/1/ALARM": "${COND_RESULT}"</code> = Set condition output value to the alarm (Turns the alarm ON or OFF based on condition evaluation)

''Note: The variable <code>${COND_RESULT}</code> contains output value of the given condition. It takes values 0 (condition not met) or 1 (condition met). It can be used for dynamic switching the alarm in Cloud ON/OFF depending on current state of the PAB.''

=== Standard output actions per each output ===
* 0 = TURN OFF
* 1 = TURN ON
* 2 = SHORT OFF
* 3 = SHORT ON
* 4 = TOGGLE - Changes the status from ON to OFF and vice versa
* 5 = NOTHING (placeholder, DO NOT USE)

== Structure ==

{| class="wikitable"
|-
! Variable
! Value
! Description
|-
| conditions
| Eg: `"PAB/PAB1_1/IN": true`
| Conditions definition. Relationship between conditions is defined by <code>operator</code> (AND/OR)
|-
| operator
| AND/OR
| Optional. Specifies relationship between conditions. <code>AND</code> = all conditions must apply at the same time. <code>OR</code> = at least one condition must apply. If missing, defaults to <code>OR</code>
|-
| filters
| Eg: <code>"SCHEDULE/MY_SCHEDULE/ACTIVE": true<code/>
| Filter definition. For multiple filter conditions, the relationship between them is always <code>AND</code>
|-
| actions
| Eg: <code>"CLOUD/OUTPUT/1/ALARM": "${COND_RESULT}"</code>
| Actions definition. All actions defined here will be triggered when conditions (and filters) are met
|}

Condition names are based on user-specified names and their types:
* For PABs, the name has structure: <code>PAB/pab_name/pab_output_value</code> (TRUE/FALSE or int)
* For WatchDogs, the name has structure: <code>WDT/watchdog_name/FAIL</code>

== Sequence <code>FW 4.0.0+</code> ==

Sequences bring extended usability to ACTIONS. In addition to basic actions that are triggered right after certain condition (conditions) are met, sequence can be defined to enable repetitive actions.

=== Configuration variables ===

{| class="wikitable"
|-
! Variable
! Value
! Description
|-
| repeat
| int (0 to 1-MAX_INT) / true
| How many times should the sequence repeat. Set <code>0</code> or <code>true</code> for indefinitely (can only be turned off by disabling the rule).
|-
| actions
|
| Standard actions as defined in section [[#ACTION| ACTION]]
|-
| delay
| int [ms] in multiples of 100ms
| '''May''' be set along with actions to be executed. Defines time the sequence waits '''after''' performing the action. The value is rounded up to hundreds of miliseconds (e.g. 85ms -> 100ms, 235ms -> 300ms).
|}

=== Example ===
This example triggers one-time action along with sequence of other actions and repeats 10-times after meeting certain condition.
:'''Condition''': WatchDog '''CR01_WDT''' fails (receives timeout from defined address)
:'''One-time action''': Restart output No. 2 (action 2 = short off/restart)
:''' Sequence ''': Following steps repeat 10-times
:# Turn output No. 1 ON
:# Wait 10s
:# Turn output No. 1 OFF
:# Wait 2s
:# Repeat

<nowiki>
{
"conditions": {
"WDT/CR01_WDT/FAIL": true
},
"actions": {
"OUTPUTS/1/ACTION": 2,
"sequence":{
"repeat": 10,
"actions":[
{"OUTPUTS/1/ACTION": 1, "delay":10000},
{"OUTPUTS/1/ACTION": 0, "delay":2000}
]
}
}
}</nowiki>

Rules

2023-06-19T17:17:08Z

Bbakala: /* Available forms of conditions */

Each Rule define the follow-up actions based on current DI / [https://wiki.netio-products.com/index.php?title=PAB '''PAB''']/ [https://wiki.netio-products.com/index.php?title=Watchdog '''WatchDog'''] function state. There can be several Rules executed based on one PAB function (switch output if Current > 1000 mA + Send Alert to NETIO Cloud IF Current > 500 mA). One Rule can be executed based on combination of several PAB / WatchDog states.

'''Rules examples are available on page:''' https://wiki.netio-products.com/index.php?title=Rules_Complete_Examples

== CONDITION ==
Rule conditions define when the action part of each Rule is executed. There can be multiple conditions for one Rule.
In order to execute the action, all conditions have to be valid (AND operator) / at least one of the conditions have to be valid (OR operator).

=== Available forms of conditions ===
* <code>"PAB/PAB1_1/IN": true</code> = <code>PAB1_1</code> is in specified interval
* <code>"PAB/PAB_ZONE_1/ZONE": 1</code> = <code>PAB_ZONE_1</code> is in zone 1
* <code>"PAB/CR13_PAB/DAY": true</code> = daylight for current time on defined location (for use with DAYLIGHT-type PAB)
* <code>"WDT/WATCHDOG_1/FAIL": true</code> = <code>WATCHDOG_1</code> is in ERROR state
* <code>"OUTPUTS/1/STATE": "on"</code> = Output 1 is currently ON (1)
* <code>"INPUTS/1/STATE": "off"</code> = DI1 is currently OFF (0)
* <code>"SYSTEM/DEVICE_POWER_UP": true</code> = device boot after power-cut (external power outage, lower-level system (MCU) firmware update)<code>FW 4.0.0+</code>
* <code>"SYSTEM/DEVICE_BOOT": true</code> = device boot after soft restart (internal watchdog or periodic restart) - no Power Outage, state of outputs not changed<code>FW 4.0.0+</code>
* <code>"NETWORK/STATE": "down"</code> = indicates network connection status, states: "up" - device is connected, "down" - device is not connected<code>FW 4.0.0+</code>
* <code>"NETWORK/ETHERNET/STATE": "down"</code> = indicates network connection status, states: "up" - device is connected, "down" - device is not connected<code>FW 4.0.0+</code>
* <code>"NETWORK/WIFI/STATE": "down"</code> = indicates network connection status, states: "up" - device is connected, "down" - device is not connected<code>FW 4.0.0+</code>

== FILTER (mask)==
The filter field specifies when the Rule is active. It acts as a mask If filter in certain time is not true, the action wont be executed even when conditions are fulfilled. Multiple filters can be set for one rule. For the rule to be active all filters must be true.

Above that the FILTER can be applied (scheduler, DI (Digital Input) or DO (Output) state).

=== Available forms of filters ===
* <code>"SCHEDULE/TestSchedule/ACTIVE": true</code> = <code>TestSchedule</code> is active
* <code>"OUTPUTS/1/STATE":"on"</code> = Output 1 is ON

== ACTION ==
ACTIONS part in the Rule contains list of several actions when condition(s) + filter(s) are valid.

The actions can change output states (turn OFF, turn ON, toggle, etc.) or trigger an Alarm state in NETIO Cloud.
There is one Alarm state reserved per each one output in the NETIO Cloud premium (only).
You can verify your configuration and check sending of the Output Alarm in the Device Log.

=== Available forms of actions ===
* <code>"OUTPUTS/1/ACTION": 0</code> = Turn OFF Output 1
* <code>"OUTPUTS/6/ACTION": 2</code> = Short OFF Output 6
* <code>"CLOUD/OUTPUT/1/ALARM": "${COND_RESULT}"</code> = Set condition output value to the alarm (Turns the alarm ON or OFF based on condition evaluation)

''Note: The variable <code>${COND_RESULT}</code> contains output value of the given condition. It takes values 0 (condition not met) or 1 (condition met). It can be used for dynamic switching the alarm in Cloud ON/OFF depending on current state of the PAB.''

=== Standard output actions per each output ===
* 0 = TURN OFF
* 1 = TURN ON
* 2 = SHORT OFF
* 3 = SHORT ON
* 4 = TOGGLE - Changes the status from ON to OFF and vice versa
* 5 = NOTHING (placeholder, DO NOT USE)

== Structure ==

{| class="wikitable"
|-
! Variable
! Value
! Description
|-
| conditions
| Eg: `"PAB/PAB1_1/IN": true`
| Conditions definition. Relationship between conditions is defined by <code>operator</code> (AND/OR)
|-
| operator
| AND/OR
| Optional. Specifies relationship between conditions. <code>AND</code> = all conditions must apply at the same time. <code>OR</code> = at least one condition must apply. If missing, defaults to <code>OR</code>
|-
| filters
| Eg: <code>"SCHEDULE/MY_SCHEDULE/ACTIVE": true<code/>
| Filter definition. For multiple filter conditions, the relationship between them is always <code>AND</code>
|-
| actions
| Eg: <code>"CLOUD/OUTPUT/1/ALARM": "${COND_RESULT}"</code>
| Actions definition. All actions defined here will be triggered when conditions (and filters) are met
|}

Condition names are based on user-specified names and their types:
* For PABs, the name has structure: <code>PAB/pab_name/pab_output_value</code> (TRUE/FALSE or int)
* For WatchDogs, the name has structure: <code>WDT/watchdog_name/FAIL</code>

== Sequence <code>FW 4.0.0+</code> ==

Sequences bring extended usability to ACTIONS. In addition to basic actions that are triggered right after certain condition (conditions) are met, sequence can be defined to enable repetitive actions.

=== Configuration variables ===

{| class="wikitable"
|-
! Variable
! Value
! Description
|-
| repeat
| int (0 to 1-MAX_INT) / true
| How many times should the sequence repeat. Set <code>0</code> or <code>true</code> for indefinitely (can only be turned off by disabling the rule).
|-
| actions
|
| Standard actions as defined in section [[#ACTION| ACTION]]
|-
| delay
| int [ms] in multiples of 100ms
| '''May''' be set along with actions to be executed. Defines time the sequence waits '''after''' performing the action. The value is rounded up to hundreds of miliseconds (e.g. 85ms -> 100ms, 235ms -> 300ms).
|}

=== Example ===
This example triggers one-time action along with sequence of other actions and repeats 10-times after meeting certain condition.
:'''Condition''': WatchDog '''CR01_WDT''' fails (receives timeout from defined address)
:'''One-time action''': Restart output No. 2 (action 2 = short off/restart)
:''' Sequence ''': Following steps repeat 10-times
:# Turn output No. 1 ON
:# Wait 10s
:# Turn output No. 1 OFF
:# Wait 2s
:# Repeat

<nowiki>
{
"conditions": {
"WDT/CR01_WDT/FAIL": true
},
"actions": {
"OUTPUTS/1/ACTION": 2,
"sequence":{
"repeat": 10,
"actions":[
{"OUTPUTS/1/ACTION": 1, "delay":10000},
{"OUTPUTS/1/ACTION": 0, "delay":2000}
]
}
}
}</nowiki>

Rules

2023-06-19T17:16:40Z

Bbakala: /* Available forms of conditions */

Each Rule define the follow-up actions based on current DI / [https://wiki.netio-products.com/index.php?title=PAB '''PAB''']/ [https://wiki.netio-products.com/index.php?title=Watchdog '''WatchDog'''] function state. There can be several Rules executed based on one PAB function (switch output if Current > 1000 mA + Send Alert to NETIO Cloud IF Current > 500 mA). One Rule can be executed based on combination of several PAB / WatchDog states.

'''Rules examples are available on page:''' https://wiki.netio-products.com/index.php?title=Rules_Complete_Examples

== CONDITION ==
Rule conditions define when the action part of each Rule is executed. There can be multiple conditions for one Rule.
In order to execute the action, all conditions have to be valid (AND operator) / at least one of the conditions have to be valid (OR operator).

=== Available forms of conditions ===
* <code>"PAB/PAB1_1/IN": true</code> = <code>PAB1_1</code> is in specified interval
* <code>"PAB/PAB_ZONE_1/ZONE": 1</code> = <code>PAB_ZONE_1</code> is in zone 1
* <code>"PAB/CR13_PAB/DAY": true</code> = daylight for current time on defined location (for use with DAYLIGHT-type PAB)
* <code>"WDT/WATCHDOG_1/FAIL": true</code> = <code>WATCHDOG_1</code> is in ERROR state
* <code>"OUTPUTS/1/STATE": "on"</code> = Output 1 is currently ON (1)
* <code>"INPUTS/1/STATE": "off"</code> = DI1 is currently OFF (0)
* <code>"SYSTEM/DEVICE_POWER_UP": true</code><code>FW 4.0.0+</code> = device boot after power-cut (external power outage, lower-level system (MCU) firmware update)
* <code>"SYSTEM/DEVICE_BOOT": true</code><code>FW 4.0.0+</code> = device boot after soft restart (internal watchdog or periodic restart) - no Power Outage, state of outputs not changed
* <code>"NETWORK/STATE": "down"</code><code>FW 4.0.0+</code> = indicates network connection status, states: "up" - device is connected, "down" - device is not connected
* <code>"NETWORK/ETHERNET/STATE": "down"</code><code>FW 4.0.0+</code> = indicates network connection status, states: "up" - device is connected, "down" - device is not connected
* <code>"NETWORK/WIFI/STATE": "down"</code><code>FW 4.0.0+</code> = indicates network connection status, states: "up" - device is connected, "down" - device is not connected

== FILTER (mask)==
The filter field specifies when the Rule is active. It acts as a mask If filter in certain time is not true, the action wont be executed even when conditions are fulfilled. Multiple filters can be set for one rule. For the rule to be active all filters must be true.

Above that the FILTER can be applied (scheduler, DI (Digital Input) or DO (Output) state).

=== Available forms of filters ===
* <code>"SCHEDULE/TestSchedule/ACTIVE": true</code> = <code>TestSchedule</code> is active
* <code>"OUTPUTS/1/STATE":"on"</code> = Output 1 is ON

== ACTION ==
ACTIONS part in the Rule contains list of several actions when condition(s) + filter(s) are valid.

The actions can change output states (turn OFF, turn ON, toggle, etc.) or trigger an Alarm state in NETIO Cloud.
There is one Alarm state reserved per each one output in the NETIO Cloud premium (only).
You can verify your configuration and check sending of the Output Alarm in the Device Log.

=== Available forms of actions ===
* <code>"OUTPUTS/1/ACTION": 0</code> = Turn OFF Output 1
* <code>"OUTPUTS/6/ACTION": 2</code> = Short OFF Output 6
* <code>"CLOUD/OUTPUT/1/ALARM": "${COND_RESULT}"</code> = Set condition output value to the alarm (Turns the alarm ON or OFF based on condition evaluation)

''Note: The variable <code>${COND_RESULT}</code> contains output value of the given condition. It takes values 0 (condition not met) or 1 (condition met). It can be used for dynamic switching the alarm in Cloud ON/OFF depending on current state of the PAB.''

=== Standard output actions per each output ===
* 0 = TURN OFF
* 1 = TURN ON
* 2 = SHORT OFF
* 3 = SHORT ON
* 4 = TOGGLE - Changes the status from ON to OFF and vice versa
* 5 = NOTHING (placeholder, DO NOT USE)

== Structure ==

{| class="wikitable"
|-
! Variable
! Value
! Description
|-
| conditions
| Eg: `"PAB/PAB1_1/IN": true`
| Conditions definition. Relationship between conditions is defined by <code>operator</code> (AND/OR)
|-
| operator
| AND/OR
| Optional. Specifies relationship between conditions. <code>AND</code> = all conditions must apply at the same time. <code>OR</code> = at least one condition must apply. If missing, defaults to <code>OR</code>
|-
| filters
| Eg: <code>"SCHEDULE/MY_SCHEDULE/ACTIVE": true<code/>
| Filter definition. For multiple filter conditions, the relationship between them is always <code>AND</code>
|-
| actions
| Eg: <code>"CLOUD/OUTPUT/1/ALARM": "${COND_RESULT}"</code>
| Actions definition. All actions defined here will be triggered when conditions (and filters) are met
|}

Condition names are based on user-specified names and their types:
* For PABs, the name has structure: <code>PAB/pab_name/pab_output_value</code> (TRUE/FALSE or int)
* For WatchDogs, the name has structure: <code>WDT/watchdog_name/FAIL</code>

== Sequence <code>FW 4.0.0+</code> ==

Sequences bring extended usability to ACTIONS. In addition to basic actions that are triggered right after certain condition (conditions) are met, sequence can be defined to enable repetitive actions.

=== Configuration variables ===

{| class="wikitable"
|-
! Variable
! Value
! Description
|-
| repeat
| int (0 to 1-MAX_INT) / true
| How many times should the sequence repeat. Set <code>0</code> or <code>true</code> for indefinitely (can only be turned off by disabling the rule).
|-
| actions
|
| Standard actions as defined in section [[#ACTION| ACTION]]
|-
| delay
| int [ms] in multiples of 100ms
| '''May''' be set along with actions to be executed. Defines time the sequence waits '''after''' performing the action. The value is rounded up to hundreds of miliseconds (e.g. 85ms -> 100ms, 235ms -> 300ms).
|}

=== Example ===
This example triggers one-time action along with sequence of other actions and repeats 10-times after meeting certain condition.
:'''Condition''': WatchDog '''CR01_WDT''' fails (receives timeout from defined address)
:'''One-time action''': Restart output No. 2 (action 2 = short off/restart)
:''' Sequence ''': Following steps repeat 10-times
:# Turn output No. 1 ON
:# Wait 10s
:# Turn output No. 1 OFF
:# Wait 2s
:# Repeat

<nowiki>
{
"conditions": {
"WDT/CR01_WDT/FAIL": true
},
"actions": {
"OUTPUTS/1/ACTION": 2,
"sequence":{
"repeat": 10,
"actions":[
{"OUTPUTS/1/ACTION": 1, "delay":10000},
{"OUTPUTS/1/ACTION": 0, "delay":2000}
]
}
}
}</nowiki>

Rules

2023-06-19T17:15:15Z

Bbakala: /* Available forms of conditions */

Each Rule define the follow-up actions based on current DI / [https://wiki.netio-products.com/index.php?title=PAB '''PAB''']/ [https://wiki.netio-products.com/index.php?title=Watchdog '''WatchDog'''] function state. There can be several Rules executed based on one PAB function (switch output if Current > 1000 mA + Send Alert to NETIO Cloud IF Current > 500 mA). One Rule can be executed based on combination of several PAB / WatchDog states.

'''Rules examples are available on page:''' https://wiki.netio-products.com/index.php?title=Rules_Complete_Examples

== CONDITION ==
Rule conditions define when the action part of each Rule is executed. There can be multiple conditions for one Rule.
In order to execute the action, all conditions have to be valid (AND operator) / at least one of the conditions have to be valid (OR operator).

=== Available forms of conditions ===
* <code>"PAB/PAB1_1/IN": true</code> = <code>PAB1_1</code> is in specified interval
* <code>"PAB/PAB_ZONE_1/ZONE": 1</code> = <code>PAB_ZONE_1</code> is in zone 1
* <code>"PAB/CR13_PAB/DAY": true</code> = daylight for current time on defined location (for use with DAYLIGHT-type PAB)
* <code>"WDT/WATCHDOG_1/FAIL": true</code> = <code>WATCHDOG_1</code> is in ERROR state
* <code>"OUTPUTS/1/STATE": "on"</code> = Output 1 is currently ON (1)
* <code>"INPUTS/1/STATE": "off"</code> = DI1 is currently OFF (0)
* <code>"SYSTEM/DEVICE_POWER_UP": true</code> = device boot after power-cut (external power outage, lower-level system (MCU) firmware update)
* <code>"SYSTEM/DEVICE_BOOT": true</code> = = device boot after soft restart (internal watchdog or periodic restart) - no Power Outage, state of outputs not changed
* <code>"NETWORK/STATE": "down"</code> = indicates network connection status, states: "up" - device is connected, "down" - device is not connected
* <code>"NETWORK/ETHERNET/STATE": "down"</code> = indicates network connection status, states: "up" - device is connected, "down" - device is not connected
* <code>"NETWORK/WIFI/STATE": "down"</code> = indicates network connection status, states: "up" - device is connected, "down" - device is not connected

== FILTER (mask)==
The filter field specifies when the Rule is active. It acts as a mask If filter in certain time is not true, the action wont be executed even when conditions are fulfilled. Multiple filters can be set for one rule. For the rule to be active all filters must be true.

Above that the FILTER can be applied (scheduler, DI (Digital Input) or DO (Output) state).

=== Available forms of filters ===
* <code>"SCHEDULE/TestSchedule/ACTIVE": true</code> = <code>TestSchedule</code> is active
* <code>"OUTPUTS/1/STATE":"on"</code> = Output 1 is ON

== ACTION ==
ACTIONS part in the Rule contains list of several actions when condition(s) + filter(s) are valid.

The actions can change output states (turn OFF, turn ON, toggle, etc.) or trigger an Alarm state in NETIO Cloud.
There is one Alarm state reserved per each one output in the NETIO Cloud premium (only).
You can verify your configuration and check sending of the Output Alarm in the Device Log.

=== Available forms of actions ===
* <code>"OUTPUTS/1/ACTION": 0</code> = Turn OFF Output 1
* <code>"OUTPUTS/6/ACTION": 2</code> = Short OFF Output 6
* <code>"CLOUD/OUTPUT/1/ALARM": "${COND_RESULT}"</code> = Set condition output value to the alarm (Turns the alarm ON or OFF based on condition evaluation)

''Note: The variable <code>${COND_RESULT}</code> contains output value of the given condition. It takes values 0 (condition not met) or 1 (condition met). It can be used for dynamic switching the alarm in Cloud ON/OFF depending on current state of the PAB.''

=== Standard output actions per each output ===
* 0 = TURN OFF
* 1 = TURN ON
* 2 = SHORT OFF
* 3 = SHORT ON
* 4 = TOGGLE - Changes the status from ON to OFF and vice versa
* 5 = NOTHING (placeholder, DO NOT USE)

== Structure ==

{| class="wikitable"
|-
! Variable
! Value
! Description
|-
| conditions
| Eg: `"PAB/PAB1_1/IN": true`
| Conditions definition. Relationship between conditions is defined by <code>operator</code> (AND/OR)
|-
| operator
| AND/OR
| Optional. Specifies relationship between conditions. <code>AND</code> = all conditions must apply at the same time. <code>OR</code> = at least one condition must apply. If missing, defaults to <code>OR</code>
|-
| filters
| Eg: <code>"SCHEDULE/MY_SCHEDULE/ACTIVE": true<code/>
| Filter definition. For multiple filter conditions, the relationship between them is always <code>AND</code>
|-
| actions
| Eg: <code>"CLOUD/OUTPUT/1/ALARM": "${COND_RESULT}"</code>
| Actions definition. All actions defined here will be triggered when conditions (and filters) are met
|}

Condition names are based on user-specified names and their types:
* For PABs, the name has structure: <code>PAB/pab_name/pab_output_value</code> (TRUE/FALSE or int)
* For WatchDogs, the name has structure: <code>WDT/watchdog_name/FAIL</code>

== Sequence <code>FW 4.0.0+</code> ==

Sequences bring extended usability to ACTIONS. In addition to basic actions that are triggered right after certain condition (conditions) are met, sequence can be defined to enable repetitive actions.

=== Configuration variables ===

{| class="wikitable"
|-
! Variable
! Value
! Description
|-
| repeat
| int (0 to 1-MAX_INT) / true
| How many times should the sequence repeat. Set <code>0</code> or <code>true</code> for indefinitely (can only be turned off by disabling the rule).
|-
| actions
|
| Standard actions as defined in section [[#ACTION| ACTION]]
|-
| delay
| int [ms] in multiples of 100ms
| '''May''' be set along with actions to be executed. Defines time the sequence waits '''after''' performing the action. The value is rounded up to hundreds of miliseconds (e.g. 85ms -> 100ms, 235ms -> 300ms).
|}

=== Example ===
This example triggers one-time action along with sequence of other actions and repeats 10-times after meeting certain condition.
:'''Condition''': WatchDog '''CR01_WDT''' fails (receives timeout from defined address)
:'''One-time action''': Restart output No. 2 (action 2 = short off/restart)
:''' Sequence ''': Following steps repeat 10-times
:# Turn output No. 1 ON
:# Wait 10s
:# Turn output No. 1 OFF
:# Wait 2s
:# Repeat

<nowiki>
{
"conditions": {
"WDT/CR01_WDT/FAIL": true
},
"actions": {
"OUTPUTS/1/ACTION": 2,
"sequence":{
"repeat": 10,
"actions":[
{"OUTPUTS/1/ACTION": 1, "delay":10000},
{"OUTPUTS/1/ACTION": 0, "delay":2000}
]
}
}
}</nowiki>

Rules

2023-06-19T17:09:51Z

Bbakala: /* Available forms of conditions */

Each Rule define the follow-up actions based on current DI / [https://wiki.netio-products.com/index.php?title=PAB '''PAB''']/ [https://wiki.netio-products.com/index.php?title=Watchdog '''WatchDog'''] function state. There can be several Rules executed based on one PAB function (switch output if Current > 1000 mA + Send Alert to NETIO Cloud IF Current > 500 mA). One Rule can be executed based on combination of several PAB / WatchDog states.

'''Rules examples are available on page:''' https://wiki.netio-products.com/index.php?title=Rules_Complete_Examples

== CONDITION ==
Rule conditions define when the action part of each Rule is executed. There can be multiple conditions for one Rule.
In order to execute the action, all conditions have to be valid (AND operator) / at least one of the conditions have to be valid (OR operator).

=== Available forms of conditions ===
* <code>"PAB/PAB1_1/IN": true</code> = <code>PAB1_1</code> is in specified interval
* <code>"PAB/PAB_ZONE_1/ZONE": 1</code> = <code>PAB_ZONE_1</code> is in zone 1
* <code>"PAB/CR13_PAB/DAY": true</code> = daylight for current time on defined location (for use with DAYLIGHT-type PAB)
* <code>"WDT/WATCHDOG_1/FAIL": true</code> = <code>WATCHDOG_1</code> is in ERROR state
* <code>"OUTPUTS/1/STATE": "on"</code> = Output 1 is currently ON (1)
* <code>"INPUTS/1/STATE": "off"</code> = DI1 is currently OFF (0)
* <code>"SYSTEM/DEVICE_POWER_UP": true</code> = device boot after power-cut (external power outage, lower-level system (MCU) firmware update)
* <code>"SYSTEM/DEVICE_BOOT": true</code> = = device boot after soft restart (internal watchdog or periodic restart) - no Power Outage, state of outputs not changed

== FILTER (mask)==
The filter field specifies when the Rule is active. It acts as a mask If filter in certain time is not true, the action wont be executed even when conditions are fulfilled. Multiple filters can be set for one rule. For the rule to be active all filters must be true.

Above that the FILTER can be applied (scheduler, DI (Digital Input) or DO (Output) state).

=== Available forms of filters ===
* <code>"SCHEDULE/TestSchedule/ACTIVE": true</code> = <code>TestSchedule</code> is active
* <code>"OUTPUTS/1/STATE":"on"</code> = Output 1 is ON

== ACTION ==
ACTIONS part in the Rule contains list of several actions when condition(s) + filter(s) are valid.

The actions can change output states (turn OFF, turn ON, toggle, etc.) or trigger an Alarm state in NETIO Cloud.
There is one Alarm state reserved per each one output in the NETIO Cloud premium (only).
You can verify your configuration and check sending of the Output Alarm in the Device Log.

=== Available forms of actions ===
* <code>"OUTPUTS/1/ACTION": 0</code> = Turn OFF Output 1
* <code>"OUTPUTS/6/ACTION": 2</code> = Short OFF Output 6
* <code>"CLOUD/OUTPUT/1/ALARM": "${COND_RESULT}"</code> = Set condition output value to the alarm (Turns the alarm ON or OFF based on condition evaluation)

''Note: The variable <code>${COND_RESULT}</code> contains output value of the given condition. It takes values 0 (condition not met) or 1 (condition met). It can be used for dynamic switching the alarm in Cloud ON/OFF depending on current state of the PAB.''

=== Standard output actions per each output ===
* 0 = TURN OFF
* 1 = TURN ON
* 2 = SHORT OFF
* 3 = SHORT ON
* 4 = TOGGLE - Changes the status from ON to OFF and vice versa
* 5 = NOTHING (placeholder, DO NOT USE)

== Structure ==

{| class="wikitable"
|-
! Variable
! Value
! Description
|-
| conditions
| Eg: `"PAB/PAB1_1/IN": true`
| Conditions definition. Relationship between conditions is defined by <code>operator</code> (AND/OR)
|-
| operator
| AND/OR
| Optional. Specifies relationship between conditions. <code>AND</code> = all conditions must apply at the same time. <code>OR</code> = at least one condition must apply. If missing, defaults to <code>OR</code>
|-
| filters
| Eg: <code>"SCHEDULE/MY_SCHEDULE/ACTIVE": true<code/>
| Filter definition. For multiple filter conditions, the relationship between them is always <code>AND</code>
|-
| actions
| Eg: <code>"CLOUD/OUTPUT/1/ALARM": "${COND_RESULT}"</code>
| Actions definition. All actions defined here will be triggered when conditions (and filters) are met
|}

Condition names are based on user-specified names and their types:
* For PABs, the name has structure: <code>PAB/pab_name/pab_output_value</code> (TRUE/FALSE or int)
* For WatchDogs, the name has structure: <code>WDT/watchdog_name/FAIL</code>

== Sequence <code>FW 4.0.0+</code> ==

Sequences bring extended usability to ACTIONS. In addition to basic actions that are triggered right after certain condition (conditions) are met, sequence can be defined to enable repetitive actions.

=== Configuration variables ===

{| class="wikitable"
|-
! Variable
! Value
! Description
|-
| repeat
| int (0 to 1-MAX_INT) / true
| How many times should the sequence repeat. Set <code>0</code> or <code>true</code> for indefinitely (can only be turned off by disabling the rule).
|-
| actions
|
| Standard actions as defined in section [[#ACTION| ACTION]]
|-
| delay
| int [ms] in multiples of 100ms
| '''May''' be set along with actions to be executed. Defines time the sequence waits '''after''' performing the action. The value is rounded up to hundreds of miliseconds (e.g. 85ms -> 100ms, 235ms -> 300ms).
|}

=== Example ===
This example triggers one-time action along with sequence of other actions and repeats 10-times after meeting certain condition.
:'''Condition''': WatchDog '''CR01_WDT''' fails (receives timeout from defined address)
:'''One-time action''': Restart output No. 2 (action 2 = short off/restart)
:''' Sequence ''': Following steps repeat 10-times
:# Turn output No. 1 ON
:# Wait 10s
:# Turn output No. 1 OFF
:# Wait 2s
:# Repeat

<nowiki>
{
"conditions": {
"WDT/CR01_WDT/FAIL": true
},
"actions": {
"OUTPUTS/1/ACTION": 2,
"sequence":{
"repeat": 10,
"actions":[
{"OUTPUTS/1/ACTION": 1, "delay":10000},
{"OUTPUTS/1/ACTION": 0, "delay":2000}
]
}
}
}</nowiki>

MQTT-flex

2023-06-13T16:57:11Z

Bbakala: /* DEVICE_MAC */

The MQTT-flex version of the MQTT protocol can be configured in detail thanks to the “flex” extension.

https://www.netio-products.com/en/glossary/mqtt-flex

Why MQTT-flex 
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 [https://en.wikipedia.org/wiki/MQTT 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 [https://en.wikipedia.org/wiki/JSON 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 101x 
* PowerCable REST 101x 
* PowerPDU 4PS 
* PowerPDU 4KS 
* PowerPDU 8QS 
* PowerDIN 4PZ 
* PowerBOX 3Px 
* PowerBOX 4Kx 

FW version: 
>2.2.1

===Not supported NETIO devices:===
* PowerPDU 4C 
* NETIO 4 
* NETIO 4All 

= Simple MQTT-flex configuration + explanation =

''We strongly recommend to create and test MQTT-flex configuration on "local" device what can be easily restarted. The validation of config before saving is not 100% and for example some specific typos can cause a freeze of a device - the solution is to restart a device (unplug/plug input power cable). If the configuration is saved and device is working then there are no known failure case so it is safe to use this configuration on the "remote" devices.''

{
"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":false,
"payload":"${OUTPUTS/1/STATE}",
"events":[
{
"type":"timer",
"period":"1000"
}
]
}
]
}
}
=== Client Configuration (broker section) ===
Put here MQTT client connection setup

This configuration example set NETIO device to connect to broker.hivemq.com with mqtt protocol, no ssl connection with credetials freedom/peace|love|empathy4ALL.

"broker":{
"url":"broker.hivemq.com",
"protocol":"mqtt",
"port":1883,
"ssl":false,
"type":"generic",
"username":"freedom",
"password":"peace|LOVE|empathy4ALL"
},

=== Device Control (subscribe section) ===
Put here array of topics where to subscribe

Device output 1 is controlled with action received by subscription to netio/${DEVICE_NAME}/output/1/action topic with QOS 0

"subscribe":[{
"topic":"netio/${DEVICE_NAME}/output/1/action",
"qos":0,
"target":"OUTPUTS/1/ACTION",
"action":"${payload}"
}
],

=== Output State monitoring (publish section) ===
Put here array of topics where to publish.

Device send every 1000 s message to topic with QOS 0, retain true information with output 1 state

"publish":[{
"topic":"netio/${DEVICE_NAME}/output/1/state",
"qos":0,
"retain":true,
"payload":"${OUTPUTS/1/STATE}",
"events":[
{
"type":"timer",
"period":"1000"
}
]
}
]

= 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 ===
{| class="wikitable"
! style="font-weight:bold; background-color:#9b9b9b;" | Item
! style="font-weight:bold; background-color:#9b9b9b;" | Presence
! style="font-weight:bold; background-color:#9b9b9b;" | Possible Values
! style="font-weight:bold; background-color:#9b9b9b;" | Description
! style="font-weight:bold; background-color:#9b9b9b;" | JSON Config Usage
|-
| style="background-color:#efefef;" | url
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" |
| style="background-color:#efefef;" | MQTT broker URL
| style="background-color:#efefef;" | "url":"broker.hivemq.com"
|-
| style="background-color:#efefef;" | port
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | 1 - 65535
| style="background-color:#efefef;" | MQTT broker port
| style="background-color:#efefef;" | "port":1883
|-
| style="background-color:#efefef;" | protocol
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" |
| style="background-color:#efefef;" | protocol spec - mqtt
| style="background-color:#efefef;" | "protocol": "mqtt"
|-
| style="background-color:#efefef;" | ssl
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | true, false
| style="background-color:#efefef;" | Use SSL crypted communication selector
| style="background-color:#efefef;" | "ssl":false
|-
| style="background-color:#efefef;" | type
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | generic
| style="background-color:#efefef;" | Communication/setup type option
| style="background-color:#efefef;" | "type":"generic"
|-
| style="background-color:#efefef;" | username
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | regexp+len
| style="background-color:#efefef;" | Credentials for MQTT broker. Max. 128 characters (since FW 3.2.4).
| style="background-color:#efefef;" | "username":"freedom"
|-
| style="background-color:#efefef;" | password
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | regexp+len
| style="background-color:#efefef;" | Credentials for MQTT broker. Max. 256 characters (since FW 3.2.4).
| style="background-color:#efefef;" | "password":"peace|LOVE|empathy4ALL"
|-
| style="background-color:#efefef;" | clientid
| style="background-color:#efefef;" | optional
| style="background-color:#efefef;" | regexp+len
| style="background-color:#efefef;" | MQTT clientid. Max. 128 characters (since FW 3.2.4). Variables ${DEVICE_MAC} or ${DEVICE_NAME} can be used
| style="background-color:#efefef;" | "clientid":"myEcoTable01"
|-
| style="background-color:#efefef;" | keepalive
| style="background-color:#efefef;" | optional
| style="background-color:#efefef;" | 1 - 65535
| style="background-color:#efefef;" | MQTT keep alive period in seconds
| style="background-color:#efefef;" | "keepalive":90
|}

Note 1: clientid attribute is mandatory for MQTT(s) communication. When not configured, random ID will be generated.

Note 2: To proper communication with MS Azure - it is necessary to set up IoT Hub to use TLS 1.2

See section "TLS 1.2 enforcement available in select regions" in following guidelines https://docs.microsoft.com/en-us/azure/iot-hub/iot-hub-tls-support

=== Examples ===
==== Standard setup ====

==== Security (SSL / TLS) secured setup ====
You can enable MQTTs by using the encrypted port 8883 + "ssl":true.

==== Variables used setup ====

== 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 ===
{| class="wikitable"
! style="font-weight:bold; background-color:#9b9b9b;" | Item
! style="font-weight:bold; background-color:#9b9b9b;" | Presence
! style="font-weight:bold; background-color:#9b9b9b;" | Possible Values
! style="font-weight:bold; background-color:#9b9b9b;" | Description
! style="font-weight:bold; background-color:#9b9b9b;" | JSON Config Usage
|-
| style="background-color:#efefef;" | topic
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | see table below
| style="background-color:#efefef;" | specification of the topic, which MQTT-flex device listens from broker and act accordingly. Max. 128 characters. The "#" can be used since FW 3.2.4 - see note under this table.
| style="background-color:#efefef;" | "topic":"netio/${DEVICE_NAME}/output/1/action"
|-
| style="background-color:#efefef;" | qos
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | 0, 1 or 2
| style="background-color:#efefef;" | 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}
| style="background-color:#efefef;" | "qos":0
|-
| style="background-color:#efefef;" | target
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" |
| style="background-color:#efefef;" | internal definition of action, which can be performed above the specified output
| style="background-color:#efefef;" | "target":"OUTPUTS/1/ACTION"
|-
| style="background-color:#efefef;" | action
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" |
| style="background-color:#efefef;" | a payload or a value the action attribute needs to have passed to
| style="background-color:#efefef;" | "action":"${payload}"
|-
| style="background-color:#efefef;" | actiondefNot supported yet
| style="background-color:#efefef;" | optional
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
|-
| style="background-color:#efefef;" | jsonNot supported yet
| style="background-color:#efefef;" | optional
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
|}

Note: The "#" wildcard can be used in subscribe topic definition. The multi-level wildcard character MUST be specified either on its own or following a topic level separator. In either case it MUST be the last character specified in the Topic.

For example, if a Device subscribes to “devices/{device_id}/messages/devicebound/#”, it would receive messages published using these topic names:

“devices/{device_id}/messages/devicebound/”

“devices/{device_id}/messages/devicebound/{property_bag}”

This should be usefull for use with MS Azure - IoT hub.

=== MQTT Subscribe as event to trigger action <code>FW 4.0.0+</code> ===

This feature allow to subscribe to specific MQTT topic and pass payload to Rules or MQTT-flex as event.

target: <code>PROTOCOLS/MQTT/EVENT</code>

"subscribe": [
{
"action": "${payload}",
"qos": 0,
"target": "PROTOCOLS/MQTT/EVENT",
"topic": "broker/12345/MQTT_EVENT/"
}
]

=== Examples ===
==== Toggle output with standard payload ====
==== Toggle output with custom payload ====
==== Subscribe to more than one topic ====
==== Trigger Rule and MQTT publish from MQTT subscribe <code>FW 4.0.0+</code> ====
This example show Request response implementation in MQTT and toggle action made by Rules.

When message with payload <code>getValues</code> is published to topic <code>broker/gv90018g/COMMAND</code> MQTT flex will create an event with name <code>PROTOCOLS/MQTT/EVENT</code> (fixed name cannot be changed) and value <code>getValues</code>. On this event will act all events and conditions set in MQTT-flex and Rules which are set to listening to change on <code>PROTOCOLS/MQTT/EVENT</code> and equals to value <code>getValues</code>. See bold marked parameters in example configuration below.

Once the triggered action is done it is needed to reset MQTT channel to <code>OK</code> status becaus event are reacting only to change. If the channel is not reset the next even would not be triggered.

Rules Configuration:
{
"conditions": {
"PROTOCOLS/MQTT/EVENT": "getValues"
},
"actions": {
"OUTPUTS/1/ACTION": 4
}
}

MQTT Configuration:
{
"broker":{
"clientid":"netio${DEVICE_SN}",
"keepalive":30,
"password":"abcdefghijk",
"port":8883,
"protocol":"mqtt",
"ssl":true,
"type":"generic",
"url":"broker.cloud.netio.eu",
"username":"gv90018g"
},
"groupEvents":[
{
"events":[
{
"source":"PROTOCOLS/MQTT/EVENT",
"type":"change",
"value":"getValues"
}
],
"appliedTopics":[
"broker/gv90018g/OUTPUTS/1/STATE",
"broker/gv90018g/COMMAND"
]
}
],
"publish":[
{
"payload":"${OUTPUTS/1/STATE}",
"qos":0,
"retain":true,
"topic":"broker/gv90018g/OUTPUTS/1/STATE"
},
{
"payload":"OK",
"qos":0,
"retain":true,
"topic":"broker/gv90018g/COMMAND"
}
],
"subscribe":[
{
"action":"${payload}",
"qos":0,
"target":"PROTOCOLS/MQTT/EVENT",
"topic":"broker/gv90018g/COMMAND"
}
]
}

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 ===
{| class="wikitable"
! style="font-weight:bold; background-color:#9b9b9b;" | Item
! style="font-weight:bold; background-color:#9b9b9b;" | Presence
! style="font-weight:bold; background-color:#9b9b9b;" | Possible Values
! style="font-weight:bold; background-color:#9b9b9b;" | Description
! style="font-weight:bold; background-color:#9b9b9b;" | JSON Config Usage
|-
| style="background-color:#efefef;" | topic
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | see table below
| style="background-color:#efefef;" | definition of the topic, how it is registered towards MQTT broker. Max. 128 characters.
| style="background-color:#efefef;" | "topic":"netio/${DEVICE_NAME}/output/1/load"
|-
| style="background-color:#efefef;" | qos
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | see table below
| style="background-color:#efefef;" | 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}
| style="background-color:#efefef;" |
|-
| style="background-color:#efefef;" | retain
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | boolean: true or false
| style="background-color:#efefef;" | 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}
| style="background-color:#efefef;" | "retain":true
|-
| style="background-color:#efefef;" | payload
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | see table below
| style="background-color:#efefef;" | definition of the payload, what is send to the MQTT broker.
| style="background-color:#efefef;" | "payload":"${OUTPUTS/1/STATE}"
|-
| style="background-color:#efefef;" | events
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | see table below
| style="background-color:#efefef;" | definition of events used for triggering sending of data via mqtt (change, delta, timer)
| style="background-color:#efefef;" |
|-
| style="background-color:#efefef;" | type
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
|-
| style="background-color:#efefef;" | source
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
|-
| style="background-color:#efefef;" | delta
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
|-
| style="background-color:#efefef;" | period
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
|-
| style="background-color:#efefef;" | payloaddefNot supported yet
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
|}

=== Examples ===
==== Publish energy periodically (event timer) ====
==== Publish current on change (delta) ====
==== Publish output state ====
==== Publish to more than one topic with different events ====

= 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 available only on NETIO PowerDIN 4PZ

=== Examples: ===

adressing controll of output 3
OUTPUTS/3/ACTION
getting voltage on output 1
OUTPUTS/1/VOLTAGE
getting state of input 1
INPUTS/1/STATE

= Group Events<code>FW 4.0.0+</code> =
Group events are smart way how to keep configuration simple. It is not replacement of publish section specification but it is extension to trigger group of different topics to be published on the same event.

See the example below. There is specific event on status change on every output and additionally the device sends periodic status every 60 seconds.

{
"broker": {
"clientid": "netio${DEVICE_SN}",
"keepalive": 30,
"password": "",
"port": 1883,
"protocol": "mqtt",
"ssl": false,
"type": "generic",
"url": "broker.hivemq.com",
"username": ""
},
"groupEvents": [
{
"events":[
{
"period": 60,
"type": "timer"
}
],
"appliedTopics":[
"devices/${DEVICE_NAME}/output/1/state",
"devices/${DEVICE_NAME}/output/2/state"
]
}
],
"publish": [
{
"events": [
{
"source": "OUTPUTS/1/STATE",
"type": "change"
}
],
"payload": "${OUTPUTS/1/STATE}",
"qos": 0,
"retain": false,
 "topic": "devices/${DEVICE_NAME}/output/1/state"
},{
"events": [
{
"source": "OUTPUTS/2/STATE",
"type": "change"
}
],
"payload": "${OUTPUTS/2/STATE}",
"qos": 0,
"retain": false,
 "topic": "devices/${DEVICE_NAME}/output/2/state"
}
]
}

= 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 ===
==== VOLTAGE ====
Unit: <code>V</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Present RMS voltage on output 1 is ${OUTPUTS/1/VOLTAGE}"</code>

Example 2: <code>"source":"${OUTPUTS/1/VOLTAGE}"</code>

==== CURRENT ====
Unit: <code>mA</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Present RMS current on output 1 is ${OUTPUTS/1/CURRENT}"</code>

Example 2: <code>"source":"${OUTPUTS/1/CURRENT}"</code>

==== POWER_FACTOR ====
Unit: <code>[-]</code>

Type: float (2 decimals)

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"True Power Factor on output 1 is ${OUTPUTS/1/POWER_FACTOR}"</code>

Example 2: <code>"source":"${OUTPUTS/1/POWER_FACTOR}"</code>

==== LOAD ====
Unit: <code>W</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Present load on output 1 is ${OUTPUTS/1/LOAD}W"</code>

Example 2: <code>"payload":"Device's load connected to output 1 is ${OUTPUTS/1/LOAD}W"</code>

Example 3: <code>"source":"${OUTPUTS/1/LOAD}"</code>

==== STATE ====
Type: bool(integer) - <code>0</code> or <code>1</code>

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Present output 1 state is ${OUTPUTS/1/STATE}"</code>

Example 2: <code>"source":"${OUTPUTS/1/STATE}"</code>

==== ACTION ====
Type: integer

Possible actions:
* <code>0</code> - set state OFF
* <code>1</code> - set state ON
* <code>2</code> - short OFF (restart)
* <code>3</code> - short ON
* <code>4</code> - toggle (switch)
* <code>5</code> - no change

Allowed in: <code>"target"</code>

Example: <code>"target":"OUTPUTS/1/ACTION"</code>

==== DELAY [ms] ====
==== NAME ====
==== FREQUENCY ====
Unit: <code>Hz</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example: <code>"payload":"Frequency in power grid is ${OUTPUTS/1/ENERGY}Hz"</code>

==== ENERGY ====
Energy consumed by an device connected to NETIO device output.

Unit: <code>Wh</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Consumed energy on output 1 is ${OUTPUTS/1/ENERGY}Wh"</code>

Example 2: <code>"source":"${OUTPUTS/1/ENERGY}"</code>

==== REVERSE_ENERGY ====
Energy delivered back to grid. For example from solar system connected to NETIO device output.

Unit: <code>Wh</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Delivered energy on output 1 is ${OUTPUTS/1/REVERSE_ENERGY}Wh"</code>

Example 2: <code>"source":"${OUTPUTS/1/REVERSE_ENERGY}"</code>

==== ENERGY_START ====
Date when the counters ENERGY and REVERSE_ENERGY have been resetted by user.

Unit: <code>unix timestamp</code>

Type: integer

Allowed in: <code>"payload"</code>

Example 1: <code>"payload":"Energy measured since ${OUTPUTS/1/ENERGY_START} unix time"</code>

Example 2: <code>"payload":"${OUTPUTS/1/ENERGY_START}"</code> is output payload <code>1567654639</code>

==== ENERGY_START_FMT ====
Date when the counters ENERGY and REVERSE_ENERGY have been resetted by user.

Unit: <code>fmt date format</code>

Type: string

Allowed in: <code>"payload"</code>

Example 1: <code>"payload":"Energy measured since ${OUTPUTS/1/ENERGY_START}"</code>

Example 2: <code>"payload":"${OUTPUTS/1/ENERGY_START_FMT}"</code> is output payload <code>2019-09-05T03:37:19+00:00</code>

==== ENERGY_NR ====
Non-resettable counter of Energy consumed by an device connected to NETIO device output.

Unit: <code>Wh</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Consumed energy on output 1 is ${OUTPUTS/1/ENERGY_NR}Wh"</code>

Example 2: <code>"source":"${OUTPUTS/1/ENERGY_NR}"</code>

==== REVERSE_ENERGY_NR ====
Non-resettable counter of Energy delivered back to grid. For example from solar system connected to NETIO device output.

Unit: <code>Wh</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Delivered energy on output 1 is ${OUTPUTS/1/REVERSE_ENERGY_NR}Wh"</code>

Example 2: <code>"source":"${OUTPUTS/1/REVERSE_ENERGY_NR}"</code>

==== TOTALs - for 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
* OUTPUTS/TOTAL/PHASE
* OUTPUTS/TOTAL/REVERSE_ENERGY
* OUTPUTS/TOTAL/ENERGY_NR
* OUTPUTS/TOTAL/REVERSE_ENERGY_NR
* OUTPUTS/TOTAL/ENERGY_START
* OUTPUTS/TOTAL/ENERGY_START_FMT

==== REST_JSON ====
Allow use of NETIO JSON structure to control outputs.

Type: string / JSON

Allowed in: <code>"target"</code> for Subscribe section

Example: <code>"target": "REST_JSON"</code>

The payload is JSON structure identical to NETIO JSON API M2M Protocol (documentation available at https://www.netio-products.com/files/NETIO-M2M-API-Protocol-JSON.pdf). You can control one or multiple outputs.

Payload example 1 - Toggle output 1: <code>{"Outputs":[{"ID": 1,"Action": 4}]}</code>

Payload example 2 - Turn output 1 OFF and output 3 ON: <code>{"Outputs":[{"ID":1,"Action":0},{"ID":3,"Action":1}]}</code>

=== INPUT variables ===
==== STATE ====
Type: bool(integer) - <code>0</code> or <code>1</code>

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Present input 1 state is ${INPUTS/1/STATE}"</code>

Example 2: <code>"source":"${INPUTS/1/STATE}"</code>

==== S0 ====
S0 Counter value
Unit: <code>-</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Input 1 S0 Counter value is ${INPUTS/1/S0}impulses"</code>

Example 2: <code>"source":"${INPUTS/1/S0}"</code>

== Payload/topic variables ==

=== DEVICE_NAME ===
Can be used in: "payload", "topic"

Example 1: <code>"payload":"${DEVICE_NAME}"</code>

Example 2: <code>"topic":"netio/${DEVICE_NAME}/output/1/action"</code>

=== DEVICE_MAC ===
Can be used in: "payload", "topic"

Example 1: <code>"payload":"${DEVICE_MAC}"</code>

Example 2: <code>"topic":"netio/${DEVICE_MAC}/output/1/action"</code>

=== UTC_TIME <code>FW 4.0.0+</code>===

send unix timestamp of devices actual time

Can be used in: "payload"

Example 1: <code>"payload": "${UTC_TIME}"</code>

=== UPTIME Not yet implemented ===

=== PAYLOAD ===
Can be used in: "action"

Example: <code>"action":"${PAYLOAD}"</code>

=== OUTPUT_ID Not yet implemented===

=== WIFI_SIGNALNot yet implemented ===

=== OUTPUTS_STATUS ===
Provide complete outputs status and measurement if supported.

Type: string / JSON

Allowed in: <code>"payload"</code> for Publish section

Example: <code>"payload":"${OUTPUTS_STATUS}"</code>

Payload example: <code>{ "GlobalMeasure":{"Voltage":236,"TotalCurrent":72,"TotalLoad":11,"TotalEnergy":167,"OverallPowerFactor":0.64,"Frequency":50.07,"Phase":-36.86,"EnergyStart":"2020-06-30T17:04:48+01:00"}, "Outputs":[ {"ID":1,"Name":"Power output 1","State":1,"Action":6,"Delay":2020,"Current":72,"PowerFactor":0.64,"Phase":-36.86,"Energy":139,"ReverseEnergy":0,"Load":11}, {"ID":2,"Name":"Power output 2","State":1,"Action":6,"Delay":2020,"Current":0,"PowerFactor":1.00,"Phase":0.00,"Energy":27,"ReverseEnergy":0,"Load":0}, {"ID":3,"Name":"Free Contact 3","State":1,"Action":6,"Delay":2020}, {"ID":4,"Name":"Free Contact 4","State":1,"Action":6,"Delay":2020} ]}</code>

=== INPUTS_STATUS ===
Provide complete inputs status if supported. Since FW 3.0.0

Type: string / JSON

Allowed in: <code>"payload"</code> for Publish section

Example: <code>"payload":"${INPUTS_STATUS}"</code>

Payload example: <code>{ "Inputs":[ {"ID":1,"Name":"Input 1","State":0,"S0Counter":0}, {"ID":2,"Name":"Input 2","State":0,"S0Counter":0} ]}</code>

=== INOUT_STATUS ===
Provide complete inputs and output status and measurement if supported. Since FW 3.0.0

Type: string / JSON

Allowed in: <code>"payload"</code> for Publish section

Example: <code>"payload":"${INOUT_STATUS}"</code>

Payload example: <code>{ "GlobalMeasure":{"Voltage":238,"TotalCurrent":105,"TotalLoad":17,"TotalEnergy":1451,"OverallPowerFactor":0.67,"Frequency":50.03,"Phase":-33.67,"EnergyStart":"2020-06-30T17:04:48+01:00"}, "Outputs":[ {"ID":1,"Name":"Power output 1","State":0,"Action":6,"Delay":5000,"Current":0,"PowerFactor":1.00,"Phase":0.00,"Energy":701,"ReverseEnergy":0,"Load":0}, {"ID":2,"Name":"Power output 2","State":1,"Action":6,"Delay":5000,"Current":105,"PowerFactor":0.65,"Phase":-33.67,"Energy":750,"ReverseEnergy":0,"Load":17}, {"ID":3,"Name":"Free Contact 3","State":1,"Action":6,"Delay":5000}, {"ID":4,"Name":"Free Contact 4","State":0,"Action":6,"Delay":5000} ], "Inputs":[ {"ID":1,"Name":"Input 1","State":0,"S0Counter":0}, {"ID":2,"Name":"Input 2","State":0,"S0Counter":0} ]}</code>

= Extended MQTT flex JSON config examples =

== Default NETIO MQTT-flex configuration ==
This example demonstrates setup for connection to public <code>broker.hivemq.com</code>, measurement reporting and output control.

The device cabe be controlled via <code>netio/${DEVICE_NAME}/output/1/action topic</code> by sending standard NETIO action values:
* 0 - OFF
* 1 - ON
* 2 - SHORT OFF
* 3 - SHORT ON
* 4 - TOGGLE
* 5 - NO ACTION.

The device report measurements:

* Output state - every 15 minutes or by change
* Voltage [V]- every 5 minutes or by change of 1 V
* Current [mA]- every 5 minutes or by change of 50 mA
* Load(Power) [W]- every 5 minutes or by change of 10 W
* Energy(Consumption) [Wh]- every 15 minutes or by change of 1Wh
* True Power Factor (TPF) [-]- every 5 minutes or by change of 0.02
* Frequency [Hz]- every 1 hour or by change of 0.1 Hz

For register all values, you can use wildcard <code>netio/${DEVICE_NAME}/output/1/#</code>

{
"config":{
"broker":{
"url":"broker.hivemq.com",
"protocol":"mqtt",
"port":1883,
"ssl":false,
"type":"generic",
"username":"",
"password":"",
"clientid":"moje${DEVICE_NAME}${DEVICE_MAC}",
"keepalive":30
},
"subscribe":[
{
"topic":"netio/${DEVICE_NAME}/output/1/action",
"qos":0,
"target":"OUTPUTS/1/ACTION",
"action":"${payload}"
},
{
"topic":"netio/${DEVICE_NAME}/output/1/switch",
"qos":0,
"target":"OUTPUTS/1/ACTION",
"action":4
}
],
"publish":[
{
"topic":"netio/${DEVICE_MAC}/output/1/state",
"qos":0,
"retain":true,
"payload":"${OUTPUTS/1/STATE}",
"events":[
{
"type":"change",
"source":"OUTPUTS/1/STATE"
},
{
"type":"timer",
"period":900
}
]
},
{
"topic":"netio/${DEVICE_NAME}/output/1/voltage",
"qos":0,
"retain":false,
"payload":"${OUTPUTS/1/VOLTAGE}",
"events":[
{
"type":"timer",
"period":300
},
{
"type":"delta",
"source":"OUTPUTS/1/VOLTAGE",
"delta":1
}
]
},
{
"topic":"netio/${DEVICE_NAME}/output/1/current",
"qos":0,
"retain":false,
"payload":"${OUTPUTS/1/CURRENT}",
"events":[
{
"type":"timer",
"period":300
},
{
"type":"delta",
"source":"OUTPUTS/1/CURRENT",
"delta":50
}
]
},
{
"topic":"netio/${DEVICE_NAME}/output/1/load",
"qos":0,
"retain":false,
"payload":"${OUTPUTS/1/LOAD}",
"events":[
{
"type":"timer",
"period":300
},
{
"type":"delta",
"source":"OUTPUTS/1/LOAD",
"delta":10
}
]
},
{
"topic":"netio/${DEVICE_NAME}/output/1/energy",
"qos":0,
"retain":false,
"payload":"${OUTPUTS/1/ENERGY}",
"events":[
{
"type":"timer",
"period":900
},
{
"type":"delta",
"source":"OUTPUTS/1/ENERGY",
"delta":1
}
]
},
{
"topic":"netio/${DEVICE_NAME}/output/1/tpf",
"qos":0,
"retain":false,
"payload":"${OUTPUTS/1/POWER_FACTOR}",
"events":[
{
"type":"timer",
"period":900
},
{
"type":"delta",
"source":"OUTPUTS/1/POWER_FACTOR",
"delta":0.02
}
]
},
{
"topic":"netio/${DEVICE_NAME}/output/1/frequency",
"qos":0,
"retain":false,
"payload":"${OUTPUTS/1/FREQUENCY}",
"events":[
{
"type":"timer",
"period":3600
},
{
"type":"delta",
"source":"OUTPUTS/1/FREQUENCY",
"delta":0.1
}
]
}
]
}
}

MQTT-flex

2023-06-13T16:56:45Z

Bbakala: /* UTC_TIME FW 4.0.0+ */

The MQTT-flex version of the MQTT protocol can be configured in detail thanks to the “flex” extension.

https://www.netio-products.com/en/glossary/mqtt-flex

Why MQTT-flex 
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 [https://en.wikipedia.org/wiki/MQTT 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 [https://en.wikipedia.org/wiki/JSON 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 101x 
* PowerCable REST 101x 
* PowerPDU 4PS 
* PowerPDU 4KS 
* PowerPDU 8QS 
* PowerDIN 4PZ 
* PowerBOX 3Px 
* PowerBOX 4Kx 

FW version: 
>2.2.1

===Not supported NETIO devices:===
* PowerPDU 4C 
* NETIO 4 
* NETIO 4All 

= Simple MQTT-flex configuration + explanation =

''We strongly recommend to create and test MQTT-flex configuration on "local" device what can be easily restarted. The validation of config before saving is not 100% and for example some specific typos can cause a freeze of a device - the solution is to restart a device (unplug/plug input power cable). If the configuration is saved and device is working then there are no known failure case so it is safe to use this configuration on the "remote" devices.''

{
"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":false,
"payload":"${OUTPUTS/1/STATE}",
"events":[
{
"type":"timer",
"period":"1000"
}
]
}
]
}
}
=== Client Configuration (broker section) ===
Put here MQTT client connection setup

This configuration example set NETIO device to connect to broker.hivemq.com with mqtt protocol, no ssl connection with credetials freedom/peace|love|empathy4ALL.

"broker":{
"url":"broker.hivemq.com",
"protocol":"mqtt",
"port":1883,
"ssl":false,
"type":"generic",
"username":"freedom",
"password":"peace|LOVE|empathy4ALL"
},

=== Device Control (subscribe section) ===
Put here array of topics where to subscribe

Device output 1 is controlled with action received by subscription to netio/${DEVICE_NAME}/output/1/action topic with QOS 0

"subscribe":[{
"topic":"netio/${DEVICE_NAME}/output/1/action",
"qos":0,
"target":"OUTPUTS/1/ACTION",
"action":"${payload}"
}
],

=== Output State monitoring (publish section) ===
Put here array of topics where to publish.

Device send every 1000 s message to topic with QOS 0, retain true information with output 1 state

"publish":[{
"topic":"netio/${DEVICE_NAME}/output/1/state",
"qos":0,
"retain":true,
"payload":"${OUTPUTS/1/STATE}",
"events":[
{
"type":"timer",
"period":"1000"
}
]
}
]

= 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 ===
{| class="wikitable"
! style="font-weight:bold; background-color:#9b9b9b;" | Item
! style="font-weight:bold; background-color:#9b9b9b;" | Presence
! style="font-weight:bold; background-color:#9b9b9b;" | Possible Values
! style="font-weight:bold; background-color:#9b9b9b;" | Description
! style="font-weight:bold; background-color:#9b9b9b;" | JSON Config Usage
|-
| style="background-color:#efefef;" | url
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" |
| style="background-color:#efefef;" | MQTT broker URL
| style="background-color:#efefef;" | "url":"broker.hivemq.com"
|-
| style="background-color:#efefef;" | port
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | 1 - 65535
| style="background-color:#efefef;" | MQTT broker port
| style="background-color:#efefef;" | "port":1883
|-
| style="background-color:#efefef;" | protocol
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" |
| style="background-color:#efefef;" | protocol spec - mqtt
| style="background-color:#efefef;" | "protocol": "mqtt"
|-
| style="background-color:#efefef;" | ssl
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | true, false
| style="background-color:#efefef;" | Use SSL crypted communication selector
| style="background-color:#efefef;" | "ssl":false
|-
| style="background-color:#efefef;" | type
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | generic
| style="background-color:#efefef;" | Communication/setup type option
| style="background-color:#efefef;" | "type":"generic"
|-
| style="background-color:#efefef;" | username
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | regexp+len
| style="background-color:#efefef;" | Credentials for MQTT broker. Max. 128 characters (since FW 3.2.4).
| style="background-color:#efefef;" | "username":"freedom"
|-
| style="background-color:#efefef;" | password
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | regexp+len
| style="background-color:#efefef;" | Credentials for MQTT broker. Max. 256 characters (since FW 3.2.4).
| style="background-color:#efefef;" | "password":"peace|LOVE|empathy4ALL"
|-
| style="background-color:#efefef;" | clientid
| style="background-color:#efefef;" | optional
| style="background-color:#efefef;" | regexp+len
| style="background-color:#efefef;" | MQTT clientid. Max. 128 characters (since FW 3.2.4). Variables ${DEVICE_MAC} or ${DEVICE_NAME} can be used
| style="background-color:#efefef;" | "clientid":"myEcoTable01"
|-
| style="background-color:#efefef;" | keepalive
| style="background-color:#efefef;" | optional
| style="background-color:#efefef;" | 1 - 65535
| style="background-color:#efefef;" | MQTT keep alive period in seconds
| style="background-color:#efefef;" | "keepalive":90
|}

Note 1: clientid attribute is mandatory for MQTT(s) communication. When not configured, random ID will be generated.

Note 2: To proper communication with MS Azure - it is necessary to set up IoT Hub to use TLS 1.2

See section "TLS 1.2 enforcement available in select regions" in following guidelines https://docs.microsoft.com/en-us/azure/iot-hub/iot-hub-tls-support

=== Examples ===
==== Standard setup ====

==== Security (SSL / TLS) secured setup ====
You can enable MQTTs by using the encrypted port 8883 + "ssl":true.

==== Variables used setup ====

== 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 ===
{| class="wikitable"
! style="font-weight:bold; background-color:#9b9b9b;" | Item
! style="font-weight:bold; background-color:#9b9b9b;" | Presence
! style="font-weight:bold; background-color:#9b9b9b;" | Possible Values
! style="font-weight:bold; background-color:#9b9b9b;" | Description
! style="font-weight:bold; background-color:#9b9b9b;" | JSON Config Usage
|-
| style="background-color:#efefef;" | topic
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | see table below
| style="background-color:#efefef;" | specification of the topic, which MQTT-flex device listens from broker and act accordingly. Max. 128 characters. The "#" can be used since FW 3.2.4 - see note under this table.
| style="background-color:#efefef;" | "topic":"netio/${DEVICE_NAME}/output/1/action"
|-
| style="background-color:#efefef;" | qos
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | 0, 1 or 2
| style="background-color:#efefef;" | 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}
| style="background-color:#efefef;" | "qos":0
|-
| style="background-color:#efefef;" | target
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" |
| style="background-color:#efefef;" | internal definition of action, which can be performed above the specified output
| style="background-color:#efefef;" | "target":"OUTPUTS/1/ACTION"
|-
| style="background-color:#efefef;" | action
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" |
| style="background-color:#efefef;" | a payload or a value the action attribute needs to have passed to
| style="background-color:#efefef;" | "action":"${payload}"
|-
| style="background-color:#efefef;" | actiondefNot supported yet
| style="background-color:#efefef;" | optional
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
|-
| style="background-color:#efefef;" | jsonNot supported yet
| style="background-color:#efefef;" | optional
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
|}

Note: The "#" wildcard can be used in subscribe topic definition. The multi-level wildcard character MUST be specified either on its own or following a topic level separator. In either case it MUST be the last character specified in the Topic.

For example, if a Device subscribes to “devices/{device_id}/messages/devicebound/#”, it would receive messages published using these topic names:

“devices/{device_id}/messages/devicebound/”

“devices/{device_id}/messages/devicebound/{property_bag}”

This should be usefull for use with MS Azure - IoT hub.

=== MQTT Subscribe as event to trigger action <code>FW 4.0.0+</code> ===

This feature allow to subscribe to specific MQTT topic and pass payload to Rules or MQTT-flex as event.

target: <code>PROTOCOLS/MQTT/EVENT</code>

"subscribe": [
{
"action": "${payload}",
"qos": 0,
"target": "PROTOCOLS/MQTT/EVENT",
"topic": "broker/12345/MQTT_EVENT/"
}
]

=== Examples ===
==== Toggle output with standard payload ====
==== Toggle output with custom payload ====
==== Subscribe to more than one topic ====
==== Trigger Rule and MQTT publish from MQTT subscribe <code>FW 4.0.0+</code> ====
This example show Request response implementation in MQTT and toggle action made by Rules.

When message with payload <code>getValues</code> is published to topic <code>broker/gv90018g/COMMAND</code> MQTT flex will create an event with name <code>PROTOCOLS/MQTT/EVENT</code> (fixed name cannot be changed) and value <code>getValues</code>. On this event will act all events and conditions set in MQTT-flex and Rules which are set to listening to change on <code>PROTOCOLS/MQTT/EVENT</code> and equals to value <code>getValues</code>. See bold marked parameters in example configuration below.

Once the triggered action is done it is needed to reset MQTT channel to <code>OK</code> status becaus event are reacting only to change. If the channel is not reset the next even would not be triggered.

Rules Configuration:
{
"conditions": {
"PROTOCOLS/MQTT/EVENT": "getValues"
},
"actions": {
"OUTPUTS/1/ACTION": 4
}
}

MQTT Configuration:
{
"broker":{
"clientid":"netio${DEVICE_SN}",
"keepalive":30,
"password":"abcdefghijk",
"port":8883,
"protocol":"mqtt",
"ssl":true,
"type":"generic",
"url":"broker.cloud.netio.eu",
"username":"gv90018g"
},
"groupEvents":[
{
"events":[
{
"source":"PROTOCOLS/MQTT/EVENT",
"type":"change",
"value":"getValues"
}
],
"appliedTopics":[
"broker/gv90018g/OUTPUTS/1/STATE",
"broker/gv90018g/COMMAND"
]
}
],
"publish":[
{
"payload":"${OUTPUTS/1/STATE}",
"qos":0,
"retain":true,
"topic":"broker/gv90018g/OUTPUTS/1/STATE"
},
{
"payload":"OK",
"qos":0,
"retain":true,
"topic":"broker/gv90018g/COMMAND"
}
],
"subscribe":[
{
"action":"${payload}",
"qos":0,
"target":"PROTOCOLS/MQTT/EVENT",
"topic":"broker/gv90018g/COMMAND"
}
]
}

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 ===
{| class="wikitable"
! style="font-weight:bold; background-color:#9b9b9b;" | Item
! style="font-weight:bold; background-color:#9b9b9b;" | Presence
! style="font-weight:bold; background-color:#9b9b9b;" | Possible Values
! style="font-weight:bold; background-color:#9b9b9b;" | Description
! style="font-weight:bold; background-color:#9b9b9b;" | JSON Config Usage
|-
| style="background-color:#efefef;" | topic
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | see table below
| style="background-color:#efefef;" | definition of the topic, how it is registered towards MQTT broker. Max. 128 characters.
| style="background-color:#efefef;" | "topic":"netio/${DEVICE_NAME}/output/1/load"
|-
| style="background-color:#efefef;" | qos
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | see table below
| style="background-color:#efefef;" | 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}
| style="background-color:#efefef;" |
|-
| style="background-color:#efefef;" | retain
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | boolean: true or false
| style="background-color:#efefef;" | 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}
| style="background-color:#efefef;" | "retain":true
|-
| style="background-color:#efefef;" | payload
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | see table below
| style="background-color:#efefef;" | definition of the payload, what is send to the MQTT broker.
| style="background-color:#efefef;" | "payload":"${OUTPUTS/1/STATE}"
|-
| style="background-color:#efefef;" | events
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | see table below
| style="background-color:#efefef;" | definition of events used for triggering sending of data via mqtt (change, delta, timer)
| style="background-color:#efefef;" |
|-
| style="background-color:#efefef;" | type
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
|-
| style="background-color:#efefef;" | source
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
|-
| style="background-color:#efefef;" | delta
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
|-
| style="background-color:#efefef;" | period
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
|-
| style="background-color:#efefef;" | payloaddefNot supported yet
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
|}

=== Examples ===
==== Publish energy periodically (event timer) ====
==== Publish current on change (delta) ====
==== Publish output state ====
==== Publish to more than one topic with different events ====

= 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 available only on NETIO PowerDIN 4PZ

=== Examples: ===

adressing controll of output 3
OUTPUTS/3/ACTION
getting voltage on output 1
OUTPUTS/1/VOLTAGE
getting state of input 1
INPUTS/1/STATE

= Group Events<code>FW 4.0.0+</code> =
Group events are smart way how to keep configuration simple. It is not replacement of publish section specification but it is extension to trigger group of different topics to be published on the same event.

See the example below. There is specific event on status change on every output and additionally the device sends periodic status every 60 seconds.

{
"broker": {
"clientid": "netio${DEVICE_SN}",
"keepalive": 30,
"password": "",
"port": 1883,
"protocol": "mqtt",
"ssl": false,
"type": "generic",
"url": "broker.hivemq.com",
"username": ""
},
"groupEvents": [
{
"events":[
{
"period": 60,
"type": "timer"
}
],
"appliedTopics":[
"devices/${DEVICE_NAME}/output/1/state",
"devices/${DEVICE_NAME}/output/2/state"
]
}
],
"publish": [
{
"events": [
{
"source": "OUTPUTS/1/STATE",
"type": "change"
}
],
"payload": "${OUTPUTS/1/STATE}",
"qos": 0,
"retain": false,
 "topic": "devices/${DEVICE_NAME}/output/1/state"
},{
"events": [
{
"source": "OUTPUTS/2/STATE",
"type": "change"
}
],
"payload": "${OUTPUTS/2/STATE}",
"qos": 0,
"retain": false,
 "topic": "devices/${DEVICE_NAME}/output/2/state"
}
]
}

= 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 ===
==== VOLTAGE ====
Unit: <code>V</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Present RMS voltage on output 1 is ${OUTPUTS/1/VOLTAGE}"</code>

Example 2: <code>"source":"${OUTPUTS/1/VOLTAGE}"</code>

==== CURRENT ====
Unit: <code>mA</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Present RMS current on output 1 is ${OUTPUTS/1/CURRENT}"</code>

Example 2: <code>"source":"${OUTPUTS/1/CURRENT}"</code>

==== POWER_FACTOR ====
Unit: <code>[-]</code>

Type: float (2 decimals)

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"True Power Factor on output 1 is ${OUTPUTS/1/POWER_FACTOR}"</code>

Example 2: <code>"source":"${OUTPUTS/1/POWER_FACTOR}"</code>

==== LOAD ====
Unit: <code>W</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Present load on output 1 is ${OUTPUTS/1/LOAD}W"</code>

Example 2: <code>"payload":"Device's load connected to output 1 is ${OUTPUTS/1/LOAD}W"</code>

Example 3: <code>"source":"${OUTPUTS/1/LOAD}"</code>

==== STATE ====
Type: bool(integer) - <code>0</code> or <code>1</code>

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Present output 1 state is ${OUTPUTS/1/STATE}"</code>

Example 2: <code>"source":"${OUTPUTS/1/STATE}"</code>

==== ACTION ====
Type: integer

Possible actions:
* <code>0</code> - set state OFF
* <code>1</code> - set state ON
* <code>2</code> - short OFF (restart)
* <code>3</code> - short ON
* <code>4</code> - toggle (switch)
* <code>5</code> - no change

Allowed in: <code>"target"</code>

Example: <code>"target":"OUTPUTS/1/ACTION"</code>

==== DELAY [ms] ====
==== NAME ====
==== FREQUENCY ====
Unit: <code>Hz</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example: <code>"payload":"Frequency in power grid is ${OUTPUTS/1/ENERGY}Hz"</code>

==== ENERGY ====
Energy consumed by an device connected to NETIO device output.

Unit: <code>Wh</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Consumed energy on output 1 is ${OUTPUTS/1/ENERGY}Wh"</code>

Example 2: <code>"source":"${OUTPUTS/1/ENERGY}"</code>

==== REVERSE_ENERGY ====
Energy delivered back to grid. For example from solar system connected to NETIO device output.

Unit: <code>Wh</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Delivered energy on output 1 is ${OUTPUTS/1/REVERSE_ENERGY}Wh"</code>

Example 2: <code>"source":"${OUTPUTS/1/REVERSE_ENERGY}"</code>

==== ENERGY_START ====
Date when the counters ENERGY and REVERSE_ENERGY have been resetted by user.

Unit: <code>unix timestamp</code>

Type: integer

Allowed in: <code>"payload"</code>

Example 1: <code>"payload":"Energy measured since ${OUTPUTS/1/ENERGY_START} unix time"</code>

Example 2: <code>"payload":"${OUTPUTS/1/ENERGY_START}"</code> is output payload <code>1567654639</code>

==== ENERGY_START_FMT ====
Date when the counters ENERGY and REVERSE_ENERGY have been resetted by user.

Unit: <code>fmt date format</code>

Type: string

Allowed in: <code>"payload"</code>

Example 1: <code>"payload":"Energy measured since ${OUTPUTS/1/ENERGY_START}"</code>

Example 2: <code>"payload":"${OUTPUTS/1/ENERGY_START_FMT}"</code> is output payload <code>2019-09-05T03:37:19+00:00</code>

==== ENERGY_NR ====
Non-resettable counter of Energy consumed by an device connected to NETIO device output.

Unit: <code>Wh</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Consumed energy on output 1 is ${OUTPUTS/1/ENERGY_NR}Wh"</code>

Example 2: <code>"source":"${OUTPUTS/1/ENERGY_NR}"</code>

==== REVERSE_ENERGY_NR ====
Non-resettable counter of Energy delivered back to grid. For example from solar system connected to NETIO device output.

Unit: <code>Wh</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Delivered energy on output 1 is ${OUTPUTS/1/REVERSE_ENERGY_NR}Wh"</code>

Example 2: <code>"source":"${OUTPUTS/1/REVERSE_ENERGY_NR}"</code>

==== TOTALs - for 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
* OUTPUTS/TOTAL/PHASE
* OUTPUTS/TOTAL/REVERSE_ENERGY
* OUTPUTS/TOTAL/ENERGY_NR
* OUTPUTS/TOTAL/REVERSE_ENERGY_NR
* OUTPUTS/TOTAL/ENERGY_START
* OUTPUTS/TOTAL/ENERGY_START_FMT

==== REST_JSON ====
Allow use of NETIO JSON structure to control outputs.

Type: string / JSON

Allowed in: <code>"target"</code> for Subscribe section

Example: <code>"target": "REST_JSON"</code>

The payload is JSON structure identical to NETIO JSON API M2M Protocol (documentation available at https://www.netio-products.com/files/NETIO-M2M-API-Protocol-JSON.pdf). You can control one or multiple outputs.

Payload example 1 - Toggle output 1: <code>{"Outputs":[{"ID": 1,"Action": 4}]}</code>

Payload example 2 - Turn output 1 OFF and output 3 ON: <code>{"Outputs":[{"ID":1,"Action":0},{"ID":3,"Action":1}]}</code>

=== INPUT variables ===
==== STATE ====
Type: bool(integer) - <code>0</code> or <code>1</code>

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Present input 1 state is ${INPUTS/1/STATE}"</code>

Example 2: <code>"source":"${INPUTS/1/STATE}"</code>

==== S0 ====
S0 Counter value
Unit: <code>-</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Input 1 S0 Counter value is ${INPUTS/1/S0}impulses"</code>

Example 2: <code>"source":"${INPUTS/1/S0}"</code>

== Payload/topic variables ==

=== DEVICE_NAME ===
Can be used in: "payload", "topic"

Example 1: <code>"payload":"${DEVICE_NAME}"</code>

Example 2: <code>"topic":"netio/${DEVICE_NAME}/output/1/action"</code>

=== DEVICE_MAC ===

=== UTC_TIME <code>FW 4.0.0+</code>===

send unix timestamp of devices actual time

Can be used in: "payload"

Example 1: <code>"payload": "${UTC_TIME}"</code>

=== UPTIME Not yet implemented ===

=== PAYLOAD ===
Can be used in: "action"

Example: <code>"action":"${PAYLOAD}"</code>

=== OUTPUT_ID Not yet implemented===

=== WIFI_SIGNALNot yet implemented ===

=== OUTPUTS_STATUS ===
Provide complete outputs status and measurement if supported.

Type: string / JSON

Allowed in: <code>"payload"</code> for Publish section

Example: <code>"payload":"${OUTPUTS_STATUS}"</code>

Payload example: <code>{ "GlobalMeasure":{"Voltage":236,"TotalCurrent":72,"TotalLoad":11,"TotalEnergy":167,"OverallPowerFactor":0.64,"Frequency":50.07,"Phase":-36.86,"EnergyStart":"2020-06-30T17:04:48+01:00"}, "Outputs":[ {"ID":1,"Name":"Power output 1","State":1,"Action":6,"Delay":2020,"Current":72,"PowerFactor":0.64,"Phase":-36.86,"Energy":139,"ReverseEnergy":0,"Load":11}, {"ID":2,"Name":"Power output 2","State":1,"Action":6,"Delay":2020,"Current":0,"PowerFactor":1.00,"Phase":0.00,"Energy":27,"ReverseEnergy":0,"Load":0}, {"ID":3,"Name":"Free Contact 3","State":1,"Action":6,"Delay":2020}, {"ID":4,"Name":"Free Contact 4","State":1,"Action":6,"Delay":2020} ]}</code>

=== INPUTS_STATUS ===
Provide complete inputs status if supported. Since FW 3.0.0

Type: string / JSON

Allowed in: <code>"payload"</code> for Publish section

Example: <code>"payload":"${INPUTS_STATUS}"</code>

Payload example: <code>{ "Inputs":[ {"ID":1,"Name":"Input 1","State":0,"S0Counter":0}, {"ID":2,"Name":"Input 2","State":0,"S0Counter":0} ]}</code>

=== INOUT_STATUS ===
Provide complete inputs and output status and measurement if supported. Since FW 3.0.0

Type: string / JSON

Allowed in: <code>"payload"</code> for Publish section

Example: <code>"payload":"${INOUT_STATUS}"</code>

Payload example: <code>{ "GlobalMeasure":{"Voltage":238,"TotalCurrent":105,"TotalLoad":17,"TotalEnergy":1451,"OverallPowerFactor":0.67,"Frequency":50.03,"Phase":-33.67,"EnergyStart":"2020-06-30T17:04:48+01:00"}, "Outputs":[ {"ID":1,"Name":"Power output 1","State":0,"Action":6,"Delay":5000,"Current":0,"PowerFactor":1.00,"Phase":0.00,"Energy":701,"ReverseEnergy":0,"Load":0}, {"ID":2,"Name":"Power output 2","State":1,"Action":6,"Delay":5000,"Current":105,"PowerFactor":0.65,"Phase":-33.67,"Energy":750,"ReverseEnergy":0,"Load":17}, {"ID":3,"Name":"Free Contact 3","State":1,"Action":6,"Delay":5000}, {"ID":4,"Name":"Free Contact 4","State":0,"Action":6,"Delay":5000} ], "Inputs":[ {"ID":1,"Name":"Input 1","State":0,"S0Counter":0}, {"ID":2,"Name":"Input 2","State":0,"S0Counter":0} ]}</code>

= Extended MQTT flex JSON config examples =

== Default NETIO MQTT-flex configuration ==
This example demonstrates setup for connection to public <code>broker.hivemq.com</code>, measurement reporting and output control.

The device cabe be controlled via <code>netio/${DEVICE_NAME}/output/1/action topic</code> by sending standard NETIO action values:
* 0 - OFF
* 1 - ON
* 2 - SHORT OFF
* 3 - SHORT ON
* 4 - TOGGLE
* 5 - NO ACTION.

The device report measurements:

* Output state - every 15 minutes or by change
* Voltage [V]- every 5 minutes or by change of 1 V
* Current [mA]- every 5 minutes or by change of 50 mA
* Load(Power) [W]- every 5 minutes or by change of 10 W
* Energy(Consumption) [Wh]- every 15 minutes or by change of 1Wh
* True Power Factor (TPF) [-]- every 5 minutes or by change of 0.02
* Frequency [Hz]- every 1 hour or by change of 0.1 Hz

For register all values, you can use wildcard <code>netio/${DEVICE_NAME}/output/1/#</code>

{
"config":{
"broker":{
"url":"broker.hivemq.com",
"protocol":"mqtt",
"port":1883,
"ssl":false,
"type":"generic",
"username":"",
"password":"",
"clientid":"moje${DEVICE_NAME}${DEVICE_MAC}",
"keepalive":30
},
"subscribe":[
{
"topic":"netio/${DEVICE_NAME}/output/1/action",
"qos":0,
"target":"OUTPUTS/1/ACTION",
"action":"${payload}"
},
{
"topic":"netio/${DEVICE_NAME}/output/1/switch",
"qos":0,
"target":"OUTPUTS/1/ACTION",
"action":4
}
],
"publish":[
{
"topic":"netio/${DEVICE_MAC}/output/1/state",
"qos":0,
"retain":true,
"payload":"${OUTPUTS/1/STATE}",
"events":[
{
"type":"change",
"source":"OUTPUTS/1/STATE"
},
{
"type":"timer",
"period":900
}
]
},
{
"topic":"netio/${DEVICE_NAME}/output/1/voltage",
"qos":0,
"retain":false,
"payload":"${OUTPUTS/1/VOLTAGE}",
"events":[
{
"type":"timer",
"period":300
},
{
"type":"delta",
"source":"OUTPUTS/1/VOLTAGE",
"delta":1
}
]
},
{
"topic":"netio/${DEVICE_NAME}/output/1/current",
"qos":0,
"retain":false,
"payload":"${OUTPUTS/1/CURRENT}",
"events":[
{
"type":"timer",
"period":300
},
{
"type":"delta",
"source":"OUTPUTS/1/CURRENT",
"delta":50
}
]
},
{
"topic":"netio/${DEVICE_NAME}/output/1/load",
"qos":0,
"retain":false,
"payload":"${OUTPUTS/1/LOAD}",
"events":[
{
"type":"timer",
"period":300
},
{
"type":"delta",
"source":"OUTPUTS/1/LOAD",
"delta":10
}
]
},
{
"topic":"netio/${DEVICE_NAME}/output/1/energy",
"qos":0,
"retain":false,
"payload":"${OUTPUTS/1/ENERGY}",
"events":[
{
"type":"timer",
"period":900
},
{
"type":"delta",
"source":"OUTPUTS/1/ENERGY",
"delta":1
}
]
},
{
"topic":"netio/${DEVICE_NAME}/output/1/tpf",
"qos":0,
"retain":false,
"payload":"${OUTPUTS/1/POWER_FACTOR}",
"events":[
{
"type":"timer",
"period":900
},
{
"type":"delta",
"source":"OUTPUTS/1/POWER_FACTOR",
"delta":0.02
}
]
},
{
"topic":"netio/${DEVICE_NAME}/output/1/frequency",
"qos":0,
"retain":false,
"payload":"${OUTPUTS/1/FREQUENCY}",
"events":[
{
"type":"timer",
"period":3600
},
{
"type":"delta",
"source":"OUTPUTS/1/FREQUENCY",
"delta":0.1
}
]
}
]
}
}

MQTT-flex

2023-06-13T16:54:01Z

Bbakala: /* UTC_TIME */

The MQTT-flex version of the MQTT protocol can be configured in detail thanks to the “flex” extension.

https://www.netio-products.com/en/glossary/mqtt-flex

Why MQTT-flex 
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 [https://en.wikipedia.org/wiki/MQTT 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 [https://en.wikipedia.org/wiki/JSON 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 101x 
* PowerCable REST 101x 
* PowerPDU 4PS 
* PowerPDU 4KS 
* PowerPDU 8QS 
* PowerDIN 4PZ 
* PowerBOX 3Px 
* PowerBOX 4Kx 

FW version: 
>2.2.1

===Not supported NETIO devices:===
* PowerPDU 4C 
* NETIO 4 
* NETIO 4All 

= Simple MQTT-flex configuration + explanation =

''We strongly recommend to create and test MQTT-flex configuration on "local" device what can be easily restarted. The validation of config before saving is not 100% and for example some specific typos can cause a freeze of a device - the solution is to restart a device (unplug/plug input power cable). If the configuration is saved and device is working then there are no known failure case so it is safe to use this configuration on the "remote" devices.''

{
"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":false,
"payload":"${OUTPUTS/1/STATE}",
"events":[
{
"type":"timer",
"period":"1000"
}
]
}
]
}
}
=== Client Configuration (broker section) ===
Put here MQTT client connection setup

This configuration example set NETIO device to connect to broker.hivemq.com with mqtt protocol, no ssl connection with credetials freedom/peace|love|empathy4ALL.

"broker":{
"url":"broker.hivemq.com",
"protocol":"mqtt",
"port":1883,
"ssl":false,
"type":"generic",
"username":"freedom",
"password":"peace|LOVE|empathy4ALL"
},

=== Device Control (subscribe section) ===
Put here array of topics where to subscribe

Device output 1 is controlled with action received by subscription to netio/${DEVICE_NAME}/output/1/action topic with QOS 0

"subscribe":[{
"topic":"netio/${DEVICE_NAME}/output/1/action",
"qos":0,
"target":"OUTPUTS/1/ACTION",
"action":"${payload}"
}
],

=== Output State monitoring (publish section) ===
Put here array of topics where to publish.

Device send every 1000 s message to topic with QOS 0, retain true information with output 1 state

"publish":[{
"topic":"netio/${DEVICE_NAME}/output/1/state",
"qos":0,
"retain":true,
"payload":"${OUTPUTS/1/STATE}",
"events":[
{
"type":"timer",
"period":"1000"
}
]
}
]

= 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 ===
{| class="wikitable"
! style="font-weight:bold; background-color:#9b9b9b;" | Item
! style="font-weight:bold; background-color:#9b9b9b;" | Presence
! style="font-weight:bold; background-color:#9b9b9b;" | Possible Values
! style="font-weight:bold; background-color:#9b9b9b;" | Description
! style="font-weight:bold; background-color:#9b9b9b;" | JSON Config Usage
|-
| style="background-color:#efefef;" | url
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" |
| style="background-color:#efefef;" | MQTT broker URL
| style="background-color:#efefef;" | "url":"broker.hivemq.com"
|-
| style="background-color:#efefef;" | port
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | 1 - 65535
| style="background-color:#efefef;" | MQTT broker port
| style="background-color:#efefef;" | "port":1883
|-
| style="background-color:#efefef;" | protocol
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" |
| style="background-color:#efefef;" | protocol spec - mqtt
| style="background-color:#efefef;" | "protocol": "mqtt"
|-
| style="background-color:#efefef;" | ssl
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | true, false
| style="background-color:#efefef;" | Use SSL crypted communication selector
| style="background-color:#efefef;" | "ssl":false
|-
| style="background-color:#efefef;" | type
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | generic
| style="background-color:#efefef;" | Communication/setup type option
| style="background-color:#efefef;" | "type":"generic"
|-
| style="background-color:#efefef;" | username
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | regexp+len
| style="background-color:#efefef;" | Credentials for MQTT broker. Max. 128 characters (since FW 3.2.4).
| style="background-color:#efefef;" | "username":"freedom"
|-
| style="background-color:#efefef;" | password
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | regexp+len
| style="background-color:#efefef;" | Credentials for MQTT broker. Max. 256 characters (since FW 3.2.4).
| style="background-color:#efefef;" | "password":"peace|LOVE|empathy4ALL"
|-
| style="background-color:#efefef;" | clientid
| style="background-color:#efefef;" | optional
| style="background-color:#efefef;" | regexp+len
| style="background-color:#efefef;" | MQTT clientid. Max. 128 characters (since FW 3.2.4). Variables ${DEVICE_MAC} or ${DEVICE_NAME} can be used
| style="background-color:#efefef;" | "clientid":"myEcoTable01"
|-
| style="background-color:#efefef;" | keepalive
| style="background-color:#efefef;" | optional
| style="background-color:#efefef;" | 1 - 65535
| style="background-color:#efefef;" | MQTT keep alive period in seconds
| style="background-color:#efefef;" | "keepalive":90
|}

Note 1: clientid attribute is mandatory for MQTT(s) communication. When not configured, random ID will be generated.

Note 2: To proper communication with MS Azure - it is necessary to set up IoT Hub to use TLS 1.2

See section "TLS 1.2 enforcement available in select regions" in following guidelines https://docs.microsoft.com/en-us/azure/iot-hub/iot-hub-tls-support

=== Examples ===
==== Standard setup ====

==== Security (SSL / TLS) secured setup ====
You can enable MQTTs by using the encrypted port 8883 + "ssl":true.

==== Variables used setup ====

== 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 ===
{| class="wikitable"
! style="font-weight:bold; background-color:#9b9b9b;" | Item
! style="font-weight:bold; background-color:#9b9b9b;" | Presence
! style="font-weight:bold; background-color:#9b9b9b;" | Possible Values
! style="font-weight:bold; background-color:#9b9b9b;" | Description
! style="font-weight:bold; background-color:#9b9b9b;" | JSON Config Usage
|-
| style="background-color:#efefef;" | topic
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | see table below
| style="background-color:#efefef;" | specification of the topic, which MQTT-flex device listens from broker and act accordingly. Max. 128 characters. The "#" can be used since FW 3.2.4 - see note under this table.
| style="background-color:#efefef;" | "topic":"netio/${DEVICE_NAME}/output/1/action"
|-
| style="background-color:#efefef;" | qos
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | 0, 1 or 2
| style="background-color:#efefef;" | 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}
| style="background-color:#efefef;" | "qos":0
|-
| style="background-color:#efefef;" | target
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" |
| style="background-color:#efefef;" | internal definition of action, which can be performed above the specified output
| style="background-color:#efefef;" | "target":"OUTPUTS/1/ACTION"
|-
| style="background-color:#efefef;" | action
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" |
| style="background-color:#efefef;" | a payload or a value the action attribute needs to have passed to
| style="background-color:#efefef;" | "action":"${payload}"
|-
| style="background-color:#efefef;" | actiondefNot supported yet
| style="background-color:#efefef;" | optional
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
|-
| style="background-color:#efefef;" | jsonNot supported yet
| style="background-color:#efefef;" | optional
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
|}

Note: The "#" wildcard can be used in subscribe topic definition. The multi-level wildcard character MUST be specified either on its own or following a topic level separator. In either case it MUST be the last character specified in the Topic.

For example, if a Device subscribes to “devices/{device_id}/messages/devicebound/#”, it would receive messages published using these topic names:

“devices/{device_id}/messages/devicebound/”

“devices/{device_id}/messages/devicebound/{property_bag}”

This should be usefull for use with MS Azure - IoT hub.

=== MQTT Subscribe as event to trigger action <code>FW 4.0.0+</code> ===

This feature allow to subscribe to specific MQTT topic and pass payload to Rules or MQTT-flex as event.

target: <code>PROTOCOLS/MQTT/EVENT</code>

"subscribe": [
{
"action": "${payload}",
"qos": 0,
"target": "PROTOCOLS/MQTT/EVENT",
"topic": "broker/12345/MQTT_EVENT/"
}
]

=== Examples ===
==== Toggle output with standard payload ====
==== Toggle output with custom payload ====
==== Subscribe to more than one topic ====
==== Trigger Rule and MQTT publish from MQTT subscribe <code>FW 4.0.0+</code> ====
This example show Request response implementation in MQTT and toggle action made by Rules.

When message with payload <code>getValues</code> is published to topic <code>broker/gv90018g/COMMAND</code> MQTT flex will create an event with name <code>PROTOCOLS/MQTT/EVENT</code> (fixed name cannot be changed) and value <code>getValues</code>. On this event will act all events and conditions set in MQTT-flex and Rules which are set to listening to change on <code>PROTOCOLS/MQTT/EVENT</code> and equals to value <code>getValues</code>. See bold marked parameters in example configuration below.

Once the triggered action is done it is needed to reset MQTT channel to <code>OK</code> status becaus event are reacting only to change. If the channel is not reset the next even would not be triggered.

Rules Configuration:
{
"conditions": {
"PROTOCOLS/MQTT/EVENT": "getValues"
},
"actions": {
"OUTPUTS/1/ACTION": 4
}
}

MQTT Configuration:
{
"broker":{
"clientid":"netio${DEVICE_SN}",
"keepalive":30,
"password":"abcdefghijk",
"port":8883,
"protocol":"mqtt",
"ssl":true,
"type":"generic",
"url":"broker.cloud.netio.eu",
"username":"gv90018g"
},
"groupEvents":[
{
"events":[
{
"source":"PROTOCOLS/MQTT/EVENT",
"type":"change",
"value":"getValues"
}
],
"appliedTopics":[
"broker/gv90018g/OUTPUTS/1/STATE",
"broker/gv90018g/COMMAND"
]
}
],
"publish":[
{
"payload":"${OUTPUTS/1/STATE}",
"qos":0,
"retain":true,
"topic":"broker/gv90018g/OUTPUTS/1/STATE"
},
{
"payload":"OK",
"qos":0,
"retain":true,
"topic":"broker/gv90018g/COMMAND"
}
],
"subscribe":[
{
"action":"${payload}",
"qos":0,
"target":"PROTOCOLS/MQTT/EVENT",
"topic":"broker/gv90018g/COMMAND"
}
]
}

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 ===
{| class="wikitable"
! style="font-weight:bold; background-color:#9b9b9b;" | Item
! style="font-weight:bold; background-color:#9b9b9b;" | Presence
! style="font-weight:bold; background-color:#9b9b9b;" | Possible Values
! style="font-weight:bold; background-color:#9b9b9b;" | Description
! style="font-weight:bold; background-color:#9b9b9b;" | JSON Config Usage
|-
| style="background-color:#efefef;" | topic
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | see table below
| style="background-color:#efefef;" | definition of the topic, how it is registered towards MQTT broker. Max. 128 characters.
| style="background-color:#efefef;" | "topic":"netio/${DEVICE_NAME}/output/1/load"
|-
| style="background-color:#efefef;" | qos
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | see table below
| style="background-color:#efefef;" | 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}
| style="background-color:#efefef;" |
|-
| style="background-color:#efefef;" | retain
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | boolean: true or false
| style="background-color:#efefef;" | 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}
| style="background-color:#efefef;" | "retain":true
|-
| style="background-color:#efefef;" | payload
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | see table below
| style="background-color:#efefef;" | definition of the payload, what is send to the MQTT broker.
| style="background-color:#efefef;" | "payload":"${OUTPUTS/1/STATE}"
|-
| style="background-color:#efefef;" | events
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | see table below
| style="background-color:#efefef;" | definition of events used for triggering sending of data via mqtt (change, delta, timer)
| style="background-color:#efefef;" |
|-
| style="background-color:#efefef;" | type
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
|-
| style="background-color:#efefef;" | source
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
|-
| style="background-color:#efefef;" | delta
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
|-
| style="background-color:#efefef;" | period
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
|-
| style="background-color:#efefef;" | payloaddefNot supported yet
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
|}

=== Examples ===
==== Publish energy periodically (event timer) ====
==== Publish current on change (delta) ====
==== Publish output state ====
==== Publish to more than one topic with different events ====

= 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 available only on NETIO PowerDIN 4PZ

=== Examples: ===

adressing controll of output 3
OUTPUTS/3/ACTION
getting voltage on output 1
OUTPUTS/1/VOLTAGE
getting state of input 1
INPUTS/1/STATE

= Group Events<code>FW 4.0.0+</code> =
Group events are smart way how to keep configuration simple. It is not replacement of publish section specification but it is extension to trigger group of different topics to be published on the same event.

See the example below. There is specific event on status change on every output and additionally the device sends periodic status every 60 seconds.

{
"broker": {
"clientid": "netio${DEVICE_SN}",
"keepalive": 30,
"password": "",
"port": 1883,
"protocol": "mqtt",
"ssl": false,
"type": "generic",
"url": "broker.hivemq.com",
"username": ""
},
"groupEvents": [
{
"events":[
{
"period": 60,
"type": "timer"
}
],
"appliedTopics":[
"devices/${DEVICE_NAME}/output/1/state",
"devices/${DEVICE_NAME}/output/2/state"
]
}
],
"publish": [
{
"events": [
{
"source": "OUTPUTS/1/STATE",
"type": "change"
}
],
"payload": "${OUTPUTS/1/STATE}",
"qos": 0,
"retain": false,
 "topic": "devices/${DEVICE_NAME}/output/1/state"
},{
"events": [
{
"source": "OUTPUTS/2/STATE",
"type": "change"
}
],
"payload": "${OUTPUTS/2/STATE}",
"qos": 0,
"retain": false,
 "topic": "devices/${DEVICE_NAME}/output/2/state"
}
]
}

= 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 ===
==== VOLTAGE ====
Unit: <code>V</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Present RMS voltage on output 1 is ${OUTPUTS/1/VOLTAGE}"</code>

Example 2: <code>"source":"${OUTPUTS/1/VOLTAGE}"</code>

==== CURRENT ====
Unit: <code>mA</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Present RMS current on output 1 is ${OUTPUTS/1/CURRENT}"</code>

Example 2: <code>"source":"${OUTPUTS/1/CURRENT}"</code>

==== POWER_FACTOR ====
Unit: <code>[-]</code>

Type: float (2 decimals)

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"True Power Factor on output 1 is ${OUTPUTS/1/POWER_FACTOR}"</code>

Example 2: <code>"source":"${OUTPUTS/1/POWER_FACTOR}"</code>

==== LOAD ====
Unit: <code>W</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Present load on output 1 is ${OUTPUTS/1/LOAD}W"</code>

Example 2: <code>"payload":"Device's load connected to output 1 is ${OUTPUTS/1/LOAD}W"</code>

Example 3: <code>"source":"${OUTPUTS/1/LOAD}"</code>

==== STATE ====
Type: bool(integer) - <code>0</code> or <code>1</code>

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Present output 1 state is ${OUTPUTS/1/STATE}"</code>

Example 2: <code>"source":"${OUTPUTS/1/STATE}"</code>

==== ACTION ====
Type: integer

Possible actions:
* <code>0</code> - set state OFF
* <code>1</code> - set state ON
* <code>2</code> - short OFF (restart)
* <code>3</code> - short ON
* <code>4</code> - toggle (switch)
* <code>5</code> - no change

Allowed in: <code>"target"</code>

Example: <code>"target":"OUTPUTS/1/ACTION"</code>

==== DELAY [ms] ====
==== NAME ====
==== FREQUENCY ====
Unit: <code>Hz</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example: <code>"payload":"Frequency in power grid is ${OUTPUTS/1/ENERGY}Hz"</code>

==== ENERGY ====
Energy consumed by an device connected to NETIO device output.

Unit: <code>Wh</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Consumed energy on output 1 is ${OUTPUTS/1/ENERGY}Wh"</code>

Example 2: <code>"source":"${OUTPUTS/1/ENERGY}"</code>

==== REVERSE_ENERGY ====
Energy delivered back to grid. For example from solar system connected to NETIO device output.

Unit: <code>Wh</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Delivered energy on output 1 is ${OUTPUTS/1/REVERSE_ENERGY}Wh"</code>

Example 2: <code>"source":"${OUTPUTS/1/REVERSE_ENERGY}"</code>

==== ENERGY_START ====
Date when the counters ENERGY and REVERSE_ENERGY have been resetted by user.

Unit: <code>unix timestamp</code>

Type: integer

Allowed in: <code>"payload"</code>

Example 1: <code>"payload":"Energy measured since ${OUTPUTS/1/ENERGY_START} unix time"</code>

Example 2: <code>"payload":"${OUTPUTS/1/ENERGY_START}"</code> is output payload <code>1567654639</code>

==== ENERGY_START_FMT ====
Date when the counters ENERGY and REVERSE_ENERGY have been resetted by user.

Unit: <code>fmt date format</code>

Type: string

Allowed in: <code>"payload"</code>

Example 1: <code>"payload":"Energy measured since ${OUTPUTS/1/ENERGY_START}"</code>

Example 2: <code>"payload":"${OUTPUTS/1/ENERGY_START_FMT}"</code> is output payload <code>2019-09-05T03:37:19+00:00</code>

==== ENERGY_NR ====
Non-resettable counter of Energy consumed by an device connected to NETIO device output.

Unit: <code>Wh</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Consumed energy on output 1 is ${OUTPUTS/1/ENERGY_NR}Wh"</code>

Example 2: <code>"source":"${OUTPUTS/1/ENERGY_NR}"</code>

==== REVERSE_ENERGY_NR ====
Non-resettable counter of Energy delivered back to grid. For example from solar system connected to NETIO device output.

Unit: <code>Wh</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Delivered energy on output 1 is ${OUTPUTS/1/REVERSE_ENERGY_NR}Wh"</code>

Example 2: <code>"source":"${OUTPUTS/1/REVERSE_ENERGY_NR}"</code>

==== TOTALs - for 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
* OUTPUTS/TOTAL/PHASE
* OUTPUTS/TOTAL/REVERSE_ENERGY
* OUTPUTS/TOTAL/ENERGY_NR
* OUTPUTS/TOTAL/REVERSE_ENERGY_NR
* OUTPUTS/TOTAL/ENERGY_START
* OUTPUTS/TOTAL/ENERGY_START_FMT

==== REST_JSON ====
Allow use of NETIO JSON structure to control outputs.

Type: string / JSON

Allowed in: <code>"target"</code> for Subscribe section

Example: <code>"target": "REST_JSON"</code>

The payload is JSON structure identical to NETIO JSON API M2M Protocol (documentation available at https://www.netio-products.com/files/NETIO-M2M-API-Protocol-JSON.pdf). You can control one or multiple outputs.

Payload example 1 - Toggle output 1: <code>{"Outputs":[{"ID": 1,"Action": 4}]}</code>

Payload example 2 - Turn output 1 OFF and output 3 ON: <code>{"Outputs":[{"ID":1,"Action":0},{"ID":3,"Action":1}]}</code>

=== INPUT variables ===
==== STATE ====
Type: bool(integer) - <code>0</code> or <code>1</code>

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Present input 1 state is ${INPUTS/1/STATE}"</code>

Example 2: <code>"source":"${INPUTS/1/STATE}"</code>

==== S0 ====
S0 Counter value
Unit: <code>-</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Input 1 S0 Counter value is ${INPUTS/1/S0}impulses"</code>

Example 2: <code>"source":"${INPUTS/1/S0}"</code>

== Payload/topic variables ==

=== DEVICE_NAME ===
Can be used in: "payload", "topic"

Example 1: <code>"payload":"${DEVICE_NAME}"</code>

Example 2: <code>"topic":"netio/${DEVICE_NAME}/output/1/action"</code>

=== DEVICE_MAC ===

=== UTC_TIME <code>FW 4.0.0+</code>===

send unix timestamp of devices actual time

Can be used in: "payload", "topic"

Example 1: <code>"payload": "${UTC_TIME}"</code>

=== UPTIME Not yet implemented ===

=== PAYLOAD ===
Can be used in: "action"

Example: <code>"action":"${PAYLOAD}"</code>

=== OUTPUT_ID Not yet implemented===

=== WIFI_SIGNALNot yet implemented ===

=== OUTPUTS_STATUS ===
Provide complete outputs status and measurement if supported.

Type: string / JSON

Allowed in: <code>"payload"</code> for Publish section

Example: <code>"payload":"${OUTPUTS_STATUS}"</code>

Payload example: <code>{ "GlobalMeasure":{"Voltage":236,"TotalCurrent":72,"TotalLoad":11,"TotalEnergy":167,"OverallPowerFactor":0.64,"Frequency":50.07,"Phase":-36.86,"EnergyStart":"2020-06-30T17:04:48+01:00"}, "Outputs":[ {"ID":1,"Name":"Power output 1","State":1,"Action":6,"Delay":2020,"Current":72,"PowerFactor":0.64,"Phase":-36.86,"Energy":139,"ReverseEnergy":0,"Load":11}, {"ID":2,"Name":"Power output 2","State":1,"Action":6,"Delay":2020,"Current":0,"PowerFactor":1.00,"Phase":0.00,"Energy":27,"ReverseEnergy":0,"Load":0}, {"ID":3,"Name":"Free Contact 3","State":1,"Action":6,"Delay":2020}, {"ID":4,"Name":"Free Contact 4","State":1,"Action":6,"Delay":2020} ]}</code>

=== INPUTS_STATUS ===
Provide complete inputs status if supported. Since FW 3.0.0

Type: string / JSON

Allowed in: <code>"payload"</code> for Publish section

Example: <code>"payload":"${INPUTS_STATUS}"</code>

Payload example: <code>{ "Inputs":[ {"ID":1,"Name":"Input 1","State":0,"S0Counter":0}, {"ID":2,"Name":"Input 2","State":0,"S0Counter":0} ]}</code>

=== INOUT_STATUS ===
Provide complete inputs and output status and measurement if supported. Since FW 3.0.0

Type: string / JSON

Allowed in: <code>"payload"</code> for Publish section

Example: <code>"payload":"${INOUT_STATUS}"</code>

Payload example: <code>{ "GlobalMeasure":{"Voltage":238,"TotalCurrent":105,"TotalLoad":17,"TotalEnergy":1451,"OverallPowerFactor":0.67,"Frequency":50.03,"Phase":-33.67,"EnergyStart":"2020-06-30T17:04:48+01:00"}, "Outputs":[ {"ID":1,"Name":"Power output 1","State":0,"Action":6,"Delay":5000,"Current":0,"PowerFactor":1.00,"Phase":0.00,"Energy":701,"ReverseEnergy":0,"Load":0}, {"ID":2,"Name":"Power output 2","State":1,"Action":6,"Delay":5000,"Current":105,"PowerFactor":0.65,"Phase":-33.67,"Energy":750,"ReverseEnergy":0,"Load":17}, {"ID":3,"Name":"Free Contact 3","State":1,"Action":6,"Delay":5000}, {"ID":4,"Name":"Free Contact 4","State":0,"Action":6,"Delay":5000} ], "Inputs":[ {"ID":1,"Name":"Input 1","State":0,"S0Counter":0}, {"ID":2,"Name":"Input 2","State":0,"S0Counter":0} ]}</code>

= Extended MQTT flex JSON config examples =

== Default NETIO MQTT-flex configuration ==
This example demonstrates setup for connection to public <code>broker.hivemq.com</code>, measurement reporting and output control.

The device cabe be controlled via <code>netio/${DEVICE_NAME}/output/1/action topic</code> by sending standard NETIO action values:
* 0 - OFF
* 1 - ON
* 2 - SHORT OFF
* 3 - SHORT ON
* 4 - TOGGLE
* 5 - NO ACTION.

The device report measurements:

* Output state - every 15 minutes or by change
* Voltage [V]- every 5 minutes or by change of 1 V
* Current [mA]- every 5 minutes or by change of 50 mA
* Load(Power) [W]- every 5 minutes or by change of 10 W
* Energy(Consumption) [Wh]- every 15 minutes or by change of 1Wh
* True Power Factor (TPF) [-]- every 5 minutes or by change of 0.02
* Frequency [Hz]- every 1 hour or by change of 0.1 Hz

For register all values, you can use wildcard <code>netio/${DEVICE_NAME}/output/1/#</code>

{
"config":{
"broker":{
"url":"broker.hivemq.com",
"protocol":"mqtt",
"port":1883,
"ssl":false,
"type":"generic",
"username":"",
"password":"",
"clientid":"moje${DEVICE_NAME}${DEVICE_MAC}",
"keepalive":30
},
"subscribe":[
{
"topic":"netio/${DEVICE_NAME}/output/1/action",
"qos":0,
"target":"OUTPUTS/1/ACTION",
"action":"${payload}"
},
{
"topic":"netio/${DEVICE_NAME}/output/1/switch",
"qos":0,
"target":"OUTPUTS/1/ACTION",
"action":4
}
],
"publish":[
{
"topic":"netio/${DEVICE_MAC}/output/1/state",
"qos":0,
"retain":true,
"payload":"${OUTPUTS/1/STATE}",
"events":[
{
"type":"change",
"source":"OUTPUTS/1/STATE"
},
{
"type":"timer",
"period":900
}
]
},
{
"topic":"netio/${DEVICE_NAME}/output/1/voltage",
"qos":0,
"retain":false,
"payload":"${OUTPUTS/1/VOLTAGE}",
"events":[
{
"type":"timer",
"period":300
},
{
"type":"delta",
"source":"OUTPUTS/1/VOLTAGE",
"delta":1
}
]
},
{
"topic":"netio/${DEVICE_NAME}/output/1/current",
"qos":0,
"retain":false,
"payload":"${OUTPUTS/1/CURRENT}",
"events":[
{
"type":"timer",
"period":300
},
{
"type":"delta",
"source":"OUTPUTS/1/CURRENT",
"delta":50
}
]
},
{
"topic":"netio/${DEVICE_NAME}/output/1/load",
"qos":0,
"retain":false,
"payload":"${OUTPUTS/1/LOAD}",
"events":[
{
"type":"timer",
"period":300
},
{
"type":"delta",
"source":"OUTPUTS/1/LOAD",
"delta":10
}
]
},
{
"topic":"netio/${DEVICE_NAME}/output/1/energy",
"qos":0,
"retain":false,
"payload":"${OUTPUTS/1/ENERGY}",
"events":[
{
"type":"timer",
"period":900
},
{
"type":"delta",
"source":"OUTPUTS/1/ENERGY",
"delta":1
}
]
},
{
"topic":"netio/${DEVICE_NAME}/output/1/tpf",
"qos":0,
"retain":false,
"payload":"${OUTPUTS/1/POWER_FACTOR}",
"events":[
{
"type":"timer",
"period":900
},
{
"type":"delta",
"source":"OUTPUTS/1/POWER_FACTOR",
"delta":0.02
}
]
},
{
"topic":"netio/${DEVICE_NAME}/output/1/frequency",
"qos":0,
"retain":false,
"payload":"${OUTPUTS/1/FREQUENCY}",
"events":[
{
"type":"timer",
"period":3600
},
{
"type":"delta",
"source":"OUTPUTS/1/FREQUENCY",
"delta":0.1
}
]
}
]
}
}

MQTT-flex

2023-06-13T16:53:21Z

Bbakala: /* Payload/topic variables */

The MQTT-flex version of the MQTT protocol can be configured in detail thanks to the “flex” extension.

https://www.netio-products.com/en/glossary/mqtt-flex

Why MQTT-flex 
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 [https://en.wikipedia.org/wiki/MQTT 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 [https://en.wikipedia.org/wiki/JSON 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 101x 
* PowerCable REST 101x 
* PowerPDU 4PS 
* PowerPDU 4KS 
* PowerPDU 8QS 
* PowerDIN 4PZ 
* PowerBOX 3Px 
* PowerBOX 4Kx 

FW version: 
>2.2.1

===Not supported NETIO devices:===
* PowerPDU 4C 
* NETIO 4 
* NETIO 4All 

= Simple MQTT-flex configuration + explanation =

''We strongly recommend to create and test MQTT-flex configuration on "local" device what can be easily restarted. The validation of config before saving is not 100% and for example some specific typos can cause a freeze of a device - the solution is to restart a device (unplug/plug input power cable). If the configuration is saved and device is working then there are no known failure case so it is safe to use this configuration on the "remote" devices.''

{
"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":false,
"payload":"${OUTPUTS/1/STATE}",
"events":[
{
"type":"timer",
"period":"1000"
}
]
}
]
}
}
=== Client Configuration (broker section) ===
Put here MQTT client connection setup

This configuration example set NETIO device to connect to broker.hivemq.com with mqtt protocol, no ssl connection with credetials freedom/peace|love|empathy4ALL.

"broker":{
"url":"broker.hivemq.com",
"protocol":"mqtt",
"port":1883,
"ssl":false,
"type":"generic",
"username":"freedom",
"password":"peace|LOVE|empathy4ALL"
},

=== Device Control (subscribe section) ===
Put here array of topics where to subscribe

Device output 1 is controlled with action received by subscription to netio/${DEVICE_NAME}/output/1/action topic with QOS 0

"subscribe":[{
"topic":"netio/${DEVICE_NAME}/output/1/action",
"qos":0,
"target":"OUTPUTS/1/ACTION",
"action":"${payload}"
}
],

=== Output State monitoring (publish section) ===
Put here array of topics where to publish.

Device send every 1000 s message to topic with QOS 0, retain true information with output 1 state

"publish":[{
"topic":"netio/${DEVICE_NAME}/output/1/state",
"qos":0,
"retain":true,
"payload":"${OUTPUTS/1/STATE}",
"events":[
{
"type":"timer",
"period":"1000"
}
]
}
]

= 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 ===
{| class="wikitable"
! style="font-weight:bold; background-color:#9b9b9b;" | Item
! style="font-weight:bold; background-color:#9b9b9b;" | Presence
! style="font-weight:bold; background-color:#9b9b9b;" | Possible Values
! style="font-weight:bold; background-color:#9b9b9b;" | Description
! style="font-weight:bold; background-color:#9b9b9b;" | JSON Config Usage
|-
| style="background-color:#efefef;" | url
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" |
| style="background-color:#efefef;" | MQTT broker URL
| style="background-color:#efefef;" | "url":"broker.hivemq.com"
|-
| style="background-color:#efefef;" | port
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | 1 - 65535
| style="background-color:#efefef;" | MQTT broker port
| style="background-color:#efefef;" | "port":1883
|-
| style="background-color:#efefef;" | protocol
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" |
| style="background-color:#efefef;" | protocol spec - mqtt
| style="background-color:#efefef;" | "protocol": "mqtt"
|-
| style="background-color:#efefef;" | ssl
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | true, false
| style="background-color:#efefef;" | Use SSL crypted communication selector
| style="background-color:#efefef;" | "ssl":false
|-
| style="background-color:#efefef;" | type
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | generic
| style="background-color:#efefef;" | Communication/setup type option
| style="background-color:#efefef;" | "type":"generic"
|-
| style="background-color:#efefef;" | username
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | regexp+len
| style="background-color:#efefef;" | Credentials for MQTT broker. Max. 128 characters (since FW 3.2.4).
| style="background-color:#efefef;" | "username":"freedom"
|-
| style="background-color:#efefef;" | password
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | regexp+len
| style="background-color:#efefef;" | Credentials for MQTT broker. Max. 256 characters (since FW 3.2.4).
| style="background-color:#efefef;" | "password":"peace|LOVE|empathy4ALL"
|-
| style="background-color:#efefef;" | clientid
| style="background-color:#efefef;" | optional
| style="background-color:#efefef;" | regexp+len
| style="background-color:#efefef;" | MQTT clientid. Max. 128 characters (since FW 3.2.4). Variables ${DEVICE_MAC} or ${DEVICE_NAME} can be used
| style="background-color:#efefef;" | "clientid":"myEcoTable01"
|-
| style="background-color:#efefef;" | keepalive
| style="background-color:#efefef;" | optional
| style="background-color:#efefef;" | 1 - 65535
| style="background-color:#efefef;" | MQTT keep alive period in seconds
| style="background-color:#efefef;" | "keepalive":90
|}

Note 1: clientid attribute is mandatory for MQTT(s) communication. When not configured, random ID will be generated.

Note 2: To proper communication with MS Azure - it is necessary to set up IoT Hub to use TLS 1.2

See section "TLS 1.2 enforcement available in select regions" in following guidelines https://docs.microsoft.com/en-us/azure/iot-hub/iot-hub-tls-support

=== Examples ===
==== Standard setup ====

==== Security (SSL / TLS) secured setup ====
You can enable MQTTs by using the encrypted port 8883 + "ssl":true.

==== Variables used setup ====

== 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 ===
{| class="wikitable"
! style="font-weight:bold; background-color:#9b9b9b;" | Item
! style="font-weight:bold; background-color:#9b9b9b;" | Presence
! style="font-weight:bold; background-color:#9b9b9b;" | Possible Values
! style="font-weight:bold; background-color:#9b9b9b;" | Description
! style="font-weight:bold; background-color:#9b9b9b;" | JSON Config Usage
|-
| style="background-color:#efefef;" | topic
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | see table below
| style="background-color:#efefef;" | specification of the topic, which MQTT-flex device listens from broker and act accordingly. Max. 128 characters. The "#" can be used since FW 3.2.4 - see note under this table.
| style="background-color:#efefef;" | "topic":"netio/${DEVICE_NAME}/output/1/action"
|-
| style="background-color:#efefef;" | qos
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | 0, 1 or 2
| style="background-color:#efefef;" | 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}
| style="background-color:#efefef;" | "qos":0
|-
| style="background-color:#efefef;" | target
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" |
| style="background-color:#efefef;" | internal definition of action, which can be performed above the specified output
| style="background-color:#efefef;" | "target":"OUTPUTS/1/ACTION"
|-
| style="background-color:#efefef;" | action
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" |
| style="background-color:#efefef;" | a payload or a value the action attribute needs to have passed to
| style="background-color:#efefef;" | "action":"${payload}"
|-
| style="background-color:#efefef;" | actiondefNot supported yet
| style="background-color:#efefef;" | optional
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
|-
| style="background-color:#efefef;" | jsonNot supported yet
| style="background-color:#efefef;" | optional
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
|}

Note: The "#" wildcard can be used in subscribe topic definition. The multi-level wildcard character MUST be specified either on its own or following a topic level separator. In either case it MUST be the last character specified in the Topic.

For example, if a Device subscribes to “devices/{device_id}/messages/devicebound/#”, it would receive messages published using these topic names:

“devices/{device_id}/messages/devicebound/”

“devices/{device_id}/messages/devicebound/{property_bag}”

This should be usefull for use with MS Azure - IoT hub.

=== MQTT Subscribe as event to trigger action <code>FW 4.0.0+</code> ===

This feature allow to subscribe to specific MQTT topic and pass payload to Rules or MQTT-flex as event.

target: <code>PROTOCOLS/MQTT/EVENT</code>

"subscribe": [
{
"action": "${payload}",
"qos": 0,
"target": "PROTOCOLS/MQTT/EVENT",
"topic": "broker/12345/MQTT_EVENT/"
}
]

=== Examples ===
==== Toggle output with standard payload ====
==== Toggle output with custom payload ====
==== Subscribe to more than one topic ====
==== Trigger Rule and MQTT publish from MQTT subscribe <code>FW 4.0.0+</code> ====
This example show Request response implementation in MQTT and toggle action made by Rules.

When message with payload <code>getValues</code> is published to topic <code>broker/gv90018g/COMMAND</code> MQTT flex will create an event with name <code>PROTOCOLS/MQTT/EVENT</code> (fixed name cannot be changed) and value <code>getValues</code>. On this event will act all events and conditions set in MQTT-flex and Rules which are set to listening to change on <code>PROTOCOLS/MQTT/EVENT</code> and equals to value <code>getValues</code>. See bold marked parameters in example configuration below.

Once the triggered action is done it is needed to reset MQTT channel to <code>OK</code> status becaus event are reacting only to change. If the channel is not reset the next even would not be triggered.

Rules Configuration:
{
"conditions": {
"PROTOCOLS/MQTT/EVENT": "getValues"
},
"actions": {
"OUTPUTS/1/ACTION": 4
}
}

MQTT Configuration:
{
"broker":{
"clientid":"netio${DEVICE_SN}",
"keepalive":30,
"password":"abcdefghijk",
"port":8883,
"protocol":"mqtt",
"ssl":true,
"type":"generic",
"url":"broker.cloud.netio.eu",
"username":"gv90018g"
},
"groupEvents":[
{
"events":[
{
"source":"PROTOCOLS/MQTT/EVENT",
"type":"change",
"value":"getValues"
}
],
"appliedTopics":[
"broker/gv90018g/OUTPUTS/1/STATE",
"broker/gv90018g/COMMAND"
]
}
],
"publish":[
{
"payload":"${OUTPUTS/1/STATE}",
"qos":0,
"retain":true,
"topic":"broker/gv90018g/OUTPUTS/1/STATE"
},
{
"payload":"OK",
"qos":0,
"retain":true,
"topic":"broker/gv90018g/COMMAND"
}
],
"subscribe":[
{
"action":"${payload}",
"qos":0,
"target":"PROTOCOLS/MQTT/EVENT",
"topic":"broker/gv90018g/COMMAND"
}
]
}

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 ===
{| class="wikitable"
! style="font-weight:bold; background-color:#9b9b9b;" | Item
! style="font-weight:bold; background-color:#9b9b9b;" | Presence
! style="font-weight:bold; background-color:#9b9b9b;" | Possible Values
! style="font-weight:bold; background-color:#9b9b9b;" | Description
! style="font-weight:bold; background-color:#9b9b9b;" | JSON Config Usage
|-
| style="background-color:#efefef;" | topic
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | see table below
| style="background-color:#efefef;" | definition of the topic, how it is registered towards MQTT broker. Max. 128 characters.
| style="background-color:#efefef;" | "topic":"netio/${DEVICE_NAME}/output/1/load"
|-
| style="background-color:#efefef;" | qos
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | see table below
| style="background-color:#efefef;" | 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}
| style="background-color:#efefef;" |
|-
| style="background-color:#efefef;" | retain
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | boolean: true or false
| style="background-color:#efefef;" | 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}
| style="background-color:#efefef;" | "retain":true
|-
| style="background-color:#efefef;" | payload
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | see table below
| style="background-color:#efefef;" | definition of the payload, what is send to the MQTT broker.
| style="background-color:#efefef;" | "payload":"${OUTPUTS/1/STATE}"
|-
| style="background-color:#efefef;" | events
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | see table below
| style="background-color:#efefef;" | definition of events used for triggering sending of data via mqtt (change, delta, timer)
| style="background-color:#efefef;" |
|-
| style="background-color:#efefef;" | type
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
|-
| style="background-color:#efefef;" | source
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
|-
| style="background-color:#efefef;" | delta
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
|-
| style="background-color:#efefef;" | period
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
|-
| style="background-color:#efefef;" | payloaddefNot supported yet
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
|}

=== Examples ===
==== Publish energy periodically (event timer) ====
==== Publish current on change (delta) ====
==== Publish output state ====
==== Publish to more than one topic with different events ====

= 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 available only on NETIO PowerDIN 4PZ

=== Examples: ===

adressing controll of output 3
OUTPUTS/3/ACTION
getting voltage on output 1
OUTPUTS/1/VOLTAGE
getting state of input 1
INPUTS/1/STATE

= Group Events<code>FW 4.0.0+</code> =
Group events are smart way how to keep configuration simple. It is not replacement of publish section specification but it is extension to trigger group of different topics to be published on the same event.

See the example below. There is specific event on status change on every output and additionally the device sends periodic status every 60 seconds.

{
"broker": {
"clientid": "netio${DEVICE_SN}",
"keepalive": 30,
"password": "",
"port": 1883,
"protocol": "mqtt",
"ssl": false,
"type": "generic",
"url": "broker.hivemq.com",
"username": ""
},
"groupEvents": [
{
"events":[
{
"period": 60,
"type": "timer"
}
],
"appliedTopics":[
"devices/${DEVICE_NAME}/output/1/state",
"devices/${DEVICE_NAME}/output/2/state"
]
}
],
"publish": [
{
"events": [
{
"source": "OUTPUTS/1/STATE",
"type": "change"
}
],
"payload": "${OUTPUTS/1/STATE}",
"qos": 0,
"retain": false,
 "topic": "devices/${DEVICE_NAME}/output/1/state"
},{
"events": [
{
"source": "OUTPUTS/2/STATE",
"type": "change"
}
],
"payload": "${OUTPUTS/2/STATE}",
"qos": 0,
"retain": false,
 "topic": "devices/${DEVICE_NAME}/output/2/state"
}
]
}

= 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 ===
==== VOLTAGE ====
Unit: <code>V</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Present RMS voltage on output 1 is ${OUTPUTS/1/VOLTAGE}"</code>

Example 2: <code>"source":"${OUTPUTS/1/VOLTAGE}"</code>

==== CURRENT ====
Unit: <code>mA</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Present RMS current on output 1 is ${OUTPUTS/1/CURRENT}"</code>

Example 2: <code>"source":"${OUTPUTS/1/CURRENT}"</code>

==== POWER_FACTOR ====
Unit: <code>[-]</code>

Type: float (2 decimals)

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"True Power Factor on output 1 is ${OUTPUTS/1/POWER_FACTOR}"</code>

Example 2: <code>"source":"${OUTPUTS/1/POWER_FACTOR}"</code>

==== LOAD ====
Unit: <code>W</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Present load on output 1 is ${OUTPUTS/1/LOAD}W"</code>

Example 2: <code>"payload":"Device's load connected to output 1 is ${OUTPUTS/1/LOAD}W"</code>

Example 3: <code>"source":"${OUTPUTS/1/LOAD}"</code>

==== STATE ====
Type: bool(integer) - <code>0</code> or <code>1</code>

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Present output 1 state is ${OUTPUTS/1/STATE}"</code>

Example 2: <code>"source":"${OUTPUTS/1/STATE}"</code>

==== ACTION ====
Type: integer

Possible actions:
* <code>0</code> - set state OFF
* <code>1</code> - set state ON
* <code>2</code> - short OFF (restart)
* <code>3</code> - short ON
* <code>4</code> - toggle (switch)
* <code>5</code> - no change

Allowed in: <code>"target"</code>

Example: <code>"target":"OUTPUTS/1/ACTION"</code>

==== DELAY [ms] ====
==== NAME ====
==== FREQUENCY ====
Unit: <code>Hz</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example: <code>"payload":"Frequency in power grid is ${OUTPUTS/1/ENERGY}Hz"</code>

==== ENERGY ====
Energy consumed by an device connected to NETIO device output.

Unit: <code>Wh</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Consumed energy on output 1 is ${OUTPUTS/1/ENERGY}Wh"</code>

Example 2: <code>"source":"${OUTPUTS/1/ENERGY}"</code>

==== REVERSE_ENERGY ====
Energy delivered back to grid. For example from solar system connected to NETIO device output.

Unit: <code>Wh</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Delivered energy on output 1 is ${OUTPUTS/1/REVERSE_ENERGY}Wh"</code>

Example 2: <code>"source":"${OUTPUTS/1/REVERSE_ENERGY}"</code>

==== ENERGY_START ====
Date when the counters ENERGY and REVERSE_ENERGY have been resetted by user.

Unit: <code>unix timestamp</code>

Type: integer

Allowed in: <code>"payload"</code>

Example 1: <code>"payload":"Energy measured since ${OUTPUTS/1/ENERGY_START} unix time"</code>

Example 2: <code>"payload":"${OUTPUTS/1/ENERGY_START}"</code> is output payload <code>1567654639</code>

==== ENERGY_START_FMT ====
Date when the counters ENERGY and REVERSE_ENERGY have been resetted by user.

Unit: <code>fmt date format</code>

Type: string

Allowed in: <code>"payload"</code>

Example 1: <code>"payload":"Energy measured since ${OUTPUTS/1/ENERGY_START}"</code>

Example 2: <code>"payload":"${OUTPUTS/1/ENERGY_START_FMT}"</code> is output payload <code>2019-09-05T03:37:19+00:00</code>

==== ENERGY_NR ====
Non-resettable counter of Energy consumed by an device connected to NETIO device output.

Unit: <code>Wh</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Consumed energy on output 1 is ${OUTPUTS/1/ENERGY_NR}Wh"</code>

Example 2: <code>"source":"${OUTPUTS/1/ENERGY_NR}"</code>

==== REVERSE_ENERGY_NR ====
Non-resettable counter of Energy delivered back to grid. For example from solar system connected to NETIO device output.

Unit: <code>Wh</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Delivered energy on output 1 is ${OUTPUTS/1/REVERSE_ENERGY_NR}Wh"</code>

Example 2: <code>"source":"${OUTPUTS/1/REVERSE_ENERGY_NR}"</code>

==== TOTALs - for 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
* OUTPUTS/TOTAL/PHASE
* OUTPUTS/TOTAL/REVERSE_ENERGY
* OUTPUTS/TOTAL/ENERGY_NR
* OUTPUTS/TOTAL/REVERSE_ENERGY_NR
* OUTPUTS/TOTAL/ENERGY_START
* OUTPUTS/TOTAL/ENERGY_START_FMT

==== REST_JSON ====
Allow use of NETIO JSON structure to control outputs.

Type: string / JSON

Allowed in: <code>"target"</code> for Subscribe section

Example: <code>"target": "REST_JSON"</code>

The payload is JSON structure identical to NETIO JSON API M2M Protocol (documentation available at https://www.netio-products.com/files/NETIO-M2M-API-Protocol-JSON.pdf). You can control one or multiple outputs.

Payload example 1 - Toggle output 1: <code>{"Outputs":[{"ID": 1,"Action": 4}]}</code>

Payload example 2 - Turn output 1 OFF and output 3 ON: <code>{"Outputs":[{"ID":1,"Action":0},{"ID":3,"Action":1}]}</code>

=== INPUT variables ===
==== STATE ====
Type: bool(integer) - <code>0</code> or <code>1</code>

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Present input 1 state is ${INPUTS/1/STATE}"</code>

Example 2: <code>"source":"${INPUTS/1/STATE}"</code>

==== S0 ====
S0 Counter value
Unit: <code>-</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Input 1 S0 Counter value is ${INPUTS/1/S0}impulses"</code>

Example 2: <code>"source":"${INPUTS/1/S0}"</code>

== Payload/topic variables ==

=== DEVICE_NAME ===
Can be used in: "payload", "topic"

Example 1: <code>"payload":"${DEVICE_NAME}"</code>

Example 2: <code>"topic":"netio/${DEVICE_NAME}/output/1/action"</code>

=== DEVICE_MAC ===

=== UTC_TIME ===

send unix timestamp of devices actual time

Can be used in: "payload", "topic"

Example 1: <code>"payload": "${UTC_TIME}"</code>

=== UPTIME Not yet implemented ===

=== PAYLOAD ===
Can be used in: "action"

Example: <code>"action":"${PAYLOAD}"</code>

=== OUTPUT_ID Not yet implemented===

=== WIFI_SIGNALNot yet implemented ===

=== OUTPUTS_STATUS ===
Provide complete outputs status and measurement if supported.

Type: string / JSON

Allowed in: <code>"payload"</code> for Publish section

Example: <code>"payload":"${OUTPUTS_STATUS}"</code>

Payload example: <code>{ "GlobalMeasure":{"Voltage":236,"TotalCurrent":72,"TotalLoad":11,"TotalEnergy":167,"OverallPowerFactor":0.64,"Frequency":50.07,"Phase":-36.86,"EnergyStart":"2020-06-30T17:04:48+01:00"}, "Outputs":[ {"ID":1,"Name":"Power output 1","State":1,"Action":6,"Delay":2020,"Current":72,"PowerFactor":0.64,"Phase":-36.86,"Energy":139,"ReverseEnergy":0,"Load":11}, {"ID":2,"Name":"Power output 2","State":1,"Action":6,"Delay":2020,"Current":0,"PowerFactor":1.00,"Phase":0.00,"Energy":27,"ReverseEnergy":0,"Load":0}, {"ID":3,"Name":"Free Contact 3","State":1,"Action":6,"Delay":2020}, {"ID":4,"Name":"Free Contact 4","State":1,"Action":6,"Delay":2020} ]}</code>

=== INPUTS_STATUS ===
Provide complete inputs status if supported. Since FW 3.0.0

Type: string / JSON

Allowed in: <code>"payload"</code> for Publish section

Example: <code>"payload":"${INPUTS_STATUS}"</code>

Payload example: <code>{ "Inputs":[ {"ID":1,"Name":"Input 1","State":0,"S0Counter":0}, {"ID":2,"Name":"Input 2","State":0,"S0Counter":0} ]}</code>

=== INOUT_STATUS ===
Provide complete inputs and output status and measurement if supported. Since FW 3.0.0

Type: string / JSON

Allowed in: <code>"payload"</code> for Publish section

Example: <code>"payload":"${INOUT_STATUS}"</code>

Payload example: <code>{ "GlobalMeasure":{"Voltage":238,"TotalCurrent":105,"TotalLoad":17,"TotalEnergy":1451,"OverallPowerFactor":0.67,"Frequency":50.03,"Phase":-33.67,"EnergyStart":"2020-06-30T17:04:48+01:00"}, "Outputs":[ {"ID":1,"Name":"Power output 1","State":0,"Action":6,"Delay":5000,"Current":0,"PowerFactor":1.00,"Phase":0.00,"Energy":701,"ReverseEnergy":0,"Load":0}, {"ID":2,"Name":"Power output 2","State":1,"Action":6,"Delay":5000,"Current":105,"PowerFactor":0.65,"Phase":-33.67,"Energy":750,"ReverseEnergy":0,"Load":17}, {"ID":3,"Name":"Free Contact 3","State":1,"Action":6,"Delay":5000}, {"ID":4,"Name":"Free Contact 4","State":0,"Action":6,"Delay":5000} ], "Inputs":[ {"ID":1,"Name":"Input 1","State":0,"S0Counter":0}, {"ID":2,"Name":"Input 2","State":0,"S0Counter":0} ]}</code>

= Extended MQTT flex JSON config examples =

== Default NETIO MQTT-flex configuration ==
This example demonstrates setup for connection to public <code>broker.hivemq.com</code>, measurement reporting and output control.

The device cabe be controlled via <code>netio/${DEVICE_NAME}/output/1/action topic</code> by sending standard NETIO action values:
* 0 - OFF
* 1 - ON
* 2 - SHORT OFF
* 3 - SHORT ON
* 4 - TOGGLE
* 5 - NO ACTION.

The device report measurements:

* Output state - every 15 minutes or by change
* Voltage [V]- every 5 minutes or by change of 1 V
* Current [mA]- every 5 minutes or by change of 50 mA
* Load(Power) [W]- every 5 minutes or by change of 10 W
* Energy(Consumption) [Wh]- every 15 minutes or by change of 1Wh
* True Power Factor (TPF) [-]- every 5 minutes or by change of 0.02
* Frequency [Hz]- every 1 hour or by change of 0.1 Hz

For register all values, you can use wildcard <code>netio/${DEVICE_NAME}/output/1/#</code>

{
"config":{
"broker":{
"url":"broker.hivemq.com",
"protocol":"mqtt",
"port":1883,
"ssl":false,
"type":"generic",
"username":"",
"password":"",
"clientid":"moje${DEVICE_NAME}${DEVICE_MAC}",
"keepalive":30
},
"subscribe":[
{
"topic":"netio/${DEVICE_NAME}/output/1/action",
"qos":0,
"target":"OUTPUTS/1/ACTION",
"action":"${payload}"
},
{
"topic":"netio/${DEVICE_NAME}/output/1/switch",
"qos":0,
"target":"OUTPUTS/1/ACTION",
"action":4
}
],
"publish":[
{
"topic":"netio/${DEVICE_MAC}/output/1/state",
"qos":0,
"retain":true,
"payload":"${OUTPUTS/1/STATE}",
"events":[
{
"type":"change",
"source":"OUTPUTS/1/STATE"
},
{
"type":"timer",
"period":900
}
]
},
{
"topic":"netio/${DEVICE_NAME}/output/1/voltage",
"qos":0,
"retain":false,
"payload":"${OUTPUTS/1/VOLTAGE}",
"events":[
{
"type":"timer",
"period":300
},
{
"type":"delta",
"source":"OUTPUTS/1/VOLTAGE",
"delta":1
}
]
},
{
"topic":"netio/${DEVICE_NAME}/output/1/current",
"qos":0,
"retain":false,
"payload":"${OUTPUTS/1/CURRENT}",
"events":[
{
"type":"timer",
"period":300
},
{
"type":"delta",
"source":"OUTPUTS/1/CURRENT",
"delta":50
}
]
},
{
"topic":"netio/${DEVICE_NAME}/output/1/load",
"qos":0,
"retain":false,
"payload":"${OUTPUTS/1/LOAD}",
"events":[
{
"type":"timer",
"period":300
},
{
"type":"delta",
"source":"OUTPUTS/1/LOAD",
"delta":10
}
]
},
{
"topic":"netio/${DEVICE_NAME}/output/1/energy",
"qos":0,
"retain":false,
"payload":"${OUTPUTS/1/ENERGY}",
"events":[
{
"type":"timer",
"period":900
},
{
"type":"delta",
"source":"OUTPUTS/1/ENERGY",
"delta":1
}
]
},
{
"topic":"netio/${DEVICE_NAME}/output/1/tpf",
"qos":0,
"retain":false,
"payload":"${OUTPUTS/1/POWER_FACTOR}",
"events":[
{
"type":"timer",
"period":900
},
{
"type":"delta",
"source":"OUTPUTS/1/POWER_FACTOR",
"delta":0.02
}
]
},
{
"topic":"netio/${DEVICE_NAME}/output/1/frequency",
"qos":0,
"retain":false,
"payload":"${OUTPUTS/1/FREQUENCY}",
"events":[
{
"type":"timer",
"period":3600
},
{
"type":"delta",
"source":"OUTPUTS/1/FREQUENCY",
"delta":0.1
}
]
}
]
}
}

MQTT-flex

2023-06-06T14:31:32Z

Bbakala: /* Group EventsFW 4.0.0+ */

The MQTT-flex version of the MQTT protocol can be configured in detail thanks to the “flex” extension.

https://www.netio-products.com/en/glossary/mqtt-flex

Why MQTT-flex 
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 [https://en.wikipedia.org/wiki/MQTT 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 [https://en.wikipedia.org/wiki/JSON 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 101x 
* PowerCable REST 101x 
* PowerPDU 4PS 
* PowerPDU 4KS 
* PowerPDU 8QS 
* PowerDIN 4PZ 
* PowerBOX 3Px 
* PowerBOX 4Kx 

FW version: 
>2.2.1

===Not supported NETIO devices:===
* PowerPDU 4C 
* NETIO 4 
* NETIO 4All 

= Simple MQTT-flex configuration + explanation =

''We strongly recommend to create and test MQTT-flex configuration on "local" device what can be easily restarted. The validation of config before saving is not 100% and for example some specific typos can cause a freeze of a device - the solution is to restart a device (unplug/plug input power cable). If the configuration is saved and device is working then there are no known failure case so it is safe to use this configuration on the "remote" devices.''

{
"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":false,
"payload":"${OUTPUTS/1/STATE}",
"events":[
{
"type":"timer",
"period":"1000"
}
]
}
]
}
}
=== Client Configuration (broker section) ===
Put here MQTT client connection setup

This configuration example set NETIO device to connect to broker.hivemq.com with mqtt protocol, no ssl connection with credetials freedom/peace|love|empathy4ALL.

"broker":{
"url":"broker.hivemq.com",
"protocol":"mqtt",
"port":1883,
"ssl":false,
"type":"generic",
"username":"freedom",
"password":"peace|LOVE|empathy4ALL"
},

=== Device Control (subscribe section) ===
Put here array of topics where to subscribe

Device output 1 is controlled with action received by subscription to netio/${DEVICE_NAME}/output/1/action topic with QOS 0

"subscribe":[{
"topic":"netio/${DEVICE_NAME}/output/1/action",
"qos":0,
"target":"OUTPUTS/1/ACTION",
"action":"${payload}"
}
],

=== Output State monitoring (publish section) ===
Put here array of topics where to publish.

Device send every 1000 s message to topic with QOS 0, retain true information with output 1 state

"publish":[{
"topic":"netio/${DEVICE_NAME}/output/1/state",
"qos":0,
"retain":true,
"payload":"${OUTPUTS/1/STATE}",
"events":[
{
"type":"timer",
"period":"1000"
}
]
}
]

= 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 ===
{| class="wikitable"
! style="font-weight:bold; background-color:#9b9b9b;" | Item
! style="font-weight:bold; background-color:#9b9b9b;" | Presence
! style="font-weight:bold; background-color:#9b9b9b;" | Possible Values
! style="font-weight:bold; background-color:#9b9b9b;" | Description
! style="font-weight:bold; background-color:#9b9b9b;" | JSON Config Usage
|-
| style="background-color:#efefef;" | url
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" |
| style="background-color:#efefef;" | MQTT broker URL
| style="background-color:#efefef;" | "url":"broker.hivemq.com"
|-
| style="background-color:#efefef;" | port
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | 1 - 65535
| style="background-color:#efefef;" | MQTT broker port
| style="background-color:#efefef;" | "port":1883
|-
| style="background-color:#efefef;" | protocol
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" |
| style="background-color:#efefef;" | protocol spec - mqtt
| style="background-color:#efefef;" | "protocol": "mqtt"
|-
| style="background-color:#efefef;" | ssl
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | true, false
| style="background-color:#efefef;" | Use SSL crypted communication selector
| style="background-color:#efefef;" | "ssl":false
|-
| style="background-color:#efefef;" | type
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | generic
| style="background-color:#efefef;" | Communication/setup type option
| style="background-color:#efefef;" | "type":"generic"
|-
| style="background-color:#efefef;" | username
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | regexp+len
| style="background-color:#efefef;" | Credentials for MQTT broker. Max. 128 characters (since FW 3.2.4).
| style="background-color:#efefef;" | "username":"freedom"
|-
| style="background-color:#efefef;" | password
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | regexp+len
| style="background-color:#efefef;" | Credentials for MQTT broker. Max. 256 characters (since FW 3.2.4).
| style="background-color:#efefef;" | "password":"peace|LOVE|empathy4ALL"
|-
| style="background-color:#efefef;" | clientid
| style="background-color:#efefef;" | optional
| style="background-color:#efefef;" | regexp+len
| style="background-color:#efefef;" | MQTT clientid. Max. 128 characters (since FW 3.2.4). Variables ${DEVICE_MAC} or ${DEVICE_NAME} can be used
| style="background-color:#efefef;" | "clientid":"myEcoTable01"
|-
| style="background-color:#efefef;" | keepalive
| style="background-color:#efefef;" | optional
| style="background-color:#efefef;" | 1 - 65535
| style="background-color:#efefef;" | MQTT keep alive period in seconds
| style="background-color:#efefef;" | "keepalive":90
|}

Note 1: clientid attribute is mandatory for MQTT(s) communication. When not configured, random ID will be generated.

Note 2: To proper communication with MS Azure - it is necessary to set up IoT Hub to use TLS 1.2

See section "TLS 1.2 enforcement available in select regions" in following guidelines https://docs.microsoft.com/en-us/azure/iot-hub/iot-hub-tls-support

=== Examples ===
==== Standard setup ====

==== Security (SSL / TLS) secured setup ====
You can enable MQTTs by using the encrypted port 8883 + "ssl":true.

==== Variables used setup ====

== 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 ===
{| class="wikitable"
! style="font-weight:bold; background-color:#9b9b9b;" | Item
! style="font-weight:bold; background-color:#9b9b9b;" | Presence
! style="font-weight:bold; background-color:#9b9b9b;" | Possible Values
! style="font-weight:bold; background-color:#9b9b9b;" | Description
! style="font-weight:bold; background-color:#9b9b9b;" | JSON Config Usage
|-
| style="background-color:#efefef;" | topic
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | see table below
| style="background-color:#efefef;" | specification of the topic, which MQTT-flex device listens from broker and act accordingly. Max. 128 characters. The "#" can be used since FW 3.2.4 - see note under this table.
| style="background-color:#efefef;" | "topic":"netio/${DEVICE_NAME}/output/1/action"
|-
| style="background-color:#efefef;" | qos
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | 0, 1 or 2
| style="background-color:#efefef;" | 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}
| style="background-color:#efefef;" | "qos":0
|-
| style="background-color:#efefef;" | target
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" |
| style="background-color:#efefef;" | internal definition of action, which can be performed above the specified output
| style="background-color:#efefef;" | "target":"OUTPUTS/1/ACTION"
|-
| style="background-color:#efefef;" | action
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" |
| style="background-color:#efefef;" | a payload or a value the action attribute needs to have passed to
| style="background-color:#efefef;" | "action":"${payload}"
|-
| style="background-color:#efefef;" | actiondefNot supported yet
| style="background-color:#efefef;" | optional
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
|-
| style="background-color:#efefef;" | jsonNot supported yet
| style="background-color:#efefef;" | optional
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
|}

Note: The "#" wildcard can be used in subscribe topic definition. The multi-level wildcard character MUST be specified either on its own or following a topic level separator. In either case it MUST be the last character specified in the Topic.

For example, if a Device subscribes to “devices/{device_id}/messages/devicebound/#”, it would receive messages published using these topic names:

“devices/{device_id}/messages/devicebound/”

“devices/{device_id}/messages/devicebound/{property_bag}”

This should be usefull for use with MS Azure - IoT hub.

=== MQTT Subscribe as event to trigger action <code>FW 4.0.0+</code> ===

This feature allow to subscribe to specific MQTT topic and pass payload to Rules or MQTT-flex as event.

target: <code>PROTOCOLS/MQTT/EVENT</code>

"subscribe": [
{
"action": "${payload}",
"qos": 0,
"target": "PROTOCOLS/MQTT/EVENT",
"topic": "broker/12345/MQTT_EVENT/"
}
]

=== Examples ===
==== Toggle output with standard payload ====
==== Toggle output with custom payload ====
==== Subscribe to more than one topic ====
==== Trigger Rule and MQTT publish from MQTT subscribe <code>FW 4.0.0+</code> ====
This example show Request response implementation in MQTT and toggle action made by Rules.

When message with payload <code>getValues</code> is published to topic <code>broker/gv90018g/COMMAND</code> MQTT flex will create an event with name <code>PROTOCOLS/MQTT/EVENT</code> (fixed name cannot be changed) and value <code>getValues</code>. On this event will act all events and conditions set in MQTT-flex and Rules which are set to listening to change on <code>PROTOCOLS/MQTT/EVENT</code> and equals to value <code>getValues</code>. See bold marked parameters in example configuration below.

Once the triggered action is done it is needed to reset MQTT channel to <code>OK</code> status becaus event are reacting only to change. If the channel is not reset the next even would not be triggered.

Rules Configuration:
{
"conditions": {
"PROTOCOLS/MQTT/EVENT": "getValues"
},
"actions": {
"OUTPUTS/1/ACTION": 4
}
}

MQTT Configuration:
{
"broker":{
"clientid":"netio${DEVICE_SN}",
"keepalive":30,
"password":"abcdefghijk",
"port":8883,
"protocol":"mqtt",
"ssl":true,
"type":"generic",
"url":"broker.cloud.netio.eu",
"username":"gv90018g"
},
"groupEvents":[
{
"events":[
{
"source":"PROTOCOLS/MQTT/EVENT",
"type":"change",
"value":"getValues"
}
],
"appliedTopics":[
"broker/gv90018g/OUTPUTS/1/STATE",
"broker/gv90018g/COMMAND"
]
}
],
"publish":[
{
"payload":"${OUTPUTS/1/STATE}",
"qos":0,
"retain":true,
"topic":"broker/gv90018g/OUTPUTS/1/STATE"
},
{
"payload":"OK",
"qos":0,
"retain":true,
"topic":"broker/gv90018g/COMMAND"
}
],
"subscribe":[
{
"action":"${payload}",
"qos":0,
"target":"PROTOCOLS/MQTT/EVENT",
"topic":"broker/gv90018g/COMMAND"
}
]
}

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 ===
{| class="wikitable"
! style="font-weight:bold; background-color:#9b9b9b;" | Item
! style="font-weight:bold; background-color:#9b9b9b;" | Presence
! style="font-weight:bold; background-color:#9b9b9b;" | Possible Values
! style="font-weight:bold; background-color:#9b9b9b;" | Description
! style="font-weight:bold; background-color:#9b9b9b;" | JSON Config Usage
|-
| style="background-color:#efefef;" | topic
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | see table below
| style="background-color:#efefef;" | definition of the topic, how it is registered towards MQTT broker. Max. 128 characters.
| style="background-color:#efefef;" | "topic":"netio/${DEVICE_NAME}/output/1/load"
|-
| style="background-color:#efefef;" | qos
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | see table below
| style="background-color:#efefef;" | 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}
| style="background-color:#efefef;" |
|-
| style="background-color:#efefef;" | retain
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | boolean: true or false
| style="background-color:#efefef;" | 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}
| style="background-color:#efefef;" | "retain":true
|-
| style="background-color:#efefef;" | payload
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | see table below
| style="background-color:#efefef;" | definition of the payload, what is send to the MQTT broker.
| style="background-color:#efefef;" | "payload":"${OUTPUTS/1/STATE}"
|-
| style="background-color:#efefef;" | events
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | see table below
| style="background-color:#efefef;" | definition of events used for triggering sending of data via mqtt (change, delta, timer)
| style="background-color:#efefef;" |
|-
| style="background-color:#efefef;" | type
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
|-
| style="background-color:#efefef;" | source
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
|-
| style="background-color:#efefef;" | delta
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
|-
| style="background-color:#efefef;" | period
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
|-
| style="background-color:#efefef;" | payloaddefNot supported yet
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
|}

=== Examples ===
==== Publish energy periodically (event timer) ====
==== Publish current on change (delta) ====
==== Publish output state ====
==== Publish to more than one topic with different events ====

= 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 available only on NETIO PowerDIN 4PZ

=== Examples: ===

adressing controll of output 3
OUTPUTS/3/ACTION
getting voltage on output 1
OUTPUTS/1/VOLTAGE
getting state of input 1
INPUTS/1/STATE

= Group Events<code>FW 4.0.0+</code> =
Group events are smart way how to keep configuration simple. It is not replacement of publish section specification but it is extension to trigger group of different topics to be published on the same event.

See the example below. There is specific event on status change on every output and additionally the device sends periodic status every 60 seconds.

{
"broker": {
"clientid": "netio${DEVICE_SN}",
"keepalive": 30,
"password": "",
"port": 1883,
"protocol": "mqtt",
"ssl": false,
"type": "generic",
"url": "broker.hivemq.com",
"username": ""
},
"groupEvents": [
{
"events":[
{
"period": 60,
"type": "timer"
}
],
"appliedTopics":[
"devices/${DEVICE_NAME}/output/1/state",
"devices/${DEVICE_NAME}/output/2/state"
]
}
],
"publish": [
{
"events": [
{
"source": "OUTPUTS/1/STATE",
"type": "change"
}
],
"payload": "${OUTPUTS/1/STATE}",
"qos": 0,
"retain": false,
 "topic": "devices/${DEVICE_NAME}/output/1/state"
},{
"events": [
{
"source": "OUTPUTS/2/STATE",
"type": "change"
}
],
"payload": "${OUTPUTS/2/STATE}",
"qos": 0,
"retain": false,
 "topic": "devices/${DEVICE_NAME}/output/2/state"
}
]
}

= 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 ===
==== VOLTAGE ====
Unit: <code>V</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Present RMS voltage on output 1 is ${OUTPUTS/1/VOLTAGE}"</code>

Example 2: <code>"source":"${OUTPUTS/1/VOLTAGE}"</code>

==== CURRENT ====
Unit: <code>mA</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Present RMS current on output 1 is ${OUTPUTS/1/CURRENT}"</code>

Example 2: <code>"source":"${OUTPUTS/1/CURRENT}"</code>

==== POWER_FACTOR ====
Unit: <code>[-]</code>

Type: float (2 decimals)

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"True Power Factor on output 1 is ${OUTPUTS/1/POWER_FACTOR}"</code>

Example 2: <code>"source":"${OUTPUTS/1/POWER_FACTOR}"</code>

==== LOAD ====
Unit: <code>W</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Present load on output 1 is ${OUTPUTS/1/LOAD}W"</code>

Example 2: <code>"payload":"Device's load connected to output 1 is ${OUTPUTS/1/LOAD}W"</code>

Example 3: <code>"source":"${OUTPUTS/1/LOAD}"</code>

==== STATE ====
Type: bool(integer) - <code>0</code> or <code>1</code>

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Present output 1 state is ${OUTPUTS/1/STATE}"</code>

Example 2: <code>"source":"${OUTPUTS/1/STATE}"</code>

==== ACTION ====
Type: integer

Possible actions:
* <code>0</code> - set state OFF
* <code>1</code> - set state ON
* <code>2</code> - short OFF (restart)
* <code>3</code> - short ON
* <code>4</code> - toggle (switch)
* <code>5</code> - no change

Allowed in: <code>"target"</code>

Example: <code>"target":"OUTPUTS/1/ACTION"</code>

==== DELAY [ms] ====
==== NAME ====
==== FREQUENCY ====
Unit: <code>Hz</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example: <code>"payload":"Frequency in power grid is ${OUTPUTS/1/ENERGY}Hz"</code>

==== ENERGY ====
Energy consumed by an device connected to NETIO device output.

Unit: <code>Wh</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Consumed energy on output 1 is ${OUTPUTS/1/ENERGY}Wh"</code>

Example 2: <code>"source":"${OUTPUTS/1/ENERGY}"</code>

==== REVERSE_ENERGY ====
Energy delivered back to grid. For example from solar system connected to NETIO device output.

Unit: <code>Wh</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Delivered energy on output 1 is ${OUTPUTS/1/REVERSE_ENERGY}Wh"</code>

Example 2: <code>"source":"${OUTPUTS/1/REVERSE_ENERGY}"</code>

==== ENERGY_START ====
Date when the counters ENERGY and REVERSE_ENERGY have been resetted by user.

Unit: <code>unix timestamp</code>

Type: integer

Allowed in: <code>"payload"</code>

Example 1: <code>"payload":"Energy measured since ${OUTPUTS/1/ENERGY_START} unix time"</code>

Example 2: <code>"payload":"${OUTPUTS/1/ENERGY_START}"</code> is output payload <code>1567654639</code>

==== ENERGY_START_FMT ====
Date when the counters ENERGY and REVERSE_ENERGY have been resetted by user.

Unit: <code>fmt date format</code>

Type: string

Allowed in: <code>"payload"</code>

Example 1: <code>"payload":"Energy measured since ${OUTPUTS/1/ENERGY_START}"</code>

Example 2: <code>"payload":"${OUTPUTS/1/ENERGY_START_FMT}"</code> is output payload <code>2019-09-05T03:37:19+00:00</code>

==== ENERGY_NR ====
Non-resettable counter of Energy consumed by an device connected to NETIO device output.

Unit: <code>Wh</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Consumed energy on output 1 is ${OUTPUTS/1/ENERGY_NR}Wh"</code>

Example 2: <code>"source":"${OUTPUTS/1/ENERGY_NR}"</code>

==== REVERSE_ENERGY_NR ====
Non-resettable counter of Energy delivered back to grid. For example from solar system connected to NETIO device output.

Unit: <code>Wh</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Delivered energy on output 1 is ${OUTPUTS/1/REVERSE_ENERGY_NR}Wh"</code>

Example 2: <code>"source":"${OUTPUTS/1/REVERSE_ENERGY_NR}"</code>

==== TOTALs - for 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
* OUTPUTS/TOTAL/PHASE
* OUTPUTS/TOTAL/REVERSE_ENERGY
* OUTPUTS/TOTAL/ENERGY_NR
* OUTPUTS/TOTAL/REVERSE_ENERGY_NR
* OUTPUTS/TOTAL/ENERGY_START
* OUTPUTS/TOTAL/ENERGY_START_FMT

==== REST_JSON ====
Allow use of NETIO JSON structure to control outputs.

Type: string / JSON

Allowed in: <code>"target"</code> for Subscribe section

Example: <code>"target": "REST_JSON"</code>

The payload is JSON structure identical to NETIO JSON API M2M Protocol (documentation available at https://www.netio-products.com/files/NETIO-M2M-API-Protocol-JSON.pdf). You can control one or multiple outputs.

Payload example 1 - Toggle output 1: <code>{"Outputs":[{"ID": 1,"Action": 4}]}</code>

Payload example 2 - Turn output 1 OFF and output 3 ON: <code>{"Outputs":[{"ID":1,"Action":0},{"ID":3,"Action":1}]}</code>

=== INPUT variables ===
==== STATE ====
Type: bool(integer) - <code>0</code> or <code>1</code>

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Present input 1 state is ${INPUTS/1/STATE}"</code>

Example 2: <code>"source":"${INPUTS/1/STATE}"</code>

==== S0 ====
S0 Counter value
Unit: <code>-</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Input 1 S0 Counter value is ${INPUTS/1/S0}impulses"</code>

Example 2: <code>"source":"${INPUTS/1/S0}"</code>

== Payload/topic variables ==

=== DEVICE_NAME ===
Can be used in: "payload", "topic"

Example 1: <code>"payload":"${DEVICE_NAME}"</code>

Example 2: <code>"topic":"netio/${DEVICE_NAME}/output/1/action"</code>

=== DEVICE_MAC ===

=== UPTIME Not yet implemented ===

=== PAYLOAD ===
Can be used in: "action"

Example: <code>"action":"${PAYLOAD}"</code>

=== OUTPUT_ID Not yet implemented===

=== WIFI_SIGNALNot yet implemented ===

=== OUTPUTS_STATUS ===
Provide complete outputs status and measurement if supported.

Type: string / JSON

Allowed in: <code>"payload"</code> for Publish section

Example: <code>"payload":"${OUTPUTS_STATUS}"</code>

Payload example: <code>{ "GlobalMeasure":{"Voltage":236,"TotalCurrent":72,"TotalLoad":11,"TotalEnergy":167,"OverallPowerFactor":0.64,"Frequency":50.07,"Phase":-36.86,"EnergyStart":"2020-06-30T17:04:48+01:00"}, "Outputs":[ {"ID":1,"Name":"Power output 1","State":1,"Action":6,"Delay":2020,"Current":72,"PowerFactor":0.64,"Phase":-36.86,"Energy":139,"ReverseEnergy":0,"Load":11}, {"ID":2,"Name":"Power output 2","State":1,"Action":6,"Delay":2020,"Current":0,"PowerFactor":1.00,"Phase":0.00,"Energy":27,"ReverseEnergy":0,"Load":0}, {"ID":3,"Name":"Free Contact 3","State":1,"Action":6,"Delay":2020}, {"ID":4,"Name":"Free Contact 4","State":1,"Action":6,"Delay":2020} ]}</code>

=== INPUTS_STATUS ===
Provide complete inputs status if supported. Since FW 3.0.0

Type: string / JSON

Allowed in: <code>"payload"</code> for Publish section

Example: <code>"payload":"${INPUTS_STATUS}"</code>

Payload example: <code>{ "Inputs":[ {"ID":1,"Name":"Input 1","State":0,"S0Counter":0}, {"ID":2,"Name":"Input 2","State":0,"S0Counter":0} ]}</code>

=== INOUT_STATUS ===
Provide complete inputs and output status and measurement if supported. Since FW 3.0.0

Type: string / JSON

Allowed in: <code>"payload"</code> for Publish section

Example: <code>"payload":"${INOUT_STATUS}"</code>

Payload example: <code>{ "GlobalMeasure":{"Voltage":238,"TotalCurrent":105,"TotalLoad":17,"TotalEnergy":1451,"OverallPowerFactor":0.67,"Frequency":50.03,"Phase":-33.67,"EnergyStart":"2020-06-30T17:04:48+01:00"}, "Outputs":[ {"ID":1,"Name":"Power output 1","State":0,"Action":6,"Delay":5000,"Current":0,"PowerFactor":1.00,"Phase":0.00,"Energy":701,"ReverseEnergy":0,"Load":0}, {"ID":2,"Name":"Power output 2","State":1,"Action":6,"Delay":5000,"Current":105,"PowerFactor":0.65,"Phase":-33.67,"Energy":750,"ReverseEnergy":0,"Load":17}, {"ID":3,"Name":"Free Contact 3","State":1,"Action":6,"Delay":5000}, {"ID":4,"Name":"Free Contact 4","State":0,"Action":6,"Delay":5000} ], "Inputs":[ {"ID":1,"Name":"Input 1","State":0,"S0Counter":0}, {"ID":2,"Name":"Input 2","State":0,"S0Counter":0} ]}</code>

= Extended MQTT flex JSON config examples =

== Default NETIO MQTT-flex configuration ==
This example demonstrates setup for connection to public <code>broker.hivemq.com</code>, measurement reporting and output control.

The device cabe be controlled via <code>netio/${DEVICE_NAME}/output/1/action topic</code> by sending standard NETIO action values:
* 0 - OFF
* 1 - ON
* 2 - SHORT OFF
* 3 - SHORT ON
* 4 - TOGGLE
* 5 - NO ACTION.

The device report measurements:

* Output state - every 15 minutes or by change
* Voltage [V]- every 5 minutes or by change of 1 V
* Current [mA]- every 5 minutes or by change of 50 mA
* Load(Power) [W]- every 5 minutes or by change of 10 W
* Energy(Consumption) [Wh]- every 15 minutes or by change of 1Wh
* True Power Factor (TPF) [-]- every 5 minutes or by change of 0.02
* Frequency [Hz]- every 1 hour or by change of 0.1 Hz

For register all values, you can use wildcard <code>netio/${DEVICE_NAME}/output/1/#</code>

{
"config":{
"broker":{
"url":"broker.hivemq.com",
"protocol":"mqtt",
"port":1883,
"ssl":false,
"type":"generic",
"username":"",
"password":"",
"clientid":"moje${DEVICE_NAME}${DEVICE_MAC}",
"keepalive":30
},
"subscribe":[
{
"topic":"netio/${DEVICE_NAME}/output/1/action",
"qos":0,
"target":"OUTPUTS/1/ACTION",
"action":"${payload}"
},
{
"topic":"netio/${DEVICE_NAME}/output/1/switch",
"qos":0,
"target":"OUTPUTS/1/ACTION",
"action":4
}
],
"publish":[
{
"topic":"netio/${DEVICE_MAC}/output/1/state",
"qos":0,
"retain":true,
"payload":"${OUTPUTS/1/STATE}",
"events":[
{
"type":"change",
"source":"OUTPUTS/1/STATE"
},
{
"type":"timer",
"period":900
}
]
},
{
"topic":"netio/${DEVICE_NAME}/output/1/voltage",
"qos":0,
"retain":false,
"payload":"${OUTPUTS/1/VOLTAGE}",
"events":[
{
"type":"timer",
"period":300
},
{
"type":"delta",
"source":"OUTPUTS/1/VOLTAGE",
"delta":1
}
]
},
{
"topic":"netio/${DEVICE_NAME}/output/1/current",
"qos":0,
"retain":false,
"payload":"${OUTPUTS/1/CURRENT}",
"events":[
{
"type":"timer",
"period":300
},
{
"type":"delta",
"source":"OUTPUTS/1/CURRENT",
"delta":50
}
]
},
{
"topic":"netio/${DEVICE_NAME}/output/1/load",
"qos":0,
"retain":false,
"payload":"${OUTPUTS/1/LOAD}",
"events":[
{
"type":"timer",
"period":300
},
{
"type":"delta",
"source":"OUTPUTS/1/LOAD",
"delta":10
}
]
},
{
"topic":"netio/${DEVICE_NAME}/output/1/energy",
"qos":0,
"retain":false,
"payload":"${OUTPUTS/1/ENERGY}",
"events":[
{
"type":"timer",
"period":900
},
{
"type":"delta",
"source":"OUTPUTS/1/ENERGY",
"delta":1
}
]
},
{
"topic":"netio/${DEVICE_NAME}/output/1/tpf",
"qos":0,
"retain":false,
"payload":"${OUTPUTS/1/POWER_FACTOR}",
"events":[
{
"type":"timer",
"period":900
},
{
"type":"delta",
"source":"OUTPUTS/1/POWER_FACTOR",
"delta":0.02
}
]
},
{
"topic":"netio/${DEVICE_NAME}/output/1/frequency",
"qos":0,
"retain":false,
"payload":"${OUTPUTS/1/FREQUENCY}",
"events":[
{
"type":"timer",
"period":3600
},
{
"type":"delta",
"source":"OUTPUTS/1/FREQUENCY",
"delta":0.1
}
]
}
]
}
}

MQTT-flex

2023-06-06T14:29:38Z

Bbakala: /* Group EventsFW 4.0.0+ */

The MQTT-flex version of the MQTT protocol can be configured in detail thanks to the “flex” extension.

https://www.netio-products.com/en/glossary/mqtt-flex

Why MQTT-flex 
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 [https://en.wikipedia.org/wiki/MQTT 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 [https://en.wikipedia.org/wiki/JSON 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 101x 
* PowerCable REST 101x 
* PowerPDU 4PS 
* PowerPDU 4KS 
* PowerPDU 8QS 
* PowerDIN 4PZ 
* PowerBOX 3Px 
* PowerBOX 4Kx 

FW version: 
>2.2.1

===Not supported NETIO devices:===
* PowerPDU 4C 
* NETIO 4 
* NETIO 4All 

= Simple MQTT-flex configuration + explanation =

''We strongly recommend to create and test MQTT-flex configuration on "local" device what can be easily restarted. The validation of config before saving is not 100% and for example some specific typos can cause a freeze of a device - the solution is to restart a device (unplug/plug input power cable). If the configuration is saved and device is working then there are no known failure case so it is safe to use this configuration on the "remote" devices.''

{
"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":false,
"payload":"${OUTPUTS/1/STATE}",
"events":[
{
"type":"timer",
"period":"1000"
}
]
}
]
}
}
=== Client Configuration (broker section) ===
Put here MQTT client connection setup

This configuration example set NETIO device to connect to broker.hivemq.com with mqtt protocol, no ssl connection with credetials freedom/peace|love|empathy4ALL.

"broker":{
"url":"broker.hivemq.com",
"protocol":"mqtt",
"port":1883,
"ssl":false,
"type":"generic",
"username":"freedom",
"password":"peace|LOVE|empathy4ALL"
},

=== Device Control (subscribe section) ===
Put here array of topics where to subscribe

Device output 1 is controlled with action received by subscription to netio/${DEVICE_NAME}/output/1/action topic with QOS 0

"subscribe":[{
"topic":"netio/${DEVICE_NAME}/output/1/action",
"qos":0,
"target":"OUTPUTS/1/ACTION",
"action":"${payload}"
}
],

=== Output State monitoring (publish section) ===
Put here array of topics where to publish.

Device send every 1000 s message to topic with QOS 0, retain true information with output 1 state

"publish":[{
"topic":"netio/${DEVICE_NAME}/output/1/state",
"qos":0,
"retain":true,
"payload":"${OUTPUTS/1/STATE}",
"events":[
{
"type":"timer",
"period":"1000"
}
]
}
]

= 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 ===
{| class="wikitable"
! style="font-weight:bold; background-color:#9b9b9b;" | Item
! style="font-weight:bold; background-color:#9b9b9b;" | Presence
! style="font-weight:bold; background-color:#9b9b9b;" | Possible Values
! style="font-weight:bold; background-color:#9b9b9b;" | Description
! style="font-weight:bold; background-color:#9b9b9b;" | JSON Config Usage
|-
| style="background-color:#efefef;" | url
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" |
| style="background-color:#efefef;" | MQTT broker URL
| style="background-color:#efefef;" | "url":"broker.hivemq.com"
|-
| style="background-color:#efefef;" | port
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | 1 - 65535
| style="background-color:#efefef;" | MQTT broker port
| style="background-color:#efefef;" | "port":1883
|-
| style="background-color:#efefef;" | protocol
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" |
| style="background-color:#efefef;" | protocol spec - mqtt
| style="background-color:#efefef;" | "protocol": "mqtt"
|-
| style="background-color:#efefef;" | ssl
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | true, false
| style="background-color:#efefef;" | Use SSL crypted communication selector
| style="background-color:#efefef;" | "ssl":false
|-
| style="background-color:#efefef;" | type
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | generic
| style="background-color:#efefef;" | Communication/setup type option
| style="background-color:#efefef;" | "type":"generic"
|-
| style="background-color:#efefef;" | username
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | regexp+len
| style="background-color:#efefef;" | Credentials for MQTT broker. Max. 128 characters (since FW 3.2.4).
| style="background-color:#efefef;" | "username":"freedom"
|-
| style="background-color:#efefef;" | password
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | regexp+len
| style="background-color:#efefef;" | Credentials for MQTT broker. Max. 256 characters (since FW 3.2.4).
| style="background-color:#efefef;" | "password":"peace|LOVE|empathy4ALL"
|-
| style="background-color:#efefef;" | clientid
| style="background-color:#efefef;" | optional
| style="background-color:#efefef;" | regexp+len
| style="background-color:#efefef;" | MQTT clientid. Max. 128 characters (since FW 3.2.4). Variables ${DEVICE_MAC} or ${DEVICE_NAME} can be used
| style="background-color:#efefef;" | "clientid":"myEcoTable01"
|-
| style="background-color:#efefef;" | keepalive
| style="background-color:#efefef;" | optional
| style="background-color:#efefef;" | 1 - 65535
| style="background-color:#efefef;" | MQTT keep alive period in seconds
| style="background-color:#efefef;" | "keepalive":90
|}

Note 1: clientid attribute is mandatory for MQTT(s) communication. When not configured, random ID will be generated.

Note 2: To proper communication with MS Azure - it is necessary to set up IoT Hub to use TLS 1.2

See section "TLS 1.2 enforcement available in select regions" in following guidelines https://docs.microsoft.com/en-us/azure/iot-hub/iot-hub-tls-support

=== Examples ===
==== Standard setup ====

==== Security (SSL / TLS) secured setup ====
You can enable MQTTs by using the encrypted port 8883 + "ssl":true.

==== Variables used setup ====

== 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 ===
{| class="wikitable"
! style="font-weight:bold; background-color:#9b9b9b;" | Item
! style="font-weight:bold; background-color:#9b9b9b;" | Presence
! style="font-weight:bold; background-color:#9b9b9b;" | Possible Values
! style="font-weight:bold; background-color:#9b9b9b;" | Description
! style="font-weight:bold; background-color:#9b9b9b;" | JSON Config Usage
|-
| style="background-color:#efefef;" | topic
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | see table below
| style="background-color:#efefef;" | specification of the topic, which MQTT-flex device listens from broker and act accordingly. Max. 128 characters. The "#" can be used since FW 3.2.4 - see note under this table.
| style="background-color:#efefef;" | "topic":"netio/${DEVICE_NAME}/output/1/action"
|-
| style="background-color:#efefef;" | qos
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | 0, 1 or 2
| style="background-color:#efefef;" | 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}
| style="background-color:#efefef;" | "qos":0
|-
| style="background-color:#efefef;" | target
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" |
| style="background-color:#efefef;" | internal definition of action, which can be performed above the specified output
| style="background-color:#efefef;" | "target":"OUTPUTS/1/ACTION"
|-
| style="background-color:#efefef;" | action
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" |
| style="background-color:#efefef;" | a payload or a value the action attribute needs to have passed to
| style="background-color:#efefef;" | "action":"${payload}"
|-
| style="background-color:#efefef;" | actiondefNot supported yet
| style="background-color:#efefef;" | optional
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
|-
| style="background-color:#efefef;" | jsonNot supported yet
| style="background-color:#efefef;" | optional
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
|}

Note: The "#" wildcard can be used in subscribe topic definition. The multi-level wildcard character MUST be specified either on its own or following a topic level separator. In either case it MUST be the last character specified in the Topic.

For example, if a Device subscribes to “devices/{device_id}/messages/devicebound/#”, it would receive messages published using these topic names:

“devices/{device_id}/messages/devicebound/”

“devices/{device_id}/messages/devicebound/{property_bag}”

This should be usefull for use with MS Azure - IoT hub.

=== MQTT Subscribe as event to trigger action <code>FW 4.0.0+</code> ===

This feature allow to subscribe to specific MQTT topic and pass payload to Rules or MQTT-flex as event.

target: <code>PROTOCOLS/MQTT/EVENT</code>

"subscribe": [
{
"action": "${payload}",
"qos": 0,
"target": "PROTOCOLS/MQTT/EVENT",
"topic": "broker/12345/MQTT_EVENT/"
}
]

=== Examples ===
==== Toggle output with standard payload ====
==== Toggle output with custom payload ====
==== Subscribe to more than one topic ====
==== Trigger Rule and MQTT publish from MQTT subscribe <code>FW 4.0.0+</code> ====
This example show Request response implementation in MQTT and toggle action made by Rules.

When message with payload <code>getValues</code> is published to topic <code>broker/gv90018g/COMMAND</code> MQTT flex will create an event with name <code>PROTOCOLS/MQTT/EVENT</code> (fixed name cannot be changed) and value <code>getValues</code>. On this event will act all events and conditions set in MQTT-flex and Rules which are set to listening to change on <code>PROTOCOLS/MQTT/EVENT</code> and equals to value <code>getValues</code>. See bold marked parameters in example configuration below.

Once the triggered action is done it is needed to reset MQTT channel to <code>OK</code> status becaus event are reacting only to change. If the channel is not reset the next even would not be triggered.

Rules Configuration:
{
"conditions": {
"PROTOCOLS/MQTT/EVENT": "getValues"
},
"actions": {
"OUTPUTS/1/ACTION": 4
}
}

MQTT Configuration:
{
"broker":{
"clientid":"netio${DEVICE_SN}",
"keepalive":30,
"password":"abcdefghijk",
"port":8883,
"protocol":"mqtt",
"ssl":true,
"type":"generic",
"url":"broker.cloud.netio.eu",
"username":"gv90018g"
},
"groupEvents":[
{
"events":[
{
"source":"PROTOCOLS/MQTT/EVENT",
"type":"change",
"value":"getValues"
}
],
"appliedTopics":[
"broker/gv90018g/OUTPUTS/1/STATE",
"broker/gv90018g/COMMAND"
]
}
],
"publish":[
{
"payload":"${OUTPUTS/1/STATE}",
"qos":0,
"retain":true,
"topic":"broker/gv90018g/OUTPUTS/1/STATE"
},
{
"payload":"OK",
"qos":0,
"retain":true,
"topic":"broker/gv90018g/COMMAND"
}
],
"subscribe":[
{
"action":"${payload}",
"qos":0,
"target":"PROTOCOLS/MQTT/EVENT",
"topic":"broker/gv90018g/COMMAND"
}
]
}

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 ===
{| class="wikitable"
! style="font-weight:bold; background-color:#9b9b9b;" | Item
! style="font-weight:bold; background-color:#9b9b9b;" | Presence
! style="font-weight:bold; background-color:#9b9b9b;" | Possible Values
! style="font-weight:bold; background-color:#9b9b9b;" | Description
! style="font-weight:bold; background-color:#9b9b9b;" | JSON Config Usage
|-
| style="background-color:#efefef;" | topic
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | see table below
| style="background-color:#efefef;" | definition of the topic, how it is registered towards MQTT broker. Max. 128 characters.
| style="background-color:#efefef;" | "topic":"netio/${DEVICE_NAME}/output/1/load"
|-
| style="background-color:#efefef;" | qos
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | see table below
| style="background-color:#efefef;" | 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}
| style="background-color:#efefef;" |
|-
| style="background-color:#efefef;" | retain
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | boolean: true or false
| style="background-color:#efefef;" | 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}
| style="background-color:#efefef;" | "retain":true
|-
| style="background-color:#efefef;" | payload
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | see table below
| style="background-color:#efefef;" | definition of the payload, what is send to the MQTT broker.
| style="background-color:#efefef;" | "payload":"${OUTPUTS/1/STATE}"
|-
| style="background-color:#efefef;" | events
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | see table below
| style="background-color:#efefef;" | definition of events used for triggering sending of data via mqtt (change, delta, timer)
| style="background-color:#efefef;" |
|-
| style="background-color:#efefef;" | type
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
|-
| style="background-color:#efefef;" | source
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
|-
| style="background-color:#efefef;" | delta
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
|-
| style="background-color:#efefef;" | period
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
|-
| style="background-color:#efefef;" | payloaddefNot supported yet
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
|}

=== Examples ===
==== Publish energy periodically (event timer) ====
==== Publish current on change (delta) ====
==== Publish output state ====
==== Publish to more than one topic with different events ====

= 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 available only on NETIO PowerDIN 4PZ

=== Examples: ===

adressing controll of output 3
OUTPUTS/3/ACTION
getting voltage on output 1
OUTPUTS/1/VOLTAGE
getting state of input 1
INPUTS/1/STATE

= Group Events<code>FW 4.0.0+</code> =
Group events are smart way how to keep configuration simple. It is not replacement of publish section specification but it is extension to trigger group of different topic publish on the same event.

See the example below.

{
"broker": {
"clientid": "netio${DEVICE_SN}",
"keepalive": 30,
"password": "",
"port": 1883,
"protocol": "mqtt",
"ssl": false,
"type": "generic",
"url": "broker.hivemq.com",
"username": ""
},
"groupEvents": [
{
"events":[
{
"period": 60,
"type": "timer"
}
],
"appliedTopics":[
"devices/${DEVICE_NAME}/output/1/state",
"devices/${DEVICE_NAME}/output/2/state"
]
}
],
"publish": [
{
"events": [
{
"source": "OUTPUTS/1/STATE",
"type": "change"
}
],
"payload": "${OUTPUTS/1/STATE}",
"qos": 0,
"retain": false,
 "topic": "devices/${DEVICE_NAME}/output/1/state"
},{
"events": [
{
"source": "OUTPUTS/2/STATE",
"type": "change"
}
],
"payload": "${OUTPUTS/2/STATE}",
"qos": 0,
"retain": false,
 "topic": "devices/${DEVICE_NAME}/output/2/state"
}
]
}

= 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 ===
==== VOLTAGE ====
Unit: <code>V</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Present RMS voltage on output 1 is ${OUTPUTS/1/VOLTAGE}"</code>

Example 2: <code>"source":"${OUTPUTS/1/VOLTAGE}"</code>

==== CURRENT ====
Unit: <code>mA</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Present RMS current on output 1 is ${OUTPUTS/1/CURRENT}"</code>

Example 2: <code>"source":"${OUTPUTS/1/CURRENT}"</code>

==== POWER_FACTOR ====
Unit: <code>[-]</code>

Type: float (2 decimals)

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"True Power Factor on output 1 is ${OUTPUTS/1/POWER_FACTOR}"</code>

Example 2: <code>"source":"${OUTPUTS/1/POWER_FACTOR}"</code>

==== LOAD ====
Unit: <code>W</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Present load on output 1 is ${OUTPUTS/1/LOAD}W"</code>

Example 2: <code>"payload":"Device's load connected to output 1 is ${OUTPUTS/1/LOAD}W"</code>

Example 3: <code>"source":"${OUTPUTS/1/LOAD}"</code>

==== STATE ====
Type: bool(integer) - <code>0</code> or <code>1</code>

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Present output 1 state is ${OUTPUTS/1/STATE}"</code>

Example 2: <code>"source":"${OUTPUTS/1/STATE}"</code>

==== ACTION ====
Type: integer

Possible actions:
* <code>0</code> - set state OFF
* <code>1</code> - set state ON
* <code>2</code> - short OFF (restart)
* <code>3</code> - short ON
* <code>4</code> - toggle (switch)
* <code>5</code> - no change

Allowed in: <code>"target"</code>

Example: <code>"target":"OUTPUTS/1/ACTION"</code>

==== DELAY [ms] ====
==== NAME ====
==== FREQUENCY ====
Unit: <code>Hz</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example: <code>"payload":"Frequency in power grid is ${OUTPUTS/1/ENERGY}Hz"</code>

==== ENERGY ====
Energy consumed by an device connected to NETIO device output.

Unit: <code>Wh</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Consumed energy on output 1 is ${OUTPUTS/1/ENERGY}Wh"</code>

Example 2: <code>"source":"${OUTPUTS/1/ENERGY}"</code>

==== REVERSE_ENERGY ====
Energy delivered back to grid. For example from solar system connected to NETIO device output.

Unit: <code>Wh</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Delivered energy on output 1 is ${OUTPUTS/1/REVERSE_ENERGY}Wh"</code>

Example 2: <code>"source":"${OUTPUTS/1/REVERSE_ENERGY}"</code>

==== ENERGY_START ====
Date when the counters ENERGY and REVERSE_ENERGY have been resetted by user.

Unit: <code>unix timestamp</code>

Type: integer

Allowed in: <code>"payload"</code>

Example 1: <code>"payload":"Energy measured since ${OUTPUTS/1/ENERGY_START} unix time"</code>

Example 2: <code>"payload":"${OUTPUTS/1/ENERGY_START}"</code> is output payload <code>1567654639</code>

==== ENERGY_START_FMT ====
Date when the counters ENERGY and REVERSE_ENERGY have been resetted by user.

Unit: <code>fmt date format</code>

Type: string

Allowed in: <code>"payload"</code>

Example 1: <code>"payload":"Energy measured since ${OUTPUTS/1/ENERGY_START}"</code>

Example 2: <code>"payload":"${OUTPUTS/1/ENERGY_START_FMT}"</code> is output payload <code>2019-09-05T03:37:19+00:00</code>

==== ENERGY_NR ====
Non-resettable counter of Energy consumed by an device connected to NETIO device output.

Unit: <code>Wh</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Consumed energy on output 1 is ${OUTPUTS/1/ENERGY_NR}Wh"</code>

Example 2: <code>"source":"${OUTPUTS/1/ENERGY_NR}"</code>

==== REVERSE_ENERGY_NR ====
Non-resettable counter of Energy delivered back to grid. For example from solar system connected to NETIO device output.

Unit: <code>Wh</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Delivered energy on output 1 is ${OUTPUTS/1/REVERSE_ENERGY_NR}Wh"</code>

Example 2: <code>"source":"${OUTPUTS/1/REVERSE_ENERGY_NR}"</code>

==== TOTALs - for 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
* OUTPUTS/TOTAL/PHASE
* OUTPUTS/TOTAL/REVERSE_ENERGY
* OUTPUTS/TOTAL/ENERGY_NR
* OUTPUTS/TOTAL/REVERSE_ENERGY_NR
* OUTPUTS/TOTAL/ENERGY_START
* OUTPUTS/TOTAL/ENERGY_START_FMT

==== REST_JSON ====
Allow use of NETIO JSON structure to control outputs.

Type: string / JSON

Allowed in: <code>"target"</code> for Subscribe section

Example: <code>"target": "REST_JSON"</code>

The payload is JSON structure identical to NETIO JSON API M2M Protocol (documentation available at https://www.netio-products.com/files/NETIO-M2M-API-Protocol-JSON.pdf). You can control one or multiple outputs.

Payload example 1 - Toggle output 1: <code>{"Outputs":[{"ID": 1,"Action": 4}]}</code>

Payload example 2 - Turn output 1 OFF and output 3 ON: <code>{"Outputs":[{"ID":1,"Action":0},{"ID":3,"Action":1}]}</code>

=== INPUT variables ===
==== STATE ====
Type: bool(integer) - <code>0</code> or <code>1</code>

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Present input 1 state is ${INPUTS/1/STATE}"</code>

Example 2: <code>"source":"${INPUTS/1/STATE}"</code>

==== S0 ====
S0 Counter value
Unit: <code>-</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Input 1 S0 Counter value is ${INPUTS/1/S0}impulses"</code>

Example 2: <code>"source":"${INPUTS/1/S0}"</code>

== Payload/topic variables ==

=== DEVICE_NAME ===
Can be used in: "payload", "topic"

Example 1: <code>"payload":"${DEVICE_NAME}"</code>

Example 2: <code>"topic":"netio/${DEVICE_NAME}/output/1/action"</code>

=== DEVICE_MAC ===

=== UPTIME Not yet implemented ===

=== PAYLOAD ===
Can be used in: "action"

Example: <code>"action":"${PAYLOAD}"</code>

=== OUTPUT_ID Not yet implemented===

=== WIFI_SIGNALNot yet implemented ===

=== OUTPUTS_STATUS ===
Provide complete outputs status and measurement if supported.

Type: string / JSON

Allowed in: <code>"payload"</code> for Publish section

Example: <code>"payload":"${OUTPUTS_STATUS}"</code>

Payload example: <code>{ "GlobalMeasure":{"Voltage":236,"TotalCurrent":72,"TotalLoad":11,"TotalEnergy":167,"OverallPowerFactor":0.64,"Frequency":50.07,"Phase":-36.86,"EnergyStart":"2020-06-30T17:04:48+01:00"}, "Outputs":[ {"ID":1,"Name":"Power output 1","State":1,"Action":6,"Delay":2020,"Current":72,"PowerFactor":0.64,"Phase":-36.86,"Energy":139,"ReverseEnergy":0,"Load":11}, {"ID":2,"Name":"Power output 2","State":1,"Action":6,"Delay":2020,"Current":0,"PowerFactor":1.00,"Phase":0.00,"Energy":27,"ReverseEnergy":0,"Load":0}, {"ID":3,"Name":"Free Contact 3","State":1,"Action":6,"Delay":2020}, {"ID":4,"Name":"Free Contact 4","State":1,"Action":6,"Delay":2020} ]}</code>

=== INPUTS_STATUS ===
Provide complete inputs status if supported. Since FW 3.0.0

Type: string / JSON

Allowed in: <code>"payload"</code> for Publish section

Example: <code>"payload":"${INPUTS_STATUS}"</code>

Payload example: <code>{ "Inputs":[ {"ID":1,"Name":"Input 1","State":0,"S0Counter":0}, {"ID":2,"Name":"Input 2","State":0,"S0Counter":0} ]}</code>

=== INOUT_STATUS ===
Provide complete inputs and output status and measurement if supported. Since FW 3.0.0

Type: string / JSON

Allowed in: <code>"payload"</code> for Publish section

Example: <code>"payload":"${INOUT_STATUS}"</code>

Payload example: <code>{ "GlobalMeasure":{"Voltage":238,"TotalCurrent":105,"TotalLoad":17,"TotalEnergy":1451,"OverallPowerFactor":0.67,"Frequency":50.03,"Phase":-33.67,"EnergyStart":"2020-06-30T17:04:48+01:00"}, "Outputs":[ {"ID":1,"Name":"Power output 1","State":0,"Action":6,"Delay":5000,"Current":0,"PowerFactor":1.00,"Phase":0.00,"Energy":701,"ReverseEnergy":0,"Load":0}, {"ID":2,"Name":"Power output 2","State":1,"Action":6,"Delay":5000,"Current":105,"PowerFactor":0.65,"Phase":-33.67,"Energy":750,"ReverseEnergy":0,"Load":17}, {"ID":3,"Name":"Free Contact 3","State":1,"Action":6,"Delay":5000}, {"ID":4,"Name":"Free Contact 4","State":0,"Action":6,"Delay":5000} ], "Inputs":[ {"ID":1,"Name":"Input 1","State":0,"S0Counter":0}, {"ID":2,"Name":"Input 2","State":0,"S0Counter":0} ]}</code>

= Extended MQTT flex JSON config examples =

== Default NETIO MQTT-flex configuration ==
This example demonstrates setup for connection to public <code>broker.hivemq.com</code>, measurement reporting and output control.

The device cabe be controlled via <code>netio/${DEVICE_NAME}/output/1/action topic</code> by sending standard NETIO action values:
* 0 - OFF
* 1 - ON
* 2 - SHORT OFF
* 3 - SHORT ON
* 4 - TOGGLE
* 5 - NO ACTION.

The device report measurements:

* Output state - every 15 minutes or by change
* Voltage [V]- every 5 minutes or by change of 1 V
* Current [mA]- every 5 minutes or by change of 50 mA
* Load(Power) [W]- every 5 minutes or by change of 10 W
* Energy(Consumption) [Wh]- every 15 minutes or by change of 1Wh
* True Power Factor (TPF) [-]- every 5 minutes or by change of 0.02
* Frequency [Hz]- every 1 hour or by change of 0.1 Hz

For register all values, you can use wildcard <code>netio/${DEVICE_NAME}/output/1/#</code>

{
"config":{
"broker":{
"url":"broker.hivemq.com",
"protocol":"mqtt",
"port":1883,
"ssl":false,
"type":"generic",
"username":"",
"password":"",
"clientid":"moje${DEVICE_NAME}${DEVICE_MAC}",
"keepalive":30
},
"subscribe":[
{
"topic":"netio/${DEVICE_NAME}/output/1/action",
"qos":0,
"target":"OUTPUTS/1/ACTION",
"action":"${payload}"
},
{
"topic":"netio/${DEVICE_NAME}/output/1/switch",
"qos":0,
"target":"OUTPUTS/1/ACTION",
"action":4
}
],
"publish":[
{
"topic":"netio/${DEVICE_MAC}/output/1/state",
"qos":0,
"retain":true,
"payload":"${OUTPUTS/1/STATE}",
"events":[
{
"type":"change",
"source":"OUTPUTS/1/STATE"
},
{
"type":"timer",
"period":900
}
]
},
{
"topic":"netio/${DEVICE_NAME}/output/1/voltage",
"qos":0,
"retain":false,
"payload":"${OUTPUTS/1/VOLTAGE}",
"events":[
{
"type":"timer",
"period":300
},
{
"type":"delta",
"source":"OUTPUTS/1/VOLTAGE",
"delta":1
}
]
},
{
"topic":"netio/${DEVICE_NAME}/output/1/current",
"qos":0,
"retain":false,
"payload":"${OUTPUTS/1/CURRENT}",
"events":[
{
"type":"timer",
"period":300
},
{
"type":"delta",
"source":"OUTPUTS/1/CURRENT",
"delta":50
}
]
},
{
"topic":"netio/${DEVICE_NAME}/output/1/load",
"qos":0,
"retain":false,
"payload":"${OUTPUTS/1/LOAD}",
"events":[
{
"type":"timer",
"period":300
},
{
"type":"delta",
"source":"OUTPUTS/1/LOAD",
"delta":10
}
]
},
{
"topic":"netio/${DEVICE_NAME}/output/1/energy",
"qos":0,
"retain":false,
"payload":"${OUTPUTS/1/ENERGY}",
"events":[
{
"type":"timer",
"period":900
},
{
"type":"delta",
"source":"OUTPUTS/1/ENERGY",
"delta":1
}
]
},
{
"topic":"netio/${DEVICE_NAME}/output/1/tpf",
"qos":0,
"retain":false,
"payload":"${OUTPUTS/1/POWER_FACTOR}",
"events":[
{
"type":"timer",
"period":900
},
{
"type":"delta",
"source":"OUTPUTS/1/POWER_FACTOR",
"delta":0.02
}
]
},
{
"topic":"netio/${DEVICE_NAME}/output/1/frequency",
"qos":0,
"retain":false,
"payload":"${OUTPUTS/1/FREQUENCY}",
"events":[
{
"type":"timer",
"period":3600
},
{
"type":"delta",
"source":"OUTPUTS/1/FREQUENCY",
"delta":0.1
}
]
}
]
}
}

MQTT-flex

2023-06-06T14:29:16Z

Bbakala: /* Group EventsFW 4.0.0+ */

The MQTT-flex version of the MQTT protocol can be configured in detail thanks to the “flex” extension.

https://www.netio-products.com/en/glossary/mqtt-flex

Why MQTT-flex 
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 [https://en.wikipedia.org/wiki/MQTT 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 [https://en.wikipedia.org/wiki/JSON 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 101x 
* PowerCable REST 101x 
* PowerPDU 4PS 
* PowerPDU 4KS 
* PowerPDU 8QS 
* PowerDIN 4PZ 
* PowerBOX 3Px 
* PowerBOX 4Kx 

FW version: 
>2.2.1

===Not supported NETIO devices:===
* PowerPDU 4C 
* NETIO 4 
* NETIO 4All 

= Simple MQTT-flex configuration + explanation =

''We strongly recommend to create and test MQTT-flex configuration on "local" device what can be easily restarted. The validation of config before saving is not 100% and for example some specific typos can cause a freeze of a device - the solution is to restart a device (unplug/plug input power cable). If the configuration is saved and device is working then there are no known failure case so it is safe to use this configuration on the "remote" devices.''

{
"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":false,
"payload":"${OUTPUTS/1/STATE}",
"events":[
{
"type":"timer",
"period":"1000"
}
]
}
]
}
}
=== Client Configuration (broker section) ===
Put here MQTT client connection setup

This configuration example set NETIO device to connect to broker.hivemq.com with mqtt protocol, no ssl connection with credetials freedom/peace|love|empathy4ALL.

"broker":{
"url":"broker.hivemq.com",
"protocol":"mqtt",
"port":1883,
"ssl":false,
"type":"generic",
"username":"freedom",
"password":"peace|LOVE|empathy4ALL"
},

=== Device Control (subscribe section) ===
Put here array of topics where to subscribe

Device output 1 is controlled with action received by subscription to netio/${DEVICE_NAME}/output/1/action topic with QOS 0

"subscribe":[{
"topic":"netio/${DEVICE_NAME}/output/1/action",
"qos":0,
"target":"OUTPUTS/1/ACTION",
"action":"${payload}"
}
],

=== Output State monitoring (publish section) ===
Put here array of topics where to publish.

Device send every 1000 s message to topic with QOS 0, retain true information with output 1 state

"publish":[{
"topic":"netio/${DEVICE_NAME}/output/1/state",
"qos":0,
"retain":true,
"payload":"${OUTPUTS/1/STATE}",
"events":[
{
"type":"timer",
"period":"1000"
}
]
}
]

= 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 ===
{| class="wikitable"
! style="font-weight:bold; background-color:#9b9b9b;" | Item
! style="font-weight:bold; background-color:#9b9b9b;" | Presence
! style="font-weight:bold; background-color:#9b9b9b;" | Possible Values
! style="font-weight:bold; background-color:#9b9b9b;" | Description
! style="font-weight:bold; background-color:#9b9b9b;" | JSON Config Usage
|-
| style="background-color:#efefef;" | url
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" |
| style="background-color:#efefef;" | MQTT broker URL
| style="background-color:#efefef;" | "url":"broker.hivemq.com"
|-
| style="background-color:#efefef;" | port
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | 1 - 65535
| style="background-color:#efefef;" | MQTT broker port
| style="background-color:#efefef;" | "port":1883
|-
| style="background-color:#efefef;" | protocol
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" |
| style="background-color:#efefef;" | protocol spec - mqtt
| style="background-color:#efefef;" | "protocol": "mqtt"
|-
| style="background-color:#efefef;" | ssl
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | true, false
| style="background-color:#efefef;" | Use SSL crypted communication selector
| style="background-color:#efefef;" | "ssl":false
|-
| style="background-color:#efefef;" | type
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | generic
| style="background-color:#efefef;" | Communication/setup type option
| style="background-color:#efefef;" | "type":"generic"
|-
| style="background-color:#efefef;" | username
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | regexp+len
| style="background-color:#efefef;" | Credentials for MQTT broker. Max. 128 characters (since FW 3.2.4).
| style="background-color:#efefef;" | "username":"freedom"
|-
| style="background-color:#efefef;" | password
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | regexp+len
| style="background-color:#efefef;" | Credentials for MQTT broker. Max. 256 characters (since FW 3.2.4).
| style="background-color:#efefef;" | "password":"peace|LOVE|empathy4ALL"
|-
| style="background-color:#efefef;" | clientid
| style="background-color:#efefef;" | optional
| style="background-color:#efefef;" | regexp+len
| style="background-color:#efefef;" | MQTT clientid. Max. 128 characters (since FW 3.2.4). Variables ${DEVICE_MAC} or ${DEVICE_NAME} can be used
| style="background-color:#efefef;" | "clientid":"myEcoTable01"
|-
| style="background-color:#efefef;" | keepalive
| style="background-color:#efefef;" | optional
| style="background-color:#efefef;" | 1 - 65535
| style="background-color:#efefef;" | MQTT keep alive period in seconds
| style="background-color:#efefef;" | "keepalive":90
|}

Note 1: clientid attribute is mandatory for MQTT(s) communication. When not configured, random ID will be generated.

Note 2: To proper communication with MS Azure - it is necessary to set up IoT Hub to use TLS 1.2

See section "TLS 1.2 enforcement available in select regions" in following guidelines https://docs.microsoft.com/en-us/azure/iot-hub/iot-hub-tls-support

=== Examples ===
==== Standard setup ====

==== Security (SSL / TLS) secured setup ====
You can enable MQTTs by using the encrypted port 8883 + "ssl":true.

==== Variables used setup ====

== 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 ===
{| class="wikitable"
! style="font-weight:bold; background-color:#9b9b9b;" | Item
! style="font-weight:bold; background-color:#9b9b9b;" | Presence
! style="font-weight:bold; background-color:#9b9b9b;" | Possible Values
! style="font-weight:bold; background-color:#9b9b9b;" | Description
! style="font-weight:bold; background-color:#9b9b9b;" | JSON Config Usage
|-
| style="background-color:#efefef;" | topic
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | see table below
| style="background-color:#efefef;" | specification of the topic, which MQTT-flex device listens from broker and act accordingly. Max. 128 characters. The "#" can be used since FW 3.2.4 - see note under this table.
| style="background-color:#efefef;" | "topic":"netio/${DEVICE_NAME}/output/1/action"
|-
| style="background-color:#efefef;" | qos
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | 0, 1 or 2
| style="background-color:#efefef;" | 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}
| style="background-color:#efefef;" | "qos":0
|-
| style="background-color:#efefef;" | target
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" |
| style="background-color:#efefef;" | internal definition of action, which can be performed above the specified output
| style="background-color:#efefef;" | "target":"OUTPUTS/1/ACTION"
|-
| style="background-color:#efefef;" | action
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" |
| style="background-color:#efefef;" | a payload or a value the action attribute needs to have passed to
| style="background-color:#efefef;" | "action":"${payload}"
|-
| style="background-color:#efefef;" | actiondefNot supported yet
| style="background-color:#efefef;" | optional
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
|-
| style="background-color:#efefef;" | jsonNot supported yet
| style="background-color:#efefef;" | optional
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
|}

Note: The "#" wildcard can be used in subscribe topic definition. The multi-level wildcard character MUST be specified either on its own or following a topic level separator. In either case it MUST be the last character specified in the Topic.

For example, if a Device subscribes to “devices/{device_id}/messages/devicebound/#”, it would receive messages published using these topic names:

“devices/{device_id}/messages/devicebound/”

“devices/{device_id}/messages/devicebound/{property_bag}”

This should be usefull for use with MS Azure - IoT hub.

=== MQTT Subscribe as event to trigger action <code>FW 4.0.0+</code> ===

This feature allow to subscribe to specific MQTT topic and pass payload to Rules or MQTT-flex as event.

target: <code>PROTOCOLS/MQTT/EVENT</code>

"subscribe": [
{
"action": "${payload}",
"qos": 0,
"target": "PROTOCOLS/MQTT/EVENT",
"topic": "broker/12345/MQTT_EVENT/"
}
]

=== Examples ===
==== Toggle output with standard payload ====
==== Toggle output with custom payload ====
==== Subscribe to more than one topic ====
==== Trigger Rule and MQTT publish from MQTT subscribe <code>FW 4.0.0+</code> ====
This example show Request response implementation in MQTT and toggle action made by Rules.

When message with payload <code>getValues</code> is published to topic <code>broker/gv90018g/COMMAND</code> MQTT flex will create an event with name <code>PROTOCOLS/MQTT/EVENT</code> (fixed name cannot be changed) and value <code>getValues</code>. On this event will act all events and conditions set in MQTT-flex and Rules which are set to listening to change on <code>PROTOCOLS/MQTT/EVENT</code> and equals to value <code>getValues</code>. See bold marked parameters in example configuration below.

Once the triggered action is done it is needed to reset MQTT channel to <code>OK</code> status becaus event are reacting only to change. If the channel is not reset the next even would not be triggered.

Rules Configuration:
{
"conditions": {
"PROTOCOLS/MQTT/EVENT": "getValues"
},
"actions": {
"OUTPUTS/1/ACTION": 4
}
}

MQTT Configuration:
{
"broker":{
"clientid":"netio${DEVICE_SN}",
"keepalive":30,
"password":"abcdefghijk",
"port":8883,
"protocol":"mqtt",
"ssl":true,
"type":"generic",
"url":"broker.cloud.netio.eu",
"username":"gv90018g"
},
"groupEvents":[
{
"events":[
{
"source":"PROTOCOLS/MQTT/EVENT",
"type":"change",
"value":"getValues"
}
],
"appliedTopics":[
"broker/gv90018g/OUTPUTS/1/STATE",
"broker/gv90018g/COMMAND"
]
}
],
"publish":[
{
"payload":"${OUTPUTS/1/STATE}",
"qos":0,
"retain":true,
"topic":"broker/gv90018g/OUTPUTS/1/STATE"
},
{
"payload":"OK",
"qos":0,
"retain":true,
"topic":"broker/gv90018g/COMMAND"
}
],
"subscribe":[
{
"action":"${payload}",
"qos":0,
"target":"PROTOCOLS/MQTT/EVENT",
"topic":"broker/gv90018g/COMMAND"
}
]
}

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 ===
{| class="wikitable"
! style="font-weight:bold; background-color:#9b9b9b;" | Item
! style="font-weight:bold; background-color:#9b9b9b;" | Presence
! style="font-weight:bold; background-color:#9b9b9b;" | Possible Values
! style="font-weight:bold; background-color:#9b9b9b;" | Description
! style="font-weight:bold; background-color:#9b9b9b;" | JSON Config Usage
|-
| style="background-color:#efefef;" | topic
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | see table below
| style="background-color:#efefef;" | definition of the topic, how it is registered towards MQTT broker. Max. 128 characters.
| style="background-color:#efefef;" | "topic":"netio/${DEVICE_NAME}/output/1/load"
|-
| style="background-color:#efefef;" | qos
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | see table below
| style="background-color:#efefef;" | 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}
| style="background-color:#efefef;" |
|-
| style="background-color:#efefef;" | retain
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | boolean: true or false
| style="background-color:#efefef;" | 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}
| style="background-color:#efefef;" | "retain":true
|-
| style="background-color:#efefef;" | payload
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | see table below
| style="background-color:#efefef;" | definition of the payload, what is send to the MQTT broker.
| style="background-color:#efefef;" | "payload":"${OUTPUTS/1/STATE}"
|-
| style="background-color:#efefef;" | events
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | see table below
| style="background-color:#efefef;" | definition of events used for triggering sending of data via mqtt (change, delta, timer)
| style="background-color:#efefef;" |
|-
| style="background-color:#efefef;" | type
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
|-
| style="background-color:#efefef;" | source
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
|-
| style="background-color:#efefef;" | delta
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
|-
| style="background-color:#efefef;" | period
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
|-
| style="background-color:#efefef;" | payloaddefNot supported yet
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
|}

=== Examples ===
==== Publish energy periodically (event timer) ====
==== Publish current on change (delta) ====
==== Publish output state ====
==== Publish to more than one topic with different events ====

= 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 available only on NETIO PowerDIN 4PZ

=== Examples: ===

adressing controll of output 3
OUTPUTS/3/ACTION
getting voltage on output 1
OUTPUTS/1/VOLTAGE
getting state of input 1
INPUTS/1/STATE

= Group Events<code>FW 4.0.0+</code> =
Group events are smart way how to keep configuration simple. It is not replacement of publish section specification but it is extension to trigger group of different topic publish on the same event.

See the example below.

{
"broker": {
"clientid": "netio${DEVICE_SN}",
"keepalive": 30,
"password": "",
"port": 1883,
"protocol": "mqtt",
"ssl": false,
"type": "generic",
"url": "broker.hivemq.com",
"username": ""
},
 "groupEvents": [
{
"events":[
{
"period": 60,
"type": "timer"
}
],
"appliedTopics":[
"devices/${DEVICE_NAME}/output/1/state",
"devices/${DEVICE_NAME}/output/2/state"
]
}
],
"publish": [
{
"events": [
{
"source": "OUTPUTS/1/STATE",
"type": "change"
}
],
"payload": "${OUTPUTS/1/STATE}",
"qos": 0,
"retain": false,
 "topic": "devices/${DEVICE_NAME}/output/1/state"
},{
"events": [
{
"source": "OUTPUTS/2/STATE",
"type": "change"
}
],
"payload": "${OUTPUTS/2/STATE}",
"qos": 0,
"retain": false,
 "topic": "devices/${DEVICE_NAME}/output/2/state"
}
]
}

= 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 ===
==== VOLTAGE ====
Unit: <code>V</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Present RMS voltage on output 1 is ${OUTPUTS/1/VOLTAGE}"</code>

Example 2: <code>"source":"${OUTPUTS/1/VOLTAGE}"</code>

==== CURRENT ====
Unit: <code>mA</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Present RMS current on output 1 is ${OUTPUTS/1/CURRENT}"</code>

Example 2: <code>"source":"${OUTPUTS/1/CURRENT}"</code>

==== POWER_FACTOR ====
Unit: <code>[-]</code>

Type: float (2 decimals)

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"True Power Factor on output 1 is ${OUTPUTS/1/POWER_FACTOR}"</code>

Example 2: <code>"source":"${OUTPUTS/1/POWER_FACTOR}"</code>

==== LOAD ====
Unit: <code>W</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Present load on output 1 is ${OUTPUTS/1/LOAD}W"</code>

Example 2: <code>"payload":"Device's load connected to output 1 is ${OUTPUTS/1/LOAD}W"</code>

Example 3: <code>"source":"${OUTPUTS/1/LOAD}"</code>

==== STATE ====
Type: bool(integer) - <code>0</code> or <code>1</code>

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Present output 1 state is ${OUTPUTS/1/STATE}"</code>

Example 2: <code>"source":"${OUTPUTS/1/STATE}"</code>

==== ACTION ====
Type: integer

Possible actions:
* <code>0</code> - set state OFF
* <code>1</code> - set state ON
* <code>2</code> - short OFF (restart)
* <code>3</code> - short ON
* <code>4</code> - toggle (switch)
* <code>5</code> - no change

Allowed in: <code>"target"</code>

Example: <code>"target":"OUTPUTS/1/ACTION"</code>

==== DELAY [ms] ====
==== NAME ====
==== FREQUENCY ====
Unit: <code>Hz</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example: <code>"payload":"Frequency in power grid is ${OUTPUTS/1/ENERGY}Hz"</code>

==== ENERGY ====
Energy consumed by an device connected to NETIO device output.

Unit: <code>Wh</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Consumed energy on output 1 is ${OUTPUTS/1/ENERGY}Wh"</code>

Example 2: <code>"source":"${OUTPUTS/1/ENERGY}"</code>

==== REVERSE_ENERGY ====
Energy delivered back to grid. For example from solar system connected to NETIO device output.

Unit: <code>Wh</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Delivered energy on output 1 is ${OUTPUTS/1/REVERSE_ENERGY}Wh"</code>

Example 2: <code>"source":"${OUTPUTS/1/REVERSE_ENERGY}"</code>

==== ENERGY_START ====
Date when the counters ENERGY and REVERSE_ENERGY have been resetted by user.

Unit: <code>unix timestamp</code>

Type: integer

Allowed in: <code>"payload"</code>

Example 1: <code>"payload":"Energy measured since ${OUTPUTS/1/ENERGY_START} unix time"</code>

Example 2: <code>"payload":"${OUTPUTS/1/ENERGY_START}"</code> is output payload <code>1567654639</code>

==== ENERGY_START_FMT ====
Date when the counters ENERGY and REVERSE_ENERGY have been resetted by user.

Unit: <code>fmt date format</code>

Type: string

Allowed in: <code>"payload"</code>

Example 1: <code>"payload":"Energy measured since ${OUTPUTS/1/ENERGY_START}"</code>

Example 2: <code>"payload":"${OUTPUTS/1/ENERGY_START_FMT}"</code> is output payload <code>2019-09-05T03:37:19+00:00</code>

==== ENERGY_NR ====
Non-resettable counter of Energy consumed by an device connected to NETIO device output.

Unit: <code>Wh</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Consumed energy on output 1 is ${OUTPUTS/1/ENERGY_NR}Wh"</code>

Example 2: <code>"source":"${OUTPUTS/1/ENERGY_NR}"</code>

==== REVERSE_ENERGY_NR ====
Non-resettable counter of Energy delivered back to grid. For example from solar system connected to NETIO device output.

Unit: <code>Wh</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Delivered energy on output 1 is ${OUTPUTS/1/REVERSE_ENERGY_NR}Wh"</code>

Example 2: <code>"source":"${OUTPUTS/1/REVERSE_ENERGY_NR}"</code>

==== TOTALs - for 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
* OUTPUTS/TOTAL/PHASE
* OUTPUTS/TOTAL/REVERSE_ENERGY
* OUTPUTS/TOTAL/ENERGY_NR
* OUTPUTS/TOTAL/REVERSE_ENERGY_NR
* OUTPUTS/TOTAL/ENERGY_START
* OUTPUTS/TOTAL/ENERGY_START_FMT

==== REST_JSON ====
Allow use of NETIO JSON structure to control outputs.

Type: string / JSON

Allowed in: <code>"target"</code> for Subscribe section

Example: <code>"target": "REST_JSON"</code>

The payload is JSON structure identical to NETIO JSON API M2M Protocol (documentation available at https://www.netio-products.com/files/NETIO-M2M-API-Protocol-JSON.pdf). You can control one or multiple outputs.

Payload example 1 - Toggle output 1: <code>{"Outputs":[{"ID": 1,"Action": 4}]}</code>

Payload example 2 - Turn output 1 OFF and output 3 ON: <code>{"Outputs":[{"ID":1,"Action":0},{"ID":3,"Action":1}]}</code>

=== INPUT variables ===
==== STATE ====
Type: bool(integer) - <code>0</code> or <code>1</code>

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Present input 1 state is ${INPUTS/1/STATE}"</code>

Example 2: <code>"source":"${INPUTS/1/STATE}"</code>

==== S0 ====
S0 Counter value
Unit: <code>-</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Input 1 S0 Counter value is ${INPUTS/1/S0}impulses"</code>

Example 2: <code>"source":"${INPUTS/1/S0}"</code>

== Payload/topic variables ==

=== DEVICE_NAME ===
Can be used in: "payload", "topic"

Example 1: <code>"payload":"${DEVICE_NAME}"</code>

Example 2: <code>"topic":"netio/${DEVICE_NAME}/output/1/action"</code>

=== DEVICE_MAC ===

=== UPTIME Not yet implemented ===

=== PAYLOAD ===
Can be used in: "action"

Example: <code>"action":"${PAYLOAD}"</code>

=== OUTPUT_ID Not yet implemented===

=== WIFI_SIGNALNot yet implemented ===

=== OUTPUTS_STATUS ===
Provide complete outputs status and measurement if supported.

Type: string / JSON

Allowed in: <code>"payload"</code> for Publish section

Example: <code>"payload":"${OUTPUTS_STATUS}"</code>

Payload example: <code>{ "GlobalMeasure":{"Voltage":236,"TotalCurrent":72,"TotalLoad":11,"TotalEnergy":167,"OverallPowerFactor":0.64,"Frequency":50.07,"Phase":-36.86,"EnergyStart":"2020-06-30T17:04:48+01:00"}, "Outputs":[ {"ID":1,"Name":"Power output 1","State":1,"Action":6,"Delay":2020,"Current":72,"PowerFactor":0.64,"Phase":-36.86,"Energy":139,"ReverseEnergy":0,"Load":11}, {"ID":2,"Name":"Power output 2","State":1,"Action":6,"Delay":2020,"Current":0,"PowerFactor":1.00,"Phase":0.00,"Energy":27,"ReverseEnergy":0,"Load":0}, {"ID":3,"Name":"Free Contact 3","State":1,"Action":6,"Delay":2020}, {"ID":4,"Name":"Free Contact 4","State":1,"Action":6,"Delay":2020} ]}</code>

=== INPUTS_STATUS ===
Provide complete inputs status if supported. Since FW 3.0.0

Type: string / JSON

Allowed in: <code>"payload"</code> for Publish section

Example: <code>"payload":"${INPUTS_STATUS}"</code>

Payload example: <code>{ "Inputs":[ {"ID":1,"Name":"Input 1","State":0,"S0Counter":0}, {"ID":2,"Name":"Input 2","State":0,"S0Counter":0} ]}</code>

=== INOUT_STATUS ===
Provide complete inputs and output status and measurement if supported. Since FW 3.0.0

Type: string / JSON

Allowed in: <code>"payload"</code> for Publish section

Example: <code>"payload":"${INOUT_STATUS}"</code>

Payload example: <code>{ "GlobalMeasure":{"Voltage":238,"TotalCurrent":105,"TotalLoad":17,"TotalEnergy":1451,"OverallPowerFactor":0.67,"Frequency":50.03,"Phase":-33.67,"EnergyStart":"2020-06-30T17:04:48+01:00"}, "Outputs":[ {"ID":1,"Name":"Power output 1","State":0,"Action":6,"Delay":5000,"Current":0,"PowerFactor":1.00,"Phase":0.00,"Energy":701,"ReverseEnergy":0,"Load":0}, {"ID":2,"Name":"Power output 2","State":1,"Action":6,"Delay":5000,"Current":105,"PowerFactor":0.65,"Phase":-33.67,"Energy":750,"ReverseEnergy":0,"Load":17}, {"ID":3,"Name":"Free Contact 3","State":1,"Action":6,"Delay":5000}, {"ID":4,"Name":"Free Contact 4","State":0,"Action":6,"Delay":5000} ], "Inputs":[ {"ID":1,"Name":"Input 1","State":0,"S0Counter":0}, {"ID":2,"Name":"Input 2","State":0,"S0Counter":0} ]}</code>

= Extended MQTT flex JSON config examples =

== Default NETIO MQTT-flex configuration ==
This example demonstrates setup for connection to public <code>broker.hivemq.com</code>, measurement reporting and output control.

The device cabe be controlled via <code>netio/${DEVICE_NAME}/output/1/action topic</code> by sending standard NETIO action values:
* 0 - OFF
* 1 - ON
* 2 - SHORT OFF
* 3 - SHORT ON
* 4 - TOGGLE
* 5 - NO ACTION.

The device report measurements:

* Output state - every 15 minutes or by change
* Voltage [V]- every 5 minutes or by change of 1 V
* Current [mA]- every 5 minutes or by change of 50 mA
* Load(Power) [W]- every 5 minutes or by change of 10 W
* Energy(Consumption) [Wh]- every 15 minutes or by change of 1Wh
* True Power Factor (TPF) [-]- every 5 minutes or by change of 0.02
* Frequency [Hz]- every 1 hour or by change of 0.1 Hz

For register all values, you can use wildcard <code>netio/${DEVICE_NAME}/output/1/#</code>

{
"config":{
"broker":{
"url":"broker.hivemq.com",
"protocol":"mqtt",
"port":1883,
"ssl":false,
"type":"generic",
"username":"",
"password":"",
"clientid":"moje${DEVICE_NAME}${DEVICE_MAC}",
"keepalive":30
},
"subscribe":[
{
"topic":"netio/${DEVICE_NAME}/output/1/action",
"qos":0,
"target":"OUTPUTS/1/ACTION",
"action":"${payload}"
},
{
"topic":"netio/${DEVICE_NAME}/output/1/switch",
"qos":0,
"target":"OUTPUTS/1/ACTION",
"action":4
}
],
"publish":[
{
"topic":"netio/${DEVICE_MAC}/output/1/state",
"qos":0,
"retain":true,
"payload":"${OUTPUTS/1/STATE}",
"events":[
{
"type":"change",
"source":"OUTPUTS/1/STATE"
},
{
"type":"timer",
"period":900
}
]
},
{
"topic":"netio/${DEVICE_NAME}/output/1/voltage",
"qos":0,
"retain":false,
"payload":"${OUTPUTS/1/VOLTAGE}",
"events":[
{
"type":"timer",
"period":300
},
{
"type":"delta",
"source":"OUTPUTS/1/VOLTAGE",
"delta":1
}
]
},
{
"topic":"netio/${DEVICE_NAME}/output/1/current",
"qos":0,
"retain":false,
"payload":"${OUTPUTS/1/CURRENT}",
"events":[
{
"type":"timer",
"period":300
},
{
"type":"delta",
"source":"OUTPUTS/1/CURRENT",
"delta":50
}
]
},
{
"topic":"netio/${DEVICE_NAME}/output/1/load",
"qos":0,
"retain":false,
"payload":"${OUTPUTS/1/LOAD}",
"events":[
{
"type":"timer",
"period":300
},
{
"type":"delta",
"source":"OUTPUTS/1/LOAD",
"delta":10
}
]
},
{
"topic":"netio/${DEVICE_NAME}/output/1/energy",
"qos":0,
"retain":false,
"payload":"${OUTPUTS/1/ENERGY}",
"events":[
{
"type":"timer",
"period":900
},
{
"type":"delta",
"source":"OUTPUTS/1/ENERGY",
"delta":1
}
]
},
{
"topic":"netio/${DEVICE_NAME}/output/1/tpf",
"qos":0,
"retain":false,
"payload":"${OUTPUTS/1/POWER_FACTOR}",
"events":[
{
"type":"timer",
"period":900
},
{
"type":"delta",
"source":"OUTPUTS/1/POWER_FACTOR",
"delta":0.02
}
]
},
{
"topic":"netio/${DEVICE_NAME}/output/1/frequency",
"qos":0,
"retain":false,
"payload":"${OUTPUTS/1/FREQUENCY}",
"events":[
{
"type":"timer",
"period":3600
},
{
"type":"delta",
"source":"OUTPUTS/1/FREQUENCY",
"delta":0.1
}
]
}
]
}
}

MQTT-flex

2023-06-06T14:23:06Z

Bbakala: /* Group EventsFW 4.0.0+ */

The MQTT-flex version of the MQTT protocol can be configured in detail thanks to the “flex” extension.

https://www.netio-products.com/en/glossary/mqtt-flex

Why MQTT-flex 
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 [https://en.wikipedia.org/wiki/MQTT 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 [https://en.wikipedia.org/wiki/JSON 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 101x 
* PowerCable REST 101x 
* PowerPDU 4PS 
* PowerPDU 4KS 
* PowerPDU 8QS 
* PowerDIN 4PZ 
* PowerBOX 3Px 
* PowerBOX 4Kx 

FW version: 
>2.2.1

===Not supported NETIO devices:===
* PowerPDU 4C 
* NETIO 4 
* NETIO 4All 

= Simple MQTT-flex configuration + explanation =

''We strongly recommend to create and test MQTT-flex configuration on "local" device what can be easily restarted. The validation of config before saving is not 100% and for example some specific typos can cause a freeze of a device - the solution is to restart a device (unplug/plug input power cable). If the configuration is saved and device is working then there are no known failure case so it is safe to use this configuration on the "remote" devices.''

{
"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":false,
"payload":"${OUTPUTS/1/STATE}",
"events":[
{
"type":"timer",
"period":"1000"
}
]
}
]
}
}
=== Client Configuration (broker section) ===
Put here MQTT client connection setup

This configuration example set NETIO device to connect to broker.hivemq.com with mqtt protocol, no ssl connection with credetials freedom/peace|love|empathy4ALL.

"broker":{
"url":"broker.hivemq.com",
"protocol":"mqtt",
"port":1883,
"ssl":false,
"type":"generic",
"username":"freedom",
"password":"peace|LOVE|empathy4ALL"
},

=== Device Control (subscribe section) ===
Put here array of topics where to subscribe

Device output 1 is controlled with action received by subscription to netio/${DEVICE_NAME}/output/1/action topic with QOS 0

"subscribe":[{
"topic":"netio/${DEVICE_NAME}/output/1/action",
"qos":0,
"target":"OUTPUTS/1/ACTION",
"action":"${payload}"
}
],

=== Output State monitoring (publish section) ===
Put here array of topics where to publish.

Device send every 1000 s message to topic with QOS 0, retain true information with output 1 state

"publish":[{
"topic":"netio/${DEVICE_NAME}/output/1/state",
"qos":0,
"retain":true,
"payload":"${OUTPUTS/1/STATE}",
"events":[
{
"type":"timer",
"period":"1000"
}
]
}
]

= 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 ===
{| class="wikitable"
! style="font-weight:bold; background-color:#9b9b9b;" | Item
! style="font-weight:bold; background-color:#9b9b9b;" | Presence
! style="font-weight:bold; background-color:#9b9b9b;" | Possible Values
! style="font-weight:bold; background-color:#9b9b9b;" | Description
! style="font-weight:bold; background-color:#9b9b9b;" | JSON Config Usage
|-
| style="background-color:#efefef;" | url
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" |
| style="background-color:#efefef;" | MQTT broker URL
| style="background-color:#efefef;" | "url":"broker.hivemq.com"
|-
| style="background-color:#efefef;" | port
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | 1 - 65535
| style="background-color:#efefef;" | MQTT broker port
| style="background-color:#efefef;" | "port":1883
|-
| style="background-color:#efefef;" | protocol
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" |
| style="background-color:#efefef;" | protocol spec - mqtt
| style="background-color:#efefef;" | "protocol": "mqtt"
|-
| style="background-color:#efefef;" | ssl
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | true, false
| style="background-color:#efefef;" | Use SSL crypted communication selector
| style="background-color:#efefef;" | "ssl":false
|-
| style="background-color:#efefef;" | type
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | generic
| style="background-color:#efefef;" | Communication/setup type option
| style="background-color:#efefef;" | "type":"generic"
|-
| style="background-color:#efefef;" | username
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | regexp+len
| style="background-color:#efefef;" | Credentials for MQTT broker. Max. 128 characters (since FW 3.2.4).
| style="background-color:#efefef;" | "username":"freedom"
|-
| style="background-color:#efefef;" | password
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | regexp+len
| style="background-color:#efefef;" | Credentials for MQTT broker. Max. 256 characters (since FW 3.2.4).
| style="background-color:#efefef;" | "password":"peace|LOVE|empathy4ALL"
|-
| style="background-color:#efefef;" | clientid
| style="background-color:#efefef;" | optional
| style="background-color:#efefef;" | regexp+len
| style="background-color:#efefef;" | MQTT clientid. Max. 128 characters (since FW 3.2.4). Variables ${DEVICE_MAC} or ${DEVICE_NAME} can be used
| style="background-color:#efefef;" | "clientid":"myEcoTable01"
|-
| style="background-color:#efefef;" | keepalive
| style="background-color:#efefef;" | optional
| style="background-color:#efefef;" | 1 - 65535
| style="background-color:#efefef;" | MQTT keep alive period in seconds
| style="background-color:#efefef;" | "keepalive":90
|}

Note 1: clientid attribute is mandatory for MQTT(s) communication. When not configured, random ID will be generated.

Note 2: To proper communication with MS Azure - it is necessary to set up IoT Hub to use TLS 1.2

See section "TLS 1.2 enforcement available in select regions" in following guidelines https://docs.microsoft.com/en-us/azure/iot-hub/iot-hub-tls-support

=== Examples ===
==== Standard setup ====

==== Security (SSL / TLS) secured setup ====
You can enable MQTTs by using the encrypted port 8883 + "ssl":true.

==== Variables used setup ====

== 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 ===
{| class="wikitable"
! style="font-weight:bold; background-color:#9b9b9b;" | Item
! style="font-weight:bold; background-color:#9b9b9b;" | Presence
! style="font-weight:bold; background-color:#9b9b9b;" | Possible Values
! style="font-weight:bold; background-color:#9b9b9b;" | Description
! style="font-weight:bold; background-color:#9b9b9b;" | JSON Config Usage
|-
| style="background-color:#efefef;" | topic
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | see table below
| style="background-color:#efefef;" | specification of the topic, which MQTT-flex device listens from broker and act accordingly. Max. 128 characters. The "#" can be used since FW 3.2.4 - see note under this table.
| style="background-color:#efefef;" | "topic":"netio/${DEVICE_NAME}/output/1/action"
|-
| style="background-color:#efefef;" | qos
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | 0, 1 or 2
| style="background-color:#efefef;" | 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}
| style="background-color:#efefef;" | "qos":0
|-
| style="background-color:#efefef;" | target
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" |
| style="background-color:#efefef;" | internal definition of action, which can be performed above the specified output
| style="background-color:#efefef;" | "target":"OUTPUTS/1/ACTION"
|-
| style="background-color:#efefef;" | action
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" |
| style="background-color:#efefef;" | a payload or a value the action attribute needs to have passed to
| style="background-color:#efefef;" | "action":"${payload}"
|-
| style="background-color:#efefef;" | actiondefNot supported yet
| style="background-color:#efefef;" | optional
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
|-
| style="background-color:#efefef;" | jsonNot supported yet
| style="background-color:#efefef;" | optional
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
|}

Note: The "#" wildcard can be used in subscribe topic definition. The multi-level wildcard character MUST be specified either on its own or following a topic level separator. In either case it MUST be the last character specified in the Topic.

For example, if a Device subscribes to “devices/{device_id}/messages/devicebound/#”, it would receive messages published using these topic names:

“devices/{device_id}/messages/devicebound/”

“devices/{device_id}/messages/devicebound/{property_bag}”

This should be usefull for use with MS Azure - IoT hub.

=== MQTT Subscribe as event to trigger action <code>FW 4.0.0+</code> ===

This feature allow to subscribe to specific MQTT topic and pass payload to Rules or MQTT-flex as event.

target: <code>PROTOCOLS/MQTT/EVENT</code>

"subscribe": [
{
"action": "${payload}",
"qos": 0,
"target": "PROTOCOLS/MQTT/EVENT",
"topic": "broker/12345/MQTT_EVENT/"
}
]

=== Examples ===
==== Toggle output with standard payload ====
==== Toggle output with custom payload ====
==== Subscribe to more than one topic ====
==== Trigger Rule and MQTT publish from MQTT subscribe <code>FW 4.0.0+</code> ====
This example show Request response implementation in MQTT and toggle action made by Rules.

When message with payload <code>getValues</code> is published to topic <code>broker/gv90018g/COMMAND</code> MQTT flex will create an event with name <code>PROTOCOLS/MQTT/EVENT</code> (fixed name cannot be changed) and value <code>getValues</code>. On this event will act all events and conditions set in MQTT-flex and Rules which are set to listening to change on <code>PROTOCOLS/MQTT/EVENT</code> and equals to value <code>getValues</code>. See bold marked parameters in example configuration below.

Once the triggered action is done it is needed to reset MQTT channel to <code>OK</code> status becaus event are reacting only to change. If the channel is not reset the next even would not be triggered.

Rules Configuration:
{
"conditions": {
"PROTOCOLS/MQTT/EVENT": "getValues"
},
"actions": {
"OUTPUTS/1/ACTION": 4
}
}

MQTT Configuration:
{
"broker":{
"clientid":"netio${DEVICE_SN}",
"keepalive":30,
"password":"abcdefghijk",
"port":8883,
"protocol":"mqtt",
"ssl":true,
"type":"generic",
"url":"broker.cloud.netio.eu",
"username":"gv90018g"
},
"groupEvents":[
{
"events":[
{
"source":"PROTOCOLS/MQTT/EVENT",
"type":"change",
"value":"getValues"
}
],
"appliedTopics":[
"broker/gv90018g/OUTPUTS/1/STATE",
"broker/gv90018g/COMMAND"
]
}
],
"publish":[
{
"payload":"${OUTPUTS/1/STATE}",
"qos":0,
"retain":true,
"topic":"broker/gv90018g/OUTPUTS/1/STATE"
},
{
"payload":"OK",
"qos":0,
"retain":true,
"topic":"broker/gv90018g/COMMAND"
}
],
"subscribe":[
{
"action":"${payload}",
"qos":0,
"target":"PROTOCOLS/MQTT/EVENT",
"topic":"broker/gv90018g/COMMAND"
}
]
}

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 ===
{| class="wikitable"
! style="font-weight:bold; background-color:#9b9b9b;" | Item
! style="font-weight:bold; background-color:#9b9b9b;" | Presence
! style="font-weight:bold; background-color:#9b9b9b;" | Possible Values
! style="font-weight:bold; background-color:#9b9b9b;" | Description
! style="font-weight:bold; background-color:#9b9b9b;" | JSON Config Usage
|-
| style="background-color:#efefef;" | topic
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | see table below
| style="background-color:#efefef;" | definition of the topic, how it is registered towards MQTT broker. Max. 128 characters.
| style="background-color:#efefef;" | "topic":"netio/${DEVICE_NAME}/output/1/load"
|-
| style="background-color:#efefef;" | qos
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | see table below
| style="background-color:#efefef;" | 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}
| style="background-color:#efefef;" |
|-
| style="background-color:#efefef;" | retain
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | boolean: true or false
| style="background-color:#efefef;" | 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}
| style="background-color:#efefef;" | "retain":true
|-
| style="background-color:#efefef;" | payload
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | see table below
| style="background-color:#efefef;" | definition of the payload, what is send to the MQTT broker.
| style="background-color:#efefef;" | "payload":"${OUTPUTS/1/STATE}"
|-
| style="background-color:#efefef;" | events
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | see table below
| style="background-color:#efefef;" | definition of events used for triggering sending of data via mqtt (change, delta, timer)
| style="background-color:#efefef;" |
|-
| style="background-color:#efefef;" | type
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
|-
| style="background-color:#efefef;" | source
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
|-
| style="background-color:#efefef;" | delta
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
|-
| style="background-color:#efefef;" | period
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
|-
| style="background-color:#efefef;" | payloaddefNot supported yet
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
|}

=== Examples ===
==== Publish energy periodically (event timer) ====
==== Publish current on change (delta) ====
==== Publish output state ====
==== Publish to more than one topic with different events ====

= 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 available only on NETIO PowerDIN 4PZ

=== Examples: ===

adressing controll of output 3
OUTPUTS/3/ACTION
getting voltage on output 1
OUTPUTS/1/VOLTAGE
getting state of input 1
INPUTS/1/STATE

= Group Events<code>FW 4.0.0+</code> =
Group events are smart way how to keep configuration simple. It is not replacement of publish section specification but it is extension to trigger group of different topic publish on the same event.

See the example below.

{
"broker": {
"clientid": "netio${DEVICE_SN}",
"keepalive": 30,
"password": "",
"port": 1883,
"protocol": "mqtt",
"ssl": false,
"type": "generic",
"url": "broker.hivemq.com",
"username": ""
},
"groupEvents": [
{
"events":[
{
"period": 60,
"type": "timer"
}
],
"appliedTopics":[
"devices/${DEVICE_NAME}/output/1/state",
"devices/${DEVICE_NAME}/output/2/state"
]
}
],
"publish": [
{
"events": [
{
"source": "OUTPUT/1/STATE",
"type": "change"
}
],
"payload": "${OUTPUT/1/STATE}",
"qos": 0,
"retain": false,
"topic": "devices/${DEVICE_NAME}/output/1/state"
},{
"events": [
{
"source": "OUTPUT/2/STATE",
"type": "change"
}
],
"payload": "${OUTPUT/2/STATE}",
"qos": 0,
"retain": false,
"topic": "devices/${DEVICE_NAME}/output/2/state"
}
]
}

= 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 ===
==== VOLTAGE ====
Unit: <code>V</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Present RMS voltage on output 1 is ${OUTPUTS/1/VOLTAGE}"</code>

Example 2: <code>"source":"${OUTPUTS/1/VOLTAGE}"</code>

==== CURRENT ====
Unit: <code>mA</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Present RMS current on output 1 is ${OUTPUTS/1/CURRENT}"</code>

Example 2: <code>"source":"${OUTPUTS/1/CURRENT}"</code>

==== POWER_FACTOR ====
Unit: <code>[-]</code>

Type: float (2 decimals)

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"True Power Factor on output 1 is ${OUTPUTS/1/POWER_FACTOR}"</code>

Example 2: <code>"source":"${OUTPUTS/1/POWER_FACTOR}"</code>

==== LOAD ====
Unit: <code>W</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Present load on output 1 is ${OUTPUTS/1/LOAD}W"</code>

Example 2: <code>"payload":"Device's load connected to output 1 is ${OUTPUTS/1/LOAD}W"</code>

Example 3: <code>"source":"${OUTPUTS/1/LOAD}"</code>

==== STATE ====
Type: bool(integer) - <code>0</code> or <code>1</code>

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Present output 1 state is ${OUTPUTS/1/STATE}"</code>

Example 2: <code>"source":"${OUTPUTS/1/STATE}"</code>

==== ACTION ====
Type: integer

Possible actions:
* <code>0</code> - set state OFF
* <code>1</code> - set state ON
* <code>2</code> - short OFF (restart)
* <code>3</code> - short ON
* <code>4</code> - toggle (switch)
* <code>5</code> - no change

Allowed in: <code>"target"</code>

Example: <code>"target":"OUTPUTS/1/ACTION"</code>

==== DELAY [ms] ====
==== NAME ====
==== FREQUENCY ====
Unit: <code>Hz</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example: <code>"payload":"Frequency in power grid is ${OUTPUTS/1/ENERGY}Hz"</code>

==== ENERGY ====
Energy consumed by an device connected to NETIO device output.

Unit: <code>Wh</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Consumed energy on output 1 is ${OUTPUTS/1/ENERGY}Wh"</code>

Example 2: <code>"source":"${OUTPUTS/1/ENERGY}"</code>

==== REVERSE_ENERGY ====
Energy delivered back to grid. For example from solar system connected to NETIO device output.

Unit: <code>Wh</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Delivered energy on output 1 is ${OUTPUTS/1/REVERSE_ENERGY}Wh"</code>

Example 2: <code>"source":"${OUTPUTS/1/REVERSE_ENERGY}"</code>

==== ENERGY_START ====
Date when the counters ENERGY and REVERSE_ENERGY have been resetted by user.

Unit: <code>unix timestamp</code>

Type: integer

Allowed in: <code>"payload"</code>

Example 1: <code>"payload":"Energy measured since ${OUTPUTS/1/ENERGY_START} unix time"</code>

Example 2: <code>"payload":"${OUTPUTS/1/ENERGY_START}"</code> is output payload <code>1567654639</code>

==== ENERGY_START_FMT ====
Date when the counters ENERGY and REVERSE_ENERGY have been resetted by user.

Unit: <code>fmt date format</code>

Type: string

Allowed in: <code>"payload"</code>

Example 1: <code>"payload":"Energy measured since ${OUTPUTS/1/ENERGY_START}"</code>

Example 2: <code>"payload":"${OUTPUTS/1/ENERGY_START_FMT}"</code> is output payload <code>2019-09-05T03:37:19+00:00</code>

==== ENERGY_NR ====
Non-resettable counter of Energy consumed by an device connected to NETIO device output.

Unit: <code>Wh</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Consumed energy on output 1 is ${OUTPUTS/1/ENERGY_NR}Wh"</code>

Example 2: <code>"source":"${OUTPUTS/1/ENERGY_NR}"</code>

==== REVERSE_ENERGY_NR ====
Non-resettable counter of Energy delivered back to grid. For example from solar system connected to NETIO device output.

Unit: <code>Wh</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Delivered energy on output 1 is ${OUTPUTS/1/REVERSE_ENERGY_NR}Wh"</code>

Example 2: <code>"source":"${OUTPUTS/1/REVERSE_ENERGY_NR}"</code>

==== TOTALs - for 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
* OUTPUTS/TOTAL/PHASE
* OUTPUTS/TOTAL/REVERSE_ENERGY
* OUTPUTS/TOTAL/ENERGY_NR
* OUTPUTS/TOTAL/REVERSE_ENERGY_NR
* OUTPUTS/TOTAL/ENERGY_START
* OUTPUTS/TOTAL/ENERGY_START_FMT

==== REST_JSON ====
Allow use of NETIO JSON structure to control outputs.

Type: string / JSON

Allowed in: <code>"target"</code> for Subscribe section

Example: <code>"target": "REST_JSON"</code>

The payload is JSON structure identical to NETIO JSON API M2M Protocol (documentation available at https://www.netio-products.com/files/NETIO-M2M-API-Protocol-JSON.pdf). You can control one or multiple outputs.

Payload example 1 - Toggle output 1: <code>{"Outputs":[{"ID": 1,"Action": 4}]}</code>

Payload example 2 - Turn output 1 OFF and output 3 ON: <code>{"Outputs":[{"ID":1,"Action":0},{"ID":3,"Action":1}]}</code>

=== INPUT variables ===
==== STATE ====
Type: bool(integer) - <code>0</code> or <code>1</code>

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Present input 1 state is ${INPUTS/1/STATE}"</code>

Example 2: <code>"source":"${INPUTS/1/STATE}"</code>

==== S0 ====
S0 Counter value
Unit: <code>-</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Input 1 S0 Counter value is ${INPUTS/1/S0}impulses"</code>

Example 2: <code>"source":"${INPUTS/1/S0}"</code>

== Payload/topic variables ==

=== DEVICE_NAME ===
Can be used in: "payload", "topic"

Example 1: <code>"payload":"${DEVICE_NAME}"</code>

Example 2: <code>"topic":"netio/${DEVICE_NAME}/output/1/action"</code>

=== DEVICE_MAC ===

=== UPTIME Not yet implemented ===

=== PAYLOAD ===
Can be used in: "action"

Example: <code>"action":"${PAYLOAD}"</code>

=== OUTPUT_ID Not yet implemented===

=== WIFI_SIGNALNot yet implemented ===

=== OUTPUTS_STATUS ===
Provide complete outputs status and measurement if supported.

Type: string / JSON

Allowed in: <code>"payload"</code> for Publish section

Example: <code>"payload":"${OUTPUTS_STATUS}"</code>

Payload example: <code>{ "GlobalMeasure":{"Voltage":236,"TotalCurrent":72,"TotalLoad":11,"TotalEnergy":167,"OverallPowerFactor":0.64,"Frequency":50.07,"Phase":-36.86,"EnergyStart":"2020-06-30T17:04:48+01:00"}, "Outputs":[ {"ID":1,"Name":"Power output 1","State":1,"Action":6,"Delay":2020,"Current":72,"PowerFactor":0.64,"Phase":-36.86,"Energy":139,"ReverseEnergy":0,"Load":11}, {"ID":2,"Name":"Power output 2","State":1,"Action":6,"Delay":2020,"Current":0,"PowerFactor":1.00,"Phase":0.00,"Energy":27,"ReverseEnergy":0,"Load":0}, {"ID":3,"Name":"Free Contact 3","State":1,"Action":6,"Delay":2020}, {"ID":4,"Name":"Free Contact 4","State":1,"Action":6,"Delay":2020} ]}</code>

=== INPUTS_STATUS ===
Provide complete inputs status if supported. Since FW 3.0.0

Type: string / JSON

Allowed in: <code>"payload"</code> for Publish section

Example: <code>"payload":"${INPUTS_STATUS}"</code>

Payload example: <code>{ "Inputs":[ {"ID":1,"Name":"Input 1","State":0,"S0Counter":0}, {"ID":2,"Name":"Input 2","State":0,"S0Counter":0} ]}</code>

=== INOUT_STATUS ===
Provide complete inputs and output status and measurement if supported. Since FW 3.0.0

Type: string / JSON

Allowed in: <code>"payload"</code> for Publish section

Example: <code>"payload":"${INOUT_STATUS}"</code>

Payload example: <code>{ "GlobalMeasure":{"Voltage":238,"TotalCurrent":105,"TotalLoad":17,"TotalEnergy":1451,"OverallPowerFactor":0.67,"Frequency":50.03,"Phase":-33.67,"EnergyStart":"2020-06-30T17:04:48+01:00"}, "Outputs":[ {"ID":1,"Name":"Power output 1","State":0,"Action":6,"Delay":5000,"Current":0,"PowerFactor":1.00,"Phase":0.00,"Energy":701,"ReverseEnergy":0,"Load":0}, {"ID":2,"Name":"Power output 2","State":1,"Action":6,"Delay":5000,"Current":105,"PowerFactor":0.65,"Phase":-33.67,"Energy":750,"ReverseEnergy":0,"Load":17}, {"ID":3,"Name":"Free Contact 3","State":1,"Action":6,"Delay":5000}, {"ID":4,"Name":"Free Contact 4","State":0,"Action":6,"Delay":5000} ], "Inputs":[ {"ID":1,"Name":"Input 1","State":0,"S0Counter":0}, {"ID":2,"Name":"Input 2","State":0,"S0Counter":0} ]}</code>

= Extended MQTT flex JSON config examples =

== Default NETIO MQTT-flex configuration ==
This example demonstrates setup for connection to public <code>broker.hivemq.com</code>, measurement reporting and output control.

The device cabe be controlled via <code>netio/${DEVICE_NAME}/output/1/action topic</code> by sending standard NETIO action values:
* 0 - OFF
* 1 - ON
* 2 - SHORT OFF
* 3 - SHORT ON
* 4 - TOGGLE
* 5 - NO ACTION.

The device report measurements:

* Output state - every 15 minutes or by change
* Voltage [V]- every 5 minutes or by change of 1 V
* Current [mA]- every 5 minutes or by change of 50 mA
* Load(Power) [W]- every 5 minutes or by change of 10 W
* Energy(Consumption) [Wh]- every 15 minutes or by change of 1Wh
* True Power Factor (TPF) [-]- every 5 minutes or by change of 0.02
* Frequency [Hz]- every 1 hour or by change of 0.1 Hz

For register all values, you can use wildcard <code>netio/${DEVICE_NAME}/output/1/#</code>

{
"config":{
"broker":{
"url":"broker.hivemq.com",
"protocol":"mqtt",
"port":1883,
"ssl":false,
"type":"generic",
"username":"",
"password":"",
"clientid":"moje${DEVICE_NAME}${DEVICE_MAC}",
"keepalive":30
},
"subscribe":[
{
"topic":"netio/${DEVICE_NAME}/output/1/action",
"qos":0,
"target":"OUTPUTS/1/ACTION",
"action":"${payload}"
},
{
"topic":"netio/${DEVICE_NAME}/output/1/switch",
"qos":0,
"target":"OUTPUTS/1/ACTION",
"action":4
}
],
"publish":[
{
"topic":"netio/${DEVICE_MAC}/output/1/state",
"qos":0,
"retain":true,
"payload":"${OUTPUTS/1/STATE}",
"events":[
{
"type":"change",
"source":"OUTPUTS/1/STATE"
},
{
"type":"timer",
"period":900
}
]
},
{
"topic":"netio/${DEVICE_NAME}/output/1/voltage",
"qos":0,
"retain":false,
"payload":"${OUTPUTS/1/VOLTAGE}",
"events":[
{
"type":"timer",
"period":300
},
{
"type":"delta",
"source":"OUTPUTS/1/VOLTAGE",
"delta":1
}
]
},
{
"topic":"netio/${DEVICE_NAME}/output/1/current",
"qos":0,
"retain":false,
"payload":"${OUTPUTS/1/CURRENT}",
"events":[
{
"type":"timer",
"period":300
},
{
"type":"delta",
"source":"OUTPUTS/1/CURRENT",
"delta":50
}
]
},
{
"topic":"netio/${DEVICE_NAME}/output/1/load",
"qos":0,
"retain":false,
"payload":"${OUTPUTS/1/LOAD}",
"events":[
{
"type":"timer",
"period":300
},
{
"type":"delta",
"source":"OUTPUTS/1/LOAD",
"delta":10
}
]
},
{
"topic":"netio/${DEVICE_NAME}/output/1/energy",
"qos":0,
"retain":false,
"payload":"${OUTPUTS/1/ENERGY}",
"events":[
{
"type":"timer",
"period":900
},
{
"type":"delta",
"source":"OUTPUTS/1/ENERGY",
"delta":1
}
]
},
{
"topic":"netio/${DEVICE_NAME}/output/1/tpf",
"qos":0,
"retain":false,
"payload":"${OUTPUTS/1/POWER_FACTOR}",
"events":[
{
"type":"timer",
"period":900
},
{
"type":"delta",
"source":"OUTPUTS/1/POWER_FACTOR",
"delta":0.02
}
]
},
{
"topic":"netio/${DEVICE_NAME}/output/1/frequency",
"qos":0,
"retain":false,
"payload":"${OUTPUTS/1/FREQUENCY}",
"events":[
{
"type":"timer",
"period":3600
},
{
"type":"delta",
"source":"OUTPUTS/1/FREQUENCY",
"delta":0.1
}
]
}
]
}
}

MQTT-flex

2023-06-06T14:20:39Z

Bbakala: /* Group EventsFW 4.0.0+ */

The MQTT-flex version of the MQTT protocol can be configured in detail thanks to the “flex” extension.

https://www.netio-products.com/en/glossary/mqtt-flex

Why MQTT-flex 
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 [https://en.wikipedia.org/wiki/MQTT 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 [https://en.wikipedia.org/wiki/JSON 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 101x 
* PowerCable REST 101x 
* PowerPDU 4PS 
* PowerPDU 4KS 
* PowerPDU 8QS 
* PowerDIN 4PZ 
* PowerBOX 3Px 
* PowerBOX 4Kx 

FW version: 
>2.2.1

===Not supported NETIO devices:===
* PowerPDU 4C 
* NETIO 4 
* NETIO 4All 

= Simple MQTT-flex configuration + explanation =

''We strongly recommend to create and test MQTT-flex configuration on "local" device what can be easily restarted. The validation of config before saving is not 100% and for example some specific typos can cause a freeze of a device - the solution is to restart a device (unplug/plug input power cable). If the configuration is saved and device is working then there are no known failure case so it is safe to use this configuration on the "remote" devices.''

{
"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":false,
"payload":"${OUTPUTS/1/STATE}",
"events":[
{
"type":"timer",
"period":"1000"
}
]
}
]
}
}
=== Client Configuration (broker section) ===
Put here MQTT client connection setup

This configuration example set NETIO device to connect to broker.hivemq.com with mqtt protocol, no ssl connection with credetials freedom/peace|love|empathy4ALL.

"broker":{
"url":"broker.hivemq.com",
"protocol":"mqtt",
"port":1883,
"ssl":false,
"type":"generic",
"username":"freedom",
"password":"peace|LOVE|empathy4ALL"
},

=== Device Control (subscribe section) ===
Put here array of topics where to subscribe

Device output 1 is controlled with action received by subscription to netio/${DEVICE_NAME}/output/1/action topic with QOS 0

"subscribe":[{
"topic":"netio/${DEVICE_NAME}/output/1/action",
"qos":0,
"target":"OUTPUTS/1/ACTION",
"action":"${payload}"
}
],

=== Output State monitoring (publish section) ===
Put here array of topics where to publish.

Device send every 1000 s message to topic with QOS 0, retain true information with output 1 state

"publish":[{
"topic":"netio/${DEVICE_NAME}/output/1/state",
"qos":0,
"retain":true,
"payload":"${OUTPUTS/1/STATE}",
"events":[
{
"type":"timer",
"period":"1000"
}
]
}
]

= 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 ===
{| class="wikitable"
! style="font-weight:bold; background-color:#9b9b9b;" | Item
! style="font-weight:bold; background-color:#9b9b9b;" | Presence
! style="font-weight:bold; background-color:#9b9b9b;" | Possible Values
! style="font-weight:bold; background-color:#9b9b9b;" | Description
! style="font-weight:bold; background-color:#9b9b9b;" | JSON Config Usage
|-
| style="background-color:#efefef;" | url
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" |
| style="background-color:#efefef;" | MQTT broker URL
| style="background-color:#efefef;" | "url":"broker.hivemq.com"
|-
| style="background-color:#efefef;" | port
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | 1 - 65535
| style="background-color:#efefef;" | MQTT broker port
| style="background-color:#efefef;" | "port":1883
|-
| style="background-color:#efefef;" | protocol
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" |
| style="background-color:#efefef;" | protocol spec - mqtt
| style="background-color:#efefef;" | "protocol": "mqtt"
|-
| style="background-color:#efefef;" | ssl
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | true, false
| style="background-color:#efefef;" | Use SSL crypted communication selector
| style="background-color:#efefef;" | "ssl":false
|-
| style="background-color:#efefef;" | type
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | generic
| style="background-color:#efefef;" | Communication/setup type option
| style="background-color:#efefef;" | "type":"generic"
|-
| style="background-color:#efefef;" | username
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | regexp+len
| style="background-color:#efefef;" | Credentials for MQTT broker. Max. 128 characters (since FW 3.2.4).
| style="background-color:#efefef;" | "username":"freedom"
|-
| style="background-color:#efefef;" | password
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | regexp+len
| style="background-color:#efefef;" | Credentials for MQTT broker. Max. 256 characters (since FW 3.2.4).
| style="background-color:#efefef;" | "password":"peace|LOVE|empathy4ALL"
|-
| style="background-color:#efefef;" | clientid
| style="background-color:#efefef;" | optional
| style="background-color:#efefef;" | regexp+len
| style="background-color:#efefef;" | MQTT clientid. Max. 128 characters (since FW 3.2.4). Variables ${DEVICE_MAC} or ${DEVICE_NAME} can be used
| style="background-color:#efefef;" | "clientid":"myEcoTable01"
|-
| style="background-color:#efefef;" | keepalive
| style="background-color:#efefef;" | optional
| style="background-color:#efefef;" | 1 - 65535
| style="background-color:#efefef;" | MQTT keep alive period in seconds
| style="background-color:#efefef;" | "keepalive":90
|}

Note 1: clientid attribute is mandatory for MQTT(s) communication. When not configured, random ID will be generated.

Note 2: To proper communication with MS Azure - it is necessary to set up IoT Hub to use TLS 1.2

See section "TLS 1.2 enforcement available in select regions" in following guidelines https://docs.microsoft.com/en-us/azure/iot-hub/iot-hub-tls-support

=== Examples ===
==== Standard setup ====

==== Security (SSL / TLS) secured setup ====
You can enable MQTTs by using the encrypted port 8883 + "ssl":true.

==== Variables used setup ====

== 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 ===
{| class="wikitable"
! style="font-weight:bold; background-color:#9b9b9b;" | Item
! style="font-weight:bold; background-color:#9b9b9b;" | Presence
! style="font-weight:bold; background-color:#9b9b9b;" | Possible Values
! style="font-weight:bold; background-color:#9b9b9b;" | Description
! style="font-weight:bold; background-color:#9b9b9b;" | JSON Config Usage
|-
| style="background-color:#efefef;" | topic
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | see table below
| style="background-color:#efefef;" | specification of the topic, which MQTT-flex device listens from broker and act accordingly. Max. 128 characters. The "#" can be used since FW 3.2.4 - see note under this table.
| style="background-color:#efefef;" | "topic":"netio/${DEVICE_NAME}/output/1/action"
|-
| style="background-color:#efefef;" | qos
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | 0, 1 or 2
| style="background-color:#efefef;" | 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}
| style="background-color:#efefef;" | "qos":0
|-
| style="background-color:#efefef;" | target
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" |
| style="background-color:#efefef;" | internal definition of action, which can be performed above the specified output
| style="background-color:#efefef;" | "target":"OUTPUTS/1/ACTION"
|-
| style="background-color:#efefef;" | action
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" |
| style="background-color:#efefef;" | a payload or a value the action attribute needs to have passed to
| style="background-color:#efefef;" | "action":"${payload}"
|-
| style="background-color:#efefef;" | actiondefNot supported yet
| style="background-color:#efefef;" | optional
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
|-
| style="background-color:#efefef;" | jsonNot supported yet
| style="background-color:#efefef;" | optional
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
|}

Note: The "#" wildcard can be used in subscribe topic definition. The multi-level wildcard character MUST be specified either on its own or following a topic level separator. In either case it MUST be the last character specified in the Topic.

For example, if a Device subscribes to “devices/{device_id}/messages/devicebound/#”, it would receive messages published using these topic names:

“devices/{device_id}/messages/devicebound/”

“devices/{device_id}/messages/devicebound/{property_bag}”

This should be usefull for use with MS Azure - IoT hub.

=== MQTT Subscribe as event to trigger action <code>FW 4.0.0+</code> ===

This feature allow to subscribe to specific MQTT topic and pass payload to Rules or MQTT-flex as event.

target: <code>PROTOCOLS/MQTT/EVENT</code>

"subscribe": [
{
"action": "${payload}",
"qos": 0,
"target": "PROTOCOLS/MQTT/EVENT",
"topic": "broker/12345/MQTT_EVENT/"
}
]

=== Examples ===
==== Toggle output with standard payload ====
==== Toggle output with custom payload ====
==== Subscribe to more than one topic ====
==== Trigger Rule and MQTT publish from MQTT subscribe <code>FW 4.0.0+</code> ====
This example show Request response implementation in MQTT and toggle action made by Rules.

When message with payload <code>getValues</code> is published to topic <code>broker/gv90018g/COMMAND</code> MQTT flex will create an event with name <code>PROTOCOLS/MQTT/EVENT</code> (fixed name cannot be changed) and value <code>getValues</code>. On this event will act all events and conditions set in MQTT-flex and Rules which are set to listening to change on <code>PROTOCOLS/MQTT/EVENT</code> and equals to value <code>getValues</code>. See bold marked parameters in example configuration below.

Once the triggered action is done it is needed to reset MQTT channel to <code>OK</code> status becaus event are reacting only to change. If the channel is not reset the next even would not be triggered.

Rules Configuration:
{
"conditions": {
"PROTOCOLS/MQTT/EVENT": "getValues"
},
"actions": {
"OUTPUTS/1/ACTION": 4
}
}

MQTT Configuration:
{
"broker":{
"clientid":"netio${DEVICE_SN}",
"keepalive":30,
"password":"abcdefghijk",
"port":8883,
"protocol":"mqtt",
"ssl":true,
"type":"generic",
"url":"broker.cloud.netio.eu",
"username":"gv90018g"
},
"groupEvents":[
{
"events":[
{
"source":"PROTOCOLS/MQTT/EVENT",
"type":"change",
"value":"getValues"
}
],
"appliedTopics":[
"broker/gv90018g/OUTPUTS/1/STATE",
"broker/gv90018g/COMMAND"
]
}
],
"publish":[
{
"payload":"${OUTPUTS/1/STATE}",
"qos":0,
"retain":true,
"topic":"broker/gv90018g/OUTPUTS/1/STATE"
},
{
"payload":"OK",
"qos":0,
"retain":true,
"topic":"broker/gv90018g/COMMAND"
}
],
"subscribe":[
{
"action":"${payload}",
"qos":0,
"target":"PROTOCOLS/MQTT/EVENT",
"topic":"broker/gv90018g/COMMAND"
}
]
}

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 ===
{| class="wikitable"
! style="font-weight:bold; background-color:#9b9b9b;" | Item
! style="font-weight:bold; background-color:#9b9b9b;" | Presence
! style="font-weight:bold; background-color:#9b9b9b;" | Possible Values
! style="font-weight:bold; background-color:#9b9b9b;" | Description
! style="font-weight:bold; background-color:#9b9b9b;" | JSON Config Usage
|-
| style="background-color:#efefef;" | topic
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | see table below
| style="background-color:#efefef;" | definition of the topic, how it is registered towards MQTT broker. Max. 128 characters.
| style="background-color:#efefef;" | "topic":"netio/${DEVICE_NAME}/output/1/load"
|-
| style="background-color:#efefef;" | qos
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | see table below
| style="background-color:#efefef;" | 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}
| style="background-color:#efefef;" |
|-
| style="background-color:#efefef;" | retain
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | boolean: true or false
| style="background-color:#efefef;" | 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}
| style="background-color:#efefef;" | "retain":true
|-
| style="background-color:#efefef;" | payload
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | see table below
| style="background-color:#efefef;" | definition of the payload, what is send to the MQTT broker.
| style="background-color:#efefef;" | "payload":"${OUTPUTS/1/STATE}"
|-
| style="background-color:#efefef;" | events
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | see table below
| style="background-color:#efefef;" | definition of events used for triggering sending of data via mqtt (change, delta, timer)
| style="background-color:#efefef;" |
|-
| style="background-color:#efefef;" | type
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
|-
| style="background-color:#efefef;" | source
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
|-
| style="background-color:#efefef;" | delta
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
|-
| style="background-color:#efefef;" | period
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
|-
| style="background-color:#efefef;" | payloaddefNot supported yet
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
|}

=== Examples ===
==== Publish energy periodically (event timer) ====
==== Publish current on change (delta) ====
==== Publish output state ====
==== Publish to more than one topic with different events ====

= 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 available only on NETIO PowerDIN 4PZ

=== Examples: ===

adressing controll of output 3
OUTPUTS/3/ACTION
getting voltage on output 1
OUTPUTS/1/VOLTAGE
getting state of input 1
INPUTS/1/STATE

= Group Events<code>FW 4.0.0+</code> =
Group events are smart way how to keep configuration simple. It is not replacement of publish section specification but it is extension to trigger group of different topic publish on the same event.

See the example below.

{
"broker": {
"clientid": "netio${DEVICE_SN}",
"keepalive": 30,
"password": "",
"port": 1883,
"protocol": "mqtt",
"ssl": false,
"type": "generic",
"url": "broker.hivemq.com",
"username": ""
},
"groupEvents": [
{
"events":[
{
"period": 60,
"type": "timer"
}
],
"appliedTopics":[
"devices/${DEVICE_NAME}/output/1/state",
"devices/${DEVICE_NAME}/output/1/state"
]
}
],
"publish": [
{
"events": [
{
"source": "OUTPUT/1/STATE",
"type": "change"
}
],
"payload": "${OUTPUT/1/STATE}",
"qos": 0,
"retain": false,
"topic": "devices/${DEVICE_NAME}/output/1/state"
},{
"events": [
{
"source": "OUTPUT/2/STATE",
"type": "change"
}
],
"payload": "${OUTPUT/2/STATE}",
"qos": 0,
"retain": false,
"topic": "devices/${DEVICE_NAME}/output/2/state"
}
]
}

= 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 ===
==== VOLTAGE ====
Unit: <code>V</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Present RMS voltage on output 1 is ${OUTPUTS/1/VOLTAGE}"</code>

Example 2: <code>"source":"${OUTPUTS/1/VOLTAGE}"</code>

==== CURRENT ====
Unit: <code>mA</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Present RMS current on output 1 is ${OUTPUTS/1/CURRENT}"</code>

Example 2: <code>"source":"${OUTPUTS/1/CURRENT}"</code>

==== POWER_FACTOR ====
Unit: <code>[-]</code>

Type: float (2 decimals)

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"True Power Factor on output 1 is ${OUTPUTS/1/POWER_FACTOR}"</code>

Example 2: <code>"source":"${OUTPUTS/1/POWER_FACTOR}"</code>

==== LOAD ====
Unit: <code>W</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Present load on output 1 is ${OUTPUTS/1/LOAD}W"</code>

Example 2: <code>"payload":"Device's load connected to output 1 is ${OUTPUTS/1/LOAD}W"</code>

Example 3: <code>"source":"${OUTPUTS/1/LOAD}"</code>

==== STATE ====
Type: bool(integer) - <code>0</code> or <code>1</code>

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Present output 1 state is ${OUTPUTS/1/STATE}"</code>

Example 2: <code>"source":"${OUTPUTS/1/STATE}"</code>

==== ACTION ====
Type: integer

Possible actions:
* <code>0</code> - set state OFF
* <code>1</code> - set state ON
* <code>2</code> - short OFF (restart)
* <code>3</code> - short ON
* <code>4</code> - toggle (switch)
* <code>5</code> - no change

Allowed in: <code>"target"</code>

Example: <code>"target":"OUTPUTS/1/ACTION"</code>

==== DELAY [ms] ====
==== NAME ====
==== FREQUENCY ====
Unit: <code>Hz</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example: <code>"payload":"Frequency in power grid is ${OUTPUTS/1/ENERGY}Hz"</code>

==== ENERGY ====
Energy consumed by an device connected to NETIO device output.

Unit: <code>Wh</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Consumed energy on output 1 is ${OUTPUTS/1/ENERGY}Wh"</code>

Example 2: <code>"source":"${OUTPUTS/1/ENERGY}"</code>

==== REVERSE_ENERGY ====
Energy delivered back to grid. For example from solar system connected to NETIO device output.

Unit: <code>Wh</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Delivered energy on output 1 is ${OUTPUTS/1/REVERSE_ENERGY}Wh"</code>

Example 2: <code>"source":"${OUTPUTS/1/REVERSE_ENERGY}"</code>

==== ENERGY_START ====
Date when the counters ENERGY and REVERSE_ENERGY have been resetted by user.

Unit: <code>unix timestamp</code>

Type: integer

Allowed in: <code>"payload"</code>

Example 1: <code>"payload":"Energy measured since ${OUTPUTS/1/ENERGY_START} unix time"</code>

Example 2: <code>"payload":"${OUTPUTS/1/ENERGY_START}"</code> is output payload <code>1567654639</code>

==== ENERGY_START_FMT ====
Date when the counters ENERGY and REVERSE_ENERGY have been resetted by user.

Unit: <code>fmt date format</code>

Type: string

Allowed in: <code>"payload"</code>

Example 1: <code>"payload":"Energy measured since ${OUTPUTS/1/ENERGY_START}"</code>

Example 2: <code>"payload":"${OUTPUTS/1/ENERGY_START_FMT}"</code> is output payload <code>2019-09-05T03:37:19+00:00</code>

==== ENERGY_NR ====
Non-resettable counter of Energy consumed by an device connected to NETIO device output.

Unit: <code>Wh</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Consumed energy on output 1 is ${OUTPUTS/1/ENERGY_NR}Wh"</code>

Example 2: <code>"source":"${OUTPUTS/1/ENERGY_NR}"</code>

==== REVERSE_ENERGY_NR ====
Non-resettable counter of Energy delivered back to grid. For example from solar system connected to NETIO device output.

Unit: <code>Wh</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Delivered energy on output 1 is ${OUTPUTS/1/REVERSE_ENERGY_NR}Wh"</code>

Example 2: <code>"source":"${OUTPUTS/1/REVERSE_ENERGY_NR}"</code>

==== TOTALs - for 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
* OUTPUTS/TOTAL/PHASE
* OUTPUTS/TOTAL/REVERSE_ENERGY
* OUTPUTS/TOTAL/ENERGY_NR
* OUTPUTS/TOTAL/REVERSE_ENERGY_NR
* OUTPUTS/TOTAL/ENERGY_START
* OUTPUTS/TOTAL/ENERGY_START_FMT

==== REST_JSON ====
Allow use of NETIO JSON structure to control outputs.

Type: string / JSON

Allowed in: <code>"target"</code> for Subscribe section

Example: <code>"target": "REST_JSON"</code>

The payload is JSON structure identical to NETIO JSON API M2M Protocol (documentation available at https://www.netio-products.com/files/NETIO-M2M-API-Protocol-JSON.pdf). You can control one or multiple outputs.

Payload example 1 - Toggle output 1: <code>{"Outputs":[{"ID": 1,"Action": 4}]}</code>

Payload example 2 - Turn output 1 OFF and output 3 ON: <code>{"Outputs":[{"ID":1,"Action":0},{"ID":3,"Action":1}]}</code>

=== INPUT variables ===
==== STATE ====
Type: bool(integer) - <code>0</code> or <code>1</code>

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Present input 1 state is ${INPUTS/1/STATE}"</code>

Example 2: <code>"source":"${INPUTS/1/STATE}"</code>

==== S0 ====
S0 Counter value
Unit: <code>-</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Input 1 S0 Counter value is ${INPUTS/1/S0}impulses"</code>

Example 2: <code>"source":"${INPUTS/1/S0}"</code>

== Payload/topic variables ==

=== DEVICE_NAME ===
Can be used in: "payload", "topic"

Example 1: <code>"payload":"${DEVICE_NAME}"</code>

Example 2: <code>"topic":"netio/${DEVICE_NAME}/output/1/action"</code>

=== DEVICE_MAC ===

=== UPTIME Not yet implemented ===

=== PAYLOAD ===
Can be used in: "action"

Example: <code>"action":"${PAYLOAD}"</code>

=== OUTPUT_ID Not yet implemented===

=== WIFI_SIGNALNot yet implemented ===

=== OUTPUTS_STATUS ===
Provide complete outputs status and measurement if supported.

Type: string / JSON

Allowed in: <code>"payload"</code> for Publish section

Example: <code>"payload":"${OUTPUTS_STATUS}"</code>

Payload example: <code>{ "GlobalMeasure":{"Voltage":236,"TotalCurrent":72,"TotalLoad":11,"TotalEnergy":167,"OverallPowerFactor":0.64,"Frequency":50.07,"Phase":-36.86,"EnergyStart":"2020-06-30T17:04:48+01:00"}, "Outputs":[ {"ID":1,"Name":"Power output 1","State":1,"Action":6,"Delay":2020,"Current":72,"PowerFactor":0.64,"Phase":-36.86,"Energy":139,"ReverseEnergy":0,"Load":11}, {"ID":2,"Name":"Power output 2","State":1,"Action":6,"Delay":2020,"Current":0,"PowerFactor":1.00,"Phase":0.00,"Energy":27,"ReverseEnergy":0,"Load":0}, {"ID":3,"Name":"Free Contact 3","State":1,"Action":6,"Delay":2020}, {"ID":4,"Name":"Free Contact 4","State":1,"Action":6,"Delay":2020} ]}</code>

=== INPUTS_STATUS ===
Provide complete inputs status if supported. Since FW 3.0.0

Type: string / JSON

Allowed in: <code>"payload"</code> for Publish section

Example: <code>"payload":"${INPUTS_STATUS}"</code>

Payload example: <code>{ "Inputs":[ {"ID":1,"Name":"Input 1","State":0,"S0Counter":0}, {"ID":2,"Name":"Input 2","State":0,"S0Counter":0} ]}</code>

=== INOUT_STATUS ===
Provide complete inputs and output status and measurement if supported. Since FW 3.0.0

Type: string / JSON

Allowed in: <code>"payload"</code> for Publish section

Example: <code>"payload":"${INOUT_STATUS}"</code>

Payload example: <code>{ "GlobalMeasure":{"Voltage":238,"TotalCurrent":105,"TotalLoad":17,"TotalEnergy":1451,"OverallPowerFactor":0.67,"Frequency":50.03,"Phase":-33.67,"EnergyStart":"2020-06-30T17:04:48+01:00"}, "Outputs":[ {"ID":1,"Name":"Power output 1","State":0,"Action":6,"Delay":5000,"Current":0,"PowerFactor":1.00,"Phase":0.00,"Energy":701,"ReverseEnergy":0,"Load":0}, {"ID":2,"Name":"Power output 2","State":1,"Action":6,"Delay":5000,"Current":105,"PowerFactor":0.65,"Phase":-33.67,"Energy":750,"ReverseEnergy":0,"Load":17}, {"ID":3,"Name":"Free Contact 3","State":1,"Action":6,"Delay":5000}, {"ID":4,"Name":"Free Contact 4","State":0,"Action":6,"Delay":5000} ], "Inputs":[ {"ID":1,"Name":"Input 1","State":0,"S0Counter":0}, {"ID":2,"Name":"Input 2","State":0,"S0Counter":0} ]}</code>

= Extended MQTT flex JSON config examples =

== Default NETIO MQTT-flex configuration ==
This example demonstrates setup for connection to public <code>broker.hivemq.com</code>, measurement reporting and output control.

The device cabe be controlled via <code>netio/${DEVICE_NAME}/output/1/action topic</code> by sending standard NETIO action values:
* 0 - OFF
* 1 - ON
* 2 - SHORT OFF
* 3 - SHORT ON
* 4 - TOGGLE
* 5 - NO ACTION.

The device report measurements:

* Output state - every 15 minutes or by change
* Voltage [V]- every 5 minutes or by change of 1 V
* Current [mA]- every 5 minutes or by change of 50 mA
* Load(Power) [W]- every 5 minutes or by change of 10 W
* Energy(Consumption) [Wh]- every 15 minutes or by change of 1Wh
* True Power Factor (TPF) [-]- every 5 minutes or by change of 0.02
* Frequency [Hz]- every 1 hour or by change of 0.1 Hz

For register all values, you can use wildcard <code>netio/${DEVICE_NAME}/output/1/#</code>

{
"config":{
"broker":{
"url":"broker.hivemq.com",
"protocol":"mqtt",
"port":1883,
"ssl":false,
"type":"generic",
"username":"",
"password":"",
"clientid":"moje${DEVICE_NAME}${DEVICE_MAC}",
"keepalive":30
},
"subscribe":[
{
"topic":"netio/${DEVICE_NAME}/output/1/action",
"qos":0,
"target":"OUTPUTS/1/ACTION",
"action":"${payload}"
},
{
"topic":"netio/${DEVICE_NAME}/output/1/switch",
"qos":0,
"target":"OUTPUTS/1/ACTION",
"action":4
}
],
"publish":[
{
"topic":"netio/${DEVICE_MAC}/output/1/state",
"qos":0,
"retain":true,
"payload":"${OUTPUTS/1/STATE}",
"events":[
{
"type":"change",
"source":"OUTPUTS/1/STATE"
},
{
"type":"timer",
"period":900
}
]
},
{
"topic":"netio/${DEVICE_NAME}/output/1/voltage",
"qos":0,
"retain":false,
"payload":"${OUTPUTS/1/VOLTAGE}",
"events":[
{
"type":"timer",
"period":300
},
{
"type":"delta",
"source":"OUTPUTS/1/VOLTAGE",
"delta":1
}
]
},
{
"topic":"netio/${DEVICE_NAME}/output/1/current",
"qos":0,
"retain":false,
"payload":"${OUTPUTS/1/CURRENT}",
"events":[
{
"type":"timer",
"period":300
},
{
"type":"delta",
"source":"OUTPUTS/1/CURRENT",
"delta":50
}
]
},
{
"topic":"netio/${DEVICE_NAME}/output/1/load",
"qos":0,
"retain":false,
"payload":"${OUTPUTS/1/LOAD}",
"events":[
{
"type":"timer",
"period":300
},
{
"type":"delta",
"source":"OUTPUTS/1/LOAD",
"delta":10
}
]
},
{
"topic":"netio/${DEVICE_NAME}/output/1/energy",
"qos":0,
"retain":false,
"payload":"${OUTPUTS/1/ENERGY}",
"events":[
{
"type":"timer",
"period":900
},
{
"type":"delta",
"source":"OUTPUTS/1/ENERGY",
"delta":1
}
]
},
{
"topic":"netio/${DEVICE_NAME}/output/1/tpf",
"qos":0,
"retain":false,
"payload":"${OUTPUTS/1/POWER_FACTOR}",
"events":[
{
"type":"timer",
"period":900
},
{
"type":"delta",
"source":"OUTPUTS/1/POWER_FACTOR",
"delta":0.02
}
]
},
{
"topic":"netio/${DEVICE_NAME}/output/1/frequency",
"qos":0,
"retain":false,
"payload":"${OUTPUTS/1/FREQUENCY}",
"events":[
{
"type":"timer",
"period":3600
},
{
"type":"delta",
"source":"OUTPUTS/1/FREQUENCY",
"delta":0.1
}
]
}
]
}
}

MQTT-flex

2023-06-06T14:20:20Z

Bbakala: /* Group EventsFW 4.0.0+ */

The MQTT-flex version of the MQTT protocol can be configured in detail thanks to the “flex” extension.

https://www.netio-products.com/en/glossary/mqtt-flex

Why MQTT-flex 
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 [https://en.wikipedia.org/wiki/MQTT 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 [https://en.wikipedia.org/wiki/JSON 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 101x 
* PowerCable REST 101x 
* PowerPDU 4PS 
* PowerPDU 4KS 
* PowerPDU 8QS 
* PowerDIN 4PZ 
* PowerBOX 3Px 
* PowerBOX 4Kx 

FW version: 
>2.2.1

===Not supported NETIO devices:===
* PowerPDU 4C 
* NETIO 4 
* NETIO 4All 

= Simple MQTT-flex configuration + explanation =

''We strongly recommend to create and test MQTT-flex configuration on "local" device what can be easily restarted. The validation of config before saving is not 100% and for example some specific typos can cause a freeze of a device - the solution is to restart a device (unplug/plug input power cable). If the configuration is saved and device is working then there are no known failure case so it is safe to use this configuration on the "remote" devices.''

{
"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":false,
"payload":"${OUTPUTS/1/STATE}",
"events":[
{
"type":"timer",
"period":"1000"
}
]
}
]
}
}
=== Client Configuration (broker section) ===
Put here MQTT client connection setup

This configuration example set NETIO device to connect to broker.hivemq.com with mqtt protocol, no ssl connection with credetials freedom/peace|love|empathy4ALL.

"broker":{
"url":"broker.hivemq.com",
"protocol":"mqtt",
"port":1883,
"ssl":false,
"type":"generic",
"username":"freedom",
"password":"peace|LOVE|empathy4ALL"
},

=== Device Control (subscribe section) ===
Put here array of topics where to subscribe

Device output 1 is controlled with action received by subscription to netio/${DEVICE_NAME}/output/1/action topic with QOS 0

"subscribe":[{
"topic":"netio/${DEVICE_NAME}/output/1/action",
"qos":0,
"target":"OUTPUTS/1/ACTION",
"action":"${payload}"
}
],

=== Output State monitoring (publish section) ===
Put here array of topics where to publish.

Device send every 1000 s message to topic with QOS 0, retain true information with output 1 state

"publish":[{
"topic":"netio/${DEVICE_NAME}/output/1/state",
"qos":0,
"retain":true,
"payload":"${OUTPUTS/1/STATE}",
"events":[
{
"type":"timer",
"period":"1000"
}
]
}
]

= 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 ===
{| class="wikitable"
! style="font-weight:bold; background-color:#9b9b9b;" | Item
! style="font-weight:bold; background-color:#9b9b9b;" | Presence
! style="font-weight:bold; background-color:#9b9b9b;" | Possible Values
! style="font-weight:bold; background-color:#9b9b9b;" | Description
! style="font-weight:bold; background-color:#9b9b9b;" | JSON Config Usage
|-
| style="background-color:#efefef;" | url
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" |
| style="background-color:#efefef;" | MQTT broker URL
| style="background-color:#efefef;" | "url":"broker.hivemq.com"
|-
| style="background-color:#efefef;" | port
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | 1 - 65535
| style="background-color:#efefef;" | MQTT broker port
| style="background-color:#efefef;" | "port":1883
|-
| style="background-color:#efefef;" | protocol
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" |
| style="background-color:#efefef;" | protocol spec - mqtt
| style="background-color:#efefef;" | "protocol": "mqtt"
|-
| style="background-color:#efefef;" | ssl
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | true, false
| style="background-color:#efefef;" | Use SSL crypted communication selector
| style="background-color:#efefef;" | "ssl":false
|-
| style="background-color:#efefef;" | type
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | generic
| style="background-color:#efefef;" | Communication/setup type option
| style="background-color:#efefef;" | "type":"generic"
|-
| style="background-color:#efefef;" | username
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | regexp+len
| style="background-color:#efefef;" | Credentials for MQTT broker. Max. 128 characters (since FW 3.2.4).
| style="background-color:#efefef;" | "username":"freedom"
|-
| style="background-color:#efefef;" | password
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | regexp+len
| style="background-color:#efefef;" | Credentials for MQTT broker. Max. 256 characters (since FW 3.2.4).
| style="background-color:#efefef;" | "password":"peace|LOVE|empathy4ALL"
|-
| style="background-color:#efefef;" | clientid
| style="background-color:#efefef;" | optional
| style="background-color:#efefef;" | regexp+len
| style="background-color:#efefef;" | MQTT clientid. Max. 128 characters (since FW 3.2.4). Variables ${DEVICE_MAC} or ${DEVICE_NAME} can be used
| style="background-color:#efefef;" | "clientid":"myEcoTable01"
|-
| style="background-color:#efefef;" | keepalive
| style="background-color:#efefef;" | optional
| style="background-color:#efefef;" | 1 - 65535
| style="background-color:#efefef;" | MQTT keep alive period in seconds
| style="background-color:#efefef;" | "keepalive":90
|}

Note 1: clientid attribute is mandatory for MQTT(s) communication. When not configured, random ID will be generated.

Note 2: To proper communication with MS Azure - it is necessary to set up IoT Hub to use TLS 1.2

See section "TLS 1.2 enforcement available in select regions" in following guidelines https://docs.microsoft.com/en-us/azure/iot-hub/iot-hub-tls-support

=== Examples ===
==== Standard setup ====

==== Security (SSL / TLS) secured setup ====
You can enable MQTTs by using the encrypted port 8883 + "ssl":true.

==== Variables used setup ====

== 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 ===
{| class="wikitable"
! style="font-weight:bold; background-color:#9b9b9b;" | Item
! style="font-weight:bold; background-color:#9b9b9b;" | Presence
! style="font-weight:bold; background-color:#9b9b9b;" | Possible Values
! style="font-weight:bold; background-color:#9b9b9b;" | Description
! style="font-weight:bold; background-color:#9b9b9b;" | JSON Config Usage
|-
| style="background-color:#efefef;" | topic
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | see table below
| style="background-color:#efefef;" | specification of the topic, which MQTT-flex device listens from broker and act accordingly. Max. 128 characters. The "#" can be used since FW 3.2.4 - see note under this table.
| style="background-color:#efefef;" | "topic":"netio/${DEVICE_NAME}/output/1/action"
|-
| style="background-color:#efefef;" | qos
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | 0, 1 or 2
| style="background-color:#efefef;" | 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}
| style="background-color:#efefef;" | "qos":0
|-
| style="background-color:#efefef;" | target
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" |
| style="background-color:#efefef;" | internal definition of action, which can be performed above the specified output
| style="background-color:#efefef;" | "target":"OUTPUTS/1/ACTION"
|-
| style="background-color:#efefef;" | action
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" |
| style="background-color:#efefef;" | a payload or a value the action attribute needs to have passed to
| style="background-color:#efefef;" | "action":"${payload}"
|-
| style="background-color:#efefef;" | actiondefNot supported yet
| style="background-color:#efefef;" | optional
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
|-
| style="background-color:#efefef;" | jsonNot supported yet
| style="background-color:#efefef;" | optional
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
|}

Note: The "#" wildcard can be used in subscribe topic definition. The multi-level wildcard character MUST be specified either on its own or following a topic level separator. In either case it MUST be the last character specified in the Topic.

For example, if a Device subscribes to “devices/{device_id}/messages/devicebound/#”, it would receive messages published using these topic names:

“devices/{device_id}/messages/devicebound/”

“devices/{device_id}/messages/devicebound/{property_bag}”

This should be usefull for use with MS Azure - IoT hub.

=== MQTT Subscribe as event to trigger action <code>FW 4.0.0+</code> ===

This feature allow to subscribe to specific MQTT topic and pass payload to Rules or MQTT-flex as event.

target: <code>PROTOCOLS/MQTT/EVENT</code>

"subscribe": [
{
"action": "${payload}",
"qos": 0,
"target": "PROTOCOLS/MQTT/EVENT",
"topic": "broker/12345/MQTT_EVENT/"
}
]

=== Examples ===
==== Toggle output with standard payload ====
==== Toggle output with custom payload ====
==== Subscribe to more than one topic ====
==== Trigger Rule and MQTT publish from MQTT subscribe <code>FW 4.0.0+</code> ====
This example show Request response implementation in MQTT and toggle action made by Rules.

When message with payload <code>getValues</code> is published to topic <code>broker/gv90018g/COMMAND</code> MQTT flex will create an event with name <code>PROTOCOLS/MQTT/EVENT</code> (fixed name cannot be changed) and value <code>getValues</code>. On this event will act all events and conditions set in MQTT-flex and Rules which are set to listening to change on <code>PROTOCOLS/MQTT/EVENT</code> and equals to value <code>getValues</code>. See bold marked parameters in example configuration below.

Once the triggered action is done it is needed to reset MQTT channel to <code>OK</code> status becaus event are reacting only to change. If the channel is not reset the next even would not be triggered.

Rules Configuration:
{
"conditions": {
"PROTOCOLS/MQTT/EVENT": "getValues"
},
"actions": {
"OUTPUTS/1/ACTION": 4
}
}

MQTT Configuration:
{
"broker":{
"clientid":"netio${DEVICE_SN}",
"keepalive":30,
"password":"abcdefghijk",
"port":8883,
"protocol":"mqtt",
"ssl":true,
"type":"generic",
"url":"broker.cloud.netio.eu",
"username":"gv90018g"
},
"groupEvents":[
{
"events":[
{
"source":"PROTOCOLS/MQTT/EVENT",
"type":"change",
"value":"getValues"
}
],
"appliedTopics":[
"broker/gv90018g/OUTPUTS/1/STATE",
"broker/gv90018g/COMMAND"
]
}
],
"publish":[
{
"payload":"${OUTPUTS/1/STATE}",
"qos":0,
"retain":true,
"topic":"broker/gv90018g/OUTPUTS/1/STATE"
},
{
"payload":"OK",
"qos":0,
"retain":true,
"topic":"broker/gv90018g/COMMAND"
}
],
"subscribe":[
{
"action":"${payload}",
"qos":0,
"target":"PROTOCOLS/MQTT/EVENT",
"topic":"broker/gv90018g/COMMAND"
}
]
}

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 ===
{| class="wikitable"
! style="font-weight:bold; background-color:#9b9b9b;" | Item
! style="font-weight:bold; background-color:#9b9b9b;" | Presence
! style="font-weight:bold; background-color:#9b9b9b;" | Possible Values
! style="font-weight:bold; background-color:#9b9b9b;" | Description
! style="font-weight:bold; background-color:#9b9b9b;" | JSON Config Usage
|-
| style="background-color:#efefef;" | topic
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | see table below
| style="background-color:#efefef;" | definition of the topic, how it is registered towards MQTT broker. Max. 128 characters.
| style="background-color:#efefef;" | "topic":"netio/${DEVICE_NAME}/output/1/load"
|-
| style="background-color:#efefef;" | qos
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | see table below
| style="background-color:#efefef;" | 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}
| style="background-color:#efefef;" |
|-
| style="background-color:#efefef;" | retain
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | boolean: true or false
| style="background-color:#efefef;" | 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}
| style="background-color:#efefef;" | "retain":true
|-
| style="background-color:#efefef;" | payload
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | see table below
| style="background-color:#efefef;" | definition of the payload, what is send to the MQTT broker.
| style="background-color:#efefef;" | "payload":"${OUTPUTS/1/STATE}"
|-
| style="background-color:#efefef;" | events
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | see table below
| style="background-color:#efefef;" | definition of events used for triggering sending of data via mqtt (change, delta, timer)
| style="background-color:#efefef;" |
|-
| style="background-color:#efefef;" | type
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
|-
| style="background-color:#efefef;" | source
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
|-
| style="background-color:#efefef;" | delta
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
|-
| style="background-color:#efefef;" | period
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
|-
| style="background-color:#efefef;" | payloaddefNot supported yet
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
|}

=== Examples ===
==== Publish energy periodically (event timer) ====
==== Publish current on change (delta) ====
==== Publish output state ====
==== Publish to more than one topic with different events ====

= 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 available only on NETIO PowerDIN 4PZ

=== Examples: ===

adressing controll of output 3
OUTPUTS/3/ACTION
getting voltage on output 1
OUTPUTS/1/VOLTAGE
getting state of input 1
INPUTS/1/STATE

= Group Events<code>FW 4.0.0+</code> =
Group events are smart way how to keep configuration simple. It is not replacement of publish section specification but it is extension to trigger group of different topic publish on the same event.

See the example below.

{
"broker": {
"clientid": "netio${DEVICE_SN}",
"keepalive": 30,
"password": "",
"port": 1883,
"protocol": "mqtt",
"ssl": false,
"type": "generic",
"url": "broker.hivemq.com",
"username": ""
},
"groupEvents": [
{
"events":[
{
"period": 60,
"type": "timer"
}
],
"appliedTopics":[
"devices/${DEVICE_NAME}/output/1/state",
"devices/${DEVICE_NAME}/output/1/state"
]
}
],
"publish": [
{
"events": [
{
"source": "OUTPUT/1/STATE",
"type": "change"
}
],
"payload": "${OUTPUT/1/STATE}",
"qos": 0,
"retain": false,
"topic": "devices/${DEVICE_NAME}/output/1/state"
},{
"events": [
{
"source": "OUTPUT/2/STATE",
"type": "change"
}
],
"payload": "${OUTPUT/2/STATE}",
"qos": 0,
"retain": false,
"topic": "devices/${DEVICE_NAME}/output/2/state"
},
]
}

= 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 ===
==== VOLTAGE ====
Unit: <code>V</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Present RMS voltage on output 1 is ${OUTPUTS/1/VOLTAGE}"</code>

Example 2: <code>"source":"${OUTPUTS/1/VOLTAGE}"</code>

==== CURRENT ====
Unit: <code>mA</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Present RMS current on output 1 is ${OUTPUTS/1/CURRENT}"</code>

Example 2: <code>"source":"${OUTPUTS/1/CURRENT}"</code>

==== POWER_FACTOR ====
Unit: <code>[-]</code>

Type: float (2 decimals)

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"True Power Factor on output 1 is ${OUTPUTS/1/POWER_FACTOR}"</code>

Example 2: <code>"source":"${OUTPUTS/1/POWER_FACTOR}"</code>

==== LOAD ====
Unit: <code>W</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Present load on output 1 is ${OUTPUTS/1/LOAD}W"</code>

Example 2: <code>"payload":"Device's load connected to output 1 is ${OUTPUTS/1/LOAD}W"</code>

Example 3: <code>"source":"${OUTPUTS/1/LOAD}"</code>

==== STATE ====
Type: bool(integer) - <code>0</code> or <code>1</code>

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Present output 1 state is ${OUTPUTS/1/STATE}"</code>

Example 2: <code>"source":"${OUTPUTS/1/STATE}"</code>

==== ACTION ====
Type: integer

Possible actions:
* <code>0</code> - set state OFF
* <code>1</code> - set state ON
* <code>2</code> - short OFF (restart)
* <code>3</code> - short ON
* <code>4</code> - toggle (switch)
* <code>5</code> - no change

Allowed in: <code>"target"</code>

Example: <code>"target":"OUTPUTS/1/ACTION"</code>

==== DELAY [ms] ====
==== NAME ====
==== FREQUENCY ====
Unit: <code>Hz</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example: <code>"payload":"Frequency in power grid is ${OUTPUTS/1/ENERGY}Hz"</code>

==== ENERGY ====
Energy consumed by an device connected to NETIO device output.

Unit: <code>Wh</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Consumed energy on output 1 is ${OUTPUTS/1/ENERGY}Wh"</code>

Example 2: <code>"source":"${OUTPUTS/1/ENERGY}"</code>

==== REVERSE_ENERGY ====
Energy delivered back to grid. For example from solar system connected to NETIO device output.

Unit: <code>Wh</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Delivered energy on output 1 is ${OUTPUTS/1/REVERSE_ENERGY}Wh"</code>

Example 2: <code>"source":"${OUTPUTS/1/REVERSE_ENERGY}"</code>

==== ENERGY_START ====
Date when the counters ENERGY and REVERSE_ENERGY have been resetted by user.

Unit: <code>unix timestamp</code>

Type: integer

Allowed in: <code>"payload"</code>

Example 1: <code>"payload":"Energy measured since ${OUTPUTS/1/ENERGY_START} unix time"</code>

Example 2: <code>"payload":"${OUTPUTS/1/ENERGY_START}"</code> is output payload <code>1567654639</code>

==== ENERGY_START_FMT ====
Date when the counters ENERGY and REVERSE_ENERGY have been resetted by user.

Unit: <code>fmt date format</code>

Type: string

Allowed in: <code>"payload"</code>

Example 1: <code>"payload":"Energy measured since ${OUTPUTS/1/ENERGY_START}"</code>

Example 2: <code>"payload":"${OUTPUTS/1/ENERGY_START_FMT}"</code> is output payload <code>2019-09-05T03:37:19+00:00</code>

==== ENERGY_NR ====
Non-resettable counter of Energy consumed by an device connected to NETIO device output.

Unit: <code>Wh</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Consumed energy on output 1 is ${OUTPUTS/1/ENERGY_NR}Wh"</code>

Example 2: <code>"source":"${OUTPUTS/1/ENERGY_NR}"</code>

==== REVERSE_ENERGY_NR ====
Non-resettable counter of Energy delivered back to grid. For example from solar system connected to NETIO device output.

Unit: <code>Wh</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Delivered energy on output 1 is ${OUTPUTS/1/REVERSE_ENERGY_NR}Wh"</code>

Example 2: <code>"source":"${OUTPUTS/1/REVERSE_ENERGY_NR}"</code>

==== TOTALs - for 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
* OUTPUTS/TOTAL/PHASE
* OUTPUTS/TOTAL/REVERSE_ENERGY
* OUTPUTS/TOTAL/ENERGY_NR
* OUTPUTS/TOTAL/REVERSE_ENERGY_NR
* OUTPUTS/TOTAL/ENERGY_START
* OUTPUTS/TOTAL/ENERGY_START_FMT

==== REST_JSON ====
Allow use of NETIO JSON structure to control outputs.

Type: string / JSON

Allowed in: <code>"target"</code> for Subscribe section

Example: <code>"target": "REST_JSON"</code>

The payload is JSON structure identical to NETIO JSON API M2M Protocol (documentation available at https://www.netio-products.com/files/NETIO-M2M-API-Protocol-JSON.pdf). You can control one or multiple outputs.

Payload example 1 - Toggle output 1: <code>{"Outputs":[{"ID": 1,"Action": 4}]}</code>

Payload example 2 - Turn output 1 OFF and output 3 ON: <code>{"Outputs":[{"ID":1,"Action":0},{"ID":3,"Action":1}]}</code>

=== INPUT variables ===
==== STATE ====
Type: bool(integer) - <code>0</code> or <code>1</code>

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Present input 1 state is ${INPUTS/1/STATE}"</code>

Example 2: <code>"source":"${INPUTS/1/STATE}"</code>

==== S0 ====
S0 Counter value
Unit: <code>-</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Input 1 S0 Counter value is ${INPUTS/1/S0}impulses"</code>

Example 2: <code>"source":"${INPUTS/1/S0}"</code>

== Payload/topic variables ==

=== DEVICE_NAME ===
Can be used in: "payload", "topic"

Example 1: <code>"payload":"${DEVICE_NAME}"</code>

Example 2: <code>"topic":"netio/${DEVICE_NAME}/output/1/action"</code>

=== DEVICE_MAC ===

=== UPTIME Not yet implemented ===

=== PAYLOAD ===
Can be used in: "action"

Example: <code>"action":"${PAYLOAD}"</code>

=== OUTPUT_ID Not yet implemented===

=== WIFI_SIGNALNot yet implemented ===

=== OUTPUTS_STATUS ===
Provide complete outputs status and measurement if supported.

Type: string / JSON

Allowed in: <code>"payload"</code> for Publish section

Example: <code>"payload":"${OUTPUTS_STATUS}"</code>

Payload example: <code>{ "GlobalMeasure":{"Voltage":236,"TotalCurrent":72,"TotalLoad":11,"TotalEnergy":167,"OverallPowerFactor":0.64,"Frequency":50.07,"Phase":-36.86,"EnergyStart":"2020-06-30T17:04:48+01:00"}, "Outputs":[ {"ID":1,"Name":"Power output 1","State":1,"Action":6,"Delay":2020,"Current":72,"PowerFactor":0.64,"Phase":-36.86,"Energy":139,"ReverseEnergy":0,"Load":11}, {"ID":2,"Name":"Power output 2","State":1,"Action":6,"Delay":2020,"Current":0,"PowerFactor":1.00,"Phase":0.00,"Energy":27,"ReverseEnergy":0,"Load":0}, {"ID":3,"Name":"Free Contact 3","State":1,"Action":6,"Delay":2020}, {"ID":4,"Name":"Free Contact 4","State":1,"Action":6,"Delay":2020} ]}</code>

=== INPUTS_STATUS ===
Provide complete inputs status if supported. Since FW 3.0.0

Type: string / JSON

Allowed in: <code>"payload"</code> for Publish section

Example: <code>"payload":"${INPUTS_STATUS}"</code>

Payload example: <code>{ "Inputs":[ {"ID":1,"Name":"Input 1","State":0,"S0Counter":0}, {"ID":2,"Name":"Input 2","State":0,"S0Counter":0} ]}</code>

=== INOUT_STATUS ===
Provide complete inputs and output status and measurement if supported. Since FW 3.0.0

Type: string / JSON

Allowed in: <code>"payload"</code> for Publish section

Example: <code>"payload":"${INOUT_STATUS}"</code>

Payload example: <code>{ "GlobalMeasure":{"Voltage":238,"TotalCurrent":105,"TotalLoad":17,"TotalEnergy":1451,"OverallPowerFactor":0.67,"Frequency":50.03,"Phase":-33.67,"EnergyStart":"2020-06-30T17:04:48+01:00"}, "Outputs":[ {"ID":1,"Name":"Power output 1","State":0,"Action":6,"Delay":5000,"Current":0,"PowerFactor":1.00,"Phase":0.00,"Energy":701,"ReverseEnergy":0,"Load":0}, {"ID":2,"Name":"Power output 2","State":1,"Action":6,"Delay":5000,"Current":105,"PowerFactor":0.65,"Phase":-33.67,"Energy":750,"ReverseEnergy":0,"Load":17}, {"ID":3,"Name":"Free Contact 3","State":1,"Action":6,"Delay":5000}, {"ID":4,"Name":"Free Contact 4","State":0,"Action":6,"Delay":5000} ], "Inputs":[ {"ID":1,"Name":"Input 1","State":0,"S0Counter":0}, {"ID":2,"Name":"Input 2","State":0,"S0Counter":0} ]}</code>

= Extended MQTT flex JSON config examples =

== Default NETIO MQTT-flex configuration ==
This example demonstrates setup for connection to public <code>broker.hivemq.com</code>, measurement reporting and output control.

The device cabe be controlled via <code>netio/${DEVICE_NAME}/output/1/action topic</code> by sending standard NETIO action values:
* 0 - OFF
* 1 - ON
* 2 - SHORT OFF
* 3 - SHORT ON
* 4 - TOGGLE
* 5 - NO ACTION.

The device report measurements:

* Output state - every 15 minutes or by change
* Voltage [V]- every 5 minutes or by change of 1 V
* Current [mA]- every 5 minutes or by change of 50 mA
* Load(Power) [W]- every 5 minutes or by change of 10 W
* Energy(Consumption) [Wh]- every 15 minutes or by change of 1Wh
* True Power Factor (TPF) [-]- every 5 minutes or by change of 0.02
* Frequency [Hz]- every 1 hour or by change of 0.1 Hz

For register all values, you can use wildcard <code>netio/${DEVICE_NAME}/output/1/#</code>

{
"config":{
"broker":{
"url":"broker.hivemq.com",
"protocol":"mqtt",
"port":1883,
"ssl":false,
"type":"generic",
"username":"",
"password":"",
"clientid":"moje${DEVICE_NAME}${DEVICE_MAC}",
"keepalive":30
},
"subscribe":[
{
"topic":"netio/${DEVICE_NAME}/output/1/action",
"qos":0,
"target":"OUTPUTS/1/ACTION",
"action":"${payload}"
},
{
"topic":"netio/${DEVICE_NAME}/output/1/switch",
"qos":0,
"target":"OUTPUTS/1/ACTION",
"action":4
}
],
"publish":[
{
"topic":"netio/${DEVICE_MAC}/output/1/state",
"qos":0,
"retain":true,
"payload":"${OUTPUTS/1/STATE}",
"events":[
{
"type":"change",
"source":"OUTPUTS/1/STATE"
},
{
"type":"timer",
"period":900
}
]
},
{
"topic":"netio/${DEVICE_NAME}/output/1/voltage",
"qos":0,
"retain":false,
"payload":"${OUTPUTS/1/VOLTAGE}",
"events":[
{
"type":"timer",
"period":300
},
{
"type":"delta",
"source":"OUTPUTS/1/VOLTAGE",
"delta":1
}
]
},
{
"topic":"netio/${DEVICE_NAME}/output/1/current",
"qos":0,
"retain":false,
"payload":"${OUTPUTS/1/CURRENT}",
"events":[
{
"type":"timer",
"period":300
},
{
"type":"delta",
"source":"OUTPUTS/1/CURRENT",
"delta":50
}
]
},
{
"topic":"netio/${DEVICE_NAME}/output/1/load",
"qos":0,
"retain":false,
"payload":"${OUTPUTS/1/LOAD}",
"events":[
{
"type":"timer",
"period":300
},
{
"type":"delta",
"source":"OUTPUTS/1/LOAD",
"delta":10
}
]
},
{
"topic":"netio/${DEVICE_NAME}/output/1/energy",
"qos":0,
"retain":false,
"payload":"${OUTPUTS/1/ENERGY}",
"events":[
{
"type":"timer",
"period":900
},
{
"type":"delta",
"source":"OUTPUTS/1/ENERGY",
"delta":1
}
]
},
{
"topic":"netio/${DEVICE_NAME}/output/1/tpf",
"qos":0,
"retain":false,
"payload":"${OUTPUTS/1/POWER_FACTOR}",
"events":[
{
"type":"timer",
"period":900
},
{
"type":"delta",
"source":"OUTPUTS/1/POWER_FACTOR",
"delta":0.02
}
]
},
{
"topic":"netio/${DEVICE_NAME}/output/1/frequency",
"qos":0,
"retain":false,
"payload":"${OUTPUTS/1/FREQUENCY}",
"events":[
{
"type":"timer",
"period":3600
},
{
"type":"delta",
"source":"OUTPUTS/1/FREQUENCY",
"delta":0.1
}
]
}
]
}
}

MQTT-flex

2023-06-06T14:18:50Z

Bbakala: /* Group EventsFW 4.0.0+ */

The MQTT-flex version of the MQTT protocol can be configured in detail thanks to the “flex” extension.

https://www.netio-products.com/en/glossary/mqtt-flex

Why MQTT-flex 
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 [https://en.wikipedia.org/wiki/MQTT 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 [https://en.wikipedia.org/wiki/JSON 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 101x 
* PowerCable REST 101x 
* PowerPDU 4PS 
* PowerPDU 4KS 
* PowerPDU 8QS 
* PowerDIN 4PZ 
* PowerBOX 3Px 
* PowerBOX 4Kx 

FW version: 
>2.2.1

===Not supported NETIO devices:===
* PowerPDU 4C 
* NETIO 4 
* NETIO 4All 

= Simple MQTT-flex configuration + explanation =

''We strongly recommend to create and test MQTT-flex configuration on "local" device what can be easily restarted. The validation of config before saving is not 100% and for example some specific typos can cause a freeze of a device - the solution is to restart a device (unplug/plug input power cable). If the configuration is saved and device is working then there are no known failure case so it is safe to use this configuration on the "remote" devices.''

{
"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":false,
"payload":"${OUTPUTS/1/STATE}",
"events":[
{
"type":"timer",
"period":"1000"
}
]
}
]
}
}
=== Client Configuration (broker section) ===
Put here MQTT client connection setup

This configuration example set NETIO device to connect to broker.hivemq.com with mqtt protocol, no ssl connection with credetials freedom/peace|love|empathy4ALL.

"broker":{
"url":"broker.hivemq.com",
"protocol":"mqtt",
"port":1883,
"ssl":false,
"type":"generic",
"username":"freedom",
"password":"peace|LOVE|empathy4ALL"
},

=== Device Control (subscribe section) ===
Put here array of topics where to subscribe

Device output 1 is controlled with action received by subscription to netio/${DEVICE_NAME}/output/1/action topic with QOS 0

"subscribe":[{
"topic":"netio/${DEVICE_NAME}/output/1/action",
"qos":0,
"target":"OUTPUTS/1/ACTION",
"action":"${payload}"
}
],

=== Output State monitoring (publish section) ===
Put here array of topics where to publish.

Device send every 1000 s message to topic with QOS 0, retain true information with output 1 state

"publish":[{
"topic":"netio/${DEVICE_NAME}/output/1/state",
"qos":0,
"retain":true,
"payload":"${OUTPUTS/1/STATE}",
"events":[
{
"type":"timer",
"period":"1000"
}
]
}
]

= 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 ===
{| class="wikitable"
! style="font-weight:bold; background-color:#9b9b9b;" | Item
! style="font-weight:bold; background-color:#9b9b9b;" | Presence
! style="font-weight:bold; background-color:#9b9b9b;" | Possible Values
! style="font-weight:bold; background-color:#9b9b9b;" | Description
! style="font-weight:bold; background-color:#9b9b9b;" | JSON Config Usage
|-
| style="background-color:#efefef;" | url
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" |
| style="background-color:#efefef;" | MQTT broker URL
| style="background-color:#efefef;" | "url":"broker.hivemq.com"
|-
| style="background-color:#efefef;" | port
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | 1 - 65535
| style="background-color:#efefef;" | MQTT broker port
| style="background-color:#efefef;" | "port":1883
|-
| style="background-color:#efefef;" | protocol
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" |
| style="background-color:#efefef;" | protocol spec - mqtt
| style="background-color:#efefef;" | "protocol": "mqtt"
|-
| style="background-color:#efefef;" | ssl
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | true, false
| style="background-color:#efefef;" | Use SSL crypted communication selector
| style="background-color:#efefef;" | "ssl":false
|-
| style="background-color:#efefef;" | type
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | generic
| style="background-color:#efefef;" | Communication/setup type option
| style="background-color:#efefef;" | "type":"generic"
|-
| style="background-color:#efefef;" | username
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | regexp+len
| style="background-color:#efefef;" | Credentials for MQTT broker. Max. 128 characters (since FW 3.2.4).
| style="background-color:#efefef;" | "username":"freedom"
|-
| style="background-color:#efefef;" | password
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | regexp+len
| style="background-color:#efefef;" | Credentials for MQTT broker. Max. 256 characters (since FW 3.2.4).
| style="background-color:#efefef;" | "password":"peace|LOVE|empathy4ALL"
|-
| style="background-color:#efefef;" | clientid
| style="background-color:#efefef;" | optional
| style="background-color:#efefef;" | regexp+len
| style="background-color:#efefef;" | MQTT clientid. Max. 128 characters (since FW 3.2.4). Variables ${DEVICE_MAC} or ${DEVICE_NAME} can be used
| style="background-color:#efefef;" | "clientid":"myEcoTable01"
|-
| style="background-color:#efefef;" | keepalive
| style="background-color:#efefef;" | optional
| style="background-color:#efefef;" | 1 - 65535
| style="background-color:#efefef;" | MQTT keep alive period in seconds
| style="background-color:#efefef;" | "keepalive":90
|}

Note 1: clientid attribute is mandatory for MQTT(s) communication. When not configured, random ID will be generated.

Note 2: To proper communication with MS Azure - it is necessary to set up IoT Hub to use TLS 1.2

See section "TLS 1.2 enforcement available in select regions" in following guidelines https://docs.microsoft.com/en-us/azure/iot-hub/iot-hub-tls-support

=== Examples ===
==== Standard setup ====

==== Security (SSL / TLS) secured setup ====
You can enable MQTTs by using the encrypted port 8883 + "ssl":true.

==== Variables used setup ====

== 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 ===
{| class="wikitable"
! style="font-weight:bold; background-color:#9b9b9b;" | Item
! style="font-weight:bold; background-color:#9b9b9b;" | Presence
! style="font-weight:bold; background-color:#9b9b9b;" | Possible Values
! style="font-weight:bold; background-color:#9b9b9b;" | Description
! style="font-weight:bold; background-color:#9b9b9b;" | JSON Config Usage
|-
| style="background-color:#efefef;" | topic
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | see table below
| style="background-color:#efefef;" | specification of the topic, which MQTT-flex device listens from broker and act accordingly. Max. 128 characters. The "#" can be used since FW 3.2.4 - see note under this table.
| style="background-color:#efefef;" | "topic":"netio/${DEVICE_NAME}/output/1/action"
|-
| style="background-color:#efefef;" | qos
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | 0, 1 or 2
| style="background-color:#efefef;" | 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}
| style="background-color:#efefef;" | "qos":0
|-
| style="background-color:#efefef;" | target
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" |
| style="background-color:#efefef;" | internal definition of action, which can be performed above the specified output
| style="background-color:#efefef;" | "target":"OUTPUTS/1/ACTION"
|-
| style="background-color:#efefef;" | action
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" |
| style="background-color:#efefef;" | a payload or a value the action attribute needs to have passed to
| style="background-color:#efefef;" | "action":"${payload}"
|-
| style="background-color:#efefef;" | actiondefNot supported yet
| style="background-color:#efefef;" | optional
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
|-
| style="background-color:#efefef;" | jsonNot supported yet
| style="background-color:#efefef;" | optional
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
|}

Note: The "#" wildcard can be used in subscribe topic definition. The multi-level wildcard character MUST be specified either on its own or following a topic level separator. In either case it MUST be the last character specified in the Topic.

For example, if a Device subscribes to “devices/{device_id}/messages/devicebound/#”, it would receive messages published using these topic names:

“devices/{device_id}/messages/devicebound/”

“devices/{device_id}/messages/devicebound/{property_bag}”

This should be usefull for use with MS Azure - IoT hub.

=== MQTT Subscribe as event to trigger action <code>FW 4.0.0+</code> ===

This feature allow to subscribe to specific MQTT topic and pass payload to Rules or MQTT-flex as event.

target: <code>PROTOCOLS/MQTT/EVENT</code>

"subscribe": [
{
"action": "${payload}",
"qos": 0,
"target": "PROTOCOLS/MQTT/EVENT",
"topic": "broker/12345/MQTT_EVENT/"
}
]

=== Examples ===
==== Toggle output with standard payload ====
==== Toggle output with custom payload ====
==== Subscribe to more than one topic ====
==== Trigger Rule and MQTT publish from MQTT subscribe <code>FW 4.0.0+</code> ====
This example show Request response implementation in MQTT and toggle action made by Rules.

When message with payload <code>getValues</code> is published to topic <code>broker/gv90018g/COMMAND</code> MQTT flex will create an event with name <code>PROTOCOLS/MQTT/EVENT</code> (fixed name cannot be changed) and value <code>getValues</code>. On this event will act all events and conditions set in MQTT-flex and Rules which are set to listening to change on <code>PROTOCOLS/MQTT/EVENT</code> and equals to value <code>getValues</code>. See bold marked parameters in example configuration below.

Once the triggered action is done it is needed to reset MQTT channel to <code>OK</code> status becaus event are reacting only to change. If the channel is not reset the next even would not be triggered.

Rules Configuration:
{
"conditions": {
"PROTOCOLS/MQTT/EVENT": "getValues"
},
"actions": {
"OUTPUTS/1/ACTION": 4
}
}

MQTT Configuration:
{
"broker":{
"clientid":"netio${DEVICE_SN}",
"keepalive":30,
"password":"abcdefghijk",
"port":8883,
"protocol":"mqtt",
"ssl":true,
"type":"generic",
"url":"broker.cloud.netio.eu",
"username":"gv90018g"
},
"groupEvents":[
{
"events":[
{
"source":"PROTOCOLS/MQTT/EVENT",
"type":"change",
"value":"getValues"
}
],
"appliedTopics":[
"broker/gv90018g/OUTPUTS/1/STATE",
"broker/gv90018g/COMMAND"
]
}
],
"publish":[
{
"payload":"${OUTPUTS/1/STATE}",
"qos":0,
"retain":true,
"topic":"broker/gv90018g/OUTPUTS/1/STATE"
},
{
"payload":"OK",
"qos":0,
"retain":true,
"topic":"broker/gv90018g/COMMAND"
}
],
"subscribe":[
{
"action":"${payload}",
"qos":0,
"target":"PROTOCOLS/MQTT/EVENT",
"topic":"broker/gv90018g/COMMAND"
}
]
}

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 ===
{| class="wikitable"
! style="font-weight:bold; background-color:#9b9b9b;" | Item
! style="font-weight:bold; background-color:#9b9b9b;" | Presence
! style="font-weight:bold; background-color:#9b9b9b;" | Possible Values
! style="font-weight:bold; background-color:#9b9b9b;" | Description
! style="font-weight:bold; background-color:#9b9b9b;" | JSON Config Usage
|-
| style="background-color:#efefef;" | topic
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | see table below
| style="background-color:#efefef;" | definition of the topic, how it is registered towards MQTT broker. Max. 128 characters.
| style="background-color:#efefef;" | "topic":"netio/${DEVICE_NAME}/output/1/load"
|-
| style="background-color:#efefef;" | qos
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | see table below
| style="background-color:#efefef;" | 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}
| style="background-color:#efefef;" |
|-
| style="background-color:#efefef;" | retain
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | boolean: true or false
| style="background-color:#efefef;" | 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}
| style="background-color:#efefef;" | "retain":true
|-
| style="background-color:#efefef;" | payload
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | see table below
| style="background-color:#efefef;" | definition of the payload, what is send to the MQTT broker.
| style="background-color:#efefef;" | "payload":"${OUTPUTS/1/STATE}"
|-
| style="background-color:#efefef;" | events
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | see table below
| style="background-color:#efefef;" | definition of events used for triggering sending of data via mqtt (change, delta, timer)
| style="background-color:#efefef;" |
|-
| style="background-color:#efefef;" | type
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
|-
| style="background-color:#efefef;" | source
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
|-
| style="background-color:#efefef;" | delta
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
|-
| style="background-color:#efefef;" | period
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
|-
| style="background-color:#efefef;" | payloaddefNot supported yet
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
|}

=== Examples ===
==== Publish energy periodically (event timer) ====
==== Publish current on change (delta) ====
==== Publish output state ====
==== Publish to more than one topic with different events ====

= 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 available only on NETIO PowerDIN 4PZ

=== Examples: ===

adressing controll of output 3
OUTPUTS/3/ACTION
getting voltage on output 1
OUTPUTS/1/VOLTAGE
getting state of input 1
INPUTS/1/STATE

= Group Events<code>FW 4.0.0+</code> =
Group events are smart way how to keep configuration simple. It is not replacement of publish section specification but it is extension to trigger group of different topic publish on the same event.

See the example below.

{
"broker": {
"clientid": "netio${DEVICE_SN}",
"keepalive": 30,
"password": "",
"port": 1883,
"protocol": "mqtt",
"ssl": false,
"type": "generic",
"url": "broker.hivemq.com",
"username": ""
},
"groupEvents": [
{
"events":[
{
"period": 60,
"type": "timer"
}
],
"appliedTopics":[
"devices/${DEVICE_NAME}/output/1/state",
"devices/${DEVICE_NAME}/output/1/state"
]
}
]
},
"publish": [
{
"events": [
{
"source": "OUTPUT/1/STATE",
"type": "change"
}
],
"payload": "${OUTPUT/1/STATE}",
"qos": 0,
"retain": false,
"topic": "devices/${DEVICE_NAME}/output/1/state"
},{
"events": [
{
"source": "OUTPUT/2/STATE",
"type": "change"
}
],
"payload": "${OUTPUT/2/STATE}",
"qos": 0,
"retain": false,
"topic": "devices/${DEVICE_NAME}/output/2/state"
},
]
}

= 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 ===
==== VOLTAGE ====
Unit: <code>V</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Present RMS voltage on output 1 is ${OUTPUTS/1/VOLTAGE}"</code>

Example 2: <code>"source":"${OUTPUTS/1/VOLTAGE}"</code>

==== CURRENT ====
Unit: <code>mA</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Present RMS current on output 1 is ${OUTPUTS/1/CURRENT}"</code>

Example 2: <code>"source":"${OUTPUTS/1/CURRENT}"</code>

==== POWER_FACTOR ====
Unit: <code>[-]</code>

Type: float (2 decimals)

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"True Power Factor on output 1 is ${OUTPUTS/1/POWER_FACTOR}"</code>

Example 2: <code>"source":"${OUTPUTS/1/POWER_FACTOR}"</code>

==== LOAD ====
Unit: <code>W</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Present load on output 1 is ${OUTPUTS/1/LOAD}W"</code>

Example 2: <code>"payload":"Device's load connected to output 1 is ${OUTPUTS/1/LOAD}W"</code>

Example 3: <code>"source":"${OUTPUTS/1/LOAD}"</code>

==== STATE ====
Type: bool(integer) - <code>0</code> or <code>1</code>

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Present output 1 state is ${OUTPUTS/1/STATE}"</code>

Example 2: <code>"source":"${OUTPUTS/1/STATE}"</code>

==== ACTION ====
Type: integer

Possible actions:
* <code>0</code> - set state OFF
* <code>1</code> - set state ON
* <code>2</code> - short OFF (restart)
* <code>3</code> - short ON
* <code>4</code> - toggle (switch)
* <code>5</code> - no change

Allowed in: <code>"target"</code>

Example: <code>"target":"OUTPUTS/1/ACTION"</code>

==== DELAY [ms] ====
==== NAME ====
==== FREQUENCY ====
Unit: <code>Hz</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example: <code>"payload":"Frequency in power grid is ${OUTPUTS/1/ENERGY}Hz"</code>

==== ENERGY ====
Energy consumed by an device connected to NETIO device output.

Unit: <code>Wh</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Consumed energy on output 1 is ${OUTPUTS/1/ENERGY}Wh"</code>

Example 2: <code>"source":"${OUTPUTS/1/ENERGY}"</code>

==== REVERSE_ENERGY ====
Energy delivered back to grid. For example from solar system connected to NETIO device output.

Unit: <code>Wh</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Delivered energy on output 1 is ${OUTPUTS/1/REVERSE_ENERGY}Wh"</code>

Example 2: <code>"source":"${OUTPUTS/1/REVERSE_ENERGY}"</code>

==== ENERGY_START ====
Date when the counters ENERGY and REVERSE_ENERGY have been resetted by user.

Unit: <code>unix timestamp</code>

Type: integer

Allowed in: <code>"payload"</code>

Example 1: <code>"payload":"Energy measured since ${OUTPUTS/1/ENERGY_START} unix time"</code>

Example 2: <code>"payload":"${OUTPUTS/1/ENERGY_START}"</code> is output payload <code>1567654639</code>

==== ENERGY_START_FMT ====
Date when the counters ENERGY and REVERSE_ENERGY have been resetted by user.

Unit: <code>fmt date format</code>

Type: string

Allowed in: <code>"payload"</code>

Example 1: <code>"payload":"Energy measured since ${OUTPUTS/1/ENERGY_START}"</code>

Example 2: <code>"payload":"${OUTPUTS/1/ENERGY_START_FMT}"</code> is output payload <code>2019-09-05T03:37:19+00:00</code>

==== ENERGY_NR ====
Non-resettable counter of Energy consumed by an device connected to NETIO device output.

Unit: <code>Wh</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Consumed energy on output 1 is ${OUTPUTS/1/ENERGY_NR}Wh"</code>

Example 2: <code>"source":"${OUTPUTS/1/ENERGY_NR}"</code>

==== REVERSE_ENERGY_NR ====
Non-resettable counter of Energy delivered back to grid. For example from solar system connected to NETIO device output.

Unit: <code>Wh</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Delivered energy on output 1 is ${OUTPUTS/1/REVERSE_ENERGY_NR}Wh"</code>

Example 2: <code>"source":"${OUTPUTS/1/REVERSE_ENERGY_NR}"</code>

==== TOTALs - for 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
* OUTPUTS/TOTAL/PHASE
* OUTPUTS/TOTAL/REVERSE_ENERGY
* OUTPUTS/TOTAL/ENERGY_NR
* OUTPUTS/TOTAL/REVERSE_ENERGY_NR
* OUTPUTS/TOTAL/ENERGY_START
* OUTPUTS/TOTAL/ENERGY_START_FMT

==== REST_JSON ====
Allow use of NETIO JSON structure to control outputs.

Type: string / JSON

Allowed in: <code>"target"</code> for Subscribe section

Example: <code>"target": "REST_JSON"</code>

The payload is JSON structure identical to NETIO JSON API M2M Protocol (documentation available at https://www.netio-products.com/files/NETIO-M2M-API-Protocol-JSON.pdf). You can control one or multiple outputs.

Payload example 1 - Toggle output 1: <code>{"Outputs":[{"ID": 1,"Action": 4}]}</code>

Payload example 2 - Turn output 1 OFF and output 3 ON: <code>{"Outputs":[{"ID":1,"Action":0},{"ID":3,"Action":1}]}</code>

=== INPUT variables ===
==== STATE ====
Type: bool(integer) - <code>0</code> or <code>1</code>

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Present input 1 state is ${INPUTS/1/STATE}"</code>

Example 2: <code>"source":"${INPUTS/1/STATE}"</code>

==== S0 ====
S0 Counter value
Unit: <code>-</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Input 1 S0 Counter value is ${INPUTS/1/S0}impulses"</code>

Example 2: <code>"source":"${INPUTS/1/S0}"</code>

== Payload/topic variables ==

=== DEVICE_NAME ===
Can be used in: "payload", "topic"

Example 1: <code>"payload":"${DEVICE_NAME}"</code>

Example 2: <code>"topic":"netio/${DEVICE_NAME}/output/1/action"</code>

=== DEVICE_MAC ===

=== UPTIME Not yet implemented ===

=== PAYLOAD ===
Can be used in: "action"

Example: <code>"action":"${PAYLOAD}"</code>

=== OUTPUT_ID Not yet implemented===

=== WIFI_SIGNALNot yet implemented ===

=== OUTPUTS_STATUS ===
Provide complete outputs status and measurement if supported.

Type: string / JSON

Allowed in: <code>"payload"</code> for Publish section

Example: <code>"payload":"${OUTPUTS_STATUS}"</code>

Payload example: <code>{ "GlobalMeasure":{"Voltage":236,"TotalCurrent":72,"TotalLoad":11,"TotalEnergy":167,"OverallPowerFactor":0.64,"Frequency":50.07,"Phase":-36.86,"EnergyStart":"2020-06-30T17:04:48+01:00"}, "Outputs":[ {"ID":1,"Name":"Power output 1","State":1,"Action":6,"Delay":2020,"Current":72,"PowerFactor":0.64,"Phase":-36.86,"Energy":139,"ReverseEnergy":0,"Load":11}, {"ID":2,"Name":"Power output 2","State":1,"Action":6,"Delay":2020,"Current":0,"PowerFactor":1.00,"Phase":0.00,"Energy":27,"ReverseEnergy":0,"Load":0}, {"ID":3,"Name":"Free Contact 3","State":1,"Action":6,"Delay":2020}, {"ID":4,"Name":"Free Contact 4","State":1,"Action":6,"Delay":2020} ]}</code>

=== INPUTS_STATUS ===
Provide complete inputs status if supported. Since FW 3.0.0

Type: string / JSON

Allowed in: <code>"payload"</code> for Publish section

Example: <code>"payload":"${INPUTS_STATUS}"</code>

Payload example: <code>{ "Inputs":[ {"ID":1,"Name":"Input 1","State":0,"S0Counter":0}, {"ID":2,"Name":"Input 2","State":0,"S0Counter":0} ]}</code>

=== INOUT_STATUS ===
Provide complete inputs and output status and measurement if supported. Since FW 3.0.0

Type: string / JSON

Allowed in: <code>"payload"</code> for Publish section

Example: <code>"payload":"${INOUT_STATUS}"</code>

Payload example: <code>{ "GlobalMeasure":{"Voltage":238,"TotalCurrent":105,"TotalLoad":17,"TotalEnergy":1451,"OverallPowerFactor":0.67,"Frequency":50.03,"Phase":-33.67,"EnergyStart":"2020-06-30T17:04:48+01:00"}, "Outputs":[ {"ID":1,"Name":"Power output 1","State":0,"Action":6,"Delay":5000,"Current":0,"PowerFactor":1.00,"Phase":0.00,"Energy":701,"ReverseEnergy":0,"Load":0}, {"ID":2,"Name":"Power output 2","State":1,"Action":6,"Delay":5000,"Current":105,"PowerFactor":0.65,"Phase":-33.67,"Energy":750,"ReverseEnergy":0,"Load":17}, {"ID":3,"Name":"Free Contact 3","State":1,"Action":6,"Delay":5000}, {"ID":4,"Name":"Free Contact 4","State":0,"Action":6,"Delay":5000} ], "Inputs":[ {"ID":1,"Name":"Input 1","State":0,"S0Counter":0}, {"ID":2,"Name":"Input 2","State":0,"S0Counter":0} ]}</code>

= Extended MQTT flex JSON config examples =

== Default NETIO MQTT-flex configuration ==
This example demonstrates setup for connection to public <code>broker.hivemq.com</code>, measurement reporting and output control.

The device cabe be controlled via <code>netio/${DEVICE_NAME}/output/1/action topic</code> by sending standard NETIO action values:
* 0 - OFF
* 1 - ON
* 2 - SHORT OFF
* 3 - SHORT ON
* 4 - TOGGLE
* 5 - NO ACTION.

The device report measurements:

* Output state - every 15 minutes or by change
* Voltage [V]- every 5 minutes or by change of 1 V
* Current [mA]- every 5 minutes or by change of 50 mA
* Load(Power) [W]- every 5 minutes or by change of 10 W
* Energy(Consumption) [Wh]- every 15 minutes or by change of 1Wh
* True Power Factor (TPF) [-]- every 5 minutes or by change of 0.02
* Frequency [Hz]- every 1 hour or by change of 0.1 Hz

For register all values, you can use wildcard <code>netio/${DEVICE_NAME}/output/1/#</code>

{
"config":{
"broker":{
"url":"broker.hivemq.com",
"protocol":"mqtt",
"port":1883,
"ssl":false,
"type":"generic",
"username":"",
"password":"",
"clientid":"moje${DEVICE_NAME}${DEVICE_MAC}",
"keepalive":30
},
"subscribe":[
{
"topic":"netio/${DEVICE_NAME}/output/1/action",
"qos":0,
"target":"OUTPUTS/1/ACTION",
"action":"${payload}"
},
{
"topic":"netio/${DEVICE_NAME}/output/1/switch",
"qos":0,
"target":"OUTPUTS/1/ACTION",
"action":4
}
],
"publish":[
{
"topic":"netio/${DEVICE_MAC}/output/1/state",
"qos":0,
"retain":true,
"payload":"${OUTPUTS/1/STATE}",
"events":[
{
"type":"change",
"source":"OUTPUTS/1/STATE"
},
{
"type":"timer",
"period":900
}
]
},
{
"topic":"netio/${DEVICE_NAME}/output/1/voltage",
"qos":0,
"retain":false,
"payload":"${OUTPUTS/1/VOLTAGE}",
"events":[
{
"type":"timer",
"period":300
},
{
"type":"delta",
"source":"OUTPUTS/1/VOLTAGE",
"delta":1
}
]
},
{
"topic":"netio/${DEVICE_NAME}/output/1/current",
"qos":0,
"retain":false,
"payload":"${OUTPUTS/1/CURRENT}",
"events":[
{
"type":"timer",
"period":300
},
{
"type":"delta",
"source":"OUTPUTS/1/CURRENT",
"delta":50
}
]
},
{
"topic":"netio/${DEVICE_NAME}/output/1/load",
"qos":0,
"retain":false,
"payload":"${OUTPUTS/1/LOAD}",
"events":[
{
"type":"timer",
"period":300
},
{
"type":"delta",
"source":"OUTPUTS/1/LOAD",
"delta":10
}
]
},
{
"topic":"netio/${DEVICE_NAME}/output/1/energy",
"qos":0,
"retain":false,
"payload":"${OUTPUTS/1/ENERGY}",
"events":[
{
"type":"timer",
"period":900
},
{
"type":"delta",
"source":"OUTPUTS/1/ENERGY",
"delta":1
}
]
},
{
"topic":"netio/${DEVICE_NAME}/output/1/tpf",
"qos":0,
"retain":false,
"payload":"${OUTPUTS/1/POWER_FACTOR}",
"events":[
{
"type":"timer",
"period":900
},
{
"type":"delta",
"source":"OUTPUTS/1/POWER_FACTOR",
"delta":0.02
}
]
},
{
"topic":"netio/${DEVICE_NAME}/output/1/frequency",
"qos":0,
"retain":false,
"payload":"${OUTPUTS/1/FREQUENCY}",
"events":[
{
"type":"timer",
"period":3600
},
{
"type":"delta",
"source":"OUTPUTS/1/FREQUENCY",
"delta":0.1
}
]
}
]
}
}

MQTT-flex

2023-06-06T14:18:32Z

Bbakala: /* Events */

The MQTT-flex version of the MQTT protocol can be configured in detail thanks to the “flex” extension.

https://www.netio-products.com/en/glossary/mqtt-flex

Why MQTT-flex 
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 [https://en.wikipedia.org/wiki/MQTT 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 [https://en.wikipedia.org/wiki/JSON 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 101x 
* PowerCable REST 101x 
* PowerPDU 4PS 
* PowerPDU 4KS 
* PowerPDU 8QS 
* PowerDIN 4PZ 
* PowerBOX 3Px 
* PowerBOX 4Kx 

FW version: 
>2.2.1

===Not supported NETIO devices:===
* PowerPDU 4C 
* NETIO 4 
* NETIO 4All 

= Simple MQTT-flex configuration + explanation =

''We strongly recommend to create and test MQTT-flex configuration on "local" device what can be easily restarted. The validation of config before saving is not 100% and for example some specific typos can cause a freeze of a device - the solution is to restart a device (unplug/plug input power cable). If the configuration is saved and device is working then there are no known failure case so it is safe to use this configuration on the "remote" devices.''

{
"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":false,
"payload":"${OUTPUTS/1/STATE}",
"events":[
{
"type":"timer",
"period":"1000"
}
]
}
]
}
}
=== Client Configuration (broker section) ===
Put here MQTT client connection setup

This configuration example set NETIO device to connect to broker.hivemq.com with mqtt protocol, no ssl connection with credetials freedom/peace|love|empathy4ALL.

"broker":{
"url":"broker.hivemq.com",
"protocol":"mqtt",
"port":1883,
"ssl":false,
"type":"generic",
"username":"freedom",
"password":"peace|LOVE|empathy4ALL"
},

=== Device Control (subscribe section) ===
Put here array of topics where to subscribe

Device output 1 is controlled with action received by subscription to netio/${DEVICE_NAME}/output/1/action topic with QOS 0

"subscribe":[{
"topic":"netio/${DEVICE_NAME}/output/1/action",
"qos":0,
"target":"OUTPUTS/1/ACTION",
"action":"${payload}"
}
],

=== Output State monitoring (publish section) ===
Put here array of topics where to publish.

Device send every 1000 s message to topic with QOS 0, retain true information with output 1 state

"publish":[{
"topic":"netio/${DEVICE_NAME}/output/1/state",
"qos":0,
"retain":true,
"payload":"${OUTPUTS/1/STATE}",
"events":[
{
"type":"timer",
"period":"1000"
}
]
}
]

= 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 ===
{| class="wikitable"
! style="font-weight:bold; background-color:#9b9b9b;" | Item
! style="font-weight:bold; background-color:#9b9b9b;" | Presence
! style="font-weight:bold; background-color:#9b9b9b;" | Possible Values
! style="font-weight:bold; background-color:#9b9b9b;" | Description
! style="font-weight:bold; background-color:#9b9b9b;" | JSON Config Usage
|-
| style="background-color:#efefef;" | url
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" |
| style="background-color:#efefef;" | MQTT broker URL
| style="background-color:#efefef;" | "url":"broker.hivemq.com"
|-
| style="background-color:#efefef;" | port
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | 1 - 65535
| style="background-color:#efefef;" | MQTT broker port
| style="background-color:#efefef;" | "port":1883
|-
| style="background-color:#efefef;" | protocol
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" |
| style="background-color:#efefef;" | protocol spec - mqtt
| style="background-color:#efefef;" | "protocol": "mqtt"
|-
| style="background-color:#efefef;" | ssl
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | true, false
| style="background-color:#efefef;" | Use SSL crypted communication selector
| style="background-color:#efefef;" | "ssl":false
|-
| style="background-color:#efefef;" | type
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | generic
| style="background-color:#efefef;" | Communication/setup type option
| style="background-color:#efefef;" | "type":"generic"
|-
| style="background-color:#efefef;" | username
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | regexp+len
| style="background-color:#efefef;" | Credentials for MQTT broker. Max. 128 characters (since FW 3.2.4).
| style="background-color:#efefef;" | "username":"freedom"
|-
| style="background-color:#efefef;" | password
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | regexp+len
| style="background-color:#efefef;" | Credentials for MQTT broker. Max. 256 characters (since FW 3.2.4).
| style="background-color:#efefef;" | "password":"peace|LOVE|empathy4ALL"
|-
| style="background-color:#efefef;" | clientid
| style="background-color:#efefef;" | optional
| style="background-color:#efefef;" | regexp+len
| style="background-color:#efefef;" | MQTT clientid. Max. 128 characters (since FW 3.2.4). Variables ${DEVICE_MAC} or ${DEVICE_NAME} can be used
| style="background-color:#efefef;" | "clientid":"myEcoTable01"
|-
| style="background-color:#efefef;" | keepalive
| style="background-color:#efefef;" | optional
| style="background-color:#efefef;" | 1 - 65535
| style="background-color:#efefef;" | MQTT keep alive period in seconds
| style="background-color:#efefef;" | "keepalive":90
|}

Note 1: clientid attribute is mandatory for MQTT(s) communication. When not configured, random ID will be generated.

Note 2: To proper communication with MS Azure - it is necessary to set up IoT Hub to use TLS 1.2

See section "TLS 1.2 enforcement available in select regions" in following guidelines https://docs.microsoft.com/en-us/azure/iot-hub/iot-hub-tls-support

=== Examples ===
==== Standard setup ====

==== Security (SSL / TLS) secured setup ====
You can enable MQTTs by using the encrypted port 8883 + "ssl":true.

==== Variables used setup ====

== 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 ===
{| class="wikitable"
! style="font-weight:bold; background-color:#9b9b9b;" | Item
! style="font-weight:bold; background-color:#9b9b9b;" | Presence
! style="font-weight:bold; background-color:#9b9b9b;" | Possible Values
! style="font-weight:bold; background-color:#9b9b9b;" | Description
! style="font-weight:bold; background-color:#9b9b9b;" | JSON Config Usage
|-
| style="background-color:#efefef;" | topic
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | see table below
| style="background-color:#efefef;" | specification of the topic, which MQTT-flex device listens from broker and act accordingly. Max. 128 characters. The "#" can be used since FW 3.2.4 - see note under this table.
| style="background-color:#efefef;" | "topic":"netio/${DEVICE_NAME}/output/1/action"
|-
| style="background-color:#efefef;" | qos
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | 0, 1 or 2
| style="background-color:#efefef;" | 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}
| style="background-color:#efefef;" | "qos":0
|-
| style="background-color:#efefef;" | target
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" |
| style="background-color:#efefef;" | internal definition of action, which can be performed above the specified output
| style="background-color:#efefef;" | "target":"OUTPUTS/1/ACTION"
|-
| style="background-color:#efefef;" | action
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" |
| style="background-color:#efefef;" | a payload or a value the action attribute needs to have passed to
| style="background-color:#efefef;" | "action":"${payload}"
|-
| style="background-color:#efefef;" | actiondefNot supported yet
| style="background-color:#efefef;" | optional
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
|-
| style="background-color:#efefef;" | jsonNot supported yet
| style="background-color:#efefef;" | optional
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
|}

Note: The "#" wildcard can be used in subscribe topic definition. The multi-level wildcard character MUST be specified either on its own or following a topic level separator. In either case it MUST be the last character specified in the Topic.

For example, if a Device subscribes to “devices/{device_id}/messages/devicebound/#”, it would receive messages published using these topic names:

“devices/{device_id}/messages/devicebound/”

“devices/{device_id}/messages/devicebound/{property_bag}”

This should be usefull for use with MS Azure - IoT hub.

=== MQTT Subscribe as event to trigger action <code>FW 4.0.0+</code> ===

This feature allow to subscribe to specific MQTT topic and pass payload to Rules or MQTT-flex as event.

target: <code>PROTOCOLS/MQTT/EVENT</code>

"subscribe": [
{
"action": "${payload}",
"qos": 0,
"target": "PROTOCOLS/MQTT/EVENT",
"topic": "broker/12345/MQTT_EVENT/"
}
]

=== Examples ===
==== Toggle output with standard payload ====
==== Toggle output with custom payload ====
==== Subscribe to more than one topic ====
==== Trigger Rule and MQTT publish from MQTT subscribe <code>FW 4.0.0+</code> ====
This example show Request response implementation in MQTT and toggle action made by Rules.

When message with payload <code>getValues</code> is published to topic <code>broker/gv90018g/COMMAND</code> MQTT flex will create an event with name <code>PROTOCOLS/MQTT/EVENT</code> (fixed name cannot be changed) and value <code>getValues</code>. On this event will act all events and conditions set in MQTT-flex and Rules which are set to listening to change on <code>PROTOCOLS/MQTT/EVENT</code> and equals to value <code>getValues</code>. See bold marked parameters in example configuration below.

Once the triggered action is done it is needed to reset MQTT channel to <code>OK</code> status becaus event are reacting only to change. If the channel is not reset the next even would not be triggered.

Rules Configuration:
{
"conditions": {
"PROTOCOLS/MQTT/EVENT": "getValues"
},
"actions": {
"OUTPUTS/1/ACTION": 4
}
}

MQTT Configuration:
{
"broker":{
"clientid":"netio${DEVICE_SN}",
"keepalive":30,
"password":"abcdefghijk",
"port":8883,
"protocol":"mqtt",
"ssl":true,
"type":"generic",
"url":"broker.cloud.netio.eu",
"username":"gv90018g"
},
"groupEvents":[
{
"events":[
{
"source":"PROTOCOLS/MQTT/EVENT",
"type":"change",
"value":"getValues"
}
],
"appliedTopics":[
"broker/gv90018g/OUTPUTS/1/STATE",
"broker/gv90018g/COMMAND"
]
}
],
"publish":[
{
"payload":"${OUTPUTS/1/STATE}",
"qos":0,
"retain":true,
"topic":"broker/gv90018g/OUTPUTS/1/STATE"
},
{
"payload":"OK",
"qos":0,
"retain":true,
"topic":"broker/gv90018g/COMMAND"
}
],
"subscribe":[
{
"action":"${payload}",
"qos":0,
"target":"PROTOCOLS/MQTT/EVENT",
"topic":"broker/gv90018g/COMMAND"
}
]
}

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 ===
{| class="wikitable"
! style="font-weight:bold; background-color:#9b9b9b;" | Item
! style="font-weight:bold; background-color:#9b9b9b;" | Presence
! style="font-weight:bold; background-color:#9b9b9b;" | Possible Values
! style="font-weight:bold; background-color:#9b9b9b;" | Description
! style="font-weight:bold; background-color:#9b9b9b;" | JSON Config Usage
|-
| style="background-color:#efefef;" | topic
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | see table below
| style="background-color:#efefef;" | definition of the topic, how it is registered towards MQTT broker. Max. 128 characters.
| style="background-color:#efefef;" | "topic":"netio/${DEVICE_NAME}/output/1/load"
|-
| style="background-color:#efefef;" | qos
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | see table below
| style="background-color:#efefef;" | 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}
| style="background-color:#efefef;" |
|-
| style="background-color:#efefef;" | retain
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | boolean: true or false
| style="background-color:#efefef;" | 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}
| style="background-color:#efefef;" | "retain":true
|-
| style="background-color:#efefef;" | payload
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | see table below
| style="background-color:#efefef;" | definition of the payload, what is send to the MQTT broker.
| style="background-color:#efefef;" | "payload":"${OUTPUTS/1/STATE}"
|-
| style="background-color:#efefef;" | events
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | see table below
| style="background-color:#efefef;" | definition of events used for triggering sending of data via mqtt (change, delta, timer)
| style="background-color:#efefef;" |
|-
| style="background-color:#efefef;" | type
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
|-
| style="background-color:#efefef;" | source
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
|-
| style="background-color:#efefef;" | delta
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
|-
| style="background-color:#efefef;" | period
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
|-
| style="background-color:#efefef;" | payloaddefNot supported yet
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
|}

=== Examples ===
==== Publish energy periodically (event timer) ====
==== Publish current on change (delta) ====
==== Publish output state ====
==== Publish to more than one topic with different events ====

= 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 available only on NETIO PowerDIN 4PZ

=== Examples: ===

adressing controll of output 3
OUTPUTS/3/ACTION
getting voltage on output 1
OUTPUTS/1/VOLTAGE
getting state of input 1
INPUTS/1/STATE

= Group Events<code>FW 4.0.0+</code> =
Group events are smart way how to keep configuration simple. It is not replacement of publish section specification but it is extension to trigger group of different topic publish on the same event.

See the example below.

{
"broker": {
"clientid": "netio${DEVICE_SN}",
"keepalive": 30,
"password": "",
"port": 1883,
"protocol": "mqtt",
"ssl": false,
"type": "generic",
"url": "broker.hivemq.com",
"username": ""
},
"groupEvents": [
{
"events":[
{
"period": 60,
"type": "timer"
}
],
"appliedTopics":[
"devices/${DEVICE_NAME}/output/1/state",
"devices/${DEVICE_NAME}/output/1/state"
]
}
]
},
"publish": [
{
"events": [
{
"source": "OUTPUT/1/STATE",
"type": "change"
}
],
"payload": "${OUTPUT/1/STATE}",
"qos": 0,
"retain": false,
"topic": "devices/${DEVICE_NAME}/output/1/state"
},{
"events": [
{
"source": "OUTPUT/2/STATE",
"type": "change"
}
],
"payload": "${OUTPUT/2/STATE}",
"qos": 0,
"retain": false,
"topic": "devices/${DEVICE_NAME}/output/2/state"
},
]
}

= 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 ===
==== VOLTAGE ====
Unit: <code>V</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Present RMS voltage on output 1 is ${OUTPUTS/1/VOLTAGE}"</code>

Example 2: <code>"source":"${OUTPUTS/1/VOLTAGE}"</code>

==== CURRENT ====
Unit: <code>mA</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Present RMS current on output 1 is ${OUTPUTS/1/CURRENT}"</code>

Example 2: <code>"source":"${OUTPUTS/1/CURRENT}"</code>

==== POWER_FACTOR ====
Unit: <code>[-]</code>

Type: float (2 decimals)

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"True Power Factor on output 1 is ${OUTPUTS/1/POWER_FACTOR}"</code>

Example 2: <code>"source":"${OUTPUTS/1/POWER_FACTOR}"</code>

==== LOAD ====
Unit: <code>W</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Present load on output 1 is ${OUTPUTS/1/LOAD}W"</code>

Example 2: <code>"payload":"Device's load connected to output 1 is ${OUTPUTS/1/LOAD}W"</code>

Example 3: <code>"source":"${OUTPUTS/1/LOAD}"</code>

==== STATE ====
Type: bool(integer) - <code>0</code> or <code>1</code>

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Present output 1 state is ${OUTPUTS/1/STATE}"</code>

Example 2: <code>"source":"${OUTPUTS/1/STATE}"</code>

==== ACTION ====
Type: integer

Possible actions:
* <code>0</code> - set state OFF
* <code>1</code> - set state ON
* <code>2</code> - short OFF (restart)
* <code>3</code> - short ON
* <code>4</code> - toggle (switch)
* <code>5</code> - no change

Allowed in: <code>"target"</code>

Example: <code>"target":"OUTPUTS/1/ACTION"</code>

==== DELAY [ms] ====
==== NAME ====
==== FREQUENCY ====
Unit: <code>Hz</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example: <code>"payload":"Frequency in power grid is ${OUTPUTS/1/ENERGY}Hz"</code>

==== ENERGY ====
Energy consumed by an device connected to NETIO device output.

Unit: <code>Wh</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Consumed energy on output 1 is ${OUTPUTS/1/ENERGY}Wh"</code>

Example 2: <code>"source":"${OUTPUTS/1/ENERGY}"</code>

==== REVERSE_ENERGY ====
Energy delivered back to grid. For example from solar system connected to NETIO device output.

Unit: <code>Wh</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Delivered energy on output 1 is ${OUTPUTS/1/REVERSE_ENERGY}Wh"</code>

Example 2: <code>"source":"${OUTPUTS/1/REVERSE_ENERGY}"</code>

==== ENERGY_START ====
Date when the counters ENERGY and REVERSE_ENERGY have been resetted by user.

Unit: <code>unix timestamp</code>

Type: integer

Allowed in: <code>"payload"</code>

Example 1: <code>"payload":"Energy measured since ${OUTPUTS/1/ENERGY_START} unix time"</code>

Example 2: <code>"payload":"${OUTPUTS/1/ENERGY_START}"</code> is output payload <code>1567654639</code>

==== ENERGY_START_FMT ====
Date when the counters ENERGY and REVERSE_ENERGY have been resetted by user.

Unit: <code>fmt date format</code>

Type: string

Allowed in: <code>"payload"</code>

Example 1: <code>"payload":"Energy measured since ${OUTPUTS/1/ENERGY_START}"</code>

Example 2: <code>"payload":"${OUTPUTS/1/ENERGY_START_FMT}"</code> is output payload <code>2019-09-05T03:37:19+00:00</code>

==== ENERGY_NR ====
Non-resettable counter of Energy consumed by an device connected to NETIO device output.

Unit: <code>Wh</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Consumed energy on output 1 is ${OUTPUTS/1/ENERGY_NR}Wh"</code>

Example 2: <code>"source":"${OUTPUTS/1/ENERGY_NR}"</code>

==== REVERSE_ENERGY_NR ====
Non-resettable counter of Energy delivered back to grid. For example from solar system connected to NETIO device output.

Unit: <code>Wh</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Delivered energy on output 1 is ${OUTPUTS/1/REVERSE_ENERGY_NR}Wh"</code>

Example 2: <code>"source":"${OUTPUTS/1/REVERSE_ENERGY_NR}"</code>

==== TOTALs - for 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
* OUTPUTS/TOTAL/PHASE
* OUTPUTS/TOTAL/REVERSE_ENERGY
* OUTPUTS/TOTAL/ENERGY_NR
* OUTPUTS/TOTAL/REVERSE_ENERGY_NR
* OUTPUTS/TOTAL/ENERGY_START
* OUTPUTS/TOTAL/ENERGY_START_FMT

==== REST_JSON ====
Allow use of NETIO JSON structure to control outputs.

Type: string / JSON

Allowed in: <code>"target"</code> for Subscribe section

Example: <code>"target": "REST_JSON"</code>

The payload is JSON structure identical to NETIO JSON API M2M Protocol (documentation available at https://www.netio-products.com/files/NETIO-M2M-API-Protocol-JSON.pdf). You can control one or multiple outputs.

Payload example 1 - Toggle output 1: <code>{"Outputs":[{"ID": 1,"Action": 4}]}</code>

Payload example 2 - Turn output 1 OFF and output 3 ON: <code>{"Outputs":[{"ID":1,"Action":0},{"ID":3,"Action":1}]}</code>

=== INPUT variables ===
==== STATE ====
Type: bool(integer) - <code>0</code> or <code>1</code>

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Present input 1 state is ${INPUTS/1/STATE}"</code>

Example 2: <code>"source":"${INPUTS/1/STATE}"</code>

==== S0 ====
S0 Counter value
Unit: <code>-</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Input 1 S0 Counter value is ${INPUTS/1/S0}impulses"</code>

Example 2: <code>"source":"${INPUTS/1/S0}"</code>

== Payload/topic variables ==

=== DEVICE_NAME ===
Can be used in: "payload", "topic"

Example 1: <code>"payload":"${DEVICE_NAME}"</code>

Example 2: <code>"topic":"netio/${DEVICE_NAME}/output/1/action"</code>

=== DEVICE_MAC ===

=== UPTIME Not yet implemented ===

=== PAYLOAD ===
Can be used in: "action"

Example: <code>"action":"${PAYLOAD}"</code>

=== OUTPUT_ID Not yet implemented===

=== WIFI_SIGNALNot yet implemented ===

=== OUTPUTS_STATUS ===
Provide complete outputs status and measurement if supported.

Type: string / JSON

Allowed in: <code>"payload"</code> for Publish section

Example: <code>"payload":"${OUTPUTS_STATUS}"</code>

Payload example: <code>{ "GlobalMeasure":{"Voltage":236,"TotalCurrent":72,"TotalLoad":11,"TotalEnergy":167,"OverallPowerFactor":0.64,"Frequency":50.07,"Phase":-36.86,"EnergyStart":"2020-06-30T17:04:48+01:00"}, "Outputs":[ {"ID":1,"Name":"Power output 1","State":1,"Action":6,"Delay":2020,"Current":72,"PowerFactor":0.64,"Phase":-36.86,"Energy":139,"ReverseEnergy":0,"Load":11}, {"ID":2,"Name":"Power output 2","State":1,"Action":6,"Delay":2020,"Current":0,"PowerFactor":1.00,"Phase":0.00,"Energy":27,"ReverseEnergy":0,"Load":0}, {"ID":3,"Name":"Free Contact 3","State":1,"Action":6,"Delay":2020}, {"ID":4,"Name":"Free Contact 4","State":1,"Action":6,"Delay":2020} ]}</code>

=== INPUTS_STATUS ===
Provide complete inputs status if supported. Since FW 3.0.0

Type: string / JSON

Allowed in: <code>"payload"</code> for Publish section

Example: <code>"payload":"${INPUTS_STATUS}"</code>

Payload example: <code>{ "Inputs":[ {"ID":1,"Name":"Input 1","State":0,"S0Counter":0}, {"ID":2,"Name":"Input 2","State":0,"S0Counter":0} ]}</code>

=== INOUT_STATUS ===
Provide complete inputs and output status and measurement if supported. Since FW 3.0.0

Type: string / JSON

Allowed in: <code>"payload"</code> for Publish section

Example: <code>"payload":"${INOUT_STATUS}"</code>

Payload example: <code>{ "GlobalMeasure":{"Voltage":238,"TotalCurrent":105,"TotalLoad":17,"TotalEnergy":1451,"OverallPowerFactor":0.67,"Frequency":50.03,"Phase":-33.67,"EnergyStart":"2020-06-30T17:04:48+01:00"}, "Outputs":[ {"ID":1,"Name":"Power output 1","State":0,"Action":6,"Delay":5000,"Current":0,"PowerFactor":1.00,"Phase":0.00,"Energy":701,"ReverseEnergy":0,"Load":0}, {"ID":2,"Name":"Power output 2","State":1,"Action":6,"Delay":5000,"Current":105,"PowerFactor":0.65,"Phase":-33.67,"Energy":750,"ReverseEnergy":0,"Load":17}, {"ID":3,"Name":"Free Contact 3","State":1,"Action":6,"Delay":5000}, {"ID":4,"Name":"Free Contact 4","State":0,"Action":6,"Delay":5000} ], "Inputs":[ {"ID":1,"Name":"Input 1","State":0,"S0Counter":0}, {"ID":2,"Name":"Input 2","State":0,"S0Counter":0} ]}</code>

= Extended MQTT flex JSON config examples =

== Default NETIO MQTT-flex configuration ==
This example demonstrates setup for connection to public <code>broker.hivemq.com</code>, measurement reporting and output control.

The device cabe be controlled via <code>netio/${DEVICE_NAME}/output/1/action topic</code> by sending standard NETIO action values:
* 0 - OFF
* 1 - ON
* 2 - SHORT OFF
* 3 - SHORT ON
* 4 - TOGGLE
* 5 - NO ACTION.

The device report measurements:

* Output state - every 15 minutes or by change
* Voltage [V]- every 5 minutes or by change of 1 V
* Current [mA]- every 5 minutes or by change of 50 mA
* Load(Power) [W]- every 5 minutes or by change of 10 W
* Energy(Consumption) [Wh]- every 15 minutes or by change of 1Wh
* True Power Factor (TPF) [-]- every 5 minutes or by change of 0.02
* Frequency [Hz]- every 1 hour or by change of 0.1 Hz

For register all values, you can use wildcard <code>netio/${DEVICE_NAME}/output/1/#</code>

{
"config":{
"broker":{
"url":"broker.hivemq.com",
"protocol":"mqtt",
"port":1883,
"ssl":false,
"type":"generic",
"username":"",
"password":"",
"clientid":"moje${DEVICE_NAME}${DEVICE_MAC}",
"keepalive":30
},
"subscribe":[
{
"topic":"netio/${DEVICE_NAME}/output/1/action",
"qos":0,
"target":"OUTPUTS/1/ACTION",
"action":"${payload}"
},
{
"topic":"netio/${DEVICE_NAME}/output/1/switch",
"qos":0,
"target":"OUTPUTS/1/ACTION",
"action":4
}
],
"publish":[
{
"topic":"netio/${DEVICE_MAC}/output/1/state",
"qos":0,
"retain":true,
"payload":"${OUTPUTS/1/STATE}",
"events":[
{
"type":"change",
"source":"OUTPUTS/1/STATE"
},
{
"type":"timer",
"period":900
}
]
},
{
"topic":"netio/${DEVICE_NAME}/output/1/voltage",
"qos":0,
"retain":false,
"payload":"${OUTPUTS/1/VOLTAGE}",
"events":[
{
"type":"timer",
"period":300
},
{
"type":"delta",
"source":"OUTPUTS/1/VOLTAGE",
"delta":1
}
]
},
{
"topic":"netio/${DEVICE_NAME}/output/1/current",
"qos":0,
"retain":false,
"payload":"${OUTPUTS/1/CURRENT}",
"events":[
{
"type":"timer",
"period":300
},
{
"type":"delta",
"source":"OUTPUTS/1/CURRENT",
"delta":50
}
]
},
{
"topic":"netio/${DEVICE_NAME}/output/1/load",
"qos":0,
"retain":false,
"payload":"${OUTPUTS/1/LOAD}",
"events":[
{
"type":"timer",
"period":300
},
{
"type":"delta",
"source":"OUTPUTS/1/LOAD",
"delta":10
}
]
},
{
"topic":"netio/${DEVICE_NAME}/output/1/energy",
"qos":0,
"retain":false,
"payload":"${OUTPUTS/1/ENERGY}",
"events":[
{
"type":"timer",
"period":900
},
{
"type":"delta",
"source":"OUTPUTS/1/ENERGY",
"delta":1
}
]
},
{
"topic":"netio/${DEVICE_NAME}/output/1/tpf",
"qos":0,
"retain":false,
"payload":"${OUTPUTS/1/POWER_FACTOR}",
"events":[
{
"type":"timer",
"period":900
},
{
"type":"delta",
"source":"OUTPUTS/1/POWER_FACTOR",
"delta":0.02
}
]
},
{
"topic":"netio/${DEVICE_NAME}/output/1/frequency",
"qos":0,
"retain":false,
"payload":"${OUTPUTS/1/FREQUENCY}",
"events":[
{
"type":"timer",
"period":3600
},
{
"type":"delta",
"source":"OUTPUTS/1/FREQUENCY",
"delta":0.1
}
]
}
]
}
}

MQTT-flex

2023-06-06T14:10:56Z

Bbakala: /* Trigger Rule and MQTT publish from MQTT subscribe FW 4.0.0+ */

The MQTT-flex version of the MQTT protocol can be configured in detail thanks to the “flex” extension.

https://www.netio-products.com/en/glossary/mqtt-flex

Why MQTT-flex 
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 [https://en.wikipedia.org/wiki/MQTT 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 [https://en.wikipedia.org/wiki/JSON 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 101x 
* PowerCable REST 101x 
* PowerPDU 4PS 
* PowerPDU 4KS 
* PowerPDU 8QS 
* PowerDIN 4PZ 
* PowerBOX 3Px 
* PowerBOX 4Kx 

FW version: 
>2.2.1

===Not supported NETIO devices:===
* PowerPDU 4C 
* NETIO 4 
* NETIO 4All 

= Simple MQTT-flex configuration + explanation =

''We strongly recommend to create and test MQTT-flex configuration on "local" device what can be easily restarted. The validation of config before saving is not 100% and for example some specific typos can cause a freeze of a device - the solution is to restart a device (unplug/plug input power cable). If the configuration is saved and device is working then there are no known failure case so it is safe to use this configuration on the "remote" devices.''

{
"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":false,
"payload":"${OUTPUTS/1/STATE}",
"events":[
{
"type":"timer",
"period":"1000"
}
]
}
]
}
}
=== Client Configuration (broker section) ===
Put here MQTT client connection setup

This configuration example set NETIO device to connect to broker.hivemq.com with mqtt protocol, no ssl connection with credetials freedom/peace|love|empathy4ALL.

"broker":{
"url":"broker.hivemq.com",
"protocol":"mqtt",
"port":1883,
"ssl":false,
"type":"generic",
"username":"freedom",
"password":"peace|LOVE|empathy4ALL"
},

=== Device Control (subscribe section) ===
Put here array of topics where to subscribe

Device output 1 is controlled with action received by subscription to netio/${DEVICE_NAME}/output/1/action topic with QOS 0

"subscribe":[{
"topic":"netio/${DEVICE_NAME}/output/1/action",
"qos":0,
"target":"OUTPUTS/1/ACTION",
"action":"${payload}"
}
],

=== Output State monitoring (publish section) ===
Put here array of topics where to publish.

Device send every 1000 s message to topic with QOS 0, retain true information with output 1 state

"publish":[{
"topic":"netio/${DEVICE_NAME}/output/1/state",
"qos":0,
"retain":true,
"payload":"${OUTPUTS/1/STATE}",
"events":[
{
"type":"timer",
"period":"1000"
}
]
}
]

= 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 ===
{| class="wikitable"
! style="font-weight:bold; background-color:#9b9b9b;" | Item
! style="font-weight:bold; background-color:#9b9b9b;" | Presence
! style="font-weight:bold; background-color:#9b9b9b;" | Possible Values
! style="font-weight:bold; background-color:#9b9b9b;" | Description
! style="font-weight:bold; background-color:#9b9b9b;" | JSON Config Usage
|-
| style="background-color:#efefef;" | url
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" |
| style="background-color:#efefef;" | MQTT broker URL
| style="background-color:#efefef;" | "url":"broker.hivemq.com"
|-
| style="background-color:#efefef;" | port
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | 1 - 65535
| style="background-color:#efefef;" | MQTT broker port
| style="background-color:#efefef;" | "port":1883
|-
| style="background-color:#efefef;" | protocol
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" |
| style="background-color:#efefef;" | protocol spec - mqtt
| style="background-color:#efefef;" | "protocol": "mqtt"
|-
| style="background-color:#efefef;" | ssl
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | true, false
| style="background-color:#efefef;" | Use SSL crypted communication selector
| style="background-color:#efefef;" | "ssl":false
|-
| style="background-color:#efefef;" | type
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | generic
| style="background-color:#efefef;" | Communication/setup type option
| style="background-color:#efefef;" | "type":"generic"
|-
| style="background-color:#efefef;" | username
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | regexp+len
| style="background-color:#efefef;" | Credentials for MQTT broker. Max. 128 characters (since FW 3.2.4).
| style="background-color:#efefef;" | "username":"freedom"
|-
| style="background-color:#efefef;" | password
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | regexp+len
| style="background-color:#efefef;" | Credentials for MQTT broker. Max. 256 characters (since FW 3.2.4).
| style="background-color:#efefef;" | "password":"peace|LOVE|empathy4ALL"
|-
| style="background-color:#efefef;" | clientid
| style="background-color:#efefef;" | optional
| style="background-color:#efefef;" | regexp+len
| style="background-color:#efefef;" | MQTT clientid. Max. 128 characters (since FW 3.2.4). Variables ${DEVICE_MAC} or ${DEVICE_NAME} can be used
| style="background-color:#efefef;" | "clientid":"myEcoTable01"
|-
| style="background-color:#efefef;" | keepalive
| style="background-color:#efefef;" | optional
| style="background-color:#efefef;" | 1 - 65535
| style="background-color:#efefef;" | MQTT keep alive period in seconds
| style="background-color:#efefef;" | "keepalive":90
|}

Note 1: clientid attribute is mandatory for MQTT(s) communication. When not configured, random ID will be generated.

Note 2: To proper communication with MS Azure - it is necessary to set up IoT Hub to use TLS 1.2

See section "TLS 1.2 enforcement available in select regions" in following guidelines https://docs.microsoft.com/en-us/azure/iot-hub/iot-hub-tls-support

=== Examples ===
==== Standard setup ====

==== Security (SSL / TLS) secured setup ====
You can enable MQTTs by using the encrypted port 8883 + "ssl":true.

==== Variables used setup ====

== 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 ===
{| class="wikitable"
! style="font-weight:bold; background-color:#9b9b9b;" | Item
! style="font-weight:bold; background-color:#9b9b9b;" | Presence
! style="font-weight:bold; background-color:#9b9b9b;" | Possible Values
! style="font-weight:bold; background-color:#9b9b9b;" | Description
! style="font-weight:bold; background-color:#9b9b9b;" | JSON Config Usage
|-
| style="background-color:#efefef;" | topic
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | see table below
| style="background-color:#efefef;" | specification of the topic, which MQTT-flex device listens from broker and act accordingly. Max. 128 characters. The "#" can be used since FW 3.2.4 - see note under this table.
| style="background-color:#efefef;" | "topic":"netio/${DEVICE_NAME}/output/1/action"
|-
| style="background-color:#efefef;" | qos
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | 0, 1 or 2
| style="background-color:#efefef;" | 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}
| style="background-color:#efefef;" | "qos":0
|-
| style="background-color:#efefef;" | target
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" |
| style="background-color:#efefef;" | internal definition of action, which can be performed above the specified output
| style="background-color:#efefef;" | "target":"OUTPUTS/1/ACTION"
|-
| style="background-color:#efefef;" | action
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" |
| style="background-color:#efefef;" | a payload or a value the action attribute needs to have passed to
| style="background-color:#efefef;" | "action":"${payload}"
|-
| style="background-color:#efefef;" | actiondefNot supported yet
| style="background-color:#efefef;" | optional
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
|-
| style="background-color:#efefef;" | jsonNot supported yet
| style="background-color:#efefef;" | optional
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
|}

Note: The "#" wildcard can be used in subscribe topic definition. The multi-level wildcard character MUST be specified either on its own or following a topic level separator. In either case it MUST be the last character specified in the Topic.

For example, if a Device subscribes to “devices/{device_id}/messages/devicebound/#”, it would receive messages published using these topic names:

“devices/{device_id}/messages/devicebound/”

“devices/{device_id}/messages/devicebound/{property_bag}”

This should be usefull for use with MS Azure - IoT hub.

=== MQTT Subscribe as event to trigger action <code>FW 4.0.0+</code> ===

This feature allow to subscribe to specific MQTT topic and pass payload to Rules or MQTT-flex as event.

target: <code>PROTOCOLS/MQTT/EVENT</code>

"subscribe": [
{
"action": "${payload}",
"qos": 0,
"target": "PROTOCOLS/MQTT/EVENT",
"topic": "broker/12345/MQTT_EVENT/"
}
]

=== Examples ===
==== Toggle output with standard payload ====
==== Toggle output with custom payload ====
==== Subscribe to more than one topic ====
==== Trigger Rule and MQTT publish from MQTT subscribe <code>FW 4.0.0+</code> ====
This example show Request response implementation in MQTT and toggle action made by Rules.

When message with payload <code>getValues</code> is published to topic <code>broker/gv90018g/COMMAND</code> MQTT flex will create an event with name <code>PROTOCOLS/MQTT/EVENT</code> (fixed name cannot be changed) and value <code>getValues</code>. On this event will act all events and conditions set in MQTT-flex and Rules which are set to listening to change on <code>PROTOCOLS/MQTT/EVENT</code> and equals to value <code>getValues</code>. See bold marked parameters in example configuration below.

Once the triggered action is done it is needed to reset MQTT channel to <code>OK</code> status becaus event are reacting only to change. If the channel is not reset the next even would not be triggered.

Rules Configuration:
{
"conditions": {
"PROTOCOLS/MQTT/EVENT": "getValues"
},
"actions": {
"OUTPUTS/1/ACTION": 4
}
}

MQTT Configuration:
{
"broker":{
"clientid":"netio${DEVICE_SN}",
"keepalive":30,
"password":"abcdefghijk",
"port":8883,
"protocol":"mqtt",
"ssl":true,
"type":"generic",
"url":"broker.cloud.netio.eu",
"username":"gv90018g"
},
"groupEvents":[
{
"events":[
{
"source":"PROTOCOLS/MQTT/EVENT",
"type":"change",
"value":"getValues"
}
],
"appliedTopics":[
"broker/gv90018g/OUTPUTS/1/STATE",
"broker/gv90018g/COMMAND"
]
}
],
"publish":[
{
"payload":"${OUTPUTS/1/STATE}",
"qos":0,
"retain":true,
"topic":"broker/gv90018g/OUTPUTS/1/STATE"
},
{
"payload":"OK",
"qos":0,
"retain":true,
"topic":"broker/gv90018g/COMMAND"
}
],
"subscribe":[
{
"action":"${payload}",
"qos":0,
"target":"PROTOCOLS/MQTT/EVENT",
"topic":"broker/gv90018g/COMMAND"
}
]
}

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 ===
{| class="wikitable"
! style="font-weight:bold; background-color:#9b9b9b;" | Item
! style="font-weight:bold; background-color:#9b9b9b;" | Presence
! style="font-weight:bold; background-color:#9b9b9b;" | Possible Values
! style="font-weight:bold; background-color:#9b9b9b;" | Description
! style="font-weight:bold; background-color:#9b9b9b;" | JSON Config Usage
|-
| style="background-color:#efefef;" | topic
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | see table below
| style="background-color:#efefef;" | definition of the topic, how it is registered towards MQTT broker. Max. 128 characters.
| style="background-color:#efefef;" | "topic":"netio/${DEVICE_NAME}/output/1/load"
|-
| style="background-color:#efefef;" | qos
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | see table below
| style="background-color:#efefef;" | 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}
| style="background-color:#efefef;" |
|-
| style="background-color:#efefef;" | retain
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | boolean: true or false
| style="background-color:#efefef;" | 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}
| style="background-color:#efefef;" | "retain":true
|-
| style="background-color:#efefef;" | payload
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | see table below
| style="background-color:#efefef;" | definition of the payload, what is send to the MQTT broker.
| style="background-color:#efefef;" | "payload":"${OUTPUTS/1/STATE}"
|-
| style="background-color:#efefef;" | events
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | see table below
| style="background-color:#efefef;" | definition of events used for triggering sending of data via mqtt (change, delta, timer)
| style="background-color:#efefef;" |
|-
| style="background-color:#efefef;" | type
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
|-
| style="background-color:#efefef;" | source
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
|-
| style="background-color:#efefef;" | delta
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
|-
| style="background-color:#efefef;" | period
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
|-
| style="background-color:#efefef;" | payloaddefNot supported yet
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
|}

=== Examples ===
==== Publish energy periodically (event timer) ====
==== Publish current on change (delta) ====
==== Publish output state ====
==== Publish to more than one topic with different events ====

= 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 available only on NETIO PowerDIN 4PZ

=== Examples: ===

adressing controll of output 3
OUTPUTS/3/ACTION
getting voltage on output 1
OUTPUTS/1/VOLTAGE
getting state of input 1
INPUTS/1/STATE

= Events =
==== Timer ====

==== Delta ====

==== Change ====

==== Group Events<code>FW 4.0.0+</code>====

= 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 ===
==== VOLTAGE ====
Unit: <code>V</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Present RMS voltage on output 1 is ${OUTPUTS/1/VOLTAGE}"</code>

Example 2: <code>"source":"${OUTPUTS/1/VOLTAGE}"</code>

==== CURRENT ====
Unit: <code>mA</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Present RMS current on output 1 is ${OUTPUTS/1/CURRENT}"</code>

Example 2: <code>"source":"${OUTPUTS/1/CURRENT}"</code>

==== POWER_FACTOR ====
Unit: <code>[-]</code>

Type: float (2 decimals)

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"True Power Factor on output 1 is ${OUTPUTS/1/POWER_FACTOR}"</code>

Example 2: <code>"source":"${OUTPUTS/1/POWER_FACTOR}"</code>

==== LOAD ====
Unit: <code>W</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Present load on output 1 is ${OUTPUTS/1/LOAD}W"</code>

Example 2: <code>"payload":"Device's load connected to output 1 is ${OUTPUTS/1/LOAD}W"</code>

Example 3: <code>"source":"${OUTPUTS/1/LOAD}"</code>

==== STATE ====
Type: bool(integer) - <code>0</code> or <code>1</code>

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Present output 1 state is ${OUTPUTS/1/STATE}"</code>

Example 2: <code>"source":"${OUTPUTS/1/STATE}"</code>

==== ACTION ====
Type: integer

Possible actions:
* <code>0</code> - set state OFF
* <code>1</code> - set state ON
* <code>2</code> - short OFF (restart)
* <code>3</code> - short ON
* <code>4</code> - toggle (switch)
* <code>5</code> - no change

Allowed in: <code>"target"</code>

Example: <code>"target":"OUTPUTS/1/ACTION"</code>

==== DELAY [ms] ====
==== NAME ====
==== FREQUENCY ====
Unit: <code>Hz</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example: <code>"payload":"Frequency in power grid is ${OUTPUTS/1/ENERGY}Hz"</code>

==== ENERGY ====
Energy consumed by an device connected to NETIO device output.

Unit: <code>Wh</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Consumed energy on output 1 is ${OUTPUTS/1/ENERGY}Wh"</code>

Example 2: <code>"source":"${OUTPUTS/1/ENERGY}"</code>

==== REVERSE_ENERGY ====
Energy delivered back to grid. For example from solar system connected to NETIO device output.

Unit: <code>Wh</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Delivered energy on output 1 is ${OUTPUTS/1/REVERSE_ENERGY}Wh"</code>

Example 2: <code>"source":"${OUTPUTS/1/REVERSE_ENERGY}"</code>

==== ENERGY_START ====
Date when the counters ENERGY and REVERSE_ENERGY have been resetted by user.

Unit: <code>unix timestamp</code>

Type: integer

Allowed in: <code>"payload"</code>

Example 1: <code>"payload":"Energy measured since ${OUTPUTS/1/ENERGY_START} unix time"</code>

Example 2: <code>"payload":"${OUTPUTS/1/ENERGY_START}"</code> is output payload <code>1567654639</code>

==== ENERGY_START_FMT ====
Date when the counters ENERGY and REVERSE_ENERGY have been resetted by user.

Unit: <code>fmt date format</code>

Type: string

Allowed in: <code>"payload"</code>

Example 1: <code>"payload":"Energy measured since ${OUTPUTS/1/ENERGY_START}"</code>

Example 2: <code>"payload":"${OUTPUTS/1/ENERGY_START_FMT}"</code> is output payload <code>2019-09-05T03:37:19+00:00</code>

==== ENERGY_NR ====
Non-resettable counter of Energy consumed by an device connected to NETIO device output.

Unit: <code>Wh</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Consumed energy on output 1 is ${OUTPUTS/1/ENERGY_NR}Wh"</code>

Example 2: <code>"source":"${OUTPUTS/1/ENERGY_NR}"</code>

==== REVERSE_ENERGY_NR ====
Non-resettable counter of Energy delivered back to grid. For example from solar system connected to NETIO device output.

Unit: <code>Wh</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Delivered energy on output 1 is ${OUTPUTS/1/REVERSE_ENERGY_NR}Wh"</code>

Example 2: <code>"source":"${OUTPUTS/1/REVERSE_ENERGY_NR}"</code>

==== TOTALs - for 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
* OUTPUTS/TOTAL/PHASE
* OUTPUTS/TOTAL/REVERSE_ENERGY
* OUTPUTS/TOTAL/ENERGY_NR
* OUTPUTS/TOTAL/REVERSE_ENERGY_NR
* OUTPUTS/TOTAL/ENERGY_START
* OUTPUTS/TOTAL/ENERGY_START_FMT

==== REST_JSON ====
Allow use of NETIO JSON structure to control outputs.

Type: string / JSON

Allowed in: <code>"target"</code> for Subscribe section

Example: <code>"target": "REST_JSON"</code>

The payload is JSON structure identical to NETIO JSON API M2M Protocol (documentation available at https://www.netio-products.com/files/NETIO-M2M-API-Protocol-JSON.pdf). You can control one or multiple outputs.

Payload example 1 - Toggle output 1: <code>{"Outputs":[{"ID": 1,"Action": 4}]}</code>

Payload example 2 - Turn output 1 OFF and output 3 ON: <code>{"Outputs":[{"ID":1,"Action":0},{"ID":3,"Action":1}]}</code>

=== INPUT variables ===
==== STATE ====
Type: bool(integer) - <code>0</code> or <code>1</code>

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Present input 1 state is ${INPUTS/1/STATE}"</code>

Example 2: <code>"source":"${INPUTS/1/STATE}"</code>

==== S0 ====
S0 Counter value
Unit: <code>-</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Input 1 S0 Counter value is ${INPUTS/1/S0}impulses"</code>

Example 2: <code>"source":"${INPUTS/1/S0}"</code>

== Payload/topic variables ==

=== DEVICE_NAME ===
Can be used in: "payload", "topic"

Example 1: <code>"payload":"${DEVICE_NAME}"</code>

Example 2: <code>"topic":"netio/${DEVICE_NAME}/output/1/action"</code>

=== DEVICE_MAC ===

=== UPTIME Not yet implemented ===

=== PAYLOAD ===
Can be used in: "action"

Example: <code>"action":"${PAYLOAD}"</code>

=== OUTPUT_ID Not yet implemented===

=== WIFI_SIGNALNot yet implemented ===

=== OUTPUTS_STATUS ===
Provide complete outputs status and measurement if supported.

Type: string / JSON

Allowed in: <code>"payload"</code> for Publish section

Example: <code>"payload":"${OUTPUTS_STATUS}"</code>

Payload example: <code>{ "GlobalMeasure":{"Voltage":236,"TotalCurrent":72,"TotalLoad":11,"TotalEnergy":167,"OverallPowerFactor":0.64,"Frequency":50.07,"Phase":-36.86,"EnergyStart":"2020-06-30T17:04:48+01:00"}, "Outputs":[ {"ID":1,"Name":"Power output 1","State":1,"Action":6,"Delay":2020,"Current":72,"PowerFactor":0.64,"Phase":-36.86,"Energy":139,"ReverseEnergy":0,"Load":11}, {"ID":2,"Name":"Power output 2","State":1,"Action":6,"Delay":2020,"Current":0,"PowerFactor":1.00,"Phase":0.00,"Energy":27,"ReverseEnergy":0,"Load":0}, {"ID":3,"Name":"Free Contact 3","State":1,"Action":6,"Delay":2020}, {"ID":4,"Name":"Free Contact 4","State":1,"Action":6,"Delay":2020} ]}</code>

=== INPUTS_STATUS ===
Provide complete inputs status if supported. Since FW 3.0.0

Type: string / JSON

Allowed in: <code>"payload"</code> for Publish section

Example: <code>"payload":"${INPUTS_STATUS}"</code>

Payload example: <code>{ "Inputs":[ {"ID":1,"Name":"Input 1","State":0,"S0Counter":0}, {"ID":2,"Name":"Input 2","State":0,"S0Counter":0} ]}</code>

=== INOUT_STATUS ===
Provide complete inputs and output status and measurement if supported. Since FW 3.0.0

Type: string / JSON

Allowed in: <code>"payload"</code> for Publish section

Example: <code>"payload":"${INOUT_STATUS}"</code>

Payload example: <code>{ "GlobalMeasure":{"Voltage":238,"TotalCurrent":105,"TotalLoad":17,"TotalEnergy":1451,"OverallPowerFactor":0.67,"Frequency":50.03,"Phase":-33.67,"EnergyStart":"2020-06-30T17:04:48+01:00"}, "Outputs":[ {"ID":1,"Name":"Power output 1","State":0,"Action":6,"Delay":5000,"Current":0,"PowerFactor":1.00,"Phase":0.00,"Energy":701,"ReverseEnergy":0,"Load":0}, {"ID":2,"Name":"Power output 2","State":1,"Action":6,"Delay":5000,"Current":105,"PowerFactor":0.65,"Phase":-33.67,"Energy":750,"ReverseEnergy":0,"Load":17}, {"ID":3,"Name":"Free Contact 3","State":1,"Action":6,"Delay":5000}, {"ID":4,"Name":"Free Contact 4","State":0,"Action":6,"Delay":5000} ], "Inputs":[ {"ID":1,"Name":"Input 1","State":0,"S0Counter":0}, {"ID":2,"Name":"Input 2","State":0,"S0Counter":0} ]}</code>

= Extended MQTT flex JSON config examples =

== Default NETIO MQTT-flex configuration ==
This example demonstrates setup for connection to public <code>broker.hivemq.com</code>, measurement reporting and output control.

The device cabe be controlled via <code>netio/${DEVICE_NAME}/output/1/action topic</code> by sending standard NETIO action values:
* 0 - OFF
* 1 - ON
* 2 - SHORT OFF
* 3 - SHORT ON
* 4 - TOGGLE
* 5 - NO ACTION.

The device report measurements:

* Output state - every 15 minutes or by change
* Voltage [V]- every 5 minutes or by change of 1 V
* Current [mA]- every 5 minutes or by change of 50 mA
* Load(Power) [W]- every 5 minutes or by change of 10 W
* Energy(Consumption) [Wh]- every 15 minutes or by change of 1Wh
* True Power Factor (TPF) [-]- every 5 minutes or by change of 0.02
* Frequency [Hz]- every 1 hour or by change of 0.1 Hz

For register all values, you can use wildcard <code>netio/${DEVICE_NAME}/output/1/#</code>

{
"config":{
"broker":{
"url":"broker.hivemq.com",
"protocol":"mqtt",
"port":1883,
"ssl":false,
"type":"generic",
"username":"",
"password":"",
"clientid":"moje${DEVICE_NAME}${DEVICE_MAC}",
"keepalive":30
},
"subscribe":[
{
"topic":"netio/${DEVICE_NAME}/output/1/action",
"qos":0,
"target":"OUTPUTS/1/ACTION",
"action":"${payload}"
},
{
"topic":"netio/${DEVICE_NAME}/output/1/switch",
"qos":0,
"target":"OUTPUTS/1/ACTION",
"action":4
}
],
"publish":[
{
"topic":"netio/${DEVICE_MAC}/output/1/state",
"qos":0,
"retain":true,
"payload":"${OUTPUTS/1/STATE}",
"events":[
{
"type":"change",
"source":"OUTPUTS/1/STATE"
},
{
"type":"timer",
"period":900
}
]
},
{
"topic":"netio/${DEVICE_NAME}/output/1/voltage",
"qos":0,
"retain":false,
"payload":"${OUTPUTS/1/VOLTAGE}",
"events":[
{
"type":"timer",
"period":300
},
{
"type":"delta",
"source":"OUTPUTS/1/VOLTAGE",
"delta":1
}
]
},
{
"topic":"netio/${DEVICE_NAME}/output/1/current",
"qos":0,
"retain":false,
"payload":"${OUTPUTS/1/CURRENT}",
"events":[
{
"type":"timer",
"period":300
},
{
"type":"delta",
"source":"OUTPUTS/1/CURRENT",
"delta":50
}
]
},
{
"topic":"netio/${DEVICE_NAME}/output/1/load",
"qos":0,
"retain":false,
"payload":"${OUTPUTS/1/LOAD}",
"events":[
{
"type":"timer",
"period":300
},
{
"type":"delta",
"source":"OUTPUTS/1/LOAD",
"delta":10
}
]
},
{
"topic":"netio/${DEVICE_NAME}/output/1/energy",
"qos":0,
"retain":false,
"payload":"${OUTPUTS/1/ENERGY}",
"events":[
{
"type":"timer",
"period":900
},
{
"type":"delta",
"source":"OUTPUTS/1/ENERGY",
"delta":1
}
]
},
{
"topic":"netio/${DEVICE_NAME}/output/1/tpf",
"qos":0,
"retain":false,
"payload":"${OUTPUTS/1/POWER_FACTOR}",
"events":[
{
"type":"timer",
"period":900
},
{
"type":"delta",
"source":"OUTPUTS/1/POWER_FACTOR",
"delta":0.02
}
]
},
{
"topic":"netio/${DEVICE_NAME}/output/1/frequency",
"qos":0,
"retain":false,
"payload":"${OUTPUTS/1/FREQUENCY}",
"events":[
{
"type":"timer",
"period":3600
},
{
"type":"delta",
"source":"OUTPUTS/1/FREQUENCY",
"delta":0.1
}
]
}
]
}
}

MQTT-flex

2023-06-06T14:10:01Z

Bbakala: /* Trigger MQTT publish by MQTT subscribe FW 4.0.0+ */

The MQTT-flex version of the MQTT protocol can be configured in detail thanks to the “flex” extension.

https://www.netio-products.com/en/glossary/mqtt-flex

Why MQTT-flex 
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 [https://en.wikipedia.org/wiki/MQTT 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 [https://en.wikipedia.org/wiki/JSON 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 101x 
* PowerCable REST 101x 
* PowerPDU 4PS 
* PowerPDU 4KS 
* PowerPDU 8QS 
* PowerDIN 4PZ 
* PowerBOX 3Px 
* PowerBOX 4Kx 

FW version: 
>2.2.1

===Not supported NETIO devices:===
* PowerPDU 4C 
* NETIO 4 
* NETIO 4All 

= Simple MQTT-flex configuration + explanation =

''We strongly recommend to create and test MQTT-flex configuration on "local" device what can be easily restarted. The validation of config before saving is not 100% and for example some specific typos can cause a freeze of a device - the solution is to restart a device (unplug/plug input power cable). If the configuration is saved and device is working then there are no known failure case so it is safe to use this configuration on the "remote" devices.''

{
"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":false,
"payload":"${OUTPUTS/1/STATE}",
"events":[
{
"type":"timer",
"period":"1000"
}
]
}
]
}
}
=== Client Configuration (broker section) ===
Put here MQTT client connection setup

This configuration example set NETIO device to connect to broker.hivemq.com with mqtt protocol, no ssl connection with credetials freedom/peace|love|empathy4ALL.

"broker":{
"url":"broker.hivemq.com",
"protocol":"mqtt",
"port":1883,
"ssl":false,
"type":"generic",
"username":"freedom",
"password":"peace|LOVE|empathy4ALL"
},

=== Device Control (subscribe section) ===
Put here array of topics where to subscribe

Device output 1 is controlled with action received by subscription to netio/${DEVICE_NAME}/output/1/action topic with QOS 0

"subscribe":[{
"topic":"netio/${DEVICE_NAME}/output/1/action",
"qos":0,
"target":"OUTPUTS/1/ACTION",
"action":"${payload}"
}
],

=== Output State monitoring (publish section) ===
Put here array of topics where to publish.

Device send every 1000 s message to topic with QOS 0, retain true information with output 1 state

"publish":[{
"topic":"netio/${DEVICE_NAME}/output/1/state",
"qos":0,
"retain":true,
"payload":"${OUTPUTS/1/STATE}",
"events":[
{
"type":"timer",
"period":"1000"
}
]
}
]

= 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 ===
{| class="wikitable"
! style="font-weight:bold; background-color:#9b9b9b;" | Item
! style="font-weight:bold; background-color:#9b9b9b;" | Presence
! style="font-weight:bold; background-color:#9b9b9b;" | Possible Values
! style="font-weight:bold; background-color:#9b9b9b;" | Description
! style="font-weight:bold; background-color:#9b9b9b;" | JSON Config Usage
|-
| style="background-color:#efefef;" | url
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" |
| style="background-color:#efefef;" | MQTT broker URL
| style="background-color:#efefef;" | "url":"broker.hivemq.com"
|-
| style="background-color:#efefef;" | port
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | 1 - 65535
| style="background-color:#efefef;" | MQTT broker port
| style="background-color:#efefef;" | "port":1883
|-
| style="background-color:#efefef;" | protocol
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" |
| style="background-color:#efefef;" | protocol spec - mqtt
| style="background-color:#efefef;" | "protocol": "mqtt"
|-
| style="background-color:#efefef;" | ssl
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | true, false
| style="background-color:#efefef;" | Use SSL crypted communication selector
| style="background-color:#efefef;" | "ssl":false
|-
| style="background-color:#efefef;" | type
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | generic
| style="background-color:#efefef;" | Communication/setup type option
| style="background-color:#efefef;" | "type":"generic"
|-
| style="background-color:#efefef;" | username
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | regexp+len
| style="background-color:#efefef;" | Credentials for MQTT broker. Max. 128 characters (since FW 3.2.4).
| style="background-color:#efefef;" | "username":"freedom"
|-
| style="background-color:#efefef;" | password
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | regexp+len
| style="background-color:#efefef;" | Credentials for MQTT broker. Max. 256 characters (since FW 3.2.4).
| style="background-color:#efefef;" | "password":"peace|LOVE|empathy4ALL"
|-
| style="background-color:#efefef;" | clientid
| style="background-color:#efefef;" | optional
| style="background-color:#efefef;" | regexp+len
| style="background-color:#efefef;" | MQTT clientid. Max. 128 characters (since FW 3.2.4). Variables ${DEVICE_MAC} or ${DEVICE_NAME} can be used
| style="background-color:#efefef;" | "clientid":"myEcoTable01"
|-
| style="background-color:#efefef;" | keepalive
| style="background-color:#efefef;" | optional
| style="background-color:#efefef;" | 1 - 65535
| style="background-color:#efefef;" | MQTT keep alive period in seconds
| style="background-color:#efefef;" | "keepalive":90
|}

Note 1: clientid attribute is mandatory for MQTT(s) communication. When not configured, random ID will be generated.

Note 2: To proper communication with MS Azure - it is necessary to set up IoT Hub to use TLS 1.2

See section "TLS 1.2 enforcement available in select regions" in following guidelines https://docs.microsoft.com/en-us/azure/iot-hub/iot-hub-tls-support

=== Examples ===
==== Standard setup ====

==== Security (SSL / TLS) secured setup ====
You can enable MQTTs by using the encrypted port 8883 + "ssl":true.

==== Variables used setup ====

== 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 ===
{| class="wikitable"
! style="font-weight:bold; background-color:#9b9b9b;" | Item
! style="font-weight:bold; background-color:#9b9b9b;" | Presence
! style="font-weight:bold; background-color:#9b9b9b;" | Possible Values
! style="font-weight:bold; background-color:#9b9b9b;" | Description
! style="font-weight:bold; background-color:#9b9b9b;" | JSON Config Usage
|-
| style="background-color:#efefef;" | topic
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | see table below
| style="background-color:#efefef;" | specification of the topic, which MQTT-flex device listens from broker and act accordingly. Max. 128 characters. The "#" can be used since FW 3.2.4 - see note under this table.
| style="background-color:#efefef;" | "topic":"netio/${DEVICE_NAME}/output/1/action"
|-
| style="background-color:#efefef;" | qos
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | 0, 1 or 2
| style="background-color:#efefef;" | 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}
| style="background-color:#efefef;" | "qos":0
|-
| style="background-color:#efefef;" | target
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" |
| style="background-color:#efefef;" | internal definition of action, which can be performed above the specified output
| style="background-color:#efefef;" | "target":"OUTPUTS/1/ACTION"
|-
| style="background-color:#efefef;" | action
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" |
| style="background-color:#efefef;" | a payload or a value the action attribute needs to have passed to
| style="background-color:#efefef;" | "action":"${payload}"
|-
| style="background-color:#efefef;" | actiondefNot supported yet
| style="background-color:#efefef;" | optional
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
|-
| style="background-color:#efefef;" | jsonNot supported yet
| style="background-color:#efefef;" | optional
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
|}

Note: The "#" wildcard can be used in subscribe topic definition. The multi-level wildcard character MUST be specified either on its own or following a topic level separator. In either case it MUST be the last character specified in the Topic.

For example, if a Device subscribes to “devices/{device_id}/messages/devicebound/#”, it would receive messages published using these topic names:

“devices/{device_id}/messages/devicebound/”

“devices/{device_id}/messages/devicebound/{property_bag}”

This should be usefull for use with MS Azure - IoT hub.

=== MQTT Subscribe as event to trigger action <code>FW 4.0.0+</code> ===

This feature allow to subscribe to specific MQTT topic and pass payload to Rules or MQTT-flex as event.

target: <code>PROTOCOLS/MQTT/EVENT</code>

"subscribe": [
{
"action": "${payload}",
"qos": 0,
"target": "PROTOCOLS/MQTT/EVENT",
"topic": "broker/12345/MQTT_EVENT/"
}
]

=== Examples ===
==== Toggle output with standard payload ====
==== Toggle output with custom payload ====
==== Subscribe to more than one topic ====
==== Trigger Rule and MQTT publish from MQTT subscribe <code>FW 4.0.0+</code> ====
This example show Request response implementation in MQTT and toggle action made by Rules.

When message with payload <code>getValues</code> is published to topic <code>broker/gv90018g/COMMAND</code> MQTT flex will create an event with name <code>PROTOCOLS/MQTT/EVENT</code> (fixed name cannot be changed) and value <code>getValues</code>. On this event will act all events and conditions set in MQTT-flex and Rules which are set to listening to change on <code>PROTOCOLS/MQTT/EVENT</code> and equals to value <code>getValues</code>. See bold marked parameters in example configuration below.

Once the triggered action is done it is needed to reset MQTT channel to <code>OK</code> status becaus event are reacting only to change. If the channel is not reset the next even would not be triggered.

Rules Configuration:
{
"conditions": {
"PROTOCOLS/MQTT/EVENT": "getValues"
},
"actions": {
"OUTPUTS/1/ACTION": 4
}
}

MQTT Configuration:
{
"broker":{
"clientid":"netio${DEVICE_SN}",
"keepalive":30,
"password":"goad7jbh326pr2ne",
"port":8883,
"protocol":"mqtt",
"ssl":true,
"type":"generic",
"url":"broker.cloud-dev.netio.eu",
"username":"gv90018g"
},
"groupEvents":[
{
"events":[
{
"source":"PROTOCOLS/MQTT/EVENT",
"type":"change",
"value":"getValues"
}
],
"appliedTopics":[
"broker/gv90018g/OUTPUTS/1/STATE",
"broker/gv90018g/COMMAND"
]
}
],
"publish":[
{
"payload":"${OUTPUTS/1/STATE}",
"qos":0,
"retain":true,
"topic":"broker/gv90018g/OUTPUTS/1/STATE"
},
{
"payload":"OK",
"qos":0,
"retain":true,
"topic":"broker/gv90018g/COMMAND"
}
],
"subscribe":[
{
"action":"${payload}",
"qos":0,
"target":"PROTOCOLS/MQTT/EVENT",
"topic":"broker/gv90018g/COMMAND"
}
]
}

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 ===
{| class="wikitable"
! style="font-weight:bold; background-color:#9b9b9b;" | Item
! style="font-weight:bold; background-color:#9b9b9b;" | Presence
! style="font-weight:bold; background-color:#9b9b9b;" | Possible Values
! style="font-weight:bold; background-color:#9b9b9b;" | Description
! style="font-weight:bold; background-color:#9b9b9b;" | JSON Config Usage
|-
| style="background-color:#efefef;" | topic
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | see table below
| style="background-color:#efefef;" | definition of the topic, how it is registered towards MQTT broker. Max. 128 characters.
| style="background-color:#efefef;" | "topic":"netio/${DEVICE_NAME}/output/1/load"
|-
| style="background-color:#efefef;" | qos
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | see table below
| style="background-color:#efefef;" | 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}
| style="background-color:#efefef;" |
|-
| style="background-color:#efefef;" | retain
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | boolean: true or false
| style="background-color:#efefef;" | 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}
| style="background-color:#efefef;" | "retain":true
|-
| style="background-color:#efefef;" | payload
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | see table below
| style="background-color:#efefef;" | definition of the payload, what is send to the MQTT broker.
| style="background-color:#efefef;" | "payload":"${OUTPUTS/1/STATE}"
|-
| style="background-color:#efefef;" | events
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | see table below
| style="background-color:#efefef;" | definition of events used for triggering sending of data via mqtt (change, delta, timer)
| style="background-color:#efefef;" |
|-
| style="background-color:#efefef;" | type
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
|-
| style="background-color:#efefef;" | source
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
|-
| style="background-color:#efefef;" | delta
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
|-
| style="background-color:#efefef;" | period
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
|-
| style="background-color:#efefef;" | payloaddefNot supported yet
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
|}

=== Examples ===
==== Publish energy periodically (event timer) ====
==== Publish current on change (delta) ====
==== Publish output state ====
==== Publish to more than one topic with different events ====

= 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 available only on NETIO PowerDIN 4PZ

=== Examples: ===

adressing controll of output 3
OUTPUTS/3/ACTION
getting voltage on output 1
OUTPUTS/1/VOLTAGE
getting state of input 1
INPUTS/1/STATE

= Events =
==== Timer ====

==== Delta ====

==== Change ====

==== Group Events<code>FW 4.0.0+</code>====

= 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 ===
==== VOLTAGE ====
Unit: <code>V</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Present RMS voltage on output 1 is ${OUTPUTS/1/VOLTAGE}"</code>

Example 2: <code>"source":"${OUTPUTS/1/VOLTAGE}"</code>

==== CURRENT ====
Unit: <code>mA</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Present RMS current on output 1 is ${OUTPUTS/1/CURRENT}"</code>

Example 2: <code>"source":"${OUTPUTS/1/CURRENT}"</code>

==== POWER_FACTOR ====
Unit: <code>[-]</code>

Type: float (2 decimals)

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"True Power Factor on output 1 is ${OUTPUTS/1/POWER_FACTOR}"</code>

Example 2: <code>"source":"${OUTPUTS/1/POWER_FACTOR}"</code>

==== LOAD ====
Unit: <code>W</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Present load on output 1 is ${OUTPUTS/1/LOAD}W"</code>

Example 2: <code>"payload":"Device's load connected to output 1 is ${OUTPUTS/1/LOAD}W"</code>

Example 3: <code>"source":"${OUTPUTS/1/LOAD}"</code>

==== STATE ====
Type: bool(integer) - <code>0</code> or <code>1</code>

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Present output 1 state is ${OUTPUTS/1/STATE}"</code>

Example 2: <code>"source":"${OUTPUTS/1/STATE}"</code>

==== ACTION ====
Type: integer

Possible actions:
* <code>0</code> - set state OFF
* <code>1</code> - set state ON
* <code>2</code> - short OFF (restart)
* <code>3</code> - short ON
* <code>4</code> - toggle (switch)
* <code>5</code> - no change

Allowed in: <code>"target"</code>

Example: <code>"target":"OUTPUTS/1/ACTION"</code>

==== DELAY [ms] ====
==== NAME ====
==== FREQUENCY ====
Unit: <code>Hz</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example: <code>"payload":"Frequency in power grid is ${OUTPUTS/1/ENERGY}Hz"</code>

==== ENERGY ====
Energy consumed by an device connected to NETIO device output.

Unit: <code>Wh</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Consumed energy on output 1 is ${OUTPUTS/1/ENERGY}Wh"</code>

Example 2: <code>"source":"${OUTPUTS/1/ENERGY}"</code>

==== REVERSE_ENERGY ====
Energy delivered back to grid. For example from solar system connected to NETIO device output.

Unit: <code>Wh</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Delivered energy on output 1 is ${OUTPUTS/1/REVERSE_ENERGY}Wh"</code>

Example 2: <code>"source":"${OUTPUTS/1/REVERSE_ENERGY}"</code>

==== ENERGY_START ====
Date when the counters ENERGY and REVERSE_ENERGY have been resetted by user.

Unit: <code>unix timestamp</code>

Type: integer

Allowed in: <code>"payload"</code>

Example 1: <code>"payload":"Energy measured since ${OUTPUTS/1/ENERGY_START} unix time"</code>

Example 2: <code>"payload":"${OUTPUTS/1/ENERGY_START}"</code> is output payload <code>1567654639</code>

==== ENERGY_START_FMT ====
Date when the counters ENERGY and REVERSE_ENERGY have been resetted by user.

Unit: <code>fmt date format</code>

Type: string

Allowed in: <code>"payload"</code>

Example 1: <code>"payload":"Energy measured since ${OUTPUTS/1/ENERGY_START}"</code>

Example 2: <code>"payload":"${OUTPUTS/1/ENERGY_START_FMT}"</code> is output payload <code>2019-09-05T03:37:19+00:00</code>

==== ENERGY_NR ====
Non-resettable counter of Energy consumed by an device connected to NETIO device output.

Unit: <code>Wh</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Consumed energy on output 1 is ${OUTPUTS/1/ENERGY_NR}Wh"</code>

Example 2: <code>"source":"${OUTPUTS/1/ENERGY_NR}"</code>

==== REVERSE_ENERGY_NR ====
Non-resettable counter of Energy delivered back to grid. For example from solar system connected to NETIO device output.

Unit: <code>Wh</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Delivered energy on output 1 is ${OUTPUTS/1/REVERSE_ENERGY_NR}Wh"</code>

Example 2: <code>"source":"${OUTPUTS/1/REVERSE_ENERGY_NR}"</code>

==== TOTALs - for 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
* OUTPUTS/TOTAL/PHASE
* OUTPUTS/TOTAL/REVERSE_ENERGY
* OUTPUTS/TOTAL/ENERGY_NR
* OUTPUTS/TOTAL/REVERSE_ENERGY_NR
* OUTPUTS/TOTAL/ENERGY_START
* OUTPUTS/TOTAL/ENERGY_START_FMT

==== REST_JSON ====
Allow use of NETIO JSON structure to control outputs.

Type: string / JSON

Allowed in: <code>"target"</code> for Subscribe section

Example: <code>"target": "REST_JSON"</code>

The payload is JSON structure identical to NETIO JSON API M2M Protocol (documentation available at https://www.netio-products.com/files/NETIO-M2M-API-Protocol-JSON.pdf). You can control one or multiple outputs.

Payload example 1 - Toggle output 1: <code>{"Outputs":[{"ID": 1,"Action": 4}]}</code>

Payload example 2 - Turn output 1 OFF and output 3 ON: <code>{"Outputs":[{"ID":1,"Action":0},{"ID":3,"Action":1}]}</code>

=== INPUT variables ===
==== STATE ====
Type: bool(integer) - <code>0</code> or <code>1</code>

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Present input 1 state is ${INPUTS/1/STATE}"</code>

Example 2: <code>"source":"${INPUTS/1/STATE}"</code>

==== S0 ====
S0 Counter value
Unit: <code>-</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Input 1 S0 Counter value is ${INPUTS/1/S0}impulses"</code>

Example 2: <code>"source":"${INPUTS/1/S0}"</code>

== Payload/topic variables ==

=== DEVICE_NAME ===
Can be used in: "payload", "topic"

Example 1: <code>"payload":"${DEVICE_NAME}"</code>

Example 2: <code>"topic":"netio/${DEVICE_NAME}/output/1/action"</code>

=== DEVICE_MAC ===

=== UPTIME Not yet implemented ===

=== PAYLOAD ===
Can be used in: "action"

Example: <code>"action":"${PAYLOAD}"</code>

=== OUTPUT_ID Not yet implemented===

=== WIFI_SIGNALNot yet implemented ===

=== OUTPUTS_STATUS ===
Provide complete outputs status and measurement if supported.

Type: string / JSON

Allowed in: <code>"payload"</code> for Publish section

Example: <code>"payload":"${OUTPUTS_STATUS}"</code>

Payload example: <code>{ "GlobalMeasure":{"Voltage":236,"TotalCurrent":72,"TotalLoad":11,"TotalEnergy":167,"OverallPowerFactor":0.64,"Frequency":50.07,"Phase":-36.86,"EnergyStart":"2020-06-30T17:04:48+01:00"}, "Outputs":[ {"ID":1,"Name":"Power output 1","State":1,"Action":6,"Delay":2020,"Current":72,"PowerFactor":0.64,"Phase":-36.86,"Energy":139,"ReverseEnergy":0,"Load":11}, {"ID":2,"Name":"Power output 2","State":1,"Action":6,"Delay":2020,"Current":0,"PowerFactor":1.00,"Phase":0.00,"Energy":27,"ReverseEnergy":0,"Load":0}, {"ID":3,"Name":"Free Contact 3","State":1,"Action":6,"Delay":2020}, {"ID":4,"Name":"Free Contact 4","State":1,"Action":6,"Delay":2020} ]}</code>

=== INPUTS_STATUS ===
Provide complete inputs status if supported. Since FW 3.0.0

Type: string / JSON

Allowed in: <code>"payload"</code> for Publish section

Example: <code>"payload":"${INPUTS_STATUS}"</code>

Payload example: <code>{ "Inputs":[ {"ID":1,"Name":"Input 1","State":0,"S0Counter":0}, {"ID":2,"Name":"Input 2","State":0,"S0Counter":0} ]}</code>

=== INOUT_STATUS ===
Provide complete inputs and output status and measurement if supported. Since FW 3.0.0

Type: string / JSON

Allowed in: <code>"payload"</code> for Publish section

Example: <code>"payload":"${INOUT_STATUS}"</code>

Payload example: <code>{ "GlobalMeasure":{"Voltage":238,"TotalCurrent":105,"TotalLoad":17,"TotalEnergy":1451,"OverallPowerFactor":0.67,"Frequency":50.03,"Phase":-33.67,"EnergyStart":"2020-06-30T17:04:48+01:00"}, "Outputs":[ {"ID":1,"Name":"Power output 1","State":0,"Action":6,"Delay":5000,"Current":0,"PowerFactor":1.00,"Phase":0.00,"Energy":701,"ReverseEnergy":0,"Load":0}, {"ID":2,"Name":"Power output 2","State":1,"Action":6,"Delay":5000,"Current":105,"PowerFactor":0.65,"Phase":-33.67,"Energy":750,"ReverseEnergy":0,"Load":17}, {"ID":3,"Name":"Free Contact 3","State":1,"Action":6,"Delay":5000}, {"ID":4,"Name":"Free Contact 4","State":0,"Action":6,"Delay":5000} ], "Inputs":[ {"ID":1,"Name":"Input 1","State":0,"S0Counter":0}, {"ID":2,"Name":"Input 2","State":0,"S0Counter":0} ]}</code>

= Extended MQTT flex JSON config examples =

== Default NETIO MQTT-flex configuration ==
This example demonstrates setup for connection to public <code>broker.hivemq.com</code>, measurement reporting and output control.

The device cabe be controlled via <code>netio/${DEVICE_NAME}/output/1/action topic</code> by sending standard NETIO action values:
* 0 - OFF
* 1 - ON
* 2 - SHORT OFF
* 3 - SHORT ON
* 4 - TOGGLE
* 5 - NO ACTION.

The device report measurements:

* Output state - every 15 minutes or by change
* Voltage [V]- every 5 minutes or by change of 1 V
* Current [mA]- every 5 minutes or by change of 50 mA
* Load(Power) [W]- every 5 minutes or by change of 10 W
* Energy(Consumption) [Wh]- every 15 minutes or by change of 1Wh
* True Power Factor (TPF) [-]- every 5 minutes or by change of 0.02
* Frequency [Hz]- every 1 hour or by change of 0.1 Hz

For register all values, you can use wildcard <code>netio/${DEVICE_NAME}/output/1/#</code>

{
"config":{
"broker":{
"url":"broker.hivemq.com",
"protocol":"mqtt",
"port":1883,
"ssl":false,
"type":"generic",
"username":"",
"password":"",
"clientid":"moje${DEVICE_NAME}${DEVICE_MAC}",
"keepalive":30
},
"subscribe":[
{
"topic":"netio/${DEVICE_NAME}/output/1/action",
"qos":0,
"target":"OUTPUTS/1/ACTION",
"action":"${payload}"
},
{
"topic":"netio/${DEVICE_NAME}/output/1/switch",
"qos":0,
"target":"OUTPUTS/1/ACTION",
"action":4
}
],
"publish":[
{
"topic":"netio/${DEVICE_MAC}/output/1/state",
"qos":0,
"retain":true,
"payload":"${OUTPUTS/1/STATE}",
"events":[
{
"type":"change",
"source":"OUTPUTS/1/STATE"
},
{
"type":"timer",
"period":900
}
]
},
{
"topic":"netio/${DEVICE_NAME}/output/1/voltage",
"qos":0,
"retain":false,
"payload":"${OUTPUTS/1/VOLTAGE}",
"events":[
{
"type":"timer",
"period":300
},
{
"type":"delta",
"source":"OUTPUTS/1/VOLTAGE",
"delta":1
}
]
},
{
"topic":"netio/${DEVICE_NAME}/output/1/current",
"qos":0,
"retain":false,
"payload":"${OUTPUTS/1/CURRENT}",
"events":[
{
"type":"timer",
"period":300
},
{
"type":"delta",
"source":"OUTPUTS/1/CURRENT",
"delta":50
}
]
},
{
"topic":"netio/${DEVICE_NAME}/output/1/load",
"qos":0,
"retain":false,
"payload":"${OUTPUTS/1/LOAD}",
"events":[
{
"type":"timer",
"period":300
},
{
"type":"delta",
"source":"OUTPUTS/1/LOAD",
"delta":10
}
]
},
{
"topic":"netio/${DEVICE_NAME}/output/1/energy",
"qos":0,
"retain":false,
"payload":"${OUTPUTS/1/ENERGY}",
"events":[
{
"type":"timer",
"period":900
},
{
"type":"delta",
"source":"OUTPUTS/1/ENERGY",
"delta":1
}
]
},
{
"topic":"netio/${DEVICE_NAME}/output/1/tpf",
"qos":0,
"retain":false,
"payload":"${OUTPUTS/1/POWER_FACTOR}",
"events":[
{
"type":"timer",
"period":900
},
{
"type":"delta",
"source":"OUTPUTS/1/POWER_FACTOR",
"delta":0.02
}
]
},
{
"topic":"netio/${DEVICE_NAME}/output/1/frequency",
"qos":0,
"retain":false,
"payload":"${OUTPUTS/1/FREQUENCY}",
"events":[
{
"type":"timer",
"period":3600
},
{
"type":"delta",
"source":"OUTPUTS/1/FREQUENCY",
"delta":0.1
}
]
}
]
}
}

MQTT-flex

2023-06-06T14:09:44Z

Bbakala: /* Trigger Rule sequence from MQTT FW 4.0.0+ */

The MQTT-flex version of the MQTT protocol can be configured in detail thanks to the “flex” extension.

https://www.netio-products.com/en/glossary/mqtt-flex

Why MQTT-flex 
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 [https://en.wikipedia.org/wiki/MQTT 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 [https://en.wikipedia.org/wiki/JSON 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 101x 
* PowerCable REST 101x 
* PowerPDU 4PS 
* PowerPDU 4KS 
* PowerPDU 8QS 
* PowerDIN 4PZ 
* PowerBOX 3Px 
* PowerBOX 4Kx 

FW version: 
>2.2.1

===Not supported NETIO devices:===
* PowerPDU 4C 
* NETIO 4 
* NETIO 4All 

= Simple MQTT-flex configuration + explanation =

''We strongly recommend to create and test MQTT-flex configuration on "local" device what can be easily restarted. The validation of config before saving is not 100% and for example some specific typos can cause a freeze of a device - the solution is to restart a device (unplug/plug input power cable). If the configuration is saved and device is working then there are no known failure case so it is safe to use this configuration on the "remote" devices.''

{
"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":false,
"payload":"${OUTPUTS/1/STATE}",
"events":[
{
"type":"timer",
"period":"1000"
}
]
}
]
}
}
=== Client Configuration (broker section) ===
Put here MQTT client connection setup

This configuration example set NETIO device to connect to broker.hivemq.com with mqtt protocol, no ssl connection with credetials freedom/peace|love|empathy4ALL.

"broker":{
"url":"broker.hivemq.com",
"protocol":"mqtt",
"port":1883,
"ssl":false,
"type":"generic",
"username":"freedom",
"password":"peace|LOVE|empathy4ALL"
},

=== Device Control (subscribe section) ===
Put here array of topics where to subscribe

Device output 1 is controlled with action received by subscription to netio/${DEVICE_NAME}/output/1/action topic with QOS 0

"subscribe":[{
"topic":"netio/${DEVICE_NAME}/output/1/action",
"qos":0,
"target":"OUTPUTS/1/ACTION",
"action":"${payload}"
}
],

=== Output State monitoring (publish section) ===
Put here array of topics where to publish.

Device send every 1000 s message to topic with QOS 0, retain true information with output 1 state

"publish":[{
"topic":"netio/${DEVICE_NAME}/output/1/state",
"qos":0,
"retain":true,
"payload":"${OUTPUTS/1/STATE}",
"events":[
{
"type":"timer",
"period":"1000"
}
]
}
]

= 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 ===
{| class="wikitable"
! style="font-weight:bold; background-color:#9b9b9b;" | Item
! style="font-weight:bold; background-color:#9b9b9b;" | Presence
! style="font-weight:bold; background-color:#9b9b9b;" | Possible Values
! style="font-weight:bold; background-color:#9b9b9b;" | Description
! style="font-weight:bold; background-color:#9b9b9b;" | JSON Config Usage
|-
| style="background-color:#efefef;" | url
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" |
| style="background-color:#efefef;" | MQTT broker URL
| style="background-color:#efefef;" | "url":"broker.hivemq.com"
|-
| style="background-color:#efefef;" | port
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | 1 - 65535
| style="background-color:#efefef;" | MQTT broker port
| style="background-color:#efefef;" | "port":1883
|-
| style="background-color:#efefef;" | protocol
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" |
| style="background-color:#efefef;" | protocol spec - mqtt
| style="background-color:#efefef;" | "protocol": "mqtt"
|-
| style="background-color:#efefef;" | ssl
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | true, false
| style="background-color:#efefef;" | Use SSL crypted communication selector
| style="background-color:#efefef;" | "ssl":false
|-
| style="background-color:#efefef;" | type
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | generic
| style="background-color:#efefef;" | Communication/setup type option
| style="background-color:#efefef;" | "type":"generic"
|-
| style="background-color:#efefef;" | username
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | regexp+len
| style="background-color:#efefef;" | Credentials for MQTT broker. Max. 128 characters (since FW 3.2.4).
| style="background-color:#efefef;" | "username":"freedom"
|-
| style="background-color:#efefef;" | password
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | regexp+len
| style="background-color:#efefef;" | Credentials for MQTT broker. Max. 256 characters (since FW 3.2.4).
| style="background-color:#efefef;" | "password":"peace|LOVE|empathy4ALL"
|-
| style="background-color:#efefef;" | clientid
| style="background-color:#efefef;" | optional
| style="background-color:#efefef;" | regexp+len
| style="background-color:#efefef;" | MQTT clientid. Max. 128 characters (since FW 3.2.4). Variables ${DEVICE_MAC} or ${DEVICE_NAME} can be used
| style="background-color:#efefef;" | "clientid":"myEcoTable01"
|-
| style="background-color:#efefef;" | keepalive
| style="background-color:#efefef;" | optional
| style="background-color:#efefef;" | 1 - 65535
| style="background-color:#efefef;" | MQTT keep alive period in seconds
| style="background-color:#efefef;" | "keepalive":90
|}

Note 1: clientid attribute is mandatory for MQTT(s) communication. When not configured, random ID will be generated.

Note 2: To proper communication with MS Azure - it is necessary to set up IoT Hub to use TLS 1.2

See section "TLS 1.2 enforcement available in select regions" in following guidelines https://docs.microsoft.com/en-us/azure/iot-hub/iot-hub-tls-support

=== Examples ===
==== Standard setup ====

==== Security (SSL / TLS) secured setup ====
You can enable MQTTs by using the encrypted port 8883 + "ssl":true.

==== Variables used setup ====

== 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 ===
{| class="wikitable"
! style="font-weight:bold; background-color:#9b9b9b;" | Item
! style="font-weight:bold; background-color:#9b9b9b;" | Presence
! style="font-weight:bold; background-color:#9b9b9b;" | Possible Values
! style="font-weight:bold; background-color:#9b9b9b;" | Description
! style="font-weight:bold; background-color:#9b9b9b;" | JSON Config Usage
|-
| style="background-color:#efefef;" | topic
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | see table below
| style="background-color:#efefef;" | specification of the topic, which MQTT-flex device listens from broker and act accordingly. Max. 128 characters. The "#" can be used since FW 3.2.4 - see note under this table.
| style="background-color:#efefef;" | "topic":"netio/${DEVICE_NAME}/output/1/action"
|-
| style="background-color:#efefef;" | qos
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | 0, 1 or 2
| style="background-color:#efefef;" | 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}
| style="background-color:#efefef;" | "qos":0
|-
| style="background-color:#efefef;" | target
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" |
| style="background-color:#efefef;" | internal definition of action, which can be performed above the specified output
| style="background-color:#efefef;" | "target":"OUTPUTS/1/ACTION"
|-
| style="background-color:#efefef;" | action
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" |
| style="background-color:#efefef;" | a payload or a value the action attribute needs to have passed to
| style="background-color:#efefef;" | "action":"${payload}"
|-
| style="background-color:#efefef;" | actiondefNot supported yet
| style="background-color:#efefef;" | optional
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
|-
| style="background-color:#efefef;" | jsonNot supported yet
| style="background-color:#efefef;" | optional
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
|}

Note: The "#" wildcard can be used in subscribe topic definition. The multi-level wildcard character MUST be specified either on its own or following a topic level separator. In either case it MUST be the last character specified in the Topic.

For example, if a Device subscribes to “devices/{device_id}/messages/devicebound/#”, it would receive messages published using these topic names:

“devices/{device_id}/messages/devicebound/”

“devices/{device_id}/messages/devicebound/{property_bag}”

This should be usefull for use with MS Azure - IoT hub.

=== MQTT Subscribe as event to trigger action <code>FW 4.0.0+</code> ===

This feature allow to subscribe to specific MQTT topic and pass payload to Rules or MQTT-flex as event.

target: <code>PROTOCOLS/MQTT/EVENT</code>

"subscribe": [
{
"action": "${payload}",
"qos": 0,
"target": "PROTOCOLS/MQTT/EVENT",
"topic": "broker/12345/MQTT_EVENT/"
}
]

=== Examples ===
==== Toggle output with standard payload ====
==== Toggle output with custom payload ====
==== Subscribe to more than one topic ====
==== Trigger Rule and MQTT publish from MQTT subscribe <code>FW 4.0.0+</code> ====
This example show Request response implementation in MQTT and toggle action made by Rules.

When message with payload <code>getValues</code> is published to topic <code>broker/gv90018g/COMMAND</code> MQTT flex will create an event with name <code>PROTOCOLS/MQTT/EVENT</code> (fixed name cannot be changed) and value <code>getValues</code>. On this event will act all events and conditions set in MQTT-flex and Rules which are set to listening to change on <code>PROTOCOLS/MQTT/EVENT</code> and equals to value <code>getValues</code>. See bold marked parameters in example configuration below.

Once the triggered action is done it is needed to reset MQTT channel to <code>OK</code> status becaus event are reacting only to change. If the channel is not reset the next even would not be triggered.

Rules Configuration:
{
"conditions": {
"PROTOCOLS/MQTT/EVENT": "getValues"
},
"actions": {
"OUTPUTS/1/ACTION": 4
}
}

MQTT Configuration:
{
"broker":{
"clientid":"netio${DEVICE_SN}",
"keepalive":30,
"password":"goad7jbh326pr2ne",
"port":8883,
"protocol":"mqtt",
"ssl":true,
"type":"generic",
"url":"broker.cloud-dev.netio.eu",
"username":"gv90018g"
},
"groupEvents":[
{
"events":[
{
"source":"PROTOCOLS/MQTT/EVENT",
"type":"change",
"value":"getValues"
}
],
"appliedTopics":[
"broker/gv90018g/OUTPUTS/1/STATE",
"broker/gv90018g/COMMAND"
]
}
],
"publish":[
{
"payload":"${OUTPUTS/1/STATE}",
"qos":0,
"retain":true,
"topic":"broker/gv90018g/OUTPUTS/1/STATE"
},
{
"payload":"OK",
"qos":0,
"retain":true,
"topic":"broker/gv90018g/COMMAND"
}
],
"subscribe":[
{
"action":"${payload}",
"qos":0,
"target":"PROTOCOLS/MQTT/EVENT",
"topic":"broker/gv90018g/COMMAND"
}
]
}

==== Trigger MQTT publish by MQTT subscribe <code>FW 4.0.0+</code> ====

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 ===
{| class="wikitable"
! style="font-weight:bold; background-color:#9b9b9b;" | Item
! style="font-weight:bold; background-color:#9b9b9b;" | Presence
! style="font-weight:bold; background-color:#9b9b9b;" | Possible Values
! style="font-weight:bold; background-color:#9b9b9b;" | Description
! style="font-weight:bold; background-color:#9b9b9b;" | JSON Config Usage
|-
| style="background-color:#efefef;" | topic
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | see table below
| style="background-color:#efefef;" | definition of the topic, how it is registered towards MQTT broker. Max. 128 characters.
| style="background-color:#efefef;" | "topic":"netio/${DEVICE_NAME}/output/1/load"
|-
| style="background-color:#efefef;" | qos
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | see table below
| style="background-color:#efefef;" | 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}
| style="background-color:#efefef;" |
|-
| style="background-color:#efefef;" | retain
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | boolean: true or false
| style="background-color:#efefef;" | 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}
| style="background-color:#efefef;" | "retain":true
|-
| style="background-color:#efefef;" | payload
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | see table below
| style="background-color:#efefef;" | definition of the payload, what is send to the MQTT broker.
| style="background-color:#efefef;" | "payload":"${OUTPUTS/1/STATE}"
|-
| style="background-color:#efefef;" | events
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | see table below
| style="background-color:#efefef;" | definition of events used for triggering sending of data via mqtt (change, delta, timer)
| style="background-color:#efefef;" |
|-
| style="background-color:#efefef;" | type
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
|-
| style="background-color:#efefef;" | source
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
|-
| style="background-color:#efefef;" | delta
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
|-
| style="background-color:#efefef;" | period
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
|-
| style="background-color:#efefef;" | payloaddefNot supported yet
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
|}

=== Examples ===
==== Publish energy periodically (event timer) ====
==== Publish current on change (delta) ====
==== Publish output state ====
==== Publish to more than one topic with different events ====

= 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 available only on NETIO PowerDIN 4PZ

=== Examples: ===

adressing controll of output 3
OUTPUTS/3/ACTION
getting voltage on output 1
OUTPUTS/1/VOLTAGE
getting state of input 1
INPUTS/1/STATE

= Events =
==== Timer ====

==== Delta ====

==== Change ====

==== Group Events<code>FW 4.0.0+</code>====

= 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 ===
==== VOLTAGE ====
Unit: <code>V</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Present RMS voltage on output 1 is ${OUTPUTS/1/VOLTAGE}"</code>

Example 2: <code>"source":"${OUTPUTS/1/VOLTAGE}"</code>

==== CURRENT ====
Unit: <code>mA</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Present RMS current on output 1 is ${OUTPUTS/1/CURRENT}"</code>

Example 2: <code>"source":"${OUTPUTS/1/CURRENT}"</code>

==== POWER_FACTOR ====
Unit: <code>[-]</code>

Type: float (2 decimals)

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"True Power Factor on output 1 is ${OUTPUTS/1/POWER_FACTOR}"</code>

Example 2: <code>"source":"${OUTPUTS/1/POWER_FACTOR}"</code>

==== LOAD ====
Unit: <code>W</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Present load on output 1 is ${OUTPUTS/1/LOAD}W"</code>

Example 2: <code>"payload":"Device's load connected to output 1 is ${OUTPUTS/1/LOAD}W"</code>

Example 3: <code>"source":"${OUTPUTS/1/LOAD}"</code>

==== STATE ====
Type: bool(integer) - <code>0</code> or <code>1</code>

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Present output 1 state is ${OUTPUTS/1/STATE}"</code>

Example 2: <code>"source":"${OUTPUTS/1/STATE}"</code>

==== ACTION ====
Type: integer

Possible actions:
* <code>0</code> - set state OFF
* <code>1</code> - set state ON
* <code>2</code> - short OFF (restart)
* <code>3</code> - short ON
* <code>4</code> - toggle (switch)
* <code>5</code> - no change

Allowed in: <code>"target"</code>

Example: <code>"target":"OUTPUTS/1/ACTION"</code>

==== DELAY [ms] ====
==== NAME ====
==== FREQUENCY ====
Unit: <code>Hz</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example: <code>"payload":"Frequency in power grid is ${OUTPUTS/1/ENERGY}Hz"</code>

==== ENERGY ====
Energy consumed by an device connected to NETIO device output.

Unit: <code>Wh</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Consumed energy on output 1 is ${OUTPUTS/1/ENERGY}Wh"</code>

Example 2: <code>"source":"${OUTPUTS/1/ENERGY}"</code>

==== REVERSE_ENERGY ====
Energy delivered back to grid. For example from solar system connected to NETIO device output.

Unit: <code>Wh</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Delivered energy on output 1 is ${OUTPUTS/1/REVERSE_ENERGY}Wh"</code>

Example 2: <code>"source":"${OUTPUTS/1/REVERSE_ENERGY}"</code>

==== ENERGY_START ====
Date when the counters ENERGY and REVERSE_ENERGY have been resetted by user.

Unit: <code>unix timestamp</code>

Type: integer

Allowed in: <code>"payload"</code>

Example 1: <code>"payload":"Energy measured since ${OUTPUTS/1/ENERGY_START} unix time"</code>

Example 2: <code>"payload":"${OUTPUTS/1/ENERGY_START}"</code> is output payload <code>1567654639</code>

==== ENERGY_START_FMT ====
Date when the counters ENERGY and REVERSE_ENERGY have been resetted by user.

Unit: <code>fmt date format</code>

Type: string

Allowed in: <code>"payload"</code>

Example 1: <code>"payload":"Energy measured since ${OUTPUTS/1/ENERGY_START}"</code>

Example 2: <code>"payload":"${OUTPUTS/1/ENERGY_START_FMT}"</code> is output payload <code>2019-09-05T03:37:19+00:00</code>

==== ENERGY_NR ====
Non-resettable counter of Energy consumed by an device connected to NETIO device output.

Unit: <code>Wh</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Consumed energy on output 1 is ${OUTPUTS/1/ENERGY_NR}Wh"</code>

Example 2: <code>"source":"${OUTPUTS/1/ENERGY_NR}"</code>

==== REVERSE_ENERGY_NR ====
Non-resettable counter of Energy delivered back to grid. For example from solar system connected to NETIO device output.

Unit: <code>Wh</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Delivered energy on output 1 is ${OUTPUTS/1/REVERSE_ENERGY_NR}Wh"</code>

Example 2: <code>"source":"${OUTPUTS/1/REVERSE_ENERGY_NR}"</code>

==== TOTALs - for 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
* OUTPUTS/TOTAL/PHASE
* OUTPUTS/TOTAL/REVERSE_ENERGY
* OUTPUTS/TOTAL/ENERGY_NR
* OUTPUTS/TOTAL/REVERSE_ENERGY_NR
* OUTPUTS/TOTAL/ENERGY_START
* OUTPUTS/TOTAL/ENERGY_START_FMT

==== REST_JSON ====
Allow use of NETIO JSON structure to control outputs.

Type: string / JSON

Allowed in: <code>"target"</code> for Subscribe section

Example: <code>"target": "REST_JSON"</code>

The payload is JSON structure identical to NETIO JSON API M2M Protocol (documentation available at https://www.netio-products.com/files/NETIO-M2M-API-Protocol-JSON.pdf). You can control one or multiple outputs.

Payload example 1 - Toggle output 1: <code>{"Outputs":[{"ID": 1,"Action": 4}]}</code>

Payload example 2 - Turn output 1 OFF and output 3 ON: <code>{"Outputs":[{"ID":1,"Action":0},{"ID":3,"Action":1}]}</code>

=== INPUT variables ===
==== STATE ====
Type: bool(integer) - <code>0</code> or <code>1</code>

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Present input 1 state is ${INPUTS/1/STATE}"</code>

Example 2: <code>"source":"${INPUTS/1/STATE}"</code>

==== S0 ====
S0 Counter value
Unit: <code>-</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Input 1 S0 Counter value is ${INPUTS/1/S0}impulses"</code>

Example 2: <code>"source":"${INPUTS/1/S0}"</code>

== Payload/topic variables ==

=== DEVICE_NAME ===
Can be used in: "payload", "topic"

Example 1: <code>"payload":"${DEVICE_NAME}"</code>

Example 2: <code>"topic":"netio/${DEVICE_NAME}/output/1/action"</code>

=== DEVICE_MAC ===

=== UPTIME Not yet implemented ===

=== PAYLOAD ===
Can be used in: "action"

Example: <code>"action":"${PAYLOAD}"</code>

=== OUTPUT_ID Not yet implemented===

=== WIFI_SIGNALNot yet implemented ===

=== OUTPUTS_STATUS ===
Provide complete outputs status and measurement if supported.

Type: string / JSON

Allowed in: <code>"payload"</code> for Publish section

Example: <code>"payload":"${OUTPUTS_STATUS}"</code>

Payload example: <code>{ "GlobalMeasure":{"Voltage":236,"TotalCurrent":72,"TotalLoad":11,"TotalEnergy":167,"OverallPowerFactor":0.64,"Frequency":50.07,"Phase":-36.86,"EnergyStart":"2020-06-30T17:04:48+01:00"}, "Outputs":[ {"ID":1,"Name":"Power output 1","State":1,"Action":6,"Delay":2020,"Current":72,"PowerFactor":0.64,"Phase":-36.86,"Energy":139,"ReverseEnergy":0,"Load":11}, {"ID":2,"Name":"Power output 2","State":1,"Action":6,"Delay":2020,"Current":0,"PowerFactor":1.00,"Phase":0.00,"Energy":27,"ReverseEnergy":0,"Load":0}, {"ID":3,"Name":"Free Contact 3","State":1,"Action":6,"Delay":2020}, {"ID":4,"Name":"Free Contact 4","State":1,"Action":6,"Delay":2020} ]}</code>

=== INPUTS_STATUS ===
Provide complete inputs status if supported. Since FW 3.0.0

Type: string / JSON

Allowed in: <code>"payload"</code> for Publish section

Example: <code>"payload":"${INPUTS_STATUS}"</code>

Payload example: <code>{ "Inputs":[ {"ID":1,"Name":"Input 1","State":0,"S0Counter":0}, {"ID":2,"Name":"Input 2","State":0,"S0Counter":0} ]}</code>

=== INOUT_STATUS ===
Provide complete inputs and output status and measurement if supported. Since FW 3.0.0

Type: string / JSON

Allowed in: <code>"payload"</code> for Publish section

Example: <code>"payload":"${INOUT_STATUS}"</code>

Payload example: <code>{ "GlobalMeasure":{"Voltage":238,"TotalCurrent":105,"TotalLoad":17,"TotalEnergy":1451,"OverallPowerFactor":0.67,"Frequency":50.03,"Phase":-33.67,"EnergyStart":"2020-06-30T17:04:48+01:00"}, "Outputs":[ {"ID":1,"Name":"Power output 1","State":0,"Action":6,"Delay":5000,"Current":0,"PowerFactor":1.00,"Phase":0.00,"Energy":701,"ReverseEnergy":0,"Load":0}, {"ID":2,"Name":"Power output 2","State":1,"Action":6,"Delay":5000,"Current":105,"PowerFactor":0.65,"Phase":-33.67,"Energy":750,"ReverseEnergy":0,"Load":17}, {"ID":3,"Name":"Free Contact 3","State":1,"Action":6,"Delay":5000}, {"ID":4,"Name":"Free Contact 4","State":0,"Action":6,"Delay":5000} ], "Inputs":[ {"ID":1,"Name":"Input 1","State":0,"S0Counter":0}, {"ID":2,"Name":"Input 2","State":0,"S0Counter":0} ]}</code>

= Extended MQTT flex JSON config examples =

== Default NETIO MQTT-flex configuration ==
This example demonstrates setup for connection to public <code>broker.hivemq.com</code>, measurement reporting and output control.

The device cabe be controlled via <code>netio/${DEVICE_NAME}/output/1/action topic</code> by sending standard NETIO action values:
* 0 - OFF
* 1 - ON
* 2 - SHORT OFF
* 3 - SHORT ON
* 4 - TOGGLE
* 5 - NO ACTION.

The device report measurements:

* Output state - every 15 minutes or by change
* Voltage [V]- every 5 minutes or by change of 1 V
* Current [mA]- every 5 minutes or by change of 50 mA
* Load(Power) [W]- every 5 minutes or by change of 10 W
* Energy(Consumption) [Wh]- every 15 minutes or by change of 1Wh
* True Power Factor (TPF) [-]- every 5 minutes or by change of 0.02
* Frequency [Hz]- every 1 hour or by change of 0.1 Hz

For register all values, you can use wildcard <code>netio/${DEVICE_NAME}/output/1/#</code>

{
"config":{
"broker":{
"url":"broker.hivemq.com",
"protocol":"mqtt",
"port":1883,
"ssl":false,
"type":"generic",
"username":"",
"password":"",
"clientid":"moje${DEVICE_NAME}${DEVICE_MAC}",
"keepalive":30
},
"subscribe":[
{
"topic":"netio/${DEVICE_NAME}/output/1/action",
"qos":0,
"target":"OUTPUTS/1/ACTION",
"action":"${payload}"
},
{
"topic":"netio/${DEVICE_NAME}/output/1/switch",
"qos":0,
"target":"OUTPUTS/1/ACTION",
"action":4
}
],
"publish":[
{
"topic":"netio/${DEVICE_MAC}/output/1/state",
"qos":0,
"retain":true,
"payload":"${OUTPUTS/1/STATE}",
"events":[
{
"type":"change",
"source":"OUTPUTS/1/STATE"
},
{
"type":"timer",
"period":900
}
]
},
{
"topic":"netio/${DEVICE_NAME}/output/1/voltage",
"qos":0,
"retain":false,
"payload":"${OUTPUTS/1/VOLTAGE}",
"events":[
{
"type":"timer",
"period":300
},
{
"type":"delta",
"source":"OUTPUTS/1/VOLTAGE",
"delta":1
}
]
},
{
"topic":"netio/${DEVICE_NAME}/output/1/current",
"qos":0,
"retain":false,
"payload":"${OUTPUTS/1/CURRENT}",
"events":[
{
"type":"timer",
"period":300
},
{
"type":"delta",
"source":"OUTPUTS/1/CURRENT",
"delta":50
}
]
},
{
"topic":"netio/${DEVICE_NAME}/output/1/load",
"qos":0,
"retain":false,
"payload":"${OUTPUTS/1/LOAD}",
"events":[
{
"type":"timer",
"period":300
},
{
"type":"delta",
"source":"OUTPUTS/1/LOAD",
"delta":10
}
]
},
{
"topic":"netio/${DEVICE_NAME}/output/1/energy",
"qos":0,
"retain":false,
"payload":"${OUTPUTS/1/ENERGY}",
"events":[
{
"type":"timer",
"period":900
},
{
"type":"delta",
"source":"OUTPUTS/1/ENERGY",
"delta":1
}
]
},
{
"topic":"netio/${DEVICE_NAME}/output/1/tpf",
"qos":0,
"retain":false,
"payload":"${OUTPUTS/1/POWER_FACTOR}",
"events":[
{
"type":"timer",
"period":900
},
{
"type":"delta",
"source":"OUTPUTS/1/POWER_FACTOR",
"delta":0.02
}
]
},
{
"topic":"netio/${DEVICE_NAME}/output/1/frequency",
"qos":0,
"retain":false,
"payload":"${OUTPUTS/1/FREQUENCY}",
"events":[
{
"type":"timer",
"period":3600
},
{
"type":"delta",
"source":"OUTPUTS/1/FREQUENCY",
"delta":0.1
}
]
}
]
}
}

MQTT-flex

2023-06-06T14:09:10Z

Bbakala: /* Trigger Rule sequence from MQTT FW 4.0.0+ */

The MQTT-flex version of the MQTT protocol can be configured in detail thanks to the “flex” extension.

https://www.netio-products.com/en/glossary/mqtt-flex

Why MQTT-flex 
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 [https://en.wikipedia.org/wiki/MQTT 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 [https://en.wikipedia.org/wiki/JSON 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 101x 
* PowerCable REST 101x 
* PowerPDU 4PS 
* PowerPDU 4KS 
* PowerPDU 8QS 
* PowerDIN 4PZ 
* PowerBOX 3Px 
* PowerBOX 4Kx 

FW version: 
>2.2.1

===Not supported NETIO devices:===
* PowerPDU 4C 
* NETIO 4 
* NETIO 4All 

= Simple MQTT-flex configuration + explanation =

''We strongly recommend to create and test MQTT-flex configuration on "local" device what can be easily restarted. The validation of config before saving is not 100% and for example some specific typos can cause a freeze of a device - the solution is to restart a device (unplug/plug input power cable). If the configuration is saved and device is working then there are no known failure case so it is safe to use this configuration on the "remote" devices.''

{
"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":false,
"payload":"${OUTPUTS/1/STATE}",
"events":[
{
"type":"timer",
"period":"1000"
}
]
}
]
}
}
=== Client Configuration (broker section) ===
Put here MQTT client connection setup

This configuration example set NETIO device to connect to broker.hivemq.com with mqtt protocol, no ssl connection with credetials freedom/peace|love|empathy4ALL.

"broker":{
"url":"broker.hivemq.com",
"protocol":"mqtt",
"port":1883,
"ssl":false,
"type":"generic",
"username":"freedom",
"password":"peace|LOVE|empathy4ALL"
},

=== Device Control (subscribe section) ===
Put here array of topics where to subscribe

Device output 1 is controlled with action received by subscription to netio/${DEVICE_NAME}/output/1/action topic with QOS 0

"subscribe":[{
"topic":"netio/${DEVICE_NAME}/output/1/action",
"qos":0,
"target":"OUTPUTS/1/ACTION",
"action":"${payload}"
}
],

=== Output State monitoring (publish section) ===
Put here array of topics where to publish.

Device send every 1000 s message to topic with QOS 0, retain true information with output 1 state

"publish":[{
"topic":"netio/${DEVICE_NAME}/output/1/state",
"qos":0,
"retain":true,
"payload":"${OUTPUTS/1/STATE}",
"events":[
{
"type":"timer",
"period":"1000"
}
]
}
]

= 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 ===
{| class="wikitable"
! style="font-weight:bold; background-color:#9b9b9b;" | Item
! style="font-weight:bold; background-color:#9b9b9b;" | Presence
! style="font-weight:bold; background-color:#9b9b9b;" | Possible Values
! style="font-weight:bold; background-color:#9b9b9b;" | Description
! style="font-weight:bold; background-color:#9b9b9b;" | JSON Config Usage
|-
| style="background-color:#efefef;" | url
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" |
| style="background-color:#efefef;" | MQTT broker URL
| style="background-color:#efefef;" | "url":"broker.hivemq.com"
|-
| style="background-color:#efefef;" | port
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | 1 - 65535
| style="background-color:#efefef;" | MQTT broker port
| style="background-color:#efefef;" | "port":1883
|-
| style="background-color:#efefef;" | protocol
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" |
| style="background-color:#efefef;" | protocol spec - mqtt
| style="background-color:#efefef;" | "protocol": "mqtt"
|-
| style="background-color:#efefef;" | ssl
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | true, false
| style="background-color:#efefef;" | Use SSL crypted communication selector
| style="background-color:#efefef;" | "ssl":false
|-
| style="background-color:#efefef;" | type
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | generic
| style="background-color:#efefef;" | Communication/setup type option
| style="background-color:#efefef;" | "type":"generic"
|-
| style="background-color:#efefef;" | username
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | regexp+len
| style="background-color:#efefef;" | Credentials for MQTT broker. Max. 128 characters (since FW 3.2.4).
| style="background-color:#efefef;" | "username":"freedom"
|-
| style="background-color:#efefef;" | password
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | regexp+len
| style="background-color:#efefef;" | Credentials for MQTT broker. Max. 256 characters (since FW 3.2.4).
| style="background-color:#efefef;" | "password":"peace|LOVE|empathy4ALL"
|-
| style="background-color:#efefef;" | clientid
| style="background-color:#efefef;" | optional
| style="background-color:#efefef;" | regexp+len
| style="background-color:#efefef;" | MQTT clientid. Max. 128 characters (since FW 3.2.4). Variables ${DEVICE_MAC} or ${DEVICE_NAME} can be used
| style="background-color:#efefef;" | "clientid":"myEcoTable01"
|-
| style="background-color:#efefef;" | keepalive
| style="background-color:#efefef;" | optional
| style="background-color:#efefef;" | 1 - 65535
| style="background-color:#efefef;" | MQTT keep alive period in seconds
| style="background-color:#efefef;" | "keepalive":90
|}

Note 1: clientid attribute is mandatory for MQTT(s) communication. When not configured, random ID will be generated.

Note 2: To proper communication with MS Azure - it is necessary to set up IoT Hub to use TLS 1.2

See section "TLS 1.2 enforcement available in select regions" in following guidelines https://docs.microsoft.com/en-us/azure/iot-hub/iot-hub-tls-support

=== Examples ===
==== Standard setup ====

==== Security (SSL / TLS) secured setup ====
You can enable MQTTs by using the encrypted port 8883 + "ssl":true.

==== Variables used setup ====

== 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 ===
{| class="wikitable"
! style="font-weight:bold; background-color:#9b9b9b;" | Item
! style="font-weight:bold; background-color:#9b9b9b;" | Presence
! style="font-weight:bold; background-color:#9b9b9b;" | Possible Values
! style="font-weight:bold; background-color:#9b9b9b;" | Description
! style="font-weight:bold; background-color:#9b9b9b;" | JSON Config Usage
|-
| style="background-color:#efefef;" | topic
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | see table below
| style="background-color:#efefef;" | specification of the topic, which MQTT-flex device listens from broker and act accordingly. Max. 128 characters. The "#" can be used since FW 3.2.4 - see note under this table.
| style="background-color:#efefef;" | "topic":"netio/${DEVICE_NAME}/output/1/action"
|-
| style="background-color:#efefef;" | qos
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | 0, 1 or 2
| style="background-color:#efefef;" | 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}
| style="background-color:#efefef;" | "qos":0
|-
| style="background-color:#efefef;" | target
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" |
| style="background-color:#efefef;" | internal definition of action, which can be performed above the specified output
| style="background-color:#efefef;" | "target":"OUTPUTS/1/ACTION"
|-
| style="background-color:#efefef;" | action
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" |
| style="background-color:#efefef;" | a payload or a value the action attribute needs to have passed to
| style="background-color:#efefef;" | "action":"${payload}"
|-
| style="background-color:#efefef;" | actiondefNot supported yet
| style="background-color:#efefef;" | optional
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
|-
| style="background-color:#efefef;" | jsonNot supported yet
| style="background-color:#efefef;" | optional
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
|}

Note: The "#" wildcard can be used in subscribe topic definition. The multi-level wildcard character MUST be specified either on its own or following a topic level separator. In either case it MUST be the last character specified in the Topic.

For example, if a Device subscribes to “devices/{device_id}/messages/devicebound/#”, it would receive messages published using these topic names:

“devices/{device_id}/messages/devicebound/”

“devices/{device_id}/messages/devicebound/{property_bag}”

This should be usefull for use with MS Azure - IoT hub.

=== MQTT Subscribe as event to trigger action <code>FW 4.0.0+</code> ===

This feature allow to subscribe to specific MQTT topic and pass payload to Rules or MQTT-flex as event.

target: <code>PROTOCOLS/MQTT/EVENT</code>

"subscribe": [
{
"action": "${payload}",
"qos": 0,
"target": "PROTOCOLS/MQTT/EVENT",
"topic": "broker/12345/MQTT_EVENT/"
}
]

=== Examples ===
==== Toggle output with standard payload ====
==== Toggle output with custom payload ====
==== Subscribe to more than one topic ====
==== Trigger Rule sequence from MQTT <code>FW 4.0.0+</code> ====
This example show Request response implementation in MQTT and toggle action made by Rules.

When message with payload <code>getValues</code> is published to topic <code>broker/gv90018g/COMMAND</code> MQTT flex will create an event with name <code>PROTOCOLS/MQTT/EVENT</code> (fixed name cannot be changed) and value <code>getValues</code>. On this event will act all events and conditions set in MQTT-flex and Rules which are set to listening to change on <code>PROTOCOLS/MQTT/EVENT</code> and equals to value <code>getValues</code>. See bold marked parameters in example configuration below.

Once the triggered action is done it is needed to reset MQTT channel to <code>OK</code> status becaus event are reacting only to change. If the channel is not reset the next even would not be triggered.

Rules Configuration:
{
"conditions": {
"PROTOCOLS/MQTT/EVENT": "getValues"
},
"actions": {
"OUTPUTS/1/ACTION": 4
}
}

MQTT Configuration:
{
"broker":{
"clientid":"netio${DEVICE_SN}",
"keepalive":30,
"password":"goad7jbh326pr2ne",
"port":8883,
"protocol":"mqtt",
"ssl":true,
"type":"generic",
"url":"broker.cloud-dev.netio.eu",
"username":"gv90018g"
},
"groupEvents":[
{
"events":[
{
"source":"PROTOCOLS/MQTT/EVENT",
"type":"change",
"value":"getValues"
}
],
"appliedTopics":[
"broker/gv90018g/OUTPUTS/1/STATE",
"broker/gv90018g/COMMAND"
]
}
],
"publish":[
{
"payload":"${OUTPUTS/1/STATE}",
"qos":0,
"retain":true,
"topic":"broker/gv90018g/OUTPUTS/1/STATE"
},
{
"payload":"OK",
"qos":0,
"retain":true,
"topic":"broker/gv90018g/COMMAND"
}
],
"subscribe":[
{
"action":"${payload}",
"qos":0,
"target":"PROTOCOLS/MQTT/EVENT",
"topic":"broker/gv90018g/COMMAND"
}
]
}

==== Trigger MQTT publish by MQTT subscribe <code>FW 4.0.0+</code> ====

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 ===
{| class="wikitable"
! style="font-weight:bold; background-color:#9b9b9b;" | Item
! style="font-weight:bold; background-color:#9b9b9b;" | Presence
! style="font-weight:bold; background-color:#9b9b9b;" | Possible Values
! style="font-weight:bold; background-color:#9b9b9b;" | Description
! style="font-weight:bold; background-color:#9b9b9b;" | JSON Config Usage
|-
| style="background-color:#efefef;" | topic
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | see table below
| style="background-color:#efefef;" | definition of the topic, how it is registered towards MQTT broker. Max. 128 characters.
| style="background-color:#efefef;" | "topic":"netio/${DEVICE_NAME}/output/1/load"
|-
| style="background-color:#efefef;" | qos
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | see table below
| style="background-color:#efefef;" | 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}
| style="background-color:#efefef;" |
|-
| style="background-color:#efefef;" | retain
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | boolean: true or false
| style="background-color:#efefef;" | 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}
| style="background-color:#efefef;" | "retain":true
|-
| style="background-color:#efefef;" | payload
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | see table below
| style="background-color:#efefef;" | definition of the payload, what is send to the MQTT broker.
| style="background-color:#efefef;" | "payload":"${OUTPUTS/1/STATE}"
|-
| style="background-color:#efefef;" | events
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | see table below
| style="background-color:#efefef;" | definition of events used for triggering sending of data via mqtt (change, delta, timer)
| style="background-color:#efefef;" |
|-
| style="background-color:#efefef;" | type
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
|-
| style="background-color:#efefef;" | source
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
|-
| style="background-color:#efefef;" | delta
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
|-
| style="background-color:#efefef;" | period
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
|-
| style="background-color:#efefef;" | payloaddefNot supported yet
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
|}

=== Examples ===
==== Publish energy periodically (event timer) ====
==== Publish current on change (delta) ====
==== Publish output state ====
==== Publish to more than one topic with different events ====

= 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 available only on NETIO PowerDIN 4PZ

=== Examples: ===

adressing controll of output 3
OUTPUTS/3/ACTION
getting voltage on output 1
OUTPUTS/1/VOLTAGE
getting state of input 1
INPUTS/1/STATE

= Events =
==== Timer ====

==== Delta ====

==== Change ====

==== Group Events<code>FW 4.0.0+</code>====

= 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 ===
==== VOLTAGE ====
Unit: <code>V</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Present RMS voltage on output 1 is ${OUTPUTS/1/VOLTAGE}"</code>

Example 2: <code>"source":"${OUTPUTS/1/VOLTAGE}"</code>

==== CURRENT ====
Unit: <code>mA</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Present RMS current on output 1 is ${OUTPUTS/1/CURRENT}"</code>

Example 2: <code>"source":"${OUTPUTS/1/CURRENT}"</code>

==== POWER_FACTOR ====
Unit: <code>[-]</code>

Type: float (2 decimals)

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"True Power Factor on output 1 is ${OUTPUTS/1/POWER_FACTOR}"</code>

Example 2: <code>"source":"${OUTPUTS/1/POWER_FACTOR}"</code>

==== LOAD ====
Unit: <code>W</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Present load on output 1 is ${OUTPUTS/1/LOAD}W"</code>

Example 2: <code>"payload":"Device's load connected to output 1 is ${OUTPUTS/1/LOAD}W"</code>

Example 3: <code>"source":"${OUTPUTS/1/LOAD}"</code>

==== STATE ====
Type: bool(integer) - <code>0</code> or <code>1</code>

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Present output 1 state is ${OUTPUTS/1/STATE}"</code>

Example 2: <code>"source":"${OUTPUTS/1/STATE}"</code>

==== ACTION ====
Type: integer

Possible actions:
* <code>0</code> - set state OFF
* <code>1</code> - set state ON
* <code>2</code> - short OFF (restart)
* <code>3</code> - short ON
* <code>4</code> - toggle (switch)
* <code>5</code> - no change

Allowed in: <code>"target"</code>

Example: <code>"target":"OUTPUTS/1/ACTION"</code>

==== DELAY [ms] ====
==== NAME ====
==== FREQUENCY ====
Unit: <code>Hz</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example: <code>"payload":"Frequency in power grid is ${OUTPUTS/1/ENERGY}Hz"</code>

==== ENERGY ====
Energy consumed by an device connected to NETIO device output.

Unit: <code>Wh</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Consumed energy on output 1 is ${OUTPUTS/1/ENERGY}Wh"</code>

Example 2: <code>"source":"${OUTPUTS/1/ENERGY}"</code>

==== REVERSE_ENERGY ====
Energy delivered back to grid. For example from solar system connected to NETIO device output.

Unit: <code>Wh</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Delivered energy on output 1 is ${OUTPUTS/1/REVERSE_ENERGY}Wh"</code>

Example 2: <code>"source":"${OUTPUTS/1/REVERSE_ENERGY}"</code>

==== ENERGY_START ====
Date when the counters ENERGY and REVERSE_ENERGY have been resetted by user.

Unit: <code>unix timestamp</code>

Type: integer

Allowed in: <code>"payload"</code>

Example 1: <code>"payload":"Energy measured since ${OUTPUTS/1/ENERGY_START} unix time"</code>

Example 2: <code>"payload":"${OUTPUTS/1/ENERGY_START}"</code> is output payload <code>1567654639</code>

==== ENERGY_START_FMT ====
Date when the counters ENERGY and REVERSE_ENERGY have been resetted by user.

Unit: <code>fmt date format</code>

Type: string

Allowed in: <code>"payload"</code>

Example 1: <code>"payload":"Energy measured since ${OUTPUTS/1/ENERGY_START}"</code>

Example 2: <code>"payload":"${OUTPUTS/1/ENERGY_START_FMT}"</code> is output payload <code>2019-09-05T03:37:19+00:00</code>

==== ENERGY_NR ====
Non-resettable counter of Energy consumed by an device connected to NETIO device output.

Unit: <code>Wh</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Consumed energy on output 1 is ${OUTPUTS/1/ENERGY_NR}Wh"</code>

Example 2: <code>"source":"${OUTPUTS/1/ENERGY_NR}"</code>

==== REVERSE_ENERGY_NR ====
Non-resettable counter of Energy delivered back to grid. For example from solar system connected to NETIO device output.

Unit: <code>Wh</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Delivered energy on output 1 is ${OUTPUTS/1/REVERSE_ENERGY_NR}Wh"</code>

Example 2: <code>"source":"${OUTPUTS/1/REVERSE_ENERGY_NR}"</code>

==== TOTALs - for 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
* OUTPUTS/TOTAL/PHASE
* OUTPUTS/TOTAL/REVERSE_ENERGY
* OUTPUTS/TOTAL/ENERGY_NR
* OUTPUTS/TOTAL/REVERSE_ENERGY_NR
* OUTPUTS/TOTAL/ENERGY_START
* OUTPUTS/TOTAL/ENERGY_START_FMT

==== REST_JSON ====
Allow use of NETIO JSON structure to control outputs.

Type: string / JSON

Allowed in: <code>"target"</code> for Subscribe section

Example: <code>"target": "REST_JSON"</code>

The payload is JSON structure identical to NETIO JSON API M2M Protocol (documentation available at https://www.netio-products.com/files/NETIO-M2M-API-Protocol-JSON.pdf). You can control one or multiple outputs.

Payload example 1 - Toggle output 1: <code>{"Outputs":[{"ID": 1,"Action": 4}]}</code>

Payload example 2 - Turn output 1 OFF and output 3 ON: <code>{"Outputs":[{"ID":1,"Action":0},{"ID":3,"Action":1}]}</code>

=== INPUT variables ===
==== STATE ====
Type: bool(integer) - <code>0</code> or <code>1</code>

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Present input 1 state is ${INPUTS/1/STATE}"</code>

Example 2: <code>"source":"${INPUTS/1/STATE}"</code>

==== S0 ====
S0 Counter value
Unit: <code>-</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Input 1 S0 Counter value is ${INPUTS/1/S0}impulses"</code>

Example 2: <code>"source":"${INPUTS/1/S0}"</code>

== Payload/topic variables ==

=== DEVICE_NAME ===
Can be used in: "payload", "topic"

Example 1: <code>"payload":"${DEVICE_NAME}"</code>

Example 2: <code>"topic":"netio/${DEVICE_NAME}/output/1/action"</code>

=== DEVICE_MAC ===

=== UPTIME Not yet implemented ===

=== PAYLOAD ===
Can be used in: "action"

Example: <code>"action":"${PAYLOAD}"</code>

=== OUTPUT_ID Not yet implemented===

=== WIFI_SIGNALNot yet implemented ===

=== OUTPUTS_STATUS ===
Provide complete outputs status and measurement if supported.

Type: string / JSON

Allowed in: <code>"payload"</code> for Publish section

Example: <code>"payload":"${OUTPUTS_STATUS}"</code>

Payload example: <code>{ "GlobalMeasure":{"Voltage":236,"TotalCurrent":72,"TotalLoad":11,"TotalEnergy":167,"OverallPowerFactor":0.64,"Frequency":50.07,"Phase":-36.86,"EnergyStart":"2020-06-30T17:04:48+01:00"}, "Outputs":[ {"ID":1,"Name":"Power output 1","State":1,"Action":6,"Delay":2020,"Current":72,"PowerFactor":0.64,"Phase":-36.86,"Energy":139,"ReverseEnergy":0,"Load":11}, {"ID":2,"Name":"Power output 2","State":1,"Action":6,"Delay":2020,"Current":0,"PowerFactor":1.00,"Phase":0.00,"Energy":27,"ReverseEnergy":0,"Load":0}, {"ID":3,"Name":"Free Contact 3","State":1,"Action":6,"Delay":2020}, {"ID":4,"Name":"Free Contact 4","State":1,"Action":6,"Delay":2020} ]}</code>

=== INPUTS_STATUS ===
Provide complete inputs status if supported. Since FW 3.0.0

Type: string / JSON

Allowed in: <code>"payload"</code> for Publish section

Example: <code>"payload":"${INPUTS_STATUS}"</code>

Payload example: <code>{ "Inputs":[ {"ID":1,"Name":"Input 1","State":0,"S0Counter":0}, {"ID":2,"Name":"Input 2","State":0,"S0Counter":0} ]}</code>

=== INOUT_STATUS ===
Provide complete inputs and output status and measurement if supported. Since FW 3.0.0

Type: string / JSON

Allowed in: <code>"payload"</code> for Publish section

Example: <code>"payload":"${INOUT_STATUS}"</code>

Payload example: <code>{ "GlobalMeasure":{"Voltage":238,"TotalCurrent":105,"TotalLoad":17,"TotalEnergy":1451,"OverallPowerFactor":0.67,"Frequency":50.03,"Phase":-33.67,"EnergyStart":"2020-06-30T17:04:48+01:00"}, "Outputs":[ {"ID":1,"Name":"Power output 1","State":0,"Action":6,"Delay":5000,"Current":0,"PowerFactor":1.00,"Phase":0.00,"Energy":701,"ReverseEnergy":0,"Load":0}, {"ID":2,"Name":"Power output 2","State":1,"Action":6,"Delay":5000,"Current":105,"PowerFactor":0.65,"Phase":-33.67,"Energy":750,"ReverseEnergy":0,"Load":17}, {"ID":3,"Name":"Free Contact 3","State":1,"Action":6,"Delay":5000}, {"ID":4,"Name":"Free Contact 4","State":0,"Action":6,"Delay":5000} ], "Inputs":[ {"ID":1,"Name":"Input 1","State":0,"S0Counter":0}, {"ID":2,"Name":"Input 2","State":0,"S0Counter":0} ]}</code>

= Extended MQTT flex JSON config examples =

== Default NETIO MQTT-flex configuration ==
This example demonstrates setup for connection to public <code>broker.hivemq.com</code>, measurement reporting and output control.

The device cabe be controlled via <code>netio/${DEVICE_NAME}/output/1/action topic</code> by sending standard NETIO action values:
* 0 - OFF
* 1 - ON
* 2 - SHORT OFF
* 3 - SHORT ON
* 4 - TOGGLE
* 5 - NO ACTION.

The device report measurements:

* Output state - every 15 minutes or by change
* Voltage [V]- every 5 minutes or by change of 1 V
* Current [mA]- every 5 minutes or by change of 50 mA
* Load(Power) [W]- every 5 minutes or by change of 10 W
* Energy(Consumption) [Wh]- every 15 minutes or by change of 1Wh
* True Power Factor (TPF) [-]- every 5 minutes or by change of 0.02
* Frequency [Hz]- every 1 hour or by change of 0.1 Hz

For register all values, you can use wildcard <code>netio/${DEVICE_NAME}/output/1/#</code>

{
"config":{
"broker":{
"url":"broker.hivemq.com",
"protocol":"mqtt",
"port":1883,
"ssl":false,
"type":"generic",
"username":"",
"password":"",
"clientid":"moje${DEVICE_NAME}${DEVICE_MAC}",
"keepalive":30
},
"subscribe":[
{
"topic":"netio/${DEVICE_NAME}/output/1/action",
"qos":0,
"target":"OUTPUTS/1/ACTION",
"action":"${payload}"
},
{
"topic":"netio/${DEVICE_NAME}/output/1/switch",
"qos":0,
"target":"OUTPUTS/1/ACTION",
"action":4
}
],
"publish":[
{
"topic":"netio/${DEVICE_MAC}/output/1/state",
"qos":0,
"retain":true,
"payload":"${OUTPUTS/1/STATE}",
"events":[
{
"type":"change",
"source":"OUTPUTS/1/STATE"
},
{
"type":"timer",
"period":900
}
]
},
{
"topic":"netio/${DEVICE_NAME}/output/1/voltage",
"qos":0,
"retain":false,
"payload":"${OUTPUTS/1/VOLTAGE}",
"events":[
{
"type":"timer",
"period":300
},
{
"type":"delta",
"source":"OUTPUTS/1/VOLTAGE",
"delta":1
}
]
},
{
"topic":"netio/${DEVICE_NAME}/output/1/current",
"qos":0,
"retain":false,
"payload":"${OUTPUTS/1/CURRENT}",
"events":[
{
"type":"timer",
"period":300
},
{
"type":"delta",
"source":"OUTPUTS/1/CURRENT",
"delta":50
}
]
},
{
"topic":"netio/${DEVICE_NAME}/output/1/load",
"qos":0,
"retain":false,
"payload":"${OUTPUTS/1/LOAD}",
"events":[
{
"type":"timer",
"period":300
},
{
"type":"delta",
"source":"OUTPUTS/1/LOAD",
"delta":10
}
]
},
{
"topic":"netio/${DEVICE_NAME}/output/1/energy",
"qos":0,
"retain":false,
"payload":"${OUTPUTS/1/ENERGY}",
"events":[
{
"type":"timer",
"period":900
},
{
"type":"delta",
"source":"OUTPUTS/1/ENERGY",
"delta":1
}
]
},
{
"topic":"netio/${DEVICE_NAME}/output/1/tpf",
"qos":0,
"retain":false,
"payload":"${OUTPUTS/1/POWER_FACTOR}",
"events":[
{
"type":"timer",
"period":900
},
{
"type":"delta",
"source":"OUTPUTS/1/POWER_FACTOR",
"delta":0.02
}
]
},
{
"topic":"netio/${DEVICE_NAME}/output/1/frequency",
"qos":0,
"retain":false,
"payload":"${OUTPUTS/1/FREQUENCY}",
"events":[
{
"type":"timer",
"period":3600
},
{
"type":"delta",
"source":"OUTPUTS/1/FREQUENCY",
"delta":0.1
}
]
}
]
}
}

MQTT-flex

2023-06-06T14:01:54Z

Bbakala: /* Trigger Rule sequence from MQTT FW 4.0.0+ */

The MQTT-flex version of the MQTT protocol can be configured in detail thanks to the “flex” extension.

https://www.netio-products.com/en/glossary/mqtt-flex

Why MQTT-flex 
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 [https://en.wikipedia.org/wiki/MQTT 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 [https://en.wikipedia.org/wiki/JSON 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 101x 
* PowerCable REST 101x 
* PowerPDU 4PS 
* PowerPDU 4KS 
* PowerPDU 8QS 
* PowerDIN 4PZ 
* PowerBOX 3Px 
* PowerBOX 4Kx 

FW version: 
>2.2.1

===Not supported NETIO devices:===
* PowerPDU 4C 
* NETIO 4 
* NETIO 4All 

= Simple MQTT-flex configuration + explanation =

''We strongly recommend to create and test MQTT-flex configuration on "local" device what can be easily restarted. The validation of config before saving is not 100% and for example some specific typos can cause a freeze of a device - the solution is to restart a device (unplug/plug input power cable). If the configuration is saved and device is working then there are no known failure case so it is safe to use this configuration on the "remote" devices.''

{
"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":false,
"payload":"${OUTPUTS/1/STATE}",
"events":[
{
"type":"timer",
"period":"1000"
}
]
}
]
}
}
=== Client Configuration (broker section) ===
Put here MQTT client connection setup

This configuration example set NETIO device to connect to broker.hivemq.com with mqtt protocol, no ssl connection with credetials freedom/peace|love|empathy4ALL.

"broker":{
"url":"broker.hivemq.com",
"protocol":"mqtt",
"port":1883,
"ssl":false,
"type":"generic",
"username":"freedom",
"password":"peace|LOVE|empathy4ALL"
},

=== Device Control (subscribe section) ===
Put here array of topics where to subscribe

Device output 1 is controlled with action received by subscription to netio/${DEVICE_NAME}/output/1/action topic with QOS 0

"subscribe":[{
"topic":"netio/${DEVICE_NAME}/output/1/action",
"qos":0,
"target":"OUTPUTS/1/ACTION",
"action":"${payload}"
}
],

=== Output State monitoring (publish section) ===
Put here array of topics where to publish.

Device send every 1000 s message to topic with QOS 0, retain true information with output 1 state

"publish":[{
"topic":"netio/${DEVICE_NAME}/output/1/state",
"qos":0,
"retain":true,
"payload":"${OUTPUTS/1/STATE}",
"events":[
{
"type":"timer",
"period":"1000"
}
]
}
]

= 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 ===
{| class="wikitable"
! style="font-weight:bold; background-color:#9b9b9b;" | Item
! style="font-weight:bold; background-color:#9b9b9b;" | Presence
! style="font-weight:bold; background-color:#9b9b9b;" | Possible Values
! style="font-weight:bold; background-color:#9b9b9b;" | Description
! style="font-weight:bold; background-color:#9b9b9b;" | JSON Config Usage
|-
| style="background-color:#efefef;" | url
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" |
| style="background-color:#efefef;" | MQTT broker URL
| style="background-color:#efefef;" | "url":"broker.hivemq.com"
|-
| style="background-color:#efefef;" | port
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | 1 - 65535
| style="background-color:#efefef;" | MQTT broker port
| style="background-color:#efefef;" | "port":1883
|-
| style="background-color:#efefef;" | protocol
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" |
| style="background-color:#efefef;" | protocol spec - mqtt
| style="background-color:#efefef;" | "protocol": "mqtt"
|-
| style="background-color:#efefef;" | ssl
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | true, false
| style="background-color:#efefef;" | Use SSL crypted communication selector
| style="background-color:#efefef;" | "ssl":false
|-
| style="background-color:#efefef;" | type
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | generic
| style="background-color:#efefef;" | Communication/setup type option
| style="background-color:#efefef;" | "type":"generic"
|-
| style="background-color:#efefef;" | username
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | regexp+len
| style="background-color:#efefef;" | Credentials for MQTT broker. Max. 128 characters (since FW 3.2.4).
| style="background-color:#efefef;" | "username":"freedom"
|-
| style="background-color:#efefef;" | password
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | regexp+len
| style="background-color:#efefef;" | Credentials for MQTT broker. Max. 256 characters (since FW 3.2.4).
| style="background-color:#efefef;" | "password":"peace|LOVE|empathy4ALL"
|-
| style="background-color:#efefef;" | clientid
| style="background-color:#efefef;" | optional
| style="background-color:#efefef;" | regexp+len
| style="background-color:#efefef;" | MQTT clientid. Max. 128 characters (since FW 3.2.4). Variables ${DEVICE_MAC} or ${DEVICE_NAME} can be used
| style="background-color:#efefef;" | "clientid":"myEcoTable01"
|-
| style="background-color:#efefef;" | keepalive
| style="background-color:#efefef;" | optional
| style="background-color:#efefef;" | 1 - 65535
| style="background-color:#efefef;" | MQTT keep alive period in seconds
| style="background-color:#efefef;" | "keepalive":90
|}

Note 1: clientid attribute is mandatory for MQTT(s) communication. When not configured, random ID will be generated.

Note 2: To proper communication with MS Azure - it is necessary to set up IoT Hub to use TLS 1.2

See section "TLS 1.2 enforcement available in select regions" in following guidelines https://docs.microsoft.com/en-us/azure/iot-hub/iot-hub-tls-support

=== Examples ===
==== Standard setup ====

==== Security (SSL / TLS) secured setup ====
You can enable MQTTs by using the encrypted port 8883 + "ssl":true.

==== Variables used setup ====

== 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 ===
{| class="wikitable"
! style="font-weight:bold; background-color:#9b9b9b;" | Item
! style="font-weight:bold; background-color:#9b9b9b;" | Presence
! style="font-weight:bold; background-color:#9b9b9b;" | Possible Values
! style="font-weight:bold; background-color:#9b9b9b;" | Description
! style="font-weight:bold; background-color:#9b9b9b;" | JSON Config Usage
|-
| style="background-color:#efefef;" | topic
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | see table below
| style="background-color:#efefef;" | specification of the topic, which MQTT-flex device listens from broker and act accordingly. Max. 128 characters. The "#" can be used since FW 3.2.4 - see note under this table.
| style="background-color:#efefef;" | "topic":"netio/${DEVICE_NAME}/output/1/action"
|-
| style="background-color:#efefef;" | qos
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | 0, 1 or 2
| style="background-color:#efefef;" | 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}
| style="background-color:#efefef;" | "qos":0
|-
| style="background-color:#efefef;" | target
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" |
| style="background-color:#efefef;" | internal definition of action, which can be performed above the specified output
| style="background-color:#efefef;" | "target":"OUTPUTS/1/ACTION"
|-
| style="background-color:#efefef;" | action
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" |
| style="background-color:#efefef;" | a payload or a value the action attribute needs to have passed to
| style="background-color:#efefef;" | "action":"${payload}"
|-
| style="background-color:#efefef;" | actiondefNot supported yet
| style="background-color:#efefef;" | optional
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
|-
| style="background-color:#efefef;" | jsonNot supported yet
| style="background-color:#efefef;" | optional
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
|}

Note: The "#" wildcard can be used in subscribe topic definition. The multi-level wildcard character MUST be specified either on its own or following a topic level separator. In either case it MUST be the last character specified in the Topic.

For example, if a Device subscribes to “devices/{device_id}/messages/devicebound/#”, it would receive messages published using these topic names:

“devices/{device_id}/messages/devicebound/”

“devices/{device_id}/messages/devicebound/{property_bag}”

This should be usefull for use with MS Azure - IoT hub.

=== MQTT Subscribe as event to trigger action <code>FW 4.0.0+</code> ===

This feature allow to subscribe to specific MQTT topic and pass payload to Rules or MQTT-flex as event.

target: <code>PROTOCOLS/MQTT/EVENT</code>

"subscribe": [
{
"action": "${payload}",
"qos": 0,
"target": "PROTOCOLS/MQTT/EVENT",
"topic": "broker/12345/MQTT_EVENT/"
}
]

=== Examples ===
==== Toggle output with standard payload ====
==== Toggle output with custom payload ====
==== Subscribe to more than one topic ====
==== Trigger Rule sequence from MQTT <code>FW 4.0.0+</code> ====

Rules Configuration:
{
"conditions": {
"PROTOCOLS/MQTT/EVENT": "getValues"
},
"actions": {
"OUTPUTS/1/ACTION": 4
}
}

MQTT Configuration:
{
"broker":{
"clientid":"netio${DEVICE_SN}",
"keepalive":30,
"password":"goad7jbh326pr2ne",
"port":8883,
"protocol":"mqtt",
"ssl":true,
"type":"generic",
"url":"broker.cloud-dev.netio.eu",
"username":"gv90018g"
},
"groupEvents":[
{
"events":[
{
"source":"PROTOCOLS/MQTT/EVENT",
"type":"change",
"value":"getValues"
}
],
"appliedTopics":[
"broker/gv90018g/OUTPUTS/1/STATE",
"broker/gv90018g/COMMAND"
]
}
],
"publish":[
{
"payload":"${OUTPUTS/1/STATE}",
"qos":0,
"retain":true,
"topic":"broker/gv90018g/OUTPUTS/1/STATE"
},
{
"payload":"OK",
"qos":0,
"retain":true,
"topic":"broker/gv90018g/COMMAND"
}
],
"subscribe":[
{
"action":"${payload}",
"qos":0,
"target":"PROTOCOLS/MQTT/EVENT",
"topic":"broker/gv90018g/COMMAND"
}
]
}

==== Trigger MQTT publish by MQTT subscribe <code>FW 4.0.0+</code> ====

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 ===
{| class="wikitable"
! style="font-weight:bold; background-color:#9b9b9b;" | Item
! style="font-weight:bold; background-color:#9b9b9b;" | Presence
! style="font-weight:bold; background-color:#9b9b9b;" | Possible Values
! style="font-weight:bold; background-color:#9b9b9b;" | Description
! style="font-weight:bold; background-color:#9b9b9b;" | JSON Config Usage
|-
| style="background-color:#efefef;" | topic
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | see table below
| style="background-color:#efefef;" | definition of the topic, how it is registered towards MQTT broker. Max. 128 characters.
| style="background-color:#efefef;" | "topic":"netio/${DEVICE_NAME}/output/1/load"
|-
| style="background-color:#efefef;" | qos
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | see table below
| style="background-color:#efefef;" | 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}
| style="background-color:#efefef;" |
|-
| style="background-color:#efefef;" | retain
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | boolean: true or false
| style="background-color:#efefef;" | 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}
| style="background-color:#efefef;" | "retain":true
|-
| style="background-color:#efefef;" | payload
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | see table below
| style="background-color:#efefef;" | definition of the payload, what is send to the MQTT broker.
| style="background-color:#efefef;" | "payload":"${OUTPUTS/1/STATE}"
|-
| style="background-color:#efefef;" | events
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | see table below
| style="background-color:#efefef;" | definition of events used for triggering sending of data via mqtt (change, delta, timer)
| style="background-color:#efefef;" |
|-
| style="background-color:#efefef;" | type
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
|-
| style="background-color:#efefef;" | source
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
|-
| style="background-color:#efefef;" | delta
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
|-
| style="background-color:#efefef;" | period
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
|-
| style="background-color:#efefef;" | payloaddefNot supported yet
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
|}

=== Examples ===
==== Publish energy periodically (event timer) ====
==== Publish current on change (delta) ====
==== Publish output state ====
==== Publish to more than one topic with different events ====

= 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 available only on NETIO PowerDIN 4PZ

=== Examples: ===

adressing controll of output 3
OUTPUTS/3/ACTION
getting voltage on output 1
OUTPUTS/1/VOLTAGE
getting state of input 1
INPUTS/1/STATE

= Events =
==== Timer ====

==== Delta ====

==== Change ====

==== Group Events<code>FW 4.0.0+</code>====

= 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 ===
==== VOLTAGE ====
Unit: <code>V</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Present RMS voltage on output 1 is ${OUTPUTS/1/VOLTAGE}"</code>

Example 2: <code>"source":"${OUTPUTS/1/VOLTAGE}"</code>

==== CURRENT ====
Unit: <code>mA</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Present RMS current on output 1 is ${OUTPUTS/1/CURRENT}"</code>

Example 2: <code>"source":"${OUTPUTS/1/CURRENT}"</code>

==== POWER_FACTOR ====
Unit: <code>[-]</code>

Type: float (2 decimals)

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"True Power Factor on output 1 is ${OUTPUTS/1/POWER_FACTOR}"</code>

Example 2: <code>"source":"${OUTPUTS/1/POWER_FACTOR}"</code>

==== LOAD ====
Unit: <code>W</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Present load on output 1 is ${OUTPUTS/1/LOAD}W"</code>

Example 2: <code>"payload":"Device's load connected to output 1 is ${OUTPUTS/1/LOAD}W"</code>

Example 3: <code>"source":"${OUTPUTS/1/LOAD}"</code>

==== STATE ====
Type: bool(integer) - <code>0</code> or <code>1</code>

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Present output 1 state is ${OUTPUTS/1/STATE}"</code>

Example 2: <code>"source":"${OUTPUTS/1/STATE}"</code>

==== ACTION ====
Type: integer

Possible actions:
* <code>0</code> - set state OFF
* <code>1</code> - set state ON
* <code>2</code> - short OFF (restart)
* <code>3</code> - short ON
* <code>4</code> - toggle (switch)
* <code>5</code> - no change

Allowed in: <code>"target"</code>

Example: <code>"target":"OUTPUTS/1/ACTION"</code>

==== DELAY [ms] ====
==== NAME ====
==== FREQUENCY ====
Unit: <code>Hz</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example: <code>"payload":"Frequency in power grid is ${OUTPUTS/1/ENERGY}Hz"</code>

==== ENERGY ====
Energy consumed by an device connected to NETIO device output.

Unit: <code>Wh</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Consumed energy on output 1 is ${OUTPUTS/1/ENERGY}Wh"</code>

Example 2: <code>"source":"${OUTPUTS/1/ENERGY}"</code>

==== REVERSE_ENERGY ====
Energy delivered back to grid. For example from solar system connected to NETIO device output.

Unit: <code>Wh</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Delivered energy on output 1 is ${OUTPUTS/1/REVERSE_ENERGY}Wh"</code>

Example 2: <code>"source":"${OUTPUTS/1/REVERSE_ENERGY}"</code>

==== ENERGY_START ====
Date when the counters ENERGY and REVERSE_ENERGY have been resetted by user.

Unit: <code>unix timestamp</code>

Type: integer

Allowed in: <code>"payload"</code>

Example 1: <code>"payload":"Energy measured since ${OUTPUTS/1/ENERGY_START} unix time"</code>

Example 2: <code>"payload":"${OUTPUTS/1/ENERGY_START}"</code> is output payload <code>1567654639</code>

==== ENERGY_START_FMT ====
Date when the counters ENERGY and REVERSE_ENERGY have been resetted by user.

Unit: <code>fmt date format</code>

Type: string

Allowed in: <code>"payload"</code>

Example 1: <code>"payload":"Energy measured since ${OUTPUTS/1/ENERGY_START}"</code>

Example 2: <code>"payload":"${OUTPUTS/1/ENERGY_START_FMT}"</code> is output payload <code>2019-09-05T03:37:19+00:00</code>

==== ENERGY_NR ====
Non-resettable counter of Energy consumed by an device connected to NETIO device output.

Unit: <code>Wh</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Consumed energy on output 1 is ${OUTPUTS/1/ENERGY_NR}Wh"</code>

Example 2: <code>"source":"${OUTPUTS/1/ENERGY_NR}"</code>

==== REVERSE_ENERGY_NR ====
Non-resettable counter of Energy delivered back to grid. For example from solar system connected to NETIO device output.

Unit: <code>Wh</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Delivered energy on output 1 is ${OUTPUTS/1/REVERSE_ENERGY_NR}Wh"</code>

Example 2: <code>"source":"${OUTPUTS/1/REVERSE_ENERGY_NR}"</code>

==== TOTALs - for 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
* OUTPUTS/TOTAL/PHASE
* OUTPUTS/TOTAL/REVERSE_ENERGY
* OUTPUTS/TOTAL/ENERGY_NR
* OUTPUTS/TOTAL/REVERSE_ENERGY_NR
* OUTPUTS/TOTAL/ENERGY_START
* OUTPUTS/TOTAL/ENERGY_START_FMT

==== REST_JSON ====
Allow use of NETIO JSON structure to control outputs.

Type: string / JSON

Allowed in: <code>"target"</code> for Subscribe section

Example: <code>"target": "REST_JSON"</code>

The payload is JSON structure identical to NETIO JSON API M2M Protocol (documentation available at https://www.netio-products.com/files/NETIO-M2M-API-Protocol-JSON.pdf). You can control one or multiple outputs.

Payload example 1 - Toggle output 1: <code>{"Outputs":[{"ID": 1,"Action": 4}]}</code>

Payload example 2 - Turn output 1 OFF and output 3 ON: <code>{"Outputs":[{"ID":1,"Action":0},{"ID":3,"Action":1}]}</code>

=== INPUT variables ===
==== STATE ====
Type: bool(integer) - <code>0</code> or <code>1</code>

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Present input 1 state is ${INPUTS/1/STATE}"</code>

Example 2: <code>"source":"${INPUTS/1/STATE}"</code>

==== S0 ====
S0 Counter value
Unit: <code>-</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Input 1 S0 Counter value is ${INPUTS/1/S0}impulses"</code>

Example 2: <code>"source":"${INPUTS/1/S0}"</code>

== Payload/topic variables ==

=== DEVICE_NAME ===
Can be used in: "payload", "topic"

Example 1: <code>"payload":"${DEVICE_NAME}"</code>

Example 2: <code>"topic":"netio/${DEVICE_NAME}/output/1/action"</code>

=== DEVICE_MAC ===

=== UPTIME Not yet implemented ===

=== PAYLOAD ===
Can be used in: "action"

Example: <code>"action":"${PAYLOAD}"</code>

=== OUTPUT_ID Not yet implemented===

=== WIFI_SIGNALNot yet implemented ===

=== OUTPUTS_STATUS ===
Provide complete outputs status and measurement if supported.

Type: string / JSON

Allowed in: <code>"payload"</code> for Publish section

Example: <code>"payload":"${OUTPUTS_STATUS}"</code>

Payload example: <code>{ "GlobalMeasure":{"Voltage":236,"TotalCurrent":72,"TotalLoad":11,"TotalEnergy":167,"OverallPowerFactor":0.64,"Frequency":50.07,"Phase":-36.86,"EnergyStart":"2020-06-30T17:04:48+01:00"}, "Outputs":[ {"ID":1,"Name":"Power output 1","State":1,"Action":6,"Delay":2020,"Current":72,"PowerFactor":0.64,"Phase":-36.86,"Energy":139,"ReverseEnergy":0,"Load":11}, {"ID":2,"Name":"Power output 2","State":1,"Action":6,"Delay":2020,"Current":0,"PowerFactor":1.00,"Phase":0.00,"Energy":27,"ReverseEnergy":0,"Load":0}, {"ID":3,"Name":"Free Contact 3","State":1,"Action":6,"Delay":2020}, {"ID":4,"Name":"Free Contact 4","State":1,"Action":6,"Delay":2020} ]}</code>

=== INPUTS_STATUS ===
Provide complete inputs status if supported. Since FW 3.0.0

Type: string / JSON

Allowed in: <code>"payload"</code> for Publish section

Example: <code>"payload":"${INPUTS_STATUS}"</code>

Payload example: <code>{ "Inputs":[ {"ID":1,"Name":"Input 1","State":0,"S0Counter":0}, {"ID":2,"Name":"Input 2","State":0,"S0Counter":0} ]}</code>

=== INOUT_STATUS ===
Provide complete inputs and output status and measurement if supported. Since FW 3.0.0

Type: string / JSON

Allowed in: <code>"payload"</code> for Publish section

Example: <code>"payload":"${INOUT_STATUS}"</code>

Payload example: <code>{ "GlobalMeasure":{"Voltage":238,"TotalCurrent":105,"TotalLoad":17,"TotalEnergy":1451,"OverallPowerFactor":0.67,"Frequency":50.03,"Phase":-33.67,"EnergyStart":"2020-06-30T17:04:48+01:00"}, "Outputs":[ {"ID":1,"Name":"Power output 1","State":0,"Action":6,"Delay":5000,"Current":0,"PowerFactor":1.00,"Phase":0.00,"Energy":701,"ReverseEnergy":0,"Load":0}, {"ID":2,"Name":"Power output 2","State":1,"Action":6,"Delay":5000,"Current":105,"PowerFactor":0.65,"Phase":-33.67,"Energy":750,"ReverseEnergy":0,"Load":17}, {"ID":3,"Name":"Free Contact 3","State":1,"Action":6,"Delay":5000}, {"ID":4,"Name":"Free Contact 4","State":0,"Action":6,"Delay":5000} ], "Inputs":[ {"ID":1,"Name":"Input 1","State":0,"S0Counter":0}, {"ID":2,"Name":"Input 2","State":0,"S0Counter":0} ]}</code>

= Extended MQTT flex JSON config examples =

== Default NETIO MQTT-flex configuration ==
This example demonstrates setup for connection to public <code>broker.hivemq.com</code>, measurement reporting and output control.

The device cabe be controlled via <code>netio/${DEVICE_NAME}/output/1/action topic</code> by sending standard NETIO action values:
* 0 - OFF
* 1 - ON
* 2 - SHORT OFF
* 3 - SHORT ON
* 4 - TOGGLE
* 5 - NO ACTION.

The device report measurements:

* Output state - every 15 minutes or by change
* Voltage [V]- every 5 minutes or by change of 1 V
* Current [mA]- every 5 minutes or by change of 50 mA
* Load(Power) [W]- every 5 minutes or by change of 10 W
* Energy(Consumption) [Wh]- every 15 minutes or by change of 1Wh
* True Power Factor (TPF) [-]- every 5 minutes or by change of 0.02
* Frequency [Hz]- every 1 hour or by change of 0.1 Hz

For register all values, you can use wildcard <code>netio/${DEVICE_NAME}/output/1/#</code>

{
"config":{
"broker":{
"url":"broker.hivemq.com",
"protocol":"mqtt",
"port":1883,
"ssl":false,
"type":"generic",
"username":"",
"password":"",
"clientid":"moje${DEVICE_NAME}${DEVICE_MAC}",
"keepalive":30
},
"subscribe":[
{
"topic":"netio/${DEVICE_NAME}/output/1/action",
"qos":0,
"target":"OUTPUTS/1/ACTION",
"action":"${payload}"
},
{
"topic":"netio/${DEVICE_NAME}/output/1/switch",
"qos":0,
"target":"OUTPUTS/1/ACTION",
"action":4
}
],
"publish":[
{
"topic":"netio/${DEVICE_MAC}/output/1/state",
"qos":0,
"retain":true,
"payload":"${OUTPUTS/1/STATE}",
"events":[
{
"type":"change",
"source":"OUTPUTS/1/STATE"
},
{
"type":"timer",
"period":900
}
]
},
{
"topic":"netio/${DEVICE_NAME}/output/1/voltage",
"qos":0,
"retain":false,
"payload":"${OUTPUTS/1/VOLTAGE}",
"events":[
{
"type":"timer",
"period":300
},
{
"type":"delta",
"source":"OUTPUTS/1/VOLTAGE",
"delta":1
}
]
},
{
"topic":"netio/${DEVICE_NAME}/output/1/current",
"qos":0,
"retain":false,
"payload":"${OUTPUTS/1/CURRENT}",
"events":[
{
"type":"timer",
"period":300
},
{
"type":"delta",
"source":"OUTPUTS/1/CURRENT",
"delta":50
}
]
},
{
"topic":"netio/${DEVICE_NAME}/output/1/load",
"qos":0,
"retain":false,
"payload":"${OUTPUTS/1/LOAD}",
"events":[
{
"type":"timer",
"period":300
},
{
"type":"delta",
"source":"OUTPUTS/1/LOAD",
"delta":10
}
]
},
{
"topic":"netio/${DEVICE_NAME}/output/1/energy",
"qos":0,
"retain":false,
"payload":"${OUTPUTS/1/ENERGY}",
"events":[
{
"type":"timer",
"period":900
},
{
"type":"delta",
"source":"OUTPUTS/1/ENERGY",
"delta":1
}
]
},
{
"topic":"netio/${DEVICE_NAME}/output/1/tpf",
"qos":0,
"retain":false,
"payload":"${OUTPUTS/1/POWER_FACTOR}",
"events":[
{
"type":"timer",
"period":900
},
{
"type":"delta",
"source":"OUTPUTS/1/POWER_FACTOR",
"delta":0.02
}
]
},
{
"topic":"netio/${DEVICE_NAME}/output/1/frequency",
"qos":0,
"retain":false,
"payload":"${OUTPUTS/1/FREQUENCY}",
"events":[
{
"type":"timer",
"period":3600
},
{
"type":"delta",
"source":"OUTPUTS/1/FREQUENCY",
"delta":0.1
}
]
}
]
}
}

MQTT-flex

2023-06-06T13:59:46Z

Bbakala: /* Trigger Rule sequence from MQTT FW 4.0.0+ */

The MQTT-flex version of the MQTT protocol can be configured in detail thanks to the “flex” extension.

https://www.netio-products.com/en/glossary/mqtt-flex

Why MQTT-flex 
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 [https://en.wikipedia.org/wiki/MQTT 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 [https://en.wikipedia.org/wiki/JSON 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 101x 
* PowerCable REST 101x 
* PowerPDU 4PS 
* PowerPDU 4KS 
* PowerPDU 8QS 
* PowerDIN 4PZ 
* PowerBOX 3Px 
* PowerBOX 4Kx 

FW version: 
>2.2.1

===Not supported NETIO devices:===
* PowerPDU 4C 
* NETIO 4 
* NETIO 4All 

= Simple MQTT-flex configuration + explanation =

''We strongly recommend to create and test MQTT-flex configuration on "local" device what can be easily restarted. The validation of config before saving is not 100% and for example some specific typos can cause a freeze of a device - the solution is to restart a device (unplug/plug input power cable). If the configuration is saved and device is working then there are no known failure case so it is safe to use this configuration on the "remote" devices.''

{
"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":false,
"payload":"${OUTPUTS/1/STATE}",
"events":[
{
"type":"timer",
"period":"1000"
}
]
}
]
}
}
=== Client Configuration (broker section) ===
Put here MQTT client connection setup

This configuration example set NETIO device to connect to broker.hivemq.com with mqtt protocol, no ssl connection with credetials freedom/peace|love|empathy4ALL.

"broker":{
"url":"broker.hivemq.com",
"protocol":"mqtt",
"port":1883,
"ssl":false,
"type":"generic",
"username":"freedom",
"password":"peace|LOVE|empathy4ALL"
},

=== Device Control (subscribe section) ===
Put here array of topics where to subscribe

Device output 1 is controlled with action received by subscription to netio/${DEVICE_NAME}/output/1/action topic with QOS 0

"subscribe":[{
"topic":"netio/${DEVICE_NAME}/output/1/action",
"qos":0,
"target":"OUTPUTS/1/ACTION",
"action":"${payload}"
}
],

=== Output State monitoring (publish section) ===
Put here array of topics where to publish.

Device send every 1000 s message to topic with QOS 0, retain true information with output 1 state

"publish":[{
"topic":"netio/${DEVICE_NAME}/output/1/state",
"qos":0,
"retain":true,
"payload":"${OUTPUTS/1/STATE}",
"events":[
{
"type":"timer",
"period":"1000"
}
]
}
]

= 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 ===
{| class="wikitable"
! style="font-weight:bold; background-color:#9b9b9b;" | Item
! style="font-weight:bold; background-color:#9b9b9b;" | Presence
! style="font-weight:bold; background-color:#9b9b9b;" | Possible Values
! style="font-weight:bold; background-color:#9b9b9b;" | Description
! style="font-weight:bold; background-color:#9b9b9b;" | JSON Config Usage
|-
| style="background-color:#efefef;" | url
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" |
| style="background-color:#efefef;" | MQTT broker URL
| style="background-color:#efefef;" | "url":"broker.hivemq.com"
|-
| style="background-color:#efefef;" | port
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | 1 - 65535
| style="background-color:#efefef;" | MQTT broker port
| style="background-color:#efefef;" | "port":1883
|-
| style="background-color:#efefef;" | protocol
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" |
| style="background-color:#efefef;" | protocol spec - mqtt
| style="background-color:#efefef;" | "protocol": "mqtt"
|-
| style="background-color:#efefef;" | ssl
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | true, false
| style="background-color:#efefef;" | Use SSL crypted communication selector
| style="background-color:#efefef;" | "ssl":false
|-
| style="background-color:#efefef;" | type
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | generic
| style="background-color:#efefef;" | Communication/setup type option
| style="background-color:#efefef;" | "type":"generic"
|-
| style="background-color:#efefef;" | username
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | regexp+len
| style="background-color:#efefef;" | Credentials for MQTT broker. Max. 128 characters (since FW 3.2.4).
| style="background-color:#efefef;" | "username":"freedom"
|-
| style="background-color:#efefef;" | password
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | regexp+len
| style="background-color:#efefef;" | Credentials for MQTT broker. Max. 256 characters (since FW 3.2.4).
| style="background-color:#efefef;" | "password":"peace|LOVE|empathy4ALL"
|-
| style="background-color:#efefef;" | clientid
| style="background-color:#efefef;" | optional
| style="background-color:#efefef;" | regexp+len
| style="background-color:#efefef;" | MQTT clientid. Max. 128 characters (since FW 3.2.4). Variables ${DEVICE_MAC} or ${DEVICE_NAME} can be used
| style="background-color:#efefef;" | "clientid":"myEcoTable01"
|-
| style="background-color:#efefef;" | keepalive
| style="background-color:#efefef;" | optional
| style="background-color:#efefef;" | 1 - 65535
| style="background-color:#efefef;" | MQTT keep alive period in seconds
| style="background-color:#efefef;" | "keepalive":90
|}

Note 1: clientid attribute is mandatory for MQTT(s) communication. When not configured, random ID will be generated.

Note 2: To proper communication with MS Azure - it is necessary to set up IoT Hub to use TLS 1.2

See section "TLS 1.2 enforcement available in select regions" in following guidelines https://docs.microsoft.com/en-us/azure/iot-hub/iot-hub-tls-support

=== Examples ===
==== Standard setup ====

==== Security (SSL / TLS) secured setup ====
You can enable MQTTs by using the encrypted port 8883 + "ssl":true.

==== Variables used setup ====

== 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 ===
{| class="wikitable"
! style="font-weight:bold; background-color:#9b9b9b;" | Item
! style="font-weight:bold; background-color:#9b9b9b;" | Presence
! style="font-weight:bold; background-color:#9b9b9b;" | Possible Values
! style="font-weight:bold; background-color:#9b9b9b;" | Description
! style="font-weight:bold; background-color:#9b9b9b;" | JSON Config Usage
|-
| style="background-color:#efefef;" | topic
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | see table below
| style="background-color:#efefef;" | specification of the topic, which MQTT-flex device listens from broker and act accordingly. Max. 128 characters. The "#" can be used since FW 3.2.4 - see note under this table.
| style="background-color:#efefef;" | "topic":"netio/${DEVICE_NAME}/output/1/action"
|-
| style="background-color:#efefef;" | qos
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | 0, 1 or 2
| style="background-color:#efefef;" | 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}
| style="background-color:#efefef;" | "qos":0
|-
| style="background-color:#efefef;" | target
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" |
| style="background-color:#efefef;" | internal definition of action, which can be performed above the specified output
| style="background-color:#efefef;" | "target":"OUTPUTS/1/ACTION"
|-
| style="background-color:#efefef;" | action
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" |
| style="background-color:#efefef;" | a payload or a value the action attribute needs to have passed to
| style="background-color:#efefef;" | "action":"${payload}"
|-
| style="background-color:#efefef;" | actiondefNot supported yet
| style="background-color:#efefef;" | optional
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
|-
| style="background-color:#efefef;" | jsonNot supported yet
| style="background-color:#efefef;" | optional
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
|}

Note: The "#" wildcard can be used in subscribe topic definition. The multi-level wildcard character MUST be specified either on its own or following a topic level separator. In either case it MUST be the last character specified in the Topic.

For example, if a Device subscribes to “devices/{device_id}/messages/devicebound/#”, it would receive messages published using these topic names:

“devices/{device_id}/messages/devicebound/”

“devices/{device_id}/messages/devicebound/{property_bag}”

This should be usefull for use with MS Azure - IoT hub.

=== MQTT Subscribe as event to trigger action <code>FW 4.0.0+</code> ===

This feature allow to subscribe to specific MQTT topic and pass payload to Rules or MQTT-flex as event.

target: <code>PROTOCOLS/MQTT/EVENT</code>

"subscribe": [
{
"action": "${payload}",
"qos": 0,
"target": "PROTOCOLS/MQTT/EVENT",
"topic": "broker/12345/MQTT_EVENT/"
}
]

=== Examples ===
==== Toggle output with standard payload ====
==== Toggle output with custom payload ====
==== Subscribe to more than one topic ====
==== Trigger Rule sequence from MQTT <code>FW 4.0.0+</code> ====

Rules Configuration:
{
"conditions": {
"PROTOCOLS/MQTT/EVENT": "getValues"
},
"actions": {
"OUTPUTS/1/ACTION": 4
}
}

MQTT Configuration:
{
"broker":{
"clientid":"netio${DEVICE_SN}",
"keepalive":30,
"password":"goad7jbh326pr2ne",
"port":8883,
"protocol":"mqtt",
"ssl":true,
"type":"generic",
"url":"broker.cloud-dev.netio.eu",
"username":"gv90018g"
},
"groupEvents":[
{
"events":[
{
"source":"PROTOCOLS/MQTT/EVENT",
"type":"change",
"value":"getValues"
}
],
"appliedTopics":[
"broker/gv90018g/TOTAL/ENERGY/",
"broker/gv90018g//TOTAL/LOAD/",
"broker/gv90018g/OUTPUTS/1/STATE",
"broker/gv90018g/OUTPUTS/2/STATE",
"broker/gv90018g/OUTPUTS/3/STATE",
"broker/gv90018g/OUTPUTS/4/STATE",
"broker/gv90018g/INPUTS/1/STATE",
"broker/gv90018g/INPUTS/1/STATE",
"broker/gv90018g/COMMAND"
]
}
],
"publish":[
{
"payload":"${OUTPUTS/TOTAL/ENERGY}",
"qos":0,
"retain":false,
"topic":"broker/gv90018g/TOTAL/ENERGY/"
},
{
"payload":"${OUTPUTS/TOTAL/LOAD}",
"qos":0,
"retain":false,
"topic":"broker/gv90018g/TOTAL/LOAD/"
},
{
"payload":"${OUTPUTS/1/STATE}",
"qos":0,
"retain":true,
"topic":"broker/gv90018g/OUTPUTS/1/STATE"
},
{
"payload":"${OUTPUTS/2/STATE}",
"qos":0,
"retain":true,
"topic":"broker/gv90018g/OUTPUTS/2/STATE"
},
{
"payload":"${OUTPUTS/3/STATE}",
"qos":0,
"retain":true,
"topic":"broker/gv90018g/OUTPUTS/3/STATE"
},
{
"payload":"${OUTPUTS/4/STATE}",
"qos":0,
"retain":true,
"topic":"broker/gv90018g/OUTPUTS/4/STATE"
},
{
"payload":"${INPUTS/1/STATE}",
"qos":0,
"retain":true,
"topic":"broker/gv90018g/INPUTS/1/STATE"
},
{
"payload":"${INPUTS/1/STATE}",
"qos":0,
"retain":true,
"topic":"broker/gv90018g/INPUTS/1/STATE"
},
{
"payload":"OK",
"qos":0,
"retain":true,
"topic":"broker/gv90018g/COMMAND"
}
],
"subscribe":[
{
"action":"${payload}",
"qos":0,
"target":"PROTOCOLS/MQTT/EVENT",
"topic":"broker/gv90018g/COMMAND"
}
]
}

==== Trigger MQTT publish by MQTT subscribe <code>FW 4.0.0+</code> ====

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 ===
{| class="wikitable"
! style="font-weight:bold; background-color:#9b9b9b;" | Item
! style="font-weight:bold; background-color:#9b9b9b;" | Presence
! style="font-weight:bold; background-color:#9b9b9b;" | Possible Values
! style="font-weight:bold; background-color:#9b9b9b;" | Description
! style="font-weight:bold; background-color:#9b9b9b;" | JSON Config Usage
|-
| style="background-color:#efefef;" | topic
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | see table below
| style="background-color:#efefef;" | definition of the topic, how it is registered towards MQTT broker. Max. 128 characters.
| style="background-color:#efefef;" | "topic":"netio/${DEVICE_NAME}/output/1/load"
|-
| style="background-color:#efefef;" | qos
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | see table below
| style="background-color:#efefef;" | 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}
| style="background-color:#efefef;" |
|-
| style="background-color:#efefef;" | retain
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | boolean: true or false
| style="background-color:#efefef;" | 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}
| style="background-color:#efefef;" | "retain":true
|-
| style="background-color:#efefef;" | payload
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | see table below
| style="background-color:#efefef;" | definition of the payload, what is send to the MQTT broker.
| style="background-color:#efefef;" | "payload":"${OUTPUTS/1/STATE}"
|-
| style="background-color:#efefef;" | events
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | see table below
| style="background-color:#efefef;" | definition of events used for triggering sending of data via mqtt (change, delta, timer)
| style="background-color:#efefef;" |
|-
| style="background-color:#efefef;" | type
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
|-
| style="background-color:#efefef;" | source
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
|-
| style="background-color:#efefef;" | delta
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
|-
| style="background-color:#efefef;" | period
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
|-
| style="background-color:#efefef;" | payloaddefNot supported yet
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
|}

=== Examples ===
==== Publish energy periodically (event timer) ====
==== Publish current on change (delta) ====
==== Publish output state ====
==== Publish to more than one topic with different events ====

= 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 available only on NETIO PowerDIN 4PZ

=== Examples: ===

adressing controll of output 3
OUTPUTS/3/ACTION
getting voltage on output 1
OUTPUTS/1/VOLTAGE
getting state of input 1
INPUTS/1/STATE

= Events =
==== Timer ====

==== Delta ====

==== Change ====

==== Group Events<code>FW 4.0.0+</code>====

= 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 ===
==== VOLTAGE ====
Unit: <code>V</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Present RMS voltage on output 1 is ${OUTPUTS/1/VOLTAGE}"</code>

Example 2: <code>"source":"${OUTPUTS/1/VOLTAGE}"</code>

==== CURRENT ====
Unit: <code>mA</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Present RMS current on output 1 is ${OUTPUTS/1/CURRENT}"</code>

Example 2: <code>"source":"${OUTPUTS/1/CURRENT}"</code>

==== POWER_FACTOR ====
Unit: <code>[-]</code>

Type: float (2 decimals)

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"True Power Factor on output 1 is ${OUTPUTS/1/POWER_FACTOR}"</code>

Example 2: <code>"source":"${OUTPUTS/1/POWER_FACTOR}"</code>

==== LOAD ====
Unit: <code>W</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Present load on output 1 is ${OUTPUTS/1/LOAD}W"</code>

Example 2: <code>"payload":"Device's load connected to output 1 is ${OUTPUTS/1/LOAD}W"</code>

Example 3: <code>"source":"${OUTPUTS/1/LOAD}"</code>

==== STATE ====
Type: bool(integer) - <code>0</code> or <code>1</code>

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Present output 1 state is ${OUTPUTS/1/STATE}"</code>

Example 2: <code>"source":"${OUTPUTS/1/STATE}"</code>

==== ACTION ====
Type: integer

Possible actions:
* <code>0</code> - set state OFF
* <code>1</code> - set state ON
* <code>2</code> - short OFF (restart)
* <code>3</code> - short ON
* <code>4</code> - toggle (switch)
* <code>5</code> - no change

Allowed in: <code>"target"</code>

Example: <code>"target":"OUTPUTS/1/ACTION"</code>

==== DELAY [ms] ====
==== NAME ====
==== FREQUENCY ====
Unit: <code>Hz</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example: <code>"payload":"Frequency in power grid is ${OUTPUTS/1/ENERGY}Hz"</code>

==== ENERGY ====
Energy consumed by an device connected to NETIO device output.

Unit: <code>Wh</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Consumed energy on output 1 is ${OUTPUTS/1/ENERGY}Wh"</code>

Example 2: <code>"source":"${OUTPUTS/1/ENERGY}"</code>

==== REVERSE_ENERGY ====
Energy delivered back to grid. For example from solar system connected to NETIO device output.

Unit: <code>Wh</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Delivered energy on output 1 is ${OUTPUTS/1/REVERSE_ENERGY}Wh"</code>

Example 2: <code>"source":"${OUTPUTS/1/REVERSE_ENERGY}"</code>

==== ENERGY_START ====
Date when the counters ENERGY and REVERSE_ENERGY have been resetted by user.

Unit: <code>unix timestamp</code>

Type: integer

Allowed in: <code>"payload"</code>

Example 1: <code>"payload":"Energy measured since ${OUTPUTS/1/ENERGY_START} unix time"</code>

Example 2: <code>"payload":"${OUTPUTS/1/ENERGY_START}"</code> is output payload <code>1567654639</code>

==== ENERGY_START_FMT ====
Date when the counters ENERGY and REVERSE_ENERGY have been resetted by user.

Unit: <code>fmt date format</code>

Type: string

Allowed in: <code>"payload"</code>

Example 1: <code>"payload":"Energy measured since ${OUTPUTS/1/ENERGY_START}"</code>

Example 2: <code>"payload":"${OUTPUTS/1/ENERGY_START_FMT}"</code> is output payload <code>2019-09-05T03:37:19+00:00</code>

==== ENERGY_NR ====
Non-resettable counter of Energy consumed by an device connected to NETIO device output.

Unit: <code>Wh</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Consumed energy on output 1 is ${OUTPUTS/1/ENERGY_NR}Wh"</code>

Example 2: <code>"source":"${OUTPUTS/1/ENERGY_NR}"</code>

==== REVERSE_ENERGY_NR ====
Non-resettable counter of Energy delivered back to grid. For example from solar system connected to NETIO device output.

Unit: <code>Wh</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Delivered energy on output 1 is ${OUTPUTS/1/REVERSE_ENERGY_NR}Wh"</code>

Example 2: <code>"source":"${OUTPUTS/1/REVERSE_ENERGY_NR}"</code>

==== TOTALs - for 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
* OUTPUTS/TOTAL/PHASE
* OUTPUTS/TOTAL/REVERSE_ENERGY
* OUTPUTS/TOTAL/ENERGY_NR
* OUTPUTS/TOTAL/REVERSE_ENERGY_NR
* OUTPUTS/TOTAL/ENERGY_START
* OUTPUTS/TOTAL/ENERGY_START_FMT

==== REST_JSON ====
Allow use of NETIO JSON structure to control outputs.

Type: string / JSON

Allowed in: <code>"target"</code> for Subscribe section

Example: <code>"target": "REST_JSON"</code>

The payload is JSON structure identical to NETIO JSON API M2M Protocol (documentation available at https://www.netio-products.com/files/NETIO-M2M-API-Protocol-JSON.pdf). You can control one or multiple outputs.

Payload example 1 - Toggle output 1: <code>{"Outputs":[{"ID": 1,"Action": 4}]}</code>

Payload example 2 - Turn output 1 OFF and output 3 ON: <code>{"Outputs":[{"ID":1,"Action":0},{"ID":3,"Action":1}]}</code>

=== INPUT variables ===
==== STATE ====
Type: bool(integer) - <code>0</code> or <code>1</code>

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Present input 1 state is ${INPUTS/1/STATE}"</code>

Example 2: <code>"source":"${INPUTS/1/STATE}"</code>

==== S0 ====
S0 Counter value
Unit: <code>-</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Input 1 S0 Counter value is ${INPUTS/1/S0}impulses"</code>

Example 2: <code>"source":"${INPUTS/1/S0}"</code>

== Payload/topic variables ==

=== DEVICE_NAME ===
Can be used in: "payload", "topic"

Example 1: <code>"payload":"${DEVICE_NAME}"</code>

Example 2: <code>"topic":"netio/${DEVICE_NAME}/output/1/action"</code>

=== DEVICE_MAC ===

=== UPTIME Not yet implemented ===

=== PAYLOAD ===
Can be used in: "action"

Example: <code>"action":"${PAYLOAD}"</code>

=== OUTPUT_ID Not yet implemented===

=== WIFI_SIGNALNot yet implemented ===

=== OUTPUTS_STATUS ===
Provide complete outputs status and measurement if supported.

Type: string / JSON

Allowed in: <code>"payload"</code> for Publish section

Example: <code>"payload":"${OUTPUTS_STATUS}"</code>

Payload example: <code>{ "GlobalMeasure":{"Voltage":236,"TotalCurrent":72,"TotalLoad":11,"TotalEnergy":167,"OverallPowerFactor":0.64,"Frequency":50.07,"Phase":-36.86,"EnergyStart":"2020-06-30T17:04:48+01:00"}, "Outputs":[ {"ID":1,"Name":"Power output 1","State":1,"Action":6,"Delay":2020,"Current":72,"PowerFactor":0.64,"Phase":-36.86,"Energy":139,"ReverseEnergy":0,"Load":11}, {"ID":2,"Name":"Power output 2","State":1,"Action":6,"Delay":2020,"Current":0,"PowerFactor":1.00,"Phase":0.00,"Energy":27,"ReverseEnergy":0,"Load":0}, {"ID":3,"Name":"Free Contact 3","State":1,"Action":6,"Delay":2020}, {"ID":4,"Name":"Free Contact 4","State":1,"Action":6,"Delay":2020} ]}</code>

=== INPUTS_STATUS ===
Provide complete inputs status if supported. Since FW 3.0.0

Type: string / JSON

Allowed in: <code>"payload"</code> for Publish section

Example: <code>"payload":"${INPUTS_STATUS}"</code>

Payload example: <code>{ "Inputs":[ {"ID":1,"Name":"Input 1","State":0,"S0Counter":0}, {"ID":2,"Name":"Input 2","State":0,"S0Counter":0} ]}</code>

=== INOUT_STATUS ===
Provide complete inputs and output status and measurement if supported. Since FW 3.0.0

Type: string / JSON

Allowed in: <code>"payload"</code> for Publish section

Example: <code>"payload":"${INOUT_STATUS}"</code>

Payload example: <code>{ "GlobalMeasure":{"Voltage":238,"TotalCurrent":105,"TotalLoad":17,"TotalEnergy":1451,"OverallPowerFactor":0.67,"Frequency":50.03,"Phase":-33.67,"EnergyStart":"2020-06-30T17:04:48+01:00"}, "Outputs":[ {"ID":1,"Name":"Power output 1","State":0,"Action":6,"Delay":5000,"Current":0,"PowerFactor":1.00,"Phase":0.00,"Energy":701,"ReverseEnergy":0,"Load":0}, {"ID":2,"Name":"Power output 2","State":1,"Action":6,"Delay":5000,"Current":105,"PowerFactor":0.65,"Phase":-33.67,"Energy":750,"ReverseEnergy":0,"Load":17}, {"ID":3,"Name":"Free Contact 3","State":1,"Action":6,"Delay":5000}, {"ID":4,"Name":"Free Contact 4","State":0,"Action":6,"Delay":5000} ], "Inputs":[ {"ID":1,"Name":"Input 1","State":0,"S0Counter":0}, {"ID":2,"Name":"Input 2","State":0,"S0Counter":0} ]}</code>

= Extended MQTT flex JSON config examples =

== Default NETIO MQTT-flex configuration ==
This example demonstrates setup for connection to public <code>broker.hivemq.com</code>, measurement reporting and output control.

The device cabe be controlled via <code>netio/${DEVICE_NAME}/output/1/action topic</code> by sending standard NETIO action values:
* 0 - OFF
* 1 - ON
* 2 - SHORT OFF
* 3 - SHORT ON
* 4 - TOGGLE
* 5 - NO ACTION.

The device report measurements:

* Output state - every 15 minutes or by change
* Voltage [V]- every 5 minutes or by change of 1 V
* Current [mA]- every 5 minutes or by change of 50 mA
* Load(Power) [W]- every 5 minutes or by change of 10 W
* Energy(Consumption) [Wh]- every 15 minutes or by change of 1Wh
* True Power Factor (TPF) [-]- every 5 minutes or by change of 0.02
* Frequency [Hz]- every 1 hour or by change of 0.1 Hz

For register all values, you can use wildcard <code>netio/${DEVICE_NAME}/output/1/#</code>

{
"config":{
"broker":{
"url":"broker.hivemq.com",
"protocol":"mqtt",
"port":1883,
"ssl":false,
"type":"generic",
"username":"",
"password":"",
"clientid":"moje${DEVICE_NAME}${DEVICE_MAC}",
"keepalive":30
},
"subscribe":[
{
"topic":"netio/${DEVICE_NAME}/output/1/action",
"qos":0,
"target":"OUTPUTS/1/ACTION",
"action":"${payload}"
},
{
"topic":"netio/${DEVICE_NAME}/output/1/switch",
"qos":0,
"target":"OUTPUTS/1/ACTION",
"action":4
}
],
"publish":[
{
"topic":"netio/${DEVICE_MAC}/output/1/state",
"qos":0,
"retain":true,
"payload":"${OUTPUTS/1/STATE}",
"events":[
{
"type":"change",
"source":"OUTPUTS/1/STATE"
},
{
"type":"timer",
"period":900
}
]
},
{
"topic":"netio/${DEVICE_NAME}/output/1/voltage",
"qos":0,
"retain":false,
"payload":"${OUTPUTS/1/VOLTAGE}",
"events":[
{
"type":"timer",
"period":300
},
{
"type":"delta",
"source":"OUTPUTS/1/VOLTAGE",
"delta":1
}
]
},
{
"topic":"netio/${DEVICE_NAME}/output/1/current",
"qos":0,
"retain":false,
"payload":"${OUTPUTS/1/CURRENT}",
"events":[
{
"type":"timer",
"period":300
},
{
"type":"delta",
"source":"OUTPUTS/1/CURRENT",
"delta":50
}
]
},
{
"topic":"netio/${DEVICE_NAME}/output/1/load",
"qos":0,
"retain":false,
"payload":"${OUTPUTS/1/LOAD}",
"events":[
{
"type":"timer",
"period":300
},
{
"type":"delta",
"source":"OUTPUTS/1/LOAD",
"delta":10
}
]
},
{
"topic":"netio/${DEVICE_NAME}/output/1/energy",
"qos":0,
"retain":false,
"payload":"${OUTPUTS/1/ENERGY}",
"events":[
{
"type":"timer",
"period":900
},
{
"type":"delta",
"source":"OUTPUTS/1/ENERGY",
"delta":1
}
]
},
{
"topic":"netio/${DEVICE_NAME}/output/1/tpf",
"qos":0,
"retain":false,
"payload":"${OUTPUTS/1/POWER_FACTOR}",
"events":[
{
"type":"timer",
"period":900
},
{
"type":"delta",
"source":"OUTPUTS/1/POWER_FACTOR",
"delta":0.02
}
]
},
{
"topic":"netio/${DEVICE_NAME}/output/1/frequency",
"qos":0,
"retain":false,
"payload":"${OUTPUTS/1/FREQUENCY}",
"events":[
{
"type":"timer",
"period":3600
},
{
"type":"delta",
"source":"OUTPUTS/1/FREQUENCY",
"delta":0.1
}
]
}
]
}
}

MQTT-flex

2023-06-06T13:58:25Z

Bbakala: /* Trigger Rule sequence from MQTT FW 4.0.0+ */

The MQTT-flex version of the MQTT protocol can be configured in detail thanks to the “flex” extension.

https://www.netio-products.com/en/glossary/mqtt-flex

Why MQTT-flex 
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 [https://en.wikipedia.org/wiki/MQTT 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 [https://en.wikipedia.org/wiki/JSON 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 101x 
* PowerCable REST 101x 
* PowerPDU 4PS 
* PowerPDU 4KS 
* PowerPDU 8QS 
* PowerDIN 4PZ 
* PowerBOX 3Px 
* PowerBOX 4Kx 

FW version: 
>2.2.1

===Not supported NETIO devices:===
* PowerPDU 4C 
* NETIO 4 
* NETIO 4All 

= Simple MQTT-flex configuration + explanation =

''We strongly recommend to create and test MQTT-flex configuration on "local" device what can be easily restarted. The validation of config before saving is not 100% and for example some specific typos can cause a freeze of a device - the solution is to restart a device (unplug/plug input power cable). If the configuration is saved and device is working then there are no known failure case so it is safe to use this configuration on the "remote" devices.''

{
"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":false,
"payload":"${OUTPUTS/1/STATE}",
"events":[
{
"type":"timer",
"period":"1000"
}
]
}
]
}
}
=== Client Configuration (broker section) ===
Put here MQTT client connection setup

This configuration example set NETIO device to connect to broker.hivemq.com with mqtt protocol, no ssl connection with credetials freedom/peace|love|empathy4ALL.

"broker":{
"url":"broker.hivemq.com",
"protocol":"mqtt",
"port":1883,
"ssl":false,
"type":"generic",
"username":"freedom",
"password":"peace|LOVE|empathy4ALL"
},

=== Device Control (subscribe section) ===
Put here array of topics where to subscribe

Device output 1 is controlled with action received by subscription to netio/${DEVICE_NAME}/output/1/action topic with QOS 0

"subscribe":[{
"topic":"netio/${DEVICE_NAME}/output/1/action",
"qos":0,
"target":"OUTPUTS/1/ACTION",
"action":"${payload}"
}
],

=== Output State monitoring (publish section) ===
Put here array of topics where to publish.

Device send every 1000 s message to topic with QOS 0, retain true information with output 1 state

"publish":[{
"topic":"netio/${DEVICE_NAME}/output/1/state",
"qos":0,
"retain":true,
"payload":"${OUTPUTS/1/STATE}",
"events":[
{
"type":"timer",
"period":"1000"
}
]
}
]

= 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 ===
{| class="wikitable"
! style="font-weight:bold; background-color:#9b9b9b;" | Item
! style="font-weight:bold; background-color:#9b9b9b;" | Presence
! style="font-weight:bold; background-color:#9b9b9b;" | Possible Values
! style="font-weight:bold; background-color:#9b9b9b;" | Description
! style="font-weight:bold; background-color:#9b9b9b;" | JSON Config Usage
|-
| style="background-color:#efefef;" | url
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" |
| style="background-color:#efefef;" | MQTT broker URL
| style="background-color:#efefef;" | "url":"broker.hivemq.com"
|-
| style="background-color:#efefef;" | port
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | 1 - 65535
| style="background-color:#efefef;" | MQTT broker port
| style="background-color:#efefef;" | "port":1883
|-
| style="background-color:#efefef;" | protocol
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" |
| style="background-color:#efefef;" | protocol spec - mqtt
| style="background-color:#efefef;" | "protocol": "mqtt"
|-
| style="background-color:#efefef;" | ssl
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | true, false
| style="background-color:#efefef;" | Use SSL crypted communication selector
| style="background-color:#efefef;" | "ssl":false
|-
| style="background-color:#efefef;" | type
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | generic
| style="background-color:#efefef;" | Communication/setup type option
| style="background-color:#efefef;" | "type":"generic"
|-
| style="background-color:#efefef;" | username
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | regexp+len
| style="background-color:#efefef;" | Credentials for MQTT broker. Max. 128 characters (since FW 3.2.4).
| style="background-color:#efefef;" | "username":"freedom"
|-
| style="background-color:#efefef;" | password
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | regexp+len
| style="background-color:#efefef;" | Credentials for MQTT broker. Max. 256 characters (since FW 3.2.4).
| style="background-color:#efefef;" | "password":"peace|LOVE|empathy4ALL"
|-
| style="background-color:#efefef;" | clientid
| style="background-color:#efefef;" | optional
| style="background-color:#efefef;" | regexp+len
| style="background-color:#efefef;" | MQTT clientid. Max. 128 characters (since FW 3.2.4). Variables ${DEVICE_MAC} or ${DEVICE_NAME} can be used
| style="background-color:#efefef;" | "clientid":"myEcoTable01"
|-
| style="background-color:#efefef;" | keepalive
| style="background-color:#efefef;" | optional
| style="background-color:#efefef;" | 1 - 65535
| style="background-color:#efefef;" | MQTT keep alive period in seconds
| style="background-color:#efefef;" | "keepalive":90
|}

Note 1: clientid attribute is mandatory for MQTT(s) communication. When not configured, random ID will be generated.

Note 2: To proper communication with MS Azure - it is necessary to set up IoT Hub to use TLS 1.2

See section "TLS 1.2 enforcement available in select regions" in following guidelines https://docs.microsoft.com/en-us/azure/iot-hub/iot-hub-tls-support

=== Examples ===
==== Standard setup ====

==== Security (SSL / TLS) secured setup ====
You can enable MQTTs by using the encrypted port 8883 + "ssl":true.

==== Variables used setup ====

== 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 ===
{| class="wikitable"
! style="font-weight:bold; background-color:#9b9b9b;" | Item
! style="font-weight:bold; background-color:#9b9b9b;" | Presence
! style="font-weight:bold; background-color:#9b9b9b;" | Possible Values
! style="font-weight:bold; background-color:#9b9b9b;" | Description
! style="font-weight:bold; background-color:#9b9b9b;" | JSON Config Usage
|-
| style="background-color:#efefef;" | topic
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | see table below
| style="background-color:#efefef;" | specification of the topic, which MQTT-flex device listens from broker and act accordingly. Max. 128 characters. The "#" can be used since FW 3.2.4 - see note under this table.
| style="background-color:#efefef;" | "topic":"netio/${DEVICE_NAME}/output/1/action"
|-
| style="background-color:#efefef;" | qos
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | 0, 1 or 2
| style="background-color:#efefef;" | 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}
| style="background-color:#efefef;" | "qos":0
|-
| style="background-color:#efefef;" | target
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" |
| style="background-color:#efefef;" | internal definition of action, which can be performed above the specified output
| style="background-color:#efefef;" | "target":"OUTPUTS/1/ACTION"
|-
| style="background-color:#efefef;" | action
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" |
| style="background-color:#efefef;" | a payload or a value the action attribute needs to have passed to
| style="background-color:#efefef;" | "action":"${payload}"
|-
| style="background-color:#efefef;" | actiondefNot supported yet
| style="background-color:#efefef;" | optional
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
|-
| style="background-color:#efefef;" | jsonNot supported yet
| style="background-color:#efefef;" | optional
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
|}

Note: The "#" wildcard can be used in subscribe topic definition. The multi-level wildcard character MUST be specified either on its own or following a topic level separator. In either case it MUST be the last character specified in the Topic.

For example, if a Device subscribes to “devices/{device_id}/messages/devicebound/#”, it would receive messages published using these topic names:

“devices/{device_id}/messages/devicebound/”

“devices/{device_id}/messages/devicebound/{property_bag}”

This should be usefull for use with MS Azure - IoT hub.

=== MQTT Subscribe as event to trigger action <code>FW 4.0.0+</code> ===

This feature allow to subscribe to specific MQTT topic and pass payload to Rules or MQTT-flex as event.

target: <code>PROTOCOLS/MQTT/EVENT</code>

"subscribe": [
{
"action": "${payload}",
"qos": 0,
"target": "PROTOCOLS/MQTT/EVENT",
"topic": "broker/12345/MQTT_EVENT/"
}
]

=== Examples ===
==== Toggle output with standard payload ====
==== Toggle output with custom payload ====
==== Subscribe to more than one topic ====
==== Trigger Rule sequence from MQTT <code>FW 4.0.0+</code> ====

====== Rules Configuration: ======
{
"conditions": {
"PROTOCOLS/MQTT/EVENT": "getValues"
},
"actions": {
"OUTPUTS/1/ACTION": 4
}
}

====== MQTT Configuration: ======
{
"broker":{
"clientid":"netio${DEVICE_SN}",
"keepalive":30,
"password":"goad7jbh326pr2ne",
"port":8883,
"protocol":"mqtt",
"ssl":true,
"type":"generic",
"url":"broker.cloud-dev.netio.eu",
"username":"gv90018g"
},
"groupEvents":[
{
"events":[
{
"source":"PROTOCOLS/MQTT/EVENT",
"type":"change",
"value":"getValues"
}
],
"appliedTopics":[
"broker/gv90018g/TOTAL/ENERGY/",
"broker/gv90018g//TOTAL/LOAD/",
"broker/gv90018g/OUTPUTS/1/STATE",
"broker/gv90018g/OUTPUTS/2/STATE",
"broker/gv90018g/OUTPUTS/3/STATE",
"broker/gv90018g/OUTPUTS/4/STATE",
"broker/gv90018g/INPUTS/1/STATE",
"broker/gv90018g/INPUTS/1/STATE",
"broker/gv90018g/COMMAND"
]
}
],
"publish":[
{
"payload":"${OUTPUTS/TOTAL/ENERGY}",
"qos":0,
"retain":false,
"topic":"broker/gv90018g/TOTAL/ENERGY/"
},
{
"payload":"${OUTPUTS/TOTAL/LOAD}",
"qos":0,
"retain":false,
"topic":"broker/gv90018g/TOTAL/LOAD/"
},
{
"payload":"${OUTPUTS/1/STATE}",
"qos":0,
"retain":true,
"topic":"broker/gv90018g/OUTPUTS/1/STATE"
},
{
"payload":"${OUTPUTS/2/STATE}",
"qos":0,
"retain":true,
"topic":"broker/gv90018g/OUTPUTS/2/STATE"
},
{
"payload":"${OUTPUTS/3/STATE}",
"qos":0,
"retain":true,
"topic":"broker/gv90018g/OUTPUTS/3/STATE"
},
{
"payload":"${OUTPUTS/4/STATE}",
"qos":0,
"retain":true,
"topic":"broker/gv90018g/OUTPUTS/4/STATE"
},
{
"payload":"${INPUTS/1/STATE}",
"qos":0,
"retain":true,
"topic":"broker/gv90018g/INPUTS/1/STATE"
},
{
"payload":"${INPUTS/1/STATE}",
"qos":0,
"retain":true,
"topic":"broker/gv90018g/INPUTS/1/STATE"
},
{
"payload":"OK",
"qos":0,
"retain":true,
"topic":"broker/gv90018g/COMMAND"
}
],
"subscribe":[
{
"action":"${payload}",
"qos":0,
"target":"PROTOCOLS/MQTT/EVENT",
"topic":"broker/gv90018g/COMMAND"
}
]
}

==== Trigger MQTT publish by MQTT subscribe <code>FW 4.0.0+</code> ====

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 ===
{| class="wikitable"
! style="font-weight:bold; background-color:#9b9b9b;" | Item
! style="font-weight:bold; background-color:#9b9b9b;" | Presence
! style="font-weight:bold; background-color:#9b9b9b;" | Possible Values
! style="font-weight:bold; background-color:#9b9b9b;" | Description
! style="font-weight:bold; background-color:#9b9b9b;" | JSON Config Usage
|-
| style="background-color:#efefef;" | topic
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | see table below
| style="background-color:#efefef;" | definition of the topic, how it is registered towards MQTT broker. Max. 128 characters.
| style="background-color:#efefef;" | "topic":"netio/${DEVICE_NAME}/output/1/load"
|-
| style="background-color:#efefef;" | qos
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | see table below
| style="background-color:#efefef;" | 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}
| style="background-color:#efefef;" |
|-
| style="background-color:#efefef;" | retain
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | boolean: true or false
| style="background-color:#efefef;" | 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}
| style="background-color:#efefef;" | "retain":true
|-
| style="background-color:#efefef;" | payload
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | see table below
| style="background-color:#efefef;" | definition of the payload, what is send to the MQTT broker.
| style="background-color:#efefef;" | "payload":"${OUTPUTS/1/STATE}"
|-
| style="background-color:#efefef;" | events
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | see table below
| style="background-color:#efefef;" | definition of events used for triggering sending of data via mqtt (change, delta, timer)
| style="background-color:#efefef;" |
|-
| style="background-color:#efefef;" | type
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
|-
| style="background-color:#efefef;" | source
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
|-
| style="background-color:#efefef;" | delta
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
|-
| style="background-color:#efefef;" | period
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
|-
| style="background-color:#efefef;" | payloaddefNot supported yet
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
|}

=== Examples ===
==== Publish energy periodically (event timer) ====
==== Publish current on change (delta) ====
==== Publish output state ====
==== Publish to more than one topic with different events ====

= 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 available only on NETIO PowerDIN 4PZ

=== Examples: ===

adressing controll of output 3
OUTPUTS/3/ACTION
getting voltage on output 1
OUTPUTS/1/VOLTAGE
getting state of input 1
INPUTS/1/STATE

= Events =
==== Timer ====

==== Delta ====

==== Change ====

==== Group Events<code>FW 4.0.0+</code>====

= 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 ===
==== VOLTAGE ====
Unit: <code>V</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Present RMS voltage on output 1 is ${OUTPUTS/1/VOLTAGE}"</code>

Example 2: <code>"source":"${OUTPUTS/1/VOLTAGE}"</code>

==== CURRENT ====
Unit: <code>mA</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Present RMS current on output 1 is ${OUTPUTS/1/CURRENT}"</code>

Example 2: <code>"source":"${OUTPUTS/1/CURRENT}"</code>

==== POWER_FACTOR ====
Unit: <code>[-]</code>

Type: float (2 decimals)

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"True Power Factor on output 1 is ${OUTPUTS/1/POWER_FACTOR}"</code>

Example 2: <code>"source":"${OUTPUTS/1/POWER_FACTOR}"</code>

==== LOAD ====
Unit: <code>W</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Present load on output 1 is ${OUTPUTS/1/LOAD}W"</code>

Example 2: <code>"payload":"Device's load connected to output 1 is ${OUTPUTS/1/LOAD}W"</code>

Example 3: <code>"source":"${OUTPUTS/1/LOAD}"</code>

==== STATE ====
Type: bool(integer) - <code>0</code> or <code>1</code>

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Present output 1 state is ${OUTPUTS/1/STATE}"</code>

Example 2: <code>"source":"${OUTPUTS/1/STATE}"</code>

==== ACTION ====
Type: integer

Possible actions:
* <code>0</code> - set state OFF
* <code>1</code> - set state ON
* <code>2</code> - short OFF (restart)
* <code>3</code> - short ON
* <code>4</code> - toggle (switch)
* <code>5</code> - no change

Allowed in: <code>"target"</code>

Example: <code>"target":"OUTPUTS/1/ACTION"</code>

==== DELAY [ms] ====
==== NAME ====
==== FREQUENCY ====
Unit: <code>Hz</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example: <code>"payload":"Frequency in power grid is ${OUTPUTS/1/ENERGY}Hz"</code>

==== ENERGY ====
Energy consumed by an device connected to NETIO device output.

Unit: <code>Wh</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Consumed energy on output 1 is ${OUTPUTS/1/ENERGY}Wh"</code>

Example 2: <code>"source":"${OUTPUTS/1/ENERGY}"</code>

==== REVERSE_ENERGY ====
Energy delivered back to grid. For example from solar system connected to NETIO device output.

Unit: <code>Wh</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Delivered energy on output 1 is ${OUTPUTS/1/REVERSE_ENERGY}Wh"</code>

Example 2: <code>"source":"${OUTPUTS/1/REVERSE_ENERGY}"</code>

==== ENERGY_START ====
Date when the counters ENERGY and REVERSE_ENERGY have been resetted by user.

Unit: <code>unix timestamp</code>

Type: integer

Allowed in: <code>"payload"</code>

Example 1: <code>"payload":"Energy measured since ${OUTPUTS/1/ENERGY_START} unix time"</code>

Example 2: <code>"payload":"${OUTPUTS/1/ENERGY_START}"</code> is output payload <code>1567654639</code>

==== ENERGY_START_FMT ====
Date when the counters ENERGY and REVERSE_ENERGY have been resetted by user.

Unit: <code>fmt date format</code>

Type: string

Allowed in: <code>"payload"</code>

Example 1: <code>"payload":"Energy measured since ${OUTPUTS/1/ENERGY_START}"</code>

Example 2: <code>"payload":"${OUTPUTS/1/ENERGY_START_FMT}"</code> is output payload <code>2019-09-05T03:37:19+00:00</code>

==== ENERGY_NR ====
Non-resettable counter of Energy consumed by an device connected to NETIO device output.

Unit: <code>Wh</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Consumed energy on output 1 is ${OUTPUTS/1/ENERGY_NR}Wh"</code>

Example 2: <code>"source":"${OUTPUTS/1/ENERGY_NR}"</code>

==== REVERSE_ENERGY_NR ====
Non-resettable counter of Energy delivered back to grid. For example from solar system connected to NETIO device output.

Unit: <code>Wh</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Delivered energy on output 1 is ${OUTPUTS/1/REVERSE_ENERGY_NR}Wh"</code>

Example 2: <code>"source":"${OUTPUTS/1/REVERSE_ENERGY_NR}"</code>

==== TOTALs - for 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
* OUTPUTS/TOTAL/PHASE
* OUTPUTS/TOTAL/REVERSE_ENERGY
* OUTPUTS/TOTAL/ENERGY_NR
* OUTPUTS/TOTAL/REVERSE_ENERGY_NR
* OUTPUTS/TOTAL/ENERGY_START
* OUTPUTS/TOTAL/ENERGY_START_FMT

==== REST_JSON ====
Allow use of NETIO JSON structure to control outputs.

Type: string / JSON

Allowed in: <code>"target"</code> for Subscribe section

Example: <code>"target": "REST_JSON"</code>

The payload is JSON structure identical to NETIO JSON API M2M Protocol (documentation available at https://www.netio-products.com/files/NETIO-M2M-API-Protocol-JSON.pdf). You can control one or multiple outputs.

Payload example 1 - Toggle output 1: <code>{"Outputs":[{"ID": 1,"Action": 4}]}</code>

Payload example 2 - Turn output 1 OFF and output 3 ON: <code>{"Outputs":[{"ID":1,"Action":0},{"ID":3,"Action":1}]}</code>

=== INPUT variables ===
==== STATE ====
Type: bool(integer) - <code>0</code> or <code>1</code>

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Present input 1 state is ${INPUTS/1/STATE}"</code>

Example 2: <code>"source":"${INPUTS/1/STATE}"</code>

==== S0 ====
S0 Counter value
Unit: <code>-</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Input 1 S0 Counter value is ${INPUTS/1/S0}impulses"</code>

Example 2: <code>"source":"${INPUTS/1/S0}"</code>

== Payload/topic variables ==

=== DEVICE_NAME ===
Can be used in: "payload", "topic"

Example 1: <code>"payload":"${DEVICE_NAME}"</code>

Example 2: <code>"topic":"netio/${DEVICE_NAME}/output/1/action"</code>

=== DEVICE_MAC ===

=== UPTIME Not yet implemented ===

=== PAYLOAD ===
Can be used in: "action"

Example: <code>"action":"${PAYLOAD}"</code>

=== OUTPUT_ID Not yet implemented===

=== WIFI_SIGNALNot yet implemented ===

=== OUTPUTS_STATUS ===
Provide complete outputs status and measurement if supported.

Type: string / JSON

Allowed in: <code>"payload"</code> for Publish section

Example: <code>"payload":"${OUTPUTS_STATUS}"</code>

Payload example: <code>{ "GlobalMeasure":{"Voltage":236,"TotalCurrent":72,"TotalLoad":11,"TotalEnergy":167,"OverallPowerFactor":0.64,"Frequency":50.07,"Phase":-36.86,"EnergyStart":"2020-06-30T17:04:48+01:00"}, "Outputs":[ {"ID":1,"Name":"Power output 1","State":1,"Action":6,"Delay":2020,"Current":72,"PowerFactor":0.64,"Phase":-36.86,"Energy":139,"ReverseEnergy":0,"Load":11}, {"ID":2,"Name":"Power output 2","State":1,"Action":6,"Delay":2020,"Current":0,"PowerFactor":1.00,"Phase":0.00,"Energy":27,"ReverseEnergy":0,"Load":0}, {"ID":3,"Name":"Free Contact 3","State":1,"Action":6,"Delay":2020}, {"ID":4,"Name":"Free Contact 4","State":1,"Action":6,"Delay":2020} ]}</code>

=== INPUTS_STATUS ===
Provide complete inputs status if supported. Since FW 3.0.0

Type: string / JSON

Allowed in: <code>"payload"</code> for Publish section

Example: <code>"payload":"${INPUTS_STATUS}"</code>

Payload example: <code>{ "Inputs":[ {"ID":1,"Name":"Input 1","State":0,"S0Counter":0}, {"ID":2,"Name":"Input 2","State":0,"S0Counter":0} ]}</code>

=== INOUT_STATUS ===
Provide complete inputs and output status and measurement if supported. Since FW 3.0.0

Type: string / JSON

Allowed in: <code>"payload"</code> for Publish section

Example: <code>"payload":"${INOUT_STATUS}"</code>

Payload example: <code>{ "GlobalMeasure":{"Voltage":238,"TotalCurrent":105,"TotalLoad":17,"TotalEnergy":1451,"OverallPowerFactor":0.67,"Frequency":50.03,"Phase":-33.67,"EnergyStart":"2020-06-30T17:04:48+01:00"}, "Outputs":[ {"ID":1,"Name":"Power output 1","State":0,"Action":6,"Delay":5000,"Current":0,"PowerFactor":1.00,"Phase":0.00,"Energy":701,"ReverseEnergy":0,"Load":0}, {"ID":2,"Name":"Power output 2","State":1,"Action":6,"Delay":5000,"Current":105,"PowerFactor":0.65,"Phase":-33.67,"Energy":750,"ReverseEnergy":0,"Load":17}, {"ID":3,"Name":"Free Contact 3","State":1,"Action":6,"Delay":5000}, {"ID":4,"Name":"Free Contact 4","State":0,"Action":6,"Delay":5000} ], "Inputs":[ {"ID":1,"Name":"Input 1","State":0,"S0Counter":0}, {"ID":2,"Name":"Input 2","State":0,"S0Counter":0} ]}</code>

= Extended MQTT flex JSON config examples =

== Default NETIO MQTT-flex configuration ==
This example demonstrates setup for connection to public <code>broker.hivemq.com</code>, measurement reporting and output control.

The device cabe be controlled via <code>netio/${DEVICE_NAME}/output/1/action topic</code> by sending standard NETIO action values:
* 0 - OFF
* 1 - ON
* 2 - SHORT OFF
* 3 - SHORT ON
* 4 - TOGGLE
* 5 - NO ACTION.

The device report measurements:

* Output state - every 15 minutes or by change
* Voltage [V]- every 5 minutes or by change of 1 V
* Current [mA]- every 5 minutes or by change of 50 mA
* Load(Power) [W]- every 5 minutes or by change of 10 W
* Energy(Consumption) [Wh]- every 15 minutes or by change of 1Wh
* True Power Factor (TPF) [-]- every 5 minutes or by change of 0.02
* Frequency [Hz]- every 1 hour or by change of 0.1 Hz

For register all values, you can use wildcard <code>netio/${DEVICE_NAME}/output/1/#</code>

{
"config":{
"broker":{
"url":"broker.hivemq.com",
"protocol":"mqtt",
"port":1883,
"ssl":false,
"type":"generic",
"username":"",
"password":"",
"clientid":"moje${DEVICE_NAME}${DEVICE_MAC}",
"keepalive":30
},
"subscribe":[
{
"topic":"netio/${DEVICE_NAME}/output/1/action",
"qos":0,
"target":"OUTPUTS/1/ACTION",
"action":"${payload}"
},
{
"topic":"netio/${DEVICE_NAME}/output/1/switch",
"qos":0,
"target":"OUTPUTS/1/ACTION",
"action":4
}
],
"publish":[
{
"topic":"netio/${DEVICE_MAC}/output/1/state",
"qos":0,
"retain":true,
"payload":"${OUTPUTS/1/STATE}",
"events":[
{
"type":"change",
"source":"OUTPUTS/1/STATE"
},
{
"type":"timer",
"period":900
}
]
},
{
"topic":"netio/${DEVICE_NAME}/output/1/voltage",
"qos":0,
"retain":false,
"payload":"${OUTPUTS/1/VOLTAGE}",
"events":[
{
"type":"timer",
"period":300
},
{
"type":"delta",
"source":"OUTPUTS/1/VOLTAGE",
"delta":1
}
]
},
{
"topic":"netio/${DEVICE_NAME}/output/1/current",
"qos":0,
"retain":false,
"payload":"${OUTPUTS/1/CURRENT}",
"events":[
{
"type":"timer",
"period":300
},
{
"type":"delta",
"source":"OUTPUTS/1/CURRENT",
"delta":50
}
]
},
{
"topic":"netio/${DEVICE_NAME}/output/1/load",
"qos":0,
"retain":false,
"payload":"${OUTPUTS/1/LOAD}",
"events":[
{
"type":"timer",
"period":300
},
{
"type":"delta",
"source":"OUTPUTS/1/LOAD",
"delta":10
}
]
},
{
"topic":"netio/${DEVICE_NAME}/output/1/energy",
"qos":0,
"retain":false,
"payload":"${OUTPUTS/1/ENERGY}",
"events":[
{
"type":"timer",
"period":900
},
{
"type":"delta",
"source":"OUTPUTS/1/ENERGY",
"delta":1
}
]
},
{
"topic":"netio/${DEVICE_NAME}/output/1/tpf",
"qos":0,
"retain":false,
"payload":"${OUTPUTS/1/POWER_FACTOR}",
"events":[
{
"type":"timer",
"period":900
},
{
"type":"delta",
"source":"OUTPUTS/1/POWER_FACTOR",
"delta":0.02
}
]
},
{
"topic":"netio/${DEVICE_NAME}/output/1/frequency",
"qos":0,
"retain":false,
"payload":"${OUTPUTS/1/FREQUENCY}",
"events":[
{
"type":"timer",
"period":3600
},
{
"type":"delta",
"source":"OUTPUTS/1/FREQUENCY",
"delta":0.1
}
]
}
]
}
}

MQTT-flex

2023-06-06T13:44:55Z

Bbakala: /* Trigger Rule sequence from MQTT */

The MQTT-flex version of the MQTT protocol can be configured in detail thanks to the “flex” extension.

https://www.netio-products.com/en/glossary/mqtt-flex

Why MQTT-flex 
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 [https://en.wikipedia.org/wiki/MQTT 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 [https://en.wikipedia.org/wiki/JSON 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 101x 
* PowerCable REST 101x 
* PowerPDU 4PS 
* PowerPDU 4KS 
* PowerPDU 8QS 
* PowerDIN 4PZ 
* PowerBOX 3Px 
* PowerBOX 4Kx 

FW version: 
>2.2.1

===Not supported NETIO devices:===
* PowerPDU 4C 
* NETIO 4 
* NETIO 4All 

= Simple MQTT-flex configuration + explanation =

''We strongly recommend to create and test MQTT-flex configuration on "local" device what can be easily restarted. The validation of config before saving is not 100% and for example some specific typos can cause a freeze of a device - the solution is to restart a device (unplug/plug input power cable). If the configuration is saved and device is working then there are no known failure case so it is safe to use this configuration on the "remote" devices.''

{
"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":false,
"payload":"${OUTPUTS/1/STATE}",
"events":[
{
"type":"timer",
"period":"1000"
}
]
}
]
}
}
=== Client Configuration (broker section) ===
Put here MQTT client connection setup

This configuration example set NETIO device to connect to broker.hivemq.com with mqtt protocol, no ssl connection with credetials freedom/peace|love|empathy4ALL.

"broker":{
"url":"broker.hivemq.com",
"protocol":"mqtt",
"port":1883,
"ssl":false,
"type":"generic",
"username":"freedom",
"password":"peace|LOVE|empathy4ALL"
},

=== Device Control (subscribe section) ===
Put here array of topics where to subscribe

Device output 1 is controlled with action received by subscription to netio/${DEVICE_NAME}/output/1/action topic with QOS 0

"subscribe":[{
"topic":"netio/${DEVICE_NAME}/output/1/action",
"qos":0,
"target":"OUTPUTS/1/ACTION",
"action":"${payload}"
}
],

=== Output State monitoring (publish section) ===
Put here array of topics where to publish.

Device send every 1000 s message to topic with QOS 0, retain true information with output 1 state

"publish":[{
"topic":"netio/${DEVICE_NAME}/output/1/state",
"qos":0,
"retain":true,
"payload":"${OUTPUTS/1/STATE}",
"events":[
{
"type":"timer",
"period":"1000"
}
]
}
]

= 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 ===
{| class="wikitable"
! style="font-weight:bold; background-color:#9b9b9b;" | Item
! style="font-weight:bold; background-color:#9b9b9b;" | Presence
! style="font-weight:bold; background-color:#9b9b9b;" | Possible Values
! style="font-weight:bold; background-color:#9b9b9b;" | Description
! style="font-weight:bold; background-color:#9b9b9b;" | JSON Config Usage
|-
| style="background-color:#efefef;" | url
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" |
| style="background-color:#efefef;" | MQTT broker URL
| style="background-color:#efefef;" | "url":"broker.hivemq.com"
|-
| style="background-color:#efefef;" | port
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | 1 - 65535
| style="background-color:#efefef;" | MQTT broker port
| style="background-color:#efefef;" | "port":1883
|-
| style="background-color:#efefef;" | protocol
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" |
| style="background-color:#efefef;" | protocol spec - mqtt
| style="background-color:#efefef;" | "protocol": "mqtt"
|-
| style="background-color:#efefef;" | ssl
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | true, false
| style="background-color:#efefef;" | Use SSL crypted communication selector
| style="background-color:#efefef;" | "ssl":false
|-
| style="background-color:#efefef;" | type
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | generic
| style="background-color:#efefef;" | Communication/setup type option
| style="background-color:#efefef;" | "type":"generic"
|-
| style="background-color:#efefef;" | username
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | regexp+len
| style="background-color:#efefef;" | Credentials for MQTT broker. Max. 128 characters (since FW 3.2.4).
| style="background-color:#efefef;" | "username":"freedom"
|-
| style="background-color:#efefef;" | password
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | regexp+len
| style="background-color:#efefef;" | Credentials for MQTT broker. Max. 256 characters (since FW 3.2.4).
| style="background-color:#efefef;" | "password":"peace|LOVE|empathy4ALL"
|-
| style="background-color:#efefef;" | clientid
| style="background-color:#efefef;" | optional
| style="background-color:#efefef;" | regexp+len
| style="background-color:#efefef;" | MQTT clientid. Max. 128 characters (since FW 3.2.4). Variables ${DEVICE_MAC} or ${DEVICE_NAME} can be used
| style="background-color:#efefef;" | "clientid":"myEcoTable01"
|-
| style="background-color:#efefef;" | keepalive
| style="background-color:#efefef;" | optional
| style="background-color:#efefef;" | 1 - 65535
| style="background-color:#efefef;" | MQTT keep alive period in seconds
| style="background-color:#efefef;" | "keepalive":90
|}

Note 1: clientid attribute is mandatory for MQTT(s) communication. When not configured, random ID will be generated.

Note 2: To proper communication with MS Azure - it is necessary to set up IoT Hub to use TLS 1.2

See section "TLS 1.2 enforcement available in select regions" in following guidelines https://docs.microsoft.com/en-us/azure/iot-hub/iot-hub-tls-support

=== Examples ===
==== Standard setup ====

==== Security (SSL / TLS) secured setup ====
You can enable MQTTs by using the encrypted port 8883 + "ssl":true.

==== Variables used setup ====

== 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 ===
{| class="wikitable"
! style="font-weight:bold; background-color:#9b9b9b;" | Item
! style="font-weight:bold; background-color:#9b9b9b;" | Presence
! style="font-weight:bold; background-color:#9b9b9b;" | Possible Values
! style="font-weight:bold; background-color:#9b9b9b;" | Description
! style="font-weight:bold; background-color:#9b9b9b;" | JSON Config Usage
|-
| style="background-color:#efefef;" | topic
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | see table below
| style="background-color:#efefef;" | specification of the topic, which MQTT-flex device listens from broker and act accordingly. Max. 128 characters. The "#" can be used since FW 3.2.4 - see note under this table.
| style="background-color:#efefef;" | "topic":"netio/${DEVICE_NAME}/output/1/action"
|-
| style="background-color:#efefef;" | qos
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | 0, 1 or 2
| style="background-color:#efefef;" | 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}
| style="background-color:#efefef;" | "qos":0
|-
| style="background-color:#efefef;" | target
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" |
| style="background-color:#efefef;" | internal definition of action, which can be performed above the specified output
| style="background-color:#efefef;" | "target":"OUTPUTS/1/ACTION"
|-
| style="background-color:#efefef;" | action
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" |
| style="background-color:#efefef;" | a payload or a value the action attribute needs to have passed to
| style="background-color:#efefef;" | "action":"${payload}"
|-
| style="background-color:#efefef;" | actiondefNot supported yet
| style="background-color:#efefef;" | optional
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
|-
| style="background-color:#efefef;" | jsonNot supported yet
| style="background-color:#efefef;" | optional
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
|}

Note: The "#" wildcard can be used in subscribe topic definition. The multi-level wildcard character MUST be specified either on its own or following a topic level separator. In either case it MUST be the last character specified in the Topic.

For example, if a Device subscribes to “devices/{device_id}/messages/devicebound/#”, it would receive messages published using these topic names:

“devices/{device_id}/messages/devicebound/”

“devices/{device_id}/messages/devicebound/{property_bag}”

This should be usefull for use with MS Azure - IoT hub.

=== MQTT Subscribe as event to trigger action <code>FW 4.0.0+</code> ===

This feature allow to subscribe to specific MQTT topic and pass payload to Rules or MQTT-flex as event.

target: <code>PROTOCOLS/MQTT/EVENT</code>

"subscribe": [
{
"action": "${payload}",
"qos": 0,
"target": "PROTOCOLS/MQTT/EVENT",
"topic": "broker/12345/MQTT_EVENT/"
}
]

=== Examples ===
==== Toggle output with standard payload ====
==== Toggle output with custom payload ====
==== Subscribe to more than one topic ====
==== Trigger Rule sequence from MQTT <code>FW 4.0.0+</code> ====

==== Trigger MQTT publish by MQTT subscribe <code>FW 4.0.0+</code> ====

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 ===
{| class="wikitable"
! style="font-weight:bold; background-color:#9b9b9b;" | Item
! style="font-weight:bold; background-color:#9b9b9b;" | Presence
! style="font-weight:bold; background-color:#9b9b9b;" | Possible Values
! style="font-weight:bold; background-color:#9b9b9b;" | Description
! style="font-weight:bold; background-color:#9b9b9b;" | JSON Config Usage
|-
| style="background-color:#efefef;" | topic
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | see table below
| style="background-color:#efefef;" | definition of the topic, how it is registered towards MQTT broker. Max. 128 characters.
| style="background-color:#efefef;" | "topic":"netio/${DEVICE_NAME}/output/1/load"
|-
| style="background-color:#efefef;" | qos
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | see table below
| style="background-color:#efefef;" | 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}
| style="background-color:#efefef;" |
|-
| style="background-color:#efefef;" | retain
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | boolean: true or false
| style="background-color:#efefef;" | 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}
| style="background-color:#efefef;" | "retain":true
|-
| style="background-color:#efefef;" | payload
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | see table below
| style="background-color:#efefef;" | definition of the payload, what is send to the MQTT broker.
| style="background-color:#efefef;" | "payload":"${OUTPUTS/1/STATE}"
|-
| style="background-color:#efefef;" | events
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | see table below
| style="background-color:#efefef;" | definition of events used for triggering sending of data via mqtt (change, delta, timer)
| style="background-color:#efefef;" |
|-
| style="background-color:#efefef;" | type
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
|-
| style="background-color:#efefef;" | source
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
|-
| style="background-color:#efefef;" | delta
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
|-
| style="background-color:#efefef;" | period
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
|-
| style="background-color:#efefef;" | payloaddefNot supported yet
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
|}

=== Examples ===
==== Publish energy periodically (event timer) ====
==== Publish current on change (delta) ====
==== Publish output state ====
==== Publish to more than one topic with different events ====

= 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 available only on NETIO PowerDIN 4PZ

=== Examples: ===

adressing controll of output 3
OUTPUTS/3/ACTION
getting voltage on output 1
OUTPUTS/1/VOLTAGE
getting state of input 1
INPUTS/1/STATE

= Events =
==== Timer ====

==== Delta ====

==== Change ====

==== Group Events<code>FW 4.0.0+</code>====

= 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 ===
==== VOLTAGE ====
Unit: <code>V</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Present RMS voltage on output 1 is ${OUTPUTS/1/VOLTAGE}"</code>

Example 2: <code>"source":"${OUTPUTS/1/VOLTAGE}"</code>

==== CURRENT ====
Unit: <code>mA</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Present RMS current on output 1 is ${OUTPUTS/1/CURRENT}"</code>

Example 2: <code>"source":"${OUTPUTS/1/CURRENT}"</code>

==== POWER_FACTOR ====
Unit: <code>[-]</code>

Type: float (2 decimals)

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"True Power Factor on output 1 is ${OUTPUTS/1/POWER_FACTOR}"</code>

Example 2: <code>"source":"${OUTPUTS/1/POWER_FACTOR}"</code>

==== LOAD ====
Unit: <code>W</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Present load on output 1 is ${OUTPUTS/1/LOAD}W"</code>

Example 2: <code>"payload":"Device's load connected to output 1 is ${OUTPUTS/1/LOAD}W"</code>

Example 3: <code>"source":"${OUTPUTS/1/LOAD}"</code>

==== STATE ====
Type: bool(integer) - <code>0</code> or <code>1</code>

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Present output 1 state is ${OUTPUTS/1/STATE}"</code>

Example 2: <code>"source":"${OUTPUTS/1/STATE}"</code>

==== ACTION ====
Type: integer

Possible actions:
* <code>0</code> - set state OFF
* <code>1</code> - set state ON
* <code>2</code> - short OFF (restart)
* <code>3</code> - short ON
* <code>4</code> - toggle (switch)
* <code>5</code> - no change

Allowed in: <code>"target"</code>

Example: <code>"target":"OUTPUTS/1/ACTION"</code>

==== DELAY [ms] ====
==== NAME ====
==== FREQUENCY ====
Unit: <code>Hz</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example: <code>"payload":"Frequency in power grid is ${OUTPUTS/1/ENERGY}Hz"</code>

==== ENERGY ====
Energy consumed by an device connected to NETIO device output.

Unit: <code>Wh</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Consumed energy on output 1 is ${OUTPUTS/1/ENERGY}Wh"</code>

Example 2: <code>"source":"${OUTPUTS/1/ENERGY}"</code>

==== REVERSE_ENERGY ====
Energy delivered back to grid. For example from solar system connected to NETIO device output.

Unit: <code>Wh</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Delivered energy on output 1 is ${OUTPUTS/1/REVERSE_ENERGY}Wh"</code>

Example 2: <code>"source":"${OUTPUTS/1/REVERSE_ENERGY}"</code>

==== ENERGY_START ====
Date when the counters ENERGY and REVERSE_ENERGY have been resetted by user.

Unit: <code>unix timestamp</code>

Type: integer

Allowed in: <code>"payload"</code>

Example 1: <code>"payload":"Energy measured since ${OUTPUTS/1/ENERGY_START} unix time"</code>

Example 2: <code>"payload":"${OUTPUTS/1/ENERGY_START}"</code> is output payload <code>1567654639</code>

==== ENERGY_START_FMT ====
Date when the counters ENERGY and REVERSE_ENERGY have been resetted by user.

Unit: <code>fmt date format</code>

Type: string

Allowed in: <code>"payload"</code>

Example 1: <code>"payload":"Energy measured since ${OUTPUTS/1/ENERGY_START}"</code>

Example 2: <code>"payload":"${OUTPUTS/1/ENERGY_START_FMT}"</code> is output payload <code>2019-09-05T03:37:19+00:00</code>

==== ENERGY_NR ====
Non-resettable counter of Energy consumed by an device connected to NETIO device output.

Unit: <code>Wh</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Consumed energy on output 1 is ${OUTPUTS/1/ENERGY_NR}Wh"</code>

Example 2: <code>"source":"${OUTPUTS/1/ENERGY_NR}"</code>

==== REVERSE_ENERGY_NR ====
Non-resettable counter of Energy delivered back to grid. For example from solar system connected to NETIO device output.

Unit: <code>Wh</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Delivered energy on output 1 is ${OUTPUTS/1/REVERSE_ENERGY_NR}Wh"</code>

Example 2: <code>"source":"${OUTPUTS/1/REVERSE_ENERGY_NR}"</code>

==== TOTALs - for 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
* OUTPUTS/TOTAL/PHASE
* OUTPUTS/TOTAL/REVERSE_ENERGY
* OUTPUTS/TOTAL/ENERGY_NR
* OUTPUTS/TOTAL/REVERSE_ENERGY_NR
* OUTPUTS/TOTAL/ENERGY_START
* OUTPUTS/TOTAL/ENERGY_START_FMT

==== REST_JSON ====
Allow use of NETIO JSON structure to control outputs.

Type: string / JSON

Allowed in: <code>"target"</code> for Subscribe section

Example: <code>"target": "REST_JSON"</code>

The payload is JSON structure identical to NETIO JSON API M2M Protocol (documentation available at https://www.netio-products.com/files/NETIO-M2M-API-Protocol-JSON.pdf). You can control one or multiple outputs.

Payload example 1 - Toggle output 1: <code>{"Outputs":[{"ID": 1,"Action": 4}]}</code>

Payload example 2 - Turn output 1 OFF and output 3 ON: <code>{"Outputs":[{"ID":1,"Action":0},{"ID":3,"Action":1}]}</code>

=== INPUT variables ===
==== STATE ====
Type: bool(integer) - <code>0</code> or <code>1</code>

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Present input 1 state is ${INPUTS/1/STATE}"</code>

Example 2: <code>"source":"${INPUTS/1/STATE}"</code>

==== S0 ====
S0 Counter value
Unit: <code>-</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Input 1 S0 Counter value is ${INPUTS/1/S0}impulses"</code>

Example 2: <code>"source":"${INPUTS/1/S0}"</code>

== Payload/topic variables ==

=== DEVICE_NAME ===
Can be used in: "payload", "topic"

Example 1: <code>"payload":"${DEVICE_NAME}"</code>

Example 2: <code>"topic":"netio/${DEVICE_NAME}/output/1/action"</code>

=== DEVICE_MAC ===

=== UPTIME Not yet implemented ===

=== PAYLOAD ===
Can be used in: "action"

Example: <code>"action":"${PAYLOAD}"</code>

=== OUTPUT_ID Not yet implemented===

=== WIFI_SIGNALNot yet implemented ===

=== OUTPUTS_STATUS ===
Provide complete outputs status and measurement if supported.

Type: string / JSON

Allowed in: <code>"payload"</code> for Publish section

Example: <code>"payload":"${OUTPUTS_STATUS}"</code>

Payload example: <code>{ "GlobalMeasure":{"Voltage":236,"TotalCurrent":72,"TotalLoad":11,"TotalEnergy":167,"OverallPowerFactor":0.64,"Frequency":50.07,"Phase":-36.86,"EnergyStart":"2020-06-30T17:04:48+01:00"}, "Outputs":[ {"ID":1,"Name":"Power output 1","State":1,"Action":6,"Delay":2020,"Current":72,"PowerFactor":0.64,"Phase":-36.86,"Energy":139,"ReverseEnergy":0,"Load":11}, {"ID":2,"Name":"Power output 2","State":1,"Action":6,"Delay":2020,"Current":0,"PowerFactor":1.00,"Phase":0.00,"Energy":27,"ReverseEnergy":0,"Load":0}, {"ID":3,"Name":"Free Contact 3","State":1,"Action":6,"Delay":2020}, {"ID":4,"Name":"Free Contact 4","State":1,"Action":6,"Delay":2020} ]}</code>

=== INPUTS_STATUS ===
Provide complete inputs status if supported. Since FW 3.0.0

Type: string / JSON

Allowed in: <code>"payload"</code> for Publish section

Example: <code>"payload":"${INPUTS_STATUS}"</code>

Payload example: <code>{ "Inputs":[ {"ID":1,"Name":"Input 1","State":0,"S0Counter":0}, {"ID":2,"Name":"Input 2","State":0,"S0Counter":0} ]}</code>

=== INOUT_STATUS ===
Provide complete inputs and output status and measurement if supported. Since FW 3.0.0

Type: string / JSON

Allowed in: <code>"payload"</code> for Publish section

Example: <code>"payload":"${INOUT_STATUS}"</code>

Payload example: <code>{ "GlobalMeasure":{"Voltage":238,"TotalCurrent":105,"TotalLoad":17,"TotalEnergy":1451,"OverallPowerFactor":0.67,"Frequency":50.03,"Phase":-33.67,"EnergyStart":"2020-06-30T17:04:48+01:00"}, "Outputs":[ {"ID":1,"Name":"Power output 1","State":0,"Action":6,"Delay":5000,"Current":0,"PowerFactor":1.00,"Phase":0.00,"Energy":701,"ReverseEnergy":0,"Load":0}, {"ID":2,"Name":"Power output 2","State":1,"Action":6,"Delay":5000,"Current":105,"PowerFactor":0.65,"Phase":-33.67,"Energy":750,"ReverseEnergy":0,"Load":17}, {"ID":3,"Name":"Free Contact 3","State":1,"Action":6,"Delay":5000}, {"ID":4,"Name":"Free Contact 4","State":0,"Action":6,"Delay":5000} ], "Inputs":[ {"ID":1,"Name":"Input 1","State":0,"S0Counter":0}, {"ID":2,"Name":"Input 2","State":0,"S0Counter":0} ]}</code>

= Extended MQTT flex JSON config examples =

== Default NETIO MQTT-flex configuration ==
This example demonstrates setup for connection to public <code>broker.hivemq.com</code>, measurement reporting and output control.

The device cabe be controlled via <code>netio/${DEVICE_NAME}/output/1/action topic</code> by sending standard NETIO action values:
* 0 - OFF
* 1 - ON
* 2 - SHORT OFF
* 3 - SHORT ON
* 4 - TOGGLE
* 5 - NO ACTION.

The device report measurements:

* Output state - every 15 minutes or by change
* Voltage [V]- every 5 minutes or by change of 1 V
* Current [mA]- every 5 minutes or by change of 50 mA
* Load(Power) [W]- every 5 minutes or by change of 10 W
* Energy(Consumption) [Wh]- every 15 minutes or by change of 1Wh
* True Power Factor (TPF) [-]- every 5 minutes or by change of 0.02
* Frequency [Hz]- every 1 hour or by change of 0.1 Hz

For register all values, you can use wildcard <code>netio/${DEVICE_NAME}/output/1/#</code>

{
"config":{
"broker":{
"url":"broker.hivemq.com",
"protocol":"mqtt",
"port":1883,
"ssl":false,
"type":"generic",
"username":"",
"password":"",
"clientid":"moje${DEVICE_NAME}${DEVICE_MAC}",
"keepalive":30
},
"subscribe":[
{
"topic":"netio/${DEVICE_NAME}/output/1/action",
"qos":0,
"target":"OUTPUTS/1/ACTION",
"action":"${payload}"
},
{
"topic":"netio/${DEVICE_NAME}/output/1/switch",
"qos":0,
"target":"OUTPUTS/1/ACTION",
"action":4
}
],
"publish":[
{
"topic":"netio/${DEVICE_MAC}/output/1/state",
"qos":0,
"retain":true,
"payload":"${OUTPUTS/1/STATE}",
"events":[
{
"type":"change",
"source":"OUTPUTS/1/STATE"
},
{
"type":"timer",
"period":900
}
]
},
{
"topic":"netio/${DEVICE_NAME}/output/1/voltage",
"qos":0,
"retain":false,
"payload":"${OUTPUTS/1/VOLTAGE}",
"events":[
{
"type":"timer",
"period":300
},
{
"type":"delta",
"source":"OUTPUTS/1/VOLTAGE",
"delta":1
}
]
},
{
"topic":"netio/${DEVICE_NAME}/output/1/current",
"qos":0,
"retain":false,
"payload":"${OUTPUTS/1/CURRENT}",
"events":[
{
"type":"timer",
"period":300
},
{
"type":"delta",
"source":"OUTPUTS/1/CURRENT",
"delta":50
}
]
},
{
"topic":"netio/${DEVICE_NAME}/output/1/load",
"qos":0,
"retain":false,
"payload":"${OUTPUTS/1/LOAD}",
"events":[
{
"type":"timer",
"period":300
},
{
"type":"delta",
"source":"OUTPUTS/1/LOAD",
"delta":10
}
]
},
{
"topic":"netio/${DEVICE_NAME}/output/1/energy",
"qos":0,
"retain":false,
"payload":"${OUTPUTS/1/ENERGY}",
"events":[
{
"type":"timer",
"period":900
},
{
"type":"delta",
"source":"OUTPUTS/1/ENERGY",
"delta":1
}
]
},
{
"topic":"netio/${DEVICE_NAME}/output/1/tpf",
"qos":0,
"retain":false,
"payload":"${OUTPUTS/1/POWER_FACTOR}",
"events":[
{
"type":"timer",
"period":900
},
{
"type":"delta",
"source":"OUTPUTS/1/POWER_FACTOR",
"delta":0.02
}
]
},
{
"topic":"netio/${DEVICE_NAME}/output/1/frequency",
"qos":0,
"retain":false,
"payload":"${OUTPUTS/1/FREQUENCY}",
"events":[
{
"type":"timer",
"period":3600
},
{
"type":"delta",
"source":"OUTPUTS/1/FREQUENCY",
"delta":0.1
}
]
}
]
}
}

MQTT-flex

2023-06-06T13:44:43Z

Bbakala: /* Trigger MQTT publish by MQTT subscribe */

The MQTT-flex version of the MQTT protocol can be configured in detail thanks to the “flex” extension.

https://www.netio-products.com/en/glossary/mqtt-flex

Why MQTT-flex 
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 [https://en.wikipedia.org/wiki/MQTT 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 [https://en.wikipedia.org/wiki/JSON 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 101x 
* PowerCable REST 101x 
* PowerPDU 4PS 
* PowerPDU 4KS 
* PowerPDU 8QS 
* PowerDIN 4PZ 
* PowerBOX 3Px 
* PowerBOX 4Kx 

FW version: 
>2.2.1

===Not supported NETIO devices:===
* PowerPDU 4C 
* NETIO 4 
* NETIO 4All 

= Simple MQTT-flex configuration + explanation =

''We strongly recommend to create and test MQTT-flex configuration on "local" device what can be easily restarted. The validation of config before saving is not 100% and for example some specific typos can cause a freeze of a device - the solution is to restart a device (unplug/plug input power cable). If the configuration is saved and device is working then there are no known failure case so it is safe to use this configuration on the "remote" devices.''

{
"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":false,
"payload":"${OUTPUTS/1/STATE}",
"events":[
{
"type":"timer",
"period":"1000"
}
]
}
]
}
}
=== Client Configuration (broker section) ===
Put here MQTT client connection setup

This configuration example set NETIO device to connect to broker.hivemq.com with mqtt protocol, no ssl connection with credetials freedom/peace|love|empathy4ALL.

"broker":{
"url":"broker.hivemq.com",
"protocol":"mqtt",
"port":1883,
"ssl":false,
"type":"generic",
"username":"freedom",
"password":"peace|LOVE|empathy4ALL"
},

=== Device Control (subscribe section) ===
Put here array of topics where to subscribe

Device output 1 is controlled with action received by subscription to netio/${DEVICE_NAME}/output/1/action topic with QOS 0

"subscribe":[{
"topic":"netio/${DEVICE_NAME}/output/1/action",
"qos":0,
"target":"OUTPUTS/1/ACTION",
"action":"${payload}"
}
],

=== Output State monitoring (publish section) ===
Put here array of topics where to publish.

Device send every 1000 s message to topic with QOS 0, retain true information with output 1 state

"publish":[{
"topic":"netio/${DEVICE_NAME}/output/1/state",
"qos":0,
"retain":true,
"payload":"${OUTPUTS/1/STATE}",
"events":[
{
"type":"timer",
"period":"1000"
}
]
}
]

= 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 ===
{| class="wikitable"
! style="font-weight:bold; background-color:#9b9b9b;" | Item
! style="font-weight:bold; background-color:#9b9b9b;" | Presence
! style="font-weight:bold; background-color:#9b9b9b;" | Possible Values
! style="font-weight:bold; background-color:#9b9b9b;" | Description
! style="font-weight:bold; background-color:#9b9b9b;" | JSON Config Usage
|-
| style="background-color:#efefef;" | url
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" |
| style="background-color:#efefef;" | MQTT broker URL
| style="background-color:#efefef;" | "url":"broker.hivemq.com"
|-
| style="background-color:#efefef;" | port
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | 1 - 65535
| style="background-color:#efefef;" | MQTT broker port
| style="background-color:#efefef;" | "port":1883
|-
| style="background-color:#efefef;" | protocol
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" |
| style="background-color:#efefef;" | protocol spec - mqtt
| style="background-color:#efefef;" | "protocol": "mqtt"
|-
| style="background-color:#efefef;" | ssl
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | true, false
| style="background-color:#efefef;" | Use SSL crypted communication selector
| style="background-color:#efefef;" | "ssl":false
|-
| style="background-color:#efefef;" | type
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | generic
| style="background-color:#efefef;" | Communication/setup type option
| style="background-color:#efefef;" | "type":"generic"
|-
| style="background-color:#efefef;" | username
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | regexp+len
| style="background-color:#efefef;" | Credentials for MQTT broker. Max. 128 characters (since FW 3.2.4).
| style="background-color:#efefef;" | "username":"freedom"
|-
| style="background-color:#efefef;" | password
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | regexp+len
| style="background-color:#efefef;" | Credentials for MQTT broker. Max. 256 characters (since FW 3.2.4).
| style="background-color:#efefef;" | "password":"peace|LOVE|empathy4ALL"
|-
| style="background-color:#efefef;" | clientid
| style="background-color:#efefef;" | optional
| style="background-color:#efefef;" | regexp+len
| style="background-color:#efefef;" | MQTT clientid. Max. 128 characters (since FW 3.2.4). Variables ${DEVICE_MAC} or ${DEVICE_NAME} can be used
| style="background-color:#efefef;" | "clientid":"myEcoTable01"
|-
| style="background-color:#efefef;" | keepalive
| style="background-color:#efefef;" | optional
| style="background-color:#efefef;" | 1 - 65535
| style="background-color:#efefef;" | MQTT keep alive period in seconds
| style="background-color:#efefef;" | "keepalive":90
|}

Note 1: clientid attribute is mandatory for MQTT(s) communication. When not configured, random ID will be generated.

Note 2: To proper communication with MS Azure - it is necessary to set up IoT Hub to use TLS 1.2

See section "TLS 1.2 enforcement available in select regions" in following guidelines https://docs.microsoft.com/en-us/azure/iot-hub/iot-hub-tls-support

=== Examples ===
==== Standard setup ====

==== Security (SSL / TLS) secured setup ====
You can enable MQTTs by using the encrypted port 8883 + "ssl":true.

==== Variables used setup ====

== 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 ===
{| class="wikitable"
! style="font-weight:bold; background-color:#9b9b9b;" | Item
! style="font-weight:bold; background-color:#9b9b9b;" | Presence
! style="font-weight:bold; background-color:#9b9b9b;" | Possible Values
! style="font-weight:bold; background-color:#9b9b9b;" | Description
! style="font-weight:bold; background-color:#9b9b9b;" | JSON Config Usage
|-
| style="background-color:#efefef;" | topic
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | see table below
| style="background-color:#efefef;" | specification of the topic, which MQTT-flex device listens from broker and act accordingly. Max. 128 characters. The "#" can be used since FW 3.2.4 - see note under this table.
| style="background-color:#efefef;" | "topic":"netio/${DEVICE_NAME}/output/1/action"
|-
| style="background-color:#efefef;" | qos
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | 0, 1 or 2
| style="background-color:#efefef;" | 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}
| style="background-color:#efefef;" | "qos":0
|-
| style="background-color:#efefef;" | target
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" |
| style="background-color:#efefef;" | internal definition of action, which can be performed above the specified output
| style="background-color:#efefef;" | "target":"OUTPUTS/1/ACTION"
|-
| style="background-color:#efefef;" | action
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" |
| style="background-color:#efefef;" | a payload or a value the action attribute needs to have passed to
| style="background-color:#efefef;" | "action":"${payload}"
|-
| style="background-color:#efefef;" | actiondefNot supported yet
| style="background-color:#efefef;" | optional
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
|-
| style="background-color:#efefef;" | jsonNot supported yet
| style="background-color:#efefef;" | optional
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
|}

Note: The "#" wildcard can be used in subscribe topic definition. The multi-level wildcard character MUST be specified either on its own or following a topic level separator. In either case it MUST be the last character specified in the Topic.

For example, if a Device subscribes to “devices/{device_id}/messages/devicebound/#”, it would receive messages published using these topic names:

“devices/{device_id}/messages/devicebound/”

“devices/{device_id}/messages/devicebound/{property_bag}”

This should be usefull for use with MS Azure - IoT hub.

=== MQTT Subscribe as event to trigger action <code>FW 4.0.0+</code> ===

This feature allow to subscribe to specific MQTT topic and pass payload to Rules or MQTT-flex as event.

target: <code>PROTOCOLS/MQTT/EVENT</code>

"subscribe": [
{
"action": "${payload}",
"qos": 0,
"target": "PROTOCOLS/MQTT/EVENT",
"topic": "broker/12345/MQTT_EVENT/"
}
]

=== Examples ===
==== Toggle output with standard payload ====
==== Toggle output with custom payload ====
==== Subscribe to more than one topic ====
==== Trigger Rule sequence from MQTT ====
==== Trigger MQTT publish by MQTT subscribe <code>FW 4.0.0+</code> ====

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 ===
{| class="wikitable"
! style="font-weight:bold; background-color:#9b9b9b;" | Item
! style="font-weight:bold; background-color:#9b9b9b;" | Presence
! style="font-weight:bold; background-color:#9b9b9b;" | Possible Values
! style="font-weight:bold; background-color:#9b9b9b;" | Description
! style="font-weight:bold; background-color:#9b9b9b;" | JSON Config Usage
|-
| style="background-color:#efefef;" | topic
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | see table below
| style="background-color:#efefef;" | definition of the topic, how it is registered towards MQTT broker. Max. 128 characters.
| style="background-color:#efefef;" | "topic":"netio/${DEVICE_NAME}/output/1/load"
|-
| style="background-color:#efefef;" | qos
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | see table below
| style="background-color:#efefef;" | 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}
| style="background-color:#efefef;" |
|-
| style="background-color:#efefef;" | retain
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | boolean: true or false
| style="background-color:#efefef;" | 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}
| style="background-color:#efefef;" | "retain":true
|-
| style="background-color:#efefef;" | payload
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | see table below
| style="background-color:#efefef;" | definition of the payload, what is send to the MQTT broker.
| style="background-color:#efefef;" | "payload":"${OUTPUTS/1/STATE}"
|-
| style="background-color:#efefef;" | events
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | see table below
| style="background-color:#efefef;" | definition of events used for triggering sending of data via mqtt (change, delta, timer)
| style="background-color:#efefef;" |
|-
| style="background-color:#efefef;" | type
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
|-
| style="background-color:#efefef;" | source
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
|-
| style="background-color:#efefef;" | delta
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
|-
| style="background-color:#efefef;" | period
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
|-
| style="background-color:#efefef;" | payloaddefNot supported yet
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
|}

=== Examples ===
==== Publish energy periodically (event timer) ====
==== Publish current on change (delta) ====
==== Publish output state ====
==== Publish to more than one topic with different events ====

= 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 available only on NETIO PowerDIN 4PZ

=== Examples: ===

adressing controll of output 3
OUTPUTS/3/ACTION
getting voltage on output 1
OUTPUTS/1/VOLTAGE
getting state of input 1
INPUTS/1/STATE

= Events =
==== Timer ====

==== Delta ====

==== Change ====

==== Group Events<code>FW 4.0.0+</code>====

= 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 ===
==== VOLTAGE ====
Unit: <code>V</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Present RMS voltage on output 1 is ${OUTPUTS/1/VOLTAGE}"</code>

Example 2: <code>"source":"${OUTPUTS/1/VOLTAGE}"</code>

==== CURRENT ====
Unit: <code>mA</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Present RMS current on output 1 is ${OUTPUTS/1/CURRENT}"</code>

Example 2: <code>"source":"${OUTPUTS/1/CURRENT}"</code>

==== POWER_FACTOR ====
Unit: <code>[-]</code>

Type: float (2 decimals)

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"True Power Factor on output 1 is ${OUTPUTS/1/POWER_FACTOR}"</code>

Example 2: <code>"source":"${OUTPUTS/1/POWER_FACTOR}"</code>

==== LOAD ====
Unit: <code>W</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Present load on output 1 is ${OUTPUTS/1/LOAD}W"</code>

Example 2: <code>"payload":"Device's load connected to output 1 is ${OUTPUTS/1/LOAD}W"</code>

Example 3: <code>"source":"${OUTPUTS/1/LOAD}"</code>

==== STATE ====
Type: bool(integer) - <code>0</code> or <code>1</code>

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Present output 1 state is ${OUTPUTS/1/STATE}"</code>

Example 2: <code>"source":"${OUTPUTS/1/STATE}"</code>

==== ACTION ====
Type: integer

Possible actions:
* <code>0</code> - set state OFF
* <code>1</code> - set state ON
* <code>2</code> - short OFF (restart)
* <code>3</code> - short ON
* <code>4</code> - toggle (switch)
* <code>5</code> - no change

Allowed in: <code>"target"</code>

Example: <code>"target":"OUTPUTS/1/ACTION"</code>

==== DELAY [ms] ====
==== NAME ====
==== FREQUENCY ====
Unit: <code>Hz</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example: <code>"payload":"Frequency in power grid is ${OUTPUTS/1/ENERGY}Hz"</code>

==== ENERGY ====
Energy consumed by an device connected to NETIO device output.

Unit: <code>Wh</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Consumed energy on output 1 is ${OUTPUTS/1/ENERGY}Wh"</code>

Example 2: <code>"source":"${OUTPUTS/1/ENERGY}"</code>

==== REVERSE_ENERGY ====
Energy delivered back to grid. For example from solar system connected to NETIO device output.

Unit: <code>Wh</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Delivered energy on output 1 is ${OUTPUTS/1/REVERSE_ENERGY}Wh"</code>

Example 2: <code>"source":"${OUTPUTS/1/REVERSE_ENERGY}"</code>

==== ENERGY_START ====
Date when the counters ENERGY and REVERSE_ENERGY have been resetted by user.

Unit: <code>unix timestamp</code>

Type: integer

Allowed in: <code>"payload"</code>

Example 1: <code>"payload":"Energy measured since ${OUTPUTS/1/ENERGY_START} unix time"</code>

Example 2: <code>"payload":"${OUTPUTS/1/ENERGY_START}"</code> is output payload <code>1567654639</code>

==== ENERGY_START_FMT ====
Date when the counters ENERGY and REVERSE_ENERGY have been resetted by user.

Unit: <code>fmt date format</code>

Type: string

Allowed in: <code>"payload"</code>

Example 1: <code>"payload":"Energy measured since ${OUTPUTS/1/ENERGY_START}"</code>

Example 2: <code>"payload":"${OUTPUTS/1/ENERGY_START_FMT}"</code> is output payload <code>2019-09-05T03:37:19+00:00</code>

==== ENERGY_NR ====
Non-resettable counter of Energy consumed by an device connected to NETIO device output.

Unit: <code>Wh</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Consumed energy on output 1 is ${OUTPUTS/1/ENERGY_NR}Wh"</code>

Example 2: <code>"source":"${OUTPUTS/1/ENERGY_NR}"</code>

==== REVERSE_ENERGY_NR ====
Non-resettable counter of Energy delivered back to grid. For example from solar system connected to NETIO device output.

Unit: <code>Wh</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Delivered energy on output 1 is ${OUTPUTS/1/REVERSE_ENERGY_NR}Wh"</code>

Example 2: <code>"source":"${OUTPUTS/1/REVERSE_ENERGY_NR}"</code>

==== TOTALs - for 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
* OUTPUTS/TOTAL/PHASE
* OUTPUTS/TOTAL/REVERSE_ENERGY
* OUTPUTS/TOTAL/ENERGY_NR
* OUTPUTS/TOTAL/REVERSE_ENERGY_NR
* OUTPUTS/TOTAL/ENERGY_START
* OUTPUTS/TOTAL/ENERGY_START_FMT

==== REST_JSON ====
Allow use of NETIO JSON structure to control outputs.

Type: string / JSON

Allowed in: <code>"target"</code> for Subscribe section

Example: <code>"target": "REST_JSON"</code>

The payload is JSON structure identical to NETIO JSON API M2M Protocol (documentation available at https://www.netio-products.com/files/NETIO-M2M-API-Protocol-JSON.pdf). You can control one or multiple outputs.

Payload example 1 - Toggle output 1: <code>{"Outputs":[{"ID": 1,"Action": 4}]}</code>

Payload example 2 - Turn output 1 OFF and output 3 ON: <code>{"Outputs":[{"ID":1,"Action":0},{"ID":3,"Action":1}]}</code>

=== INPUT variables ===
==== STATE ====
Type: bool(integer) - <code>0</code> or <code>1</code>

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Present input 1 state is ${INPUTS/1/STATE}"</code>

Example 2: <code>"source":"${INPUTS/1/STATE}"</code>

==== S0 ====
S0 Counter value
Unit: <code>-</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Input 1 S0 Counter value is ${INPUTS/1/S0}impulses"</code>

Example 2: <code>"source":"${INPUTS/1/S0}"</code>

== Payload/topic variables ==

=== DEVICE_NAME ===
Can be used in: "payload", "topic"

Example 1: <code>"payload":"${DEVICE_NAME}"</code>

Example 2: <code>"topic":"netio/${DEVICE_NAME}/output/1/action"</code>

=== DEVICE_MAC ===

=== UPTIME Not yet implemented ===

=== PAYLOAD ===
Can be used in: "action"

Example: <code>"action":"${PAYLOAD}"</code>

=== OUTPUT_ID Not yet implemented===

=== WIFI_SIGNALNot yet implemented ===

=== OUTPUTS_STATUS ===
Provide complete outputs status and measurement if supported.

Type: string / JSON

Allowed in: <code>"payload"</code> for Publish section

Example: <code>"payload":"${OUTPUTS_STATUS}"</code>

Payload example: <code>{ "GlobalMeasure":{"Voltage":236,"TotalCurrent":72,"TotalLoad":11,"TotalEnergy":167,"OverallPowerFactor":0.64,"Frequency":50.07,"Phase":-36.86,"EnergyStart":"2020-06-30T17:04:48+01:00"}, "Outputs":[ {"ID":1,"Name":"Power output 1","State":1,"Action":6,"Delay":2020,"Current":72,"PowerFactor":0.64,"Phase":-36.86,"Energy":139,"ReverseEnergy":0,"Load":11}, {"ID":2,"Name":"Power output 2","State":1,"Action":6,"Delay":2020,"Current":0,"PowerFactor":1.00,"Phase":0.00,"Energy":27,"ReverseEnergy":0,"Load":0}, {"ID":3,"Name":"Free Contact 3","State":1,"Action":6,"Delay":2020}, {"ID":4,"Name":"Free Contact 4","State":1,"Action":6,"Delay":2020} ]}</code>

=== INPUTS_STATUS ===
Provide complete inputs status if supported. Since FW 3.0.0

Type: string / JSON

Allowed in: <code>"payload"</code> for Publish section

Example: <code>"payload":"${INPUTS_STATUS}"</code>

Payload example: <code>{ "Inputs":[ {"ID":1,"Name":"Input 1","State":0,"S0Counter":0}, {"ID":2,"Name":"Input 2","State":0,"S0Counter":0} ]}</code>

=== INOUT_STATUS ===
Provide complete inputs and output status and measurement if supported. Since FW 3.0.0

Type: string / JSON

Allowed in: <code>"payload"</code> for Publish section

Example: <code>"payload":"${INOUT_STATUS}"</code>

Payload example: <code>{ "GlobalMeasure":{"Voltage":238,"TotalCurrent":105,"TotalLoad":17,"TotalEnergy":1451,"OverallPowerFactor":0.67,"Frequency":50.03,"Phase":-33.67,"EnergyStart":"2020-06-30T17:04:48+01:00"}, "Outputs":[ {"ID":1,"Name":"Power output 1","State":0,"Action":6,"Delay":5000,"Current":0,"PowerFactor":1.00,"Phase":0.00,"Energy":701,"ReverseEnergy":0,"Load":0}, {"ID":2,"Name":"Power output 2","State":1,"Action":6,"Delay":5000,"Current":105,"PowerFactor":0.65,"Phase":-33.67,"Energy":750,"ReverseEnergy":0,"Load":17}, {"ID":3,"Name":"Free Contact 3","State":1,"Action":6,"Delay":5000}, {"ID":4,"Name":"Free Contact 4","State":0,"Action":6,"Delay":5000} ], "Inputs":[ {"ID":1,"Name":"Input 1","State":0,"S0Counter":0}, {"ID":2,"Name":"Input 2","State":0,"S0Counter":0} ]}</code>

= Extended MQTT flex JSON config examples =

== Default NETIO MQTT-flex configuration ==
This example demonstrates setup for connection to public <code>broker.hivemq.com</code>, measurement reporting and output control.

The device cabe be controlled via <code>netio/${DEVICE_NAME}/output/1/action topic</code> by sending standard NETIO action values:
* 0 - OFF
* 1 - ON
* 2 - SHORT OFF
* 3 - SHORT ON
* 4 - TOGGLE
* 5 - NO ACTION.

The device report measurements:

* Output state - every 15 minutes or by change
* Voltage [V]- every 5 minutes or by change of 1 V
* Current [mA]- every 5 minutes or by change of 50 mA
* Load(Power) [W]- every 5 minutes or by change of 10 W
* Energy(Consumption) [Wh]- every 15 minutes or by change of 1Wh
* True Power Factor (TPF) [-]- every 5 minutes or by change of 0.02
* Frequency [Hz]- every 1 hour or by change of 0.1 Hz

For register all values, you can use wildcard <code>netio/${DEVICE_NAME}/output/1/#</code>

{
"config":{
"broker":{
"url":"broker.hivemq.com",
"protocol":"mqtt",
"port":1883,
"ssl":false,
"type":"generic",
"username":"",
"password":"",
"clientid":"moje${DEVICE_NAME}${DEVICE_MAC}",
"keepalive":30
},
"subscribe":[
{
"topic":"netio/${DEVICE_NAME}/output/1/action",
"qos":0,
"target":"OUTPUTS/1/ACTION",
"action":"${payload}"
},
{
"topic":"netio/${DEVICE_NAME}/output/1/switch",
"qos":0,
"target":"OUTPUTS/1/ACTION",
"action":4
}
],
"publish":[
{
"topic":"netio/${DEVICE_MAC}/output/1/state",
"qos":0,
"retain":true,
"payload":"${OUTPUTS/1/STATE}",
"events":[
{
"type":"change",
"source":"OUTPUTS/1/STATE"
},
{
"type":"timer",
"period":900
}
]
},
{
"topic":"netio/${DEVICE_NAME}/output/1/voltage",
"qos":0,
"retain":false,
"payload":"${OUTPUTS/1/VOLTAGE}",
"events":[
{
"type":"timer",
"period":300
},
{
"type":"delta",
"source":"OUTPUTS/1/VOLTAGE",
"delta":1
}
]
},
{
"topic":"netio/${DEVICE_NAME}/output/1/current",
"qos":0,
"retain":false,
"payload":"${OUTPUTS/1/CURRENT}",
"events":[
{
"type":"timer",
"period":300
},
{
"type":"delta",
"source":"OUTPUTS/1/CURRENT",
"delta":50
}
]
},
{
"topic":"netio/${DEVICE_NAME}/output/1/load",
"qos":0,
"retain":false,
"payload":"${OUTPUTS/1/LOAD}",
"events":[
{
"type":"timer",
"period":300
},
{
"type":"delta",
"source":"OUTPUTS/1/LOAD",
"delta":10
}
]
},
{
"topic":"netio/${DEVICE_NAME}/output/1/energy",
"qos":0,
"retain":false,
"payload":"${OUTPUTS/1/ENERGY}",
"events":[
{
"type":"timer",
"period":900
},
{
"type":"delta",
"source":"OUTPUTS/1/ENERGY",
"delta":1
}
]
},
{
"topic":"netio/${DEVICE_NAME}/output/1/tpf",
"qos":0,
"retain":false,
"payload":"${OUTPUTS/1/POWER_FACTOR}",
"events":[
{
"type":"timer",
"period":900
},
{
"type":"delta",
"source":"OUTPUTS/1/POWER_FACTOR",
"delta":0.02
}
]
},
{
"topic":"netio/${DEVICE_NAME}/output/1/frequency",
"qos":0,
"retain":false,
"payload":"${OUTPUTS/1/FREQUENCY}",
"events":[
{
"type":"timer",
"period":3600
},
{
"type":"delta",
"source":"OUTPUTS/1/FREQUENCY",
"delta":0.1
}
]
}
]
}
}

MQTT-flex

2023-06-06T13:44:27Z

Bbakala: /* MQTT Subscribe as event to trigger action */

The MQTT-flex version of the MQTT protocol can be configured in detail thanks to the “flex” extension.

https://www.netio-products.com/en/glossary/mqtt-flex

Why MQTT-flex 
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 [https://en.wikipedia.org/wiki/MQTT 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 [https://en.wikipedia.org/wiki/JSON 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 101x 
* PowerCable REST 101x 
* PowerPDU 4PS 
* PowerPDU 4KS 
* PowerPDU 8QS 
* PowerDIN 4PZ 
* PowerBOX 3Px 
* PowerBOX 4Kx 

FW version: 
>2.2.1

===Not supported NETIO devices:===
* PowerPDU 4C 
* NETIO 4 
* NETIO 4All 

= Simple MQTT-flex configuration + explanation =

''We strongly recommend to create and test MQTT-flex configuration on "local" device what can be easily restarted. The validation of config before saving is not 100% and for example some specific typos can cause a freeze of a device - the solution is to restart a device (unplug/plug input power cable). If the configuration is saved and device is working then there are no known failure case so it is safe to use this configuration on the "remote" devices.''

{
"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":false,
"payload":"${OUTPUTS/1/STATE}",
"events":[
{
"type":"timer",
"period":"1000"
}
]
}
]
}
}
=== Client Configuration (broker section) ===
Put here MQTT client connection setup

This configuration example set NETIO device to connect to broker.hivemq.com with mqtt protocol, no ssl connection with credetials freedom/peace|love|empathy4ALL.

"broker":{
"url":"broker.hivemq.com",
"protocol":"mqtt",
"port":1883,
"ssl":false,
"type":"generic",
"username":"freedom",
"password":"peace|LOVE|empathy4ALL"
},

=== Device Control (subscribe section) ===
Put here array of topics where to subscribe

Device output 1 is controlled with action received by subscription to netio/${DEVICE_NAME}/output/1/action topic with QOS 0

"subscribe":[{
"topic":"netio/${DEVICE_NAME}/output/1/action",
"qos":0,
"target":"OUTPUTS/1/ACTION",
"action":"${payload}"
}
],

=== Output State monitoring (publish section) ===
Put here array of topics where to publish.

Device send every 1000 s message to topic with QOS 0, retain true information with output 1 state

"publish":[{
"topic":"netio/${DEVICE_NAME}/output/1/state",
"qos":0,
"retain":true,
"payload":"${OUTPUTS/1/STATE}",
"events":[
{
"type":"timer",
"period":"1000"
}
]
}
]

= 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 ===
{| class="wikitable"
! style="font-weight:bold; background-color:#9b9b9b;" | Item
! style="font-weight:bold; background-color:#9b9b9b;" | Presence
! style="font-weight:bold; background-color:#9b9b9b;" | Possible Values
! style="font-weight:bold; background-color:#9b9b9b;" | Description
! style="font-weight:bold; background-color:#9b9b9b;" | JSON Config Usage
|-
| style="background-color:#efefef;" | url
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" |
| style="background-color:#efefef;" | MQTT broker URL
| style="background-color:#efefef;" | "url":"broker.hivemq.com"
|-
| style="background-color:#efefef;" | port
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | 1 - 65535
| style="background-color:#efefef;" | MQTT broker port
| style="background-color:#efefef;" | "port":1883
|-
| style="background-color:#efefef;" | protocol
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" |
| style="background-color:#efefef;" | protocol spec - mqtt
| style="background-color:#efefef;" | "protocol": "mqtt"
|-
| style="background-color:#efefef;" | ssl
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | true, false
| style="background-color:#efefef;" | Use SSL crypted communication selector
| style="background-color:#efefef;" | "ssl":false
|-
| style="background-color:#efefef;" | type
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | generic
| style="background-color:#efefef;" | Communication/setup type option
| style="background-color:#efefef;" | "type":"generic"
|-
| style="background-color:#efefef;" | username
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | regexp+len
| style="background-color:#efefef;" | Credentials for MQTT broker. Max. 128 characters (since FW 3.2.4).
| style="background-color:#efefef;" | "username":"freedom"
|-
| style="background-color:#efefef;" | password
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | regexp+len
| style="background-color:#efefef;" | Credentials for MQTT broker. Max. 256 characters (since FW 3.2.4).
| style="background-color:#efefef;" | "password":"peace|LOVE|empathy4ALL"
|-
| style="background-color:#efefef;" | clientid
| style="background-color:#efefef;" | optional
| style="background-color:#efefef;" | regexp+len
| style="background-color:#efefef;" | MQTT clientid. Max. 128 characters (since FW 3.2.4). Variables ${DEVICE_MAC} or ${DEVICE_NAME} can be used
| style="background-color:#efefef;" | "clientid":"myEcoTable01"
|-
| style="background-color:#efefef;" | keepalive
| style="background-color:#efefef;" | optional
| style="background-color:#efefef;" | 1 - 65535
| style="background-color:#efefef;" | MQTT keep alive period in seconds
| style="background-color:#efefef;" | "keepalive":90
|}

Note 1: clientid attribute is mandatory for MQTT(s) communication. When not configured, random ID will be generated.

Note 2: To proper communication with MS Azure - it is necessary to set up IoT Hub to use TLS 1.2

See section "TLS 1.2 enforcement available in select regions" in following guidelines https://docs.microsoft.com/en-us/azure/iot-hub/iot-hub-tls-support

=== Examples ===
==== Standard setup ====

==== Security (SSL / TLS) secured setup ====
You can enable MQTTs by using the encrypted port 8883 + "ssl":true.

==== Variables used setup ====

== 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 ===
{| class="wikitable"
! style="font-weight:bold; background-color:#9b9b9b;" | Item
! style="font-weight:bold; background-color:#9b9b9b;" | Presence
! style="font-weight:bold; background-color:#9b9b9b;" | Possible Values
! style="font-weight:bold; background-color:#9b9b9b;" | Description
! style="font-weight:bold; background-color:#9b9b9b;" | JSON Config Usage
|-
| style="background-color:#efefef;" | topic
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | see table below
| style="background-color:#efefef;" | specification of the topic, which MQTT-flex device listens from broker and act accordingly. Max. 128 characters. The "#" can be used since FW 3.2.4 - see note under this table.
| style="background-color:#efefef;" | "topic":"netio/${DEVICE_NAME}/output/1/action"
|-
| style="background-color:#efefef;" | qos
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | 0, 1 or 2
| style="background-color:#efefef;" | 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}
| style="background-color:#efefef;" | "qos":0
|-
| style="background-color:#efefef;" | target
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" |
| style="background-color:#efefef;" | internal definition of action, which can be performed above the specified output
| style="background-color:#efefef;" | "target":"OUTPUTS/1/ACTION"
|-
| style="background-color:#efefef;" | action
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" |
| style="background-color:#efefef;" | a payload or a value the action attribute needs to have passed to
| style="background-color:#efefef;" | "action":"${payload}"
|-
| style="background-color:#efefef;" | actiondefNot supported yet
| style="background-color:#efefef;" | optional
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
|-
| style="background-color:#efefef;" | jsonNot supported yet
| style="background-color:#efefef;" | optional
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
|}

Note: The "#" wildcard can be used in subscribe topic definition. The multi-level wildcard character MUST be specified either on its own or following a topic level separator. In either case it MUST be the last character specified in the Topic.

For example, if a Device subscribes to “devices/{device_id}/messages/devicebound/#”, it would receive messages published using these topic names:

“devices/{device_id}/messages/devicebound/”

“devices/{device_id}/messages/devicebound/{property_bag}”

This should be usefull for use with MS Azure - IoT hub.

=== MQTT Subscribe as event to trigger action <code>FW 4.0.0+</code> ===

This feature allow to subscribe to specific MQTT topic and pass payload to Rules or MQTT-flex as event.

target: <code>PROTOCOLS/MQTT/EVENT</code>

"subscribe": [
{
"action": "${payload}",
"qos": 0,
"target": "PROTOCOLS/MQTT/EVENT",
"topic": "broker/12345/MQTT_EVENT/"
}
]

=== Examples ===
==== Toggle output with standard payload ====
==== Toggle output with custom payload ====
==== Subscribe to more than one topic ====
==== Trigger Rule sequence from MQTT ====
==== Trigger MQTT publish by MQTT subscribe ====

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 ===
{| class="wikitable"
! style="font-weight:bold; background-color:#9b9b9b;" | Item
! style="font-weight:bold; background-color:#9b9b9b;" | Presence
! style="font-weight:bold; background-color:#9b9b9b;" | Possible Values
! style="font-weight:bold; background-color:#9b9b9b;" | Description
! style="font-weight:bold; background-color:#9b9b9b;" | JSON Config Usage
|-
| style="background-color:#efefef;" | topic
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | see table below
| style="background-color:#efefef;" | definition of the topic, how it is registered towards MQTT broker. Max. 128 characters.
| style="background-color:#efefef;" | "topic":"netio/${DEVICE_NAME}/output/1/load"
|-
| style="background-color:#efefef;" | qos
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | see table below
| style="background-color:#efefef;" | 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}
| style="background-color:#efefef;" |
|-
| style="background-color:#efefef;" | retain
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | boolean: true or false
| style="background-color:#efefef;" | 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}
| style="background-color:#efefef;" | "retain":true
|-
| style="background-color:#efefef;" | payload
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | see table below
| style="background-color:#efefef;" | definition of the payload, what is send to the MQTT broker.
| style="background-color:#efefef;" | "payload":"${OUTPUTS/1/STATE}"
|-
| style="background-color:#efefef;" | events
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | see table below
| style="background-color:#efefef;" | definition of events used for triggering sending of data via mqtt (change, delta, timer)
| style="background-color:#efefef;" |
|-
| style="background-color:#efefef;" | type
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
|-
| style="background-color:#efefef;" | source
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
|-
| style="background-color:#efefef;" | delta
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
|-
| style="background-color:#efefef;" | period
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
|-
| style="background-color:#efefef;" | payloaddefNot supported yet
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
|}

=== Examples ===
==== Publish energy periodically (event timer) ====
==== Publish current on change (delta) ====
==== Publish output state ====
==== Publish to more than one topic with different events ====

= 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 available only on NETIO PowerDIN 4PZ

=== Examples: ===

adressing controll of output 3
OUTPUTS/3/ACTION
getting voltage on output 1
OUTPUTS/1/VOLTAGE
getting state of input 1
INPUTS/1/STATE

= Events =
==== Timer ====

==== Delta ====

==== Change ====

==== Group Events<code>FW 4.0.0+</code>====

= 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 ===
==== VOLTAGE ====
Unit: <code>V</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Present RMS voltage on output 1 is ${OUTPUTS/1/VOLTAGE}"</code>

Example 2: <code>"source":"${OUTPUTS/1/VOLTAGE}"</code>

==== CURRENT ====
Unit: <code>mA</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Present RMS current on output 1 is ${OUTPUTS/1/CURRENT}"</code>

Example 2: <code>"source":"${OUTPUTS/1/CURRENT}"</code>

==== POWER_FACTOR ====
Unit: <code>[-]</code>

Type: float (2 decimals)

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"True Power Factor on output 1 is ${OUTPUTS/1/POWER_FACTOR}"</code>

Example 2: <code>"source":"${OUTPUTS/1/POWER_FACTOR}"</code>

==== LOAD ====
Unit: <code>W</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Present load on output 1 is ${OUTPUTS/1/LOAD}W"</code>

Example 2: <code>"payload":"Device's load connected to output 1 is ${OUTPUTS/1/LOAD}W"</code>

Example 3: <code>"source":"${OUTPUTS/1/LOAD}"</code>

==== STATE ====
Type: bool(integer) - <code>0</code> or <code>1</code>

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Present output 1 state is ${OUTPUTS/1/STATE}"</code>

Example 2: <code>"source":"${OUTPUTS/1/STATE}"</code>

==== ACTION ====
Type: integer

Possible actions:
* <code>0</code> - set state OFF
* <code>1</code> - set state ON
* <code>2</code> - short OFF (restart)
* <code>3</code> - short ON
* <code>4</code> - toggle (switch)
* <code>5</code> - no change

Allowed in: <code>"target"</code>

Example: <code>"target":"OUTPUTS/1/ACTION"</code>

==== DELAY [ms] ====
==== NAME ====
==== FREQUENCY ====
Unit: <code>Hz</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example: <code>"payload":"Frequency in power grid is ${OUTPUTS/1/ENERGY}Hz"</code>

==== ENERGY ====
Energy consumed by an device connected to NETIO device output.

Unit: <code>Wh</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Consumed energy on output 1 is ${OUTPUTS/1/ENERGY}Wh"</code>

Example 2: <code>"source":"${OUTPUTS/1/ENERGY}"</code>

==== REVERSE_ENERGY ====
Energy delivered back to grid. For example from solar system connected to NETIO device output.

Unit: <code>Wh</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Delivered energy on output 1 is ${OUTPUTS/1/REVERSE_ENERGY}Wh"</code>

Example 2: <code>"source":"${OUTPUTS/1/REVERSE_ENERGY}"</code>

==== ENERGY_START ====
Date when the counters ENERGY and REVERSE_ENERGY have been resetted by user.

Unit: <code>unix timestamp</code>

Type: integer

Allowed in: <code>"payload"</code>

Example 1: <code>"payload":"Energy measured since ${OUTPUTS/1/ENERGY_START} unix time"</code>

Example 2: <code>"payload":"${OUTPUTS/1/ENERGY_START}"</code> is output payload <code>1567654639</code>

==== ENERGY_START_FMT ====
Date when the counters ENERGY and REVERSE_ENERGY have been resetted by user.

Unit: <code>fmt date format</code>

Type: string

Allowed in: <code>"payload"</code>

Example 1: <code>"payload":"Energy measured since ${OUTPUTS/1/ENERGY_START}"</code>

Example 2: <code>"payload":"${OUTPUTS/1/ENERGY_START_FMT}"</code> is output payload <code>2019-09-05T03:37:19+00:00</code>

==== ENERGY_NR ====
Non-resettable counter of Energy consumed by an device connected to NETIO device output.

Unit: <code>Wh</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Consumed energy on output 1 is ${OUTPUTS/1/ENERGY_NR}Wh"</code>

Example 2: <code>"source":"${OUTPUTS/1/ENERGY_NR}"</code>

==== REVERSE_ENERGY_NR ====
Non-resettable counter of Energy delivered back to grid. For example from solar system connected to NETIO device output.

Unit: <code>Wh</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Delivered energy on output 1 is ${OUTPUTS/1/REVERSE_ENERGY_NR}Wh"</code>

Example 2: <code>"source":"${OUTPUTS/1/REVERSE_ENERGY_NR}"</code>

==== TOTALs - for 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
* OUTPUTS/TOTAL/PHASE
* OUTPUTS/TOTAL/REVERSE_ENERGY
* OUTPUTS/TOTAL/ENERGY_NR
* OUTPUTS/TOTAL/REVERSE_ENERGY_NR
* OUTPUTS/TOTAL/ENERGY_START
* OUTPUTS/TOTAL/ENERGY_START_FMT

==== REST_JSON ====
Allow use of NETIO JSON structure to control outputs.

Type: string / JSON

Allowed in: <code>"target"</code> for Subscribe section

Example: <code>"target": "REST_JSON"</code>

The payload is JSON structure identical to NETIO JSON API M2M Protocol (documentation available at https://www.netio-products.com/files/NETIO-M2M-API-Protocol-JSON.pdf). You can control one or multiple outputs.

Payload example 1 - Toggle output 1: <code>{"Outputs":[{"ID": 1,"Action": 4}]}</code>

Payload example 2 - Turn output 1 OFF and output 3 ON: <code>{"Outputs":[{"ID":1,"Action":0},{"ID":3,"Action":1}]}</code>

=== INPUT variables ===
==== STATE ====
Type: bool(integer) - <code>0</code> or <code>1</code>

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Present input 1 state is ${INPUTS/1/STATE}"</code>

Example 2: <code>"source":"${INPUTS/1/STATE}"</code>

==== S0 ====
S0 Counter value
Unit: <code>-</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Input 1 S0 Counter value is ${INPUTS/1/S0}impulses"</code>

Example 2: <code>"source":"${INPUTS/1/S0}"</code>

== Payload/topic variables ==

=== DEVICE_NAME ===
Can be used in: "payload", "topic"

Example 1: <code>"payload":"${DEVICE_NAME}"</code>

Example 2: <code>"topic":"netio/${DEVICE_NAME}/output/1/action"</code>

=== DEVICE_MAC ===

=== UPTIME Not yet implemented ===

=== PAYLOAD ===
Can be used in: "action"

Example: <code>"action":"${PAYLOAD}"</code>

=== OUTPUT_ID Not yet implemented===

=== WIFI_SIGNALNot yet implemented ===

=== OUTPUTS_STATUS ===
Provide complete outputs status and measurement if supported.

Type: string / JSON

Allowed in: <code>"payload"</code> for Publish section

Example: <code>"payload":"${OUTPUTS_STATUS}"</code>

Payload example: <code>{ "GlobalMeasure":{"Voltage":236,"TotalCurrent":72,"TotalLoad":11,"TotalEnergy":167,"OverallPowerFactor":0.64,"Frequency":50.07,"Phase":-36.86,"EnergyStart":"2020-06-30T17:04:48+01:00"}, "Outputs":[ {"ID":1,"Name":"Power output 1","State":1,"Action":6,"Delay":2020,"Current":72,"PowerFactor":0.64,"Phase":-36.86,"Energy":139,"ReverseEnergy":0,"Load":11}, {"ID":2,"Name":"Power output 2","State":1,"Action":6,"Delay":2020,"Current":0,"PowerFactor":1.00,"Phase":0.00,"Energy":27,"ReverseEnergy":0,"Load":0}, {"ID":3,"Name":"Free Contact 3","State":1,"Action":6,"Delay":2020}, {"ID":4,"Name":"Free Contact 4","State":1,"Action":6,"Delay":2020} ]}</code>

=== INPUTS_STATUS ===
Provide complete inputs status if supported. Since FW 3.0.0

Type: string / JSON

Allowed in: <code>"payload"</code> for Publish section

Example: <code>"payload":"${INPUTS_STATUS}"</code>

Payload example: <code>{ "Inputs":[ {"ID":1,"Name":"Input 1","State":0,"S0Counter":0}, {"ID":2,"Name":"Input 2","State":0,"S0Counter":0} ]}</code>

=== INOUT_STATUS ===
Provide complete inputs and output status and measurement if supported. Since FW 3.0.0

Type: string / JSON

Allowed in: <code>"payload"</code> for Publish section

Example: <code>"payload":"${INOUT_STATUS}"</code>

Payload example: <code>{ "GlobalMeasure":{"Voltage":238,"TotalCurrent":105,"TotalLoad":17,"TotalEnergy":1451,"OverallPowerFactor":0.67,"Frequency":50.03,"Phase":-33.67,"EnergyStart":"2020-06-30T17:04:48+01:00"}, "Outputs":[ {"ID":1,"Name":"Power output 1","State":0,"Action":6,"Delay":5000,"Current":0,"PowerFactor":1.00,"Phase":0.00,"Energy":701,"ReverseEnergy":0,"Load":0}, {"ID":2,"Name":"Power output 2","State":1,"Action":6,"Delay":5000,"Current":105,"PowerFactor":0.65,"Phase":-33.67,"Energy":750,"ReverseEnergy":0,"Load":17}, {"ID":3,"Name":"Free Contact 3","State":1,"Action":6,"Delay":5000}, {"ID":4,"Name":"Free Contact 4","State":0,"Action":6,"Delay":5000} ], "Inputs":[ {"ID":1,"Name":"Input 1","State":0,"S0Counter":0}, {"ID":2,"Name":"Input 2","State":0,"S0Counter":0} ]}</code>

= Extended MQTT flex JSON config examples =

== Default NETIO MQTT-flex configuration ==
This example demonstrates setup for connection to public <code>broker.hivemq.com</code>, measurement reporting and output control.

The device cabe be controlled via <code>netio/${DEVICE_NAME}/output/1/action topic</code> by sending standard NETIO action values:
* 0 - OFF
* 1 - ON
* 2 - SHORT OFF
* 3 - SHORT ON
* 4 - TOGGLE
* 5 - NO ACTION.

The device report measurements:

* Output state - every 15 minutes or by change
* Voltage [V]- every 5 minutes or by change of 1 V
* Current [mA]- every 5 minutes or by change of 50 mA
* Load(Power) [W]- every 5 minutes or by change of 10 W
* Energy(Consumption) [Wh]- every 15 minutes or by change of 1Wh
* True Power Factor (TPF) [-]- every 5 minutes or by change of 0.02
* Frequency [Hz]- every 1 hour or by change of 0.1 Hz

For register all values, you can use wildcard <code>netio/${DEVICE_NAME}/output/1/#</code>

{
"config":{
"broker":{
"url":"broker.hivemq.com",
"protocol":"mqtt",
"port":1883,
"ssl":false,
"type":"generic",
"username":"",
"password":"",
"clientid":"moje${DEVICE_NAME}${DEVICE_MAC}",
"keepalive":30
},
"subscribe":[
{
"topic":"netio/${DEVICE_NAME}/output/1/action",
"qos":0,
"target":"OUTPUTS/1/ACTION",
"action":"${payload}"
},
{
"topic":"netio/${DEVICE_NAME}/output/1/switch",
"qos":0,
"target":"OUTPUTS/1/ACTION",
"action":4
}
],
"publish":[
{
"topic":"netio/${DEVICE_MAC}/output/1/state",
"qos":0,
"retain":true,
"payload":"${OUTPUTS/1/STATE}",
"events":[
{
"type":"change",
"source":"OUTPUTS/1/STATE"
},
{
"type":"timer",
"period":900
}
]
},
{
"topic":"netio/${DEVICE_NAME}/output/1/voltage",
"qos":0,
"retain":false,
"payload":"${OUTPUTS/1/VOLTAGE}",
"events":[
{
"type":"timer",
"period":300
},
{
"type":"delta",
"source":"OUTPUTS/1/VOLTAGE",
"delta":1
}
]
},
{
"topic":"netio/${DEVICE_NAME}/output/1/current",
"qos":0,
"retain":false,
"payload":"${OUTPUTS/1/CURRENT}",
"events":[
{
"type":"timer",
"period":300
},
{
"type":"delta",
"source":"OUTPUTS/1/CURRENT",
"delta":50
}
]
},
{
"topic":"netio/${DEVICE_NAME}/output/1/load",
"qos":0,
"retain":false,
"payload":"${OUTPUTS/1/LOAD}",
"events":[
{
"type":"timer",
"period":300
},
{
"type":"delta",
"source":"OUTPUTS/1/LOAD",
"delta":10
}
]
},
{
"topic":"netio/${DEVICE_NAME}/output/1/energy",
"qos":0,
"retain":false,
"payload":"${OUTPUTS/1/ENERGY}",
"events":[
{
"type":"timer",
"period":900
},
{
"type":"delta",
"source":"OUTPUTS/1/ENERGY",
"delta":1
}
]
},
{
"topic":"netio/${DEVICE_NAME}/output/1/tpf",
"qos":0,
"retain":false,
"payload":"${OUTPUTS/1/POWER_FACTOR}",
"events":[
{
"type":"timer",
"period":900
},
{
"type":"delta",
"source":"OUTPUTS/1/POWER_FACTOR",
"delta":0.02
}
]
},
{
"topic":"netio/${DEVICE_NAME}/output/1/frequency",
"qos":0,
"retain":false,
"payload":"${OUTPUTS/1/FREQUENCY}",
"events":[
{
"type":"timer",
"period":3600
},
{
"type":"delta",
"source":"OUTPUTS/1/FREQUENCY",
"delta":0.1
}
]
}
]
}
}

MQTT-flex

2023-06-06T13:15:11Z

Bbakala: /* MQTT Event to rules */

The MQTT-flex version of the MQTT protocol can be configured in detail thanks to the “flex” extension.

https://www.netio-products.com/en/glossary/mqtt-flex

Why MQTT-flex 
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 [https://en.wikipedia.org/wiki/MQTT 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 [https://en.wikipedia.org/wiki/JSON 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 101x 
* PowerCable REST 101x 
* PowerPDU 4PS 
* PowerPDU 4KS 
* PowerPDU 8QS 
* PowerDIN 4PZ 
* PowerBOX 3Px 
* PowerBOX 4Kx 

FW version: 
>2.2.1

===Not supported NETIO devices:===
* PowerPDU 4C 
* NETIO 4 
* NETIO 4All 

= Simple MQTT-flex configuration + explanation =

''We strongly recommend to create and test MQTT-flex configuration on "local" device what can be easily restarted. The validation of config before saving is not 100% and for example some specific typos can cause a freeze of a device - the solution is to restart a device (unplug/plug input power cable). If the configuration is saved and device is working then there are no known failure case so it is safe to use this configuration on the "remote" devices.''

{
"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":false,
"payload":"${OUTPUTS/1/STATE}",
"events":[
{
"type":"timer",
"period":"1000"
}
]
}
]
}
}
=== Client Configuration (broker section) ===
Put here MQTT client connection setup

This configuration example set NETIO device to connect to broker.hivemq.com with mqtt protocol, no ssl connection with credetials freedom/peace|love|empathy4ALL.

"broker":{
"url":"broker.hivemq.com",
"protocol":"mqtt",
"port":1883,
"ssl":false,
"type":"generic",
"username":"freedom",
"password":"peace|LOVE|empathy4ALL"
},

=== Device Control (subscribe section) ===
Put here array of topics where to subscribe

Device output 1 is controlled with action received by subscription to netio/${DEVICE_NAME}/output/1/action topic with QOS 0

"subscribe":[{
"topic":"netio/${DEVICE_NAME}/output/1/action",
"qos":0,
"target":"OUTPUTS/1/ACTION",
"action":"${payload}"
}
],

=== Output State monitoring (publish section) ===
Put here array of topics where to publish.

Device send every 1000 s message to topic with QOS 0, retain true information with output 1 state

"publish":[{
"topic":"netio/${DEVICE_NAME}/output/1/state",
"qos":0,
"retain":true,
"payload":"${OUTPUTS/1/STATE}",
"events":[
{
"type":"timer",
"period":"1000"
}
]
}
]

= 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 ===
{| class="wikitable"
! style="font-weight:bold; background-color:#9b9b9b;" | Item
! style="font-weight:bold; background-color:#9b9b9b;" | Presence
! style="font-weight:bold; background-color:#9b9b9b;" | Possible Values
! style="font-weight:bold; background-color:#9b9b9b;" | Description
! style="font-weight:bold; background-color:#9b9b9b;" | JSON Config Usage
|-
| style="background-color:#efefef;" | url
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" |
| style="background-color:#efefef;" | MQTT broker URL
| style="background-color:#efefef;" | "url":"broker.hivemq.com"
|-
| style="background-color:#efefef;" | port
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | 1 - 65535
| style="background-color:#efefef;" | MQTT broker port
| style="background-color:#efefef;" | "port":1883
|-
| style="background-color:#efefef;" | protocol
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" |
| style="background-color:#efefef;" | protocol spec - mqtt
| style="background-color:#efefef;" | "protocol": "mqtt"
|-
| style="background-color:#efefef;" | ssl
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | true, false
| style="background-color:#efefef;" | Use SSL crypted communication selector
| style="background-color:#efefef;" | "ssl":false
|-
| style="background-color:#efefef;" | type
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | generic
| style="background-color:#efefef;" | Communication/setup type option
| style="background-color:#efefef;" | "type":"generic"
|-
| style="background-color:#efefef;" | username
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | regexp+len
| style="background-color:#efefef;" | Credentials for MQTT broker. Max. 128 characters (since FW 3.2.4).
| style="background-color:#efefef;" | "username":"freedom"
|-
| style="background-color:#efefef;" | password
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | regexp+len
| style="background-color:#efefef;" | Credentials for MQTT broker. Max. 256 characters (since FW 3.2.4).
| style="background-color:#efefef;" | "password":"peace|LOVE|empathy4ALL"
|-
| style="background-color:#efefef;" | clientid
| style="background-color:#efefef;" | optional
| style="background-color:#efefef;" | regexp+len
| style="background-color:#efefef;" | MQTT clientid. Max. 128 characters (since FW 3.2.4). Variables ${DEVICE_MAC} or ${DEVICE_NAME} can be used
| style="background-color:#efefef;" | "clientid":"myEcoTable01"
|-
| style="background-color:#efefef;" | keepalive
| style="background-color:#efefef;" | optional
| style="background-color:#efefef;" | 1 - 65535
| style="background-color:#efefef;" | MQTT keep alive period in seconds
| style="background-color:#efefef;" | "keepalive":90
|}

Note 1: clientid attribute is mandatory for MQTT(s) communication. When not configured, random ID will be generated.

Note 2: To proper communication with MS Azure - it is necessary to set up IoT Hub to use TLS 1.2

See section "TLS 1.2 enforcement available in select regions" in following guidelines https://docs.microsoft.com/en-us/azure/iot-hub/iot-hub-tls-support

=== Examples ===
==== Standard setup ====

==== Security (SSL / TLS) secured setup ====
You can enable MQTTs by using the encrypted port 8883 + "ssl":true.

==== Variables used setup ====

== 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 ===
{| class="wikitable"
! style="font-weight:bold; background-color:#9b9b9b;" | Item
! style="font-weight:bold; background-color:#9b9b9b;" | Presence
! style="font-weight:bold; background-color:#9b9b9b;" | Possible Values
! style="font-weight:bold; background-color:#9b9b9b;" | Description
! style="font-weight:bold; background-color:#9b9b9b;" | JSON Config Usage
|-
| style="background-color:#efefef;" | topic
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | see table below
| style="background-color:#efefef;" | specification of the topic, which MQTT-flex device listens from broker and act accordingly. Max. 128 characters. The "#" can be used since FW 3.2.4 - see note under this table.
| style="background-color:#efefef;" | "topic":"netio/${DEVICE_NAME}/output/1/action"
|-
| style="background-color:#efefef;" | qos
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | 0, 1 or 2
| style="background-color:#efefef;" | 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}
| style="background-color:#efefef;" | "qos":0
|-
| style="background-color:#efefef;" | target
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" |
| style="background-color:#efefef;" | internal definition of action, which can be performed above the specified output
| style="background-color:#efefef;" | "target":"OUTPUTS/1/ACTION"
|-
| style="background-color:#efefef;" | action
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" |
| style="background-color:#efefef;" | a payload or a value the action attribute needs to have passed to
| style="background-color:#efefef;" | "action":"${payload}"
|-
| style="background-color:#efefef;" | actiondefNot supported yet
| style="background-color:#efefef;" | optional
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
|-
| style="background-color:#efefef;" | jsonNot supported yet
| style="background-color:#efefef;" | optional
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
|}

Note: The "#" wildcard can be used in subscribe topic definition. The multi-level wildcard character MUST be specified either on its own or following a topic level separator. In either case it MUST be the last character specified in the Topic.

For example, if a Device subscribes to “devices/{device_id}/messages/devicebound/#”, it would receive messages published using these topic names:

“devices/{device_id}/messages/devicebound/”

“devices/{device_id}/messages/devicebound/{property_bag}”

This should be usefull for use with MS Azure - IoT hub.

=== MQTT Subscribe as event to trigger action ===

This feature allow to subscribe to specific MQTT topic and pass payload to Rules or MQTT-flex as event.

target: <code>PROTOCOLS/MQTT/EVENT</code>

"subscribe": [
{
"action": "${payload}",
"qos": 0,
"target": "PROTOCOLS/MQTT/EVENT",
"topic": "broker/12345/MQTT_EVENT/"
}
]

=== Examples ===
==== Toggle output with standard payload ====
==== Toggle output with custom payload ====
==== Subscribe to more than one topic ====
==== Trigger Rule sequence from MQTT ====
==== Trigger MQTT publish by MQTT subscribe ====

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 ===
{| class="wikitable"
! style="font-weight:bold; background-color:#9b9b9b;" | Item
! style="font-weight:bold; background-color:#9b9b9b;" | Presence
! style="font-weight:bold; background-color:#9b9b9b;" | Possible Values
! style="font-weight:bold; background-color:#9b9b9b;" | Description
! style="font-weight:bold; background-color:#9b9b9b;" | JSON Config Usage
|-
| style="background-color:#efefef;" | topic
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | see table below
| style="background-color:#efefef;" | definition of the topic, how it is registered towards MQTT broker. Max. 128 characters.
| style="background-color:#efefef;" | "topic":"netio/${DEVICE_NAME}/output/1/load"
|-
| style="background-color:#efefef;" | qos
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | see table below
| style="background-color:#efefef;" | 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}
| style="background-color:#efefef;" |
|-
| style="background-color:#efefef;" | retain
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | boolean: true or false
| style="background-color:#efefef;" | 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}
| style="background-color:#efefef;" | "retain":true
|-
| style="background-color:#efefef;" | payload
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | see table below
| style="background-color:#efefef;" | definition of the payload, what is send to the MQTT broker.
| style="background-color:#efefef;" | "payload":"${OUTPUTS/1/STATE}"
|-
| style="background-color:#efefef;" | events
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | see table below
| style="background-color:#efefef;" | definition of events used for triggering sending of data via mqtt (change, delta, timer)
| style="background-color:#efefef;" |
|-
| style="background-color:#efefef;" | type
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
|-
| style="background-color:#efefef;" | source
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
|-
| style="background-color:#efefef;" | delta
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
|-
| style="background-color:#efefef;" | period
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
|-
| style="background-color:#efefef;" | payloaddefNot supported yet
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
|}

=== Examples ===
==== Publish energy periodically (event timer) ====
==== Publish current on change (delta) ====
==== Publish output state ====
==== Publish to more than one topic with different events ====

= 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 available only on NETIO PowerDIN 4PZ

=== Examples: ===

adressing controll of output 3
OUTPUTS/3/ACTION
getting voltage on output 1
OUTPUTS/1/VOLTAGE
getting state of input 1
INPUTS/1/STATE

= Events =
==== Timer ====

==== Delta ====

==== Change ====

==== Group Events<code>FW 4.0.0+</code>====

= 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 ===
==== VOLTAGE ====
Unit: <code>V</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Present RMS voltage on output 1 is ${OUTPUTS/1/VOLTAGE}"</code>

Example 2: <code>"source":"${OUTPUTS/1/VOLTAGE}"</code>

==== CURRENT ====
Unit: <code>mA</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Present RMS current on output 1 is ${OUTPUTS/1/CURRENT}"</code>

Example 2: <code>"source":"${OUTPUTS/1/CURRENT}"</code>

==== POWER_FACTOR ====
Unit: <code>[-]</code>

Type: float (2 decimals)

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"True Power Factor on output 1 is ${OUTPUTS/1/POWER_FACTOR}"</code>

Example 2: <code>"source":"${OUTPUTS/1/POWER_FACTOR}"</code>

==== LOAD ====
Unit: <code>W</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Present load on output 1 is ${OUTPUTS/1/LOAD}W"</code>

Example 2: <code>"payload":"Device's load connected to output 1 is ${OUTPUTS/1/LOAD}W"</code>

Example 3: <code>"source":"${OUTPUTS/1/LOAD}"</code>

==== STATE ====
Type: bool(integer) - <code>0</code> or <code>1</code>

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Present output 1 state is ${OUTPUTS/1/STATE}"</code>

Example 2: <code>"source":"${OUTPUTS/1/STATE}"</code>

==== ACTION ====
Type: integer

Possible actions:
* <code>0</code> - set state OFF
* <code>1</code> - set state ON
* <code>2</code> - short OFF (restart)
* <code>3</code> - short ON
* <code>4</code> - toggle (switch)
* <code>5</code> - no change

Allowed in: <code>"target"</code>

Example: <code>"target":"OUTPUTS/1/ACTION"</code>

==== DELAY [ms] ====
==== NAME ====
==== FREQUENCY ====
Unit: <code>Hz</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example: <code>"payload":"Frequency in power grid is ${OUTPUTS/1/ENERGY}Hz"</code>

==== ENERGY ====
Energy consumed by an device connected to NETIO device output.

Unit: <code>Wh</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Consumed energy on output 1 is ${OUTPUTS/1/ENERGY}Wh"</code>

Example 2: <code>"source":"${OUTPUTS/1/ENERGY}"</code>

==== REVERSE_ENERGY ====
Energy delivered back to grid. For example from solar system connected to NETIO device output.

Unit: <code>Wh</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Delivered energy on output 1 is ${OUTPUTS/1/REVERSE_ENERGY}Wh"</code>

Example 2: <code>"source":"${OUTPUTS/1/REVERSE_ENERGY}"</code>

==== ENERGY_START ====
Date when the counters ENERGY and REVERSE_ENERGY have been resetted by user.

Unit: <code>unix timestamp</code>

Type: integer

Allowed in: <code>"payload"</code>

Example 1: <code>"payload":"Energy measured since ${OUTPUTS/1/ENERGY_START} unix time"</code>

Example 2: <code>"payload":"${OUTPUTS/1/ENERGY_START}"</code> is output payload <code>1567654639</code>

==== ENERGY_START_FMT ====
Date when the counters ENERGY and REVERSE_ENERGY have been resetted by user.

Unit: <code>fmt date format</code>

Type: string

Allowed in: <code>"payload"</code>

Example 1: <code>"payload":"Energy measured since ${OUTPUTS/1/ENERGY_START}"</code>

Example 2: <code>"payload":"${OUTPUTS/1/ENERGY_START_FMT}"</code> is output payload <code>2019-09-05T03:37:19+00:00</code>

==== ENERGY_NR ====
Non-resettable counter of Energy consumed by an device connected to NETIO device output.

Unit: <code>Wh</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Consumed energy on output 1 is ${OUTPUTS/1/ENERGY_NR}Wh"</code>

Example 2: <code>"source":"${OUTPUTS/1/ENERGY_NR}"</code>

==== REVERSE_ENERGY_NR ====
Non-resettable counter of Energy delivered back to grid. For example from solar system connected to NETIO device output.

Unit: <code>Wh</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Delivered energy on output 1 is ${OUTPUTS/1/REVERSE_ENERGY_NR}Wh"</code>

Example 2: <code>"source":"${OUTPUTS/1/REVERSE_ENERGY_NR}"</code>

==== TOTALs - for 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
* OUTPUTS/TOTAL/PHASE
* OUTPUTS/TOTAL/REVERSE_ENERGY
* OUTPUTS/TOTAL/ENERGY_NR
* OUTPUTS/TOTAL/REVERSE_ENERGY_NR
* OUTPUTS/TOTAL/ENERGY_START
* OUTPUTS/TOTAL/ENERGY_START_FMT

==== REST_JSON ====
Allow use of NETIO JSON structure to control outputs.

Type: string / JSON

Allowed in: <code>"target"</code> for Subscribe section

Example: <code>"target": "REST_JSON"</code>

The payload is JSON structure identical to NETIO JSON API M2M Protocol (documentation available at https://www.netio-products.com/files/NETIO-M2M-API-Protocol-JSON.pdf). You can control one or multiple outputs.

Payload example 1 - Toggle output 1: <code>{"Outputs":[{"ID": 1,"Action": 4}]}</code>

Payload example 2 - Turn output 1 OFF and output 3 ON: <code>{"Outputs":[{"ID":1,"Action":0},{"ID":3,"Action":1}]}</code>

=== INPUT variables ===
==== STATE ====
Type: bool(integer) - <code>0</code> or <code>1</code>

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Present input 1 state is ${INPUTS/1/STATE}"</code>

Example 2: <code>"source":"${INPUTS/1/STATE}"</code>

==== S0 ====
S0 Counter value
Unit: <code>-</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Input 1 S0 Counter value is ${INPUTS/1/S0}impulses"</code>

Example 2: <code>"source":"${INPUTS/1/S0}"</code>

== Payload/topic variables ==

=== DEVICE_NAME ===
Can be used in: "payload", "topic"

Example 1: <code>"payload":"${DEVICE_NAME}"</code>

Example 2: <code>"topic":"netio/${DEVICE_NAME}/output/1/action"</code>

=== DEVICE_MAC ===

=== UPTIME Not yet implemented ===

=== PAYLOAD ===
Can be used in: "action"

Example: <code>"action":"${PAYLOAD}"</code>

=== OUTPUT_ID Not yet implemented===

=== WIFI_SIGNALNot yet implemented ===

=== OUTPUTS_STATUS ===
Provide complete outputs status and measurement if supported.

Type: string / JSON

Allowed in: <code>"payload"</code> for Publish section

Example: <code>"payload":"${OUTPUTS_STATUS}"</code>

Payload example: <code>{ "GlobalMeasure":{"Voltage":236,"TotalCurrent":72,"TotalLoad":11,"TotalEnergy":167,"OverallPowerFactor":0.64,"Frequency":50.07,"Phase":-36.86,"EnergyStart":"2020-06-30T17:04:48+01:00"}, "Outputs":[ {"ID":1,"Name":"Power output 1","State":1,"Action":6,"Delay":2020,"Current":72,"PowerFactor":0.64,"Phase":-36.86,"Energy":139,"ReverseEnergy":0,"Load":11}, {"ID":2,"Name":"Power output 2","State":1,"Action":6,"Delay":2020,"Current":0,"PowerFactor":1.00,"Phase":0.00,"Energy":27,"ReverseEnergy":0,"Load":0}, {"ID":3,"Name":"Free Contact 3","State":1,"Action":6,"Delay":2020}, {"ID":4,"Name":"Free Contact 4","State":1,"Action":6,"Delay":2020} ]}</code>

=== INPUTS_STATUS ===
Provide complete inputs status if supported. Since FW 3.0.0

Type: string / JSON

Allowed in: <code>"payload"</code> for Publish section

Example: <code>"payload":"${INPUTS_STATUS}"</code>

Payload example: <code>{ "Inputs":[ {"ID":1,"Name":"Input 1","State":0,"S0Counter":0}, {"ID":2,"Name":"Input 2","State":0,"S0Counter":0} ]}</code>

=== INOUT_STATUS ===
Provide complete inputs and output status and measurement if supported. Since FW 3.0.0

Type: string / JSON

Allowed in: <code>"payload"</code> for Publish section

Example: <code>"payload":"${INOUT_STATUS}"</code>

Payload example: <code>{ "GlobalMeasure":{"Voltage":238,"TotalCurrent":105,"TotalLoad":17,"TotalEnergy":1451,"OverallPowerFactor":0.67,"Frequency":50.03,"Phase":-33.67,"EnergyStart":"2020-06-30T17:04:48+01:00"}, "Outputs":[ {"ID":1,"Name":"Power output 1","State":0,"Action":6,"Delay":5000,"Current":0,"PowerFactor":1.00,"Phase":0.00,"Energy":701,"ReverseEnergy":0,"Load":0}, {"ID":2,"Name":"Power output 2","State":1,"Action":6,"Delay":5000,"Current":105,"PowerFactor":0.65,"Phase":-33.67,"Energy":750,"ReverseEnergy":0,"Load":17}, {"ID":3,"Name":"Free Contact 3","State":1,"Action":6,"Delay":5000}, {"ID":4,"Name":"Free Contact 4","State":0,"Action":6,"Delay":5000} ], "Inputs":[ {"ID":1,"Name":"Input 1","State":0,"S0Counter":0}, {"ID":2,"Name":"Input 2","State":0,"S0Counter":0} ]}</code>

= Extended MQTT flex JSON config examples =

== Default NETIO MQTT-flex configuration ==
This example demonstrates setup for connection to public <code>broker.hivemq.com</code>, measurement reporting and output control.

The device cabe be controlled via <code>netio/${DEVICE_NAME}/output/1/action topic</code> by sending standard NETIO action values:
* 0 - OFF
* 1 - ON
* 2 - SHORT OFF
* 3 - SHORT ON
* 4 - TOGGLE
* 5 - NO ACTION.

The device report measurements:

* Output state - every 15 minutes or by change
* Voltage [V]- every 5 minutes or by change of 1 V
* Current [mA]- every 5 minutes or by change of 50 mA
* Load(Power) [W]- every 5 minutes or by change of 10 W
* Energy(Consumption) [Wh]- every 15 minutes or by change of 1Wh
* True Power Factor (TPF) [-]- every 5 minutes or by change of 0.02
* Frequency [Hz]- every 1 hour or by change of 0.1 Hz

For register all values, you can use wildcard <code>netio/${DEVICE_NAME}/output/1/#</code>

{
"config":{
"broker":{
"url":"broker.hivemq.com",
"protocol":"mqtt",
"port":1883,
"ssl":false,
"type":"generic",
"username":"",
"password":"",
"clientid":"moje${DEVICE_NAME}${DEVICE_MAC}",
"keepalive":30
},
"subscribe":[
{
"topic":"netio/${DEVICE_NAME}/output/1/action",
"qos":0,
"target":"OUTPUTS/1/ACTION",
"action":"${payload}"
},
{
"topic":"netio/${DEVICE_NAME}/output/1/switch",
"qos":0,
"target":"OUTPUTS/1/ACTION",
"action":4
}
],
"publish":[
{
"topic":"netio/${DEVICE_MAC}/output/1/state",
"qos":0,
"retain":true,
"payload":"${OUTPUTS/1/STATE}",
"events":[
{
"type":"change",
"source":"OUTPUTS/1/STATE"
},
{
"type":"timer",
"period":900
}
]
},
{
"topic":"netio/${DEVICE_NAME}/output/1/voltage",
"qos":0,
"retain":false,
"payload":"${OUTPUTS/1/VOLTAGE}",
"events":[
{
"type":"timer",
"period":300
},
{
"type":"delta",
"source":"OUTPUTS/1/VOLTAGE",
"delta":1
}
]
},
{
"topic":"netio/${DEVICE_NAME}/output/1/current",
"qos":0,
"retain":false,
"payload":"${OUTPUTS/1/CURRENT}",
"events":[
{
"type":"timer",
"period":300
},
{
"type":"delta",
"source":"OUTPUTS/1/CURRENT",
"delta":50
}
]
},
{
"topic":"netio/${DEVICE_NAME}/output/1/load",
"qos":0,
"retain":false,
"payload":"${OUTPUTS/1/LOAD}",
"events":[
{
"type":"timer",
"period":300
},
{
"type":"delta",
"source":"OUTPUTS/1/LOAD",
"delta":10
}
]
},
{
"topic":"netio/${DEVICE_NAME}/output/1/energy",
"qos":0,
"retain":false,
"payload":"${OUTPUTS/1/ENERGY}",
"events":[
{
"type":"timer",
"period":900
},
{
"type":"delta",
"source":"OUTPUTS/1/ENERGY",
"delta":1
}
]
},
{
"topic":"netio/${DEVICE_NAME}/output/1/tpf",
"qos":0,
"retain":false,
"payload":"${OUTPUTS/1/POWER_FACTOR}",
"events":[
{
"type":"timer",
"period":900
},
{
"type":"delta",
"source":"OUTPUTS/1/POWER_FACTOR",
"delta":0.02
}
]
},
{
"topic":"netio/${DEVICE_NAME}/output/1/frequency",
"qos":0,
"retain":false,
"payload":"${OUTPUTS/1/FREQUENCY}",
"events":[
{
"type":"timer",
"period":3600
},
{
"type":"delta",
"source":"OUTPUTS/1/FREQUENCY",
"delta":0.1
}
]
}
]
}
}

MQTT-flex

2023-06-06T12:52:13Z

Bbakala: /* MQTT Event to rules */

The MQTT-flex version of the MQTT protocol can be configured in detail thanks to the “flex” extension.

https://www.netio-products.com/en/glossary/mqtt-flex

Why MQTT-flex 
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 [https://en.wikipedia.org/wiki/MQTT 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 [https://en.wikipedia.org/wiki/JSON 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 101x 
* PowerCable REST 101x 
* PowerPDU 4PS 
* PowerPDU 4KS 
* PowerPDU 8QS 
* PowerDIN 4PZ 
* PowerBOX 3Px 
* PowerBOX 4Kx 

FW version: 
>2.2.1

===Not supported NETIO devices:===
* PowerPDU 4C 
* NETIO 4 
* NETIO 4All 

= Simple MQTT-flex configuration + explanation =

''We strongly recommend to create and test MQTT-flex configuration on "local" device what can be easily restarted. The validation of config before saving is not 100% and for example some specific typos can cause a freeze of a device - the solution is to restart a device (unplug/plug input power cable). If the configuration is saved and device is working then there are no known failure case so it is safe to use this configuration on the "remote" devices.''

{
"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":false,
"payload":"${OUTPUTS/1/STATE}",
"events":[
{
"type":"timer",
"period":"1000"
}
]
}
]
}
}
=== Client Configuration (broker section) ===
Put here MQTT client connection setup

This configuration example set NETIO device to connect to broker.hivemq.com with mqtt protocol, no ssl connection with credetials freedom/peace|love|empathy4ALL.

"broker":{
"url":"broker.hivemq.com",
"protocol":"mqtt",
"port":1883,
"ssl":false,
"type":"generic",
"username":"freedom",
"password":"peace|LOVE|empathy4ALL"
},

=== Device Control (subscribe section) ===
Put here array of topics where to subscribe

Device output 1 is controlled with action received by subscription to netio/${DEVICE_NAME}/output/1/action topic with QOS 0

"subscribe":[{
"topic":"netio/${DEVICE_NAME}/output/1/action",
"qos":0,
"target":"OUTPUTS/1/ACTION",
"action":"${payload}"
}
],

=== Output State monitoring (publish section) ===
Put here array of topics where to publish.

Device send every 1000 s message to topic with QOS 0, retain true information with output 1 state

"publish":[{
"topic":"netio/${DEVICE_NAME}/output/1/state",
"qos":0,
"retain":true,
"payload":"${OUTPUTS/1/STATE}",
"events":[
{
"type":"timer",
"period":"1000"
}
]
}
]

= 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 ===
{| class="wikitable"
! style="font-weight:bold; background-color:#9b9b9b;" | Item
! style="font-weight:bold; background-color:#9b9b9b;" | Presence
! style="font-weight:bold; background-color:#9b9b9b;" | Possible Values
! style="font-weight:bold; background-color:#9b9b9b;" | Description
! style="font-weight:bold; background-color:#9b9b9b;" | JSON Config Usage
|-
| style="background-color:#efefef;" | url
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" |
| style="background-color:#efefef;" | MQTT broker URL
| style="background-color:#efefef;" | "url":"broker.hivemq.com"
|-
| style="background-color:#efefef;" | port
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | 1 - 65535
| style="background-color:#efefef;" | MQTT broker port
| style="background-color:#efefef;" | "port":1883
|-
| style="background-color:#efefef;" | protocol
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" |
| style="background-color:#efefef;" | protocol spec - mqtt
| style="background-color:#efefef;" | "protocol": "mqtt"
|-
| style="background-color:#efefef;" | ssl
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | true, false
| style="background-color:#efefef;" | Use SSL crypted communication selector
| style="background-color:#efefef;" | "ssl":false
|-
| style="background-color:#efefef;" | type
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | generic
| style="background-color:#efefef;" | Communication/setup type option
| style="background-color:#efefef;" | "type":"generic"
|-
| style="background-color:#efefef;" | username
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | regexp+len
| style="background-color:#efefef;" | Credentials for MQTT broker. Max. 128 characters (since FW 3.2.4).
| style="background-color:#efefef;" | "username":"freedom"
|-
| style="background-color:#efefef;" | password
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | regexp+len
| style="background-color:#efefef;" | Credentials for MQTT broker. Max. 256 characters (since FW 3.2.4).
| style="background-color:#efefef;" | "password":"peace|LOVE|empathy4ALL"
|-
| style="background-color:#efefef;" | clientid
| style="background-color:#efefef;" | optional
| style="background-color:#efefef;" | regexp+len
| style="background-color:#efefef;" | MQTT clientid. Max. 128 characters (since FW 3.2.4). Variables ${DEVICE_MAC} or ${DEVICE_NAME} can be used
| style="background-color:#efefef;" | "clientid":"myEcoTable01"
|-
| style="background-color:#efefef;" | keepalive
| style="background-color:#efefef;" | optional
| style="background-color:#efefef;" | 1 - 65535
| style="background-color:#efefef;" | MQTT keep alive period in seconds
| style="background-color:#efefef;" | "keepalive":90
|}

Note 1: clientid attribute is mandatory for MQTT(s) communication. When not configured, random ID will be generated.

Note 2: To proper communication with MS Azure - it is necessary to set up IoT Hub to use TLS 1.2

See section "TLS 1.2 enforcement available in select regions" in following guidelines https://docs.microsoft.com/en-us/azure/iot-hub/iot-hub-tls-support

=== Examples ===
==== Standard setup ====

==== Security (SSL / TLS) secured setup ====
You can enable MQTTs by using the encrypted port 8883 + "ssl":true.

==== Variables used setup ====

== 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 ===
{| class="wikitable"
! style="font-weight:bold; background-color:#9b9b9b;" | Item
! style="font-weight:bold; background-color:#9b9b9b;" | Presence
! style="font-weight:bold; background-color:#9b9b9b;" | Possible Values
! style="font-weight:bold; background-color:#9b9b9b;" | Description
! style="font-weight:bold; background-color:#9b9b9b;" | JSON Config Usage
|-
| style="background-color:#efefef;" | topic
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | see table below
| style="background-color:#efefef;" | specification of the topic, which MQTT-flex device listens from broker and act accordingly. Max. 128 characters. The "#" can be used since FW 3.2.4 - see note under this table.
| style="background-color:#efefef;" | "topic":"netio/${DEVICE_NAME}/output/1/action"
|-
| style="background-color:#efefef;" | qos
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | 0, 1 or 2
| style="background-color:#efefef;" | 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}
| style="background-color:#efefef;" | "qos":0
|-
| style="background-color:#efefef;" | target
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" |
| style="background-color:#efefef;" | internal definition of action, which can be performed above the specified output
| style="background-color:#efefef;" | "target":"OUTPUTS/1/ACTION"
|-
| style="background-color:#efefef;" | action
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" |
| style="background-color:#efefef;" | a payload or a value the action attribute needs to have passed to
| style="background-color:#efefef;" | "action":"${payload}"
|-
| style="background-color:#efefef;" | actiondefNot supported yet
| style="background-color:#efefef;" | optional
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
|-
| style="background-color:#efefef;" | jsonNot supported yet
| style="background-color:#efefef;" | optional
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
|}

Note: The "#" wildcard can be used in subscribe topic definition. The multi-level wildcard character MUST be specified either on its own or following a topic level separator. In either case it MUST be the last character specified in the Topic.

For example, if a Device subscribes to “devices/{device_id}/messages/devicebound/#”, it would receive messages published using these topic names:

“devices/{device_id}/messages/devicebound/”

“devices/{device_id}/messages/devicebound/{property_bag}”

This should be usefull for use with MS Azure - IoT hub.

=== MQTT Event to rules ===

This feature allow to subscribe to specific MQTT topic and pass payload to Rules or MQTT-flex as event.

target: <code>PROTOCOLS/MQTT/EVENT</code>

"subscribe": [
{
"action": "${payload}",
"qos": 0,
"target": "PROTOCOLS/MQTT/EVENT",
"topic": "broker/12345/MQTT_EVENT/"
}
]

=== Examples ===
==== Toggle output with standard payload ====
==== Toggle output with custom payload ====
==== Subscribe to more than one topic ====
==== Trigger Rule sequence from MQTT ====
==== Trigger MQTT publish by MQTT subscribe ====

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 ===
{| class="wikitable"
! style="font-weight:bold; background-color:#9b9b9b;" | Item
! style="font-weight:bold; background-color:#9b9b9b;" | Presence
! style="font-weight:bold; background-color:#9b9b9b;" | Possible Values
! style="font-weight:bold; background-color:#9b9b9b;" | Description
! style="font-weight:bold; background-color:#9b9b9b;" | JSON Config Usage
|-
| style="background-color:#efefef;" | topic
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | see table below
| style="background-color:#efefef;" | definition of the topic, how it is registered towards MQTT broker. Max. 128 characters.
| style="background-color:#efefef;" | "topic":"netio/${DEVICE_NAME}/output/1/load"
|-
| style="background-color:#efefef;" | qos
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | see table below
| style="background-color:#efefef;" | 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}
| style="background-color:#efefef;" |
|-
| style="background-color:#efefef;" | retain
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | boolean: true or false
| style="background-color:#efefef;" | 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}
| style="background-color:#efefef;" | "retain":true
|-
| style="background-color:#efefef;" | payload
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | see table below
| style="background-color:#efefef;" | definition of the payload, what is send to the MQTT broker.
| style="background-color:#efefef;" | "payload":"${OUTPUTS/1/STATE}"
|-
| style="background-color:#efefef;" | events
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | see table below
| style="background-color:#efefef;" | definition of events used for triggering sending of data via mqtt (change, delta, timer)
| style="background-color:#efefef;" |
|-
| style="background-color:#efefef;" | type
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
|-
| style="background-color:#efefef;" | source
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
|-
| style="background-color:#efefef;" | delta
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
|-
| style="background-color:#efefef;" | period
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
|-
| style="background-color:#efefef;" | payloaddefNot supported yet
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
|}

=== Examples ===
==== Publish energy periodically (event timer) ====
==== Publish current on change (delta) ====
==== Publish output state ====
==== Publish to more than one topic with different events ====

= 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 available only on NETIO PowerDIN 4PZ

=== Examples: ===

adressing controll of output 3
OUTPUTS/3/ACTION
getting voltage on output 1
OUTPUTS/1/VOLTAGE
getting state of input 1
INPUTS/1/STATE

= Events =
==== Timer ====

==== Delta ====

==== Change ====

==== Group Events<code>FW 4.0.0+</code>====

= 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 ===
==== VOLTAGE ====
Unit: <code>V</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Present RMS voltage on output 1 is ${OUTPUTS/1/VOLTAGE}"</code>

Example 2: <code>"source":"${OUTPUTS/1/VOLTAGE}"</code>

==== CURRENT ====
Unit: <code>mA</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Present RMS current on output 1 is ${OUTPUTS/1/CURRENT}"</code>

Example 2: <code>"source":"${OUTPUTS/1/CURRENT}"</code>

==== POWER_FACTOR ====
Unit: <code>[-]</code>

Type: float (2 decimals)

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"True Power Factor on output 1 is ${OUTPUTS/1/POWER_FACTOR}"</code>

Example 2: <code>"source":"${OUTPUTS/1/POWER_FACTOR}"</code>

==== LOAD ====
Unit: <code>W</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Present load on output 1 is ${OUTPUTS/1/LOAD}W"</code>

Example 2: <code>"payload":"Device's load connected to output 1 is ${OUTPUTS/1/LOAD}W"</code>

Example 3: <code>"source":"${OUTPUTS/1/LOAD}"</code>

==== STATE ====
Type: bool(integer) - <code>0</code> or <code>1</code>

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Present output 1 state is ${OUTPUTS/1/STATE}"</code>

Example 2: <code>"source":"${OUTPUTS/1/STATE}"</code>

==== ACTION ====
Type: integer

Possible actions:
* <code>0</code> - set state OFF
* <code>1</code> - set state ON
* <code>2</code> - short OFF (restart)
* <code>3</code> - short ON
* <code>4</code> - toggle (switch)
* <code>5</code> - no change

Allowed in: <code>"target"</code>

Example: <code>"target":"OUTPUTS/1/ACTION"</code>

==== DELAY [ms] ====
==== NAME ====
==== FREQUENCY ====
Unit: <code>Hz</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example: <code>"payload":"Frequency in power grid is ${OUTPUTS/1/ENERGY}Hz"</code>

==== ENERGY ====
Energy consumed by an device connected to NETIO device output.

Unit: <code>Wh</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Consumed energy on output 1 is ${OUTPUTS/1/ENERGY}Wh"</code>

Example 2: <code>"source":"${OUTPUTS/1/ENERGY}"</code>

==== REVERSE_ENERGY ====
Energy delivered back to grid. For example from solar system connected to NETIO device output.

Unit: <code>Wh</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Delivered energy on output 1 is ${OUTPUTS/1/REVERSE_ENERGY}Wh"</code>

Example 2: <code>"source":"${OUTPUTS/1/REVERSE_ENERGY}"</code>

==== ENERGY_START ====
Date when the counters ENERGY and REVERSE_ENERGY have been resetted by user.

Unit: <code>unix timestamp</code>

Type: integer

Allowed in: <code>"payload"</code>

Example 1: <code>"payload":"Energy measured since ${OUTPUTS/1/ENERGY_START} unix time"</code>

Example 2: <code>"payload":"${OUTPUTS/1/ENERGY_START}"</code> is output payload <code>1567654639</code>

==== ENERGY_START_FMT ====
Date when the counters ENERGY and REVERSE_ENERGY have been resetted by user.

Unit: <code>fmt date format</code>

Type: string

Allowed in: <code>"payload"</code>

Example 1: <code>"payload":"Energy measured since ${OUTPUTS/1/ENERGY_START}"</code>

Example 2: <code>"payload":"${OUTPUTS/1/ENERGY_START_FMT}"</code> is output payload <code>2019-09-05T03:37:19+00:00</code>

==== ENERGY_NR ====
Non-resettable counter of Energy consumed by an device connected to NETIO device output.

Unit: <code>Wh</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Consumed energy on output 1 is ${OUTPUTS/1/ENERGY_NR}Wh"</code>

Example 2: <code>"source":"${OUTPUTS/1/ENERGY_NR}"</code>

==== REVERSE_ENERGY_NR ====
Non-resettable counter of Energy delivered back to grid. For example from solar system connected to NETIO device output.

Unit: <code>Wh</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Delivered energy on output 1 is ${OUTPUTS/1/REVERSE_ENERGY_NR}Wh"</code>

Example 2: <code>"source":"${OUTPUTS/1/REVERSE_ENERGY_NR}"</code>

==== TOTALs - for 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
* OUTPUTS/TOTAL/PHASE
* OUTPUTS/TOTAL/REVERSE_ENERGY
* OUTPUTS/TOTAL/ENERGY_NR
* OUTPUTS/TOTAL/REVERSE_ENERGY_NR
* OUTPUTS/TOTAL/ENERGY_START
* OUTPUTS/TOTAL/ENERGY_START_FMT

==== REST_JSON ====
Allow use of NETIO JSON structure to control outputs.

Type: string / JSON

Allowed in: <code>"target"</code> for Subscribe section

Example: <code>"target": "REST_JSON"</code>

The payload is JSON structure identical to NETIO JSON API M2M Protocol (documentation available at https://www.netio-products.com/files/NETIO-M2M-API-Protocol-JSON.pdf). You can control one or multiple outputs.

Payload example 1 - Toggle output 1: <code>{"Outputs":[{"ID": 1,"Action": 4}]}</code>

Payload example 2 - Turn output 1 OFF and output 3 ON: <code>{"Outputs":[{"ID":1,"Action":0},{"ID":3,"Action":1}]}</code>

=== INPUT variables ===
==== STATE ====
Type: bool(integer) - <code>0</code> or <code>1</code>

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Present input 1 state is ${INPUTS/1/STATE}"</code>

Example 2: <code>"source":"${INPUTS/1/STATE}"</code>

==== S0 ====
S0 Counter value
Unit: <code>-</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Input 1 S0 Counter value is ${INPUTS/1/S0}impulses"</code>

Example 2: <code>"source":"${INPUTS/1/S0}"</code>

== Payload/topic variables ==

=== DEVICE_NAME ===
Can be used in: "payload", "topic"

Example 1: <code>"payload":"${DEVICE_NAME}"</code>

Example 2: <code>"topic":"netio/${DEVICE_NAME}/output/1/action"</code>

=== DEVICE_MAC ===

=== UPTIME Not yet implemented ===

=== PAYLOAD ===
Can be used in: "action"

Example: <code>"action":"${PAYLOAD}"</code>

=== OUTPUT_ID Not yet implemented===

=== WIFI_SIGNALNot yet implemented ===

=== OUTPUTS_STATUS ===
Provide complete outputs status and measurement if supported.

Type: string / JSON

Allowed in: <code>"payload"</code> for Publish section

Example: <code>"payload":"${OUTPUTS_STATUS}"</code>

Payload example: <code>{ "GlobalMeasure":{"Voltage":236,"TotalCurrent":72,"TotalLoad":11,"TotalEnergy":167,"OverallPowerFactor":0.64,"Frequency":50.07,"Phase":-36.86,"EnergyStart":"2020-06-30T17:04:48+01:00"}, "Outputs":[ {"ID":1,"Name":"Power output 1","State":1,"Action":6,"Delay":2020,"Current":72,"PowerFactor":0.64,"Phase":-36.86,"Energy":139,"ReverseEnergy":0,"Load":11}, {"ID":2,"Name":"Power output 2","State":1,"Action":6,"Delay":2020,"Current":0,"PowerFactor":1.00,"Phase":0.00,"Energy":27,"ReverseEnergy":0,"Load":0}, {"ID":3,"Name":"Free Contact 3","State":1,"Action":6,"Delay":2020}, {"ID":4,"Name":"Free Contact 4","State":1,"Action":6,"Delay":2020} ]}</code>

=== INPUTS_STATUS ===
Provide complete inputs status if supported. Since FW 3.0.0

Type: string / JSON

Allowed in: <code>"payload"</code> for Publish section

Example: <code>"payload":"${INPUTS_STATUS}"</code>

Payload example: <code>{ "Inputs":[ {"ID":1,"Name":"Input 1","State":0,"S0Counter":0}, {"ID":2,"Name":"Input 2","State":0,"S0Counter":0} ]}</code>

=== INOUT_STATUS ===
Provide complete inputs and output status and measurement if supported. Since FW 3.0.0

Type: string / JSON

Allowed in: <code>"payload"</code> for Publish section

Example: <code>"payload":"${INOUT_STATUS}"</code>

Payload example: <code>{ "GlobalMeasure":{"Voltage":238,"TotalCurrent":105,"TotalLoad":17,"TotalEnergy":1451,"OverallPowerFactor":0.67,"Frequency":50.03,"Phase":-33.67,"EnergyStart":"2020-06-30T17:04:48+01:00"}, "Outputs":[ {"ID":1,"Name":"Power output 1","State":0,"Action":6,"Delay":5000,"Current":0,"PowerFactor":1.00,"Phase":0.00,"Energy":701,"ReverseEnergy":0,"Load":0}, {"ID":2,"Name":"Power output 2","State":1,"Action":6,"Delay":5000,"Current":105,"PowerFactor":0.65,"Phase":-33.67,"Energy":750,"ReverseEnergy":0,"Load":17}, {"ID":3,"Name":"Free Contact 3","State":1,"Action":6,"Delay":5000}, {"ID":4,"Name":"Free Contact 4","State":0,"Action":6,"Delay":5000} ], "Inputs":[ {"ID":1,"Name":"Input 1","State":0,"S0Counter":0}, {"ID":2,"Name":"Input 2","State":0,"S0Counter":0} ]}</code>

= Extended MQTT flex JSON config examples =

== Default NETIO MQTT-flex configuration ==
This example demonstrates setup for connection to public <code>broker.hivemq.com</code>, measurement reporting and output control.

The device cabe be controlled via <code>netio/${DEVICE_NAME}/output/1/action topic</code> by sending standard NETIO action values:
* 0 - OFF
* 1 - ON
* 2 - SHORT OFF
* 3 - SHORT ON
* 4 - TOGGLE
* 5 - NO ACTION.

The device report measurements:

* Output state - every 15 minutes or by change
* Voltage [V]- every 5 minutes or by change of 1 V
* Current [mA]- every 5 minutes or by change of 50 mA
* Load(Power) [W]- every 5 minutes or by change of 10 W
* Energy(Consumption) [Wh]- every 15 minutes or by change of 1Wh
* True Power Factor (TPF) [-]- every 5 minutes or by change of 0.02
* Frequency [Hz]- every 1 hour or by change of 0.1 Hz

For register all values, you can use wildcard <code>netio/${DEVICE_NAME}/output/1/#</code>

{
"config":{
"broker":{
"url":"broker.hivemq.com",
"protocol":"mqtt",
"port":1883,
"ssl":false,
"type":"generic",
"username":"",
"password":"",
"clientid":"moje${DEVICE_NAME}${DEVICE_MAC}",
"keepalive":30
},
"subscribe":[
{
"topic":"netio/${DEVICE_NAME}/output/1/action",
"qos":0,
"target":"OUTPUTS/1/ACTION",
"action":"${payload}"
},
{
"topic":"netio/${DEVICE_NAME}/output/1/switch",
"qos":0,
"target":"OUTPUTS/1/ACTION",
"action":4
}
],
"publish":[
{
"topic":"netio/${DEVICE_MAC}/output/1/state",
"qos":0,
"retain":true,
"payload":"${OUTPUTS/1/STATE}",
"events":[
{
"type":"change",
"source":"OUTPUTS/1/STATE"
},
{
"type":"timer",
"period":900
}
]
},
{
"topic":"netio/${DEVICE_NAME}/output/1/voltage",
"qos":0,
"retain":false,
"payload":"${OUTPUTS/1/VOLTAGE}",
"events":[
{
"type":"timer",
"period":300
},
{
"type":"delta",
"source":"OUTPUTS/1/VOLTAGE",
"delta":1
}
]
},
{
"topic":"netio/${DEVICE_NAME}/output/1/current",
"qos":0,
"retain":false,
"payload":"${OUTPUTS/1/CURRENT}",
"events":[
{
"type":"timer",
"period":300
},
{
"type":"delta",
"source":"OUTPUTS/1/CURRENT",
"delta":50
}
]
},
{
"topic":"netio/${DEVICE_NAME}/output/1/load",
"qos":0,
"retain":false,
"payload":"${OUTPUTS/1/LOAD}",
"events":[
{
"type":"timer",
"period":300
},
{
"type":"delta",
"source":"OUTPUTS/1/LOAD",
"delta":10
}
]
},
{
"topic":"netio/${DEVICE_NAME}/output/1/energy",
"qos":0,
"retain":false,
"payload":"${OUTPUTS/1/ENERGY}",
"events":[
{
"type":"timer",
"period":900
},
{
"type":"delta",
"source":"OUTPUTS/1/ENERGY",
"delta":1
}
]
},
{
"topic":"netio/${DEVICE_NAME}/output/1/tpf",
"qos":0,
"retain":false,
"payload":"${OUTPUTS/1/POWER_FACTOR}",
"events":[
{
"type":"timer",
"period":900
},
{
"type":"delta",
"source":"OUTPUTS/1/POWER_FACTOR",
"delta":0.02
}
]
},
{
"topic":"netio/${DEVICE_NAME}/output/1/frequency",
"qos":0,
"retain":false,
"payload":"${OUTPUTS/1/FREQUENCY}",
"events":[
{
"type":"timer",
"period":3600
},
{
"type":"delta",
"source":"OUTPUTS/1/FREQUENCY",
"delta":0.1
}
]
}
]
}
}

MQTT-flex

2023-06-06T12:51:24Z

Bbakala: /* MQTT Event to rules */

The MQTT-flex version of the MQTT protocol can be configured in detail thanks to the “flex” extension.

https://www.netio-products.com/en/glossary/mqtt-flex

Why MQTT-flex 
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 [https://en.wikipedia.org/wiki/MQTT 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 [https://en.wikipedia.org/wiki/JSON 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 101x 
* PowerCable REST 101x 
* PowerPDU 4PS 
* PowerPDU 4KS 
* PowerPDU 8QS 
* PowerDIN 4PZ 
* PowerBOX 3Px 
* PowerBOX 4Kx 

FW version: 
>2.2.1

===Not supported NETIO devices:===
* PowerPDU 4C 
* NETIO 4 
* NETIO 4All 

= Simple MQTT-flex configuration + explanation =

''We strongly recommend to create and test MQTT-flex configuration on "local" device what can be easily restarted. The validation of config before saving is not 100% and for example some specific typos can cause a freeze of a device - the solution is to restart a device (unplug/plug input power cable). If the configuration is saved and device is working then there are no known failure case so it is safe to use this configuration on the "remote" devices.''

{
"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":false,
"payload":"${OUTPUTS/1/STATE}",
"events":[
{
"type":"timer",
"period":"1000"
}
]
}
]
}
}
=== Client Configuration (broker section) ===
Put here MQTT client connection setup

This configuration example set NETIO device to connect to broker.hivemq.com with mqtt protocol, no ssl connection with credetials freedom/peace|love|empathy4ALL.

"broker":{
"url":"broker.hivemq.com",
"protocol":"mqtt",
"port":1883,
"ssl":false,
"type":"generic",
"username":"freedom",
"password":"peace|LOVE|empathy4ALL"
},

=== Device Control (subscribe section) ===
Put here array of topics where to subscribe

Device output 1 is controlled with action received by subscription to netio/${DEVICE_NAME}/output/1/action topic with QOS 0

"subscribe":[{
"topic":"netio/${DEVICE_NAME}/output/1/action",
"qos":0,
"target":"OUTPUTS/1/ACTION",
"action":"${payload}"
}
],

=== Output State monitoring (publish section) ===
Put here array of topics where to publish.

Device send every 1000 s message to topic with QOS 0, retain true information with output 1 state

"publish":[{
"topic":"netio/${DEVICE_NAME}/output/1/state",
"qos":0,
"retain":true,
"payload":"${OUTPUTS/1/STATE}",
"events":[
{
"type":"timer",
"period":"1000"
}
]
}
]

= 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 ===
{| class="wikitable"
! style="font-weight:bold; background-color:#9b9b9b;" | Item
! style="font-weight:bold; background-color:#9b9b9b;" | Presence
! style="font-weight:bold; background-color:#9b9b9b;" | Possible Values
! style="font-weight:bold; background-color:#9b9b9b;" | Description
! style="font-weight:bold; background-color:#9b9b9b;" | JSON Config Usage
|-
| style="background-color:#efefef;" | url
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" |
| style="background-color:#efefef;" | MQTT broker URL
| style="background-color:#efefef;" | "url":"broker.hivemq.com"
|-
| style="background-color:#efefef;" | port
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | 1 - 65535
| style="background-color:#efefef;" | MQTT broker port
| style="background-color:#efefef;" | "port":1883
|-
| style="background-color:#efefef;" | protocol
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" |
| style="background-color:#efefef;" | protocol spec - mqtt
| style="background-color:#efefef;" | "protocol": "mqtt"
|-
| style="background-color:#efefef;" | ssl
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | true, false
| style="background-color:#efefef;" | Use SSL crypted communication selector
| style="background-color:#efefef;" | "ssl":false
|-
| style="background-color:#efefef;" | type
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | generic
| style="background-color:#efefef;" | Communication/setup type option
| style="background-color:#efefef;" | "type":"generic"
|-
| style="background-color:#efefef;" | username
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | regexp+len
| style="background-color:#efefef;" | Credentials for MQTT broker. Max. 128 characters (since FW 3.2.4).
| style="background-color:#efefef;" | "username":"freedom"
|-
| style="background-color:#efefef;" | password
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | regexp+len
| style="background-color:#efefef;" | Credentials for MQTT broker. Max. 256 characters (since FW 3.2.4).
| style="background-color:#efefef;" | "password":"peace|LOVE|empathy4ALL"
|-
| style="background-color:#efefef;" | clientid
| style="background-color:#efefef;" | optional
| style="background-color:#efefef;" | regexp+len
| style="background-color:#efefef;" | MQTT clientid. Max. 128 characters (since FW 3.2.4). Variables ${DEVICE_MAC} or ${DEVICE_NAME} can be used
| style="background-color:#efefef;" | "clientid":"myEcoTable01"
|-
| style="background-color:#efefef;" | keepalive
| style="background-color:#efefef;" | optional
| style="background-color:#efefef;" | 1 - 65535
| style="background-color:#efefef;" | MQTT keep alive period in seconds
| style="background-color:#efefef;" | "keepalive":90
|}

Note 1: clientid attribute is mandatory for MQTT(s) communication. When not configured, random ID will be generated.

Note 2: To proper communication with MS Azure - it is necessary to set up IoT Hub to use TLS 1.2

See section "TLS 1.2 enforcement available in select regions" in following guidelines https://docs.microsoft.com/en-us/azure/iot-hub/iot-hub-tls-support

=== Examples ===
==== Standard setup ====

==== Security (SSL / TLS) secured setup ====
You can enable MQTTs by using the encrypted port 8883 + "ssl":true.

==== Variables used setup ====

== 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 ===
{| class="wikitable"
! style="font-weight:bold; background-color:#9b9b9b;" | Item
! style="font-weight:bold; background-color:#9b9b9b;" | Presence
! style="font-weight:bold; background-color:#9b9b9b;" | Possible Values
! style="font-weight:bold; background-color:#9b9b9b;" | Description
! style="font-weight:bold; background-color:#9b9b9b;" | JSON Config Usage
|-
| style="background-color:#efefef;" | topic
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | see table below
| style="background-color:#efefef;" | specification of the topic, which MQTT-flex device listens from broker and act accordingly. Max. 128 characters. The "#" can be used since FW 3.2.4 - see note under this table.
| style="background-color:#efefef;" | "topic":"netio/${DEVICE_NAME}/output/1/action"
|-
| style="background-color:#efefef;" | qos
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | 0, 1 or 2
| style="background-color:#efefef;" | 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}
| style="background-color:#efefef;" | "qos":0
|-
| style="background-color:#efefef;" | target
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" |
| style="background-color:#efefef;" | internal definition of action, which can be performed above the specified output
| style="background-color:#efefef;" | "target":"OUTPUTS/1/ACTION"
|-
| style="background-color:#efefef;" | action
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" |
| style="background-color:#efefef;" | a payload or a value the action attribute needs to have passed to
| style="background-color:#efefef;" | "action":"${payload}"
|-
| style="background-color:#efefef;" | actiondefNot supported yet
| style="background-color:#efefef;" | optional
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
|-
| style="background-color:#efefef;" | jsonNot supported yet
| style="background-color:#efefef;" | optional
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
|}

Note: The "#" wildcard can be used in subscribe topic definition. The multi-level wildcard character MUST be specified either on its own or following a topic level separator. In either case it MUST be the last character specified in the Topic.

For example, if a Device subscribes to “devices/{device_id}/messages/devicebound/#”, it would receive messages published using these topic names:

“devices/{device_id}/messages/devicebound/”

“devices/{device_id}/messages/devicebound/{property_bag}”

This should be usefull for use with MS Azure - IoT hub.

=== MQTT Event to rules ===

This feature allow to subscribe to specific MQTT topic and pass payload to Rules or MQTT-flex as event.

target: <code>PROTOCOLS/MQTT/EVENT</code>

usage:<code>
"subscribe": [
{
"action": "${payload}",
"qos": 0,
"target": "PROTOCOLS/MQTT/EVENT",
"topic": "broker/12345/MQTT_EVENT/"
}
]
</code>

=== Examples ===
==== Toggle output with standard payload ====
==== Toggle output with custom payload ====
==== Subscribe to more than one topic ====
==== Trigger Rule sequence from MQTT ====
==== Trigger MQTT publish by MQTT subscribe ====

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 ===
{| class="wikitable"
! style="font-weight:bold; background-color:#9b9b9b;" | Item
! style="font-weight:bold; background-color:#9b9b9b;" | Presence
! style="font-weight:bold; background-color:#9b9b9b;" | Possible Values
! style="font-weight:bold; background-color:#9b9b9b;" | Description
! style="font-weight:bold; background-color:#9b9b9b;" | JSON Config Usage
|-
| style="background-color:#efefef;" | topic
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | see table below
| style="background-color:#efefef;" | definition of the topic, how it is registered towards MQTT broker. Max. 128 characters.
| style="background-color:#efefef;" | "topic":"netio/${DEVICE_NAME}/output/1/load"
|-
| style="background-color:#efefef;" | qos
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | see table below
| style="background-color:#efefef;" | 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}
| style="background-color:#efefef;" |
|-
| style="background-color:#efefef;" | retain
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | boolean: true or false
| style="background-color:#efefef;" | 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}
| style="background-color:#efefef;" | "retain":true
|-
| style="background-color:#efefef;" | payload
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | see table below
| style="background-color:#efefef;" | definition of the payload, what is send to the MQTT broker.
| style="background-color:#efefef;" | "payload":"${OUTPUTS/1/STATE}"
|-
| style="background-color:#efefef;" | events
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | see table below
| style="background-color:#efefef;" | definition of events used for triggering sending of data via mqtt (change, delta, timer)
| style="background-color:#efefef;" |
|-
| style="background-color:#efefef;" | type
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
|-
| style="background-color:#efefef;" | source
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
|-
| style="background-color:#efefef;" | delta
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
|-
| style="background-color:#efefef;" | period
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
|-
| style="background-color:#efefef;" | payloaddefNot supported yet
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
|}

=== Examples ===
==== Publish energy periodically (event timer) ====
==== Publish current on change (delta) ====
==== Publish output state ====
==== Publish to more than one topic with different events ====

= 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 available only on NETIO PowerDIN 4PZ

=== Examples: ===

adressing controll of output 3
OUTPUTS/3/ACTION
getting voltage on output 1
OUTPUTS/1/VOLTAGE
getting state of input 1
INPUTS/1/STATE

= Events =
==== Timer ====

==== Delta ====

==== Change ====

==== Group Events<code>FW 4.0.0+</code>====

= 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 ===
==== VOLTAGE ====
Unit: <code>V</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Present RMS voltage on output 1 is ${OUTPUTS/1/VOLTAGE}"</code>

Example 2: <code>"source":"${OUTPUTS/1/VOLTAGE}"</code>

==== CURRENT ====
Unit: <code>mA</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Present RMS current on output 1 is ${OUTPUTS/1/CURRENT}"</code>

Example 2: <code>"source":"${OUTPUTS/1/CURRENT}"</code>

==== POWER_FACTOR ====
Unit: <code>[-]</code>

Type: float (2 decimals)

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"True Power Factor on output 1 is ${OUTPUTS/1/POWER_FACTOR}"</code>

Example 2: <code>"source":"${OUTPUTS/1/POWER_FACTOR}"</code>

==== LOAD ====
Unit: <code>W</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Present load on output 1 is ${OUTPUTS/1/LOAD}W"</code>

Example 2: <code>"payload":"Device's load connected to output 1 is ${OUTPUTS/1/LOAD}W"</code>

Example 3: <code>"source":"${OUTPUTS/1/LOAD}"</code>

==== STATE ====
Type: bool(integer) - <code>0</code> or <code>1</code>

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Present output 1 state is ${OUTPUTS/1/STATE}"</code>

Example 2: <code>"source":"${OUTPUTS/1/STATE}"</code>

==== ACTION ====
Type: integer

Possible actions:
* <code>0</code> - set state OFF
* <code>1</code> - set state ON
* <code>2</code> - short OFF (restart)
* <code>3</code> - short ON
* <code>4</code> - toggle (switch)
* <code>5</code> - no change

Allowed in: <code>"target"</code>

Example: <code>"target":"OUTPUTS/1/ACTION"</code>

==== DELAY [ms] ====
==== NAME ====
==== FREQUENCY ====
Unit: <code>Hz</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example: <code>"payload":"Frequency in power grid is ${OUTPUTS/1/ENERGY}Hz"</code>

==== ENERGY ====
Energy consumed by an device connected to NETIO device output.

Unit: <code>Wh</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Consumed energy on output 1 is ${OUTPUTS/1/ENERGY}Wh"</code>

Example 2: <code>"source":"${OUTPUTS/1/ENERGY}"</code>

==== REVERSE_ENERGY ====
Energy delivered back to grid. For example from solar system connected to NETIO device output.

Unit: <code>Wh</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Delivered energy on output 1 is ${OUTPUTS/1/REVERSE_ENERGY}Wh"</code>

Example 2: <code>"source":"${OUTPUTS/1/REVERSE_ENERGY}"</code>

==== ENERGY_START ====
Date when the counters ENERGY and REVERSE_ENERGY have been resetted by user.

Unit: <code>unix timestamp</code>

Type: integer

Allowed in: <code>"payload"</code>

Example 1: <code>"payload":"Energy measured since ${OUTPUTS/1/ENERGY_START} unix time"</code>

Example 2: <code>"payload":"${OUTPUTS/1/ENERGY_START}"</code> is output payload <code>1567654639</code>

==== ENERGY_START_FMT ====
Date when the counters ENERGY and REVERSE_ENERGY have been resetted by user.

Unit: <code>fmt date format</code>

Type: string

Allowed in: <code>"payload"</code>

Example 1: <code>"payload":"Energy measured since ${OUTPUTS/1/ENERGY_START}"</code>

Example 2: <code>"payload":"${OUTPUTS/1/ENERGY_START_FMT}"</code> is output payload <code>2019-09-05T03:37:19+00:00</code>

==== ENERGY_NR ====
Non-resettable counter of Energy consumed by an device connected to NETIO device output.

Unit: <code>Wh</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Consumed energy on output 1 is ${OUTPUTS/1/ENERGY_NR}Wh"</code>

Example 2: <code>"source":"${OUTPUTS/1/ENERGY_NR}"</code>

==== REVERSE_ENERGY_NR ====
Non-resettable counter of Energy delivered back to grid. For example from solar system connected to NETIO device output.

Unit: <code>Wh</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Delivered energy on output 1 is ${OUTPUTS/1/REVERSE_ENERGY_NR}Wh"</code>

Example 2: <code>"source":"${OUTPUTS/1/REVERSE_ENERGY_NR}"</code>

==== TOTALs - for 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
* OUTPUTS/TOTAL/PHASE
* OUTPUTS/TOTAL/REVERSE_ENERGY
* OUTPUTS/TOTAL/ENERGY_NR
* OUTPUTS/TOTAL/REVERSE_ENERGY_NR
* OUTPUTS/TOTAL/ENERGY_START
* OUTPUTS/TOTAL/ENERGY_START_FMT

==== REST_JSON ====
Allow use of NETIO JSON structure to control outputs.

Type: string / JSON

Allowed in: <code>"target"</code> for Subscribe section

Example: <code>"target": "REST_JSON"</code>

The payload is JSON structure identical to NETIO JSON API M2M Protocol (documentation available at https://www.netio-products.com/files/NETIO-M2M-API-Protocol-JSON.pdf). You can control one or multiple outputs.

Payload example 1 - Toggle output 1: <code>{"Outputs":[{"ID": 1,"Action": 4}]}</code>

Payload example 2 - Turn output 1 OFF and output 3 ON: <code>{"Outputs":[{"ID":1,"Action":0},{"ID":3,"Action":1}]}</code>

=== INPUT variables ===
==== STATE ====
Type: bool(integer) - <code>0</code> or <code>1</code>

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Present input 1 state is ${INPUTS/1/STATE}"</code>

Example 2: <code>"source":"${INPUTS/1/STATE}"</code>

==== S0 ====
S0 Counter value
Unit: <code>-</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Input 1 S0 Counter value is ${INPUTS/1/S0}impulses"</code>

Example 2: <code>"source":"${INPUTS/1/S0}"</code>

== Payload/topic variables ==

=== DEVICE_NAME ===
Can be used in: "payload", "topic"

Example 1: <code>"payload":"${DEVICE_NAME}"</code>

Example 2: <code>"topic":"netio/${DEVICE_NAME}/output/1/action"</code>

=== DEVICE_MAC ===

=== UPTIME Not yet implemented ===

=== PAYLOAD ===
Can be used in: "action"

Example: <code>"action":"${PAYLOAD}"</code>

=== OUTPUT_ID Not yet implemented===

=== WIFI_SIGNALNot yet implemented ===

=== OUTPUTS_STATUS ===
Provide complete outputs status and measurement if supported.

Type: string / JSON

Allowed in: <code>"payload"</code> for Publish section

Example: <code>"payload":"${OUTPUTS_STATUS}"</code>

Payload example: <code>{ "GlobalMeasure":{"Voltage":236,"TotalCurrent":72,"TotalLoad":11,"TotalEnergy":167,"OverallPowerFactor":0.64,"Frequency":50.07,"Phase":-36.86,"EnergyStart":"2020-06-30T17:04:48+01:00"}, "Outputs":[ {"ID":1,"Name":"Power output 1","State":1,"Action":6,"Delay":2020,"Current":72,"PowerFactor":0.64,"Phase":-36.86,"Energy":139,"ReverseEnergy":0,"Load":11}, {"ID":2,"Name":"Power output 2","State":1,"Action":6,"Delay":2020,"Current":0,"PowerFactor":1.00,"Phase":0.00,"Energy":27,"ReverseEnergy":0,"Load":0}, {"ID":3,"Name":"Free Contact 3","State":1,"Action":6,"Delay":2020}, {"ID":4,"Name":"Free Contact 4","State":1,"Action":6,"Delay":2020} ]}</code>

=== INPUTS_STATUS ===
Provide complete inputs status if supported. Since FW 3.0.0

Type: string / JSON

Allowed in: <code>"payload"</code> for Publish section

Example: <code>"payload":"${INPUTS_STATUS}"</code>

Payload example: <code>{ "Inputs":[ {"ID":1,"Name":"Input 1","State":0,"S0Counter":0}, {"ID":2,"Name":"Input 2","State":0,"S0Counter":0} ]}</code>

=== INOUT_STATUS ===
Provide complete inputs and output status and measurement if supported. Since FW 3.0.0

Type: string / JSON

Allowed in: <code>"payload"</code> for Publish section

Example: <code>"payload":"${INOUT_STATUS}"</code>

Payload example: <code>{ "GlobalMeasure":{"Voltage":238,"TotalCurrent":105,"TotalLoad":17,"TotalEnergy":1451,"OverallPowerFactor":0.67,"Frequency":50.03,"Phase":-33.67,"EnergyStart":"2020-06-30T17:04:48+01:00"}, "Outputs":[ {"ID":1,"Name":"Power output 1","State":0,"Action":6,"Delay":5000,"Current":0,"PowerFactor":1.00,"Phase":0.00,"Energy":701,"ReverseEnergy":0,"Load":0}, {"ID":2,"Name":"Power output 2","State":1,"Action":6,"Delay":5000,"Current":105,"PowerFactor":0.65,"Phase":-33.67,"Energy":750,"ReverseEnergy":0,"Load":17}, {"ID":3,"Name":"Free Contact 3","State":1,"Action":6,"Delay":5000}, {"ID":4,"Name":"Free Contact 4","State":0,"Action":6,"Delay":5000} ], "Inputs":[ {"ID":1,"Name":"Input 1","State":0,"S0Counter":0}, {"ID":2,"Name":"Input 2","State":0,"S0Counter":0} ]}</code>

= Extended MQTT flex JSON config examples =

== Default NETIO MQTT-flex configuration ==
This example demonstrates setup for connection to public <code>broker.hivemq.com</code>, measurement reporting and output control.

The device cabe be controlled via <code>netio/${DEVICE_NAME}/output/1/action topic</code> by sending standard NETIO action values:
* 0 - OFF
* 1 - ON
* 2 - SHORT OFF
* 3 - SHORT ON
* 4 - TOGGLE
* 5 - NO ACTION.

The device report measurements:

* Output state - every 15 minutes or by change
* Voltage [V]- every 5 minutes or by change of 1 V
* Current [mA]- every 5 minutes or by change of 50 mA
* Load(Power) [W]- every 5 minutes or by change of 10 W
* Energy(Consumption) [Wh]- every 15 minutes or by change of 1Wh
* True Power Factor (TPF) [-]- every 5 minutes or by change of 0.02
* Frequency [Hz]- every 1 hour or by change of 0.1 Hz

For register all values, you can use wildcard <code>netio/${DEVICE_NAME}/output/1/#</code>

{
"config":{
"broker":{
"url":"broker.hivemq.com",
"protocol":"mqtt",
"port":1883,
"ssl":false,
"type":"generic",
"username":"",
"password":"",
"clientid":"moje${DEVICE_NAME}${DEVICE_MAC}",
"keepalive":30
},
"subscribe":[
{
"topic":"netio/${DEVICE_NAME}/output/1/action",
"qos":0,
"target":"OUTPUTS/1/ACTION",
"action":"${payload}"
},
{
"topic":"netio/${DEVICE_NAME}/output/1/switch",
"qos":0,
"target":"OUTPUTS/1/ACTION",
"action":4
}
],
"publish":[
{
"topic":"netio/${DEVICE_MAC}/output/1/state",
"qos":0,
"retain":true,
"payload":"${OUTPUTS/1/STATE}",
"events":[
{
"type":"change",
"source":"OUTPUTS/1/STATE"
},
{
"type":"timer",
"period":900
}
]
},
{
"topic":"netio/${DEVICE_NAME}/output/1/voltage",
"qos":0,
"retain":false,
"payload":"${OUTPUTS/1/VOLTAGE}",
"events":[
{
"type":"timer",
"period":300
},
{
"type":"delta",
"source":"OUTPUTS/1/VOLTAGE",
"delta":1
}
]
},
{
"topic":"netio/${DEVICE_NAME}/output/1/current",
"qos":0,
"retain":false,
"payload":"${OUTPUTS/1/CURRENT}",
"events":[
{
"type":"timer",
"period":300
},
{
"type":"delta",
"source":"OUTPUTS/1/CURRENT",
"delta":50
}
]
},
{
"topic":"netio/${DEVICE_NAME}/output/1/load",
"qos":0,
"retain":false,
"payload":"${OUTPUTS/1/LOAD}",
"events":[
{
"type":"timer",
"period":300
},
{
"type":"delta",
"source":"OUTPUTS/1/LOAD",
"delta":10
}
]
},
{
"topic":"netio/${DEVICE_NAME}/output/1/energy",
"qos":0,
"retain":false,
"payload":"${OUTPUTS/1/ENERGY}",
"events":[
{
"type":"timer",
"period":900
},
{
"type":"delta",
"source":"OUTPUTS/1/ENERGY",
"delta":1
}
]
},
{
"topic":"netio/${DEVICE_NAME}/output/1/tpf",
"qos":0,
"retain":false,
"payload":"${OUTPUTS/1/POWER_FACTOR}",
"events":[
{
"type":"timer",
"period":900
},
{
"type":"delta",
"source":"OUTPUTS/1/POWER_FACTOR",
"delta":0.02
}
]
},
{
"topic":"netio/${DEVICE_NAME}/output/1/frequency",
"qos":0,
"retain":false,
"payload":"${OUTPUTS/1/FREQUENCY}",
"events":[
{
"type":"timer",
"period":3600
},
{
"type":"delta",
"source":"OUTPUTS/1/FREQUENCY",
"delta":0.1
}
]
}
]
}
}

MQTT-flex

2023-06-06T12:50:46Z

Bbakala: /* MQTT Event to rules */

The MQTT-flex version of the MQTT protocol can be configured in detail thanks to the “flex” extension.

https://www.netio-products.com/en/glossary/mqtt-flex

Why MQTT-flex 
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 [https://en.wikipedia.org/wiki/MQTT 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 [https://en.wikipedia.org/wiki/JSON 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 101x 
* PowerCable REST 101x 
* PowerPDU 4PS 
* PowerPDU 4KS 
* PowerPDU 8QS 
* PowerDIN 4PZ 
* PowerBOX 3Px 
* PowerBOX 4Kx 

FW version: 
>2.2.1

===Not supported NETIO devices:===
* PowerPDU 4C 
* NETIO 4 
* NETIO 4All 

= Simple MQTT-flex configuration + explanation =

''We strongly recommend to create and test MQTT-flex configuration on "local" device what can be easily restarted. The validation of config before saving is not 100% and for example some specific typos can cause a freeze of a device - the solution is to restart a device (unplug/plug input power cable). If the configuration is saved and device is working then there are no known failure case so it is safe to use this configuration on the "remote" devices.''

{
"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":false,
"payload":"${OUTPUTS/1/STATE}",
"events":[
{
"type":"timer",
"period":"1000"
}
]
}
]
}
}
=== Client Configuration (broker section) ===
Put here MQTT client connection setup

This configuration example set NETIO device to connect to broker.hivemq.com with mqtt protocol, no ssl connection with credetials freedom/peace|love|empathy4ALL.

"broker":{
"url":"broker.hivemq.com",
"protocol":"mqtt",
"port":1883,
"ssl":false,
"type":"generic",
"username":"freedom",
"password":"peace|LOVE|empathy4ALL"
},

=== Device Control (subscribe section) ===
Put here array of topics where to subscribe

Device output 1 is controlled with action received by subscription to netio/${DEVICE_NAME}/output/1/action topic with QOS 0

"subscribe":[{
"topic":"netio/${DEVICE_NAME}/output/1/action",
"qos":0,
"target":"OUTPUTS/1/ACTION",
"action":"${payload}"
}
],

=== Output State monitoring (publish section) ===
Put here array of topics where to publish.

Device send every 1000 s message to topic with QOS 0, retain true information with output 1 state

"publish":[{
"topic":"netio/${DEVICE_NAME}/output/1/state",
"qos":0,
"retain":true,
"payload":"${OUTPUTS/1/STATE}",
"events":[
{
"type":"timer",
"period":"1000"
}
]
}
]

= 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 ===
{| class="wikitable"
! style="font-weight:bold; background-color:#9b9b9b;" | Item
! style="font-weight:bold; background-color:#9b9b9b;" | Presence
! style="font-weight:bold; background-color:#9b9b9b;" | Possible Values
! style="font-weight:bold; background-color:#9b9b9b;" | Description
! style="font-weight:bold; background-color:#9b9b9b;" | JSON Config Usage
|-
| style="background-color:#efefef;" | url
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" |
| style="background-color:#efefef;" | MQTT broker URL
| style="background-color:#efefef;" | "url":"broker.hivemq.com"
|-
| style="background-color:#efefef;" | port
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | 1 - 65535
| style="background-color:#efefef;" | MQTT broker port
| style="background-color:#efefef;" | "port":1883
|-
| style="background-color:#efefef;" | protocol
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" |
| style="background-color:#efefef;" | protocol spec - mqtt
| style="background-color:#efefef;" | "protocol": "mqtt"
|-
| style="background-color:#efefef;" | ssl
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | true, false
| style="background-color:#efefef;" | Use SSL crypted communication selector
| style="background-color:#efefef;" | "ssl":false
|-
| style="background-color:#efefef;" | type
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | generic
| style="background-color:#efefef;" | Communication/setup type option
| style="background-color:#efefef;" | "type":"generic"
|-
| style="background-color:#efefef;" | username
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | regexp+len
| style="background-color:#efefef;" | Credentials for MQTT broker. Max. 128 characters (since FW 3.2.4).
| style="background-color:#efefef;" | "username":"freedom"
|-
| style="background-color:#efefef;" | password
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | regexp+len
| style="background-color:#efefef;" | Credentials for MQTT broker. Max. 256 characters (since FW 3.2.4).
| style="background-color:#efefef;" | "password":"peace|LOVE|empathy4ALL"
|-
| style="background-color:#efefef;" | clientid
| style="background-color:#efefef;" | optional
| style="background-color:#efefef;" | regexp+len
| style="background-color:#efefef;" | MQTT clientid. Max. 128 characters (since FW 3.2.4). Variables ${DEVICE_MAC} or ${DEVICE_NAME} can be used
| style="background-color:#efefef;" | "clientid":"myEcoTable01"
|-
| style="background-color:#efefef;" | keepalive
| style="background-color:#efefef;" | optional
| style="background-color:#efefef;" | 1 - 65535
| style="background-color:#efefef;" | MQTT keep alive period in seconds
| style="background-color:#efefef;" | "keepalive":90
|}

Note 1: clientid attribute is mandatory for MQTT(s) communication. When not configured, random ID will be generated.

Note 2: To proper communication with MS Azure - it is necessary to set up IoT Hub to use TLS 1.2

See section "TLS 1.2 enforcement available in select regions" in following guidelines https://docs.microsoft.com/en-us/azure/iot-hub/iot-hub-tls-support

=== Examples ===
==== Standard setup ====

==== Security (SSL / TLS) secured setup ====
You can enable MQTTs by using the encrypted port 8883 + "ssl":true.

==== Variables used setup ====

== 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 ===
{| class="wikitable"
! style="font-weight:bold; background-color:#9b9b9b;" | Item
! style="font-weight:bold; background-color:#9b9b9b;" | Presence
! style="font-weight:bold; background-color:#9b9b9b;" | Possible Values
! style="font-weight:bold; background-color:#9b9b9b;" | Description
! style="font-weight:bold; background-color:#9b9b9b;" | JSON Config Usage
|-
| style="background-color:#efefef;" | topic
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | see table below
| style="background-color:#efefef;" | specification of the topic, which MQTT-flex device listens from broker and act accordingly. Max. 128 characters. The "#" can be used since FW 3.2.4 - see note under this table.
| style="background-color:#efefef;" | "topic":"netio/${DEVICE_NAME}/output/1/action"
|-
| style="background-color:#efefef;" | qos
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | 0, 1 or 2
| style="background-color:#efefef;" | 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}
| style="background-color:#efefef;" | "qos":0
|-
| style="background-color:#efefef;" | target
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" |
| style="background-color:#efefef;" | internal definition of action, which can be performed above the specified output
| style="background-color:#efefef;" | "target":"OUTPUTS/1/ACTION"
|-
| style="background-color:#efefef;" | action
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" |
| style="background-color:#efefef;" | a payload or a value the action attribute needs to have passed to
| style="background-color:#efefef;" | "action":"${payload}"
|-
| style="background-color:#efefef;" | actiondefNot supported yet
| style="background-color:#efefef;" | optional
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
|-
| style="background-color:#efefef;" | jsonNot supported yet
| style="background-color:#efefef;" | optional
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
|}

Note: The "#" wildcard can be used in subscribe topic definition. The multi-level wildcard character MUST be specified either on its own or following a topic level separator. In either case it MUST be the last character specified in the Topic.

For example, if a Device subscribes to “devices/{device_id}/messages/devicebound/#”, it would receive messages published using these topic names:

“devices/{device_id}/messages/devicebound/”

“devices/{device_id}/messages/devicebound/{property_bag}”

This should be usefull for use with MS Azure - IoT hub.

=== MQTT Event to rules ===

This feature allow to subscribe to specific MQTT topic and pass payload to Rules or MQTT-flex as event.

target: <code>PROTOCOLS/MQTT/EVENT</code>

<code>
"subscribe": [
{
"action": "${payload}",
"qos": 0,
"target": "PROTOCOLS/MQTT/EVENT",
"topic": "broker/12345/MQTT_EVENT/"
}
]
</code>

=== Examples ===
==== Toggle output with standard payload ====
==== Toggle output with custom payload ====
==== Subscribe to more than one topic ====
==== Trigger Rule sequence from MQTT ====
==== Trigger MQTT publish by MQTT subscribe ====

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 ===
{| class="wikitable"
! style="font-weight:bold; background-color:#9b9b9b;" | Item
! style="font-weight:bold; background-color:#9b9b9b;" | Presence
! style="font-weight:bold; background-color:#9b9b9b;" | Possible Values
! style="font-weight:bold; background-color:#9b9b9b;" | Description
! style="font-weight:bold; background-color:#9b9b9b;" | JSON Config Usage
|-
| style="background-color:#efefef;" | topic
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | see table below
| style="background-color:#efefef;" | definition of the topic, how it is registered towards MQTT broker. Max. 128 characters.
| style="background-color:#efefef;" | "topic":"netio/${DEVICE_NAME}/output/1/load"
|-
| style="background-color:#efefef;" | qos
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | see table below
| style="background-color:#efefef;" | 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}
| style="background-color:#efefef;" |
|-
| style="background-color:#efefef;" | retain
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | boolean: true or false
| style="background-color:#efefef;" | 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}
| style="background-color:#efefef;" | "retain":true
|-
| style="background-color:#efefef;" | payload
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | see table below
| style="background-color:#efefef;" | definition of the payload, what is send to the MQTT broker.
| style="background-color:#efefef;" | "payload":"${OUTPUTS/1/STATE}"
|-
| style="background-color:#efefef;" | events
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | see table below
| style="background-color:#efefef;" | definition of events used for triggering sending of data via mqtt (change, delta, timer)
| style="background-color:#efefef;" |
|-
| style="background-color:#efefef;" | type
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
|-
| style="background-color:#efefef;" | source
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
|-
| style="background-color:#efefef;" | delta
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
|-
| style="background-color:#efefef;" | period
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
|-
| style="background-color:#efefef;" | payloaddefNot supported yet
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
|}

=== Examples ===
==== Publish energy periodically (event timer) ====
==== Publish current on change (delta) ====
==== Publish output state ====
==== Publish to more than one topic with different events ====

= 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 available only on NETIO PowerDIN 4PZ

=== Examples: ===

adressing controll of output 3
OUTPUTS/3/ACTION
getting voltage on output 1
OUTPUTS/1/VOLTAGE
getting state of input 1
INPUTS/1/STATE

= Events =
==== Timer ====

==== Delta ====

==== Change ====

==== Group Events<code>FW 4.0.0+</code>====

= 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 ===
==== VOLTAGE ====
Unit: <code>V</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Present RMS voltage on output 1 is ${OUTPUTS/1/VOLTAGE}"</code>

Example 2: <code>"source":"${OUTPUTS/1/VOLTAGE}"</code>

==== CURRENT ====
Unit: <code>mA</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Present RMS current on output 1 is ${OUTPUTS/1/CURRENT}"</code>

Example 2: <code>"source":"${OUTPUTS/1/CURRENT}"</code>

==== POWER_FACTOR ====
Unit: <code>[-]</code>

Type: float (2 decimals)

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"True Power Factor on output 1 is ${OUTPUTS/1/POWER_FACTOR}"</code>

Example 2: <code>"source":"${OUTPUTS/1/POWER_FACTOR}"</code>

==== LOAD ====
Unit: <code>W</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Present load on output 1 is ${OUTPUTS/1/LOAD}W"</code>

Example 2: <code>"payload":"Device's load connected to output 1 is ${OUTPUTS/1/LOAD}W"</code>

Example 3: <code>"source":"${OUTPUTS/1/LOAD}"</code>

==== STATE ====
Type: bool(integer) - <code>0</code> or <code>1</code>

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Present output 1 state is ${OUTPUTS/1/STATE}"</code>

Example 2: <code>"source":"${OUTPUTS/1/STATE}"</code>

==== ACTION ====
Type: integer

Possible actions:
* <code>0</code> - set state OFF
* <code>1</code> - set state ON
* <code>2</code> - short OFF (restart)
* <code>3</code> - short ON
* <code>4</code> - toggle (switch)
* <code>5</code> - no change

Allowed in: <code>"target"</code>

Example: <code>"target":"OUTPUTS/1/ACTION"</code>

==== DELAY [ms] ====
==== NAME ====
==== FREQUENCY ====
Unit: <code>Hz</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example: <code>"payload":"Frequency in power grid is ${OUTPUTS/1/ENERGY}Hz"</code>

==== ENERGY ====
Energy consumed by an device connected to NETIO device output.

Unit: <code>Wh</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Consumed energy on output 1 is ${OUTPUTS/1/ENERGY}Wh"</code>

Example 2: <code>"source":"${OUTPUTS/1/ENERGY}"</code>

==== REVERSE_ENERGY ====
Energy delivered back to grid. For example from solar system connected to NETIO device output.

Unit: <code>Wh</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Delivered energy on output 1 is ${OUTPUTS/1/REVERSE_ENERGY}Wh"</code>

Example 2: <code>"source":"${OUTPUTS/1/REVERSE_ENERGY}"</code>

==== ENERGY_START ====
Date when the counters ENERGY and REVERSE_ENERGY have been resetted by user.

Unit: <code>unix timestamp</code>

Type: integer

Allowed in: <code>"payload"</code>

Example 1: <code>"payload":"Energy measured since ${OUTPUTS/1/ENERGY_START} unix time"</code>

Example 2: <code>"payload":"${OUTPUTS/1/ENERGY_START}"</code> is output payload <code>1567654639</code>

==== ENERGY_START_FMT ====
Date when the counters ENERGY and REVERSE_ENERGY have been resetted by user.

Unit: <code>fmt date format</code>

Type: string

Allowed in: <code>"payload"</code>

Example 1: <code>"payload":"Energy measured since ${OUTPUTS/1/ENERGY_START}"</code>

Example 2: <code>"payload":"${OUTPUTS/1/ENERGY_START_FMT}"</code> is output payload <code>2019-09-05T03:37:19+00:00</code>

==== ENERGY_NR ====
Non-resettable counter of Energy consumed by an device connected to NETIO device output.

Unit: <code>Wh</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Consumed energy on output 1 is ${OUTPUTS/1/ENERGY_NR}Wh"</code>

Example 2: <code>"source":"${OUTPUTS/1/ENERGY_NR}"</code>

==== REVERSE_ENERGY_NR ====
Non-resettable counter of Energy delivered back to grid. For example from solar system connected to NETIO device output.

Unit: <code>Wh</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Delivered energy on output 1 is ${OUTPUTS/1/REVERSE_ENERGY_NR}Wh"</code>

Example 2: <code>"source":"${OUTPUTS/1/REVERSE_ENERGY_NR}"</code>

==== TOTALs - for 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
* OUTPUTS/TOTAL/PHASE
* OUTPUTS/TOTAL/REVERSE_ENERGY
* OUTPUTS/TOTAL/ENERGY_NR
* OUTPUTS/TOTAL/REVERSE_ENERGY_NR
* OUTPUTS/TOTAL/ENERGY_START
* OUTPUTS/TOTAL/ENERGY_START_FMT

==== REST_JSON ====
Allow use of NETIO JSON structure to control outputs.

Type: string / JSON

Allowed in: <code>"target"</code> for Subscribe section

Example: <code>"target": "REST_JSON"</code>

The payload is JSON structure identical to NETIO JSON API M2M Protocol (documentation available at https://www.netio-products.com/files/NETIO-M2M-API-Protocol-JSON.pdf). You can control one or multiple outputs.

Payload example 1 - Toggle output 1: <code>{"Outputs":[{"ID": 1,"Action": 4}]}</code>

Payload example 2 - Turn output 1 OFF and output 3 ON: <code>{"Outputs":[{"ID":1,"Action":0},{"ID":3,"Action":1}]}</code>

=== INPUT variables ===
==== STATE ====
Type: bool(integer) - <code>0</code> or <code>1</code>

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Present input 1 state is ${INPUTS/1/STATE}"</code>

Example 2: <code>"source":"${INPUTS/1/STATE}"</code>

==== S0 ====
S0 Counter value
Unit: <code>-</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Input 1 S0 Counter value is ${INPUTS/1/S0}impulses"</code>

Example 2: <code>"source":"${INPUTS/1/S0}"</code>

== Payload/topic variables ==

=== DEVICE_NAME ===
Can be used in: "payload", "topic"

Example 1: <code>"payload":"${DEVICE_NAME}"</code>

Example 2: <code>"topic":"netio/${DEVICE_NAME}/output/1/action"</code>

=== DEVICE_MAC ===

=== UPTIME Not yet implemented ===

=== PAYLOAD ===
Can be used in: "action"

Example: <code>"action":"${PAYLOAD}"</code>

=== OUTPUT_ID Not yet implemented===

=== WIFI_SIGNALNot yet implemented ===

=== OUTPUTS_STATUS ===
Provide complete outputs status and measurement if supported.

Type: string / JSON

Allowed in: <code>"payload"</code> for Publish section

Example: <code>"payload":"${OUTPUTS_STATUS}"</code>

Payload example: <code>{ "GlobalMeasure":{"Voltage":236,"TotalCurrent":72,"TotalLoad":11,"TotalEnergy":167,"OverallPowerFactor":0.64,"Frequency":50.07,"Phase":-36.86,"EnergyStart":"2020-06-30T17:04:48+01:00"}, "Outputs":[ {"ID":1,"Name":"Power output 1","State":1,"Action":6,"Delay":2020,"Current":72,"PowerFactor":0.64,"Phase":-36.86,"Energy":139,"ReverseEnergy":0,"Load":11}, {"ID":2,"Name":"Power output 2","State":1,"Action":6,"Delay":2020,"Current":0,"PowerFactor":1.00,"Phase":0.00,"Energy":27,"ReverseEnergy":0,"Load":0}, {"ID":3,"Name":"Free Contact 3","State":1,"Action":6,"Delay":2020}, {"ID":4,"Name":"Free Contact 4","State":1,"Action":6,"Delay":2020} ]}</code>

=== INPUTS_STATUS ===
Provide complete inputs status if supported. Since FW 3.0.0

Type: string / JSON

Allowed in: <code>"payload"</code> for Publish section

Example: <code>"payload":"${INPUTS_STATUS}"</code>

Payload example: <code>{ "Inputs":[ {"ID":1,"Name":"Input 1","State":0,"S0Counter":0}, {"ID":2,"Name":"Input 2","State":0,"S0Counter":0} ]}</code>

=== INOUT_STATUS ===
Provide complete inputs and output status and measurement if supported. Since FW 3.0.0

Type: string / JSON

Allowed in: <code>"payload"</code> for Publish section

Example: <code>"payload":"${INOUT_STATUS}"</code>

Payload example: <code>{ "GlobalMeasure":{"Voltage":238,"TotalCurrent":105,"TotalLoad":17,"TotalEnergy":1451,"OverallPowerFactor":0.67,"Frequency":50.03,"Phase":-33.67,"EnergyStart":"2020-06-30T17:04:48+01:00"}, "Outputs":[ {"ID":1,"Name":"Power output 1","State":0,"Action":6,"Delay":5000,"Current":0,"PowerFactor":1.00,"Phase":0.00,"Energy":701,"ReverseEnergy":0,"Load":0}, {"ID":2,"Name":"Power output 2","State":1,"Action":6,"Delay":5000,"Current":105,"PowerFactor":0.65,"Phase":-33.67,"Energy":750,"ReverseEnergy":0,"Load":17}, {"ID":3,"Name":"Free Contact 3","State":1,"Action":6,"Delay":5000}, {"ID":4,"Name":"Free Contact 4","State":0,"Action":6,"Delay":5000} ], "Inputs":[ {"ID":1,"Name":"Input 1","State":0,"S0Counter":0}, {"ID":2,"Name":"Input 2","State":0,"S0Counter":0} ]}</code>

= Extended MQTT flex JSON config examples =

== Default NETIO MQTT-flex configuration ==
This example demonstrates setup for connection to public <code>broker.hivemq.com</code>, measurement reporting and output control.

The device cabe be controlled via <code>netio/${DEVICE_NAME}/output/1/action topic</code> by sending standard NETIO action values:
* 0 - OFF
* 1 - ON
* 2 - SHORT OFF
* 3 - SHORT ON
* 4 - TOGGLE
* 5 - NO ACTION.

The device report measurements:

* Output state - every 15 minutes or by change
* Voltage [V]- every 5 minutes or by change of 1 V
* Current [mA]- every 5 minutes or by change of 50 mA
* Load(Power) [W]- every 5 minutes or by change of 10 W
* Energy(Consumption) [Wh]- every 15 minutes or by change of 1Wh
* True Power Factor (TPF) [-]- every 5 minutes or by change of 0.02
* Frequency [Hz]- every 1 hour or by change of 0.1 Hz

For register all values, you can use wildcard <code>netio/${DEVICE_NAME}/output/1/#</code>

{
"config":{
"broker":{
"url":"broker.hivemq.com",
"protocol":"mqtt",
"port":1883,
"ssl":false,
"type":"generic",
"username":"",
"password":"",
"clientid":"moje${DEVICE_NAME}${DEVICE_MAC}",
"keepalive":30
},
"subscribe":[
{
"topic":"netio/${DEVICE_NAME}/output/1/action",
"qos":0,
"target":"OUTPUTS/1/ACTION",
"action":"${payload}"
},
{
"topic":"netio/${DEVICE_NAME}/output/1/switch",
"qos":0,
"target":"OUTPUTS/1/ACTION",
"action":4
}
],
"publish":[
{
"topic":"netio/${DEVICE_MAC}/output/1/state",
"qos":0,
"retain":true,
"payload":"${OUTPUTS/1/STATE}",
"events":[
{
"type":"change",
"source":"OUTPUTS/1/STATE"
},
{
"type":"timer",
"period":900
}
]
},
{
"topic":"netio/${DEVICE_NAME}/output/1/voltage",
"qos":0,
"retain":false,
"payload":"${OUTPUTS/1/VOLTAGE}",
"events":[
{
"type":"timer",
"period":300
},
{
"type":"delta",
"source":"OUTPUTS/1/VOLTAGE",
"delta":1
}
]
},
{
"topic":"netio/${DEVICE_NAME}/output/1/current",
"qos":0,
"retain":false,
"payload":"${OUTPUTS/1/CURRENT}",
"events":[
{
"type":"timer",
"period":300
},
{
"type":"delta",
"source":"OUTPUTS/1/CURRENT",
"delta":50
}
]
},
{
"topic":"netio/${DEVICE_NAME}/output/1/load",
"qos":0,
"retain":false,
"payload":"${OUTPUTS/1/LOAD}",
"events":[
{
"type":"timer",
"period":300
},
{
"type":"delta",
"source":"OUTPUTS/1/LOAD",
"delta":10
}
]
},
{
"topic":"netio/${DEVICE_NAME}/output/1/energy",
"qos":0,
"retain":false,
"payload":"${OUTPUTS/1/ENERGY}",
"events":[
{
"type":"timer",
"period":900
},
{
"type":"delta",
"source":"OUTPUTS/1/ENERGY",
"delta":1
}
]
},
{
"topic":"netio/${DEVICE_NAME}/output/1/tpf",
"qos":0,
"retain":false,
"payload":"${OUTPUTS/1/POWER_FACTOR}",
"events":[
{
"type":"timer",
"period":900
},
{
"type":"delta",
"source":"OUTPUTS/1/POWER_FACTOR",
"delta":0.02
}
]
},
{
"topic":"netio/${DEVICE_NAME}/output/1/frequency",
"qos":0,
"retain":false,
"payload":"${OUTPUTS/1/FREQUENCY}",
"events":[
{
"type":"timer",
"period":3600
},
{
"type":"delta",
"source":"OUTPUTS/1/FREQUENCY",
"delta":0.1
}
]
}
]
}
}

MQTT-flex

2023-06-06T12:45:22Z

Bbakala: /* Subscribe */

The MQTT-flex version of the MQTT protocol can be configured in detail thanks to the “flex” extension.

https://www.netio-products.com/en/glossary/mqtt-flex

Why MQTT-flex 
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 [https://en.wikipedia.org/wiki/MQTT 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 [https://en.wikipedia.org/wiki/JSON 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 101x 
* PowerCable REST 101x 
* PowerPDU 4PS 
* PowerPDU 4KS 
* PowerPDU 8QS 
* PowerDIN 4PZ 
* PowerBOX 3Px 
* PowerBOX 4Kx 

FW version: 
>2.2.1

===Not supported NETIO devices:===
* PowerPDU 4C 
* NETIO 4 
* NETIO 4All 

= Simple MQTT-flex configuration + explanation =

''We strongly recommend to create and test MQTT-flex configuration on "local" device what can be easily restarted. The validation of config before saving is not 100% and for example some specific typos can cause a freeze of a device - the solution is to restart a device (unplug/plug input power cable). If the configuration is saved and device is working then there are no known failure case so it is safe to use this configuration on the "remote" devices.''

{
"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":false,
"payload":"${OUTPUTS/1/STATE}",
"events":[
{
"type":"timer",
"period":"1000"
}
]
}
]
}
}
=== Client Configuration (broker section) ===
Put here MQTT client connection setup

This configuration example set NETIO device to connect to broker.hivemq.com with mqtt protocol, no ssl connection with credetials freedom/peace|love|empathy4ALL.

"broker":{
"url":"broker.hivemq.com",
"protocol":"mqtt",
"port":1883,
"ssl":false,
"type":"generic",
"username":"freedom",
"password":"peace|LOVE|empathy4ALL"
},

=== Device Control (subscribe section) ===
Put here array of topics where to subscribe

Device output 1 is controlled with action received by subscription to netio/${DEVICE_NAME}/output/1/action topic with QOS 0

"subscribe":[{
"topic":"netio/${DEVICE_NAME}/output/1/action",
"qos":0,
"target":"OUTPUTS/1/ACTION",
"action":"${payload}"
}
],

=== Output State monitoring (publish section) ===
Put here array of topics where to publish.

Device send every 1000 s message to topic with QOS 0, retain true information with output 1 state

"publish":[{
"topic":"netio/${DEVICE_NAME}/output/1/state",
"qos":0,
"retain":true,
"payload":"${OUTPUTS/1/STATE}",
"events":[
{
"type":"timer",
"period":"1000"
}
]
}
]

= 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 ===
{| class="wikitable"
! style="font-weight:bold; background-color:#9b9b9b;" | Item
! style="font-weight:bold; background-color:#9b9b9b;" | Presence
! style="font-weight:bold; background-color:#9b9b9b;" | Possible Values
! style="font-weight:bold; background-color:#9b9b9b;" | Description
! style="font-weight:bold; background-color:#9b9b9b;" | JSON Config Usage
|-
| style="background-color:#efefef;" | url
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" |
| style="background-color:#efefef;" | MQTT broker URL
| style="background-color:#efefef;" | "url":"broker.hivemq.com"
|-
| style="background-color:#efefef;" | port
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | 1 - 65535
| style="background-color:#efefef;" | MQTT broker port
| style="background-color:#efefef;" | "port":1883
|-
| style="background-color:#efefef;" | protocol
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" |
| style="background-color:#efefef;" | protocol spec - mqtt
| style="background-color:#efefef;" | "protocol": "mqtt"
|-
| style="background-color:#efefef;" | ssl
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | true, false
| style="background-color:#efefef;" | Use SSL crypted communication selector
| style="background-color:#efefef;" | "ssl":false
|-
| style="background-color:#efefef;" | type
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | generic
| style="background-color:#efefef;" | Communication/setup type option
| style="background-color:#efefef;" | "type":"generic"
|-
| style="background-color:#efefef;" | username
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | regexp+len
| style="background-color:#efefef;" | Credentials for MQTT broker. Max. 128 characters (since FW 3.2.4).
| style="background-color:#efefef;" | "username":"freedom"
|-
| style="background-color:#efefef;" | password
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | regexp+len
| style="background-color:#efefef;" | Credentials for MQTT broker. Max. 256 characters (since FW 3.2.4).
| style="background-color:#efefef;" | "password":"peace|LOVE|empathy4ALL"
|-
| style="background-color:#efefef;" | clientid
| style="background-color:#efefef;" | optional
| style="background-color:#efefef;" | regexp+len
| style="background-color:#efefef;" | MQTT clientid. Max. 128 characters (since FW 3.2.4). Variables ${DEVICE_MAC} or ${DEVICE_NAME} can be used
| style="background-color:#efefef;" | "clientid":"myEcoTable01"
|-
| style="background-color:#efefef;" | keepalive
| style="background-color:#efefef;" | optional
| style="background-color:#efefef;" | 1 - 65535
| style="background-color:#efefef;" | MQTT keep alive period in seconds
| style="background-color:#efefef;" | "keepalive":90
|}

Note 1: clientid attribute is mandatory for MQTT(s) communication. When not configured, random ID will be generated.

Note 2: To proper communication with MS Azure - it is necessary to set up IoT Hub to use TLS 1.2

See section "TLS 1.2 enforcement available in select regions" in following guidelines https://docs.microsoft.com/en-us/azure/iot-hub/iot-hub-tls-support

=== Examples ===
==== Standard setup ====

==== Security (SSL / TLS) secured setup ====
You can enable MQTTs by using the encrypted port 8883 + "ssl":true.

==== Variables used setup ====

== 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 ===
{| class="wikitable"
! style="font-weight:bold; background-color:#9b9b9b;" | Item
! style="font-weight:bold; background-color:#9b9b9b;" | Presence
! style="font-weight:bold; background-color:#9b9b9b;" | Possible Values
! style="font-weight:bold; background-color:#9b9b9b;" | Description
! style="font-weight:bold; background-color:#9b9b9b;" | JSON Config Usage
|-
| style="background-color:#efefef;" | topic
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | see table below
| style="background-color:#efefef;" | specification of the topic, which MQTT-flex device listens from broker and act accordingly. Max. 128 characters. The "#" can be used since FW 3.2.4 - see note under this table.
| style="background-color:#efefef;" | "topic":"netio/${DEVICE_NAME}/output/1/action"
|-
| style="background-color:#efefef;" | qos
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | 0, 1 or 2
| style="background-color:#efefef;" | 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}
| style="background-color:#efefef;" | "qos":0
|-
| style="background-color:#efefef;" | target
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" |
| style="background-color:#efefef;" | internal definition of action, which can be performed above the specified output
| style="background-color:#efefef;" | "target":"OUTPUTS/1/ACTION"
|-
| style="background-color:#efefef;" | action
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" |
| style="background-color:#efefef;" | a payload or a value the action attribute needs to have passed to
| style="background-color:#efefef;" | "action":"${payload}"
|-
| style="background-color:#efefef;" | actiondefNot supported yet
| style="background-color:#efefef;" | optional
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
|-
| style="background-color:#efefef;" | jsonNot supported yet
| style="background-color:#efefef;" | optional
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
|}

Note: The "#" wildcard can be used in subscribe topic definition. The multi-level wildcard character MUST be specified either on its own or following a topic level separator. In either case it MUST be the last character specified in the Topic.

For example, if a Device subscribes to “devices/{device_id}/messages/devicebound/#”, it would receive messages published using these topic names:

“devices/{device_id}/messages/devicebound/”

“devices/{device_id}/messages/devicebound/{property_bag}”

This should be usefull for use with MS Azure - IoT hub.

=== MQTT Event to rules ===

This feature allow to subscribe to specific MQTT topic and pass payload to Rules or MQTT-flex as event.

target: <code></code>
<code>
"subscribe": [
{
"action": "${payload}",
"qos": 0,
"target": "PROTOCOLS/MQTT/EVENT",
"topic": "broker/12345/MQTT_EVENT/"
}
]
</code>

=== Examples ===
==== Toggle output with standard payload ====
==== Toggle output with custom payload ====
==== Subscribe to more than one topic ====
==== Trigger Rule sequence from MQTT ====
==== Trigger MQTT publish by MQTT subscribe ====

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 ===
{| class="wikitable"
! style="font-weight:bold; background-color:#9b9b9b;" | Item
! style="font-weight:bold; background-color:#9b9b9b;" | Presence
! style="font-weight:bold; background-color:#9b9b9b;" | Possible Values
! style="font-weight:bold; background-color:#9b9b9b;" | Description
! style="font-weight:bold; background-color:#9b9b9b;" | JSON Config Usage
|-
| style="background-color:#efefef;" | topic
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | see table below
| style="background-color:#efefef;" | definition of the topic, how it is registered towards MQTT broker. Max. 128 characters.
| style="background-color:#efefef;" | "topic":"netio/${DEVICE_NAME}/output/1/load"
|-
| style="background-color:#efefef;" | qos
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | see table below
| style="background-color:#efefef;" | 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}
| style="background-color:#efefef;" |
|-
| style="background-color:#efefef;" | retain
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | boolean: true or false
| style="background-color:#efefef;" | 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}
| style="background-color:#efefef;" | "retain":true
|-
| style="background-color:#efefef;" | payload
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | see table below
| style="background-color:#efefef;" | definition of the payload, what is send to the MQTT broker.
| style="background-color:#efefef;" | "payload":"${OUTPUTS/1/STATE}"
|-
| style="background-color:#efefef;" | events
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | see table below
| style="background-color:#efefef;" | definition of events used for triggering sending of data via mqtt (change, delta, timer)
| style="background-color:#efefef;" |
|-
| style="background-color:#efefef;" | type
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
|-
| style="background-color:#efefef;" | source
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
|-
| style="background-color:#efefef;" | delta
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
|-
| style="background-color:#efefef;" | period
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
|-
| style="background-color:#efefef;" | payloaddefNot supported yet
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
|}

=== Examples ===
==== Publish energy periodically (event timer) ====
==== Publish current on change (delta) ====
==== Publish output state ====
==== Publish to more than one topic with different events ====

= 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 available only on NETIO PowerDIN 4PZ

=== Examples: ===

adressing controll of output 3
OUTPUTS/3/ACTION
getting voltage on output 1
OUTPUTS/1/VOLTAGE
getting state of input 1
INPUTS/1/STATE

= Events =
==== Timer ====

==== Delta ====

==== Change ====

==== Group Events<code>FW 4.0.0+</code>====

= 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 ===
==== VOLTAGE ====
Unit: <code>V</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Present RMS voltage on output 1 is ${OUTPUTS/1/VOLTAGE}"</code>

Example 2: <code>"source":"${OUTPUTS/1/VOLTAGE}"</code>

==== CURRENT ====
Unit: <code>mA</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Present RMS current on output 1 is ${OUTPUTS/1/CURRENT}"</code>

Example 2: <code>"source":"${OUTPUTS/1/CURRENT}"</code>

==== POWER_FACTOR ====
Unit: <code>[-]</code>

Type: float (2 decimals)

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"True Power Factor on output 1 is ${OUTPUTS/1/POWER_FACTOR}"</code>

Example 2: <code>"source":"${OUTPUTS/1/POWER_FACTOR}"</code>

==== LOAD ====
Unit: <code>W</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Present load on output 1 is ${OUTPUTS/1/LOAD}W"</code>

Example 2: <code>"payload":"Device's load connected to output 1 is ${OUTPUTS/1/LOAD}W"</code>

Example 3: <code>"source":"${OUTPUTS/1/LOAD}"</code>

==== STATE ====
Type: bool(integer) - <code>0</code> or <code>1</code>

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Present output 1 state is ${OUTPUTS/1/STATE}"</code>

Example 2: <code>"source":"${OUTPUTS/1/STATE}"</code>

==== ACTION ====
Type: integer

Possible actions:
* <code>0</code> - set state OFF
* <code>1</code> - set state ON
* <code>2</code> - short OFF (restart)
* <code>3</code> - short ON
* <code>4</code> - toggle (switch)
* <code>5</code> - no change

Allowed in: <code>"target"</code>

Example: <code>"target":"OUTPUTS/1/ACTION"</code>

==== DELAY [ms] ====
==== NAME ====
==== FREQUENCY ====
Unit: <code>Hz</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example: <code>"payload":"Frequency in power grid is ${OUTPUTS/1/ENERGY}Hz"</code>

==== ENERGY ====
Energy consumed by an device connected to NETIO device output.

Unit: <code>Wh</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Consumed energy on output 1 is ${OUTPUTS/1/ENERGY}Wh"</code>

Example 2: <code>"source":"${OUTPUTS/1/ENERGY}"</code>

==== REVERSE_ENERGY ====
Energy delivered back to grid. For example from solar system connected to NETIO device output.

Unit: <code>Wh</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Delivered energy on output 1 is ${OUTPUTS/1/REVERSE_ENERGY}Wh"</code>

Example 2: <code>"source":"${OUTPUTS/1/REVERSE_ENERGY}"</code>

==== ENERGY_START ====
Date when the counters ENERGY and REVERSE_ENERGY have been resetted by user.

Unit: <code>unix timestamp</code>

Type: integer

Allowed in: <code>"payload"</code>

Example 1: <code>"payload":"Energy measured since ${OUTPUTS/1/ENERGY_START} unix time"</code>

Example 2: <code>"payload":"${OUTPUTS/1/ENERGY_START}"</code> is output payload <code>1567654639</code>

==== ENERGY_START_FMT ====
Date when the counters ENERGY and REVERSE_ENERGY have been resetted by user.

Unit: <code>fmt date format</code>

Type: string

Allowed in: <code>"payload"</code>

Example 1: <code>"payload":"Energy measured since ${OUTPUTS/1/ENERGY_START}"</code>

Example 2: <code>"payload":"${OUTPUTS/1/ENERGY_START_FMT}"</code> is output payload <code>2019-09-05T03:37:19+00:00</code>

==== ENERGY_NR ====
Non-resettable counter of Energy consumed by an device connected to NETIO device output.

Unit: <code>Wh</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Consumed energy on output 1 is ${OUTPUTS/1/ENERGY_NR}Wh"</code>

Example 2: <code>"source":"${OUTPUTS/1/ENERGY_NR}"</code>

==== REVERSE_ENERGY_NR ====
Non-resettable counter of Energy delivered back to grid. For example from solar system connected to NETIO device output.

Unit: <code>Wh</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Delivered energy on output 1 is ${OUTPUTS/1/REVERSE_ENERGY_NR}Wh"</code>

Example 2: <code>"source":"${OUTPUTS/1/REVERSE_ENERGY_NR}"</code>

==== TOTALs - for 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
* OUTPUTS/TOTAL/PHASE
* OUTPUTS/TOTAL/REVERSE_ENERGY
* OUTPUTS/TOTAL/ENERGY_NR
* OUTPUTS/TOTAL/REVERSE_ENERGY_NR
* OUTPUTS/TOTAL/ENERGY_START
* OUTPUTS/TOTAL/ENERGY_START_FMT

==== REST_JSON ====
Allow use of NETIO JSON structure to control outputs.

Type: string / JSON

Allowed in: <code>"target"</code> for Subscribe section

Example: <code>"target": "REST_JSON"</code>

The payload is JSON structure identical to NETIO JSON API M2M Protocol (documentation available at https://www.netio-products.com/files/NETIO-M2M-API-Protocol-JSON.pdf). You can control one or multiple outputs.

Payload example 1 - Toggle output 1: <code>{"Outputs":[{"ID": 1,"Action": 4}]}</code>

Payload example 2 - Turn output 1 OFF and output 3 ON: <code>{"Outputs":[{"ID":1,"Action":0},{"ID":3,"Action":1}]}</code>

=== INPUT variables ===
==== STATE ====
Type: bool(integer) - <code>0</code> or <code>1</code>

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Present input 1 state is ${INPUTS/1/STATE}"</code>

Example 2: <code>"source":"${INPUTS/1/STATE}"</code>

==== S0 ====
S0 Counter value
Unit: <code>-</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Input 1 S0 Counter value is ${INPUTS/1/S0}impulses"</code>

Example 2: <code>"source":"${INPUTS/1/S0}"</code>

== Payload/topic variables ==

=== DEVICE_NAME ===
Can be used in: "payload", "topic"

Example 1: <code>"payload":"${DEVICE_NAME}"</code>

Example 2: <code>"topic":"netio/${DEVICE_NAME}/output/1/action"</code>

=== DEVICE_MAC ===

=== UPTIME Not yet implemented ===

=== PAYLOAD ===
Can be used in: "action"

Example: <code>"action":"${PAYLOAD}"</code>

=== OUTPUT_ID Not yet implemented===

=== WIFI_SIGNALNot yet implemented ===

=== OUTPUTS_STATUS ===
Provide complete outputs status and measurement if supported.

Type: string / JSON

Allowed in: <code>"payload"</code> for Publish section

Example: <code>"payload":"${OUTPUTS_STATUS}"</code>

Payload example: <code>{ "GlobalMeasure":{"Voltage":236,"TotalCurrent":72,"TotalLoad":11,"TotalEnergy":167,"OverallPowerFactor":0.64,"Frequency":50.07,"Phase":-36.86,"EnergyStart":"2020-06-30T17:04:48+01:00"}, "Outputs":[ {"ID":1,"Name":"Power output 1","State":1,"Action":6,"Delay":2020,"Current":72,"PowerFactor":0.64,"Phase":-36.86,"Energy":139,"ReverseEnergy":0,"Load":11}, {"ID":2,"Name":"Power output 2","State":1,"Action":6,"Delay":2020,"Current":0,"PowerFactor":1.00,"Phase":0.00,"Energy":27,"ReverseEnergy":0,"Load":0}, {"ID":3,"Name":"Free Contact 3","State":1,"Action":6,"Delay":2020}, {"ID":4,"Name":"Free Contact 4","State":1,"Action":6,"Delay":2020} ]}</code>

=== INPUTS_STATUS ===
Provide complete inputs status if supported. Since FW 3.0.0

Type: string / JSON

Allowed in: <code>"payload"</code> for Publish section

Example: <code>"payload":"${INPUTS_STATUS}"</code>

Payload example: <code>{ "Inputs":[ {"ID":1,"Name":"Input 1","State":0,"S0Counter":0}, {"ID":2,"Name":"Input 2","State":0,"S0Counter":0} ]}</code>

=== INOUT_STATUS ===
Provide complete inputs and output status and measurement if supported. Since FW 3.0.0

Type: string / JSON

Allowed in: <code>"payload"</code> for Publish section

Example: <code>"payload":"${INOUT_STATUS}"</code>

Payload example: <code>{ "GlobalMeasure":{"Voltage":238,"TotalCurrent":105,"TotalLoad":17,"TotalEnergy":1451,"OverallPowerFactor":0.67,"Frequency":50.03,"Phase":-33.67,"EnergyStart":"2020-06-30T17:04:48+01:00"}, "Outputs":[ {"ID":1,"Name":"Power output 1","State":0,"Action":6,"Delay":5000,"Current":0,"PowerFactor":1.00,"Phase":0.00,"Energy":701,"ReverseEnergy":0,"Load":0}, {"ID":2,"Name":"Power output 2","State":1,"Action":6,"Delay":5000,"Current":105,"PowerFactor":0.65,"Phase":-33.67,"Energy":750,"ReverseEnergy":0,"Load":17}, {"ID":3,"Name":"Free Contact 3","State":1,"Action":6,"Delay":5000}, {"ID":4,"Name":"Free Contact 4","State":0,"Action":6,"Delay":5000} ], "Inputs":[ {"ID":1,"Name":"Input 1","State":0,"S0Counter":0}, {"ID":2,"Name":"Input 2","State":0,"S0Counter":0} ]}</code>

= Extended MQTT flex JSON config examples =

== Default NETIO MQTT-flex configuration ==
This example demonstrates setup for connection to public <code>broker.hivemq.com</code>, measurement reporting and output control.

The device cabe be controlled via <code>netio/${DEVICE_NAME}/output/1/action topic</code> by sending standard NETIO action values:
* 0 - OFF
* 1 - ON
* 2 - SHORT OFF
* 3 - SHORT ON
* 4 - TOGGLE
* 5 - NO ACTION.

The device report measurements:

* Output state - every 15 minutes or by change
* Voltage [V]- every 5 minutes or by change of 1 V
* Current [mA]- every 5 minutes or by change of 50 mA
* Load(Power) [W]- every 5 minutes or by change of 10 W
* Energy(Consumption) [Wh]- every 15 minutes or by change of 1Wh
* True Power Factor (TPF) [-]- every 5 minutes or by change of 0.02
* Frequency [Hz]- every 1 hour or by change of 0.1 Hz

For register all values, you can use wildcard <code>netio/${DEVICE_NAME}/output/1/#</code>

{
"config":{
"broker":{
"url":"broker.hivemq.com",
"protocol":"mqtt",
"port":1883,
"ssl":false,
"type":"generic",
"username":"",
"password":"",
"clientid":"moje${DEVICE_NAME}${DEVICE_MAC}",
"keepalive":30
},
"subscribe":[
{
"topic":"netio/${DEVICE_NAME}/output/1/action",
"qos":0,
"target":"OUTPUTS/1/ACTION",
"action":"${payload}"
},
{
"topic":"netio/${DEVICE_NAME}/output/1/switch",
"qos":0,
"target":"OUTPUTS/1/ACTION",
"action":4
}
],
"publish":[
{
"topic":"netio/${DEVICE_MAC}/output/1/state",
"qos":0,
"retain":true,
"payload":"${OUTPUTS/1/STATE}",
"events":[
{
"type":"change",
"source":"OUTPUTS/1/STATE"
},
{
"type":"timer",
"period":900
}
]
},
{
"topic":"netio/${DEVICE_NAME}/output/1/voltage",
"qos":0,
"retain":false,
"payload":"${OUTPUTS/1/VOLTAGE}",
"events":[
{
"type":"timer",
"period":300
},
{
"type":"delta",
"source":"OUTPUTS/1/VOLTAGE",
"delta":1
}
]
},
{
"topic":"netio/${DEVICE_NAME}/output/1/current",
"qos":0,
"retain":false,
"payload":"${OUTPUTS/1/CURRENT}",
"events":[
{
"type":"timer",
"period":300
},
{
"type":"delta",
"source":"OUTPUTS/1/CURRENT",
"delta":50
}
]
},
{
"topic":"netio/${DEVICE_NAME}/output/1/load",
"qos":0,
"retain":false,
"payload":"${OUTPUTS/1/LOAD}",
"events":[
{
"type":"timer",
"period":300
},
{
"type":"delta",
"source":"OUTPUTS/1/LOAD",
"delta":10
}
]
},
{
"topic":"netio/${DEVICE_NAME}/output/1/energy",
"qos":0,
"retain":false,
"payload":"${OUTPUTS/1/ENERGY}",
"events":[
{
"type":"timer",
"period":900
},
{
"type":"delta",
"source":"OUTPUTS/1/ENERGY",
"delta":1
}
]
},
{
"topic":"netio/${DEVICE_NAME}/output/1/tpf",
"qos":0,
"retain":false,
"payload":"${OUTPUTS/1/POWER_FACTOR}",
"events":[
{
"type":"timer",
"period":900
},
{
"type":"delta",
"source":"OUTPUTS/1/POWER_FACTOR",
"delta":0.02
}
]
},
{
"topic":"netio/${DEVICE_NAME}/output/1/frequency",
"qos":0,
"retain":false,
"payload":"${OUTPUTS/1/FREQUENCY}",
"events":[
{
"type":"timer",
"period":3600
},
{
"type":"delta",
"source":"OUTPUTS/1/FREQUENCY",
"delta":0.1
}
]
}
]
}
}

MQTT-flex

2023-06-05T21:35:35Z

Bbakala: /* Commands */

The MQTT-flex version of the MQTT protocol can be configured in detail thanks to the “flex” extension.

https://www.netio-products.com/en/glossary/mqtt-flex

Why MQTT-flex 
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 [https://en.wikipedia.org/wiki/MQTT 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 [https://en.wikipedia.org/wiki/JSON 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 101x 
* PowerCable REST 101x 
* PowerPDU 4PS 
* PowerPDU 4KS 
* PowerPDU 8QS 
* PowerDIN 4PZ 
* PowerBOX 3Px 
* PowerBOX 4Kx 

FW version: 
>2.2.1

===Not supported NETIO devices:===
* PowerPDU 4C 
* NETIO 4 
* NETIO 4All 

= Simple MQTT-flex configuration + explanation =

''We strongly recommend to create and test MQTT-flex configuration on "local" device what can be easily restarted. The validation of config before saving is not 100% and for example some specific typos can cause a freeze of a device - the solution is to restart a device (unplug/plug input power cable). If the configuration is saved and device is working then there are no known failure case so it is safe to use this configuration on the "remote" devices.''

{
"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":false,
"payload":"${OUTPUTS/1/STATE}",
"events":[
{
"type":"timer",
"period":"1000"
}
]
}
]
}
}
=== Client Configuration (broker section) ===
Put here MQTT client connection setup

This configuration example set NETIO device to connect to broker.hivemq.com with mqtt protocol, no ssl connection with credetials freedom/peace|love|empathy4ALL.

"broker":{
"url":"broker.hivemq.com",
"protocol":"mqtt",
"port":1883,
"ssl":false,
"type":"generic",
"username":"freedom",
"password":"peace|LOVE|empathy4ALL"
},

=== Device Control (subscribe section) ===
Put here array of topics where to subscribe

Device output 1 is controlled with action received by subscription to netio/${DEVICE_NAME}/output/1/action topic with QOS 0

"subscribe":[{
"topic":"netio/${DEVICE_NAME}/output/1/action",
"qos":0,
"target":"OUTPUTS/1/ACTION",
"action":"${payload}"
}
],

=== Output State monitoring (publish section) ===
Put here array of topics where to publish.

Device send every 1000 s message to topic with QOS 0, retain true information with output 1 state

"publish":[{
"topic":"netio/${DEVICE_NAME}/output/1/state",
"qos":0,
"retain":true,
"payload":"${OUTPUTS/1/STATE}",
"events":[
{
"type":"timer",
"period":"1000"
}
]
}
]

= 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 ===
{| class="wikitable"
! style="font-weight:bold; background-color:#9b9b9b;" | Item
! style="font-weight:bold; background-color:#9b9b9b;" | Presence
! style="font-weight:bold; background-color:#9b9b9b;" | Possible Values
! style="font-weight:bold; background-color:#9b9b9b;" | Description
! style="font-weight:bold; background-color:#9b9b9b;" | JSON Config Usage
|-
| style="background-color:#efefef;" | url
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" |
| style="background-color:#efefef;" | MQTT broker URL
| style="background-color:#efefef;" | "url":"broker.hivemq.com"
|-
| style="background-color:#efefef;" | port
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | 1 - 65535
| style="background-color:#efefef;" | MQTT broker port
| style="background-color:#efefef;" | "port":1883
|-
| style="background-color:#efefef;" | protocol
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" |
| style="background-color:#efefef;" | protocol spec - mqtt
| style="background-color:#efefef;" | "protocol": "mqtt"
|-
| style="background-color:#efefef;" | ssl
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | true, false
| style="background-color:#efefef;" | Use SSL crypted communication selector
| style="background-color:#efefef;" | "ssl":false
|-
| style="background-color:#efefef;" | type
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | generic
| style="background-color:#efefef;" | Communication/setup type option
| style="background-color:#efefef;" | "type":"generic"
|-
| style="background-color:#efefef;" | username
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | regexp+len
| style="background-color:#efefef;" | Credentials for MQTT broker. Max. 128 characters (since FW 3.2.4).
| style="background-color:#efefef;" | "username":"freedom"
|-
| style="background-color:#efefef;" | password
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | regexp+len
| style="background-color:#efefef;" | Credentials for MQTT broker. Max. 256 characters (since FW 3.2.4).
| style="background-color:#efefef;" | "password":"peace|LOVE|empathy4ALL"
|-
| style="background-color:#efefef;" | clientid
| style="background-color:#efefef;" | optional
| style="background-color:#efefef;" | regexp+len
| style="background-color:#efefef;" | MQTT clientid. Max. 128 characters (since FW 3.2.4). Variables ${DEVICE_MAC} or ${DEVICE_NAME} can be used
| style="background-color:#efefef;" | "clientid":"myEcoTable01"
|-
| style="background-color:#efefef;" | keepalive
| style="background-color:#efefef;" | optional
| style="background-color:#efefef;" | 1 - 65535
| style="background-color:#efefef;" | MQTT keep alive period in seconds
| style="background-color:#efefef;" | "keepalive":90
|}

Note 1: clientid attribute is mandatory for MQTT(s) communication. When not configured, random ID will be generated.

Note 2: To proper communication with MS Azure - it is necessary to set up IoT Hub to use TLS 1.2

See section "TLS 1.2 enforcement available in select regions" in following guidelines https://docs.microsoft.com/en-us/azure/iot-hub/iot-hub-tls-support

=== Examples ===
==== Standard setup ====

==== Security (SSL / TLS) secured setup ====
You can enable MQTTs by using the encrypted port 8883 + "ssl":true.

==== Variables used setup ====

== 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 ===
{| class="wikitable"
! style="font-weight:bold; background-color:#9b9b9b;" | Item
! style="font-weight:bold; background-color:#9b9b9b;" | Presence
! style="font-weight:bold; background-color:#9b9b9b;" | Possible Values
! style="font-weight:bold; background-color:#9b9b9b;" | Description
! style="font-weight:bold; background-color:#9b9b9b;" | JSON Config Usage
|-
| style="background-color:#efefef;" | topic
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | see table below
| style="background-color:#efefef;" | specification of the topic, which MQTT-flex device listens from broker and act accordingly. Max. 128 characters. The "#" can be used since FW 3.2.4 - see note under this table.
| style="background-color:#efefef;" | "topic":"netio/${DEVICE_NAME}/output/1/action"
|-
| style="background-color:#efefef;" | qos
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | 0, 1 or 2
| style="background-color:#efefef;" | 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}
| style="background-color:#efefef;" | "qos":0
|-
| style="background-color:#efefef;" | target
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" |
| style="background-color:#efefef;" | internal definition of action, which can be performed above the specified output
| style="background-color:#efefef;" | "target":"OUTPUTS/1/ACTION"
|-
| style="background-color:#efefef;" | action
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" |
| style="background-color:#efefef;" | a payload or a value the action attribute needs to have passed to
| style="background-color:#efefef;" | "action":"${payload}"
|-
| style="background-color:#efefef;" | actiondefNot supported yet
| style="background-color:#efefef;" | optional
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
|-
| style="background-color:#efefef;" | jsonNot supported yet
| style="background-color:#efefef;" | optional
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
|}

Note: The "#" wildcard can be used in subscribe topic definition. The multi-level wildcard character MUST be specified either on its own or following a topic level separator. In either case it MUST be the last character specified in the Topic.

For example, if a Device subscribes to “devices/{device_id}/messages/devicebound/#”, it would receive messages published using these topic names:

“devices/{device_id}/messages/devicebound/”

“devices/{device_id}/messages/devicebound/{property_bag}”

This should be usefull for use with MS Azure - IoT hub.

=== Examples ===
==== Toggle output with standard payload ====
==== Toggle output with custom payload ====
==== Subscribe to more than one topic ====

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 ===
{| class="wikitable"
! style="font-weight:bold; background-color:#9b9b9b;" | Item
! style="font-weight:bold; background-color:#9b9b9b;" | Presence
! style="font-weight:bold; background-color:#9b9b9b;" | Possible Values
! style="font-weight:bold; background-color:#9b9b9b;" | Description
! style="font-weight:bold; background-color:#9b9b9b;" | JSON Config Usage
|-
| style="background-color:#efefef;" | topic
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | see table below
| style="background-color:#efefef;" | definition of the topic, how it is registered towards MQTT broker. Max. 128 characters.
| style="background-color:#efefef;" | "topic":"netio/${DEVICE_NAME}/output/1/load"
|-
| style="background-color:#efefef;" | qos
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | see table below
| style="background-color:#efefef;" | 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}
| style="background-color:#efefef;" |
|-
| style="background-color:#efefef;" | retain
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | boolean: true or false
| style="background-color:#efefef;" | 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}
| style="background-color:#efefef;" | "retain":true
|-
| style="background-color:#efefef;" | payload
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | see table below
| style="background-color:#efefef;" | definition of the payload, what is send to the MQTT broker.
| style="background-color:#efefef;" | "payload":"${OUTPUTS/1/STATE}"
|-
| style="background-color:#efefef;" | events
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | see table below
| style="background-color:#efefef;" | definition of events used for triggering sending of data via mqtt (change, delta, timer)
| style="background-color:#efefef;" |
|-
| style="background-color:#efefef;" | type
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
|-
| style="background-color:#efefef;" | source
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
|-
| style="background-color:#efefef;" | delta
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
|-
| style="background-color:#efefef;" | period
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
|-
| style="background-color:#efefef;" | payloaddefNot supported yet
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
|}

=== Examples ===
==== Publish energy periodically (event timer) ====
==== Publish current on change (delta) ====
==== Publish output state ====
==== Publish to more than one topic with different events ====

= 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 available only on NETIO PowerDIN 4PZ

=== Examples: ===

adressing controll of output 3
OUTPUTS/3/ACTION
getting voltage on output 1
OUTPUTS/1/VOLTAGE
getting state of input 1
INPUTS/1/STATE

= Events =
==== Timer ====

==== Delta ====

==== Change ====

==== Group Events<code>FW 4.0.0+</code>====

= 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 ===
==== VOLTAGE ====
Unit: <code>V</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Present RMS voltage on output 1 is ${OUTPUTS/1/VOLTAGE}"</code>

Example 2: <code>"source":"${OUTPUTS/1/VOLTAGE}"</code>

==== CURRENT ====
Unit: <code>mA</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Present RMS current on output 1 is ${OUTPUTS/1/CURRENT}"</code>

Example 2: <code>"source":"${OUTPUTS/1/CURRENT}"</code>

==== POWER_FACTOR ====
Unit: <code>[-]</code>

Type: float (2 decimals)

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"True Power Factor on output 1 is ${OUTPUTS/1/POWER_FACTOR}"</code>

Example 2: <code>"source":"${OUTPUTS/1/POWER_FACTOR}"</code>

==== LOAD ====
Unit: <code>W</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Present load on output 1 is ${OUTPUTS/1/LOAD}W"</code>

Example 2: <code>"payload":"Device's load connected to output 1 is ${OUTPUTS/1/LOAD}W"</code>

Example 3: <code>"source":"${OUTPUTS/1/LOAD}"</code>

==== STATE ====
Type: bool(integer) - <code>0</code> or <code>1</code>

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Present output 1 state is ${OUTPUTS/1/STATE}"</code>

Example 2: <code>"source":"${OUTPUTS/1/STATE}"</code>

==== ACTION ====
Type: integer

Possible actions:
* <code>0</code> - set state OFF
* <code>1</code> - set state ON
* <code>2</code> - short OFF (restart)
* <code>3</code> - short ON
* <code>4</code> - toggle (switch)
* <code>5</code> - no change

Allowed in: <code>"target"</code>

Example: <code>"target":"OUTPUTS/1/ACTION"</code>

==== DELAY [ms] ====
==== NAME ====
==== FREQUENCY ====
Unit: <code>Hz</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example: <code>"payload":"Frequency in power grid is ${OUTPUTS/1/ENERGY}Hz"</code>

==== ENERGY ====
Energy consumed by an device connected to NETIO device output.

Unit: <code>Wh</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Consumed energy on output 1 is ${OUTPUTS/1/ENERGY}Wh"</code>

Example 2: <code>"source":"${OUTPUTS/1/ENERGY}"</code>

==== REVERSE_ENERGY ====
Energy delivered back to grid. For example from solar system connected to NETIO device output.

Unit: <code>Wh</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Delivered energy on output 1 is ${OUTPUTS/1/REVERSE_ENERGY}Wh"</code>

Example 2: <code>"source":"${OUTPUTS/1/REVERSE_ENERGY}"</code>

==== ENERGY_START ====
Date when the counters ENERGY and REVERSE_ENERGY have been resetted by user.

Unit: <code>unix timestamp</code>

Type: integer

Allowed in: <code>"payload"</code>

Example 1: <code>"payload":"Energy measured since ${OUTPUTS/1/ENERGY_START} unix time"</code>

Example 2: <code>"payload":"${OUTPUTS/1/ENERGY_START}"</code> is output payload <code>1567654639</code>

==== ENERGY_START_FMT ====
Date when the counters ENERGY and REVERSE_ENERGY have been resetted by user.

Unit: <code>fmt date format</code>

Type: string

Allowed in: <code>"payload"</code>

Example 1: <code>"payload":"Energy measured since ${OUTPUTS/1/ENERGY_START}"</code>

Example 2: <code>"payload":"${OUTPUTS/1/ENERGY_START_FMT}"</code> is output payload <code>2019-09-05T03:37:19+00:00</code>

==== ENERGY_NR ====
Non-resettable counter of Energy consumed by an device connected to NETIO device output.

Unit: <code>Wh</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Consumed energy on output 1 is ${OUTPUTS/1/ENERGY_NR}Wh"</code>

Example 2: <code>"source":"${OUTPUTS/1/ENERGY_NR}"</code>

==== REVERSE_ENERGY_NR ====
Non-resettable counter of Energy delivered back to grid. For example from solar system connected to NETIO device output.

Unit: <code>Wh</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Delivered energy on output 1 is ${OUTPUTS/1/REVERSE_ENERGY_NR}Wh"</code>

Example 2: <code>"source":"${OUTPUTS/1/REVERSE_ENERGY_NR}"</code>

==== TOTALs - for 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
* OUTPUTS/TOTAL/PHASE
* OUTPUTS/TOTAL/REVERSE_ENERGY
* OUTPUTS/TOTAL/ENERGY_NR
* OUTPUTS/TOTAL/REVERSE_ENERGY_NR
* OUTPUTS/TOTAL/ENERGY_START
* OUTPUTS/TOTAL/ENERGY_START_FMT

==== REST_JSON ====
Allow use of NETIO JSON structure to control outputs.

Type: string / JSON

Allowed in: <code>"target"</code> for Subscribe section

Example: <code>"target": "REST_JSON"</code>

The payload is JSON structure identical to NETIO JSON API M2M Protocol (documentation available at https://www.netio-products.com/files/NETIO-M2M-API-Protocol-JSON.pdf). You can control one or multiple outputs.

Payload example 1 - Toggle output 1: <code>{"Outputs":[{"ID": 1,"Action": 4}]}</code>

Payload example 2 - Turn output 1 OFF and output 3 ON: <code>{"Outputs":[{"ID":1,"Action":0},{"ID":3,"Action":1}]}</code>

=== INPUT variables ===
==== STATE ====
Type: bool(integer) - <code>0</code> or <code>1</code>

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Present input 1 state is ${INPUTS/1/STATE}"</code>

Example 2: <code>"source":"${INPUTS/1/STATE}"</code>

==== S0 ====
S0 Counter value
Unit: <code>-</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Input 1 S0 Counter value is ${INPUTS/1/S0}impulses"</code>

Example 2: <code>"source":"${INPUTS/1/S0}"</code>

== Payload/topic variables ==

=== DEVICE_NAME ===
Can be used in: "payload", "topic"

Example 1: <code>"payload":"${DEVICE_NAME}"</code>

Example 2: <code>"topic":"netio/${DEVICE_NAME}/output/1/action"</code>

=== DEVICE_MAC ===

=== UPTIME Not yet implemented ===

=== PAYLOAD ===
Can be used in: "action"

Example: <code>"action":"${PAYLOAD}"</code>

=== OUTPUT_ID Not yet implemented===

=== WIFI_SIGNALNot yet implemented ===

=== OUTPUTS_STATUS ===
Provide complete outputs status and measurement if supported.

Type: string / JSON

Allowed in: <code>"payload"</code> for Publish section

Example: <code>"payload":"${OUTPUTS_STATUS}"</code>

Payload example: <code>{ "GlobalMeasure":{"Voltage":236,"TotalCurrent":72,"TotalLoad":11,"TotalEnergy":167,"OverallPowerFactor":0.64,"Frequency":50.07,"Phase":-36.86,"EnergyStart":"2020-06-30T17:04:48+01:00"}, "Outputs":[ {"ID":1,"Name":"Power output 1","State":1,"Action":6,"Delay":2020,"Current":72,"PowerFactor":0.64,"Phase":-36.86,"Energy":139,"ReverseEnergy":0,"Load":11}, {"ID":2,"Name":"Power output 2","State":1,"Action":6,"Delay":2020,"Current":0,"PowerFactor":1.00,"Phase":0.00,"Energy":27,"ReverseEnergy":0,"Load":0}, {"ID":3,"Name":"Free Contact 3","State":1,"Action":6,"Delay":2020}, {"ID":4,"Name":"Free Contact 4","State":1,"Action":6,"Delay":2020} ]}</code>

=== INPUTS_STATUS ===
Provide complete inputs status if supported. Since FW 3.0.0

Type: string / JSON

Allowed in: <code>"payload"</code> for Publish section

Example: <code>"payload":"${INPUTS_STATUS}"</code>

Payload example: <code>{ "Inputs":[ {"ID":1,"Name":"Input 1","State":0,"S0Counter":0}, {"ID":2,"Name":"Input 2","State":0,"S0Counter":0} ]}</code>

=== INOUT_STATUS ===
Provide complete inputs and output status and measurement if supported. Since FW 3.0.0

Type: string / JSON

Allowed in: <code>"payload"</code> for Publish section

Example: <code>"payload":"${INOUT_STATUS}"</code>

Payload example: <code>{ "GlobalMeasure":{"Voltage":238,"TotalCurrent":105,"TotalLoad":17,"TotalEnergy":1451,"OverallPowerFactor":0.67,"Frequency":50.03,"Phase":-33.67,"EnergyStart":"2020-06-30T17:04:48+01:00"}, "Outputs":[ {"ID":1,"Name":"Power output 1","State":0,"Action":6,"Delay":5000,"Current":0,"PowerFactor":1.00,"Phase":0.00,"Energy":701,"ReverseEnergy":0,"Load":0}, {"ID":2,"Name":"Power output 2","State":1,"Action":6,"Delay":5000,"Current":105,"PowerFactor":0.65,"Phase":-33.67,"Energy":750,"ReverseEnergy":0,"Load":17}, {"ID":3,"Name":"Free Contact 3","State":1,"Action":6,"Delay":5000}, {"ID":4,"Name":"Free Contact 4","State":0,"Action":6,"Delay":5000} ], "Inputs":[ {"ID":1,"Name":"Input 1","State":0,"S0Counter":0}, {"ID":2,"Name":"Input 2","State":0,"S0Counter":0} ]}</code>

= Extended MQTT flex JSON config examples =

== Default NETIO MQTT-flex configuration ==
This example demonstrates setup for connection to public <code>broker.hivemq.com</code>, measurement reporting and output control.

The device cabe be controlled via <code>netio/${DEVICE_NAME}/output/1/action topic</code> by sending standard NETIO action values:
* 0 - OFF
* 1 - ON
* 2 - SHORT OFF
* 3 - SHORT ON
* 4 - TOGGLE
* 5 - NO ACTION.

The device report measurements:

* Output state - every 15 minutes or by change
* Voltage [V]- every 5 minutes or by change of 1 V
* Current [mA]- every 5 minutes or by change of 50 mA
* Load(Power) [W]- every 5 minutes or by change of 10 W
* Energy(Consumption) [Wh]- every 15 minutes or by change of 1Wh
* True Power Factor (TPF) [-]- every 5 minutes or by change of 0.02
* Frequency [Hz]- every 1 hour or by change of 0.1 Hz

For register all values, you can use wildcard <code>netio/${DEVICE_NAME}/output/1/#</code>

{
"config":{
"broker":{
"url":"broker.hivemq.com",
"protocol":"mqtt",
"port":1883,
"ssl":false,
"type":"generic",
"username":"",
"password":"",
"clientid":"moje${DEVICE_NAME}${DEVICE_MAC}",
"keepalive":30
},
"subscribe":[
{
"topic":"netio/${DEVICE_NAME}/output/1/action",
"qos":0,
"target":"OUTPUTS/1/ACTION",
"action":"${payload}"
},
{
"topic":"netio/${DEVICE_NAME}/output/1/switch",
"qos":0,
"target":"OUTPUTS/1/ACTION",
"action":4
}
],
"publish":[
{
"topic":"netio/${DEVICE_MAC}/output/1/state",
"qos":0,
"retain":true,
"payload":"${OUTPUTS/1/STATE}",
"events":[
{
"type":"change",
"source":"OUTPUTS/1/STATE"
},
{
"type":"timer",
"period":900
}
]
},
{
"topic":"netio/${DEVICE_NAME}/output/1/voltage",
"qos":0,
"retain":false,
"payload":"${OUTPUTS/1/VOLTAGE}",
"events":[
{
"type":"timer",
"period":300
},
{
"type":"delta",
"source":"OUTPUTS/1/VOLTAGE",
"delta":1
}
]
},
{
"topic":"netio/${DEVICE_NAME}/output/1/current",
"qos":0,
"retain":false,
"payload":"${OUTPUTS/1/CURRENT}",
"events":[
{
"type":"timer",
"period":300
},
{
"type":"delta",
"source":"OUTPUTS/1/CURRENT",
"delta":50
}
]
},
{
"topic":"netio/${DEVICE_NAME}/output/1/load",
"qos":0,
"retain":false,
"payload":"${OUTPUTS/1/LOAD}",
"events":[
{
"type":"timer",
"period":300
},
{
"type":"delta",
"source":"OUTPUTS/1/LOAD",
"delta":10
}
]
},
{
"topic":"netio/${DEVICE_NAME}/output/1/energy",
"qos":0,
"retain":false,
"payload":"${OUTPUTS/1/ENERGY}",
"events":[
{
"type":"timer",
"period":900
},
{
"type":"delta",
"source":"OUTPUTS/1/ENERGY",
"delta":1
}
]
},
{
"topic":"netio/${DEVICE_NAME}/output/1/tpf",
"qos":0,
"retain":false,
"payload":"${OUTPUTS/1/POWER_FACTOR}",
"events":[
{
"type":"timer",
"period":900
},
{
"type":"delta",
"source":"OUTPUTS/1/POWER_FACTOR",
"delta":0.02
}
]
},
{
"topic":"netio/${DEVICE_NAME}/output/1/frequency",
"qos":0,
"retain":false,
"payload":"${OUTPUTS/1/FREQUENCY}",
"events":[
{
"type":"timer",
"period":3600
},
{
"type":"delta",
"source":"OUTPUTS/1/FREQUENCY",
"delta":0.1
}
]
}
]
}
}

MQTT-flex

2023-06-05T21:34:01Z

Bbakala: /* Target Source Variables */

The MQTT-flex version of the MQTT protocol can be configured in detail thanks to the “flex” extension.

https://www.netio-products.com/en/glossary/mqtt-flex

Why MQTT-flex 
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 [https://en.wikipedia.org/wiki/MQTT 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 [https://en.wikipedia.org/wiki/JSON 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 101x 
* PowerCable REST 101x 
* PowerPDU 4PS 
* PowerPDU 4KS 
* PowerPDU 8QS 
* PowerDIN 4PZ 
* PowerBOX 3Px 
* PowerBOX 4Kx 

FW version: 
>2.2.1

===Not supported NETIO devices:===
* PowerPDU 4C 
* NETIO 4 
* NETIO 4All 

= Simple MQTT-flex configuration + explanation =

''We strongly recommend to create and test MQTT-flex configuration on "local" device what can be easily restarted. The validation of config before saving is not 100% and for example some specific typos can cause a freeze of a device - the solution is to restart a device (unplug/plug input power cable). If the configuration is saved and device is working then there are no known failure case so it is safe to use this configuration on the "remote" devices.''

{
"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":false,
"payload":"${OUTPUTS/1/STATE}",
"events":[
{
"type":"timer",
"period":"1000"
}
]
}
]
}
}
=== Client Configuration (broker section) ===
Put here MQTT client connection setup

This configuration example set NETIO device to connect to broker.hivemq.com with mqtt protocol, no ssl connection with credetials freedom/peace|love|empathy4ALL.

"broker":{
"url":"broker.hivemq.com",
"protocol":"mqtt",
"port":1883,
"ssl":false,
"type":"generic",
"username":"freedom",
"password":"peace|LOVE|empathy4ALL"
},

=== Device Control (subscribe section) ===
Put here array of topics where to subscribe

Device output 1 is controlled with action received by subscription to netio/${DEVICE_NAME}/output/1/action topic with QOS 0

"subscribe":[{
"topic":"netio/${DEVICE_NAME}/output/1/action",
"qos":0,
"target":"OUTPUTS/1/ACTION",
"action":"${payload}"
}
],

=== Output State monitoring (publish section) ===
Put here array of topics where to publish.

Device send every 1000 s message to topic with QOS 0, retain true information with output 1 state

"publish":[{
"topic":"netio/${DEVICE_NAME}/output/1/state",
"qos":0,
"retain":true,
"payload":"${OUTPUTS/1/STATE}",
"events":[
{
"type":"timer",
"period":"1000"
}
]
}
]

= 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 ===
{| class="wikitable"
! style="font-weight:bold; background-color:#9b9b9b;" | Item
! style="font-weight:bold; background-color:#9b9b9b;" | Presence
! style="font-weight:bold; background-color:#9b9b9b;" | Possible Values
! style="font-weight:bold; background-color:#9b9b9b;" | Description
! style="font-weight:bold; background-color:#9b9b9b;" | JSON Config Usage
|-
| style="background-color:#efefef;" | url
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" |
| style="background-color:#efefef;" | MQTT broker URL
| style="background-color:#efefef;" | "url":"broker.hivemq.com"
|-
| style="background-color:#efefef;" | port
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | 1 - 65535
| style="background-color:#efefef;" | MQTT broker port
| style="background-color:#efefef;" | "port":1883
|-
| style="background-color:#efefef;" | protocol
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" |
| style="background-color:#efefef;" | protocol spec - mqtt
| style="background-color:#efefef;" | "protocol": "mqtt"
|-
| style="background-color:#efefef;" | ssl
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | true, false
| style="background-color:#efefef;" | Use SSL crypted communication selector
| style="background-color:#efefef;" | "ssl":false
|-
| style="background-color:#efefef;" | type
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | generic
| style="background-color:#efefef;" | Communication/setup type option
| style="background-color:#efefef;" | "type":"generic"
|-
| style="background-color:#efefef;" | username
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | regexp+len
| style="background-color:#efefef;" | Credentials for MQTT broker. Max. 128 characters (since FW 3.2.4).
| style="background-color:#efefef;" | "username":"freedom"
|-
| style="background-color:#efefef;" | password
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | regexp+len
| style="background-color:#efefef;" | Credentials for MQTT broker. Max. 256 characters (since FW 3.2.4).
| style="background-color:#efefef;" | "password":"peace|LOVE|empathy4ALL"
|-
| style="background-color:#efefef;" | clientid
| style="background-color:#efefef;" | optional
| style="background-color:#efefef;" | regexp+len
| style="background-color:#efefef;" | MQTT clientid. Max. 128 characters (since FW 3.2.4). Variables ${DEVICE_MAC} or ${DEVICE_NAME} can be used
| style="background-color:#efefef;" | "clientid":"myEcoTable01"
|-
| style="background-color:#efefef;" | keepalive
| style="background-color:#efefef;" | optional
| style="background-color:#efefef;" | 1 - 65535
| style="background-color:#efefef;" | MQTT keep alive period in seconds
| style="background-color:#efefef;" | "keepalive":90
|}

Note 1: clientid attribute is mandatory for MQTT(s) communication. When not configured, random ID will be generated.

Note 2: To proper communication with MS Azure - it is necessary to set up IoT Hub to use TLS 1.2

See section "TLS 1.2 enforcement available in select regions" in following guidelines https://docs.microsoft.com/en-us/azure/iot-hub/iot-hub-tls-support

=== Examples ===
==== Standard setup ====

==== Security (SSL / TLS) secured setup ====
You can enable MQTTs by using the encrypted port 8883 + "ssl":true.

==== Variables used setup ====

== 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 ===
{| class="wikitable"
! style="font-weight:bold; background-color:#9b9b9b;" | Item
! style="font-weight:bold; background-color:#9b9b9b;" | Presence
! style="font-weight:bold; background-color:#9b9b9b;" | Possible Values
! style="font-weight:bold; background-color:#9b9b9b;" | Description
! style="font-weight:bold; background-color:#9b9b9b;" | JSON Config Usage
|-
| style="background-color:#efefef;" | topic
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | see table below
| style="background-color:#efefef;" | specification of the topic, which MQTT-flex device listens from broker and act accordingly. Max. 128 characters. The "#" can be used since FW 3.2.4 - see note under this table.
| style="background-color:#efefef;" | "topic":"netio/${DEVICE_NAME}/output/1/action"
|-
| style="background-color:#efefef;" | qos
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | 0, 1 or 2
| style="background-color:#efefef;" | 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}
| style="background-color:#efefef;" | "qos":0
|-
| style="background-color:#efefef;" | target
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" |
| style="background-color:#efefef;" | internal definition of action, which can be performed above the specified output
| style="background-color:#efefef;" | "target":"OUTPUTS/1/ACTION"
|-
| style="background-color:#efefef;" | action
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" |
| style="background-color:#efefef;" | a payload or a value the action attribute needs to have passed to
| style="background-color:#efefef;" | "action":"${payload}"
|-
| style="background-color:#efefef;" | actiondefNot supported yet
| style="background-color:#efefef;" | optional
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
|-
| style="background-color:#efefef;" | jsonNot supported yet
| style="background-color:#efefef;" | optional
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
|}

Note: The "#" wildcard can be used in subscribe topic definition. The multi-level wildcard character MUST be specified either on its own or following a topic level separator. In either case it MUST be the last character specified in the Topic.

For example, if a Device subscribes to “devices/{device_id}/messages/devicebound/#”, it would receive messages published using these topic names:

“devices/{device_id}/messages/devicebound/”

“devices/{device_id}/messages/devicebound/{property_bag}”

This should be usefull for use with MS Azure - IoT hub.

=== Examples ===
==== Toggle output with standard payload ====
==== Toggle output with custom payload ====
==== Subscribe to more than one topic ====

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 ===
{| class="wikitable"
! style="font-weight:bold; background-color:#9b9b9b;" | Item
! style="font-weight:bold; background-color:#9b9b9b;" | Presence
! style="font-weight:bold; background-color:#9b9b9b;" | Possible Values
! style="font-weight:bold; background-color:#9b9b9b;" | Description
! style="font-weight:bold; background-color:#9b9b9b;" | JSON Config Usage
|-
| style="background-color:#efefef;" | topic
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | see table below
| style="background-color:#efefef;" | definition of the topic, how it is registered towards MQTT broker. Max. 128 characters.
| style="background-color:#efefef;" | "topic":"netio/${DEVICE_NAME}/output/1/load"
|-
| style="background-color:#efefef;" | qos
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | see table below
| style="background-color:#efefef;" | 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}
| style="background-color:#efefef;" |
|-
| style="background-color:#efefef;" | retain
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | boolean: true or false
| style="background-color:#efefef;" | 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}
| style="background-color:#efefef;" | "retain":true
|-
| style="background-color:#efefef;" | payload
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | see table below
| style="background-color:#efefef;" | definition of the payload, what is send to the MQTT broker.
| style="background-color:#efefef;" | "payload":"${OUTPUTS/1/STATE}"
|-
| style="background-color:#efefef;" | events
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | see table below
| style="background-color:#efefef;" | definition of events used for triggering sending of data via mqtt (change, delta, timer)
| style="background-color:#efefef;" |
|-
| style="background-color:#efefef;" | type
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
|-
| style="background-color:#efefef;" | source
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
|-
| style="background-color:#efefef;" | delta
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
|-
| style="background-color:#efefef;" | period
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
|-
| style="background-color:#efefef;" | payloaddefNot supported yet
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
|}

=== Examples ===
==== Publish energy periodically (event timer) ====
==== Publish current on change (delta) ====
==== Publish output state ====
==== Publish to more than one topic with different events ====

= 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 available only on NETIO PowerDIN 4PZ

=== Examples: ===

adressing controll of output 3
OUTPUTS/3/ACTION
getting voltage on output 1
OUTPUTS/1/VOLTAGE
getting state of input 1
INPUTS/1/STATE

= 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 ===
==== VOLTAGE ====
Unit: <code>V</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Present RMS voltage on output 1 is ${OUTPUTS/1/VOLTAGE}"</code>

Example 2: <code>"source":"${OUTPUTS/1/VOLTAGE}"</code>

==== CURRENT ====
Unit: <code>mA</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Present RMS current on output 1 is ${OUTPUTS/1/CURRENT}"</code>

Example 2: <code>"source":"${OUTPUTS/1/CURRENT}"</code>

==== POWER_FACTOR ====
Unit: <code>[-]</code>

Type: float (2 decimals)

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"True Power Factor on output 1 is ${OUTPUTS/1/POWER_FACTOR}"</code>

Example 2: <code>"source":"${OUTPUTS/1/POWER_FACTOR}"</code>

==== LOAD ====
Unit: <code>W</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Present load on output 1 is ${OUTPUTS/1/LOAD}W"</code>

Example 2: <code>"payload":"Device's load connected to output 1 is ${OUTPUTS/1/LOAD}W"</code>

Example 3: <code>"source":"${OUTPUTS/1/LOAD}"</code>

==== STATE ====
Type: bool(integer) - <code>0</code> or <code>1</code>

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Present output 1 state is ${OUTPUTS/1/STATE}"</code>

Example 2: <code>"source":"${OUTPUTS/1/STATE}"</code>

==== ACTION ====
Type: integer

Possible actions:
* <code>0</code> - set state OFF
* <code>1</code> - set state ON
* <code>2</code> - short OFF (restart)
* <code>3</code> - short ON
* <code>4</code> - toggle (switch)
* <code>5</code> - no change

Allowed in: <code>"target"</code>

Example: <code>"target":"OUTPUTS/1/ACTION"</code>

==== DELAY [ms] ====
==== NAME ====
==== FREQUENCY ====
Unit: <code>Hz</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example: <code>"payload":"Frequency in power grid is ${OUTPUTS/1/ENERGY}Hz"</code>

==== ENERGY ====
Energy consumed by an device connected to NETIO device output.

Unit: <code>Wh</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Consumed energy on output 1 is ${OUTPUTS/1/ENERGY}Wh"</code>

Example 2: <code>"source":"${OUTPUTS/1/ENERGY}"</code>

==== REVERSE_ENERGY ====
Energy delivered back to grid. For example from solar system connected to NETIO device output.

Unit: <code>Wh</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Delivered energy on output 1 is ${OUTPUTS/1/REVERSE_ENERGY}Wh"</code>

Example 2: <code>"source":"${OUTPUTS/1/REVERSE_ENERGY}"</code>

==== ENERGY_START ====
Date when the counters ENERGY and REVERSE_ENERGY have been resetted by user.

Unit: <code>unix timestamp</code>

Type: integer

Allowed in: <code>"payload"</code>

Example 1: <code>"payload":"Energy measured since ${OUTPUTS/1/ENERGY_START} unix time"</code>

Example 2: <code>"payload":"${OUTPUTS/1/ENERGY_START}"</code> is output payload <code>1567654639</code>

==== ENERGY_START_FMT ====
Date when the counters ENERGY and REVERSE_ENERGY have been resetted by user.

Unit: <code>fmt date format</code>

Type: string

Allowed in: <code>"payload"</code>

Example 1: <code>"payload":"Energy measured since ${OUTPUTS/1/ENERGY_START}"</code>

Example 2: <code>"payload":"${OUTPUTS/1/ENERGY_START_FMT}"</code> is output payload <code>2019-09-05T03:37:19+00:00</code>

==== ENERGY_NR ====
Non-resettable counter of Energy consumed by an device connected to NETIO device output.

Unit: <code>Wh</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Consumed energy on output 1 is ${OUTPUTS/1/ENERGY_NR}Wh"</code>

Example 2: <code>"source":"${OUTPUTS/1/ENERGY_NR}"</code>

==== REVERSE_ENERGY_NR ====
Non-resettable counter of Energy delivered back to grid. For example from solar system connected to NETIO device output.

Unit: <code>Wh</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Delivered energy on output 1 is ${OUTPUTS/1/REVERSE_ENERGY_NR}Wh"</code>

Example 2: <code>"source":"${OUTPUTS/1/REVERSE_ENERGY_NR}"</code>

==== TOTALs - for 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
* OUTPUTS/TOTAL/PHASE
* OUTPUTS/TOTAL/REVERSE_ENERGY
* OUTPUTS/TOTAL/ENERGY_NR
* OUTPUTS/TOTAL/REVERSE_ENERGY_NR
* OUTPUTS/TOTAL/ENERGY_START
* OUTPUTS/TOTAL/ENERGY_START_FMT

==== REST_JSON ====
Allow use of NETIO JSON structure to control outputs.

Type: string / JSON

Allowed in: <code>"target"</code> for Subscribe section

Example: <code>"target": "REST_JSON"</code>

The payload is JSON structure identical to NETIO JSON API M2M Protocol (documentation available at https://www.netio-products.com/files/NETIO-M2M-API-Protocol-JSON.pdf). You can control one or multiple outputs.

Payload example 1 - Toggle output 1: <code>{"Outputs":[{"ID": 1,"Action": 4}]}</code>

Payload example 2 - Turn output 1 OFF and output 3 ON: <code>{"Outputs":[{"ID":1,"Action":0},{"ID":3,"Action":1}]}</code>

=== INPUT variables ===
==== STATE ====
Type: bool(integer) - <code>0</code> or <code>1</code>

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Present input 1 state is ${INPUTS/1/STATE}"</code>

Example 2: <code>"source":"${INPUTS/1/STATE}"</code>

==== S0 ====
S0 Counter value
Unit: <code>-</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Input 1 S0 Counter value is ${INPUTS/1/S0}impulses"</code>

Example 2: <code>"source":"${INPUTS/1/S0}"</code>

== Payload/topic variables ==

=== DEVICE_NAME ===
Can be used in: "payload", "topic"

Example 1: <code>"payload":"${DEVICE_NAME}"</code>

Example 2: <code>"topic":"netio/${DEVICE_NAME}/output/1/action"</code>

=== DEVICE_MAC ===

=== UPTIME Not yet implemented ===

=== PAYLOAD ===
Can be used in: "action"

Example: <code>"action":"${PAYLOAD}"</code>

=== OUTPUT_ID Not yet implemented===

=== WIFI_SIGNALNot yet implemented ===

=== OUTPUTS_STATUS ===
Provide complete outputs status and measurement if supported.

Type: string / JSON

Allowed in: <code>"payload"</code> for Publish section

Example: <code>"payload":"${OUTPUTS_STATUS}"</code>

Payload example: <code>{ "GlobalMeasure":{"Voltage":236,"TotalCurrent":72,"TotalLoad":11,"TotalEnergy":167,"OverallPowerFactor":0.64,"Frequency":50.07,"Phase":-36.86,"EnergyStart":"2020-06-30T17:04:48+01:00"}, "Outputs":[ {"ID":1,"Name":"Power output 1","State":1,"Action":6,"Delay":2020,"Current":72,"PowerFactor":0.64,"Phase":-36.86,"Energy":139,"ReverseEnergy":0,"Load":11}, {"ID":2,"Name":"Power output 2","State":1,"Action":6,"Delay":2020,"Current":0,"PowerFactor":1.00,"Phase":0.00,"Energy":27,"ReverseEnergy":0,"Load":0}, {"ID":3,"Name":"Free Contact 3","State":1,"Action":6,"Delay":2020}, {"ID":4,"Name":"Free Contact 4","State":1,"Action":6,"Delay":2020} ]}</code>

=== INPUTS_STATUS ===
Provide complete inputs status if supported. Since FW 3.0.0

Type: string / JSON

Allowed in: <code>"payload"</code> for Publish section

Example: <code>"payload":"${INPUTS_STATUS}"</code>

Payload example: <code>{ "Inputs":[ {"ID":1,"Name":"Input 1","State":0,"S0Counter":0}, {"ID":2,"Name":"Input 2","State":0,"S0Counter":0} ]}</code>

=== INOUT_STATUS ===
Provide complete inputs and output status and measurement if supported. Since FW 3.0.0

Type: string / JSON

Allowed in: <code>"payload"</code> for Publish section

Example: <code>"payload":"${INOUT_STATUS}"</code>

Payload example: <code>{ "GlobalMeasure":{"Voltage":238,"TotalCurrent":105,"TotalLoad":17,"TotalEnergy":1451,"OverallPowerFactor":0.67,"Frequency":50.03,"Phase":-33.67,"EnergyStart":"2020-06-30T17:04:48+01:00"}, "Outputs":[ {"ID":1,"Name":"Power output 1","State":0,"Action":6,"Delay":5000,"Current":0,"PowerFactor":1.00,"Phase":0.00,"Energy":701,"ReverseEnergy":0,"Load":0}, {"ID":2,"Name":"Power output 2","State":1,"Action":6,"Delay":5000,"Current":105,"PowerFactor":0.65,"Phase":-33.67,"Energy":750,"ReverseEnergy":0,"Load":17}, {"ID":3,"Name":"Free Contact 3","State":1,"Action":6,"Delay":5000}, {"ID":4,"Name":"Free Contact 4","State":0,"Action":6,"Delay":5000} ], "Inputs":[ {"ID":1,"Name":"Input 1","State":0,"S0Counter":0}, {"ID":2,"Name":"Input 2","State":0,"S0Counter":0} ]}</code>

= Extended MQTT flex JSON config examples =

== Default NETIO MQTT-flex configuration ==
This example demonstrates setup for connection to public <code>broker.hivemq.com</code>, measurement reporting and output control.

The device cabe be controlled via <code>netio/${DEVICE_NAME}/output/1/action topic</code> by sending standard NETIO action values:
* 0 - OFF
* 1 - ON
* 2 - SHORT OFF
* 3 - SHORT ON
* 4 - TOGGLE
* 5 - NO ACTION.

The device report measurements:

* Output state - every 15 minutes or by change
* Voltage [V]- every 5 minutes or by change of 1 V
* Current [mA]- every 5 minutes or by change of 50 mA
* Load(Power) [W]- every 5 minutes or by change of 10 W
* Energy(Consumption) [Wh]- every 15 minutes or by change of 1Wh
* True Power Factor (TPF) [-]- every 5 minutes or by change of 0.02
* Frequency [Hz]- every 1 hour or by change of 0.1 Hz

For register all values, you can use wildcard <code>netio/${DEVICE_NAME}/output/1/#</code>

{
"config":{
"broker":{
"url":"broker.hivemq.com",
"protocol":"mqtt",
"port":1883,
"ssl":false,
"type":"generic",
"username":"",
"password":"",
"clientid":"moje${DEVICE_NAME}${DEVICE_MAC}",
"keepalive":30
},
"subscribe":[
{
"topic":"netio/${DEVICE_NAME}/output/1/action",
"qos":0,
"target":"OUTPUTS/1/ACTION",
"action":"${payload}"
},
{
"topic":"netio/${DEVICE_NAME}/output/1/switch",
"qos":0,
"target":"OUTPUTS/1/ACTION",
"action":4
}
],
"publish":[
{
"topic":"netio/${DEVICE_MAC}/output/1/state",
"qos":0,
"retain":true,
"payload":"${OUTPUTS/1/STATE}",
"events":[
{
"type":"change",
"source":"OUTPUTS/1/STATE"
},
{
"type":"timer",
"period":900
}
]
},
{
"topic":"netio/${DEVICE_NAME}/output/1/voltage",
"qos":0,
"retain":false,
"payload":"${OUTPUTS/1/VOLTAGE}",
"events":[
{
"type":"timer",
"period":300
},
{
"type":"delta",
"source":"OUTPUTS/1/VOLTAGE",
"delta":1
}
]
},
{
"topic":"netio/${DEVICE_NAME}/output/1/current",
"qos":0,
"retain":false,
"payload":"${OUTPUTS/1/CURRENT}",
"events":[
{
"type":"timer",
"period":300
},
{
"type":"delta",
"source":"OUTPUTS/1/CURRENT",
"delta":50
}
]
},
{
"topic":"netio/${DEVICE_NAME}/output/1/load",
"qos":0,
"retain":false,
"payload":"${OUTPUTS/1/LOAD}",
"events":[
{
"type":"timer",
"period":300
},
{
"type":"delta",
"source":"OUTPUTS/1/LOAD",
"delta":10
}
]
},
{
"topic":"netio/${DEVICE_NAME}/output/1/energy",
"qos":0,
"retain":false,
"payload":"${OUTPUTS/1/ENERGY}",
"events":[
{
"type":"timer",
"period":900
},
{
"type":"delta",
"source":"OUTPUTS/1/ENERGY",
"delta":1
}
]
},
{
"topic":"netio/${DEVICE_NAME}/output/1/tpf",
"qos":0,
"retain":false,
"payload":"${OUTPUTS/1/POWER_FACTOR}",
"events":[
{
"type":"timer",
"period":900
},
{
"type":"delta",
"source":"OUTPUTS/1/POWER_FACTOR",
"delta":0.02
}
]
},
{
"topic":"netio/${DEVICE_NAME}/output/1/frequency",
"qos":0,
"retain":false,
"payload":"${OUTPUTS/1/FREQUENCY}",
"events":[
{
"type":"timer",
"period":3600
},
{
"type":"delta",
"source":"OUTPUTS/1/FREQUENCY",
"delta":0.1
}
]
}
]
}
}

MQTT-flex

2023-06-05T20:58:31Z

Bbakala: /* PROTOCOLS/MQTT/CONNECTEDFW 4.0.0+ */

The MQTT-flex version of the MQTT protocol can be configured in detail thanks to the “flex” extension.

https://www.netio-products.com/en/glossary/mqtt-flex

Why MQTT-flex 
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 [https://en.wikipedia.org/wiki/MQTT 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 [https://en.wikipedia.org/wiki/JSON 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 101x 
* PowerCable REST 101x 
* PowerPDU 4PS 
* PowerPDU 4KS 
* PowerPDU 8QS 
* PowerDIN 4PZ 
* PowerBOX 3Px 
* PowerBOX 4Kx 

FW version: 
>2.2.1

===Not supported NETIO devices:===
* PowerPDU 4C 
* NETIO 4 
* NETIO 4All 

= Simple MQTT-flex configuration + explanation =

''We strongly recommend to create and test MQTT-flex configuration on "local" device what can be easily restarted. The validation of config before saving is not 100% and for example some specific typos can cause a freeze of a device - the solution is to restart a device (unplug/plug input power cable). If the configuration is saved and device is working then there are no known failure case so it is safe to use this configuration on the "remote" devices.''

{
"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":false,
"payload":"${OUTPUTS/1/STATE}",
"events":[
{
"type":"timer",
"period":"1000"
}
]
}
]
}
}
=== Client Configuration (broker section) ===
Put here MQTT client connection setup

This configuration example set NETIO device to connect to broker.hivemq.com with mqtt protocol, no ssl connection with credetials freedom/peace|love|empathy4ALL.

"broker":{
"url":"broker.hivemq.com",
"protocol":"mqtt",
"port":1883,
"ssl":false,
"type":"generic",
"username":"freedom",
"password":"peace|LOVE|empathy4ALL"
},

=== Device Control (subscribe section) ===
Put here array of topics where to subscribe

Device output 1 is controlled with action received by subscription to netio/${DEVICE_NAME}/output/1/action topic with QOS 0

"subscribe":[{
"topic":"netio/${DEVICE_NAME}/output/1/action",
"qos":0,
"target":"OUTPUTS/1/ACTION",
"action":"${payload}"
}
],

=== Output State monitoring (publish section) ===
Put here array of topics where to publish.

Device send every 1000 s message to topic with QOS 0, retain true information with output 1 state

"publish":[{
"topic":"netio/${DEVICE_NAME}/output/1/state",
"qos":0,
"retain":true,
"payload":"${OUTPUTS/1/STATE}",
"events":[
{
"type":"timer",
"period":"1000"
}
]
}
]

= 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 ===
{| class="wikitable"
! style="font-weight:bold; background-color:#9b9b9b;" | Item
! style="font-weight:bold; background-color:#9b9b9b;" | Presence
! style="font-weight:bold; background-color:#9b9b9b;" | Possible Values
! style="font-weight:bold; background-color:#9b9b9b;" | Description
! style="font-weight:bold; background-color:#9b9b9b;" | JSON Config Usage
|-
| style="background-color:#efefef;" | url
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" |
| style="background-color:#efefef;" | MQTT broker URL
| style="background-color:#efefef;" | "url":"broker.hivemq.com"
|-
| style="background-color:#efefef;" | port
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | 1 - 65535
| style="background-color:#efefef;" | MQTT broker port
| style="background-color:#efefef;" | "port":1883
|-
| style="background-color:#efefef;" | protocol
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" |
| style="background-color:#efefef;" | protocol spec - mqtt
| style="background-color:#efefef;" | "protocol": "mqtt"
|-
| style="background-color:#efefef;" | ssl
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | true, false
| style="background-color:#efefef;" | Use SSL crypted communication selector
| style="background-color:#efefef;" | "ssl":false
|-
| style="background-color:#efefef;" | type
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | generic
| style="background-color:#efefef;" | Communication/setup type option
| style="background-color:#efefef;" | "type":"generic"
|-
| style="background-color:#efefef;" | username
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | regexp+len
| style="background-color:#efefef;" | Credentials for MQTT broker. Max. 128 characters (since FW 3.2.4).
| style="background-color:#efefef;" | "username":"freedom"
|-
| style="background-color:#efefef;" | password
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | regexp+len
| style="background-color:#efefef;" | Credentials for MQTT broker. Max. 256 characters (since FW 3.2.4).
| style="background-color:#efefef;" | "password":"peace|LOVE|empathy4ALL"
|-
| style="background-color:#efefef;" | clientid
| style="background-color:#efefef;" | optional
| style="background-color:#efefef;" | regexp+len
| style="background-color:#efefef;" | MQTT clientid. Max. 128 characters (since FW 3.2.4). Variables ${DEVICE_MAC} or ${DEVICE_NAME} can be used
| style="background-color:#efefef;" | "clientid":"myEcoTable01"
|-
| style="background-color:#efefef;" | keepalive
| style="background-color:#efefef;" | optional
| style="background-color:#efefef;" | 1 - 65535
| style="background-color:#efefef;" | MQTT keep alive period in seconds
| style="background-color:#efefef;" | "keepalive":90
|}

Note 1: clientid attribute is mandatory for MQTT(s) communication. When not configured, random ID will be generated.

Note 2: To proper communication with MS Azure - it is necessary to set up IoT Hub to use TLS 1.2

See section "TLS 1.2 enforcement available in select regions" in following guidelines https://docs.microsoft.com/en-us/azure/iot-hub/iot-hub-tls-support

=== Examples ===
==== Standard setup ====

==== Security (SSL / TLS) secured setup ====
You can enable MQTTs by using the encrypted port 8883 + "ssl":true.

==== Variables used setup ====

== 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 ===
{| class="wikitable"
! style="font-weight:bold; background-color:#9b9b9b;" | Item
! style="font-weight:bold; background-color:#9b9b9b;" | Presence
! style="font-weight:bold; background-color:#9b9b9b;" | Possible Values
! style="font-weight:bold; background-color:#9b9b9b;" | Description
! style="font-weight:bold; background-color:#9b9b9b;" | JSON Config Usage
|-
| style="background-color:#efefef;" | topic
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | see table below
| style="background-color:#efefef;" | specification of the topic, which MQTT-flex device listens from broker and act accordingly. Max. 128 characters. The "#" can be used since FW 3.2.4 - see note under this table.
| style="background-color:#efefef;" | "topic":"netio/${DEVICE_NAME}/output/1/action"
|-
| style="background-color:#efefef;" | qos
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | 0, 1 or 2
| style="background-color:#efefef;" | 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}
| style="background-color:#efefef;" | "qos":0
|-
| style="background-color:#efefef;" | target
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" |
| style="background-color:#efefef;" | internal definition of action, which can be performed above the specified output
| style="background-color:#efefef;" | "target":"OUTPUTS/1/ACTION"
|-
| style="background-color:#efefef;" | action
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" |
| style="background-color:#efefef;" | a payload or a value the action attribute needs to have passed to
| style="background-color:#efefef;" | "action":"${payload}"
|-
| style="background-color:#efefef;" | actiondefNot supported yet
| style="background-color:#efefef;" | optional
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
|-
| style="background-color:#efefef;" | jsonNot supported yet
| style="background-color:#efefef;" | optional
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
|}

Note: The "#" wildcard can be used in subscribe topic definition. The multi-level wildcard character MUST be specified either on its own or following a topic level separator. In either case it MUST be the last character specified in the Topic.

For example, if a Device subscribes to “devices/{device_id}/messages/devicebound/#”, it would receive messages published using these topic names:

“devices/{device_id}/messages/devicebound/”

“devices/{device_id}/messages/devicebound/{property_bag}”

This should be usefull for use with MS Azure - IoT hub.

=== Examples ===
==== Toggle output with standard payload ====
==== Toggle output with custom payload ====
==== Subscribe to more than one topic ====

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 ===
{| class="wikitable"
! style="font-weight:bold; background-color:#9b9b9b;" | Item
! style="font-weight:bold; background-color:#9b9b9b;" | Presence
! style="font-weight:bold; background-color:#9b9b9b;" | Possible Values
! style="font-weight:bold; background-color:#9b9b9b;" | Description
! style="font-weight:bold; background-color:#9b9b9b;" | JSON Config Usage
|-
| style="background-color:#efefef;" | topic
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | see table below
| style="background-color:#efefef;" | definition of the topic, how it is registered towards MQTT broker. Max. 128 characters.
| style="background-color:#efefef;" | "topic":"netio/${DEVICE_NAME}/output/1/load"
|-
| style="background-color:#efefef;" | qos
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | see table below
| style="background-color:#efefef;" | 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}
| style="background-color:#efefef;" |
|-
| style="background-color:#efefef;" | retain
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | boolean: true or false
| style="background-color:#efefef;" | 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}
| style="background-color:#efefef;" | "retain":true
|-
| style="background-color:#efefef;" | payload
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | see table below
| style="background-color:#efefef;" | definition of the payload, what is send to the MQTT broker.
| style="background-color:#efefef;" | "payload":"${OUTPUTS/1/STATE}"
|-
| style="background-color:#efefef;" | events
| style="background-color:#efefef;" | mandatory
| style="background-color:#efefef;" | see table below
| style="background-color:#efefef;" | definition of events used for triggering sending of data via mqtt (change, delta, timer)
| style="background-color:#efefef;" |
|-
| style="background-color:#efefef;" | type
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
|-
| style="background-color:#efefef;" | source
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
|-
| style="background-color:#efefef;" | delta
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
|-
| style="background-color:#efefef;" | period
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
|-
| style="background-color:#efefef;" | payloaddefNot supported yet
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
| style="background-color:#efefef;" |
|}

=== Examples ===
==== Publish energy periodically (event timer) ====
==== Publish current on change (delta) ====
==== Publish output state ====
==== Publish to more than one topic with different events ====

= 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 available only on NETIO PowerDIN 4PZ

=== Examples: ===

adressing controll of output 3
OUTPUTS/3/ACTION
getting voltage on output 1
OUTPUTS/1/VOLTAGE
getting state of input 1
INPUTS/1/STATE

= 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 ===
==== VOLTAGE ====
Unit: <code>V</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Present RMS voltage on output 1 is ${OUTPUTS/1/VOLTAGE}"</code>

Example 2: <code>"source":"${OUTPUTS/1/VOLTAGE}"</code>

==== CURRENT ====
Unit: <code>mA</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Present RMS current on output 1 is ${OUTPUTS/1/CURRENT}"</code>

Example 2: <code>"source":"${OUTPUTS/1/CURRENT}"</code>

==== POWER_FACTOR ====
Unit: <code>[-]</code>

Type: float (2 decimals)

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"True Power Factor on output 1 is ${OUTPUTS/1/POWER_FACTOR}"</code>

Example 2: <code>"source":"${OUTPUTS/1/POWER_FACTOR}"</code>

==== LOAD ====
Unit: <code>W</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Present load on output 1 is ${OUTPUTS/1/LOAD}W"</code>

Example 2: <code>"payload":"Device's load connected to output 1 is ${OUTPUTS/1/LOAD}W"</code>

Example 3: <code>"source":"${OUTPUTS/1/LOAD}"</code>

==== STATE ====
Type: bool(integer) - <code>0</code> or <code>1</code>

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Present output 1 state is ${OUTPUTS/1/STATE}"</code>

Example 2: <code>"source":"${OUTPUTS/1/STATE}"</code>

==== ACTION ====
Type: integer

Possible actions:
* <code>0</code> - set state OFF
* <code>1</code> - set state ON
* <code>2</code> - short OFF (restart)
* <code>3</code> - short ON
* <code>4</code> - toggle (switch)
* <code>5</code> - no change

Allowed in: <code>"target"</code>

Example: <code>"target":"OUTPUTS/1/ACTION"</code>

==== DELAY [ms] ====
==== NAME ====
==== FREQUENCY ====
Unit: <code>Hz</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example: <code>"payload":"Frequency in power grid is ${OUTPUTS/1/ENERGY}Hz"</code>

==== ENERGY ====
Energy consumed by an device connected to NETIO device output.

Unit: <code>Wh</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Consumed energy on output 1 is ${OUTPUTS/1/ENERGY}Wh"</code>

Example 2: <code>"source":"${OUTPUTS/1/ENERGY}"</code>

==== REVERSE_ENERGY ====
Energy delivered back to grid. For example from solar system connected to NETIO device output.

Unit: <code>Wh</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Delivered energy on output 1 is ${OUTPUTS/1/REVERSE_ENERGY}Wh"</code>

Example 2: <code>"source":"${OUTPUTS/1/REVERSE_ENERGY}"</code>

==== ENERGY_START ====
Date when the counters ENERGY and REVERSE_ENERGY have been resetted by user.

Unit: <code>unix timestamp</code>

Type: integer

Allowed in: <code>"payload"</code>

Example 1: <code>"payload":"Energy measured since ${OUTPUTS/1/ENERGY_START} unix time"</code>

Example 2: <code>"payload":"${OUTPUTS/1/ENERGY_START}"</code> is output payload <code>1567654639</code>

==== ENERGY_START_FMT ====
Date when the counters ENERGY and REVERSE_ENERGY have been resetted by user.

Unit: <code>fmt date format</code>

Type: string

Allowed in: <code>"payload"</code>

Example 1: <code>"payload":"Energy measured since ${OUTPUTS/1/ENERGY_START}"</code>

Example 2: <code>"payload":"${OUTPUTS/1/ENERGY_START_FMT}"</code> is output payload <code>2019-09-05T03:37:19+00:00</code>

==== ENERGY_NR ====
Non-resettable counter of Energy consumed by an device connected to NETIO device output.

Unit: <code>Wh</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Consumed energy on output 1 is ${OUTPUTS/1/ENERGY_NR}Wh"</code>

Example 2: <code>"source":"${OUTPUTS/1/ENERGY_NR}"</code>

==== REVERSE_ENERGY_NR ====
Non-resettable counter of Energy delivered back to grid. For example from solar system connected to NETIO device output.

Unit: <code>Wh</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Delivered energy on output 1 is ${OUTPUTS/1/REVERSE_ENERGY_NR}Wh"</code>

Example 2: <code>"source":"${OUTPUTS/1/REVERSE_ENERGY_NR}"</code>

==== TOTALs - for 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
* OUTPUTS/TOTAL/PHASE
* OUTPUTS/TOTAL/REVERSE_ENERGY
* OUTPUTS/TOTAL/ENERGY_NR
* OUTPUTS/TOTAL/REVERSE_ENERGY_NR
* OUTPUTS/TOTAL/ENERGY_START
* OUTPUTS/TOTAL/ENERGY_START_FMT

==== REST_JSON ====
Allow use of NETIO JSON structure to control outputs.

Type: string / JSON

Allowed in: <code>"target"</code> for Subscribe section

Example: <code>"target": "REST_JSON"</code>

The payload is JSON structure identical to NETIO JSON API M2M Protocol (documentation available at https://www.netio-products.com/files/NETIO-M2M-API-Protocol-JSON.pdf). You can control one or multiple outputs.

Payload example 1 - Toggle output 1: <code>{"Outputs":[{"ID": 1,"Action": 4}]}</code>

Payload example 2 - Turn output 1 OFF and output 3 ON: <code>{"Outputs":[{"ID":1,"Action":0},{"ID":3,"Action":1}]}</code>

=== INPUT variables ===
==== STATE ====
Type: bool(integer) - <code>0</code> or <code>1</code>

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Present input 1 state is ${INPUTS/1/STATE}"</code>

Example 2: <code>"source":"${INPUTS/1/STATE}"</code>

==== S0 ====
S0 Counter value
Unit: <code>-</code>

Type: integer

Allowed in: <code>"payload"</code> <code>"source"</code>

Example 1: <code>"payload":"Input 1 S0 Counter value is ${INPUTS/1/S0}impulses"</code>

Example 2: <code>"source":"${INPUTS/1/S0}"</code>

==== PROTOCOLS/MQTT/CONNECTED<code>FW 4.0.0+</code>====
Value changes when MQTT is connected or reconnected after connection failure. Useful for system synchronization

Type: bool

Allowed in: <code>"events"</code> <code>"source"</code>

Example: Creates event when MQTT is connected

<code>
"events":[
{
"source":"PROTOCOLS/MQTT/CONNECTED",
"type":"change",
"value":true
}
]
</code>

== Payload/topic variables ==

=== DEVICE_NAME ===
Can be used in: "payload", "topic"

Example 1: <code>"payload":"${DEVICE_NAME}"</code>

Example 2: <code>"topic":"netio/${DEVICE_NAME}/output/1/action"</code>

=== DEVICE_MAC ===

=== UPTIME Not yet implemented ===

=== PAYLOAD ===
Can be used in: "action"

Example: <code>"action":"${PAYLOAD}"</code>

=== OUTPUT_ID Not yet implemented===

=== WIFI_SIGNALNot yet implemented ===

=== OUTPUTS_STATUS ===
Provide complete outputs status and measurement if supported.

Type: string / JSON

Allowed in: <code>"payload"</code> for Publish section

Example: <code>"payload":"${OUTPUTS_STATUS}"</code>

Payload example: <code>{ "GlobalMeasure":{"Voltage":236,"TotalCurrent":72,"TotalLoad":11,"TotalEnergy":167,"OverallPowerFactor":0.64,"Frequency":50.07,"Phase":-36.86,"EnergyStart":"2020-06-30T17:04:48+01:00"}, "Outputs":[ {"ID":1,"Name":"Power output 1","State":1,"Action":6,"Delay":2020,"Current":72,"PowerFactor":0.64,"Phase":-36.86,"Energy":139,"ReverseEnergy":0,"Load":11}, {"ID":2,"Name":"Power output 2","State":1,"Action":6,"Delay":2020,"Current":0,"PowerFactor":1.00,"Phase":0.00,"Energy":27,"ReverseEnergy":0,"Load":0}, {"ID":3,"Name":"Free Contact 3","State":1,"Action":6,"Delay":2020}, {"ID":4,"Name":"Free Contact 4","State":1,"Action":6,"Delay":2020} ]}</code>

=== INPUTS_STATUS ===
Provide complete inputs status if supported. Since FW 3.0.0

Type: string / JSON

Allowed in: <code>"payload"</code> for Publish section

Example: <code>"payload":"${INPUTS_STATUS}"</code>

Payload example: <code>{ "Inputs":[ {"ID":1,"Name":"Input 1","State":0,"S0Counter":0}, {"ID":2,"Name":"Input 2","State":0,"S0Counter":0} ]}</code>

=== INOUT_STATUS ===
Provide complete inputs and output status and measurement if supported. Since FW 3.0.0

Type: string / JSON

Allowed in: <code>"payload"</code> for Publish section

Example: <code>"payload":"${INOUT_STATUS}"</code>

Payload example: <code>{ "GlobalMeasure":{"Voltage":238,"TotalCurrent":105,"TotalLoad":17,"TotalEnergy":1451,"OverallPowerFactor":0.67,"Frequency":50.03,"Phase":-33.67,"EnergyStart":"2020-06-30T17:04:48+01:00"}, "Outputs":[ {"ID":1,"Name":"Power output 1","State":0,"Action":6,"Delay":5000,"Current":0,"PowerFactor":1.00,"Phase":0.00,"Energy":701,"ReverseEnergy":0,"Load":0}, {"ID":2,"Name":"Power output 2","State":1,"Action":6,"Delay":5000,"Current":105,"PowerFactor":0.65,"Phase":-33.67,"Energy":750,"ReverseEnergy":0,"Load":17}, {"ID":3,"Name":"Free Contact 3","State":1,"Action":6,"Delay":5000}, {"ID":4,"Name":"Free Contact 4","State":0,"Action":6,"Delay":5000} ], "Inputs":[ {"ID":1,"Name":"Input 1","State":0,"S0Counter":0}, {"ID":2,"Name":"Input 2","State":0,"S0Counter":0} ]}</code>

= Extended MQTT flex JSON config examples =

== Default NETIO MQTT-flex configuration ==
This example demonstrates setup for connection to public <code>broker.hivemq.com</code>, measurement reporting and output control.

The device cabe be controlled via <code>netio/${DEVICE_NAME}/output/1/action topic</code> by sending standard NETIO action values:
* 0 - OFF
* 1 - ON
* 2 - SHORT OFF
* 3 - SHORT ON
* 4 - TOGGLE
* 5 - NO ACTION.

The device report measurements:

* Output state - every 15 minutes or by change
* Voltage [V]- every 5 minutes or by change of 1 V
* Current [mA]- every 5 minutes or by change of 50 mA
* Load(Power) [W]- every 5 minutes or by change of 10 W
* Energy(Consumption) [Wh]- every 15 minutes or by change of 1Wh
* True Power Factor (TPF) [-]- every 5 minutes or by change of 0.02
* Frequency [Hz]- every 1 hour or by change of 0.1 Hz

For register all values, you can use wildcard <code>netio/${DEVICE_NAME}/output/1/#</code>

{
"config":{
"broker":{
"url":"broker.hivemq.com",
"protocol":"mqtt",
"port":1883,
"ssl":false,
"type":"generic",
"username":"",
"password":"",
"clientid":"moje${DEVICE_NAME}${DEVICE_MAC}",
"keepalive":30
},
"subscribe":[
{
"topic":"netio/${DEVICE_NAME}/output/1/action",
"qos":0,
"target":"OUTPUTS/1/ACTION",
"action":"${payload}"
},
{
"topic":"netio/${DEVICE_NAME}/output/1/switch",
"qos":0,
"target":"OUTPUTS/1/ACTION",
"action":4
}
],
"publish":[
{
"topic":"netio/${DEVICE_MAC}/output/1/state",
"qos":0,
"retain":true,
"payload":"${OUTPUTS/1/STATE}",
"events":[
{
"type":"change",
"source":"OUTPUTS/1/STATE"
},
{
"type":"timer",
"period":900
}
]
},
{
"topic":"netio/${DEVICE_NAME}/output/1/voltage",
"qos":0,
"retain":false,
"payload":"${OUTPUTS/1/VOLTAGE}",
"events":[
{
"type":"timer",
"period":300
},
{
"type":"delta",
"source":"OUTPUTS/1/VOLTAGE",
"delta":1
}
]
},
{
"topic":"netio/${DEVICE_NAME}/output/1/current",
"qos":0,
"retain":false,
"payload":"${OUTPUTS/1/CURRENT}",
"events":[
{
"type":"timer",
"period":300
},
{
"type":"delta",
"source":"OUTPUTS/1/CURRENT",
"delta":50
}
]
},
{
"topic":"netio/${DEVICE_NAME}/output/1/load",
"qos":0,
"retain":false,
"payload":"${OUTPUTS/1/LOAD}",
"events":[
{
"type":"timer",
"period":300
},
{
"type":"delta",
"source":"OUTPUTS/1/LOAD",
"delta":10
}
]
},
{
"topic":"netio/${DEVICE_NAME}/output/1/energy",
"qos":0,
"retain":false,
"payload":"${OUTPUTS/1/ENERGY}",
"events":[
{
"type":"timer",
"period":900
},
{
"type":"delta",
"source":"OUTPUTS/1/ENERGY",
"delta":1
}
]
},
{
"topic":"netio/${DEVICE_NAME}/output/1/tpf",
"qos":0,
"retain":false,
"payload":"${OUTPUTS/1/POWER_FACTOR}",
"events":[
{
"type":"timer",
"period":900
},
{
"type":"delta",
"source":"OUTPUTS/1/POWER_FACTOR",
"delta":0.02
}
]
},
{
"topic":"netio/${DEVICE_NAME}/output/1/frequency",
"qos":0,
"retain":false,
"payload":"${OUTPUTS/1/FREQUENCY}",
"events":[
{
"type":"timer",
"period":3600
},
{
"type":"delta",
"source":"OUTPUTS/1/FREQUENCY",
"delta":0.1
}
]
}
]
}
}