Changes

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

Router monitoring via MQTT Linux guide applies to TRB devices and to RUT, TCR routers.

==Introduction==

==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.  

'''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 on RUT9xx, RUTx routers.

This article provides a guide on how to configure and use a basic MQTT setup on TRB devices and on RUT, TCR routers.

==How MQTT works==

==How MQTT works==

In general an MQTT connection takes place between two Clients and a Broker. A TRB14x gateways and RUT routers can be Broker, Client or both. The MQTT Publisher(Client) present in TRB14x and RUT routers subscribes to two topics by default: '''<TYPE>/get''' and '''get/<SERIAL>/command'''. Where '''<TYPE>''' is device type, for RUT routers type is '''router''' and for TRB14x gateways type is '''device'''. Parameter  '''<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 '''<TYPE>/get'''. The publisher then sends a response containing its serial number to the topic '''<TYPE>/id'''. Now that the Client knows the router's or gateway's serial number it can ask for values of various parameters by sending requests to the topic '''<TYPE>/<SERIAL>/parameter_name'''. The MQTT Publisher can send responses containing values of these system parameters, if device supports that parameter:

In general an MQTT connection takes place between two Clients and a Broker. A TRB device and RUT/TCR router can be Broker, Client or both. The MQTT Publisher(Client) present in TRB devices and RUT/TCR routers subscribes to two topics by default: '''<TYPE>/get''' and '''get/<SERIAL>/command'''. Where '''<TYPE>''' is device type, for RUT/TCR routers type is '''router''' and for TRB devices type is '''device'''. Parameter  '''<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 '''<TYPE>/get'''. The publisher then sends a response containing its serial number to the topic '''<TYPE>/id'''. Now that the Client knows the router's or device's serial number it can ask for values of various parameters by sending requests to the topic '''<TYPE>/<SERIAL>/parameter_name'''. The MQTT Publisher can send responses containing values of these system parameters, if device supports that parameter:

{| class="wikitable"

{| class="wikitable"

! style="width: 250px; background: black; color: white;"  | Parameter name

! style="width: 250px; background: black; color: white;"  | Parameter name

! style="width: 400px; background: black; color: white;"  | Parameter description

! style="width: 400px; background: black; color: white;"  | Parameter description

! style="width: 250px; background: black; color: white;"  | Supported devices

! style="width: 300; background: black; color: white;"  | Supported devices

|-

|-

! style="text-align: left; vertical-align: top;" | temperature

! 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;" | Temperature of the module in 0.1 degrees Celsius

| style="text-align: left; vertical-align: top;" | RUT9xx and RUTx11

| style="text-align: left; vertical-align: top;" | RUT2, RUT9, RUTX, RUT3, TCR1, TRB2

|-

|-

! style="text-align: left; vertical-align: top;" | operator

! 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;" | Current operator’s name

| style="text-align: left; vertical-align: top;" | RUT9xx, RUTx11 and TRB14x

| style="text-align: left; vertical-align: top;" | RUT2, RUT9, RUTX, RUT3, TCR1, TRB1, TRB2

|-

|-

! style="text-align: left; vertical-align: top;" | signal

! 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;" | Signal strength in dBm

| style="text-align: left; vertical-align: top;" | RUT9xx, RUTx11 and TRB14x

| style="text-align: left; vertical-align: top;" | RUT2, RUT9, RUTX, RUT3, TCR1, TRB1, TRB2

|-

|-

! style="text-align: left; vertical-align: top;" | network

! style="text-align: left; vertical-align: top;" | network

| style="text-align: left; vertical-align: top;" | Network state

| style="text-align: left; vertical-align: top;" | Network state

| style="text-align: left; vertical-align: top;" | RUT9xx, RUTx11 and TRB14x

| style="text-align: left; vertical-align: top;" | RUT2, RUT9, RUTX, RUT3, TCR1, TRB1, TRB2

|-

|-

! style="text-align: left; vertical-align: top;" | connection

! 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;" | Current connection type (2G, 3G, 4G)

| style="text-align: left; vertical-align: top;" | RUT9xx, RUTx11 and TRB14x

| style="text-align: left; vertical-align: top;" | RUT2, RUT9, RUTX, RUT3, TCR1, TRB1, TRB2

|-

|-

! style="text-align: left; vertical-align: top;" | wan

! 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;" | WAN IP address

| style="text-align: left; vertical-align: top;" | RUT9xx, RUTx11 and TRB14x

| style="text-align: left; vertical-align: top;" | RUT2, RUT9, RUTX, RUT3, TCR1, TRB1, TRB2

|-

|-

! style="text-align: left; vertical-align: top;" | uptime

! 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;" | System uptime in seconds

| style="text-align: left; vertical-align: top;" | RUT9xx, RUTxx and TRB14x

| style="text-align: left; vertical-align: top;" | RUT2, RUT9, RUTX, RUT3, TCR1, TRB1, TRB2

|-

|-

! style="text-align: left; vertical-align: top;" | name

! 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;" | Device's device code

| style="text-align: left; vertical-align: top;" | RUT9xx, RUTxx and TRB14x

| style="text-align: left; vertical-align: top;" | RUT2, RUT9, RUTX, RUT3, TCR1, TRB1, TRB2

|-

|-

! style="text-align: left; vertical-align: top;" | digital1

! 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;" | Value of digital input no. 1

| style="text-align: left; vertical-align: top;" | RUT9xx

| style="text-align: left; vertical-align: top;" | RUT9

|-

|-

! style="text-align: left; vertical-align: top;" | digital2

! 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;" | Value of digital input no. 2

| style="text-align: left; vertical-align: top;" | RUT9xx

| style="text-align: left; vertical-align: top;" | RUT9, TRB1

|-

|-

! style="text-align: left; vertical-align: top;" | analog

! style="text-align: left; vertical-align: top;" | analog

| style="text-align: left; vertical-align: top;" | Value of analog

| style="text-align: left; vertical-align: top;" | Value of analog

| style="text-align: left; vertical-align: top;" | RUT9xx

| style="text-align: left; vertical-align: top;" | RUT9, TRB2

|-

|-

|}

|}

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

[[File:Configuration examples mqtt scheme v2.jpg|border|class=tlt-border]]

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''.

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''.

==Configuring the router==

==Configuring the device==

This section will provide an explanation on how to configure an MQTT Broker and MQTT Publisher on a TRB14x gateways and on RUT routers.

This section will provide an explanation on how to configure an MQTT Broker and MQTT Publisher on a TRB devices and on RUT/TCR routers.

===Broker===

===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. In image below is presented how to configure RUT9xx routers:

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. In image below is presented how to configure RUT9xx routers:

   

   

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

[[Image:Configuration examples mqtt broker.png|border|class=tlt-border]]

Configuration for a TRB14x gateways and a RUTxx routers look like this:

Configuration for a TRB device and a RUT/TCR router looks like this:

[[Image:Configuration_examples_publisher_new_design.png]]

[[Image:Configuration_examples_publisher_new_design.png|border|class=tlt-border]]

===Publisher===

===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.

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. In image below is presented how configure RUT9xx routers:

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

[[Image:Configuration examples mqtt publisher.png|border|class=tlt-border]]

 

 

 

 

==Subscribing and Publishing==

==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:

Now you can use set up Brokers and Clients on your PC. In order to Publish commands and Subscribe to topics on a TRB series devices and RUT/TCR routers, you'll need to know the device's '''Serial Number''' and '''TYPE'''. For TRB series device's you'll need to use type : '''device''' and for RUT/TCR router's you'll need to use type: '''router'''. Router's serial number you can find in the '''Status → Device''' section of the router's WebUI. For TRB series devices serial number you can find in the '''Status → System''' section of the device WebUI. Or you can subscribe to the topic '''<TYPE>/id''' and publish the message '''id''' to the topic '''<TYPE>/get'''. To do so, enter these commands in separate Terminal windows:

'''Subscribe:'''

'''Subscribe:'''

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

  $ mosquitto_sub -h 192.168.1.1 -p 1833 -u user -P pass -t <TYPE>/id

'''Publish:'''

'''Publish:'''

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

  $ mosquitto_pub -h 192.168.1.1 -p 1833 -u user -P pass -t <TYPE>/get -m id

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

[[File:Configuration examples mqtt router id new 1.png|border|class=tlt-border]]

'''-t''' specifies the '''topics''' that you subscribe or publish to.

'''-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:

Now that we have the using device's serial number we can start publishing messages and receiving responses containing the device's system parameter values. Lets say we want to monitor the device'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:'''

'''Subscribe:'''

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

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

 

[[File:Configuration examples mqtt subscribe publish new 2.png|1100px|border|class=tlt-border]]

 

 

[[Category:Router control and monitoring]]