Skip to content

Commit a1a93f2

Browse files
brocaarbrocaar
committed
Update documentation.
1 parent 5dcc9e5 commit a1a93f2

File tree

5 files changed

+175
-63
lines changed

5 files changed

+175
-63
lines changed

‎README.md‎

Lines changed: 15 additions & 63 deletions
Original file line numberDiff line numberDiff line change
@@ -1,78 +1,30 @@
11
# LoRa Semtech Bridge
22

33
[![Build Status](https://travis-ci.org/brocaar/lora-semtech-bridge.svg?branch=master)](https://travis-ci.org/brocaar/lora-semtech-bridge)
4+
[![Documentation Status](https://readthedocs.org/projects/lora-semtech-bridge/badge/?version=latest)](http://lora-semtech-bridge.readthedocs.org/en/latest/?badge=latest)
5+
[![Documentation Status](https://readthedocs.org/projects/lora-semtech-bridge/badge/?version=stable)](http://lora-semtech-bridge.readthedocs.org/en/stable/?badge=stable)
46
[![GoDoc](https://godoc.org/github.com/brocaar/lora-semtech-bridge/cmd/semtech-bridge?status.svg)](https://godoc.org/github.com/brocaar/lora-semtech-bridge/cmd/semtech-bridge)
57

6-
*LoRa Semtech Bridge* is a service to enable LoRa gateway communication over MQTT.
7-
All incoming UDP traffic (Semtech UDP protocol) is published to a MQTT broker and
8-
all messages received from the MQTT broker are sent to the gateway using UDP.
8+
LoRa Semtech Bridge is a service which abstracts the
9+
[Semtech protocol](https://github.com/Lora-net/packet_forwarder/blob/master/PROTOCOL.TXT)
10+
into JSON over MQTT. This project is part of [LoRa Server](https://github.com/brocaar/loraserver).
911

10-
This project is part of [LoRa Server](https://github.com/brocaar/loraserver).
1112

12-
## Requirements
13+
## Documentation
1314

14-
#### MQTT broker
15+
See the [http://lora-semtech-bridge.readthedocs.io/](http://lora-semtech-bridge.readthedocs.io/)
16+
for documentation about setting up LoRa Semtech Bridge.
1517

16-
[Mosquitto](http://mosquitto.org/) is a popular open-source MQTT server.
18+
## Downloads
1719

18-
#### LoRa gateway
20+
Pre-compiled binaries are available for:
1921

20-
Your gateway must be setup so that it sends UDP packets (Semtech UDP protocol).
21-
Depending upon your LoRa Gateway type, you might need to install the
22-
[packet_forwarder](https://github.com/TheThingsNetwork/packet_forwarder).
23-
24-
25-
## Getting started
26-
27-
* Download and unpack a pre-compiled binary from the [releases](https://github.com/brocaar/lora-semtech-bridge/releases)
28-
page. Alternatively, build the code from source (when you have a Go development environment
29-
``make build`` should be sufficient).
30-
31-
* Start the ``semtech-bridge`` service. The ``--help`` argument will show
32-
you all the available config options. When everything is setup correctly
33-
(your gateway is configured to send data to ``semtech-bridge``), you
34-
should see ``PullData`` packets coming in. E.g.
35-
36-
``` bash
37-
$ ./semtech-bridge
38-
INFO[0000] backend/mqttpubsub: connecting to mqtt broker server=tcp://127.0.0.1:1883
39-
INFO[0000] gateway: starting gateway udp listener addr=0.0.0.0:1700
40-
INFO[0000] backend/mqttpubsub: connected to mqtt broker
41-
INFO[0006] gateway: received udp packet from gateway addr=192.168.1.8:45082 type=PullData
42-
INFO[0006] backend/mqttpubsub: subscribing to topic topic=gateway/1dee08d0b691d149/tx
43-
INFO[0006] gateway: sending udp packet to gateway addr=192.168.1.8:45082 type=PullACK
44-
INFO[0016] gateway: received udp packet from gateway addr=192.168.1.8:45082 type=PullData
45-
INFO[0016] gateway: sending udp packet to gateway addr=192.168.1.8:45082 type=PullACK
46-
INFO[0021] gateway: received udp packet from gateway addr=192.168.1.8:45738 type=PushData
47-
INFO[0021] gateway: stat packet received addr=192.168.1.8:45738 mac=1dee08d0b691d149
48-
INFO[0021] gateway: sending udp packet to gateway addr=192.168.1.8:45738 type=PushACK
49-
INFO[0021] backend/mqttpubsub: publishing packet topic=gateway/1dee08d0b691d149/stats
50-
```
51-
52-
* Now it is time to setup the [LoRa Server](https://github.com/brocaar/loraserver)!
53-
54-
## Debugging
55-
56-
To view all incoming and outgoing MQTT messages, you can use the ``mosquitto_sub``
57-
tool.
58-
59-
```bash
60-
$ mosquitto_sub -t "#" -v
61-
gateway/1dee08d0b691d149/stats {"mac":"1dee08d0b691d149","time":"2016-04-16T10:08:11Z","latitude":0,"longitude":0,"altitude":0,"rxPacketsReceived":0,"rxPacketsReceivedOK":0}
62-
gateway/1dee08d0b691d149/rx {"rxInfo":{"mac":"1dee08d0b691d149","time":"2016-04-16T10:08:30.005418Z","timestamp":1623489499,"frequency":868300000,"channel":1,"rfChain":1,"crcStatus":1,"codeRate":"4/5","rssi":-48,"loRaSNR":10,"size":23,"dataRate":{"modulation":"LORA","spreadFactor":7,"bandwidth":125}},"phyPayload":"AAEBAQEBAQEBAgICAgICAgJzTIBGXXg="}
63-
gateway/1dee08d0b691d149/stats {"mac":"1dee08d0b691d149","time":"2016-04-16T10:08:41Z","latitude":0,"longitude":0,"altitude":0,"rxPacketsReceived":1,"rxPacketsReceivedOK":1}
64-
```
65-
66-
## Data model
67-
68-
The data model is defined in the [LoRa Server](https://github.com/brocaar/loraserver)
69-
project. JSON is used as marshaling format. See:
70-
71-
* [RXPacket](https://godoc.org/github.com/brocaar/loraserver/models/#RXPacket) (packet received by the gateway)
72-
* [TXPacket](https://godoc.org/github.com/brocaar/loraserver/models/#TXPacket) (packet to be sent by the gateway)
73-
* [GatewayStatsPacket](https://godoc.org/github.com/brocaar/loraserver/models/#GatewayStatsPacket) (gateway stats)
22+
* Linux (and ARM build for e.g. Raspberry Pi)
23+
* OS X
24+
* Windows
7425

26+
See [releases](https://github.com/brocaar/lora-semtech-bridge/releases).
7527

7628
## License
7729

78-
This package is licensed under the MIT license. See ``LICENSE``.
30+
LoRa Server is licensed under the MIT license. See ``LICENSE``.

‎docs/changelog.md‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
# Changelog
2+
3+
## 1.1.3
4+
5+
* Minor log related improvements.
6+
7+
## 1.1.2
8+
9+
* Provide binaries for multiple platforms.
10+
11+
## 1.1.1
12+
13+
* Rename `DataRate` to `BitRate` (FSK modulation).
14+
15+
## 1.1.0
16+
17+
* Change from [GOB](https://golang.org/pkg/encoding/gob/) to JSON.
18+
19+
## 1.0.1
20+
21+
* Update MQTT vendor to fix various connection issues.
22+
23+
## 1.0.0
24+
25+
Initial release.

‎docs/getting-started.md‎

Lines changed: 83 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,83 @@
1+
# Getting started
2+
3+
## Requirements
4+
5+
Before you install the LoRa Semtech Bridge, make sure you've installed the following requirements:
6+
7+
#### MQTT server
8+
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).
13+
14+
## Install LoRa Semtech Brige
15+
16+
#### Download
17+
18+
Download and unpack a pre-compiled binary from the
19+
[releases](https://github.com/brocaar/lora-semtech-bridge/releases) page. Alternatively,
20+
build the code from source.
21+
22+
#### Configuration
23+
24+
All configuration is done by either environment variables or command-line
25+
arguments. Arguments and environment variables can be mixed.
26+
27+
Run ``./semtech-bridge --help`` for a list of available arguments.
28+
29+
#### Starting LoRa Semtech Bridge
30+
31+
Assuming you have a MQTT broker running on the same host without authentication,
32+
starting LoRa Semtech Bridge is as simple as:
33+
34+
```bash
35+
./semtech-bridge
36+
```
37+
38+
#### LoRa gateway configuration
39+
40+
Now you have the LoRa Semtech Bridge running, it is time to configure the gateway.
41+
Assuming you have the [``packet_forwarder``](https://github.com/Lora-net/packet_forwarder/)
42+
already setup, edit the file ``local_config.json``:
43+
44+
```json
45+
{
46+
/* Put there parameters that are different for each gateway (eg. pointing one gateway to a test server while the others stay in production) */
47+
/* Settings defined in global_conf will be overwritten by those in local_conf */
48+
"gateway_conf": {
49+
"gateway_ID": "...", /* you must pick a unique 64b number for each gateway (represented by an hex string) */
50+
"server_address": "...", /* the IP address on which the LoRa Semtech Bridge is running */
51+
"serv_port_up": 1700, /* 1700 is the default LoRa Semtech Bridge port for up and down */
52+
"serv_port_down": 1700
53+
}
54+
}
55+
```
56+
57+
#### Verify data is coming in
58+
59+
After changing the LoRa gateway configuration (and restarting the `packet_forwarder`!),
60+
you should see received packets in the logs. Example:
61+
62+
```
63+
INFO[0000] backend/mqttpubsub: connecting to mqtt broker server=tcp://127.0.0.1:1883
64+
INFO[0000] gateway: starting gateway udp listener addr=0.0.0.0:1700
65+
INFO[0000] backend/mqttpubsub: connected to mqtt broker
66+
INFO[0006] gateway: received udp packet from gateway addr=192.168.1.8:45082 type=PullData
67+
INFO[0006] backend/mqttpubsub: subscribing to topic topic=gateway/1dee08d0b691d149/tx
68+
INFO[0006] gateway: sending udp packet to gateway addr=192.168.1.8:45082 type=PullACK
69+
INFO[0016] gateway: received udp packet from gateway addr=192.168.1.8:45082 type=PullData
70+
INFO[0016] gateway: sending udp packet to gateway addr=192.168.1.8:45082 type=PullACK
71+
INFO[0021] gateway: received udp packet from gateway addr=192.168.1.8:45738 type=PushData
72+
INFO[0021] gateway: stat packet received addr=192.168.1.8:45738 mac=1dee08d0b691d149
73+
INFO[0021] gateway: sending udp packet to gateway addr=192.168.1.8:45738 type=PushACK
74+
INFO[0021] backend/mqttpubsub: publishing packet topic=gateway/1dee08d0b691d149/stats
75+
```
76+
77+
When using a MQTT client, you should be able to see all data sent by the
78+
gateways by subscribing to the topic `gateway/#`.
79+
80+
## Setup LoRa Server
81+
82+
Now you have your LoRa Semtech bridge instance up and running, it is time to
83+
setup [LoRa Server](https://github.com/brocaar/loraserver)!

‎docs/index.md‎

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
## LoRa Semtech Bridge documentation
2+
3+
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!
27+
28+
## Downloads
29+
30+
Pre-compiled binaries are available for:
31+
32+
* Linux (including ARM / Raspberry Pi)
33+
* OS X
34+
* Windows
35+
36+
See [https://github.com/brocaar/lora-semtech-bridge/releases](https://github.com/brocaar/lora-semtech-bridge/releases)
37+
for downloads. Source-code can be found at
38+
[https://github.com/brocaar/lora-semtech-bridge](https://github.com/brocaar/lora-semtech-bridge).
39+
40+
## License
41+
42+
LoRa Semtech Bridge is distributed under the MIT license. See also
43+
[LICENSE](https://github.com/brocaar/lora-semtech-bridge/blob/master/LICENSE).
44+

‎mkdocs.yml‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
site_name: LoRa Semtech Bridge documentation
2+
pages:
3+
- index.md
4+
- getting-started.md
5+
- changelog.md
6+
theme: readthedocs
7+
repo_url: https://github.com/brocaar/lora-semtech-bridge/
8+

0 commit comments

Comments
 (0)