gateway-connector-bridge
gateway-connector-bridge copied to clipboard
Bridge between Gateway Connector (protobufs over MQTT) and gRPC
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 topicconnect
.- Supply the gateway's ID and Access Key to authenticate with the backend
- On disconnect: send
types.DisconnectMessage
on topicdisconnect
.- 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.
- Supply the same ID and Access Key as in the
- On uplink: send
router.UplinkMessage
on topic<gateway-id>/up
. - For downlink: subscribe to topic
<gateway-id>/down
and receiverouter.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.
-
publish for authenticated gateways with
- 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.