LoRa® Gateway specific APIs

The Things Stack supports multiple LoRa® gateway protocols which communicate the respective APIs.

See the port allocations guide to check which protocol is supported on which port.

LoRa Basics™ Station

The Things Stack provides LoRa Basics™ Station LNS and CUPS end points for gateways to connect.

These protocols follow the LoRa Basics™ Station reference specification.

Note:

LoRa Basics™ Station CUPS API is usually exposed on the HTTP(s) port(s).

Implementation specific details for clients using the LoRa Basics™ Station LNS protocol to communicate with The Things Stack is documented in the LoRa Basics Station Implementation Guide.

This reference describes the MQTT protocol used by the Gateway Server. Packet forwarders implementing the MQTT protocols are specific for The Things Stack.

The MQTT protocol can be used to develop custom packet forwarders or gateway bridges for exchanging traffic between a gateway and The Things Stack, or easily simulating gateway traffic for testing purposes. It is an alternative to the Basic Station and the Semtech UDP protocols.

MQTT

MQTT is a server-client protocol for exchanging messages. Clients can connect to the server and publish messages (data) under a specific topic. They can also subscribe to a topic, and thus receive all messages that are published under that topic (by other clients, or the MQTT server itself).

The Gateway Server is the MQTT server, and gateways connect to the Gateway Server as MQTT clients. The gateway that connects is identified by the username that is used for authentication.

On multi-tenant environments such as Cloud, endpoints include the tenant id, e.g gateway1@tenant1. On single tenant environments such as Open Source, the tenant id can be removed, i.e gateway1.

To communicate with the MQTT protocol, the Gateway Server and the gateway are exchanging Protocol Buffers. The definitions of the Protocol Buffers can be found at the GitHub repository of The Things Stack, under messages.proto and lorawan.proto.

MQTT v2

The MQTT v2 gateway APIs are used by The Things Kickstarter Gateway and use the TTN v2 MQTT format.

MQTT v3

The MQTT v3 protocol uses the The Things Stack v3 messages definitions.

Gateways can connect using the username {gateway-id}@{tenant-id} and an API key as the password. Check how to register a gateway and create an API key.

Topic	Message
`v3/{gateway-id}@{tenant-id}/up`	Publish an uplink message to the network
`v3/{gateway-id}@{tenant-id}/status`	Publish a status message to the network
`v3/{gateway-id}@{tenant-id}/down`	Subscribe to downlink messages
`v3/{gateway-id}@{tenant-id}/ack`	Publish an acknowledgement on emitting a downlink

Connecting to the Gateway Server

See Networking for the default port of the MQTT server.

The username is <gateway-id>@<tenant-id> (e.g. gtw1@tenant1), and the password is a gateway API key with the RIGHT_GATEWAY_LINK right enabled. You can generate this API key by following instructions in the Creating Gateways section.

Authenticated clients get write-only access to the following topics:

v3/<gateway-id>@<tenant-id>/up: Used for sending uplink traffic to the Gateway Server.
v3/<gateway-id>@<tenant-id>/status: Used for sending gateway status messages to the Gateway Server.
v3/<gateway-id>@<tenant-id>/down/ack: Used for sending TxAck messages to the Gateway Server.

Clients also get read-only access and should subscribe to the following topic:

v3/<gateway-id>@<tenant-id>/down: The Gateway Server publishes downlink message that the gateway should transmit.

Disconnect from the Gateway Server

The gateway can disconnect by terminating the MQTT client connection.

Uplink Messages

To forward uplink traffic to the Gateway Server, the MQTT client must publish a Protocol Buffer of type ttnpb.UplinkMessage under the topic v3/<gateway-id>@<tenant-id>/up.

Below is an example that connects to the Gateway Server as $GATEWAY_ID, publishes an uplink message (Protocol Buffer stored as binary file test-uplink-message) and disconnects:

GATEWAY_ID="test-gtw@my-tenant"
GATEWAY_API_KEY="NNSXS.VEEBURF3KR77ZR..." # API key with RIGHT_GATEWAY_LINK rights
mosquitto_pub \
    -h "thethings.example.com" -p 1882 \
    -u "$GATEWAY_ID" -P "$GATEWAY_API_KEY" \
    -t "v3/$GATEWAY_ID/up" -f test-uplink-message

Warning:

Port 1882 is insecure. The TLS-enabled port 8882 should be used in a production setting.

Note:

The file test-uplink-message contains a Protocol Buffer of type ttnpb.UplinkMessage (binary, not JSON).

Downlink Messages

The Gateway Server instructs the gateway to send a downlink packet by publishing a Protocol Buffer of type ttnpb.GatewayDown under the topic v3/<gateway-id>@<tenant-id>/down.

The MQTT client must subscribe to this topic after connecting to the Gateway Server. It must also listen for incoming ttnpb.GatewayDown messages (which contain both the packet data payload as well as any desired transmission settings). Upon receiving a scheduling request, it must trasmit that message, and send back a TxAck packet on success.

GATEWAY_ID="test-gtw@my-tenant"
GATEWAY_API_KEY="NNSXS.VEEBURF3KR77ZR..." # API key with RIGHT_GATEWAY_LINK rights
mosquitto_sub \
    -h "thethings.example.com" -p 1882 \
    -u "$GATEWAY_ID" -P "$GATEWAY_API_KEY" \
    -t "v3/$GATEWAY_ID/down" -v

Warning:

Port 1882 is insecure. The TLS-enabled port 8882 should be used in a production setting.

Note:

The example above is not complete (as it does nothing with the scheduled downlink requests). It is only meant to showcase the MQTT client subscribing to the downlink topic.

Gateway Status Messages

To forward a gateway status message to the Gateway Server, the MQTT client must publish a Protocol Buffer of type ttnpb.GatewayStatus under the topic v3/<gateway-id>@<tenant-id>/status.

Below is an example that connects to the Gateway Server as $GATEWAY_ID, publishes a gateway status message (Protocol Buffer stored as binary file test-gateway-status) and disconnects:

GATEWAY_ID="test-gtw@my-tenant"
GATEWAY_API_KEY="NNSXS.VEEBURF3KR77ZR..." # API key with RIGHT_GATEWAY_LINK rights
mosquitto_pub \
    -h "thethings.example.com" -p 1882 \
    -u "$GATEWAY_ID" -P "$GATEWAY_API_KEY" \
    -t "v3/$GATEWAY_ID/status" -f test-gateway-status

Warning:

Port 1882 is insecure. The TLS-enabled port 8882 should be used in a production setting.

Note:

The file test-gateway-status contains a Protocol Buffer of type ttnpb.GatewayStatus (binary, not JSON).

TxAck Messages

To forward a TxAck packet to the Gateway Server, the MQTT client must publish a Protocol Buffer of type ttnpb.TxAcknowledgement under the topic v3/<gateway-id>@<tenant-id>/down/ack.

GATEWAY_ID="test-gtw@my-tenant"
GATEWAY_API_KEY="NNSXS.VEEBURF3KR77ZR..." # API key with RIGHT_GATEWAY_LINK rights
mosquitto_pub \
    -h "thethings.example.com" -p 1882 \
    -u "$GATEWAY_ID" -P "$GATEWAY_API_KEY" \
    -t "v3/$GATEWAY_ID/down/ack" -f example-tx-ack

Warning:

Port 1882 is insecure. The TLS-enabled port 8882 should be used in a production setting.

Note:

The example above is not complete (the TxAck should be sent in response to a successful downlink transmission). It is only meant to showcase the MQTT client sending a TxAck packet (contents of the example-tx-ack file) to the Gateway Server.

Tabs Hubs

The Tabs Hubs APIs are tailored to connect legacy Tabs Hub gateways that are not compatible with the official LoRa Basics Station spec. The APIs here are undocumented and is not intended for other use.

Legacy UDP

The UDP APIs support the Legacy Semtech UDP packet forwarder specifications.

Warning:

This protocol and the code are very out-dated and unmaintained by the upstream. Please use LoRa Basics™ Station.

← Errors Troubleshooting →