Implement Basic Station support.

Author: brocaar

README.md

@@ -2,13 +2,25 @@
 
 [![Build Status](https://travis-ci.org/brocaar/lora-gateway-bridge.svg?branch=master)](https://travis-ci.org/brocaar/lora-gateway-bridge)
 
-LoRa Gateway Bridge is a service which abstracts the 
-[packet_forwarder UDP protocol](https://github.com/Lora-net/packet_forwarder/blob/master/PROTOCOL.TXT)
-running on most LoRa gateways into JSON over MQTT. It enables you to use MQTT for
-receiving data from and sending data to your gateways.
+LoRa Gateway Bridge is a service which converts LoRa packet-forwarder protocols
+into a LoRa Server [common protocol](https://github.com/brocaar/loraserver/blob/master/api/gw/gw.proto) (JSON and Protobuf).
 This project is part of the [LoRa Server](https://github.com/brocaar/loraserver)
 project.
 
+## Backends
+
+The following packet-forwarder backends are provided:
+
+* [Semtech UDP packet-forwarder](https://github.com/Lora-net/packet_forwarder)
+* [Basic Station packet-forwarder](https://github.com/lorabasics/basicstation)
+
+## Integrations
+
+The following integrations are provided:
+
+* Generic MQTT broker
+* [GCP Cloud IoT Core MQTT Bridge](https://cloud.google.com/iot-core/)
+
 ## Architecture
 
 ![architecture](https://docs.loraserver.io/img/architecture.png)

cmd/lora-gateway-bridge/cmd/configfile.go

@@ -18,6 +18,14 @@ log_level = {{ .General.LogLevel }}
 # Gateway backend configuration.
 [backend]
 
+# Backend type.
+#
+# Valid options are:
+#   * semtech_udp
+#   * basic_station
+type="{{ .Backend.Type }}"
+
+
   # Semtech UDP packet-forwarder backend.
   [backend.semtech_udp]
 
@@ -69,6 +77,61 @@ log_level = {{ .General.LogLevel }}
     # # permissions to execute this command.
     # restart_command="/etc/init.d/lora-packet-forwarder restart"
 
+  # Basic Station backend.
+  [backend.basic_station]
+
+  # ip:port to bind the Websocket listener to.
+  bind="{{ .Backend.BasicStation.Bind }}"
+
+  # TLS certificate and key files.
+  #
+  # When set, the websocket listener will use TLS to secure the connections
+  # between the gateways and LoRa Gateway Bridge (optional).
+  tls_cert="{{ .Backend.BasicStation.TLSCert }}"
+  tls_key="{{ .Backend.BasicStation.TLSKey }}"
+
+  # TLS CA certificate.
+  #
+  # When configured, LoRa Gateway Bridge will validate that the client
+  # certificate of the gateway has been signed by this CA certificate.
+  ca_cert="{{ .Backend.BasicStation.CACert }}"
+
+  # Ping interval.
+  ping_interval="{{ .Backend.BasicStation.PingInterval }}"
+
+  # Read timeout.
+  #
+  # This interval must be greater than the configured ping interval.
+  read_timeout="{{ .Backend.BasicStation.ReadTimeout }}"
+
+  # Write timeout.
+  write_timeout="{{ .Backend.BasicStation.WriteTimeout }}"
+
+  # Region.
+  #
+  # Please refer to the LoRaWAN Regional Parameters specification
+  # for the complete list of common region names.
+  region="{{ .Backend.BasicStation.Region }}"
+
+  # Minimal frequency (Hz).
+  frequency_min={{ .Backend.BasicStation.FrequencyMin }}
+
+  # Maximum frequency (Hz).
+  frequency_max={{ .Backend.BasicStation.FrequencyMax }}
+
+    # Filters.
+    [backend.basic_station.filters]
+
+    # NetIDs to filter on when receiving uplinks.
+    net_ids=[{{ range $index, $elm := .Backend.BasicStation.Filters.NetIDs }}
+      "{{ $elm }}",{{ end }}
+    ]
+
+    # JoinEUIs to filter on when receiving join-requests.
+    join_euis=[{{ range $index, $elm := .Backend.BasicStation.Filters.JoinEUIs }}
+      ["{{ index $elm 0 }}", "{{ index $elm 1 }}"],{{ end }}
+    ]
+
 
 # Integration configuration.
 [integration]

cmd/lora-gateway-bridge/cmd/root.go

@@ -34,10 +34,20 @@ func init() {
 
 	// default values
 	viper.SetDefault("general.log_level", 4)
+	viper.SetDefault("backend.type", "semtech_udp")
 	viper.SetDefault("backend.semtech_udp.udp_bind", "0.0.0.0:1700")
 
-	viper.SetDefault("integration.marshaler", "protobuf")
+	viper.SetDefault("backend.basic_station.bind", ":3001")
+	viper.SetDefault("backend.basic_station.ping_interval", time.Minute)
+	viper.SetDefault("backend.basic_station.read_timeout", time.Minute+(5*time.Second))
+	viper.SetDefault("backend.basic_station.write_timeout", time.Second)
+	viper.SetDefault("backend.basic_station.filters.net_ids", []string{"000000"})
+	viper.SetDefault("backend.basic_station.filters.join_euis", [][2]string{{"0000000000000000", "ffffffffffffffff"}})
+	viper.SetDefault("backend.basic_station.region", "EU868")
+	viper.SetDefault("backend.basic_station.frequency_min", 863000000)
+	viper.SetDefault("backend.basic_station.frequency_max", 870000000)
 
+	viper.SetDefault("integration.marshaler", "protobuf")
 	viper.SetDefault("integration.mqtt.auth.type", "generic")
 
 	viper.SetDefault("integration.mqtt.event_topic_template", "gateway/{{ .GatewayID }}/event/{{ .EventType }}")

docs/config.toml

@@ -25,19 +25,26 @@ pygmentsUseClasses = true
     url = "/gateway/"
     weight = 3
 
+[[menu.main]]
+	pre = "<i class='far fa-file-alt'></i>"
+	name = "Payloads"
+	identifier = "payloads"
+	url = "/payloads/"
+	weight = "4"
+
 [[menu.main]]
     pre = "<i class='fas fa-code'></i>"
     name = "Integrate"
     identifier = "integrate"
     url = "/integrate/"
-    weight = 4
+    weight = 5
 
 [[menu.main]]
     pre = "<i class='fab fa-github'></i>"
     name = "Community & support"
     identifier = "community"
     url = "/community/"
-    weight = 5
+    weight = 6
 
 [params]
     version = "2.7.1"

docs/content/install/config.md

@@ -9,18 +9,6 @@ description: Instructions and examples how to configure the LoRa Gateway Bridge
 
 # 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
-
 The `lora-gateway-bridge` has the following command-line flags:
 
 {{<highlight text>}}
@@ -45,7 +33,7 @@ Flags:
 Use "lora-gateway-bridge [command] --help" for more information about a command.
 {{< /highlight >}}
 
-### Configuration file
+## Configuration file
 
 By default `lora-gateway-bridge` will look in the following order for a
 configuration at the following paths when `--config` / `-c` is not set:
@@ -82,6 +70,14 @@ log_level = 4
 # Gateway backend configuration.
 [backend]
 
+# Backend type.
+#
+# Valid options are:
+#   * semtech_udp
+#   * basic_station
+type="semtech_udp"
+
+
   # Semtech UDP packet-forwarder backend.
   [backend.semtech_udp]
 
@@ -133,6 +129,61 @@ log_level = 4
     # # permissions to execute this command.
     # restart_command="/etc/init.d/lora-packet-forwarder restart"
 
+  # Basic Station backend.
+  [backend.basic_station]
+
+  # ip:port to bind the Websocket listener to.
+  bind=":3001"
+
+  # TLS certificate and key files.
+  #
+  # When set, the websocket listener will use TLS to secure the connections
+  # between the gateways and LoRa Gateway Bridge (optional).
+  tls_cert=""
+  tls_key=""
+
+  # TLS CA certificate.
+  #
+  # When configured, LoRa Gateway Bridge will validate that the client
+  # certificate of the gateway has been signed by this CA certificate.
+  ca_cert=""
+
+  # Ping interval.
+  ping_interval="1m0s"
+
+  # Read timeout.
+  #
+  # This interval must be greater than the configured ping interval.
+  read_timeout="1m5s"
+
+  # Write timeout.
+  write_timeout="1s"
+
+  # Region.
+  #
+  # Please refer to the LoRaWAN Regional Parameters specification
+  # for the complete list of common region names.
+  region="EU868"
+
+  # Minimal frequency (Hz).
+  frequency_min=863000000
+
+  # Maximum frequency (Hz).
+  frequency_max=870000000
+
+    # Filters.
+    [backend.basic_station.filters]
+
+    # NetIDs to filter on when receiving uplinks.
+    net_ids=[
+      "000000",
+    ]
+
+    # JoinEUIs to filter on when receiving join-requests.
+    join_euis=[
+      ["0000000000000000", "ffffffffffffffff"],
+    ]
+
 
 # Integration configuration.
 [integration]
@@ -263,7 +314,7 @@ marshaler="protobuf"
   bind=""
 {{</highlight>}}
 
-#### Environment variables
+## Environment variables
 
 Although using the configuration file is recommended, it is also possible
 to use environment variables to set configuration variables.

docs/content/install/debian.md

@@ -24,7 +24,7 @@ commands:
 {{<highlight bash>}}
 sudo apt-key adv --keyserver keyserver.ubuntu.com --recv-keys 1CE2AFD36DBCCA00
 
-sudo echo "deb https://artifacts.loraserver.io/packages/2.x/deb stable main" | sudo tee /etc/apt/sources.list.d/loraserver.list
+sudo echo "deb https://artifacts.loraserver.io/packages/3.x/deb stable main" | sudo tee /etc/apt/sources.list.d/loraserver.list
 sudo apt-get update
 {{< /highlight >}}
 

docs/content/install/deployment.md

@@ -39,13 +39,13 @@ the setup, but has the following advantages:
 
 ### MQTT (using TCP) over UDP
 
-By using MQTT (which uses TCP) over UDP, the connection becomes more reliable
-in case packetloss is common.
+By using MQTT (which uses TCP) over UDP when using the Semtech UDP packet-forwarder
+backend, the connection becomes more reliable in case packetloss is common.
 
 ### Authentication
 
-It is possible to setup credentials for each gateway, meaning you know where
-your data is coming from.
+It is possible to setup credentials for each gateway, so that only gateways with
+valid credentials are able to ingest data.
 
 ### SSL/TLS
 

docs/content/integrate/generic-mqtt.md

@@ -26,6 +26,12 @@ Examples:
 # show data from all gateways 
 mosquitto_sub -t "gateway/#" -v
 
-# show all data for the given gateway
-mosquitto_sub -t "gateway/0101010101010101/+" -v
-{{< /highlight >}}
+# show all events and commands for the given gateway ID
+mosquitto_sub -t "gateway/0101010101010101/#" -v
+
+# show all events for the given gateway ID
+mosquitto_sub -t "gateway/0101010101010101/event/+" -v
+
+# show all commands for the given gateway ID
+mosquitto_sub -t "gateway/0101010101010101/command/+" -v
+{{< /highlight >}}