=====Control Netio Power Distribution Units using MQTT=====

This application note explains the steps involved in configuring the device and how to set up the device in Blocks using the Configurable MQTT driver.  The use of MQTT is particularly beneficial if you already have a MQTT enabled system and/or if you want to control devices located behind firewalls over the internet.

:!: NOTE: If you don't already have an MQTT broker as part of your system, the [[blocks:app-note:netio_modbus|MODBUS-based]] method of controlling this device may be easier to use.

====Prepare the device====
First of all make yourself familiar with MQTT, we have a [[blocks:server:advanced_server_configuration:mqtt|short article]] explaining the principles and describes how to enable a broker on the Blocks server.

Please refer to the vendor documentation on how to access the setup of the device.  After successfully logged on we must enable and configure the MQTT-flex api.  This is done by editing the JSON description as seen here.
{{:blocks:app-note:netio:netiomqtt.png?800|}}

There is two things we must do here, configure our connection using our credentials and connection details for the //broker// section and configure subscriptions to the topics we want to use for control of the socket relays.

====Device connection====

Update this section with the appropriate details for your broker.
<code>
{
  "broker": {
    "clientid": "netio${DEVICE_SN}",
    "keepalive": 30,
    "username": "your_broker_username"
    "password": "your_broker_password",
    "port": 8883,
    "protocol": "mqtts",
    "ssl": false,
    "type": "generic",
    "url": "your_broker_URL",
  },
</code>

====State monitoring (Publish)====
If we want to make Blocks aware of any changes made by someone or something else we can also configure the device to publish changes to MQTT topics. That is done by adding a //publish// section in the configuration like this:
<code>
"publish":[{
    "topic":"netios/${DEVICE_NAME}/output/1/state",
    "qos":0,
    "retain":true,
    "payload":"${OUTPUTS/1/STATE}",
    "events":[
      {
        "source": "OUTPUTS/1/STATE",
        "type": "change"
      }]
  },{
    "topic":"netios/${DEVICE_NAME}/output/2/state",
    "qos":0,
    "retain":true,
    "payload":"${OUTPUTS/2/STATE}",
    "events":[{
        "source": "OUTPUTS/2/STATE",
        "type": "change"
      }]
 }],
</code>

====Device Control (Subscriptions)====
We must also enable subscriptions to the topics we want to use for controlling the devices relays, as by default the device only emits metrics to the broker with no relay control for the sockets over mqtt enabled. This example shows a 2 socket PowerCABLE 2XX configuration. You may adjust to fewer or more outputs depending on the device you are setting up. 
For each output/socket/relay we need to subscripe to a topic like this:
<code>   	 {
      "topic": "netios/${DEVICE_NAME}/output/1/action",
      "qos": 0,
      "target": "OUTPUTS/1/ACTION",
      "action": "${payload}"
    }
 </code>  
While //topic// can be any topic path that makes sense for your project. In a minute will configure Blocks to send data to the same topic and as long as they match it will work. The ${DEVICE_NAME} is a parameter that contains the device name, and the device name can be configured under settings/system. Remember that this name must be unique.
 
We should end up with something like this under the //subscribe"// section:
<code>
 "subscribe": [
   	 {
      "topic": "netios/${DEVICE_NAME}/output/1/action",
      "qos": 0,
      "target": "OUTPUTS/1/ACTION",
      "action": "${payload}"
    },
    {
      "topic": "netios/${DEVICE_NAME}/output/2/action",
      "qos": 0,
      "target": "OUTPUTS/2/ACTION",
      "action": "${payload}"
    },
  ,{
      "action": "${payload}",
      "qos": 0,
      "target": "REST_JSON",
      "topic": "netios/${DEVICE_NAME}/messages/events/"
    }
</code>

For detailed information please read the vendors documentation.

====Configure the MQTT driver in Blocks====

Before adding devices we must have a broker running (somewhere) and configured in the blocks server configuration. Please read [[blocks:server:advanced_server_configuration:mqtt|the MWTT documentation]] to get started.
This application note use the generic //configurableMQTT// driver in Blocks, is has a very similar way of configuring as the netio devices. The driver is a bit "nerdy" but is also very flexible and more or less any MQTT device can be configured. It is also possible to write mqtt drivers that is bospoke for a certain device.
 
===Add the device===
Add a new mqtt device from Manage/Network Devices. Give the device a unique and meaningful name and set the //Topic Base//, this is the common part of the mqtt topic. The topic base will be concatenated with the subTopic from the configuration below to form the full topic path. 
For the Netio example configurations in this app note the Topic Base is //netios/PowerBOX-B7// where PowerBox-B7 comes from the device name inserted by the device configuration. This comes from //netios/${DEVICE_NAME}/// found in the devices mqtt configuration.

In the drivers custom options we can specify the blocks property names and the MQTT topics we need to subscribe to  using JSON. The following example is for 2 socket PowerCABLE configured as in the examples above. 

{{:blocks:app-note:netio:netio.png?800|}}

Example driver configuration for a two socket device:

 <code>
    {
        "property": "Relay1",
        "publishSubTopic": "/output/1/action",
        "subTopic": "/output/1/state",
        "dataType": "Boolean",
        "trueValue": "1",
        "falseValue": "0"
    },
    {
        "property": "Relay2",
        "publishSubTopic": "/output/2/action",
        "subTopic": "/output/2/state",
        "dataType": "Boolean",
        "trueValue": "1",
        "falseValue": "0"
    }
]

</code>

Where:

//property// is the name of the property in Blocks.

// publishSubTopic// is used to publish changes coming from Blocks. 

//subTopic// is used to listen to status changes coming from the device. 

//datatype//: is used to specify what data type to use, since this is a 2 state relay, Boolean is a good match. 
//trueValue// is used to match the value the device listens to as true, in this case "1"
//falseValue//:  is used to match the value the device listens to as false

=====Example configurations for NETIO devices=====
The following examples can be used to configure the device and Blocks for MQTT. Both ends use JSON notation to specify the configuration. Both Netio and Blocks can be configured to match any existing system, hence configurable. In the case of NETIO we do not have to adapt to anything existing but we must setup some topics to use for communication. The examples do in a sense specify create the API. 
====NETIO PowerCable 2XX====
===Netio MQTT flex api config===
Paste the following MQTT-flex config in the device configuration, change the broker connection configuration and click the save button.
<code>
{
  "broker": {
    "clientid": "netio${DEVICE_SN}",
    "keepalive": 30,
    "password": "your_password",
    "port": 8883,
    "protocol": "mqtts",
    "ssl": false,
    "type": "generic",
    "url": "your_broker_adress",
    "username": "your_username"
  },
  "publish": [
    {
      "topic": "netios/${DEVICE_NAME}/output/1/state",
      "qos": 0,
      "retain": true,
      "payload": "${OUTPUTS/1/STATE}",
      "events": [
        {
          "source": "OUTPUTS/1/STATE",
          "type": "change"
        }
      ]
    },
    {
      "topic": "netios/${DEVICE_NAME}/output/2/state",
      "qos": 0,
      "retain": true,
      "payload": "${OUTPUTS/2/STATE}",
      "events": [
        {
          "source": "OUTPUTS/2/STATE",
          "type": "change"
        }
      ]
    }
  ],
  "subscribe": [
    {
      "topic": "netios/${DEVICE_NAME}/output/1/action",
      "qos": 0,
      "target": "OUTPUTS/1/ACTION",
      "action": "${payload}"
    },
    {
      "topic": "netios/${DEVICE_NAME}/output/2/action",
      "qos": 0,
      "target": "OUTPUTS/2/ACTION",
      "action": "${payload}"
    },
    {
      "action": "${payload}",
      "qos": 0,
      "target": "REST_JSON",
      "topic": "netios/${DEVICE_NAME}/messages/events/"
    }
  ]
}
</code>

===Blocks configurable MQTT driver custom options===
<code> 
[{
        "property": "Relay1",
        "publishSubTopic": "/output/1/action",
        "subTopic": "/output/1/state",
        "dataType": "Boolean",
        "trueValue": "1",
        "falseValue": "0"
    },
    {
        "property": "Relay2",
        "publishSubTopic": "/output/2/action",
        "subTopic": "/output/2/state",
        "dataType": "Boolean",
        "trueValue": "1",
        "falseValue": "0"
    }
    
]
</code>

====NETIO PowerBOX 3XX====
===Netio MQTT flex api config===
Paste the following MQTT-flex config in the device configuration, change the broker connection configuration and click the save button.
<code>
{
  "broker": {
    "clientid": "netio${DEVICE_SN}",
    "keepalive": 30,
    "password": "your_password",
    "port": 8883,
    "protocol": "mqtts",
    "ssl": false,
    "type": "generic",
    "url": "your_broker_adress",
    "username": "your_username"
  },
  "publish": [
    {
      "topic": "netios/${DEVICE_NAME}/output/1/state",
      "qos": 0,
      "retain": true,
      "payload": "${OUTPUTS/1/STATE}",
      "events": [
        {
          "source": "OUTPUTS/1/STATE",
          "type": "change"
        }
      ]
    },
    {
      "topic": "netios/${DEVICE_NAME}/output/2/state",
      "qos": 0,
      "retain": true,
      "payload": "${OUTPUTS/2/STATE}",
      "events": [
        {
          "source": "OUTPUTS/2/STATE",
          "type": "change"
        }
      ]
    },
    {
      "topic": "netios/${DEVICE_NAME}/output/3/state",
      "qos": 0,
      "retain": true,
      "payload": "${OUTPUTS/3/STATE}",
      "events": [
        {
          "source": "OUTPUTS/3/STATE",
          "type": "change"
        }
      ]
    }
  ],
  "subscribe": [
    {
      "topic": "netios/${DEVICE_NAME}/output/1/action",
      "qos": 0,
      "target": "OUTPUTS/1/ACTION",
      "action": "${payload}"
    },
    {
      "topic": "netios/${DEVICE_NAME}/output/2/action",
      "qos": 0,
      "target": "OUTPUTS/2/ACTION",
      "action": "${payload}"
    },
    {
      "topic": "netios/${DEVICE_NAME}/output/3/action",
      "qos": 0,
      "target": "OUTPUTS/3/ACTION",
      "action": "${payload}"
    },
    {
      "action": "${payload}",
      "qos": 0,
      "target": "REST_JSON",
      "topic": "netios/${DEVICE_NAME}/messages/events/"
    }
  ]
}
</code>
===Blocks configurable MQTT driver custom options===
<code> 
[
    {
        "property": "Relay1",
        "publishSubTopic": "/output/1/action",
        "subTopic": "/output/1/state",
        "dataType": "Boolean",
        "trueValue": "1",
        "falseValue": "0"
    },
    {
        "property": "Relay2",
        "publishSubTopic": "/output/2/action",
        "subTopic": "/output/2/state",
        "dataType": "Boolean",
        "trueValue": "1",
        "falseValue": "0"
    },
    {
        "property": "Relay3",
        "publishSubTopic": "/output/3/action",
        "subTopic": "/output/3/state",
        "dataType": "Boolean",
        "trueValue": "1",
        "falseValue": "0"
    }
]
</code>

====NETIO PowerBOX 4XX====
===Netio MQTT flex api config===
Paste the following MQTT-flex config in the device configuration, change the broker connection configuration and click the save button.

<code>
{
  "broker": {
    "clientid": "netio${DEVICE_SN}",
    "keepalive": 30,
    "password": "your_password",
    "port": 8883,
    "protocol": "mqtts",
    "ssl": false,
    "type": "generic",
    "url": "your_broker_adress",
    "username": "your_username"
  },
  "publish": [
    {
      "topic": "netios/${DEVICE_NAME}/output/1/state",
      "qos": 0,
      "retain": true,
      "payload": "${OUTPUTS/1/STATE}",
      "events": [
        {
          "source": "OUTPUTS/1/STATE",
          "type": "change"
        }
      ]
    },
    {
      "topic": "netios/${DEVICE_NAME}/output/2/state",
      "qos": 0,
      "retain": true,
      "payload": "${OUTPUTS/2/STATE}",
      "events": [
        {
          "source": "OUTPUTS/2/STATE",
          "type": "change"
        }
      ]
    },
    {
      "topic": "netios/${DEVICE_NAME}/output/3/state",
      "qos": 0,
      "retain": true,
      "payload": "${OUTPUTS/3/STATE}",
      "events": [
        {
          "source": "OUTPUTS/3/STATE",
          "type": "change"
        }
      ]
    },
    {
      "topic": "netios/${DEVICE_NAME}/output/4/state",
      "qos": 0,
      "retain": true,
      "payload": "${OUTPUTS/4/STATE}",
      "events": [
        {
          "source": "OUTPUTS/4/STATE",
          "type": "change"
        }
      ]
    }
  ],
  "subscribe": [
    {
      "topic": "netios/${DEVICE_NAME}/output/1/action",
      "qos": 0,
      "target": "OUTPUTS/1/ACTION",
      "action": "${payload}"
    },
    {
      "topic": "netios/${DEVICE_NAME}/output/2/action",
      "qos": 0,
      "target": "OUTPUTS/2/ACTION",
      "action": "${payload}"
    },
    {
      "topic": "netios/${DEVICE_NAME}/output/3/action",
      "qos": 0,
      "target": "OUTPUTS/3/ACTION",
      "action": "${payload}"
    },
    {
      "topic": "netios/${DEVICE_NAME}/output/4/action",
      "qos": 0,
      "target": "OUTPUTS/4/ACTION",
      "action": "${payload}"
    },
    {
      "action": "${payload}",
      "qos": 0,
      "target": "REST_JSON",
      "topic": "netios/${DEVICE_NAME}/messages/events/"
    }
  ]
}
</code>
===Blocks configurable MQTT driver custom options===
Paste the following configuration in the ConfigurableMQTT driver options.
<code>
[
    {
        "property": "Relay1",
        "publishSubTopic": "/output/1/action",
        "subTopic": "/output/1/state",
        "dataType": "Boolean",
        "trueValue": "1",
        "falseValue": "0"
    },
    {
        "property": "Relay2",
        "publishSubTopic": "/output/2/action",
        "subTopic": "/output/2/state",
        "dataType": "Boolean",
        "trueValue": "1",
        "falseValue": "0"
    },
    {
        "property": "Relay3",
        "publishSubTopic": "/output/3/action",
        "subTopic": "/output/3/state",
        "dataType": "Boolean",
        "trueValue": "1",
        "falseValue": "0"
    },
       {
        "property": "Relay4",
        "publishSubTopic": "/output/4/action",
        "subTopic": "/output/4/state",
        "dataType": "Boolean",
        "trueValue": "1",
        "falseValue": "0"
    }
]
</code>