Changes

3,999 bytes removed ,  08:14, 13 September 2023
no edit summary
Line 1: Line 1: −
<p style="color:red">The information in this page is updated in accordance with [https://wiki.teltonika-networks.com/view/FW_%26_SDK_Downloads'''00.07.4'''] firmware version .</p>
+
<p style="color:red">The information on this page is updated in accordance with the [https://wiki.teltonika-networks.com/view/FW_%26_SDK_Downloads'''00.07.4'''] firmware version .</p>
==Introduction==
+
__TOC__
 +
==Summary==
 +
In this guide, the MQTT Serial Gateway function will be configured using third-party MQTT Broker services (in this example, ''Flespi.io'').
   −
==Configuration overview and prerequisites==
+
==Configuration overview & prerequisites==
 +
*Two devices with serials ports - one acts as Modbus RTU Master, another as Modbus RTU Slave;
 +
*Flespi.io account to act as an MQTT Broker/Publisher/Subscriber (for first configuration example);
   −
Before we begin, let's take a look at the configuration that we are attempting to achieve and the prerequisites that make it possible.
+
[[File:MQTT Serial gateway topology v2.png|border|center|class=tlt-border|847x279px]]
   −
'''Prerequisites''':
+
RUT2 will act as a Modbus RTU slave and RUT1 as a Modbus RTU Master. On RUT1, MQTT Serial Gateway will be configured to transfer Modbus data over MQTT. Flespi.io platform will serve as an MQTT Broker
* Two RUT/RUTX series routers with RUTOS firmware;
  −
* An end device (PC, Laptop) for configuration;
     −
If you're having trouble finding any page or some of the parameters described here on your device's WebUI, you should turn on '''"Advanced WebUI"''' mode. You can do that by '''clicking''' the '''"Basic"''' button '''under''' '''"Mode,"''' which is located at the top-right corner of the WebUI.
+
==RUT2 configuration==
[[File:Networking rut9 manual webui basic advanced mode.gif|border|center|class=tlt-border|1102x52px]]
+
===Configuring Modbus RTU Slave===
 +
----
 +
Go to Services → Modbus → Modbus RTU Slave and create a new instance.
 +
# Enter the '''desired instance name''';
 +
# Select the '''desired serial interface'''.
   −
==Topology==
+
[[File:Modbus RTU Slave.png|border|center|class=tlt-border|855 × 308px]]
   −
RUT1 - RUTX11 as a hub. It will be our "default gateway" for spoke device. RUTX11 has a LAN subnet of 192.168.11.0/24 configured on it, which should be reachable by the spoke.
+
==RUT1 configuration==
 +
===Configuring MQTT Gateway===
 +
----
 +
Go to '''Services → Modbus → MQTT Gateway''' and there:
   −
RUT2 - RUT955 as a spoke. It will be connecting to a hub for basic internet access. RUT955 has a lan subnet of 192.168.9.0/24 configured on it, which should be reachable by the hub.
+
# '''Enable''' the '''instance''';
 +
# '''Enter Host''' (copied from flespi connection settings without 'wss://' and port);
 +
# '''Enter Username''' (Copied from flespi Connection settings generated '''token''');
 +
# '''Enter Password'''.
   −
==RUT1 (Hub) configuration==
+
[[File:MQTT Gateway config.png|border|center|class=tlt-border|862 × 412px]]
Start by configuring HUB (RUT1) device. Login to the WebUI, navigate to '''Services → VPN → IPsec''' and add a new IPsec instance. Configure everything as follows.
     −
'''Note:''' '''''Not specified fields can be left as-is or changed according to your needs.'''''
+
'''Note''': ''Everything else can be left as default or changed according to your needs.''
===Instance configuration===
  −
----
  −
<table class="nd-othertables_2">
  −
    <tr>
  −
        <th width=330; style="border-bottom: 1px solid white;></th>
  −
        <th width=800; style="border-bottom: 1px solid white"; rowspan=2>[[File:IPsec HUB.png|border|class=tlt-border|755x406px|right]]</th>
  −
    </tr>
  −
    <tr>
  −
        <td style="border-bottom: 4px solid white>
  −
# '''''Enable''''' instance;
  −
# Authentication method - '''''Pre-shared key;'''''
  −
# Pre-shared key - '''''your desired password;'''''
  −
        </td>
  −
    </tr>
  −
</table>
     −
===Connection configuration===
+
===Configuring Serial Gateway===
 
----
 
----
 +
Under the MQTT Gateway configuration, create the Serial Gateway:
 +
# Enter the '''desired device ID''';
 +
# Select the '''desired serial interface'''.
   −
<table class="nd-othertables_2">
+
[[File:Serial gateway config.png|border|center|class=tlt-border|868×308px]]
    <tr>
  −
        <th width=330; style="border-bottom: 1px solid white;></th>
  −
        <th width=800; style="border-bottom: 1px solid white;" rowspan=2>[[File:IPsec HUB Connection.png|border|class=tlt-border|753x368px|right]]</th>
  −
    </tr>
  −
    <tr>
  −
        <td style="border-bottom: 4px solid white>
  −
# Mode - '''''Start;'''''
  −
# Type - '''''Tunnel;'''''
  −
# Local subnet - '''''0.0.0.0/.0;'''''
  −
# Key exchange - '''''IKEv2;'''''
  −
        </td>
  −
    </tr>
  −
</table>
      +
===Configuring Flespi.io MQTT Broker===
 
----
 
----
<table class="nd-othertables_2">
+
'''Log in''' or '''create an account''' on '''https://flespi.io''';
    <tr>
  −
        <th width=330; style="border-bottom: 1px solid white;></th>
  −
        <th width=800; style="border-bottom: 1px solid white;" rowspan=2>[[File:IPsec HUB Connection Advanced.png|border|class=tlt-border|752x541px|right]]</th>
  −
    </tr>
  −
    <tr>
  −
        <td style="border-bottom: 4px solid white>
  −
# '''''Enable''''' '''''Local firewall;'''''
  −
# Remote source IP - '''''10.20.30.0/24;'''''
  −
# Remote DNS '''''9.9.9.9;'''''
  −
        </td>
  −
    </tr>
  −
</table>
     −
===Proposal configuration===
+
#Navigate to '''MQTT Board''' on the '''left side''' menu;                                       
----
+
#On the right-hand panel, top right corner, next to the name of the MQTT board, '''press the cogwheel-looking icon''' to open ''Connection Settings'';
 +
#In the opened window, press '''"Get flespi token"''' to generate a username;
 +
#Enter the '''Client name''';
 +
#Copy the Host address;
 +
#Copy '''Username''';
 +
#Create a '''password'''.
   −
<table class="nd-othertables_2">
+
Once done, save all the changes.
    <tr>
+
[[File:Flespi board.png|border|center|class=tlt-border|1102x729px]]
        <th width=330; style="border-bottom: 1px solid white;></th>
  −
        <th width=800; style="border-bottom: 1px solid white;" rowspan=2>[[File:IPsec Phase1.png|border|class=tlt-border|742x254px|right]]</th>
  −
    </tr>
  −
    <tr>
  −
        <td style="border-bottom: 4px solid white>
  −
# Encryption - '''''AES256;'''''
  −
# Authentication - '''''SHA512;'''''
  −
# DH group - '''''ECP521;'''''
  −
        </td>
  −
    </tr>
  −
</table>
      +
===Message format for MQTT publisher===
 
----
 
----
<table class="nd-othertables_2">
+
Modbus request data sent in the MQTT payload should be generated in accordance with the following format:
    <tr>
  −
        <th width=330; style="border-bottom: 1px solid white;></th>
  −
        <th width=800; style="border-bottom: 1px solid white;" rowspan=2>[[File:IPsec Phase2.png|border|class=tlt-border|748x257px|right]]</th>
  −
    </tr>
  −
    <tr>
  −
        <td style="border-bottom: 4px solid white>
  −
# Encryption - '''''AES128;'''''
  −
# Authentication - '''''SHA256;'''''
  −
# DH group - '''''ECP521;'''''
  −
        </td>
  −
    </tr>
  −
</table>
     −
==RUT2 (Spoke) configuration==
+
<pre>1 <COOKIE> <SERIAL_DEVICE_ID> <TIMEOUT> <SLAVE_ID> <MODBUS_FUNCTION> <FIRST_REGISTER> <REGISTER_COUNT> </pre>
Login to the RUT2 WebUI, navigate to '''Services → VPN → IPsec''' and add a new IPsec instance. Configure everything as follows.
+
 
===Instance configuration===
+
The table below explains what each option means:
----
  −
<table class="nd-othertables_2">
  −
    <tr>
  −
        <th width=330; style="border-bottom: 1px solid white;></th>
  −
        <th width=800; style="border-bottom: 1px solid white;" rowspan=2>[[File:IPsec SPOKE.png|border|class=tlt-border|742x399px|right]]</th>
  −
    </tr>
  −
    <tr>
  −
        <td style="border-bottom: 4px solid white>
  −
# '''''Enable''''' instance;
  −
# Remote endpoint - '''''RUT1 public IP;'''''
  −
# Authentication method - '''''Pre-shared key;'''''
  −
# Pre-shared key - the '''''same password''''' you have '''''set on''''' '''''RUT1''''' when configuring '''''HUB instance;'''''
  −
        </td>
  −
    </tr>
  −
</table>
     −
===Connection configuration===
+
{| class="wikitable"
 +
|1.  Format version
 +
|'''1'''
 +
|-
 +
|2. Cookie
 +
|from '''0''' to '''2<sup>64</sup> -1'''
 +
|-
 +
|3. Serial device ID
 +
|a string used to identify a serial device. Must match with <u>Device ID</u> field in MQTT Gateway page Serial gateway configuration section
 +
|-
 +
|4. Timeout
 +
|timeout for Modbus connection, in seconds. Range [1..999].
 +
|-
 +
|5. Slave ID
 +
|Indicates to which slave request is sent
 +
|-
 +
|6. Modbus function
 +
|Modbus task type that will be executed. Possible values are:
 +
        <ul>
 +
            <li><b>1</b> - read coils;</li>
 +
            <li><b>2</b> - read input coils;</li>
 +
            <li><b>3</b> - read holding registers;</li>
 +
            <li><b>4</b> - read input registers;</li>
 +
            <li><b>5</b> - set single coil;</li>
 +
            <li><b>6</b> - write to a single holding register;</li>
 +
            <li><b>15</b> - set multiple coils;</li>
 +
            <li><b>16</b> - write to multiple holding registers.</li>
 +
        </ul>
 +
|-
 +
|7. First register
 +
|number (not address) of the first register/coil/input (in range [1..65536]) from which the registers/coils/inputs will be read/written to.
 +
|-
 +
|8. Registry count
 +
| <li><b>1</b> - <u>coil count</u> (in range [1..2000]); must not exceed the boundary (first coil number + coil count <= 65537);</li>
 +
            <li><b>2</b> - <u>input count</u> (in range [1..2000]); must not exceed the boundary (first input number + input count <= 65537);</li>
 +
            <li><b>3</b> - <u>holding register count</u> (in range [0..125]); must not exceed the boundary (first register number + holding register count <= 65537);</li>
 +
            <li><b>4</b> - <u>input register count</u> (in range [0..125]); must not exceed the boundary (first register number + input register count <= 65537);</li>
 +
            <li><b>5</b> - <u>coil value</u> (in range [0..1]);</li>
 +
            <li><b>6</b> - <u>holding register value</u> (in range [0..65535]);</li>
 +
            <li><b>15</b> - <u>coil count</u> (in range [1..1968]); must not exceed the boundary (first coil number + coil count <= 65537); and <u>coil values</u> separated with commas, without spaces (e.g., <i>1,2,3,654,21,789</i>); there must be exactly as many values as specified (with coil count); each value must be in the range of [0..1].
 +
|}
 +
====Examples====
 
----
 
----
 +
{| class="wikitable"
 +
|Setting relay (on) (Relay address is 202, which means 'Number of first register will be 203)
 +
|'''1 1 1 1 1 6 203 1'''
 +
|-
 +
|Getting temperature
 +
|'''1 1 1 1 1 3 6 2'''
 +
|}
 +
Modbus parameters are held within registers. The register numbers and corresponding system values can be found [[RUT955_Monitoring_via_Modbus#Get_Parameters|'''in this article''']].
   −
<table class="nd-othertables_2">
+
==Testing MQTT Publisher and Subscriber on flespi.io==
    <tr>
+
====Adding Flespi Subscriber====
        <th width=330; style="border-bottom: 1px solid white;></th>
  −
        <th width=800; style="border-bottom: 1px solid white;" rowspan=2>[[File:IPsec SPOKE Connection.png|border|class=tlt-border|761x280px|right]]</th>
  −
    </tr>
  −
    <tr>
  −
        <td style="border-bottom: 4px solid white>
  −
# Mode - '''''Start;'''''
  −
# Type - '''''Tunnel;'''''
  −
# '''''Enable''''' '''''default route;'''''
  −
# Key exchange - '''''IKEv2;'''''
  −
        </td>
  −
    </tr>
  −
</table>
  −
 
  −
===Proposalconfiguration===
   
----
 
----
<table class="nd-othertables_2">
+
To test the Modbus Serial Gateway functionality, '''log into''' your '''Flespi account''' '''MQTT Board''' and '''add a Subscriber''':
    <tr>
  −
        <th width=330; style="border-bottom: 1px solid white;></th>
  −
        <th width=800; style="border-bottom: 1px solid white;" rowspan=2>[[File:IPsec Phase1.png|border|class=tlt-border|742x254px|right]]</th>
  −
    </tr>
  −
    <tr>
  −
        <td style="border-bottom: 4px solid white>
  −
# Encryption - '''''AES256;'''''
  −
# Authentication - '''''SHA512;'''''
  −
# DH group - '''''ECP521;'''''
  −
        </td>
  −
    </tr>
  −
</table>
     −
----
+
#Press '''''<nowiki/>'+'''''' button on the top right corner
<table class="nd-othertables_2">
+
#Select '''''<nowiki/>'Subscriber''''''
    <tr>
+
# In the topic field enter '''''<nowiki/>'response''''''
        <th width=330; style="border-bottom: 1px solid white;></th>
+
#Press '''''<nowiki/>'Subscribe'''''' button
        <th width=800; style="border-bottom: 1px solid white;" rowspan=2>[[File:IPsec Phase2.png|border|class=tlt-border|748x257px|right]]</th>
  −
    </tr>
  −
    <tr>
  −
        <td style="border-bottom: 4px solid white>
  −
# Encryption - '''''AES128;'''''
  −
# Authentication - '''''SHA256;'''''
  −
# DH group - '''''ECP521;'''''
  −
        </td>
  −
    </tr>
  −
</table>
     −
==Testing configuration==
+
[[File:Flespi subscriber.png|border|class=tlt-border|496x204px]]          [[File:Flespi subscriber setup.png|border|class=tlt-border|496x205px]]
After we establish the tunnel, we may observe the following information:
+
====Adding Flespi Subscriber====
===RUT1 (HUB) side===
   
----
 
----
Using the <pre>ipsec statusall</pre> command we can see that the tunnel has been established.
  −
  −
<pre>
  −
root@Teltonika-RUTX12:~# ipsec statusall
  −
Status of IKE charon daemon (strongSwan 5.9.2, Linux 5.4.231, armv7l):
  −
  uptime: 74 minutes, since Mar 21 08:52:39 2023
  −
  worker threads: 11 of 16 idle, 5/0/0/0 working, job queue: 0/0/0/0, scheduled: 2
  −
  loaded plugins: charon aes des sha2 sha1 md4 md5 random nonce x509 revocation constraints pubkey pkcs1 pkcs8 pgp pem openssl gmp xcbc hmac kernel-netlink socket-default stroke vici updown eap-identity eap-mschapv2 xauth-generic
  −
Virtual IP pools (size/online/offline):
  −
  10.20.30.0/24: 254/1/0
  −
Listening IP addresses:
  −
  84.xxx.xxx.xxx
  −
  192.168.11.1
  −
  fd93:51e6:6fe8::1
  −
Connections:
  −
  HUB-HUB_c:  %any...%any  IKEv2
  −
  HUB-HUB_c:  local:  uses pre-shared key authentication
  −
  HUB-HUB_c:  remote: uses pre-shared key authentication
  −
  HUB-HUB_c:  child:  0.0.0.0/0 === dynamic TUNNEL
  −
Security Associations (1 up, 0 connecting):
  −
  HUB-HUB_c[2]: ESTABLISHED 74 minutes ago, 84.xxx.xxx.xxx[84.xxx.xxx.xxx]...88.xxx.xxx.xxx[192.168.86.197]
  −
  HUB-HUB_c[2]: IKEv2 SPIs: ded11f31c20352dc_i 58ebc8d96264c21e_r*, pre-shared key reauthentication in 89 minutes
  −
  HUB-HUB_c[2]: IKE proposal: AES_CBC_256/HMAC_SHA2_512_256/PRF_HMAC_SHA2_512/ECP_521
  −
  HUB-HUB_c{3}:  INSTALLED, TUNNEL, reqid 1, ESP in UDP SPIs: c27cb140_i c7382615_o
  −
  HUB-HUB_c{3}:  AES_CBC_128/HMAC_SHA2_256_128/ECP_521, 215536 bytes_i (1981 pkts, 1s ago), 126021 bytes_o (499 pkts, 1s ago), rekeying in 14 minutes
  −
  HUB-HUB_c{3}:  0.0.0.0/0 === 10.20.30.1/32
  −
</pre>
     −
<pre> /tmp/ipsec/ipsec.conf </pre> command output:
+
Also, you will need to '''add a Publisher''':
<pre>
  −
root@Teltonika-RUTX12:~# cat /tmp/ipsec/ipsec.conf
  −
# generated by /etc/init.d/ipsec
  −
version 2
     −
conn HUB-HUB_c
+
#Press '''''<nowiki/>'+'''''' button on the top right corner
  left=%any
+
#Select '''''<nowiki/>'Publisher''''''
  right=%any
+
#In the topic field enter '''''<nowiki/>'request''''''
  leftfirewall=yes
+
#In the message field enter message, for this example '''''<nowiki/>'Getting temperature'''''' is used
  rightfirewall=no
+
#Press '''''<nowiki/>'Publish'''''' button
  ikelifetime=3h
  −
  lifetime=1h
  −
  margintime=9m
  −
  keyingtries=3
  −
  dpdaction=none
  −
  dpddelay=30s
  −
  dpdtimeout=90s
  −
  leftauth=psk
  −
  rightauth=psk
  −
  rightsourceip=10.20.30.0/24
  −
  auto=start
  −
  leftsubnet=0.0.0.0/0
  −
  rightdns=9.9.9.9
  −
  aggressive=no
  −
  forceencaps=no
  −
  type=tunnel
  −
  keyexchange=ikev2
  −
  esp=aes128-sha256-ecp521!
  −
  ike=aes256-sha512-ecp521!
  −
</pre>
     −
===RUT2 (SPOKE) side===
+
[[File:Flespi publisher.png|border|class=tlt-border|495x238px]]  [[File:Flespi publisher setup.png|border|class=tlt-border|494x239px]]
 +
====Flespi Subscriber output====
 
----
 
----
 +
Check the response in the '''''<nowiki/>'Subscriber'''''' tab, you should receive a message similar to the one below.
   −
<pre>
  −
root@Teltonika-RUT955:~# ipsec statusall
  −
Status of IKE charon daemon (strongSwan 5.9.2, Linux 5.4.229, mips):
  −
  uptime: 23 hours, since Mar 20 12:21:06 2023
  −
  worker threads: 11 of 16 idle, 5/0/0/0 working, job queue: 0/0/0/0, scheduled: 9
  −
  loaded plugins: charon aes des sha2 sha1 md4 md5 random nonce x509 revocation constraints pubkey pkcs1 pkcs8 pgp pem openssl gmp xcbc hmac kernel-netlink socket-default stroke vici updown eap-identity eap-mschapv2 xauth-generic
  −
Listening IP addresses:
  −
  192.168.86.197
  −
  192.168.9.1
  −
  fd35:98cd:61f0::1
  −
Connections:
  −
passth_SPOKE_ph2_1_lan:  %any...%any  IKEv1/2
  −
passth_SPOKE_ph2_1_lan:  local:  uses public key authentication
  −
passth_SPOKE_ph2_1_lan:  remote: uses public key authentication
  −
passth_SPOKE_ph2_1_lan:  child:  192.168.9.0/24 === 192.168.9.0/24 PASS
  −
SPOKE-SPOKE_c:  %any...84.15.162.30  IKEv2
  −
SPOKE-SPOKE_c:  local:  uses pre-shared key authentication
  −
SPOKE-SPOKE_c:  remote: [84.15.162.30] uses pre-shared key authentication
  −
SPOKE-SPOKE_c:  child:  dynamic === 0.0.0.0/0 TUNNEL
  −
Shunted Connections:
  −
passth_SPOKE_ph2_1_lan:  192.168.9.0/24 === 192.168.9.0/24 PASS
  −
Security Associations (1 up, 0 connecting):
  −
SPOKE-SPOKE_c[431]: ESTABLISHED 77 minutes ago, 192.168.86.197[192.168.86.197]...84.15.162.30[84.15.162.30]
  −
SPOKE-SPOKE_c[431]: IKEv2 SPIs: ded11f31c20352dc_i* 58ebc8d96264c21e_r, pre-shared key reauthentication in 77 minutes
  −
SPOKE-SPOKE_c[431]: IKE proposal: AES_CBC_256/HMAC_SHA2_512_256/PRF_HMAC_SHA2_512/ECP_521
  −
SPOKE-SPOKE_c{14}:  INSTALLED, TUNNEL, reqid 1, ESP in UDP SPIs: c7382615_i c27cb140_o
  −
SPOKE-SPOKE_c{14}:  AES_CBC_128/HMAC_SHA2_256_128/ECP_521, 136768 bytes_i (536 pkts, 6s ago), 235975 bytes_o (2169 pkts, 1s ago), rekeying in 13 minutes
  −
SPOKE-SPOKE_c{14}:  10.20.30.1/32 === 0.0.0.0/0
  −
</pre>
  −
  −
  −
<pre>
  −
root@Teltonika-RUT955:~# cat /tmp/ipsec/ipsec.conf
  −
# generated by /etc/init.d/ipsec
  −
version 2
  −
  −
conn passth_SPOKE_ph2_1_lan
  −
  type=passthrough
  −
  leftsubnet=192.168.9.1/24
  −
  rightsubnet=192.168.9.1/24
  −
  auto=route
     −
conn SPOKE-SPOKE_c
+
[[File:Flespi response.png|border|center|class=tlt-border|500x305px]]
  left=%any
  −
  right=84.15.162.30
  −
  leftsourceip=%config
  −
  leftfirewall=yes
  −
  rightfirewall=no
  −
  ikelifetime=3h
  −
  lifetime=1h
  −
  margintime=9m
  −
  keyingtries=3
  −
  dpdaction=none
  −
  dpddelay=30s
  −
  dpdtimeout=90s
  −
  leftauth=psk
  −
  rightauth=psk
  −
  rightsubnet=0.0.0.0/0
  −
  auto=start
  −
  aggressive=no
  −
  forceencaps=no
  −
  type=tunnel
  −
  keyexchange=ikev2
  −
  esp=aes128-sha256-ecp521!
  −
  ike=aes256-sha512-ecp521!
  −
</pre>
        −
== See also ==
+
In the output, we can see that router's '''temperature''' is '''44 degrees Celsius'''.
   −
== External links ==
+
==See Also==
 +
*[[RUT955 Monitoring via Modbus#Get Parameters]]
 +
*[[RUT955_Modbus#MQTT_Gateway|MQTT Gateway and Modbus]]
 +
==External links==
 +
[https://flespi.io/#/ Flespi.io]