Storage Integration API

List of Storage Integration APIs.

The ApplicationUpStorage Service

Method ApplicationUpStorage.GetStoredApplicationUp
Description Returns a stream of application messages that have been stored in the database.
Request type GetStoredApplicationUpRequest
Response type Stream of ApplicationUp
The HTTP API uses Content-Type: text/event-stream
and a response body of newline-delimited JSON.
Make sure to send Accept: text/event-stream in the request.
HTTP bindings

GET /api/v3/as/applications/{end_device_ids.application_ids.application_id}/devices/{end_device_ids.device_id}/packages/storage/{type}

GET /api/v3/as/applications/{application_ids.application_id}/packages/storage/{type}
Method ApplicationUpStorage.GetStoredApplicationUpCount
Description Returns how many application messages have been stored in the database for an application or end device.
Request type GetStoredApplicationUpCountRequest
Response type GetStoredApplicationUpCountResponse
HTTP bindings

GET /api/v3/as/applications/{end_device_ids.application_ids.application_id}/devices/{end_device_ids.device_id}/packages/storage/{type}/count

GET /api/v3/as/applications/{application_ids.application_id}/packages/storage/{type}/count

Messages

Message GetStoredApplicationUpRequest

Show object example 
{
  "application_ids": {},
  "end_device_ids": {},
  "type": "",
  "limit": null,
  "after": "0001-01-01T00:00:00Z",
  "before": "0001-01-01T00:00:00Z",
  "f_port": null,
  "order": "",
  "field_mask": {},
  "last": "0s",
  "continuation_token": "",
}

Fields:

Field application_ids
Type ApplicationIdentifiers
Description

Query upstream messages from all end devices of an application. Cannot be used in conjunction with end_device_ids.
Field end_device_ids
Type EndDeviceIdentifiers
Description

Query upstream messages from a single end device. Cannot be used in conjunction with application_ids.
Field type
Type string
Description

Query upstream messages of a specific type. If not set, then all upstream messages are returned.

in: [ uplink_message uplink_normalized join_accept downlink_ack downlink_nack downlink_sent downlink_failed downlink_queued downlink_queue_invalidated location_solved service_data]
Field limit
Type google.protobuf. UInt32Value
Description

Limit number of results.
Field after
Type google.protobuf. Timestamp
Description

Query upstream messages after this timestamp only. Cannot be used in conjunction with last.
Field before
Type google.protobuf. Timestamp
Description

Query upstream messages before this timestamp only. Cannot be used in conjunction with last.
Field f_port
Type google.protobuf. UInt32Value
Description

Query uplinks on a specific FPort only.
Field order
Type string
Description

Order results.

in: [ -received_at received_at]
Field field_mask
Type google.protobuf. FieldMask
Description

The names of the upstream message fields that should be returned. See the API reference for allowed field names for each type of upstream message.
Field last
Type google.protobuf. Duration
Description

Query upstream messages that have arrived in the last minutes or hours. Cannot be used in conjunction with after and before.
Field continuation_token
Type string
Description

The continuation token, which is used to retrieve the next page. If provided, other fields are ignored.

max_len: 16000

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 ApplicationJoinAccept

Show object example 
{
  "session_key_id": "",
  "app_s_key": {},
  "invalidated_downlinks": [],
  "pending_session": false,
  "received_at": "0001-01-01T00:00:00Z",
  "locations": {},
  "version_ids": {},
  "network_ids": {},
  "attributes": {},
}

Fields:

Field session_key_id
Type bytes
Description

Join Server issued identifier for the session keys negotiated in this join.

max_len: 2048
Field app_s_key
Type KeyEnvelope
Description

Encrypted Application Session Key (if Join Server sent it to Network Server).
Field invalidated_downlinks
Type repeated ApplicationDownlink
Description

Downlink messages in the queue that got invalidated because of the session change.
Field pending_session
Type bool
Description

Indicates whether the security context refers to the pending session, i.e. when this join-accept is an answer to a rejoin-request.
Field received_at
Type google.protobuf. Timestamp
Description

Server time when the Network Server received the message.

required
Field locations
Type map of string to Location
Description

End device location metadata, set by the Application Server while handling the message.
Field version_ids
Type EndDeviceVersionIdentifiers
Description

End device version identifiers, set by the Application Server while handling the message.
Field network_ids
Type NetworkIdentifiers
Description

Network identifiers, set by the Network Server that handles the message.
Field attributes
Type map of string to string
Description

Attributes for devices, set by the Application Server while handling the message.

max_pairs: 10

max_len (key): 36

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

max_len (value): 200
Show object example 
{
  "session_key_id": "",
  "f_port": 0,
  "f_cnt": 0,
  "frm_payload": "",
  "decoded_payload": {},
  "decoded_payload_warnings": [],
  "confirmed": false,
  "class_b_c": {},
  "priority": "LOWEST",
  "correlation_ids": [],
  "confirmed_retry": {},
  "locations": {},
  "version_ids": {},
  "network_ids": {},
  "attributes": {},
}

Fields:

Field session_key_id
Type bytes
Description

Join Server issued identifier for the session keys used by this downlink.

max_len: 2048
Field f_port
Type uint32
Description

lte: 255

not_in: [224]
Field f_cnt
Type uint32
Field frm_payload
Type bytes
Description

The frame payload of the downlink message. The payload is encrypted if the skip_payload_crypto field of the EndDevice is true.

max_len: 255
Field decoded_payload
Type google.protobuf. Struct
Description

The decoded frame payload of the downlink message. When scheduling downlink with a message processor configured for the end device (see formatters) or application (see default_formatters), this fields acts as input for the downlink encoder, and the output is set to frm_payload. When reading downlink (listing the queue, downlink message events, etc), this fields acts as output of the downlink decoder, and the input is frm_payload.
Field decoded_payload_warnings
Type repeated string
Description

Warnings generated by the message processor while encoding frm_payload (scheduling downlink) or decoding the frm_payload (reading downlink).
Field confirmed
Type bool
Field class_b_c
Type ApplicationDownlink.ClassBC
Description

Optional gateway and timing information for class B and C. If set, this downlink message will only be transmitted as class B or C downlink. If not set, this downlink message may be transmitted in class A, B and C.
Field priority
Type TxSchedulePriority
Description

Priority for scheduling the downlink message.

defined_only
Field correlation_ids
Type repeated string
Description

max_len: 100
Field confirmed_retry
Type ApplicationDownlink.ConfirmedRetry
Field locations
Type map of string to Location
Description

End device location metadata, set by the Application Server while handling the message.
Field version_ids
Type EndDeviceVersionIdentifiers
Description

End device version identifiers, set by the Application Server while handling the message.
Field network_ids
Type NetworkIdentifiers
Description

Network identifiers, set by the Network Server that handles the message.
Field attributes
Type map of string to string
Description

Attributes for devices, set by the Application Server while handling the message.

max_pairs: 10

max_len (key): 36

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

max_len (value): 200

Message ApplicationDownlink.ClassBC

Show object example 
{
  "gateways": [],
  "absolute_time": "0001-01-01T00:00:00Z",
}

Fields:

Field gateways
Type repeated ClassBCGatewayIdentifiers
Description

Possible gateway identifiers, antenna index, and group index to use for this downlink message. The Network Server selects one of these gateways for downlink, based on connectivity, signal quality, channel utilization and an available slot. If none of the gateways can be selected, the downlink message fails. If empty, a gateway and antenna is selected automatically from the gateways seen in recent uplinks. If group index is set, gateways will be grouped by the index for the Network Server to select one gateway per group.
Field absolute_time
Type google.protobuf. Timestamp
Description

Absolute time when the downlink message should be transmitted. This requires the gateway to have GPS time synchronization. If the time is in the past or if there is a scheduling conflict, the downlink message fails. If null, the time is selected based on slot availability. This is recommended in class B mode.

Message ApplicationDownlink.ConfirmedRetry

Show object example 
{
  "attempt": 0,
  "max_attempts": null,
}

Fields:

Field attempt
Type uint32
Description

The number of attempted confirmed downlink acknowledgements.
Field max_attempts
Type google.protobuf. UInt32Value
Description

The maximum number of confirmed downlink acknowledgement attempts. If null, the Application Server configuration is used instead.

gt: 0

lte: 100

Message ApplicationDownlinkFailed

Show object example 
{
  "downlink": {},
  "error": {},
  "locations": {},
  "version_ids": {},
  "network_ids": {},
  "attributes": {},
}

Fields:

Field downlink
Type ApplicationDownlink
Description

required
Field error
Type ErrorDetails
Description

required
Field locations
Type map of string to Location
Description

End device location metadata, set by the Application Server while handling the message.
Field version_ids
Type EndDeviceVersionIdentifiers
Description

End device version identifiers, set by the Application Server while handling the message.
Field network_ids
Type NetworkIdentifiers
Description

Network identifiers, set by the Network Server that handles the message.
Field attributes
Type map of string to string
Description

Attributes for devices, set by the Application Server while handling the message.

max_pairs: 10

max_len (key): 36

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

max_len (value): 200
Show object example 
{
  "downlinks": [],
  "last_f_cnt_down": 0,
  "session_key_id": "",
  "locations": {},
  "version_ids": {},
  "network_ids": {},
  "attributes": {},
}

Fields:

Field downlinks
Type repeated ApplicationDownlink
Description
Field last_f_cnt_down
Type uint32
Field session_key_id
Type bytes
Description

max_len: 2048
Field locations
Type map of string to Location
Description

End device location metadata, set by the Application Server while handling the message.
Field version_ids
Type EndDeviceVersionIdentifiers
Description

End device version identifiers, set by the Application Server while handling the message.
Field network_ids
Type NetworkIdentifiers
Description

Network identifiers, set by the Network Server that handles the message.
Field attributes
Type map of string to string
Description

Attributes for devices, set by the Application Server while handling the message.

max_pairs: 10

max_len (key): 36

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

max_len (value): 200

Message ApplicationLocation

Show object example 
{
  "service": "",
  "location": {},
  "attributes": {},
}

Fields:

Field service
Type string
Field location
Type Location
Description

required
Field attributes
Type map of string to string
Description

max_pairs: 10

max_len (key): 36

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

max_len (value): 200

Message ApplicationServiceData

Show object example 
{
  "service": "",
  "data": {},
  "locations": {},
  "version_ids": {},
  "network_ids": {},
  "attributes": {},
}

Fields:

Field service
Type string
Field data
Type google.protobuf. Struct
Field locations
Type map of string to Location
Description

End device location metadata, set by the Application Server while handling the message.
Field version_ids
Type EndDeviceVersionIdentifiers
Description

End device version identifiers, set by the Application Server while handling the message.
Field network_ids
Type NetworkIdentifiers
Description

Network identifiers, set by the Network Server that handles the message.
Field attributes
Type map of string to string
Description

Attributes for devices, set by the Application Server while handling the message.

max_pairs: 10

max_len (key): 36

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

max_len (value): 200

Message ApplicationUp

Application uplink message.

Restrictions:
  • Only one of uplink_message, uplink_normalized, join_accept, downlink_ack, downlink_nack, downlink_sent, downlink_failed, downlink_queued, downlink_queue_invalidated, location_solved, service_data can be set.
Show object example 
{
  "end_device_ids": {},
  "correlation_ids": [],
  "received_at": "0001-01-01T00:00:00Z",
  "uplink_message": {},
  "uplink_normalized": {},
  "join_accept": {},
  "downlink_ack": {},
  "downlink_nack": {},
  "downlink_sent": {},
  "downlink_failed": {},
  "downlink_queued": {},
  "downlink_queue_invalidated": {},
  "location_solved": {},
  "service_data": {},
  "simulated": false,
}

Fields:

Field end_device_ids
Type EndDeviceIdentifiers
Description

required
Field correlation_ids
Type repeated string
Description

max_len: 100
Field received_at
Type google.protobuf. Timestamp
Description

Server time when the Application Server received the message.
Field uplink_message
Type ApplicationUplink
Field uplink_normalized
Type ApplicationUplinkNormalized
Field join_accept
Type ApplicationJoinAccept
Field downlink_ack
Type ApplicationDownlink
Field downlink_nack
Type ApplicationDownlink
Field downlink_sent
Type ApplicationDownlink
Field downlink_failed
Type ApplicationDownlinkFailed
Field downlink_queued
Type ApplicationDownlink
Field downlink_queue_invalidated
Type ApplicationInvalidatedDownlinks
Field location_solved
Type ApplicationLocation
Field service_data
Type ApplicationServiceData
Field simulated
Type bool
Description

Signals if the message is coming from the Network Server or is simulated. The Application Server automatically sets this field, and callers must not manually set it.
Show object example 
{
  "session_key_id": "",
  "f_port": 0,
  "f_cnt": 0,
  "frm_payload": "",
  "decoded_payload": {},
  "decoded_payload_warnings": [],
  "normalized_payload": [],
  "normalized_payload_warnings": [],
  "rx_metadata": [],
  "settings": {},
  "received_at": "0001-01-01T00:00:00Z",
  "app_s_key": {},
  "last_a_f_cnt_down": 0,
  "confirmed": false,
  "consumed_airtime": "0s",
  "packet_error_rate": 0,
  "locations": {},
  "version_ids": {},
  "network_ids": {},
  "last_battery_percentage": {},
  "attributes": {},
}

Fields:

Field session_key_id
Type bytes
Description

Join Server issued identifier for the session keys used by this uplink.

max_len: 2048
Field f_port
Type uint32
Description

LoRaWAN FPort of the uplink message.

lte: 255

not_in: [224]
Field f_cnt
Type uint32
Description

LoRaWAN FCntUp of the uplink message.
Field frm_payload
Type bytes
Description

The frame payload of the uplink message. The payload is still encrypted if the skip_payload_crypto field of the EndDevice is true, which is indicated by the presence of the app_s_key field.
Field decoded_payload
Type google.protobuf. Struct
Description

The decoded frame payload of the uplink message. This field is set by the message processor that is configured for the end device (see formatters) or application (see default_formatters).
Field decoded_payload_warnings
Type repeated string
Description

Warnings generated by the message processor while decoding the frm_payload.
Field normalized_payload
Type repeated google.protobuf. Struct
Description

The normalized frame payload of the uplink message. This field is set by the message processor that is configured for the end device (see formatters) or application (see default_formatters). If the message processor is a custom script, there is no uplink normalizer script and the decoded output is valid normalized payload, this field contains the decoded payload.
Field normalized_payload_warnings
Type repeated string
Description

Warnings generated by the message processor while normalizing the decoded payload.
Field rx_metadata
Type repeated RxMetadata
Description

A list of metadata for each antenna of each gateway that received this message.
Field settings
Type TxSettings
Description

Transmission settings used by the end device.

required
Field received_at
Type google.protobuf. Timestamp
Description

Server time when the Network Server received the message.
Field app_s_key
Type KeyEnvelope
Description

The AppSKey of the current session. This field is only present if the skip_payload_crypto field of the EndDevice is true. Can be used to decrypt uplink payloads and encrypt downlink payloads.
Field last_a_f_cnt_down
Type uint32
Description

The last AFCntDown of the current session. This field is only present if the skip_payload_crypto field of the EndDevice is true. Can be used with app_s_key to encrypt downlink payloads.
Field confirmed
Type bool
Description

Indicates whether the end device used confirmed data uplink.
Field consumed_airtime
Type google.protobuf. Duration
Description

Consumed airtime for the transmission of the uplink message. Calculated by Network Server using the raw payload size and the transmission settings.
Field packet_error_rate
Type float
Description

Packet error rate of the recent uplinks in the current session. Calculated by the Network Server. The value is defined in the [0, 1] interval.
Field locations
Type map of string to Location
Description

End device location metadata, set by the Application Server while handling the message.
Field version_ids
Type EndDeviceVersionIdentifiers
Description

End device version identifiers, set by the Application Server while handling the message.
Field network_ids
Type NetworkIdentifiers
Description

Network identifiers, set by the Network Server that handles the message.
Field last_battery_percentage
Type LastBatteryPercentage
Description

Last battery percentage of the end device. Received via the DevStatus MAC command at last_dev_status_received_at or earlier. Set by the Network Server while handling the message.
Field attributes
Type map of string to string
Description

Attributes for devices, set by the Application Server while handling the message.

max_pairs: 10

max_len (key): 36

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

max_len (value): 200

Message ApplicationUplinkNormalized

Show object example 
{
  "session_key_id": "",
  "f_port": 0,
  "f_cnt": 0,
  "frm_payload": "",
  "normalized_payload": {},
  "normalized_payload_warnings": [],
  "rx_metadata": [],
  "settings": {},
  "received_at": "0001-01-01T00:00:00Z",
  "confirmed": false,
  "consumed_airtime": "0s",
  "locations": {},
  "version_ids": {},
  "network_ids": {},
  "attributes": {},
}

Fields:

Field session_key_id
Type bytes
Description

Join Server issued identifier for the session keys used by this uplink.

max_len: 2048
Field f_port
Type uint32
Description

LoRaWAN FPort of the uplink message.

gte: 1

lte: 255

not_in: [224]
Field f_cnt
Type uint32
Description

LoRaWAN FCntUp of the uplink message.
Field frm_payload
Type bytes
Description

The frame payload of the uplink message. This field is always decrypted with AppSKey.
Field normalized_payload
Type google.protobuf. Struct
Description

The normalized frame payload of the uplink message. This field is set for each item in normalized_payload in the corresponding ApplicationUplink message.

required
Field normalized_payload_warnings
Type repeated string
Description

This field is set to normalized_payload_warnings in the corresponding ApplicationUplink message.
Field rx_metadata
Type repeated RxMetadata
Description

A list of metadata for each antenna of each gateway that received this message.
Field settings
Type TxSettings
Description

Transmission settings used by the end device.

required
Field received_at
Type google.protobuf. Timestamp
Description

Server time when the Network Server received the message.

required
Field confirmed
Type bool
Description

Indicates whether the end device used confirmed data uplink.
Field consumed_airtime
Type google.protobuf. Duration
Description

Consumed airtime for the transmission of the uplink message. Calculated by Network Server using the raw payload size and the transmission settings.
Field locations
Type map of string to Location
Description

End device location metadata, set by the Application Server while handling the message.
Field version_ids
Type EndDeviceVersionIdentifiers
Description

End device version identifiers, set by the Application Server while handling the message.
Field network_ids
Type NetworkIdentifiers
Description

Network identifiers, set by the Network Server that handles the message.
Field attributes
Type map of string to string
Description

Attributes for devices, set by the Application Server while handling the message.

max_pairs: 10

max_len (key): 36

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

max_len (value): 200

Message ClassBCGatewayIdentifiers

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

Fields:

Field gateway_ids
Type GatewayIdentifiers
Description

required
Field antenna_index
Type uint32
Field group_index
Type uint32

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 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 EndDeviceVersionIdentifiers

Identifies an end device model with version information.

Show object example 
{
  "brand_id": "",
  "model_id": "",
  "hardware_version": "",
  "firmware_version": "",
  "band_id": "",
}

Fields:

Field brand_id
Type string
Description

ignore_empty

max_len: 36

pattern: ^[a-z0-9](?:[-]?[a-z0-9]){2,}$
Field model_id
Type string
Description

ignore_empty

max_len: 36

pattern: ^[a-z0-9](?:[-]?[a-z0-9]){2,}$
Field hardware_version
Type string
Description

max_len: 32
Field firmware_version
Type string
Description

max_len: 32
Field band_id
Type string
Description

max_len: 32

Message ErrorDetails

Error details that are communicated over gRPC (and HTTP) APIs. The messages (for translation) are stored as “error::”.

Show object example 
{
  "namespace": "",
  "name": "",
  "message_format": "",
  "attributes": {},
  "correlation_id": "",
  "cause": {},
  "code": 0,
  "details": [],
}

Fields:

Field namespace
Type string
Description

Namespace of the error (typically the package name in The Things Stack).
Field name
Type string
Description

Name of the error.
Field message_format
Type string
Description

The default (fallback) message format that should be used for the error. This is also used if the client does not have a translation for the error.
Field attributes
Type google.protobuf. Struct
Description

Attributes that should be filled into the message format. Any extra attributes can be displayed as error details.
Field correlation_id
Type string
Description

The correlation ID of the error can be used to correlate the error to stack traces the network may (or may not) store about recent errors.
Field cause
Type ErrorDetails
Description

The error that caused this error.
Field code
Type uint32
Description

The status code of the error.
Field details
Type repeated google.protobuf. Any
Description

The details of the error.

Message FSKDataRate

Show object example 
{
  "bit_rate": 0,
}

Fields:

Field bit_rate
Type uint32
Description

Bit rate (bps).

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 GatewayAntennaIdentifiers

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

Fields:

Field gateway_ids
Type GatewayIdentifiers
Description

required
Field antenna_index
Type uint32

Message GetStoredApplicationUpCountRequest

Show object example 
{
  "application_ids": {},
  "end_device_ids": {},
  "type": "",
  "after": "0001-01-01T00:00:00Z",
  "before": "0001-01-01T00:00:00Z",
  "f_port": null,
  "last": "0s",
}

Fields:

Field application_ids
Type ApplicationIdentifiers
Description

Count upstream messages from all end devices of an application. Cannot be used in conjunction with end_device_ids.
Field end_device_ids
Type EndDeviceIdentifiers
Description

Count upstream messages from a single end device. Cannot be used in conjunction with application_ids.
Field type
Type string
Description

Count upstream messages of a specific type. If not set, then all upstream messages are returned.

in: [ uplink_message join_accept downlink_ack downlink_nack downlink_sent downlink_failed downlink_queued downlink_queue_invalidated location_solved service_data]
Field after
Type google.protobuf. Timestamp
Description

Count upstream messages after this timestamp only. Cannot be used in conjunction with last.
Field before
Type google.protobuf. Timestamp
Description

Count upstream messages before this timestamp only. Cannot be used in conjunction with last.
Field f_port
Type google.protobuf. UInt32Value
Description

Count uplinks on a specific FPort only.
Field last
Type google.protobuf. Duration
Description

Count upstream messages that have arrived in the last minutes or hours. Cannot be used in conjunction with after and before.

Message KeyEnvelope

Show object example 
{
  "key": "",
  "kek_label": "",
  "encrypted_key": "",
}

Fields:

Field key
Type bytes
Description

The unencrypted AES key.

ignore_empty

len: 16
Field kek_label
Type string
Description

The label of the RFC 3394 key-encryption-key (KEK) that was used to encrypt the key.

max_len: 2048
Field encrypted_key
Type bytes
Description

max_len: 1024

Message LastBatteryPercentage

Show object example 
{
  "f_cnt": 0,
  "value": null,
  "received_at": "0001-01-01T00:00:00Z",
}

Fields:

Field f_cnt
Type uint32
Description

Frame counter value of last uplink containing DevStatusAns.
Field value
Type google.protobuf. FloatValue
Description

The battery percentage of the end device. The value is defined in the [0, 100] interval.

gte: 0

lte: 100
Field received_at
Type google.protobuf. Timestamp
Description

Time when last DevStatus MAC command was received.

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 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 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 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 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 NetworkIdentifiers

Identifies a Network Server.

Show object example 
{
  "net_id": "",
  "ns_id": "",
  "tenant_id": "",
  "cluster_id": "",
  "cluster_address": "",
  "tenant_address": "",
}

Fields:

Field net_id
Type bytes
Description

LoRa Alliance NetID.

ignore_empty

len: 3
Field ns_id
Type bytes
Description

LoRaWAN NSID (EUI-64) that uniquely identifies the Network Server instance.

ignore_empty

len: 8
Field tenant_id
Type string
Description

Optional tenant identifier for multi-tenant deployments.

max_len: 36

pattern: ^[a-z0-9](?:[-]?[a-z0-9]){2,}$|^$
Field cluster_id
Type string
Description

Cluster identifier of the Network Server.

max_len: 64
Field cluster_address
Type string
Description

Cluster address of the Network Server.

max_len: 256
Field tenant_address
Type string
Description

Optional tenant address for multi-tenant deployments.

max_len: 256

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 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 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 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 RelayWORChannel

Name Value Description
RELAY_WOR_CHANNEL_DEFAULT 0
RELAY_WOR_CHANNEL_SECONDARY 1

Enum TxSchedulePriority

Name Value Description
LOWEST 0
LOW 1
BELOW_NORMAL 2
NORMAL 3
ABOVE_NORMAL 4
HIGH 5
HIGHEST 6
← Packet Broker APIs Tenant APIs →