Skip to content
This repository has been archived by the owner on Dec 14, 2021. It is now read-only.

Latest commit

 

History

History
102 lines (81 loc) · 6.73 KB

README.md

File metadata and controls

102 lines (81 loc) · 6.73 KB
Raw

The Things Network Gateway Connector Bridge

Build Status Coverage Status GoDoc

The Things Network

Installation

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

Other requirements are:

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 [email protected]: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.