Skip to content

Commit 71bc4d1

Browse files
brocaarbrocaar
committed
Update getting started docs.
1 parent 8d10431 commit 71bc4d1

File tree

3 files changed

+142
-81
lines changed

3 files changed

+142
-81
lines changed

‎docs/deployment.md‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
# Deployment strategies
2+
3+
There are multiple ways that you can deploy the LoRa Gateway Bridge:
4+
5+
## Single instance
6+
7+
The most basic strategy is to connect all your gateways to a single instance
8+
of the LoRa Gateway Bridge.
9+
10+
## Multiple instances
11+
12+
To make the LoRa Gateway Bridge HA, you can run a cluster of instances
13+
(connecting to the same MQTT broker).
14+
**Important:** make sure that each gateway connection is always routed to the
15+
same instance!
16+
17+
## On each gateway
18+
19+
Depending on the capabilities of your gateway, you can deploy the LoRa Gateway
20+
Bridge on each of your gateways. This enables you to encrypt all traffic from
21+
your gateway by connecting to the MQTT broker over SSL/TLS.

‎docs/getting-started.md‎

Lines changed: 120 additions & 81 deletions
Original file line numberDiff line numberDiff line change
@@ -1,121 +1,156 @@
11
# Getting started
22

3-
## Strategies
3+
This getting started document describes the steps needed to setup LoRa Gateway
4+
bridge and all its requirements on Ubuntu 16.04 LTS. When using an other Linux
5+
distribution, you might need to adapt these steps slightly!
46

5-
There are multiple ways that you can deploy the LoRa Gateway Bridge:
7+
!!! warning
8+
This getting started guide does not cover setting up firewall rules! After
9+
setting up LoRa Server and its requirements, don't forget to configure
10+
your firewall rules.
611

7-
### Single instance
8-
9-
The most basic strategy is to connect all your gateways to a single instance
10-
of the LoRa Gateway Bridge.
11-
12-
### Multiple instances
13-
14-
To make the LoRa Gateway Bridge HA, you can run a cluster of instances
15-
(connecting to the same MQTT broker).
16-
**Important:** make sure that each gateway connection is always routed to the
17-
same instance!
18-
19-
### On each gateway
20-
21-
Depending on the capabilities of your gateway, you can deploy the LoRa Gateway
22-
Bridge on each of your gateways. This enables you to encrypt all traffic from
23-
your gateway by connecting to the MQTT broker over SSL/TLS.
12+
## LoRa Gateway with packet_forwarder
2413

14+
The [packet_forwarder](https://github.com/Lora-net/packet_forwarder/) is an
15+
application which runs on your gateway. It's responsibility is to:
2516

26-
## Requirements
17+
* forward received uplink packets (over UDP)
18+
* forward statistics (over UDP)
19+
* enqueue and transmit downlink packets (received over UDP)
2720

28-
Before you install the LoRa Gateway Bridge, make sure you've installed the
29-
following requirements:
21+
See the **Gateways** section in the menu for instructions about how to setup the
22+
packet_forwarder on your gateway. Is your gateway not in the list? Please
23+
consider contributing to this documentation by documenting the steps needed
24+
to set your gateway up and create a pull-request!
3025

31-
### MQTT broker
26+
## MQTT broker
3227

3328
LoRa Gateway Brige makes use of MQTT for communication with the gateways and
3429
applications. [Mosquitto](http://mosquitto.org/) is a popular open-source MQTT
3530
server. Make sure you install a **recent** version of Mosquitto (the Mosquitto
3631
project provides [repositories for various Linux distributions](http://mosquitto.org/download/)).
32+
Ubuntu 16.04 LTS already includes a recent version which can be installed with:
3733

38-
### LoRa Gateway with packet_forwarder
34+
```bash
35+
sudo apt-get install mosquitto
36+
```
3937

40-
The [packet_forwarder](https://github.com/Lora-net/packet_forwarder/) is an
41-
application which runs on your gateway. It's responsibility is to:
4238

43-
* forward received uplink packets (over UDP)
44-
* forward statistics (over UDP)
45-
* enqueue and transmit downlink packets (received over UDP)
39+
## Install LoRa Gateway Brige
4640

47-
See the **Gateways** section in the menu for instructions about how to setup the
48-
packet_forwarder on your gateway. Is your gateway not in the list? Please
49-
consider contributing to this documentation by documenting the steps needed
50-
to set your gateway up and create a pull-request!
41+
Create a system user for `gatewaybridge`:
5142

52-
## Installing the LoRa Gateway Brige
43+
```bash
44+
sudo useradd -M -r -s /bin/false gatewaybridge
45+
```
5346

54-
### Download
47+
Download and unpack a pre-compiled binary from the [releases](https://github.com/brocaar/lora-gateway-bridge/releases)
48+
page:
5549

56-
Download and unpack a pre-compiled binary from the
57-
[releases](https://github.com/brocaar/lora-gateway-bridge/releases) page.
58-
Alternatively, build the code from source (not covered).
50+
```bash
51+
# replace VERSION with the latest version or the version you want to install
5952

60-
### Configuration
53+
# download
54+
wget https://github.com/brocaar/lora-gateway-bridge/releases/download/VERSION/lora_gateway_bridge_VERSION_linux_amd64.tar.gz
6155

62-
All configuration is done by either environment variables or command-line
63-
arguments. Arguments and environment variables can be mixed.
56+
# unpack
57+
tar zxf lora_gateway_bridge_VERSION_linux_amd64.tar.gz
6458

65-
To get a list (and explanation) of all the available arguments, execute:
59+
# move the binary to /usr/local/bin
60+
sudo mv lora-gateway-bridge /usr/local/bin
61+
```
62+
63+
In order to start LoRa Gateway Bridge as a service, create the file
64+
`/etc/systemd/system/lora-gateway-bridge.service` with as content:
6665

67-
``` bash
68-
$ ./lora-gateway-bridge --help
66+
```
67+
[Unit]
68+
Description=lora-gateway-bridge
69+
After=network.target
70+
71+
[Service]
72+
User=gatewaybridge
73+
Group=gatewaybridge
74+
ExecStart=/usr/local/bin/lora-gateway-bridge
75+
Restart=on-failure
76+
77+
[Install]
78+
WantedBy=multi-user.target
6979
```
7080

71-
### Starting LoRa Gateway Bridge
81+
The default LoRa Gateway Bridge settings will work, but in case you would like
82+
to use different settings, create a directory named
83+
`/etc/systemd/system/lora-gateway-bridge.service.d`:
7284

73-
Assuming you have a MQTT broker running on the same host without authentication,
74-
starting LoRa Gateway Bridge is as simple as:
85+
```bash
86+
sudo mkdir /etc/systemd/system/lora-gateway-bridge.service.d
87+
```
88+
89+
Inside this directory, put a file named `lora-gateway-bridge.conf`:
7590

76-
``` bash
77-
$ ./lora-gateway-bridge \
78-
--udp-bind 0.0.0.0:1700 \ # this is the port you must use in the packet_forwarder
79-
--mqtt-server tcp://127.0.0.1:1883
8091
```
92+
[Service]
93+
Environment="SETTING_A=value_a"
94+
Environment="SETTING_B=value_b"
95+
```
96+
97+
(note that the above content is an example and the values must be replaced by
98+
actual config keys)
99+
100+
## Starting LoRa Gateway Bridge
81101

82-
### LoRa gateway configuration
102+
In order to (re)start and stop LoRa Gateway Bridge:
83103

84-
Now you have the LoRa Gateway Bridge running, it is time to configure the
85-
packet_forwarder on your gateway. Edit the file ``local_config.json``:
104+
```bash
105+
# start
106+
sudo systemctl start lora-gateway-bridge
86107

87-
``` json
88-
{
89-
"gateway_conf": {
90-
"gateway_ID": "...", /* you must pick a unique 64b number for each gateway (represented by an hex string) */
91-
"server_address": "...", /* the IP address on which the LoRa Gateway Bridge is running */
92-
"serv_port_up": 1700, /* 1700 is the default LoRa Gateway Bridge port for up and down */
93-
"serv_port_down": 1700
94-
}
95-
}
108+
# restart
109+
sudo systemctl restart lora-gateway-bridge
110+
111+
# stop
112+
sudo systemctl stop lora-gateway-bridge
113+
```
114+
115+
Verify that LoRa Gateway Bridge is up-and-running by looking at it's log output:
116+
117+
```bash
118+
journalctl -u lora-gateway-bridge -f -n 50
96119
```
97120

121+
### Configuration
122+
123+
For all the configuration options, run `lora-gateway-bridge --help` for an
124+
overview of all available options. Note that configuration variables can be
125+
passed as cli arguments and / or environment variables
126+
(which we did in the above example).
127+
98128
### Verify data is coming in
99129

100-
After changing the LoRa gateway configuration (and restarting the
101-
packet_forwarder!), you should see received packets in the logs. Example:
130+
After setting up LoRa Gateway Bridge and configuring your gateway so that it
131+
forwards data to your Lora Gateway Bridge instance, you should see data coming
132+
in:
102133

134+
```bash
135+
journalctl -u lora-gateway-bridge -f -n 50
103136
```
104-
INFO[0000] starting LoRa Gateway Bridge docs=https://docs.loraserver.io/lora-gateway-bridge/ version=2.1.0
105-
INFO[0000] backend: connecting to mqtt broker server=tcp://127.0.0.1:1883
106-
INFO[0000] gateway: starting gateway udp listener addr=0.0.0.0:1700
107-
INFO[0000] backend: connected to mqtt broker
108-
INFO[0001] gateway: received udp packet from gateway addr=192.168.1.10:51013 protocol_version=2 type=PullData
109-
INFO[0001] backend: subscribing to topic topic=gateway/1dee08d0b691d149/tx
110-
INFO[0001] gateway: sending udp packet to gateway addr=192.168.1.10:51013 protocol_version=2 type=PullACK
111-
INFO[0007] gateway: received udp packet from gateway addr=192.168.1.10:42125 protocol_version=2 type=PushData
112-
INFO[0007] gateway: stat packet received addr=192.168.1.10:42125 mac=1dee08d0b691d149
113-
INFO[0007] backend: publishing packet topic=gateway/1dee08d0b691d149/stats
114-
INFO[0007] gateway: sending udp packet to gateway addr=192.168.1.10:42125 protocol_version=2 type=PushACK
115-
INFO[0011] gateway: received udp packet from gateway addr=192.168.1.10:51013 protocol_version=2 type=PullData
116-
INFO[0011] gateway: sending udp packet to gateway addr=192.168.1.10:51013 protocol_version=2 type=PullACK
117-
INFO[0021] gateway: received udp packet from gateway addr=192.168.1.10:51013 protocol_version=2 type=PullData
118-
INFO[0021] gateway: sending udp packet to gateway addr=192.168.1.10:51013 protocol_version=2 type=PullACK
137+
138+
Example:
139+
140+
```
141+
lora-gateway-bridge[9714]: time="2016-08-19T09:05:18+02:00" level=info msg="starting LoRa Gateway Bridge" docs="https://docs.loraserver.io/lora-gateway-bridge/" version=2.1.0
142+
lora-gateway-bridge[9714]: time="2016-08-19T09:05:18+02:00" level=info msg="backend: connecting to mqtt broker" server="tcp://localhost:1883/"
143+
lora-gateway-bridge[9714]: time="2016-08-19T09:05:18+02:00" level=info msg="gateway: starting gateway udp listener" addr=0.0.0.0:1700
144+
lora-gateway-bridge[9714]: time="2016-08-19T09:05:18+02:00" level=info msg="backend: connected to mqtt broker"
145+
lora-gateway-bridge[9714]: time="2016-08-19T09:05:23+02:00" level=info msg="gateway: received udp packet from gateway" addr=86.83.25.107:35368 protocol_version=2 type=PushData
146+
lora-gateway-bridge[9714]: time="2016-08-19T09:05:23+02:00" level=info msg="gateway: stat packet received" addr=86.83.25.107:35368 mac=1dee08d0b691d149
147+
lora-gateway-bridge[9714]: time="2016-08-19T09:05:23+02:00" level=info msg="backend: publishing packet" topic="gateway/1dee08d0b691d149/stats"
148+
lora-gateway-bridge[9714]: time="2016-08-19T09:05:23+02:00" level=info msg="gateway: sending udp packet to gateway" addr=86.83.25.107:35368 protocol_version=2 type=PushACK
149+
lora-gateway-bridge[9714]: time="2016-08-19T09:05:24+02:00" level=info msg="gateway: received udp packet from gateway" addr=86.83.25.107:45562 protocol_version=2 type=PullData
150+
lora-gateway-bridge[9714]: time="2016-08-19T09:05:24+02:00" level=info msg="backend: subscribing to topic" topic="gateway/1dee08d0b691d149/tx"
151+
lora-gateway-bridge[9714]: time="2016-08-19T09:05:24+02:00" level=info msg="gateway: sending udp packet to gateway" addr=86.83.25.107:45562 protocol_version=2 type=PullACK
152+
lora-gateway-bridge[9714]: time="2016-08-19T09:05:34+02:00" level=info msg="gateway: received udp packet from gateway" addr=86.83.25.107:45562 protocol_version=2 type=PullData
153+
lora-gateway-bridge[9714]: time="2016-08-19T09:05:34+02:00" level=info msg="gateway: sending udp packet to gateway" addr=86.83.25.107:45562 protocol_version=2 type=PullACK
119154
```
120155

121156
For an explanation of the different types of data you can receive from and
@@ -124,4 +159,8 @@ send to the LoRa Gateway Bridge see [topics](topics.md).
124159
## Setup LoRa Server
125160

126161
Now you have your LoRa Gateway bridge instance up and running, it is time to
127-
setup [LoRa Server](https://github.com/brocaar/loraserver).
162+
setup [LoRa Server](https://docs.loraserver.io/loraserver/).
163+
164+
!!! info
165+
You can also use Ansible to setup a complete LoRa Server environment. See
166+
[https://github.com/brocaar/loraserver-setup](https://github.com/brocaar/loraserver-setup).

‎mkdocs.yml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,7 @@ theme_dir: docs/material
44

55
pages:
66
- index.md
7+
- deployment.md
78
- getting-started.md
89
- topics.md
910
- frequently-asked-questions.md

0 commit comments

Comments
 (0)