Getting Started Concepts The Things Stack Cloud The Things Stack Enterprise Integrations API Hardware
Get The Things Stack

API

    Overview
  • Concepts
  • Reference
    • HTTP(REST)
    • gRPC
      • Application APIs
      • Application Package APIs
      • Application Pub/Sub APIs
      • Application Server APIs
      • Application Webhook APIs
      • Client APIs
      • Crypto Operations APIs
      • End Device APIs
      • Events API
      • Gateway APIs
      • Gateway Server APIs
      • Identity Server APIs
      • Join Server APIs
      • Network Operations Center APIs
      • Network Server APIs
      • Organization APIs
      • Packet Broker APIs
      • Storage Integration API
      • Tenant APIs
      • User APIs

Gateway Server APIs

List of Gateway Server APIs.

The Gs service

Method Gs.GetGatewayConnectionStats
Description Get statistics about the current gateway connection to the Gateway Server. This is not persisted between reconnects.
Request type GatewayIdentifiers
Response type GatewayConnectionStats
HTTP bindings

GET /api/v3/gs/gateways/{gateway_id}/connection/stats

Method Gs.BatchGetGatewayConnectionStats
Description

Get statistics about gateway connections to the Gateway Server of a batch of gateways.

  • Statistics are not persisted between reconnects.
  • Gateways that are not connected or are part of a different cluster are ignored.
  • The client should ensure that the requested gateways are in the requested cluster.
  • The client should have the right to get the gateway connection stats on all requested gateways.
Request type BatchGetGatewayConnectionStatsRequest
Response type BatchGetGatewayConnectionStatsResponse
HTTP bindings

POST /api/v3/gs/gateways/connection/stats

The GatewayConfigurationService service

Method GatewayConfigurationService.GetGatewayConfiguration
Request type GetGatewayConfigurationRequest
Response type GetGatewayConfigurationResponse
HTTP bindings

/api/v3

GET /api/v3/gcs/gateways/configuration/{gateway_ids.gateway_id}/{format}/{filename}

GET /api/v3/gcs/gateways/configuration/{gateway_ids.gateway_id}/{format}/{type}/{filename}

The GtwGs service

Method GtwGs.LinkGateway
Description Link a gateway to the Gateway Server for streaming upstream messages and downstream messages.
Request type Stream of GatewayUp
Response type Stream of GatewayDown
HTTP bindings
Method GtwGs.GetConcentratorConfig
Description Get configuration for the concentrator.
Request type google.protobuf.Empty
Response type ConcentratorConfig
HTTP bindings
Method GtwGs.GetMQTTConnectionInfo
Description Get connection information to connect an MQTT gateway.
Request type GatewayIdentifiers
Response type MQTTConnectionInfo
HTTP bindings

GET /api/v3/gs/gateways/{gateway_id}/mqtt-connection-info

Method GtwGs.GetMQTTV2ConnectionInfo
Description Get legacy connection information to connect a The Things Network Stack V2 MQTT gateway.
Request type GatewayIdentifiers
Response type MQTTConnectionInfo
HTTP bindings

GET /api/v3/gs/gateways/{gateway_id}/mqttv2-connection-info

The GsNs service

Method GsNs.HandleUplink
Description Called by the Gateway Server when an uplink message arrives.
Request type UplinkMessage
Response type google.protobuf.Empty
HTTP bindings
Method GsNs.ReportTxAcknowledgment
Description Called by the Gateway Server when a Tx acknowledgment arrives.
Request type GatewayTxAcknowledgment
Response type google.protobuf.Empty
HTTP bindings

Messages

Message ApplicationIdentifiers

Show object example
{
  "application_id": "",
}

Fields:

Field application_id
Type string
Description

max_len: 36

pattern: ^[a-z0-9](?:[-]?[a-z0-9]){2,}$

Message BatchGetGatewayConnectionStatsRequest

Show object example
{
  "gateway_ids": [],
  "field_mask": {},
}

Fields:

Field gateway_ids
Type repeated GatewayIdentifiers
Description

max_items: 100

min_items: 1

Field field_mask
Type google.protobuf. FieldMask
Description

The names of the gateway stats fields that should be returned. This mask will be applied on each entry returned.

Message BatchGetGatewayConnectionStatsResponse

Show object example
{
  "entries": {},
}

Fields:

Field entries
Type map of string to GatewayConnectionStats
Description

The map key is the gateway identifier.

Message CFList

Show object example
{
  "type": "FREQUENCIES",
  "freq": [],
  "ch_masks": [],
}

Fields:

Field type
Type CFListType
Description

defined_only

Field freq
Type repeated uint32
Description

Frequencies to be broadcasted, in hecto-Hz. These values are broadcasted as 24 bits unsigned integers. This field should not contain default values.

Field ch_masks
Type repeated bool
Description

ChMasks controlling the channels to be used. Length of this field must be equal to the amount of uplink channels defined by the selected frequency plan.

Message ConcentratorConfig

Show object example
{
  "channels": [],
  "lora_standard_channel": {},
  "fsk_channel": {},
  "lbt": {},
  "ping_slot": {},
  "radios": [],
  "clock_source": 0,
}

Fields:

Field channels
Type repeated ConcentratorConfig.Channel
Description
Field lora_standard_channel
Type ConcentratorConfig.LoRaStandardChannel
Field fsk_channel
Type ConcentratorConfig.FSKChannel
Field lbt
Type ConcentratorConfig.LBTConfiguration
Field ping_slot
Type ConcentratorConfig.Channel
Field radios
Type repeated GatewayRadio
Description
Field clock_source
Type uint32

Message ConcentratorConfig.Channel

Show object example
{
  "frequency": 0,
  "radio": 0,
}

Fields:

Field frequency
Type uint64
Description

Frequency (Hz).

Field radio
Type uint32

Message ConcentratorConfig.LoRaStandardChannel

Show object example
{
  "frequency": 0,
  "radio": 0,
  "bandwidth": 0,
  "spreading_factor": 0,
}

Fields:

Field frequency
Type uint64
Description

Frequency (Hz).

Field radio
Type uint32
Field bandwidth
Type uint32
Description

Bandwidth (Hz).

Field spreading_factor
Type uint32

Message ConcentratorConfig.FSKChannel

Show object example
{
  "frequency": 0,
  "radio": 0,
}

Fields:

Field frequency
Type uint64
Description

Frequency (Hz).

Field radio
Type uint32

Message ConcentratorConfig.LBTConfiguration

Show object example
{
  "rssi_target": 0,
  "rssi_offset": 0,
  "scan_time": "0s",
}

Fields:

Field rssi_target
Type float
Description

Received signal strength (dBm).

Field rssi_offset
Type float
Description

Received signal strength offset (dBm).

Field scan_time
Type google.protobuf. Duration

Message DownlinkPath

Restrictions:
  • Only one of uplink_token, fixed can be set.
Show object example
{
  "uplink_token": "",
  "fixed": {},
}

Fields:

Field uplink_token
Type bytes
Field fixed
Type GatewayAntennaIdentifiers

Message DataRate

Restrictions:
  • Only one of lora, fsk, lrfhss can be set.
Show object example
{
  "lora": {},
  "fsk": {},
  "lrfhss": {},
}

Fields:

Field lora
Type LoRaDataRate
Field fsk
Type FSKDataRate
Field lrfhss
Type LRFHSSDataRate

Message DLSettings

Show object example
{
  "rx1_dr_offset": "DATA_RATE_OFFSET_0",
  "rx2_dr": "DATA_RATE_0",
  "opt_neg": false,
}

Fields:

Field rx1_dr_offset
Type DataRateOffset
Description

defined_only

Field rx2_dr
Type DataRateIndex
Description

defined_only

Field opt_neg
Type bool
Description

OptNeg is set if Network Server implements LoRaWAN 1.1 or greater.

Message DownlinkMessage

Downlink message from the network to the end device

Restrictions:
  • Only one of request, scheduled can be set.
Show object example
{
  "raw_payload": "",
  "payload": {},
  "end_device_ids": {},
  "request": {},
  "scheduled": {},
  "correlation_ids": [],
  "session_key_id": "",
}

Fields:

Field raw_payload
Type bytes
Field payload
Type Message
Field end_device_ids
Type EndDeviceIdentifiers
Field request
Type TxRequest
Field scheduled
Type TxSettings
Field correlation_ids
Type repeated string
Description

max_len: 100

Field session_key_id
Type bytes
Description

max_len: 2048

Message EndDeviceIdentifiers

Show object example
{
  "device_id": "",
  "application_ids": {},
  "dev_eui": "",
  "join_eui": "",
  "dev_addr": "",
}

Fields:

Field device_id
Type string
Description

max_len: 36

pattern: ^[a-z0-9](?:[-]?[a-z0-9]){2,}$

Field application_ids
Type ApplicationIdentifiers
Description

required

Field dev_eui
Type bytes
Description

The LoRaWAN DevEUI.

ignore_empty

len: 8

Field join_eui
Type bytes
Description

The LoRaWAN JoinEUI (AppEUI until LoRaWAN 1.0.3 end devices).

ignore_empty

len: 8

Field dev_addr
Type bytes
Description

The LoRaWAN DevAddr.

ignore_empty

len: 4

Message FHDR

Show object example
{
  "dev_addr": "",
  "f_ctrl": {},
  "f_cnt": 0,
  "f_opts": "",
}

Fields:

Field dev_addr
Type bytes
Description

ignore_empty

len: 4

Field f_ctrl
Type FCtrl
Description

required

Field f_cnt
Type uint32
Description

lte: 65535

Field f_opts
Type bytes
Description

max_len: 15

Message FCtrl

Show object example
{
  "adr": false,
  "adr_ack_req": false,
  "ack": false,
  "f_pending": false,
  "class_b": false,
}

Fields:

Field adr
Type bool
Field adr_ack_req
Type bool
Description

Only on uplink.

Field ack
Type bool
Field f_pending
Type bool
Description

Only on downlink.

Field class_b
Type bool
Description

Only on uplink.

Message FSKDataRate

Show object example
{
  "bit_rate": 0,
}

Fields:

Field bit_rate
Type uint32
Description

Bit rate (bps).

Message GatewayAntennaIdentifiers

Show object example
{
  "gateway_ids": {},
  "antenna_index": 0,
}

Fields:

Field gateway_ids
Type GatewayIdentifiers
Description

required

Field antenna_index
Type uint32

Message GatewayIdentifiers

Show object example
{
  "gateway_id": "",
  "eui": "",
}

Fields:

Field gateway_id
Type string
Description

max_len: 36

pattern: ^[a-z0-9](?:[-]?[a-z0-9]){2,}$

Field eui
Type bytes
Description

Secondary identifier, which can only be used in specific requests.

ignore_empty

len: 8

Message GetGatewayConfigurationRequest

Show object example
{
  "gateway_ids": {},
  "format": "",
  "type": "",
  "filename": "",
}

Fields:

Field gateway_ids
Type GatewayIdentifiers
Description

required

Field format
Type string
Description

max_len: 36

pattern: ^[a-z0-9](?:[-]?[a-z0-9]){2,}$|^$

Field type
Type string
Description

max_len: 36

pattern: ^[a-z0-9](?:[-]?[a-z0-9]){2,}$|^$

Field filename
Type string
Description

max_len: 36

pattern: ^[a-z0-9](?:[-._]?[a-z0-9]){2,}$|^$

Message GetGatewayConfigurationResponse

Show object example
{
  "contents": "",
}

Fields:

Field contents
Type bytes

Message GatewayConnectionStats

Connection stats as monitored by the Gateway Server.

Show object example
{
  "connected_at": "0001-01-01T00:00:00Z",
  "disconnected_at": "0001-01-01T00:00:00Z",
  "protocol": "",
  "last_status_received_at": "0001-01-01T00:00:00Z",
  "last_status": {},
  "last_uplink_received_at": "0001-01-01T00:00:00Z",
  "uplink_count": 0,
  "last_downlink_received_at": "0001-01-01T00:00:00Z",
  "downlink_count": 0,
  "last_tx_acknowledgment_received_at": "0001-01-01T00:00:00Z",
  "tx_acknowledgment_count": 0,
  "round_trip_times": {},
  "sub_bands": [],
  "gateway_remote_address": {},
}

Fields:

Field connected_at
Type google.protobuf. Timestamp
Field disconnected_at
Type google.protobuf. Timestamp
Field protocol
Type string
Description

Protocol used to connect (for example, udp, mqtt, grpc)

Field last_status_received_at
Type google.protobuf. Timestamp
Field last_status
Type GatewayStatus
Field last_uplink_received_at
Type google.protobuf. Timestamp
Field uplink_count
Type uint64
Field last_downlink_received_at
Type google.protobuf. Timestamp
Field downlink_count
Type uint64
Field last_tx_acknowledgment_received_at
Type google.protobuf. Timestamp
Field tx_acknowledgment_count
Type uint64
Field round_trip_times
Type GatewayConnectionStats.RoundTripTimes
Field sub_bands
Type repeated GatewayConnectionStats.SubBand
Description

Statistics for each sub band.

Field gateway_remote_address
Type GatewayRemoteAddress
Description

Gateway Remote Address.

Message GatewayConnectionStats.RoundTripTimes

Show object example
{
  "min": "0s",
  "max": "0s",
  "median": "0s",
  "count": 0,
}

Fields:

Field min
Type google.protobuf. Duration
Field max
Type google.protobuf. Duration
Field median
Type google.protobuf. Duration
Field count
Type uint32

Message GatewayConnectionStats.SubBand

Show object example
{
  "min_frequency": 0,
  "max_frequency": 0,
  "downlink_utilization_limit": 0,
  "downlink_utilization": 0,
}

Fields:

Field min_frequency
Type uint64
Field max_frequency
Type uint64
Field downlink_utilization_limit
Type float
Description

Duty-cycle limit of the sub-band as a fraction of time.

Field downlink_utilization
Type float
Description

Utilization rate of the available duty-cycle. This value should not exceed downlink_utilization_limit.

Message GatewayDown

GatewayDown contains downlink messages for the gateway.

Show object example
{
  "downlink_message": {},
}

Fields:

Field downlink_message
Type DownlinkMessage
Description

DownlinkMessage for the gateway.

Message GatewayStatus

Show object example
{
  "time": "0001-01-01T00:00:00Z",
  "boot_time": "0001-01-01T00:00:00Z",
  "versions": {},
  "antenna_locations": [],
  "ip": [],
  "metrics": {},
  "advanced": {},
}

Fields:

Field time
Type google.protobuf. Timestamp
Description

Current time of the gateway

Field boot_time
Type google.protobuf. Timestamp
Description

Boot time of the gateway

  • can be left out to save bandwidth; old value will be kept

Field versions
Type map of string to string
Description

Versions of gateway subsystems

  • each field can be left out to save bandwidth; old value will be kept
  • map keys are written in snake_case
  • for example: firmware: “2.0.4” forwarder: “v2-3.3.1” fpga: “48” dsp: “27” hal: “v2-3.5.0”

max_pairs: 10

max_len (key): 36

pattern (key): ^[a-z0-9](?:[_-]?[a-z0-9]){2,}$

max_len (value): 128

Field antenna_locations
Type repeated Location
Description

Location of each gateway’s antenna

  • if left out, server uses registry-set location as fallback

max_items: 8

Field ip
Type repeated string
Description

IP addresses of this gateway. Repeated addresses can be used to communicate addresses of multiple interfaces (LAN, Public IP, …).

max_items: 10

ip

Field metrics
Type map of string to float
Description

Metrics

  • can be used for forwarding gateway metrics such as temperatures or performance metrics
  • map keys are written in snake_case

max_pairs: 32

max_len (key): 36

pattern (key): ^[a-z0-9](?:[_-]?[a-z0-9]){2,}$

Field advanced
Type google.protobuf. Struct
Description

Advanced metadata fields

  • can be used for advanced information or experimental features that are not yet formally defined in the API
  • field names are written in snake_case

Message GatewayRadio

Show object example
{
  "enable": false,
  "chip_type": "",
  "frequency": 0,
  "rssi_offset": 0,
  "tx_configuration": {},
}

Fields:

Field enable
Type bool
Field chip_type
Type string
Field frequency
Type uint64
Field rssi_offset
Type float
Field tx_configuration
Type GatewayRadio.TxConfiguration

Message GatewayRadio.TxConfiguration

Show object example
{
  "min_frequency": 0,
  "max_frequency": 0,
  "notch_frequency": 0,
}

Fields:

Field min_frequency
Type uint64
Field max_frequency
Type uint64
Field notch_frequency
Type uint64

Message GatewayRemoteAddress

Remote Address of the Gateway, as seen by the Gateway Server.

Show object example
{
  "ip": "",
}

Fields:

Field ip
Type string
Description

IPv4 or IPv6 address.

Message GatewayTxAcknowledgment

Show object example
{
  "gateway_ids": {},
  "tx_ack": {},
}

Fields:

Field gateway_ids
Type GatewayIdentifiers
Field tx_ack
Type TxAcknowledgment

Message GatewayUp

GatewayUp may contain zero or more uplink messages and/or a status message for the gateway.

Show object example
{
  "uplink_messages": [],
  "gateway_status": {},
  "tx_acknowledgment": {},
}

Fields:

Field uplink_messages
Type repeated UplinkMessage
Description

Uplink messages received by the gateway.

Field gateway_status
Type GatewayStatus
Description

Gateway status produced by the gateway.

Field tx_acknowledgment
Type TxAcknowledgment
Description

A Tx acknowledgment or error.

Message JoinAcceptPayload

Show object example
{
  "encrypted": "",
  "join_nonce": "",
  "net_id": "",
  "dev_addr": "",
  "dl_settings": {},
  "rx_delay": "RX_DELAY_0",
  "cf_list": {},
}

Fields:

Field encrypted
Type bytes
Field join_nonce
Type bytes
Description

ignore_empty

len: 3

Field net_id
Type bytes
Description

ignore_empty

len: 3

Field dev_addr
Type bytes
Description

ignore_empty

len: 4

Field dl_settings
Type DLSettings
Description

required

Field rx_delay
Type RxDelay
Description

defined_only

Field cf_list
Type CFList

Message JoinRequestPayload

Show object example
{
  "join_eui": "",
  "dev_eui": "",
  "dev_nonce": "",
}

Fields:

Field join_eui
Type bytes
Description

ignore_empty

len: 8

Field dev_eui
Type bytes
Description

ignore_empty

len: 8

Field dev_nonce
Type bytes
Description

ignore_empty

len: 2

Message Location

Show object example
{
  "latitude": 0,
  "longitude": 0,
  "altitude": 0,
  "accuracy": 0,
  "source": "SOURCE_UNKNOWN",
}

Fields:

Field latitude
Type double
Description

The North–South position (degrees; -90 to +90), where 0 is the equator, North pole is positive, South pole is negative.

gte: -90

lte: 90

Field longitude
Type double
Description

The East-West position (degrees; -180 to +180), where 0 is the Prime Meridian (Greenwich), East is positive , West is negative.

gte: -180

lte: 180

Field altitude
Type int32
Description

The altitude (meters), where 0 is the mean sea level.

Field accuracy
Type int32
Description

The accuracy of the location (meters).

Field source
Type LocationSource
Description

Source of the location information.

defined_only

Message LoRaDataRate

Show object example
{
  "bandwidth": 0,
  "spreading_factor": 0,
  "coding_rate": "",
}

Fields:

Field bandwidth
Type uint32
Description

Bandwidth (Hz).

Field spreading_factor
Type uint32
Field coding_rate
Type string

Message LRFHSSDataRate

Show object example
{
  "modulation_type": 0,
  "operating_channel_width": 0,
  "coding_rate": "",
}

Fields:

Field modulation_type
Type uint32
Field operating_channel_width
Type uint32
Description

Operating Channel Width (Hz).

Field coding_rate
Type string

Message MACPayload

Show object example
{
  "f_hdr": {},
  "f_port": 0,
  "frm_payload": "",
  "decoded_payload": {},
  "full_f_cnt": 0,
}

Fields:

Field f_hdr
Type FHDR
Description

required

Field f_port
Type uint32
Description

lte: 255

Field frm_payload
Type bytes
Field decoded_payload
Type google.protobuf. Struct
Field full_f_cnt
Type uint32
Description

Full 32-bit FCnt value. Used internally by Network Server.

Message Message

Message represents a LoRaWAN message

Restrictions:
  • Only one of mac_payload, join_request_payload, join_accept_payload, rejoin_request_payload can be set.
Show object example
{
  "m_hdr": {},
  "mic": "",
  "mac_payload": {},
  "join_request_payload": {},
  "join_accept_payload": {},
  "rejoin_request_payload": {},
}

Fields:

Field m_hdr
Type MHDR
Description

required

Field mic
Type bytes
Description

max_len: 4

Field mac_payload
Type MACPayload
Field join_request_payload
Type JoinRequestPayload
Field join_accept_payload
Type JoinAcceptPayload
Field rejoin_request_payload
Type RejoinRequestPayload

Message MHDR

Show object example
{
  "m_type": "JOIN_REQUEST",
  "major": "LORAWAN_R1",
}

Fields:

Field m_type
Type MType
Description

defined_only

Field major
Type Major
Description

defined_only

Message MQTTConnectionInfo

The connection information of an MQTT frontend.

Show object example
{
  "public_address": "",
  "public_tls_address": "",
  "username": "",
}

Fields:

Field public_address
Type string
Description

The public listen address of the frontend.

pattern: ^(?:(?:[a-zA-Z0-9]|[a-zA-Z0-9][a-zA-Z0-9\-]*[a-zA-Z0-9])\.)*(?:[A-Za-z0-9]|[A-Za-z0-9][A-Za-z0-9\-]*[A-Za-z0-9])(?::[0-9]{1,5})?$|^$

Field public_tls_address
Type string
Description

The public listen address of the TLS frontend.

pattern: ^(?:(?:[a-zA-Z0-9]|[a-zA-Z0-9][a-zA-Z0-9\-]*[a-zA-Z0-9])\.)*(?:[A-Za-z0-9]|[A-Za-z0-9][A-Za-z0-9\-]*[A-Za-z0-9])(?::[0-9]{1,5})?$|^$

Field username
Type string
Description

The username to be used for authentication.

Message PullGatewayConfigurationRequest

Show object example
{
  "gateway_ids": {},
  "field_mask": {},
}

Fields:

Field gateway_ids
Type GatewayIdentifiers
Field field_mask
Type google.protobuf. FieldMask

Message PacketBrokerMetadata

Show object example
{
  "message_id": "",
  "forwarder_net_id": "",
  "forwarder_tenant_id": "",
  "forwarder_cluster_id": "",
  "forwarder_gateway_eui": "",
  "forwarder_gateway_id": null,
  "home_network_net_id": "",
  "home_network_tenant_id": "",
  "home_network_cluster_id": "",
  "hops": [],
}

Fields:

Field message_id
Type string
Description

Message identifier generated by Packet Broker Router.

Field forwarder_net_id
Type bytes
Description

LoRa Alliance NetID of the Packet Broker Forwarder Member.

ignore_empty

len: 3

Field forwarder_tenant_id
Type string
Description

Tenant ID managed by the Packet Broker Forwarder Member.

Field forwarder_cluster_id
Type string
Description

Forwarder Cluster ID of the Packet Broker Forwarder.

Field forwarder_gateway_eui
Type bytes
Description

Forwarder gateway EUI.

ignore_empty

len: 8

Field forwarder_gateway_id
Type google.protobuf. StringValue
Description

Forwarder gateway ID.

Field home_network_net_id
Type bytes
Description

LoRa Alliance NetID of the Packet Broker Home Network Member.

ignore_empty

len: 3

Field home_network_tenant_id
Type string
Description

Tenant ID managed by the Packet Broker Home Network Member. This value is empty if it cannot be determined by the Packet Broker Router.

Field home_network_cluster_id
Type string
Description

Home Network Cluster ID of the Packet Broker Home Network.

Field hops
Type repeated PacketBrokerRouteHop
Description

Hops that the message passed. Each Packet Broker Router service appends an entry.

Message PacketBrokerRouteHop

Show object example
{
  "received_at": "0001-01-01T00:00:00Z",
  "sender_name": "",
  "sender_address": "",
  "receiver_name": "",
  "receiver_agent": "",
}

Fields:

Field received_at
Type google.protobuf. Timestamp
Description

Time when the service received the message.

Field sender_name
Type string
Description

Sender of the message, typically the authorized client identifier.

Field sender_address
Type string
Description

Sender IP address or host name.

Field receiver_name
Type string
Description

Receiver of the message.

Field receiver_agent
Type string
Description

Receiver agent.

Message RejoinRequestPayload

Show object example
{
  "rejoin_type": "CONTEXT",
  "net_id": "",
  "join_eui": "",
  "dev_eui": "",
  "rejoin_cnt": 0,
}

Fields:

Field rejoin_type
Type RejoinRequestType
Description

defined_only

Field net_id
Type bytes
Description

ignore_empty

len: 3

Field join_eui
Type bytes
Description

ignore_empty

len: 8

Field dev_eui
Type bytes
Description

ignore_empty

len: 8

Field rejoin_cnt
Type uint32
Description

Contains RJCount0 or RJCount1 depending on rejoin_type.

Message RelayMetadata

Show object example
{
  "device_id": "",
  "wor_channel": "RELAY_WOR_CHANNEL_DEFAULT",
}

Fields:

Field device_id
Type string
Description

End device identifiers of the relay.

max_len: 36

pattern: ^[a-z0-9](?:[-]?[a-z0-9]){2,}$

Field wor_channel
Type RelayWORChannel
Description

Wake on radio channel.

defined_only

Message RxMetadata

Contains metadata for a received message. Each antenna that receives a message corresponds to one RxMetadata.

Show object example
{
  "gateway_ids": {},
  "packet_broker": {},
  "relay": {},
  "antenna_index": 0,
  "time": "0001-01-01T00:00:00Z",
  "timestamp": 0,
  "fine_timestamp": 0,
  "encrypted_fine_timestamp": "",
  "encrypted_fine_timestamp_key_id": "",
  "rssi": 0,
  "signal_rssi": null,
  "channel_rssi": 0,
  "rssi_standard_deviation": 0,
  "snr": 0,
  "frequency_offset": 0,
  "location": {},
  "downlink_path_constraint": "DOWNLINK_PATH_CONSTRAINT_NONE",
  "uplink_token": "",
  "channel_index": 0,
  "hopping_width": 0,
  "frequency_drift": 0,
  "gps_time": "0001-01-01T00:00:00Z",
  "received_at": "0001-01-01T00:00:00Z",
  "advanced": {},
}

Fields:

Field gateway_ids
Type GatewayIdentifiers
Description

required

Field packet_broker
Type PacketBrokerMetadata
Field relay
Type RelayMetadata
Field antenna_index
Type uint32
Field time
Type google.protobuf. Timestamp
Description

Timestamp at the end of the transmission, provided by the gateway. The accuracy is undefined.

Field timestamp
Type uint32
Description

Gateway concentrator timestamp when the Rx finished (microseconds).

Field fine_timestamp
Type uint64
Description

Gateway’s internal fine timestamp when the Rx finished (nanoseconds).

Field encrypted_fine_timestamp
Type bytes
Description

Encrypted gateway’s internal fine timestamp when the Rx finished (nanoseconds).

Field encrypted_fine_timestamp_key_id
Type string
Field rssi
Type float
Description

Received signal strength indicator (dBm). This value equals channel_rssi.

Field signal_rssi
Type google.protobuf. FloatValue
Description

Received signal strength indicator of the signal (dBm).

Field channel_rssi
Type float
Description

Received signal strength indicator of the channel (dBm).

Field rssi_standard_deviation
Type float
Description

Standard deviation of the RSSI during preamble.

Field snr
Type float
Description

Signal-to-noise ratio (dB).

Field frequency_offset
Type int64
Description

Frequency offset (Hz).

Field location
Type Location
Description

Antenna location; injected by the Gateway Server.

Field downlink_path_constraint
Type DownlinkPathConstraint
Description

Gateway downlink path constraint; injected by the Gateway Server.

defined_only

Field uplink_token
Type bytes
Description

Uplink token to be included in the Tx request in class A downlink; injected by gateway, Gateway Server or fNS.

Field channel_index
Type uint32
Description

Index of the gateway channel that received the message.

lte: 255

Field hopping_width
Type uint32
Description

Hopping width; a number describing the number of steps of the LR-FHSS grid.

Field frequency_drift
Type int32
Description

Frequency drift in Hz between start and end of an LR-FHSS packet (signed).

Field gps_time
Type google.protobuf. Timestamp
Description

Timestamp at the end of the transmission, provided by the gateway. Guaranteed to be based on a GPS PPS signal, with an accuracy of 1 millisecond.

Field received_at
Type google.protobuf. Timestamp
Description

Timestamp at which the Gateway Server has received the message.

Field advanced
Type google.protobuf. Struct
Description

Advanced metadata fields

  • can be used for advanced information or experimental features that are not yet formally defined in the API
  • field names are written in snake_case

Message UplinkMessage

Uplink message from the end device to the network

Show object example
{
  "raw_payload": "",
  "payload": {},
  "settings": {},
  "rx_metadata": [],
  "received_at": "0001-01-01T00:00:00Z",
  "correlation_ids": [],
  "device_channel_index": 0,
  "consumed_airtime": "0s",
  "crc_status": null,
}

Fields:

Field raw_payload
Type bytes
Field payload
Type Message
Field settings
Type TxSettings
Description

required

Field rx_metadata
Type repeated RxMetadata
Description
Field received_at
Type google.protobuf. Timestamp
Description

Server time when a component received the message. The Gateway Server and Network Server set this value to their local server time of reception.

Field correlation_ids
Type repeated string
Description

max_len: 100

Field device_channel_index
Type uint32
Description

Index of the device channel that received the message. Set by Network Server.

lte: 255

Field consumed_airtime
Type google.protobuf. Duration
Description

Consumed airtime for the transmission of the uplink message. Calculated by Network Server using the RawPayload size and the transmission settings.

Field crc_status
Type google.protobuf. BoolValue
Description

Cyclic Redundancy Check (CRC) status of demodulating the frame. If unset, the modulation does not support CRC or the gateway did not provide a CRC status. If set to false, this message should not be processed.

Message TxAcknowledgment

Show object example
{
  "correlation_ids": [],
  "result": "SUCCESS",
  "downlink_message": {},
}

Fields:

Field correlation_ids
Type repeated string
Description

Correlation IDs for the downlink message. Set automatically by the UDP and LBS frontends. For gRPC and the MQTT v3 frontends, the correlation IDs must match the ones of the downlink message the Tx acknowledgment message refers to.

max_len: 100

Field result
Type TxAcknowledgment.Result
Description

defined_only

Field downlink_message
Type DownlinkMessage
Description

The acknowledged downlink message. Set by the Gateway Server.

Message TxSettings.Downlink

Transmission settings for downlink.

Show object example
{
  "antenna_index": 0,
  "tx_power": 0,
  "invert_polarization": false,
}

Fields:

Field antenna_index
Type uint32
Description

Index of the antenna on which the uplink was received and/or downlink must be sent.

Field tx_power
Type float
Description

Transmission power (dBm). Only on downlink.

Field invert_polarization
Type bool
Description

Invert LoRa polarization; false for LoRaWAN uplink, true for downlink.

Message TxRequest

TxRequest is a request for transmission. If sent to a roaming partner, this request is used to generate the DLMetadata Object (see Backend Interfaces 1.0, Table 22). If the gateway has a scheduler, this request is sent to the gateway, in the order of gateway_ids. Otherwise, the Gateway Server attempts to schedule the request and creates the TxSettings.

Show object example
{
  "class": "CLASS_A",
  "downlink_paths": [],
  "rx1_delay": "RX_DELAY_0",
  "rx1_data_rate": {},
  "rx1_frequency": 0,
  "rx2_data_rate": {},
  "rx2_frequency": 0,
  "priority": "LOWEST",
  "absolute_time": "0001-01-01T00:00:00Z",
  "frequency_plan_id": "",
  "advanced": {},
}

Fields:

Field class
Type Class
Field downlink_paths
Type repeated DownlinkPath
Description

Downlink paths used to select a gateway for downlink. In class A, the downlink paths are required to only contain uplink tokens. In class B and C, the downlink paths may contain uplink tokens and fixed gateways antenna identifiers.

Field rx1_delay
Type RxDelay
Description

Rx1 delay (Rx2 delay is Rx1 delay + 1 second).

defined_only

Field rx1_data_rate
Type DataRate
Description

LoRaWAN data rate for Rx1.

Field rx1_frequency
Type uint64
Description

Frequency (Hz) for Rx1.

Field rx2_data_rate
Type DataRate
Description

LoRaWAN data rate for Rx2.

Field rx2_frequency
Type uint64
Description

Frequency (Hz) for Rx2.

Field priority
Type TxSchedulePriority
Description

Priority for scheduling. Requests with a higher priority are allocated more channel time than messages with a lower priority, in duty-cycle limited regions. A priority of HIGH or higher sets the HiPriorityFlag in the DLMetadata Object.

defined_only

Field absolute_time
Type google.protobuf. Timestamp
Description

Time when the downlink message should be transmitted. This value is only valid for class C downlink; class A downlink uses uplink tokens and class B downlink is scheduled on ping slots. This requires the gateway to have GPS time sychronization. If the absolute time is not set, the first available time will be used that does not conflict or violate regional limitations.

Field frequency_plan_id
Type string
Description

Frequency plan ID from which the frequencies in this message are retrieved.

max_len: 64

Field advanced
Type google.protobuf. Struct
Description

Advanced metadata fields

  • can be used for advanced information or experimental features that are not yet formally defined in the API
  • field names are written in snake_case

Message TxRequest

TxRequest is a request for transmission. If sent to a roaming partner, this request is used to generate the DLMetadata Object (see Backend Interfaces 1.0, Table 22). If the gateway has a scheduler, this request is sent to the gateway, in the order of gateway_ids. Otherwise, the Gateway Server attempts to schedule the request and creates the TxSettings.

Show object example
{
  "class": "CLASS_A",
  "downlink_paths": [],
  "rx1_delay": "RX_DELAY_0",
  "rx1_data_rate": {},
  "rx1_frequency": 0,
  "rx2_data_rate": {},
  "rx2_frequency": 0,
  "priority": "LOWEST",
  "absolute_time": "0001-01-01T00:00:00Z",
  "frequency_plan_id": "",
  "advanced": {},
}

Fields:

Field class
Type Class
Field downlink_paths
Type repeated DownlinkPath
Description

Downlink paths used to select a gateway for downlink. In class A, the downlink paths are required to only contain uplink tokens. In class B and C, the downlink paths may contain uplink tokens and fixed gateways antenna identifiers.

Field rx1_delay
Type RxDelay
Description

Rx1 delay (Rx2 delay is Rx1 delay + 1 second).

defined_only

Field rx1_data_rate
Type DataRate
Description

LoRaWAN data rate for Rx1.

Field rx1_frequency
Type uint64
Description

Frequency (Hz) for Rx1.

Field rx2_data_rate
Type DataRate
Description

LoRaWAN data rate for Rx2.

Field rx2_frequency
Type uint64
Description

Frequency (Hz) for Rx2.

Field priority
Type TxSchedulePriority
Description

Priority for scheduling. Requests with a higher priority are allocated more channel time than messages with a lower priority, in duty-cycle limited regions. A priority of HIGH or higher sets the HiPriorityFlag in the DLMetadata Object.

defined_only

Field absolute_time
Type google.protobuf. Timestamp
Description

Time when the downlink message should be transmitted. This value is only valid for class C downlink; class A downlink uses uplink tokens and class B downlink is scheduled on ping slots. This requires the gateway to have GPS time sychronization. If the absolute time is not set, the first available time will be used that does not conflict or violate regional limitations.

Field frequency_plan_id
Type string
Description

Frequency plan ID from which the frequencies in this message are retrieved.

max_len: 64

Field advanced
Type google.protobuf. Struct
Description

Advanced metadata fields

  • can be used for advanced information or experimental features that are not yet formally defined in the API
  • field names are written in snake_case

Message TxSettings

TxSettings contains the settings for a transmission. This message is used on both uplink and downlink. On downlink, this is a scheduled transmission.

Show object example
{
  "data_rate": {},
  "frequency": 0,
  "enable_crc": false,
  "timestamp": 0,
  "time": "0001-01-01T00:00:00Z",
  "downlink": {},
  "concentrator_timestamp": 0,
}

Fields:

Field data_rate
Type DataRate
Description

Data rate.

required

Field frequency
Type uint64
Description

Frequency (Hz).

gte: 100000

Field enable_crc
Type bool
Description

Send a CRC in the packet; only on uplink; on downlink, CRC should not be enabled.

Field timestamp
Type uint32
Description

Timestamp of the gateway concentrator when the uplink message was received, or when the downlink message should be transmitted (microseconds). On downlink, set timestamp to 0 and time to null to use immediate scheduling.

Field time
Type google.protobuf. Timestamp
Description

Time of the gateway when the uplink message was received, or when the downlink message should be transmitted. For downlink, this requires the gateway to have GPS time synchronization.

Field downlink
Type TxSettings.Downlink
Description

Transmission settings for downlink.

Field concentrator_timestamp
Type int64
Description

Concentrator timestamp for the downlink as calculated by the Gateway Server scheduler. This value takes into account necessary offsets such as the RTT (Round Trip Time) and TOA (Time Of Arrival). This field is set and used only by the Gateway Server.

Enums

Enum Class

Name Value Description
CLASS_A 0
CLASS_B 1
CLASS_C 2

Enum CFListType

Name Value Description
FREQUENCIES 0
CHANNEL_MASKS 1

Enum DataRateIndex

Name Value Description
DATA_RATE_0 0
DATA_RATE_1 1
DATA_RATE_2 2
DATA_RATE_3 3
DATA_RATE_4 4
DATA_RATE_5 5
DATA_RATE_6 6
DATA_RATE_7 7
DATA_RATE_8 8
DATA_RATE_9 9
DATA_RATE_10 10
DATA_RATE_11 11
DATA_RATE_12 12
DATA_RATE_13 13
DATA_RATE_14 14
DATA_RATE_15 15

Enum DataRateOffset

Name Value Description
DATA_RATE_OFFSET_0 0
DATA_RATE_OFFSET_1 1
DATA_RATE_OFFSET_2 2
DATA_RATE_OFFSET_3 3
DATA_RATE_OFFSET_4 4
DATA_RATE_OFFSET_5 5
DATA_RATE_OFFSET_6 6
DATA_RATE_OFFSET_7 7

Enum DownlinkPathConstraint

Name Value Description
DOWNLINK_PATH_CONSTRAINT_NONE 0 Indicates that the gateway can be selected for downlink without constraints by the Network Server.
DOWNLINK_PATH_CONSTRAINT_PREFER_OTHER 1 Indicates that the gateway can be selected for downlink only if no other or better gateway can be selected.
DOWNLINK_PATH_CONSTRAINT_NEVER 2 Indicates that this gateway will never be selected for downlink, even if that results in no available downlink path.

Enum LocationSource

Name Value Description
SOURCE_UNKNOWN 0 The source of the location is not known or not set.
SOURCE_GPS 1 The location is determined by GPS.
SOURCE_REGISTRY 3 The location is set in and updated from a registry.
SOURCE_IP_GEOLOCATION 4 The location is estimated with IP geolocation.
SOURCE_WIFI_RSSI_GEOLOCATION 5 The location is estimated with WiFi RSSI geolocation.
SOURCE_BT_RSSI_GEOLOCATION 6 The location is estimated with BT/BLE RSSI geolocation.
SOURCE_LORA_RSSI_GEOLOCATION 7 The location is estimated with LoRa RSSI geolocation.
SOURCE_LORA_TDOA_GEOLOCATION 8 The location is estimated with LoRa TDOA geolocation.
SOURCE_COMBINED_GEOLOCATION 9 The location is estimated by a combination of geolocation sources.

Enum Major

Name Value Description
LORAWAN_R1 0

Enum MType

Name Value Description
JOIN_REQUEST 0
JOIN_ACCEPT 1
UNCONFIRMED_UP 2
UNCONFIRMED_DOWN 3
CONFIRMED_UP 4
CONFIRMED_DOWN 5
REJOIN_REQUEST 6
PROPRIETARY 7

Enum RejoinRequestType

Name Value Description
CONTEXT 0 Resets DevAddr, Session Keys, Frame Counters, Radio Parameters.
SESSION 1 Equivalent to the initial JoinRequest.
KEYS 2 Resets DevAddr, Session Keys, Frame Counters, while keeping the Radio Parameters.

Enum RelayWORChannel

Name Value Description
RELAY_WOR_CHANNEL_DEFAULT 0
RELAY_WOR_CHANNEL_SECONDARY 1

Enum RxDelay

Name Value Description
RX_DELAY_0 0 1 second.
RX_DELAY_1 1 1 second.
RX_DELAY_2 2 2 seconds.
RX_DELAY_3 3 3 seconds.
RX_DELAY_4 4 4 seconds.
RX_DELAY_5 5 5 seconds.
RX_DELAY_6 6 6 seconds.
RX_DELAY_7 7 7 seconds.
RX_DELAY_8 8 8 seconds.
RX_DELAY_9 9 9 seconds.
RX_DELAY_10 10 10 seconds.
RX_DELAY_11 11 11 seconds.
RX_DELAY_12 12 12 seconds.
RX_DELAY_13 13 13 seconds.
RX_DELAY_14 14 14 seconds.
RX_DELAY_15 15 15 seconds.

Enum TxAcknowledgment.Result

Name Value Description
SUCCESS 0
UNKNOWN_ERROR 1
TOO_LATE 2
TOO_EARLY 3
COLLISION_PACKET 4
COLLISION_BEACON 5
TX_FREQ 6
TX_POWER 7
GPS_UNLOCKED 8

Enum TxSchedulePriority

Name Value Description
LOWEST 0
LOW 1
BELOW_NORMAL 2
NORMAL 3
ABOVE_NORMAL 4
HIGH 5
HIGHEST 6
← Gateway APIs Identity Server APIs →

On this page

  • The Gs service
  • The GatewayConfigurationService service
  • The GtwGs service
  • The GsNs service
  • Messages
  • Enums

Sections

Getting Started

Concepts

The Things Stack Cloud

The Things Stack Enterprise

Integrations

API

Hardware

Sitemap

View our Sitemap

Contributing

GitHub

About Us

The Things Industries