gateway-connector-bridge

README

The Things Network Gateway Connector Bridge

Installation

Download precompiled binaries for 64 bit Linux, 32 bit Linux, ARM Linux, macOS, 64 bit Windows, 32 bit Windows.

Other requirements are:

• Redis
• An MQTT Broker (see also the Security section)

Usage

Usage:
  gateway-connector-bridge [flags]

Flags:
      --account-server string          Use an account server for exchanging access keys and fetching gateway information (default "https://account.thethingsnetwork.org")
      --amqp stringSlice               AMQP Broker to connect to (user:pass@host:port; disable with "disable")
      --debug                          Print debug logs
      --http-debug-addr string         The address of the HTTP debug server to start
      --id string                      ID of this bridge
      --info-expire duration           Gateway Information expiration time (default 1h0m0s)
      --inject-frequency-plan string   Inject a frequency plan field into status message that don't have one
      --log-file string                Location of the log file
      --mqtt stringSlice               MQTT Broker to connect to (user:pass@host:port; disable with "disable") (default [guest:guest@localhost:1883])
      --ratelimit                      Rate-limit messages
      --ratelimit-downlink uint        Downlink rate limit (per gateway per minute)
      --ratelimit-status uint          Status rate limit (per gateway per minute) (default 20)
      --ratelimit-uplink uint          Uplink rate limit (per gateway per minute) (default 600)
      --redis                          Use Redis auth backend (default true)
      --redis-address string           Redis host and port (default "localhost:6379")
      --redis-db int                   Redis database
      --redis-password string          Redis password
      --root-ca-file string            Location of the file containing Root CA certificates
      --route-unknown-gateways         Route traffic for unknown gateways
      --status-addr string             Address of the gRPC status server to start
      --status-key stringSlice         Access key for the gRPC status server
      --ttn-router stringSlice         TTN Router to connect to (default [discover.thethingsnetwork.org:1900/ttn-router-eu])
      --udp string                     UDP address to listen on for Semtech Packet Forwarder gateways
      --udp-lock-ip                    Lock gateways to IP addresses for the session duration (default true)
      --udp-lock-port                  Additional to udp-lock-ip, also lock gateways to ports for the session duration
      --udp-session duration           Duration of gateway sessions (default 1m0s)
      --workers int                    Number of parallel workers (default 1)

For running in Docker, please refer to docker-compose.yml.

Protocol

The Things Network's gateway-connector protocol sends protocol buffers over MQTT.

• Connect to MQTT with your gateway's ID as username and Access Key as password.
  • On MQTT brokers that don't support authentication, you can connect without authentication.
• After connect: send types.ConnectMessage on topic connect.
  • Supply the gateway's ID and Access Key to authenticate with the backend
• On disconnect: send types.DisconnectMessage on topic disconnect.
  • Supply the same ID and Access Key as in the ConnectMessage.
  • Use the "will" feature of MQTT to send the DisconnectMessage when the gateway unexpectedly disconnects.
• On uplink: send router.UplinkMessage on topic <gateway-id>/up.
• For downlink: subscribe to topic <gateway-id>/down and receive router.DownlinkMessage.
• On status: send gateway.Status on topic <gateway-id>/status.

Security

⚠️ MQTT brokers should support authentication and access control:

• The connect, disconnect, <gateway-id>/up, <gateway-id>/status topics must only allow
  • publish for authenticated gateways with <gateway-id>.
  • subscribe for the bridge.
• The <gateway-id>/down topics must only allow
  • publish for the bridge.
  • subscribe for authenticated gateways with <gateway-id>.

Development

• Make sure you have Go installed (recommended version 1.11, version 1.8 or later is known to work).
• Set up your Go environment.
• Make sure you have Redis installed and running.
• Make sure you have RabbitMQ and its MQTT plugin installed and running.
• Fork this repository on Github
• git clone git@github.com:YOURUSERNAME/gateway-connector-bridge.git $GOPATH/src/github.com/TheThingsNetwork/gateway-connector-bridge.git
• cd $GOPATH/src/github.com/TheThingsNetwork/gateway-connector-bridge
• make dev-deps
• make test
• make build

License

Source code for The Things Network is released under the MIT License, which can be found in the LICENSE file. A list of authors can be found in the AUTHORS file.