Skip to content

Commit 359742a

Browse files
brocaarbrocaar
committed
Update Multitech Conduit documentation.
1 parent baca17a commit 359742a

File tree

1 file changed

+132
-201
lines changed

1 file changed

+132
-201
lines changed

‎docs/content/install/gateway/multitech.md‎

Lines changed: 132 additions & 201 deletions
Original file line numberDiff line numberDiff line change
@@ -9,55 +9,150 @@ menu:
99

1010
### Multitech Conduit
1111

12-
There are Multitech Conduit models that differ in the operating system and
13-
versions of software. In general, the goal is to set up the Conduits so that
14-
they are running in a packet forwarding mode, forwarding packets to the
15-
lora-gateway-bridge. The difference in how this is done can be significant.
12+
After completing this steps, you have a Multitech Conduit running both the
13+
packet-forwarder and LoRa Gateway bridge. The packet-forwarder will forwards
14+
the UDP data to `localhost:1700` and the LoRa Gateway Bridge will forward
15+
this data as JSON over MQTT to a MQTT broker. See below:
1616

17-
Two of the Multitech Conduit platforms are the AEP and the mLinux varieties.
18-
The mLinux version comes in a case suitable for use outdoors. But once the
19-
box is removed from the case, the two versions look identical. Here are a few
20-
ways to tell them apart:
17+
![Gateway Pieces and Connections](/lora-gateway-bridge/img/MultitechGatewaySettings.png)
18+
19+
There are two different Multitech Conduit firmware versions: mLinux and AEP.
20+
The AEP version comes with a web-interface and IBM Node-RED pre-installed.
21+
The mLinux version provides an open Linux development environment and is
22+
recommended when complete (firmware) control is preferred.
23+
24+
If you don't know the firmware version, here are a couple of ways to tell
25+
them apart:
2126

2227
1. When logging in via the serial port behind the Multitech logo cover, they
2328
display the type of box they are.
24-
2. The AEP model supports a web interface for settings. The mLinux version
25-
does not.
26-
3. Because of the difference in step 2, startup scripts in /etc/init.d get
27-
settings from the web server using curl. In particular, if curl is used in
28-
/etc/init.d/lora-network-server, then you are on an AEP device.
29-
3. The AEP model ships with the default login/password as admin/admin. The
29+
30+
2. The AEP model ships with the default login/password as admin/admin. The
3031
mLinux version uses root/root.
3132

32-
In either case, you'll want to obtain the IP address for the device. This can
33+
Please refer to [http://www.multitech.net/developer/products/multiconnect-conduit-platform/](http://www.multitech.net/developer/products/multiconnect-conduit-platform/)
34+
for more documentation on on the Multitech Conduit.
35+
36+
**Note:** It is possible to install mLinux on an AEP Conduit version following the
37+
steps below. This is recommended when you don't rely on any software provided by
38+
the AEP firmware.
39+
40+
#### Getting the IP address
41+
42+
Before continuing, you'll want to obtain the IP address of the Conduit. This can
3343
be done using a serial connection from a computer using a USB-to-microUSB cable,
3444
connecting to the plug behind the Multitech logo placard. Plug the device into
3545
your network, provide power, and let it boot until the "STATUS" light is
3646
blinking in aheartbeat pattern. Connect to the device via a serial terminal
3747
program. Once logged in, issue the command "ifconfig" to get the IP address of
38-
the eth0 connection. Note that is the IP address is 192.168.2.1, the device is
48+
the eth0 connection. Note that if the IP address is `192.168.2.1`, the device is
3949
likely configured to be a DHCP server. In this case, edit the file
40-
/etc/network/interfaces, change the line that says, “iface eth0 inet static” to
41-
“iface eth0 inet dhcp”, and comment out the lines specifying the IP Address and
42-
netmask by adding a “#” at the beginning of each line:
43-
#address 192.168.2.1
44-
#netmask 255.255.255.0
45-
Then reboot, and obtain the issued IP address as outlined above.
46-
47-
The basic setup steps are outlined below for the packet forwarder for each
48-
device, followed by `Install lora-gateway-bridge` below. This image shows how
49-
the components connect to each other, and what some of the various settings
50-
represent:
50+
`/etc/network/interfaces`, change the line that says, `iface eth0 inet static` to
51+
`iface eth0 inet dhcp`, and comment out the lines specifying the IP Address and
52+
netmask by adding a `#` at the beginning of each line:
5153

52-
![Gateway Pieces and Connections](/lora-gateway-bridge/img/MultitechGatewaySettings.png)
54+
```text
55+
# address 192.168.2.1
56+
# netmask 255.255.255.0
57+
```
5358

54-
#### Multitech Conduit AEP
59+
Then execute `/etc/init.d/networking restart`, and obtain the issued IP address
60+
as outlined above.
61+
62+
#### Upgrading / migrating from AEP to the latest mLinux
63+
64+
The suggested way to setup the packet-forwarder and LoRa Gateway Bridge on a
65+
Multitech Conduit is by using the base mLinux firmware image
66+
(`mlinux-base-*.jffs2`). This firmware
67+
image installs the minimal amount of software needed to boot the Conduit,
68+
but does not contain any other software which could conflict with your setup.
69+
The latest firmware version can be downloaded from: [http://www.multitech.net/mlinux/images/mtcdt/](http://www.multitech.net/mlinux/images/mtcdt/).
70+
71+
The [Flashing mLinux Firmware](http://www.multitech.net/developer/software/mlinux/using-mlinux/flashing-mlinux-firmware-for-conduit/)
72+
instructions cover both upgrading mLinux to a newer version and converting an
73+
AEP model into a mLinux model. In both the AEP migrate and mLinux upgrade you
74+
can use the **Using Auto-Flash During Reboot** steps. **Again, make sure to
75+
use the `mlinux-base*.jffs2` image!**
76+
77+
#### mLinux: Setting up the packet-forwarder (MTAC-LORA-H)
78+
79+
1. Log in using SSH or use the USB to serial interface.
80+
81+
2. Download the latest `lora-packet-forwarder` `*.ipk` package
82+
from [https://dl.loraserver.io/multitech/conduit/](https://dl.loraserver.io/multitech/conduit/).
83+
Example:
84+
```text
85+
root@mtcdt:~# wget https://dl.loraserver.io/multitech/conduit/lora-packet-forwarder_4.0.1-r5.0_mtcdt.ipk
86+
```
87+
88+
3. Now this `.ipk` package is stored on the Conduit, you can install it
89+
using the `opkg` package-manager utility. Example (assuming the same
90+
`.ipk` file):
91+
```text
92+
root@mtcdt:~# opkg install lora-packet-forwarder_4.0.1-r5.0_mtcdt.ipk
93+
```
94+
95+
4. Start the packet-forwarder and enable it to start on boot. Note that the
96+
`-ap1` or `-ap2` suffix refers to the slot in which your `MTAC-LORA-H` card
97+
is present. In case you have two `MTAC-LORA-H` cards, this allows you to start
98+
two packet-forwarder instances with each using their own configuration.
99+
Example:
100+
```text
101+
root@mtcdt:~# /etc/init.d/lora-packet-forwarder-ap1 start
102+
root@mtcdt:~# /update-rc.d lora-packet-forwarder-ap1 defaults
103+
```
104+
105+
**Note:** on the first start of the packet-forwarder it will detect for you
106+
the version of your `MTAC-LORA-H` cards (868 or 915) and if your Conduit
107+
has an onboard GPS. It will then automatically generate the correct
108+
configuration for you.
109+
110+
Configuration is stored in `/var/config/lora-packet-forwarder-ap1` and
111+
`/var/config/lora-packet-forwarder-ap2` directories and can be modified after
112+
the first start.
113+
114+
The build recipe of the `.ipk` package can be found at:
115+
[https://github.com/brocaar/loraserver-yocto](https://github.com/brocaar/loraserver-yocto).
116+
117+
#### mLinux / AEP: Setting up the LoRa Gateway Bridge
118+
119+
1. Log in using SSH or use the USB to serial interface.
120+
121+
2. Download the latest `lora-gateway-bridge` `.ipk` package from:
122+
[https://dl.loraserver.io/multitech/conduit/](https://dl.loraserver.io/multitech/conduit/).
123+
Example (assuming you want to install `lora-gateway-bridge_2.2.0-r2.0_arm926ejste.ipk`):
124+
```text
125+
admin@mtcdt:~# wget https://dl.loraserver.io/multitech/conduit/lora-gateway-bridge_2.2.0-r2.0_arm926ejste.ipk
126+
```
127+
128+
3. Now this `.ipk` package is stored on the Conduit, you can install it
129+
using the `opkg` package-manager utility. Example (assuming the same
130+
`.ipk` file):
131+
```text
132+
admin@mtcdt:~# opkg install lora-gateway-bridge_2.2.0-r2.0_arm926ejste.ipk
133+
```
134+
135+
4. Update the MQTT connection details so that LoRa Gateway Bridge is able to
136+
connect to your MQTT broker. You will find the configuration file in the
137+
`/var/config/lora-gateway-bridge` directory.
138+
139+
5. Start LoRa Gateway Bridge and ensure it will be started on boot.
140+
Example:
141+
```text
142+
uadmin@mtcdt:~# /etc/init.d/lora-gateway-bridge start
143+
uadmin@mtcdt:~# update-rc.d lora-packet-forwarder defaults
144+
```
145+
146+
6. Be sure to add the gateway to the lora-app-server.
147+
See [Gateways](/lora-app-server/use/gateways/).
148+
149+
#### AEP: Setting up the packet-forwarder
55150

56151
Use the web interface to set up the Conduit's packet forwarder. By default,
57152
the connection will not be “secure” over https because the device uses a self-
58153
signed certificate. Accept the certificate to proceed.
59-
60-
1. Log in to the interface.
154+
155+
1. Log in to the web-interface.
61156
2. On the home screen, you should be able to see information about the version of the LoRa card. Find the corresponding section on the web page:
62157
http://www.multitech.net/developer/software/lora/aep-lora-packet-forwarder/
63158
This page has links to basic configuration for each card version which you
@@ -108,189 +203,25 @@ signed certificate. Accept the certificate to proceed.
108203
15. Select “Submit”.
109204
16. Select the “Save and Restart” option on the left menu.
110205

111-
#### Multitech Conduit mLinux
112-
113-
The latest Conduit mLinux version makes setting up the device pretty straight
114-
forward. Start by disabling the lora-network-server and enabling the
115-
lora-packet-forwarder. This is done by:
116-
117-
1. Create the file /var/config/lora/global_conf.json and create the settings by
118-
referencing the information at
119-
http://www.multitech.net/developer/software/lora/conduit-mlinux-convert-to-basic-packet-forwarder/
120-
and be sure to update the settings as described in step 14 for the
121-
Conduit AEP instructions above.
122-
123-
2. Edit /etc/defaults/lora-network-server and change ENABLED="yes" to
124-
ENABLED="no".
125-
3. Edit /etc/defaults/lora-packet-forwarder and change ENABLED="no" to
126-
ENABLED="yes".
127-
4. Ensure that the lora-packet-forwarder will run after reboot by issuing the
128-
command:
129-
130-
`update-rc.d lora-packet-forwarder defaults`
131-
132-
#### Multitech Conduit - Install lora-gateway-bridge
133-
134-
Now you will want to set up the lora-gateway-bridge on the device. The
135-
following are suggested files and locations:
136-
137-
1. Download the arm build of the lora-gateway-bridge (see `Downloads` on the
138-
left), and extract it to `/opt/lora-gateway-bridge/bin/`. Note that at the
139-
time of this writing, the Multitech boxes are all running 32-bit arm
140-
processors. This can be verified by issuing the command `uname -a`, where
141-
'armv7' or lower in the output represents 32-bit arm processors, and 'armv8'
142-
or higher represents 64-bit arm processors. Be sure to download the
143-
appropriate binary package for the system processor.
144-
145-
2. Create a script (or download [here](/lora-gateway-bridge/scripts/multitech/runGateway.sh)) to run the application
146-
with the appropriate settings for your installation in
147-
/opt/lora-gateway-bridge/bin/runGateway.sh (ensure that the script is
148-
executable `chmod +x /opt/lora-gateway-bridge/bin/runGateway.sh`):
149-
150-
```
151-
#!/bin/bash
152-
# Starts the gateway code
153-
154-
# Accept a single parameter of where to put the pid of the actual lora-app-server
155-
# process.
156-
if [ "$#" -ge 1 ]; then
157-
PIDFILE=$1
158-
else
159-
PIDFILE=
160-
fi
161-
162-
# These placeholder values will be replaced by the install script at startup.
163-
# A change in these values will require a manual change here or a reinstall of
164-
# the lora-gateway-bridge package.
165-
export MQTT_SERVER="ssl://some.server.net"
166-
export MQTT_USERNAME="username"
167-
export MQTT_PASSWORD="password"
168-
169-
# Start the log file by identifying the device. Just print it out, too,
170-
# so we can find it in the system startup output.
171-
export LORA_CARD_MAC=$(mts-io-sysfs show lora/eui)
172-
export LORA_CARD_MAC=${LORA_CARD_MAC//:/}
173-
echo "Lora Gateway Bridge running on device with MAC $LORA_CARD_MAC"
174-
echo "Lora Gateway Bridge running on device with MAC $LORA_CARD_MAC" > /var/log/lora-gateway-bridge.log
175-
176-
/opt/lora-gateway-bridge/bin/lora-gateway-bridge --log-level 5 >> /var/log/lora-gateway-bridge.log 2>&1 &
177-
PID=$!
178-
if [[ $PIDFILE != "" ]]; then
179-
echo $PID > $PIDFILE
180-
fi
181-
182-
```
183-
Modify the MQTT_* values to reflect the settings for your system.
184-
185-
3. Then create a startup script (or download [here](/lora-gateway-bridge/scripts/multitech/lora-gateway-bridge)) in
186-
/etc/init.d/lora-gateway-bridge (ensure that the script is executable
187-
`chmod +x /etc/init.d/lora-gateway-bridge`):
188-
189-
190-
```
191-
#!/bin/bash
192-
#
193-
# A SysV init script for the lora-gateway-bridge
194-
#
195-
### BEGIN INIT INFO
196-
# Provides: lora-gateway-bridge
197-
# Required-Start: $syslog $network
198-
# Required-Stop: $syslog $network
199-
# Should-Start: $local_fs
200-
# Should-Stop: $local_fs
201-
# Default-Start: 2 3 4 5
202-
# Default-Stop: 0 1 6
203-
# Short-Description: lora-gateway-bridge
204-
# Description: Sends lora messages from the gateway to the open source server..
205-
### END INIT INFO
206-
#
207-
PIDFILE=/var/run/lora-gateway-bridge.pid
208-
NAME=lora-gateway-bridge
209-
STARTSCRIPT=/opt/lora-gateway-bridge/bin/runGateway.sh
210-
RETVAL=0
211-
212-
start() {
213-
if [ -f $PIDFILE ]; then
214-
echo "$NAME is already running"
215-
else
216-
echo "Starting $NAME"
217-
# Start the server, passing in the file to get the PID
218-
$STARTSCRIPT $PIDFILE
219-
RETVAL=$?
220-
fi
221-
}
222-
223-
stop() {
224-
if [ -f $PIDFILE ]; then
225-
echo "Shutting down $NAME"
226-
kill `cat $PIDFILE`
227-
# Get rid of the pidfile so we don't assume it's running any more.
228-
rm -f $PIDFILE
229-
RETVAL=$?
230-
else
231-
echo "$NAME is not running."
232-
fi
233-
}
234-
235-
restart() {
236-
echo "Restarting $NAME"
237-
stop
238-
start
239-
}
240-
241-
status() {
242-
if [ -f $PIDFILE ]; then
243-
echo "Status for $NAME:"
244-
ps -ef `cat $PIDFILE`
245-
RETVAL=$?
246-
else
247-
echo "$NAME is not running"
248-
fi
249-
}
250-
251-
case "$1" in
252-
start)
253-
start
254-
;;
255-
stop)
256-
stop
257-
;;
258-
status)
259-
status
260-
;;
261-
restart)
262-
restart
263-
;;
264-
*)
265-
echo "Usage: {start|stop|status|restart}"
266-
exit 1
267-
;;
268-
esac
269-
exit $RETVAL
270-
```
271-
272-
4. Make sure the script start on reboot:
273-
274-
`update-rc.d lora-gateway-bridge defaults`
275-
276206
5. Be sure to add the gateway to the lora-app-server. See [here](/lora-app-server/use/gateways/).
277207

278208
6. Finally, restart the system to get everything running.
279209

280-
A few words about troubleshooting:
210+
#### Troubleshooting
281211

282212
Be sure to check log files to see what is happening. Logs can be found on the
283-
gateway in the directory `/var/log/`.
213+
gateway in the directory `/var/log/`.
284214

285215
Also, if the gateway seems to be running, but no statistics are
286-
appearing in lora-app-server, you may be experiencing a known bug with the
216+
appearing in LoRa App Server, you may be experiencing a known bug with the
287217
Multitech packet forwarding code. On these systems, we need to swap out the
288-
application that runs for packet formwarding. The following should resolve the issue:
218+
application that runs for packet formwarding. The following should resolve the issue:
219+
289220
```
290221
$ cd /opt/lora
291222
$ mv basic_pkt_fwd-usb basic_pkt_fwd-usb.orig
292223
$ ln -s gps_pkt_fwd-usb basic_pkt_fwd-usb
293224

294225
```
295226
296-
Once these steps have been performed, reboot.
227+
Also see [debugging]({{<ref "install/debug.md">}}).

0 commit comments

Comments
 (0)