View source for Monitoring via MQTT

Router monitoring via MQTT Linux guide applies to TRB145 gateway and RUT9xx, RUTx routers.
==Introduction==

'''MQTT (MQ Telemetry Transport or Message Queue Telemetry Transport)''' is an ISO standard (ISO/IEC PRF 20922) publish-subscribe-based messaging protocol. It works on top of the TCP/IP protocol. It is designed for connections with remote locations where a "small code footprint" is required or the network bandwidth is limited. The publish-subscribe messaging pattern requires a message broker. 

This article provides a guide on how to configure and use a basic MQTT setup on TRB145 gateway and RUT9xx, RUTx routers.

==How MQTT works==
===On RUT routers===
First lets look over how MQTT works on RUT9xx and RUTx routers. An MQTT connection takes place between two Clients and a Broker. A RUT router can be Broker, a Client or both. The MQTT Publisher (Client) present in RUT routers subscribes to two topics by default: '''router/get''' and '''get/<SERIAL>/command''', where '''<SERIAL>''' is the router's serial number. When a third party client connects to the Broker, it sends the message '''id''' to the the topic '''router/get'''. The publisher then sends a response containing its serial number to the topic '''router/id'''. Now that the Client knows the router's serial number it can ask for values of various parameters by sending requests to the topic '''router/<SERIAL>/parameter_name'''. The MQTT Publisher can send responses containing values of these system parameters:

{| class="wikitable"
|+
! style="width: 250px; background: black; color: white;"  | Parameter name
! style="width: 400px; background: black; color: white;"  | Parameter description
! style="width: 250px; background: black; color: white;"  | Parameter support on RUT9xx
! style="width: 250px; background: black; color: white;"  | Parameter support on RUTX8 and RUTX10 
! style="width: 250px; background: black; color: white;"  | Parameter support on RUTX11

|-
! style="text-align: left; vertical-align: top;" | temperature
| style="text-align: left; vertical-align: top;" | Temperature of the module in 0.1 degrees Celsius
| style="text-align: left; vertical-align: top;" | Yes
| style="text-align: left; vertical-align: top;" | No
| style="text-align: left; vertical-align: top;" | Yes
|-
! style="text-align: left; vertical-align: top;" | operator
| style="text-align: left; vertical-align: top;" | Current operator’s name
|-
! style="text-align: left; vertical-align: top;" | signal
| style="text-align: left; vertical-align: top;" | Signal strength in dBm
|-
! style="text-align: left; vertical-align: top;" | network
| style="text-align: left; vertical-align: top;" | Network state
|-
! style="text-align: left; vertical-align: top;" | connection
| style="text-align: left; vertical-align: top;" | Current connection type (2G, 3G, 4G)
|-
! style="text-align: left; vertical-align: top;" | wan
| style="text-align: left; vertical-align: top;" | WAN IP address
|-
! style="text-align: left; vertical-align: top;" | uptime
| style="text-align: left; vertical-align: top;" | System uptime in seconds
|-
! style="text-align: left; vertical-align: top;" | name
| style="text-align: left; vertical-align: top;" | Router’s device code
|-
! style="text-align: left; vertical-align: top;" | digital1
| style="text-align: left; vertical-align: top;" | Value of digital input no. 1
|-
! style="text-align: left; vertical-align: top;" | digital2
| style="text-align: left; vertical-align: top;" | Value of digital input no. 2
|-
! style="text-align: left; vertical-align: top;" | analog
| style="text-align: left; vertical-align: top;" | Value of analog
|-
|}

After the client sends a message containing of these parameters, the Publisher will send a response message containing the value of the requested parameter to the topic '''router/<SERIAL>/parameter_name''', where '''parameter_name''' is the name of the requested parameter. 


[[File:Configuration examples mqtt scheme v2.jpg]]

It should also be noted that, according to the MQTT protocol, topic names are case-sensitive. For instance, topic ''router'' is not the same as topic ''RoUtEr''.

===TRB145
==Configuring the router==

This section will provide an explanation on how to configure an MQTT Broker and MQTT Publisher on a RUT9xx router.

===Broker===
----
Basic (not counting Security, Bridge and Miscellaneous Broker settings) Broker configuration only contains three fields. Make sure to '''Enable''' the Broker and specify a '''Port''' for connection to the Broker. ''' Enable Remote Access''' if you wish to connect to your router remotely (via WAN). Although in this case your router would need to have a Public IP address. 
 
[[Image:Configuration examples mqtt broker.png]]

===Publisher===
----

Publisher configuration is similar in its simplicity to the Broker configuration. Make sure to '''Enable''' the Publisher and specify a '''Port''' for connection to a Broker. If you plan on using the router's Broker, specify the same port as the one in the Broker Settings section. '''Hostname''' is the Broker's host name or IP address. If you're using the router's Broker, specify your router's LAN IP address. '''Username''' and '''Password''' are optional and depend on the type of security (if any) that the Broker uses.

[[Image:Configuration examples mqtt publisher.png]]

==Configuring the PC==

Once the Broker is up, you'll need to install '''Mosquitto''' and '''Mosquitto Clients''' on your PC. To do so, open the Linux '''Terminal''' app and enter this command:

 $ sudo apt-get install mosquitto mosquitto-clients

<b>NOTE</b>: this software was chosen because it suits the needs of this example and is easily accessible to most users. It is not the only application compatible with RUT MQTT, so if you're using your own software for your solution, it is not mandatory to install this.

==Subscribing and Publishing==

Now you can use set up Brokers and Clients on your PC. In order to Publish commands and Subscribe to topics on a RUT router, you'll need to know the router's '''Serial Number'''. You can find your router's serial number in the '''Status → Device''' section of the router's WebUI. Or you can subscribe to the topic '''router/id''' and publish the message '''id''' to the topic '''router/get'''. To do so, enter these commands in separate Terminal windows:

'''Subscribe:'''
 $ mosquitto_sub -h 192.168.1.1 -p 1833 -u user -P pass -t router/id

'''Publish:'''
 $ mosquitto_pub -h 192.168.1.1 -p 1833 -u user -P pass -t router/get -m id


[[Image:Configuration examples mqtt router id v7.png]]


'''mosquitto_sub''' command is used to subscribe to a certain topic(s) and '''mosquitto_pub''' command is used to publish messages to specified topics. '''-m''' defines the message that you're publishing

'''-h''' indicates the host (the Broker's IP address) which, continuing from the example above, is '''192.168.1.1'''. Replace this value with your router's LAN IP address or, if you're using MQTT remotely, your WAN IP address. 

'''-p''' indicates the port used for connection to the Broker. Replace it with the port number that you specified in the Broker configuration.

'''-u''' and '''-P''' specify the username and password. If the Broker doesn't require authentication, these values aren't mandatory. Else replace them with the log in information of your Broker. 

'''-t''' specifies the '''topics''' that you subscribe or publish to.
 
Now that we have the router's serial number we can start publishing messages and receiving responses containing the router's system parameter values. Lets say we want to monitor the router's '''signal strength''' and '''up time''' values. In order to do that we'll need to subscribe to the topics '''router/<SERIAL>/signal''' and '''router/<SERIAL>/uptime''' using the '''mosquitto_sub''' command. Again, replace the values given in the commands below with the ones in your configuration:

'''Subscribe:'''
 $ mosquitto_sub -h 192.168.1.1 -p 1833 -u user -P pass -t router/<SERIAL>/signal -t router/<SERIAL>/uptime

'''Publish:'''
 $ mosquitto_pub -h 192.168.1.1 -p 1833 -u user -P pass -t router/get -m signal
 $ mosquitto_pub -h 192.168.1.1 -p 1833 -u user -P pass -t router/get -m uptime

[[File:Configuration examples mqtt subscribe publish v5.png|1150px]]