Skip to content

Commit 978d950

Browse files
brocaarbrocaar
committed
Update gateway docs and add debug steps.
1 parent 3efb329 commit 978d950

File tree

5 files changed

+246
-53
lines changed

5 files changed

+246
-53
lines changed

‎docs/content/install/debug.md

Lines changed: 161 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,161 @@
1+
---
2+
title: Debugging
3+
menu:
4+
main:
5+
parent: install
6+
weight: 6
7+
---
8+
9+
## Debugging
10+
11+
The follwing steps can be used to debug any LoRa Gateway Bridge related issues.
12+
13+
### Receiving MQTT messages
14+
15+
To validate that the LoRa Gateway Bridge is publishing LoRa frames to the
16+
MQTT broker, you can subscribe to the `gateway/+/rx` MQTT topic. When using
17+
the `mosquitto_sub` utility, you can execute the following command:
18+
19+
```bash
20+
mosquitto_sub -v -t "gateway/+/rx"
21+
```
22+
23+
Of course you will only see data when the gateway is receiving LoRa frames.
24+
Make sure that your node is sending some data.
25+
26+
When you don't see any frames appearing, this could be caused by the following issues:
27+
28+
* LoRa Gateway Bridge does not receive data from the packet-forwarder
29+
* The MQTT credentials / authorizations are invalid (the user is not authorized
30+
to subscribe to the MQTT topic)
31+
32+
### Is LoRa Gateway Bridge receiving data
33+
34+
To validate that the LoRa Gateway Bridge is receiving, you can take a look
35+
at the LoRa Gateway Bridge logs. How to retrieve the logs depends on how you
36+
installed the LoRa Gateway Bridge. When you followed the [Debian / Ubuntu]({{<ref "install/debian.md">}})
37+
installation steps, this is either:
38+
39+
* `journalctl -f -n 100 -u lora-gateway-bridge`
40+
* `tail -f -n 100 /var/log/lora-gateway-bridge/lora-gateway-bridge.log`
41+
42+
With an interval of a couple of seconds, the following lines should appear (`PullData` / `PullACK`):
43+
44+
```text
45+
level=info msg="gateway: received udp packet from gateway" addr=127.0.0.1:34268 protocol_version=2 type=PullData
46+
level=info msg="gateway: sending udp packet to gateway" addr=127.0.0.1:34268 protocol_version=2 type=PullACK
47+
level=info msg="gateway: received udp packet from gateway" addr=127.0.0.1:34268 protocol_version=2 type=PullData
48+
level=info msg="gateway: sending udp packet to gateway" addr=127.0.0.1:34268 protocol_version=2 type=PullACK
49+
level=info msg="gateway: received udp packet from gateway" addr=127.0.0.1:43827 protocol_version=2 type=PushData
50+
level=info msg="gateway: sending udp packet to gateway" addr=127.0.0.1:43827 protocol_version=2 type=PushACK
51+
```
52+
53+
The packet-forwarder sends every couple of seconds a ping (`PullData`) to which
54+
the LoRa Gateway Bridge must respond (`PullACK`).
55+
56+
When you don't see these logs, this could be caused by the following issues:
57+
58+
* The packet-forwarder is not running
59+
* The packet-forwarder is forwarding to a different host / port
60+
* Firewall / NAT issue (in case the packet-forwarder and LoRa Gateway Bridge are not installed on the same device)
61+
62+
When you do see these logs, but you don't receive any MQTT messages, this could
63+
be caused by:
64+
65+
* The MQTT user is not authorized to publish data to the MQTT topic or, the MQTT
66+
user for subscribing is not authorized to subscribe to the MQTT topic.
67+
* The node is sending on a frequency that the packet-forwarder is not
68+
configured for.
69+
70+
### Is the packet-forwarder running
71+
72+
To validate that the packet-forwarder is running, you could execute the
73+
following command on your gateway:
74+
75+
```bash
76+
# when the LoRa Gateway Bridge is running on the same device, add -i lo
77+
sudo tcpdump -AUq -i lo port 1700
78+
79+
# when the LoRa Gateway Bridge is running somewhere else
80+
sudo tcpdump -AUq port 1700
81+
```
82+
83+
This should output something like:
84+
85+
```text
86+
11:42:00.114726 IP localhost.34268 > localhost.1700: UDP, length 12
87+
E..(..@.@."................'.....UZ.....
88+
11:42:00.130292 IP localhost.1700 > localhost.34268: UDP, length 4
89+
E.. ..@.@.".....................
90+
11:42:10.204723 IP localhost.34268 > localhost.1700: UDP, length 12
91+
E..(.&@.@..................'.x...UZ.....
92+
11:42:10.206503 IP localhost.1700 > localhost.34268: UDP, length 4
93+
E.. .'@.@....................x..
94+
11:42:10.968420 IP localhost.43827 > localhost.1700: UDP, length 113
95+
E....h@.@............3...y.......UZ.....{"stat":{"time":"2017-09-11 11:42:10 GMT","rxnb":0,"rxok":0,"rxfw":0,"ackr":100.0,"dwnb":0,"txnb":0}}
96+
11:42:10.970702 IP localhost.1700 > localhost.43827: UDP, length 4
97+
E.. .i@.@..b...........3........
98+
11:42:20.284752 IP localhost.34268 > localhost.1700: UDP, length 12
99+
E..(..@.@..................'.....UZ.....
100+
11:42:20.289256 IP localhost.1700 > localhost.34268: UDP, length 4
101+
E.. ..@.@.......................
102+
11:42:30.364780 IP localhost.34268 > localhost.1700: UDP, length 12
103+
E..( .@.@..................'.S7..UZ.....
104+
11:42:30.366310 IP localhost.1700 > localhost.34268: UDP, length 4
105+
E.. .@.@....................S7.
106+
```
107+
108+
What we see in this log:
109+
110+
* `localhost.34268 > localhost.1700`: packet sent from the packet-forwarder to the LoRa Gateway Bridge
111+
* `localhost.1700 > localhost.34268`: packet sent from the LoRa Gateway Bridge to the packet-forwarder
112+
113+
A log example where the packet-forwarder is sending data, but not receiving
114+
any data (caused by a firewall / NAT issue?):
115+
116+
```text
117+
11:47:22.724729 IP localhost.34268 > localhost.1700: UDP, length 12
118+
E..([.@.@..................'.....UZ.....
119+
11:47:32.804724 IP localhost.34268 > localhost.1700: UDP, length 12
120+
E..(].@.@..................'.!...UZ.....
121+
11:47:40.964220 IP localhost.43827 > localhost.1700: UDP, length 113
122+
E...`/@.@............3...y...s...UZ.....{"stat":{"time":"2017-09-11 11:47:40 GMT","rxnb":0,"rxok":0,"rxfw":0,"ackr":100.0,"dwnb":0,"txnb":0}}
123+
11:47:42.884727 IP localhost.34268 > localhost.1700: UDP, length 12
124+
E..(`f@.@..\...............'.-C..UZ.....
125+
```
126+
127+
When you don't see any of these, this could be caused by the following issues:
128+
129+
* The packet-forwarder is not running
130+
* The packet-forwarder is forwarding to a different host / port
131+
132+
### Where is the packet-forwarder sending data to
133+
134+
Inspect the `local_conf.json` of the packet-forwarder running on your gateway.
135+
You might need to refer to your gateway manual to find out where you can locate
136+
this file. This file could contain the following content:
137+
138+
```json
139+
{
140+
"gateway_conf": {
141+
...
142+
"serv_port_down": 1700,
143+
"serv_port_up": 1700,
144+
"server_address": "localhost",
145+
...
146+
}
147+
}
148+
```
149+
150+
What we learn from this file is that:
151+
152+
* It uses port `1700` (default port used by LoRa Gateway Bridge)
153+
* It sends data to `localhost` (when LoRa Gateway Bridge is installed on the same device)
154+
155+
Make sure the ports and `server_address` are correct. In case LoRa Gateway
156+
Bridge is not running on the same device, you need to replace this with the
157+
correct hostname or IP of your LoRa Gateway Bridge instance. After making any
158+
changes, don't forget to restart the packet-forwarder.
159+
160+
See [https://github.com/Lora-net/packet_forwarder/tree/master/lora_pkt_fwd](https://github.com/Lora-net/packet_forwarder/tree/master/lora_pkt_fwd)
161+
for more information about the packet-forwarder.

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

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
---
2+
title: On the gateway
3+
menu:
4+
main:
5+
parent: install
6+
weight: 3
7+
identifier: gateway
8+
---
9+
10+
## Install on the gateway
11+
12+
### Vendors
13+
14+
Instructions are available for the following vendors:
15+
16+
* [Kerlink]({{<relref "kerlink.md">}})
17+
* [Multitech]({{<relref "multitech.md">}})
18+
19+
For Raspberry Pi / Rasbian based gateways, please refer the
20+
[Debian / Ubuntu]({{< ref "install/debian.md" >}}) installation instructions.
21+
22+
### Contribute
23+
24+
Help us making the above list complete! Is the gateway that you are using not
25+
listed in the above vendors list? Or are the steps described outdated?
26+
Contributing is easy and can be done in the following ways:
27+
28+
* Fork the [lora-gateway-bridge](https://github.com/brocaar/lora-gateway-bridge)
29+
repository (documentation can be found under `docs/content/install/gateway`),
30+
make your changes and create a pull-request.
31+
* Propose the installation instructions in the [LoRa Server project forum](https://forum.loraserver.io).

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

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
---
2+
title: Kerlink
3+
menu:
4+
main:
5+
parent: gateway
6+
---
7+
8+
## Kerlink
9+
10+
### Kerlink IOT station
11+
12+
The Kerlink IOT station has a meganism to start "custom" application on boot.
13+
These steps will install the LoRa Gateway Bridge ARM build on the Kerlink.
14+
15+
1. Create the the directories needed:
16+
17+
`mkdir -p /mnt/fsuser-1/lora-gateway-bridge/bin`
18+
19+
2. Download and extract the LoRa Gateway Bridge ARM binary into the above
20+
directory. See [downloads]({{< ref "overview/downloads.md" >}}).
21+
Make sure the binary is marked as executable.
22+
23+
3. Save the following content as `/mnt/fsuser-1/lora-gateway-bridge/start.sh`:
24+
25+
```bash
26+
#!/bin/bash
27+
28+
LOGGER="logger -p local1.notice"
29+
30+
# mosquitto
31+
iptables -A INPUT -p tcp --sport 1883 -j ACCEPT
32+
33+
/mnt/fsuser-1/lora-gateway-bridge/bin/lora-gateway-bridge --mqtt-server tcp://YOURSERVER:1883 2>&1 | $LOGGER &
34+
```
35+
36+
Make sure to replace `YOURSERVER` with the hostname / IP of your MQTT
37+
broker. Also make sure the file is marked as executable.
38+
39+
4. Save the following content as `/mnt/fsuser-1/lora-gateway-bridge/manifest.xml`:
40+
41+
```xml
42+
<?xml version="1.0"?>
43+
<manifest>
44+
<app name="lora-gateway-bridge" appid="1" binary="start.sh" >
45+
<start param="" autostart="y"/>
46+
<stop kill="9"/>
47+
</app>
48+
</manifest>
49+
```

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

Lines changed: 4 additions & 52 deletions
Original file line numberDiff line numberDiff line change
@@ -1,17 +1,11 @@
11
---
2-
title: On the gateway
2+
title: Multitech
33
menu:
44
main:
5-
parent: install
6-
weight: 3
5+
parent: gateway
76
---
87

9-
## Install on the gateway
10-
11-
### Raspberry Pi / Rasbian based gateway
12-
13-
For Raspberry Pi / Rasbian based gateways, please refer the
14-
[Debian / Ubuntu]({{< relref "debian.md" >}}) installation instructions.
8+
## Multitech
159

1610
### Multitech Conduit
1711

@@ -258,46 +252,4 @@ following are suggested files and locations:
258252
259253
`update-rc.d lora-gateway-bridge defaults`
260254
261-
5. Finally, restart the system to get everything running.
262-
263-
264-
### Kerlink IOT station
265-
266-
The Kerlink IOT station has a meganism to start "custom" application on boot.
267-
These steps will install the LoRa Gateway Bridge ARM build on the Kerlink.
268-
269-
1. Create the the directories needed:
270-
271-
`mkdir -p /mnt/fsuser-1/lora-gateway-bridge/bin`
272-
273-
2. Download and extract the LoRa Gateway Bridge ARM binary into the above
274-
directory. See [downloads]({{< ref "overview/downloads.md" >}}).
275-
Make sure the binary is marked as executable.
276-
277-
3. Save the following content as `/mnt/fsuser-1/lora-gateway-bridge/start.sh`:
278-
279-
```bash
280-
#!/bin/bash
281-
282-
LOGGER="logger -p local1.notice"
283-
284-
# mosquitto
285-
iptables -A INPUT -p tcp --sport 1883 -j ACCEPT
286-
287-
/mnt/fsuser-1/lora-gateway-bridge/bin/lora-gateway-bridge --mqtt-server tcp://YOURSERVER:1883 2>&1 | $LOGGER &
288-
```
289-
290-
Make sure to replace `YOURSERVER` with the hostname / IP of your MQTT
291-
broker. Also make sure the file is marked as executable.
292-
293-
4. Save the following content as `/mnt/fsuser-1/lora-gateway-bridge/manifest.xml`:
294-
295-
```xml
296-
<?xml version="1.0"?>
297-
<manifest>
298-
<app name="lora-gateway-bridge" appid="1" binary="start.sh" >
299-
<start param="" autostart="y"/>
300-
<stop kill="9"/>
301-
</app>
302-
</manifest>
303-
```
255+
5. Finally, restart the system to get everything running.

‎docs/layouts/partials/menu.html

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,7 @@
1111
</a>
1212
<ul class="sub">
1313
{{ range .Children }}
14-
<li{{if $currentPage.IsMenuCurrent "main" . }} class="active"{{end}}><a href="{{.URL}}"> {{ .Name }} </a> </li>
14+
<li{{if $currentPage.IsMenuCurrent "main" . }} class="active"{{end}}{{if $currentPage.HasMenuCurrent "main" . }} class="active"{{end}}><a href="{{.URL}}"> {{ .Name }}</a></li>
1515
{{ end }}
1616
</ul>
1717
</li>

0 commit comments

Comments
 (0)