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 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
• cd gateway-connector-bridge
• make 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.