Skip to content

Commit bd8a417

Browse files
brocaarbrocaar
committed
Documentation update.
1 parent ceafe38 commit bd8a417

File tree

5 files changed

+181
-70
lines changed

5 files changed

+181
-70
lines changed

‎docs/frequently-asked-questions.md‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
## Packet-loss (packet_forwarder)
2+
3+
There are many issues that can cause packet-loss (data is not received or
4+
transmitted by the gateway). Here are some hints:
5+
6+
* Compile the packet_forwarder with debugging enabled, it might give you a clue
7+
about what is going wrong. See [packet_forwarder](packet-forwarder.md)
8+
installation instructions.
9+
10+
* Make sure the packet_forwarder is configured with the right configuration.
11+
Each region has different frequencies as documented by the LoRaWAN specs. See
12+
the [Lora-net/packet_forwarder](https://github.com/Lora-net/packet_forwarder/tree/master/lora_pkt_fwd/cfg)
13+
repository for examples.
14+
15+
* packet_forwarder v3.0.0 and up implements just-in-time scheduling, meaning
16+
it keeps a queue of packets to be transmitted. Prior versions of the
17+
packet_forwarder have a queue of size 1 which gets overwritten on each
18+
packet to be transmitted.
19+
20+
### `ERROR: Packet REJECTED, unsupported frequency - [FREQUENCY] (min:0,max:0)`
21+
22+
Make sure the `tx_freq_min` and `tx_freq_max` are present in your
23+
configuration.
24+
25+
### `src/jitqueue.c:343:jit_enqueue(): ERROR: Packet (type=0) REJECTED, collision with packet already programmed at 423844236 (423843356)`
26+
27+
To be investigated
28+
29+
### `WARNING: [gps] GPS out of sync, keeping previous time reference`
30+
31+
To be investigated
32+
33+
## semtech-bridge errors
34+
35+
### `gateway: could not handle packet: gateway: invalid protocol version`
36+
37+
packet_forwarder v3.0.0+ introduced a new protocol version. Please check
38+
[Compatibility](index.md#compatibility).

‎docs/getting-started.md‎

Lines changed: 62 additions & 36 deletions
Original file line numberDiff line numberDiff line change
@@ -1,60 +1,86 @@
1-
# Getting started
1+
## Strategies
2+
3+
There are multiple ways that you can deploy the LoRa Semtech 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 Semtech Bridge.
9+
10+
### Multiple instances
11+
12+
To make the LoRa Semtech 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 Semtech
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.
22+
23+
24+
225

326
## Requirements
427

5-
Before you install the LoRa Semtech Bridge, make sure you've installed the following requirements:
28+
Before you install the LoRa Semtech Bridge, make sure you've installed the
29+
following requirements:
630

7-
#### MQTT server
31+
### MQTT broker
832

9-
LoRa Semtech Brige makes use of MQTT for communication with the gateways and applications.
10-
[Mosquitto](http://mosquitto.org/) is a popular open-source MQTT server.
11-
Make sure you install a **recent** version of Mosquitto (the Mosquitto project provides
12-
repositories for various Linux distributions).
33+
LoRa Semtech Brige makes use of MQTT for communication with the gateways and
34+
applications. [Mosquitto](http://mosquitto.org/) is a popular open-source MQTT
35+
server. Make sure you install a **recent** version of Mosquitto (the Mosquitto
36+
project provides [repositories for various Linux distributions](http://mosquitto.org/download/)).
1337

14-
## Install LoRa Semtech Brige
38+
### LoRa Gateway with packet_forwarder
1539

16-
#### Compatibility
40+
See [packet_forwarder](packet-forwarder.md) for instructions about how to
41+
setup the packet_forwarder on your gateway.
1742

18-
The table below shows the compatibility between LoRa Semtech Bridge and the
19-
available Semtech UDP protocol versions:
43+
## Install LoRa Semtech Brige
2044

21-
| LoRa Semtech Bridge | Semtech UDP protocol version | Note |
22-
|---------------------|------------------------------|---------------------------------------------------------------------|
23-
| 1.x.x | 1 | |
24-
| 2.x.x | 2 | This protocol is used since version 3.0.0 of the `packet_forwarder` |
45+
!!! warning "Compatibility"
46+
Please check the [Compatibility](index.md#compatibility) to make sure you
47+
download the correct LoRa Semtech Bridge version.
2548

26-
#### Download
49+
### Download
2750

2851
Download and unpack a pre-compiled binary from the
29-
[releases](https://github.com/brocaar/lora-semtech-bridge/releases) page. Alternatively,
30-
build the code from source.
52+
[releases](https://github.com/brocaar/lora-semtech-bridge/releases) page.
53+
Alternatively, build the code from source (not covered).
3154

32-
#### Configuration
55+
### Configuration
3356

3457
All configuration is done by either environment variables or command-line
3558
arguments. Arguments and environment variables can be mixed.
3659

37-
Run ``./semtech-bridge --help`` for a list of available arguments.
60+
To get a list (and explanation) of all the available arguments, execute:
61+
62+
``` bash
63+
$ ./semtech-bridge --help
64+
```
3865

39-
#### Starting LoRa Semtech Bridge
66+
### Starting LoRa Semtech Bridge
4067

4168
Assuming you have a MQTT broker running on the same host without authentication,
4269
starting LoRa Semtech Bridge is as simple as:
4370

44-
```bash
45-
./semtech-bridge
71+
``` bash
72+
$ ./semtech-bridge \
73+
--udp-bind 0.0.0.0:1700 \ # this is the port you must use in the packet_forwarder
74+
--mqtt-server tcp://127.0.0.1:1883
4675
```
4776

48-
#### LoRa gateway configuration
77+
### LoRa gateway configuration
4978

50-
Now you have the LoRa Semtech Bridge running, it is time to configure the gateway.
51-
Assuming you have the [``packet_forwarder``](https://github.com/Lora-net/packet_forwarder/)
52-
already setup, edit the file ``local_config.json``:
79+
Now you have the LoRa Semtech Bridge running, it is time to configure the
80+
packet_forwarder on your gateway. Edit the file ``local_config.json``:
5381

54-
```json
82+
``` json
5583
{
56-
/* Put there parameters that are different for each gateway (eg. pointing one gateway to a test server while the others stay in production) */
57-
/* Settings defined in global_conf will be overwritten by those in local_conf */
5884
"gateway_conf": {
5985
"gateway_ID": "...", /* you must pick a unique 64b number for each gateway (represented by an hex string) */
6086
"server_address": "...", /* the IP address on which the LoRa Semtech Bridge is running */
@@ -64,10 +90,10 @@ already setup, edit the file ``local_config.json``:
6490
}
6591
```
6692

67-
#### Verify data is coming in
93+
### Verify data is coming in
6894

69-
After changing the LoRa gateway configuration (and restarting the `packet_forwarder`!),
70-
you should see received packets in the logs. Example:
95+
After changing the LoRa gateway configuration (and restarting the
96+
packet_forwarder!), you should see received packets in the logs. Example:
7197

7298
```
7399
INFO[0000] backend/mqttpubsub: connecting to mqtt broker server=tcp://127.0.0.1:1883
@@ -84,10 +110,10 @@ INFO[0021] gateway: sending udp packet to gateway addr=192.168.1.8:45738
84110
INFO[0021] backend/mqttpubsub: publishing packet topic=gateway/1dee08d0b691d149/stats
85111
```
86112

87-
When using a MQTT client, you should be able to see all data sent by the
88-
gateways by subscribing to the topic `gateway/#`.
113+
For an explanation of the different types of data you can receive from and
114+
send to the LoRa Semtech Bridge see [topics](topics.md).
89115

90116
## Setup LoRa Server
91117

92118
Now you have your LoRa Semtech bridge instance up and running, it is time to
93-
setup [LoRa Server](https://github.com/brocaar/loraserver)!
119+
setup [LoRa Server](https://github.com/brocaar/loraserver).

‎docs/index.md‎

Lines changed: 19 additions & 34 deletions
Original file line numberDiff line numberDiff line change
@@ -1,54 +1,39 @@
1-
## LoRa Semtech Bridge documentation
2-
31
LoRa Semtech Bridge is a service which abstracts the
4-
[Semtech protocol](https://github.com/Lora-net/packet_forwarder/blob/master/PROTOCOL.TXT)
5-
into JSON over MQTT. This project is part of [LoRa Server](https://github.com/brocaar/loraserver).
6-
7-
## Features
8-
9-
### Connection handling
10-
11-
LoRa Semtech Bridge will handle all the gateway pings / acks.
12-
13-
### JSON
14-
15-
All (uplink) packets are published as JSON messages. Downlink packets
16-
can be published to MQTT and will be transformed back to the Semtech
17-
protocol by the LoRa Semtech Bridge.
18-
19-
### HA setup
20-
21-
Multiple LoRa Semtech Bridge instances can run at the same time. Since
22-
it will subscribe to gateway topics for which it has open connections,
23-
downlink packets are directed to the correct LoRa Semtech
24-
Bridge instance.
25-
**Important:** one gateway connection should always be load-balanced the
26-
same LoRa Semtech Bridge instance!
2+
[Semtech UDP protocol](https://github.com/Lora-net/packet_forwarder/blob/master/PROTOCOL.TXT)
3+
used by the [packet_forwarder](https://github.com/Lora-net/packet_forwarder/)
4+
which is running on most LoRa gateways. It enables you to use MQTT for
5+
receiving data from and sending data to your gateways (JSON encoded).
6+
This project is part of [LoRa Server](https://github.com/brocaar/loraserver).
277

288
## Compatibility
299

3010
The table below shows the compatibility between LoRa Semtech Bridge and the
3111
available Semtech UDP protocol versions:
3212

33-
| LoRa Semtech Bridge | Semtech UDP protocol version | Note |
34-
|---------------------|------------------------------|---------------------------------------------------------------------|
35-
| 1.x.x | 1 | |
36-
| 2.x.x | 2 | This protocol is used since version 3.0.0 of the `packet_forwarder` |
13+
| LoRa Semtech Bridge | Semtech UDP protocol version | packet_forwarder version |
14+
|---------------------|------------------------------|---------------------------|
15+
| 1.x.x | 1 | < 3.0.0 |
16+
| 2.x.x | 2 | >= 3.0.0 |
17+
18+
LoRa Semtech Bridge v1.x.x will be update with bugfixes for the near future as
19+
not all gateways are using packet_forwarder v3.0.0+ yet.
3720

3821
## Downloads
3922

40-
Pre-compiled binaries are available for:
23+
Pre-compiled binaries are available from the [releases](https://github.com/brocaar/lora-semtech-bridge/releases) page:
4124

4225
* Linux (including ARM / Raspberry Pi)
4326
* OS X
4427
* Windows
4528

46-
See [https://github.com/brocaar/lora-semtech-bridge/releases](https://github.com/brocaar/lora-semtech-bridge/releases)
47-
for downloads. Source-code can be found at
48-
[https://github.com/brocaar/lora-semtech-bridge](https://github.com/brocaar/lora-semtech-bridge).
29+
Source-code can be found at [https://github.com/brocaar/lora-semtech-bridge](https://github.com/brocaar/lora-semtech-bridge).
30+
31+
## Issues / feature-requests
32+
33+
Issues or feature-requests can be opened at [https://github.com/brocaar/lora-semtech-bridge/issues](https://github.com/brocaar/lora-semtech-bridge/issues).
4934

5035
## License
5136

52-
LoRa Semtech Bridge is distributed under the MIT license. See also
37+
LoRa Semtech Bridge is distributed under the MIT license. See
5338
[LICENSE](https://github.com/brocaar/lora-semtech-bridge/blob/master/LICENSE).
5439

‎docs/packet-forwarder.md‎

Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,60 @@
1+
The [packet_forwarder](https://github.com/Lora-net/packet_forwarder/) is an
2+
application which runs on your gateway. It's responsibility is to:
3+
4+
* forward received uplink packets (over UDP)
5+
* forward statistics (over UDP)
6+
* enqueue and transmit downlink packets (received over UDP)
7+
8+
## Building from source
9+
10+
This guide assumes you're on the same platform as where the packet_forwarder
11+
will run eventually and it assumes you have all tools installed to compile
12+
C source-code.
13+
14+
### Get the source
15+
16+
``` bash
17+
# get the driver / hardware abstraction layer source
18+
git clone https://github.com/Lora-net/lora_gateway.git
19+
20+
# get the packet_forwarder source
21+
git clone https://github.com/Lora-net/packet_forwarder.git
22+
```
23+
24+
### Debugging
25+
26+
For testing and debugging, it is advised to enable debugging as it will give
27+
you more feedback when for example packets get rejected. You can find the
28+
debug flags in `lora_gateway/libloragw/library.cfg`.
29+
30+
### Target-specific configuration
31+
32+
!!! note "please contribute"
33+
This list of target-specific changes is far from complete. Please create
34+
a pull-request to add your target to this list.
35+
36+
#### BeagleBone Black
37+
38+
When compiling the packet_forwarder for a BeagleBone Black, you need to set the
39+
`SPI_DEV_PATH` to `/dev/spidev1.0`. This can be changed in
40+
`lora_gateway/libloragw/src/loragw_spi.native.c`.
41+
42+
### Building
43+
44+
``` bash
45+
# first build the driver / hal library
46+
cd lora_gateway
47+
make all
48+
cd ..
49+
50+
# secondly, build the packet_forwarder (and tools)
51+
cd packet_forwarder
52+
make all
53+
```
54+
55+
### Configuration & usage
56+
57+
From here on, please follow the instructions documented in:
58+
59+
* [https://github.com/Lora-net/packet_forwarder/blob/master/lora_pkt_fwd/readme.md](https://github.com/Lora-net/packet_forwarder/blob/master/lora_pkt_fwd/readme.md#4-usage)
60+
* [github.com/Lora-net/packet_forwarder/](https://github.com/Lora-net/packet_forwarder/)

‎mkdocs.yml‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,9 @@ theme: material
55
pages:
66
- index.md
77
- getting-started.md
8+
- packet-forwarder.md
89
- topics.md
10+
- frequently-asked-questions.md
911
- changelog.md
1012

1113
extra:

0 commit comments

Comments
 (0)