Update documentation.

Many thanks to @jcampanell-cablelabs for collaborating on this.

Author: brocaar

.gitignore

@@ -4,3 +4,4 @@
 # binaries
 dist/
 build/
+docs/public/

.travis.yml

@@ -16,29 +16,36 @@ script:
   - make test
 
 before_deploy:
-  - rvm --default use system
-  - sudo apt-get install -y python-pip ruby ruby-dev
-  - sudo pip install -r requirements.txt
-  - sudo gem install --no-ri --no-rdoc fpm
-  - mkdocs build
+  - >
+    if ! [ "$BEFORE_DEPLOY_RUN" ]; then
+      export BEFORE_DEPLOY_RUN=1;
 
-  - GOOS=linux GOARCH=amd64 make package package-deb
-  - GOOS=linux GOARCH=386 make package package-deb
-  - GOOS=linux GOARCH=arm make package package-deb
-  - GOOS=darwin GOARCH=amd64 make package
-  - GOOS=windows BINEXT=.exe GOARCH=386 make package
-  - GOOS=windows BINEXT=.exe GOARCH=amd64 make package
+      rvm --default use system;
+      wget https://github.com/spf13/hugo/releases/download/v0.20.7/hugo_0.20.7_Linux-64bit.deb;
+      sudo dpkg -i hugo_0.20.7_Linux-64bit.deb;
+      rm *.deb;
+      sudo apt-get install -y ruby ruby-dev;
+      sudo gem install --no-ri --no-rdoc fpm;
+      make documentation;
+
+      GOOS=linux GOARCH=amd64 make package package-deb;
+      GOOS=linux GOARCH=386 make package package-deb;
+      GOOS=linux GOARCH=arm make package package-deb;
+      GOOS=darwin GOARCH=amd64 make package;
+      GOOS=windows BINEXT=.exe GOARCH=386 make package;
+      GOOS=windows BINEXT=.exe GOARCH=amd64 make package;
+    fi
 
 deploy:
   - provider: s3
     skip_cleanup: true
     access_key_id: AKIAJRLX7TQLGT6NN7WQ
     secret_access_key:
       secure: OJZy+FZeI/S9wM/qqnTHAqjItI266K5tfIqx1+au1MC1QrXAV61NbTjKAo/xUGaKLOcTh1h1/KPTTdYZnQQa8e7QjA+1PF/89Ou7pIhMqWDKCNvFHUoUCTVCLf0f4dmKZcVTEZrobFct+ZhMq5mnzvuIvvf+TT4pfee1BUUpxbMWjA/HaMQIKfRxeb5tLyOnOkKg66Gd99trAY55r8SqPzkqcqvuOqeh7Ic2Uk+Uxlosf+9gRUIWHk7i4miiKvZQmPJfOOKTlvy3BStt1KGSycBt2mYkPAtAAScnobV8GHRcA0ZVI8Blp9W5/D18L43xAP+BRdBnoblr5GNnHGznlltYOskbTPuHzo8TVOl+8sct3uVwbrxg0rzJttAqkoMce7Xg4TLLe44gsp38YOyS4D2NzvEJZMvwoq1uCdR72JOANP5fxOxLnBO2weHy1K1F3SlXXaTJpQZ6lg2j/eaZO3V9tFFbqqHB4PdwQrZ9tjvuA2Dm6NNtQIMPeD8hq6Rq/6/4sXLi7+V8Sbl9f5W+FFfqKTFUl4WH1QPu/bFwC04UL1LDX9kO30Wg9Rlgc18S5HeMivofF1NVDnY+V8SV8lHVyHXASwSRl/OrMvRf21u5+wJf6U8E1s1cK/wYdIOSm6Rbot+6UK9M3ev8VALerqAr6uTVbCmm6Bqmlc+79jw=
-    bucket: docs.loraserver.io
-    local-dir: site
-    upload-dir: lora-gateway-bridge
-    acl: public_read
+    bucket: builds.loraserver.io
+    local-dir: dist/docs
+    upload-dir: docs
+    acl: private
     region: eu-west-1
     on:
       repo: brocaar/lora-gateway-bridge

Makefile

@@ -13,6 +13,7 @@ clean:
 	@echo "Cleaning up workspace"
 	@rm -rf build
 	@rm -rf dist/tar/$(VERSION)
+	@rm -rf docs/public
 
 test:
 	@echo "Running tests"
@@ -22,6 +23,12 @@ test:
 	@go vet $(PKGS)
 	@go test -cover -v $(PKGS)
 
+documentation:
+	@echo "Building documentation"
+	@mkdir -p dist/docs
+	@cd docs && hugo
+	@cd docs/public/ && tar -pczf ../../dist/docs/lora-gateway-bridge.tar.gz .
+
 package: clean build
 	@echo "Creating package for $(GOOS) $(GOARCH)"
 	@mkdir -p dist/tar/$(VERSION)

docs/config.toml

@@ -0,0 +1,35 @@
+baseURL = "https://docs.loraserver.io/lora-gateway-bridge/"
+languageCode = "en-us"
+title = "LoRa Gateway Bridge documentation"
+googleAnalytics = "UA-3512995-9"
+
+[[menu.main]]
+    pre = "<i class='fa fa-hand-o-right'></i>"
+    name = "Overview"
+    identifier = "overview"
+    url = "/overview/"
+    weight = 1
+
+[[menu.main]]
+    pre = "<i class='fa fa-download'></i>"
+    name = "Install"
+    identifier = "install"
+    url = "/install/"
+    weight = 2
+
+[[menu.main]]
+    pre = "<i class='fa fa-user'></i>"
+    name = "Use"
+    identifier = "use"
+    url = "/use/"
+    weight = 3
+
+[[menu.main]]
+    pre = "<i class='fa fa-github'></i>"
+    name = "Community & support"
+    identifier = "community"
+    url = "/community/"
+    weight = 4
+
+[params]
+    version = "2.1.4"

docs/content/community/contribute.md

@@ -0,0 +1,19 @@
+---
+title: Contribute
+menu:
+    main:
+        parent: community
+        weight: 2
+---
+
+## Contribute
+
+There are a couple of ways to get involved:
+
+* Join the discussions and share your feedback at [https://gitter.io/loraserver/lora-gateway-bridge](https://gitter.io/loraserver/lora-gateway-bridge)
+* Report bugs or make feature-requests by opening an issue at [https://github.com/brocaar/lora-gateway-bridge/issues](https://github.com/brocaar/lora-gateway-bridge/issues)
+* Fix issues or improve documentation by creating pull-requests
+
+When you would like to add new features, please discuss the feature first
+by creating an issue describing your feature, how you're planning to implement
+it, what the usecase is etc...

docs/frequently-asked-questions.md renamed to docs/content/community/faq.md

@@ -1,6 +1,14 @@
-# Frequently asked questions
+---
+title: FAQ
+menu:
+    main:
+        parent: community
+        weight: 4
+---
 
-## Packet-loss (packet_forwarder)
+## Frequently asked questions
+
+### Packet-loss (packet_forwarder)
 
 There are many issues that can cause packet-loss (data is not received or
 transmitted by the gateway). Here are some hints:
@@ -19,12 +27,12 @@ transmitted by the gateway). Here are some hints:
   packet_forwarder have a queue of size 1 which gets overwritten on each
   packet to be transmitted.
 
-### `ERROR: Packet REJECTED, unsupported frequency - [FREQUENCY] (min:0,max:0)`
+##### `ERROR: Packet REJECTED, unsupported frequency - [FREQUENCY] (min:0,max:0)`
 
 Make sure the `tx_freq_min` and `tx_freq_max` are present in your
 configuration.
 
-### `src/jitqueue.c:343:jit_enqueue(): ERROR: Packet (type=0) REJECTED, collision with packet already programmed at 423844236 (423843356)`
+##### `src/jitqueue.c:343:jit_enqueue(): ERROR: Packet (type=0) REJECTED, collision with packet already programmed at 423844236 (423843356)`
 
 This error occurs when there is a collision between two packets being
 scheduled by the packet_forwarder. Please note that a collision does not only
@@ -35,13 +43,13 @@ scheduled for transmission, can be > 100ms). This documented behaviour and can
 be found in the [readme.md](https://github.com/Lora-net/packet_forwarder/blob/master/lora_pkt_fwd/readme.md)
 of the packet_forwarder documentation (5.3. TX scheduling).
 
-### `WARNING: [gps] GPS out of sync, keeping previous time reference`
+##### `WARNING: [gps] GPS out of sync, keeping previous time reference`
 
 To be investigated
 
-## lora-gateway-bridge errors
+### lora-gateway-bridge errors
 
-### `gateway: could not handle packet: gateway: invalid protocol version`
+##### `gateway: could not handle packet: gateway: invalid protocol version`
 
-packet_forwarder v3.0.0+ introduced a new protocol version. Please check
-[Compatibility](index.md#compatibility).
+packet_forwarder v3.0.0+ introduced a new protocol version. Please install
+the latest LoRa Gateway Bridge version (which supports both protocol versions).

docs/content/community/source.md

@@ -0,0 +1,73 @@
+---
+title: Source
+menu:
+    main:
+        parent: community
+        weight: 3
+---
+
+## LoRa Gateway Bridge source
+
+Source-code can be found at [https://github.com/brocaar/lora-gateway-bridge](https://github.com/brocaar/lora-gateway-bridge).
+
+### Building
+
+#### With Docker
+
+The easiest way to get started is by using the provided 
+[docker-compose](https://docs.docker.com/compose/) environment. To start a bash
+shell within the docker-compose environment, execute the following command from
+the root of this project:
+
+```bash
+docker-compose run --rm gatewaybridge bash
+```
+
+#### Without Docker
+
+It is possible to build LoRa App Server without Docker. However this requires
+to install a couple of dependencies (depending your platform, there might be
+pre-compiled packages available):
+
+##### Go
+
+Make sure you have [Go](https://golang.org/) installed (1.7+) and that the LoRa
+App Server repository has been cloned to 
+`$GOPATH/src/github.com/brocaar/lora-app-server`.
+
+##### Development utilities
+
+Finally, install some utilities used for development by executing the
+following commands:
+
+```bash
+go get github.com/golang/lint/golint
+go get github.com/kisielk/errcheck
+```
+
+#### Example commands
+
+A few example commands that you can run:
+
+```bash
+# run the tests
+make test
+
+# compile
+make build
+
+# cross-compile for Linux ARM
+GOOS=linux GOARCH=arm make build
+
+# cross-compile for Windows AMD64
+GOOS=windows BINEXT=.exe GOARCH=amd64 make build
+
+# build the .tar.gz file
+make package
+
+# build the .tar.gz file for Linux ARM
+GOOS=linux GOARCH=arm make package
+
+# build the .tar.gz file for Windows AMD64
+GOOS=windows BINEXT=.exe GOARCH=amd64 make package
+```

docs/content/community/support.md

@@ -0,0 +1,20 @@
+---
+title: Support
+menu:
+    main:
+        parent: community
+        weight: 1
+---
+
+## Support
+
+### Bugs
+
+Did you find a bug? Please check first if this issue has already been reported.
+If not, please create an issue at:
+[https://github.com/brocaar/lora-gateway-bridge/issues](https://github.com/brocaar/lora-gateway-bridge/issues).
+
+### Questions
+
+For questions please refer to the LoRa App Server Gitter channel:
+[https://gitter.im/loraserver/lora-gateway-bridge](https://gitter.im/loraserver/lora-gateway-bridge).

docs/content/install/config.md

@@ -0,0 +1,39 @@
+---
+title: Configuration
+menu:
+    main:
+        parent: install
+        weight: 5
+---
+
+## Configuration
+
+### Gateway
+
+Modify the [packet-forwarder](https://github.com/lora-net/packet_forwarder)
+of your gateway so that it will send its data to the LoRa Gateway Bridge.
+You will need to change the following configuration keys:
+
+* `server_address` to the IP address / hostname of the LoRa Gateway Bridge
+* `serv_port_up` to `1700` (the default port that LoRa Gateway Bridge is using)
+* `serv_port_down` to `1700` (same)
+
+### LoRa Gateway Bridge
+
+To list all configuration options, start `lora-gateway-bridge` with the
+`--help` flag. This will display:
+
+```
+GLOBAL OPTIONS:
+   --udp-bind value       ip:port to bind the UDP listener to (default: "0.0.0.0:1700") [$UDP_BIND]
+   --mqtt-server value    mqtt server (e.g. scheme://host:port where scheme is tcp, ssl or ws) (default: "tcp://127.0.0.1:1883") [$MQTT_SERVER]
+   --mqtt-username value  mqtt server username (optional) [$MQTT_USERNAME]
+   --mqtt-password value  mqtt server password (optional) [$MQTT_PASSWORD]
+   --skip-crc-check       skip the CRC status-check of received packets [$SKIP_CRC_CHECK]
+   --log-level value      debug=5, info=4, warning=3, error=2, fatal=1, panic=0 (default: 4) [$LOG_LEVEL]
+   --help, -h             show help
+   --version, -v          print the version
+```
+
+Both cli arguments and environment-variables can be used to pass configuration
+options.