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 (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
      --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])
      --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
      --status-addr string       Address of the gRPC status server to start
      --ttn-router stringSlice   TTN Router to connect to (default [discover.thethingsnetwork.org:1900/ttn-router-eu])
      --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 (version 1.7 or later).
• 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.