Protocol Documentation

Table of Contents

Top

api/application.proto

Application

FieldTypeLabelDescription
idstringApplication ID (UUID). Note: on create this will be automatically generated.
namestringApplication name.
descriptionstringApplication description.
tenant_idstringTenant ID (UUID).
tagsApplication.TagsEntryrepeatedTags (user defined). These tags can be used to add additional information to the application. These tags are exposed in all the integration events of devices under this application.

Application.TagsEntry

FieldTypeLabelDescription
keystring
valuestring

ApplicationListItem

FieldTypeLabelDescription
idstringApplication ID (UUID).
created_atgoogle.protobuf.TimestampCreated at timestamp.
updated_atgoogle.protobuf.TimestampLast update timestamp.
namestringApplication name.
descriptionstringApplication description.

AwsSnsIntegration

FieldTypeLabelDescription
application_idstringApplication ID (UUID).
encodingEncodingEncoding.
regionstringAWS region.
access_key_idstringAWS Access Key ID.
secret_access_keystringAWS Secret Access Key.
topic_arnstringTopic ARN.

AzureServiceBusIntegration

FieldTypeLabelDescription
application_idstringApplication ID (UUID).
encodingEncodingEncoding.
connection_stringstringConnection string.
publish_namestringPublish name. This is the name of the topic or queue.

CreateApplicationRequest

FieldTypeLabelDescription
applicationApplicationApplication object to create.

CreateApplicationResponse

FieldTypeLabelDescription
idstringApplication ID (UUID).

CreateAwsSnsIntegrationRequest

FieldTypeLabelDescription
integrationAwsSnsIntegrationIntegration object to create.

CreateAzureServiceBusIntegrationRequest

FieldTypeLabelDescription
integrationAzureServiceBusIntegrationIntegration object to create.

CreateGcpPubSubIntegrationRequest

FieldTypeLabelDescription
integrationGcpPubSubIntegrationIntegration object to create.

CreateHttpIntegrationRequest

FieldTypeLabelDescription
integrationHttpIntegrationIntegration object to create.

CreateIftttIntegrationRequest

FieldTypeLabelDescription
integrationIftttIntegrationIntegration object.

CreateInfluxDbIntegrationRequest

FieldTypeLabelDescription
integrationInfluxDbIntegrationIntegration object to create.

CreateLoraCloudIntegrationRequest

FieldTypeLabelDescription
integrationLoraCloudIntegrationIntegration object to create.

CreateMyDevicesIntegrationRequest

FieldTypeLabelDescription
integrationMyDevicesIntegrationIntegration object to create.

CreatePilotThingsIntegrationRequest

FieldTypeLabelDescription
integrationPilotThingsIntegrationIntegration object to create.

CreateThingsBoardIntegrationRequest

FieldTypeLabelDescription
integrationThingsBoardIntegrationIntegration object to create.

DeleteApplicationRequest

FieldTypeLabelDescription
idstringApplication ID (UUID).

DeleteAwsSnsIntegrationRequest

FieldTypeLabelDescription
application_idstringApplication ID (UUID).

DeleteAzureServiceBusIntegrationRequest

FieldTypeLabelDescription
application_idstringApplication ID (UUID).

DeleteGcpPubSubIntegrationRequest

FieldTypeLabelDescription
application_idstringApplication ID (UUID).

DeleteHttpIntegrationRequest

FieldTypeLabelDescription
application_idstringApplication ID (UUID).

DeleteIftttIntegrationRequest

FieldTypeLabelDescription
application_idstringApplication ID (UUID).

DeleteInfluxDbIntegrationRequest

FieldTypeLabelDescription
application_idstringApplication ID (UUID).

DeleteLoraCloudIntegrationRequest

FieldTypeLabelDescription
application_idstringApplication ID (UUID).

DeleteMyDevicesIntegrationRequest

FieldTypeLabelDescription
application_idstringApplication ID (UUID).

DeletePilotThingsIntegrationRequest

FieldTypeLabelDescription
application_idstringApplication ID (UUID).

DeleteThingsBoardIntegrationRequest

FieldTypeLabelDescription
application_idstringApplication ID (UUID).

GcpPubSubIntegration

FieldTypeLabelDescription
application_idstringApplication ID (UUID).
encodingEncodingEncoding.
credentials_filestringCredentials file. This IAM service-account credentials file (JSON) must have the following Pub/Sub roles: * Pub/Sub Publisher
project_idstringProject ID.
topic_namestringTopic name. This is the name of the Pub/Sub topic.

GenerateMqttIntegrationClientCertificateRequest

FieldTypeLabelDescription
application_idstringApplication ID (UUID).

GenerateMqttIntegrationClientCertificateResponse

FieldTypeLabelDescription
tls_certstringTLS certificate.
tls_keystringTLS key.
ca_certstringCA certificate.
expires_atgoogle.protobuf.TimestampExpires at defines the expiration date of the certificate.

GetApplicationRequest

FieldTypeLabelDescription
idstringApplication ID (UUID).

GetApplicationResponse

FieldTypeLabelDescription
applicationApplicationApplication object.
created_atgoogle.protobuf.TimestampCreated at timestamp.
updated_atgoogle.protobuf.TimestampLast update timestamp.
measurement_keysstringrepeatedMeasurement keys. This contains the measurement keys from all the device-profiles that are used by the devices under this application.

GetAwsSnsIntegrationRequest

FieldTypeLabelDescription
application_idstringApplication ID (UUID).

GetAwsSnsIntegrationResponse

FieldTypeLabelDescription
integrationAwsSnsIntegrationIntegration object.

GetAzureServiceBusIntegrationRequest

FieldTypeLabelDescription
application_idstringApplication ID (UUID).

GetAzureServiceBusIntegrationResponse

FieldTypeLabelDescription
integrationAzureServiceBusIntegrationIntegration object.

GetGcpPubSubIntegrationRequest

FieldTypeLabelDescription
application_idstringApplication ID (UUID).

GetGcpPubSubIntegrationResponse

FieldTypeLabelDescription
integrationGcpPubSubIntegrationIntegration object.

GetHttpIntegrationRequest

FieldTypeLabelDescription
application_idstringApplication ID (UUID).

GetHttpIntegrationResponse

FieldTypeLabelDescription
integrationHttpIntegrationIntegration object.

GetIftttIntegrationRequest

FieldTypeLabelDescription
application_idstringApplication ID (UUID).

GetIftttIntegrationResponse

FieldTypeLabelDescription
integrationIftttIntegrationIntegration object.

GetInfluxDbIntegrationRequest

FieldTypeLabelDescription
application_idstringApplication ID (UUID).

GetInfluxDbIntegrationResponse

FieldTypeLabelDescription
integrationInfluxDbIntegrationIntegration object.

GetLoraCloudIntegrationRequest

FieldTypeLabelDescription
application_idstringApplication ID (UUID).

GetLoraCloudIntegrationResponse

FieldTypeLabelDescription
integrationLoraCloudIntegrationIntegration object.

GetMyDevicesIntegrationRequest

FieldTypeLabelDescription
application_idstringApplication ID (UUID).

GetMyDevicesIntegrationResponse

FieldTypeLabelDescription
integrationMyDevicesIntegrationIntegration object.

GetPilotThingsIntegrationRequest

FieldTypeLabelDescription
application_idstringApplication ID (UUID).

GetPilotThingsIntegrationResponse

FieldTypeLabelDescription
integrationPilotThingsIntegrationIntegration object.

GetThingsBoardIntegrationRequest

FieldTypeLabelDescription
application_idstringApplication ID (UUID).

GetThingsBoardIntegrationResponse

FieldTypeLabelDescription
integrationThingsBoardIntegrationIntegration object.

HttpIntegration

FieldTypeLabelDescription
application_idstringApplication ID (UUID).
headersHttpIntegration.HeadersEntryrepeatedHTTP headers to set when making requests.
encodingEncodingPayload encoding.
event_endpoint_urlstringEvent endpoint URL. The HTTP integration will POST all events to this enpoint. The request will contain a query parameters "event" containing the type of the event.

HttpIntegration.HeadersEntry

FieldTypeLabelDescription
keystring
valuestring

IftttIntegration

FieldTypeLabelDescription
application_idstringApplication ID (UUID).
keystringKey. This key can be obtained from the IFTTT Webhooks documentation page.
uplink_valuesstringrepeatedValues. Up to 2 values can be forwarded to IFTTT. These values must map to the decoded payload keys. For example: { "batteryLevel": 75.3, "buttons": [{"pressed": false}, {"pressed": true}] } You would specify the following fields: uplink_values = ["batteryLevel", "buttons_0_pressed"]

Notes: The first value is always used for the DevEUI. Ignored if arbitrary_json is set to true. | | arbitrary_json | bool | | Arbitrary JSON. If set to true, ChirpStack events will be sent as-is as arbitrary JSON payload. If set to false (default), the 3 JSON values format will be used. | | event_prefix | string | | Event prefix. If set, the event name will be PREFIX_EVENT. For example if event_prefix is set to weatherstation, and uplink event will be sent as weatherstation_up to the IFTTT webhook. Note: Only characters in the A-Z, a-z and 0-9 range are allowed. |

InfluxDbIntegration

FieldTypeLabelDescription
application_idstringApplication ID (UUID).
endpointstringInfluxDb API write endpoint (e.g. http://localhost:8086/write).
dbstringInfluxDb database name. (InfluxDb v1)
usernamestringInfluxDb username. (InfluxDb v1)
passwordstringInfluxDb password. (InfluxDb v1)
retention_policy_namestringInfluxDb retention policy name. (InfluxDb v1)
precisionInfluxDbPrecisionInfluxDb timestamp precision (InfluxDb v1).
versionInfluxDbVersionInfluxDb version.
tokenstringToken. (InfluxDb v2)
organizationstringOrganization. (InfluxDb v2)
bucketstringBucket. (InfluxDb v2)

IntegrationListItem

FieldTypeLabelDescription
kindIntegrationKindIntegration kind.

ListApplicationsRequest

FieldTypeLabelDescription
limituint32Max number of applications to return in the result-set.
offsetuint32Offset in the result-set (for pagination).
searchstringIf set, the given string will be used to search on name (optional).
tenant_idstringTenant ID to list the applications for.

ListApplicationsResponse

FieldTypeLabelDescription
total_countuint32Total number of applications.
resultApplicationListItemrepeatedResult-set.

ListIntegrationsRequest

FieldTypeLabelDescription
application_idstringApplication ID (UUID).

ListIntegrationsResponse

FieldTypeLabelDescription
total_countuint32Total number of integrations available within the result-set.
resultIntegrationListItemrepeatedIntegrations within result-set.

LoraCloudIntegration

FieldTypeLabelDescription
application_idstringApplication ID (UUID).
modem_geolocation_servicesLoraCloudModemGeolocationServicesModem & Geolocation Services configuration.

LoraCloudModemGeolocationServices

FieldTypeLabelDescription
tokenstringAPI token.
modem_enabledboolDevice implements Modem / Modem-E stack.
forward_f_portsuint32repeatedForward FPorts. Forward uplink messages matching the given FPorts to the MGS.
gnss_use_rx_timeboolUse rx time for GNSS resolving. In case this is set to true, the MGS resolver will use the RX time of the network instead of the timestamp included in the LR1110 payload.
gnss_use_gateway_locationboolUse gateway location for GNSS resolving. In the case this is set to true, ChirpStack will provide the location of one of the gateways to the MGS resolver to aid the resolving process. Disable this in case the gateway location is not accurate / incorrectly configured as an incorrect location will cause the resolver to return an error.
parse_tlvboolParse TLV records. If enabled, stream records (expected in TLV format) are scanned for GNSS data (0x06 or 0x07). If found, ChirpStack will make an additional geolocation call to the MGS API for resolving the location of the detected payload.
geolocation_buffer_ttluint32Geolocation buffer TTL (in seconds). If > 0, uplink RX meta-data will be stored in a buffer so that the meta-data of multiple uplinks can be used for geolocation.
geolocation_min_buffer_sizeuint32Geolocation minimum buffer size. If > 0, geolocation will only be performed when the buffer has at least the given size.
geolocation_tdoaboolTDOA based geolocation is enabled.
geolocation_rssiboolRSSI based geolocation is enabled.
geolocation_gnssboolGNSS based geolocation is enabled (LR1110).
geolocation_gnss_payload_fieldstringGNSS payload field. This holds the name of the field in the decoded payload object which contains the GNSS payload bytes (as HEX string).
geolocation_gnss_use_rx_timeboolGNSS use RX time. In case this is set to true, the resolver will use the RX time of the network instead of the timestamp included in the LR1110 payload.
geolocation_wifiboolWifi based geolocation is enabled.
geolocation_wifi_payload_fieldstringWifi payload field. This holds the name of the field in the decoded payload object which contains an array of objects with the following fields: * macAddress - e.g. 01:23:45:67:89:ab * signalStrength - e.g. -51 (optional)

MyDevicesIntegration

FieldTypeLabelDescription
application_idstringApplication ID (UUID).
endpointstringmyDevices API endpoint.

PilotThingsIntegration

FieldTypeLabelDescription
application_idstringApplication ID (UUID).
serverstringServer URL.
tokenstringAuthentication token.

ThingsBoardIntegration

FieldTypeLabelDescription
application_idstringApplication ID (UUID).
serverstringThingsBoard server endpoint, e.g. https://example.com

UpdateApplicationRequest

FieldTypeLabelDescription
applicationApplicationApplication object.

UpdateAwsSnsIntegrationRequest

FieldTypeLabelDescription
integrationAwsSnsIntegrationIntegration object to update.

UpdateAzureServiceBusIntegrationRequest

FieldTypeLabelDescription
integrationAzureServiceBusIntegrationIntegration object to create.

UpdateGcpPubSubIntegrationRequest

FieldTypeLabelDescription
integrationGcpPubSubIntegrationIntegration object to update.

UpdateHttpIntegrationRequest

FieldTypeLabelDescription
integrationHttpIntegrationIntegration object to update.

UpdateIftttIntegrationRequest

FieldTypeLabelDescription
integrationIftttIntegrationIntegration object to update.

UpdateInfluxDbIntegrationRequest

FieldTypeLabelDescription
integrationInfluxDbIntegrationIntegration object to update.

UpdateLoraCloudIntegrationRequest

FieldTypeLabelDescription
integrationLoraCloudIntegrationIntegration object to update.

UpdateMyDevicesIntegrationRequest

FieldTypeLabelDescription
integrationMyDevicesIntegrationIntegration object to update.

UpdatePilotThingsIntegrationRequest

FieldTypeLabelDescription
integrationPilotThingsIntegrationIntegration object to update.

UpdateThingsBoardIntegrationRequest

FieldTypeLabelDescription
integrationThingsBoardIntegrationIntegration object to update.

Encoding

NameNumberDescription
JSON0
PROTOBUF1

InfluxDbPrecision

NameNumberDescription
NS0
U1
MS2
S3
M4
H5

InfluxDbVersion

NameNumberDescription
INFLUXDB_10
INFLUXDB_21

IntegrationKind

NameNumberDescription
HTTP0
INFLUX_DB1
THINGS_BOARD2
MY_DEVICES3
LORA_CLOUD4
GCP_PUB_SUB5
AWS_SNS6
AZURE_SERVICE_BUS7
PILOT_THINGS8
MQTT_GLOBAL9
IFTTT10

ApplicationService

ApplicationService is the service providing API methods for managing applications.

Method NameRequest TypeResponse TypeDescription
CreateCreateApplicationRequestCreateApplicationResponseCreate creates the given application.
GetGetApplicationRequestGetApplicationResponseGet the application for the given ID.
UpdateUpdateApplicationRequest.google.protobuf.EmptyUpdate updates the given application.
DeleteDeleteApplicationRequest.google.protobuf.EmptyDelete the application for the given ID.
ListListApplicationsRequestListApplicationsResponseGet the list of applications.
ListIntegrationsListIntegrationsRequestListIntegrationsResponseList all configured integrations.
CreateHttpIntegrationCreateHttpIntegrationRequest.google.protobuf.EmptyCreate HTTP integration.
GetHttpIntegrationGetHttpIntegrationRequestGetHttpIntegrationResponseGet the configured HTTP integration.
UpdateHttpIntegrationUpdateHttpIntegrationRequest.google.protobuf.EmptyUpdate the HTTP integration.
DeleteHttpIntegrationDeleteHttpIntegrationRequest.google.protobuf.EmptyDelete the HTTP integration.
CreateInfluxDbIntegrationCreateInfluxDbIntegrationRequest.google.protobuf.EmptyCreate InfluxDb integration.
GetInfluxDbIntegrationGetInfluxDbIntegrationRequestGetInfluxDbIntegrationResponseGet InfluxDb integration.
UpdateInfluxDbIntegrationUpdateInfluxDbIntegrationRequest.google.protobuf.EmptyUpdate InfluxDb integration.
DeleteInfluxDbIntegrationDeleteInfluxDbIntegrationRequest.google.protobuf.EmptyDelete InfluxDb integration.
CreateThingsBoardIntegrationCreateThingsBoardIntegrationRequest.google.protobuf.EmptyCreate ThingsBoard integration.
GetThingsBoardIntegrationGetThingsBoardIntegrationRequestGetThingsBoardIntegrationResponseGet ThingsBoard integration.
UpdateThingsBoardIntegrationUpdateThingsBoardIntegrationRequest.google.protobuf.EmptyUpdate ThingsBoard integration.
DeleteThingsBoardIntegrationDeleteThingsBoardIntegrationRequest.google.protobuf.EmptyDelete ThingsBoard integration.
CreateMyDevicesIntegrationCreateMyDevicesIntegrationRequest.google.protobuf.EmptyCreate myDevices integration.
GetMyDevicesIntegrationGetMyDevicesIntegrationRequestGetMyDevicesIntegrationResponseGet myDevices integration.
UpdateMyDevicesIntegrationUpdateMyDevicesIntegrationRequest.google.protobuf.EmptyUpdate myDevices integration.
DeleteMyDevicesIntegrationDeleteMyDevicesIntegrationRequest.google.protobuf.EmptyDelete myDevices integration.
CreateLoraCloudIntegrationCreateLoraCloudIntegrationRequest.google.protobuf.EmptyCreate LoRaCloud integration.
GetLoraCloudIntegrationGetLoraCloudIntegrationRequestGetLoraCloudIntegrationResponseGet LoRaCloud integration.
UpdateLoraCloudIntegrationUpdateLoraCloudIntegrationRequest.google.protobuf.EmptyUpdate LoRaCloud integration.
DeleteLoraCloudIntegrationDeleteLoraCloudIntegrationRequest.google.protobuf.EmptyDelete LoRaCloud integration.
CreateGcpPubSubIntegrationCreateGcpPubSubIntegrationRequest.google.protobuf.EmptyCreate GCP Pub/Sub integration.
GetGcpPubSubIntegrationGetGcpPubSubIntegrationRequestGetGcpPubSubIntegrationResponseGet GCP Pub/Sub integration.
UpdateGcpPubSubIntegrationUpdateGcpPubSubIntegrationRequest.google.protobuf.EmptyUpdate GCP Pub/Sub integration.
DeleteGcpPubSubIntegrationDeleteGcpPubSubIntegrationRequest.google.protobuf.EmptyDelete GCP Pub/Sub integration.
CreateAwsSnsIntegrationCreateAwsSnsIntegrationRequest.google.protobuf.EmptyCreate AWS SNS integration.
GetAwsSnsIntegrationGetAwsSnsIntegrationRequestGetAwsSnsIntegrationResponseGet AWS SNS integration.
UpdateAwsSnsIntegrationUpdateAwsSnsIntegrationRequest.google.protobuf.EmptyUpdate AWS SNS integration.
DeleteAwsSnsIntegrationDeleteAwsSnsIntegrationRequest.google.protobuf.EmptyDelete AWS SNS integration.
CreateAzureServiceBusIntegrationCreateAzureServiceBusIntegrationRequest.google.protobuf.EmptyCreate Azure Service-Bus integration.
GetAzureServiceBusIntegrationGetAzureServiceBusIntegrationRequestGetAzureServiceBusIntegrationResponseGet Azure Service-Bus integration.
UpdateAzureServiceBusIntegrationUpdateAzureServiceBusIntegrationRequest.google.protobuf.EmptyUpdate Azure Service-Bus integration.
DeleteAzureServiceBusIntegrationDeleteAzureServiceBusIntegrationRequest.google.protobuf.EmptyDelete Azure Service-Bus integration.
CreatePilotThingsIntegrationCreatePilotThingsIntegrationRequest.google.protobuf.EmptyCreate Pilot Things integration.
GetPilotThingsIntegrationGetPilotThingsIntegrationRequestGetPilotThingsIntegrationResponseGet Pilot Things integration.
UpdatePilotThingsIntegrationUpdatePilotThingsIntegrationRequest.google.protobuf.EmptyUpdate Pilot Things integration.
DeletePilotThingsIntegrationDeletePilotThingsIntegrationRequest.google.protobuf.EmptyDelete Pilot Things integration.
CreateIftttIntegrationCreateIftttIntegrationRequest.google.protobuf.EmptyCreate IFTTT integration.
GetIftttIntegrationGetIftttIntegrationRequestGetIftttIntegrationResponseGet IFTTT integration.
UpdateIftttIntegrationUpdateIftttIntegrationRequest.google.protobuf.EmptyUpdate IFTTT integration.
DeleteIftttIntegrationDeleteIftttIntegrationRequest.google.protobuf.EmptyDelete IFTTT integration.
GenerateMqttIntegrationClientCertificateGenerateMqttIntegrationClientCertificateRequestGenerateMqttIntegrationClientCertificateResponseGenerates application ID specific client-certificate.

Top

api/device.proto

ActivateDeviceRequest

FieldTypeLabelDescription
device_activationDeviceActivationDevice activation object.

CreateDeviceKeysRequest

FieldTypeLabelDescription
device_keysDeviceKeysDevice-keys object.

CreateDeviceRequest

FieldTypeLabelDescription
deviceDeviceDevice object.

DeactivateDeviceRequest

FieldTypeLabelDescription
dev_euistringDevEUI (EUI64).

DeleteDeviceKeysRequest

FieldTypeLabelDescription
dev_euistringDevEUI (EUI64).

DeleteDeviceRequest

FieldTypeLabelDescription
dev_euistringDevEUI (EUI64).

Device

FieldTypeLabelDescription
dev_euistringDevEUI (EUI64).
namestringName.
descriptionstringDescription.
application_idstringApplication ID (UUID).
device_profile_idstringDevice-profile ID (UUID).
skip_fcnt_checkboolSkip frame-counter checks (this is insecure, but could be helpful for debugging).
is_disabledboolDevice is disabled.
variablesDevice.VariablesEntryrepeatedVariables (user defined). These variables can be used together with integrations to store tokens / secrets that must be configured per device. These variables are not exposed in the event payloads.
tagsDevice.TagsEntryrepeatedTags (user defined). These tags can be used to add additional information to the device. These tags are exposed in all the integration events.
join_euistringJoinEUI (optional, EUI64). This field will be automatically set / updated on OTAA. However, in some cases it must be pre-configured. For example to allow OTAA using a Relay. In this case the Relay needs to know the JoinEUI + DevEUI combinations of the devices for which it needs to forward uplinks.

Device.TagsEntry

FieldTypeLabelDescription
keystring
valuestring

Device.VariablesEntry

FieldTypeLabelDescription
keystring
valuestring

DeviceActivation

FieldTypeLabelDescription
dev_euistringDevice EUI (EUI64).
dev_addrstringDevice address (HEX encoded).
app_s_keystringApplication session key (HEX encoded).
nwk_s_enc_keystringNetwork session encryption key (HEX encoded).
s_nwk_s_int_keystringServing network session integrity key (HEX encoded).
f_nwk_s_int_keystringForwarding network session integrity key (HEX encoded).
f_cnt_upuint32Uplink frame-counter.
n_f_cnt_downuint32Downlink network frame-counter.
a_f_cnt_downuint32Downlink application frame-counter.

DeviceKeys

FieldTypeLabelDescription
dev_euistringDevEUI (EUI64).
nwk_keystringNetwork root key (128 bit). Note: For LoRaWAN 1.0.x, use this field for the LoRaWAN 1.0.x 'AppKey`!
app_keystringApplication root key (128 bit). Note: This field only needs to be set for LoRaWAN 1.1.x devices!

DeviceListItem

FieldTypeLabelDescription
dev_euistringDevEUI (EUI64).
created_atgoogle.protobuf.TimestampCreated at timestamp.
updated_atgoogle.protobuf.TimestampLast update timestamp.
last_seen_atgoogle.protobuf.TimestampLast seen at timestamp.
namestringName.
descriptionstringDescription.
device_profile_idstringDevice-profile ID (UUID).
device_profile_namestringDevice-profile name.
device_statusDeviceStatusDevice status.

DeviceQueueItem

FieldTypeLabelDescription
idstringID (UUID). This is automatically generated on enqueue.
dev_euistringDevice EUI (EUI64).
confirmedboolConfirmed.
f_portuint32FPort (must be > 0).
databytesData. Or use the json_object field when a codec has been configured.
objectgoogle.protobuf.StructOnly use this when a codec has been configured that can encode this object to bytes.
is_pendingboolIs pending. This is set by ChirpStack to true when the downlink is pending (e.g. it has been sent, but a confirmation is still pending).
f_cnt_downuint32Downlink frame-counter. Do not set this for plain-text data payloads. It will be automatically set by ChirpStack when the payload has been sent as downlink.
is_encryptedboolIs encrypted. This must be set to true if the end-application has already encrypted the data payload. In this case, the f_cnt_down field must be set to the corresponding frame-counter which has been used during the encryption.

DeviceState

FieldTypeLabelDescription
namestringName.
valuestringValue.

DeviceStatus

FieldTypeLabelDescription
marginint32The device margin status -32..32: The demodulation SNR ration in dB
external_power_sourceboolDevice is connected to an external power source.
battery_levelfloatDevice battery level as a percentage. -1 when the battery level is not available.

EnqueueDeviceQueueItemRequest

FieldTypeLabelDescription
queue_itemDeviceQueueItem

EnqueueDeviceQueueItemResponse

FieldTypeLabelDescription
idstringID (UUID).

FlushDevNoncesRequest

FieldTypeLabelDescription
dev_euistringDevice EUI (EUI64).

FlushDeviceQueueRequest

FieldTypeLabelDescription
dev_euistringDevice EUI (EUI64).

GetDeviceActivationRequest

FieldTypeLabelDescription
dev_euistringDevEUI (EUI64).

GetDeviceActivationResponse

FieldTypeLabelDescription
device_activationDeviceActivationDevice activation object.

GetDeviceKeysRequest

FieldTypeLabelDescription
dev_euistringDevEUI (EUI64).

GetDeviceKeysResponse

FieldTypeLabelDescription
device_keysDeviceKeysDevice-keys object.
created_atgoogle.protobuf.TimestampCreated at timestamp.
updated_atgoogle.protobuf.TimestampLast update timestamp.

GetDeviceLinkMetricsRequest

FieldTypeLabelDescription
dev_euistringDevEUI (EUI64).
startgoogle.protobuf.TimestampInterval start timestamp.
endgoogle.protobuf.TimestampInterval end timestamp.
aggregationcommon.AggregationAggregation.

GetDeviceLinkMetricsResponse

FieldTypeLabelDescription
rx_packetscommon.MetricPackets received from the device.
gw_rssicommon.MetricRSSI (as reported by the gateway(s)).
gw_snrcommon.MetricSNR (as reported by the gateway(s)).
rx_packets_per_freqcommon.MetricPackets received by frequency.
rx_packets_per_drcommon.MetricPackets received by DR.
errorscommon.MetricErrors.

GetDeviceMetricsRequest

FieldTypeLabelDescription
dev_euistringDevEUI (EUI64).
startgoogle.protobuf.TimestampInterval start timestamp.
endgoogle.protobuf.TimestampInterval end timestamp.
aggregationcommon.AggregationAggregation.

GetDeviceMetricsResponse

FieldTypeLabelDescription
metricsGetDeviceMetricsResponse.MetricsEntryrepeated
statesGetDeviceMetricsResponse.StatesEntryrepeated

GetDeviceMetricsResponse.MetricsEntry

FieldTypeLabelDescription
keystring
valuecommon.Metric

GetDeviceMetricsResponse.StatesEntry

FieldTypeLabelDescription
keystring
valueDeviceState

GetDeviceNextFCntDownRequest

FieldTypeLabelDescription
dev_euistringDevice EUI (EUI64).

GetDeviceNextFCntDownResponse

FieldTypeLabelDescription
f_cnt_downuint32FCntDown.

GetDeviceQueueItemsRequest

FieldTypeLabelDescription
dev_euistringDevice EUI (EUI64).
count_onlyboolReturn only the count, not the result-set.

GetDeviceQueueItemsResponse

FieldTypeLabelDescription
total_countuint32Total number of queue items.
resultDeviceQueueItemrepeatedResult-set.

GetDeviceRequest

FieldTypeLabelDescription
dev_euistringDevEUI (EUI64).

GetDeviceResponse

FieldTypeLabelDescription
deviceDeviceDevice object.
created_atgoogle.protobuf.TimestampCreated at timestamp.
updated_atgoogle.protobuf.TimestampLast update timestamp.
last_seen_atgoogle.protobuf.TimestampLast seen at timestamp.
device_statusDeviceStatusDevice status.
class_enabledcommon.DeviceClassEnabled device class.

GetRandomDevAddrRequest

FieldTypeLabelDescription
dev_euistringDevEUI (EUI64).

GetRandomDevAddrResponse

FieldTypeLabelDescription
dev_addrstringDevAddr.

ListDevicesRequest

FieldTypeLabelDescription
limituint32Max number of devices to return in the result-set.
offsetuint32Offset in the result-set (for pagination).
searchstringIf set, the given string will be used to search on name (optional).
application_idstringApplication ID (UUID) to filter devices on.
multicast_group_idstringMulticst-group ID (UUID) to filter devices on.

ListDevicesResponse

FieldTypeLabelDescription
total_countuint32Total number of devices.
resultDeviceListItemrepeatedResult-set.

UpdateDeviceKeysRequest

FieldTypeLabelDescription
device_keysDeviceKeysDevice-keys object.

UpdateDeviceRequest

FieldTypeLabelDescription
deviceDeviceDevice object.

DeviceService

DeviceService is the service providing API methods for managing devices.

Method NameRequest TypeResponse TypeDescription
CreateCreateDeviceRequest.google.protobuf.EmptyCreate the given device.
GetGetDeviceRequestGetDeviceResponseGet returns the device for the given DevEUI.
UpdateUpdateDeviceRequest.google.protobuf.EmptyUpdate the given device.
DeleteDeleteDeviceRequest.google.protobuf.EmptyDelete the device with the given DevEUI.
ListListDevicesRequestListDevicesResponseGet the list of devices.
CreateKeysCreateDeviceKeysRequest.google.protobuf.EmptyCreate the given device-keys.
GetKeysGetDeviceKeysRequestGetDeviceKeysResponseGet the device-keys for the given DevEUI.
UpdateKeysUpdateDeviceKeysRequest.google.protobuf.EmptyUpdate the given device-keys.
DeleteKeysDeleteDeviceKeysRequest.google.protobuf.EmptyDelete the device-keys for the given DevEUI.
FlushDevNoncesFlushDevNoncesRequest.google.protobuf.EmptyFlushDevNonces flushes the OTAA device nonces.
ActivateActivateDeviceRequest.google.protobuf.EmptyActivate (re)activates the device with the given parameters (for ABP or for importing OTAA activations).
DeactivateDeactivateDeviceRequest.google.protobuf.EmptyDeactivate de-activates the device.
GetActivationGetDeviceActivationRequestGetDeviceActivationResponseGetActivation returns the current activation details of the device (OTAA or ABP).
GetRandomDevAddrGetRandomDevAddrRequestGetRandomDevAddrResponseGetRandomDevAddr returns a random DevAddr taking the NwkID prefix into account.
GetMetricsGetDeviceMetricsRequestGetDeviceMetricsResponseGetMetrics returns the device metrics. Note that this requires a device-profile with codec and measurements configured.
GetLinkMetricsGetDeviceLinkMetricsRequestGetDeviceLinkMetricsResponseGetLinkMetrics returns the device link metrics. This includes uplinks, downlinks, RSSI, SNR, etc...
EnqueueEnqueueDeviceQueueItemRequestEnqueueDeviceQueueItemResponseEnqueue adds the given item to the downlink queue.
FlushQueueFlushDeviceQueueRequest.google.protobuf.EmptyFlushQueue flushes the downlink device-queue.
GetQueueGetDeviceQueueItemsRequestGetDeviceQueueItemsResponseGetQueue returns the downlink device-queue.
GetNextFCntDownGetDeviceNextFCntDownRequestGetDeviceNextFCntDownResponseGetNextFCntDown returns the next FCntDown to use for enqueing encrypted downlinks. The difference with the DeviceActivation f_cont_down is that this method takes potential existing queue-items into account.

Top

api/device_profile.proto

AdrAlgorithmListItem

FieldTypeLabelDescription
idstringAlgorithm ID.
namestringAlgorithm name.

CreateDeviceProfileRequest

FieldTypeLabelDescription
device_profileDeviceProfileObject to create.

CreateDeviceProfileResponse

FieldTypeLabelDescription
idstringID (UUID).

DeleteDeviceProfileRequest

FieldTypeLabelDescription
idstringID (UUID).

DeviceProfile

FieldTypeLabelDescription
idstringDevice-profile ID (UUID). Note: on create this will be automatically generated.
tenant_idstringTenant ID (UUID).
namestringName.
descriptionstringDescription.
regioncommon.RegionRegion.
mac_versioncommon.MacVersionLoRaWAN mac-version.
reg_params_revisioncommon.RegParamsRevisionRegional parameters revision.
adr_algorithm_idstringADR algorithm ID.
payload_codec_runtimeCodecRuntimePayload codec runtime.
payload_codec_scriptstringPayload codec script.
flush_queue_on_activateboolFlush queue on device activation.
uplink_intervaluint32Uplink interval (seconds). This defines the expected uplink interval which the device uses for communication. If the uplink interval has expired and no uplink has been received, the device is considered inactive.
device_status_req_intervaluint32Device-status request interval (times / day). This defines the times per day that ChirpStack will request the device-status from the device.
supports_otaaboolSupports OTAA.
supports_class_bboolSupports Class B.
supports_class_cboolSupports Class-C.
class_b_timeoutuint32Class-B timeout (seconds). This is the maximum time ChirpStack will wait to receive an acknowledgement from the device (if requested).
class_b_ping_slot_nb_kuint32Class-B ping-slots per beacon period. Valid options are: 0 - 7.

The actual number of ping-slots per beacon period equals to 2^k. | | class_b_ping_slot_dr | uint32 | | Class-B ping-slot DR. | | class_b_ping_slot_freq | uint32 | | Class-B ping-slot freq (Hz). | | class_c_timeout | uint32 | | Class-C timeout (seconds). This is the maximum time ChirpStack will wait to receive an acknowledgement from the device (if requested). | | abp_rx1_delay | uint32 | | RX1 delay (for ABP). | | abp_rx1_dr_offset | uint32 | | RX1 DR offset (for ABP). | | abp_rx2_dr | uint32 | | RX2 DR (for ABP). | | abp_rx2_freq | uint32 | | RX2 frequency (for ABP, Hz). | | tags | DeviceProfile.TagsEntry | repeated | Tags (user defined). These tags can be used to add additional information the the device-profile. These tags are exposed in all the integration events of devices using this device-profile. | | measurements | DeviceProfile.MeasurementsEntry | repeated | Measurements. If defined, ChirpStack will visualize these metrics in the web-interface. | | auto_detect_measurements | bool | | Auto-detect measurements. If set to true, measurements will be automatically added based on the keys of the decoded payload. In cases where the decoded payload contains random keys in the data, you want to set this to false. | | region_config_id | string | | Region configuration ID. If set, devices will only use the associated region. If let blank, then devices will use all regions matching the selected common-name. Note that multiple region configurations can exist for the same common-name, e.g. to provide an 8 channel and 16 channel configuration for the US915 band. | | is_relay | bool | | Device is a Relay device. Enable this in case the device is a Relay. A Relay device implements TS011 and is able to relay data from relay capable devices. See for more information the TS011 specification. | | is_relay_ed | bool | | Device is a Relay end-device. Enable this in case the device is an end-device that can operate under a Relay. Please refer to the TS011 specification for more information. | | relay_ed_relay_only | bool | | End-device only accept data through relay. Only accept data for this device through a relay. This setting is useful for testing as in case of a test-setup, the end-device is usually within range of the gateway. | | relay_enabled | bool | | Relay must be enabled. | | relay_cad_periodicity | CadPeriodicity | | Relay CAD periodicity. | | relay_default_channel_index | uint32 | | Relay default channel index. Valid values are 0 and 1, please refer to the RP002 specification for the meaning of these values. | | relay_second_channel_freq | uint32 | | Relay second channel frequency (Hz). | | relay_second_channel_dr | uint32 | | Relay second channel DR. | | relay_second_channel_ack_offset | SecondChAckOffset | | Relay second channel ACK offset. | | relay_ed_activation_mode | RelayModeActivation | | Relay end-device activation mode. | | relay_ed_smart_enable_level | uint32 | | Relay end-device smart-enable level. | | relay_ed_back_off | uint32 | | Relay end-device back-off (in case it does not receive WOR ACK frame). 0 = Always send a LoRaWAN uplink 1..63 = Send a LoRaWAN uplink after X WOR frames without a WOR ACK | | relay_ed_uplink_limit_bucket_size | uint32 | | Relay end-device uplink limit bucket size.

This field indicates the multiplier to determine the bucket size according to the following formula: BucketSize TOKEN = _reload_rate x _bucket_size

Valid values (0 - 3): 0 = 1 1 = 2 2 = 4 3 = 12 | | relay_ed_uplink_limit_reload_rate | uint32 | | Relay end-device uplink limit reload rate.

Valid values: * 0 - 62 = X tokens every hour * 63 = no limitation | | relay_join_req_limit_reload_rate | uint32 | | Relay join-request limit reload rate.

Valid values: * 0 - 126 = X tokens every hour * 127 = no limitation | | relay_notify_limit_reload_rate | uint32 | | Relay notify limit reload rate.

Valid values: * 0 - 126 = X tokens every hour * 127 = no limitation | | relay_global_uplink_limit_reload_rate | uint32 | | Relay global uplink limit reload rate.

Valid values: * 0 - 126 = X tokens every hour * 127 = no limitation | | relay_overall_limit_reload_rate | uint32 | | Relay overall limit reload rate.

Valid values: * 0 - 126 = X tokens every hour * 127 = no limitation | | relay_join_req_limit_bucket_size | uint32 | | Relay join-request limit bucket size.

This field indicates the multiplier to determine the bucket size according to the following formula: BucketSize TOKEN = _reload_rate x _bucket_size

Valid values (0 - 3): 0 = 1 1 = 2 2 = 4 3 = 12 | | relay_notify_limit_bucket_size | uint32 | | Relay notify limit bucket size.

This field indicates the multiplier to determine the bucket size according to the following formula: BucketSize TOKEN = _reload_rate x _bucket_size

Valid values (0 - 3): 0 = 1 1 = 2 2 = 4 3 = 12 | | relay_global_uplink_limit_bucket_size | uint32 | | Relay globak uplink limit bucket size.

This field indicates the multiplier to determine the bucket size according to the following formula: BucketSize TOKEN = _reload_rate x _bucket_size

Valid values (0 - 3): 0 = 1 1 = 2 2 = 4 3 = 12 | | relay_overall_limit_bucket_size | uint32 | | Relay overall limit bucket size.

This field indicates the multiplier to determine the bucket size according to the following formula: BucketSize TOKEN = _reload_rate x _bucket_size

Valid values (0 - 3): 0 = 1 1 = 2 2 = 4 3 = 12 | | allow_roaming | bool | | Allow roaming.

If set to true, it means that the device is allowed to use roaming. |

DeviceProfile.MeasurementsEntry

FieldTypeLabelDescription
keystring
valueMeasurement

DeviceProfile.TagsEntry

FieldTypeLabelDescription
keystring
valuestring

DeviceProfileListItem

FieldTypeLabelDescription
idstringDevice-profile ID (UUID).
created_atgoogle.protobuf.TimestampCreated at timestamp.
updated_atgoogle.protobuf.TimestampLast update timestamp.
namestringName.
regioncommon.RegionRegion.
mac_versioncommon.MacVersionLoRaWAN mac-version.
reg_params_revisioncommon.RegParamsRevisionRegional parameters revision.
supports_otaaboolSupports OTAA.
supports_class_bboolSupports Class-B.
supports_class_cboolSupports Class-C.

GetDeviceProfileRequest

FieldTypeLabelDescription
idstringID (UUID).

GetDeviceProfileResponse

FieldTypeLabelDescription
device_profileDeviceProfileDevice-profile object.
created_atgoogle.protobuf.TimestampCreated at timestamp.
updated_atgoogle.protobuf.TimestampLast update timestamp.

ListDeviceProfileAdrAlgorithmsResponse

FieldTypeLabelDescription
total_countuint32Total number of algorithms.
resultAdrAlgorithmListItemrepeatedResult-set.

ListDeviceProfilesRequest

FieldTypeLabelDescription
limituint32Max number of device-profiles to return in the result-set.
offsetuint32Offset in the result-set (for pagination).
searchstringIf set, the given string will be used to search on name.
tenant_idstringTenant ID to list the device-profiles for.

ListDeviceProfilesResponse

FieldTypeLabelDescription
total_countuint32Total number of device-profiles.
resultDeviceProfileListItemrepeatedResult-set.

Measurement

FieldTypeLabelDescription
namestringName (user defined).
kindMeasurementKindKind.

UpdateDeviceProfileRequest

FieldTypeLabelDescription
device_profileDeviceProfileDevice-profile object.

CadPeriodicity

NameNumberDescription
SEC_101 second.
MS_5001500 milliseconds
MS_2502250 milliseconds
MS_1003100 milliseconds
MS_50450 milliseconds
MS_20520 milliseconds

CodecRuntime

NameNumberDescription
NONE0None.
CAYENNE_LPP1Cayenne LPP.
JS2JavaScript.

MeasurementKind

NameNumberDescription
UNKNOWN0Unknown (in which case it is not tracked).
COUNTER1Incrementing counters that never decrease (these are not reset on each reading).
ABSOLUTE2Counters that do get reset upon reading.
GAUGE3E.g. a temperature value.
STRING4E.g. a firmware version, true / false value.

RelayModeActivation

NameNumberDescription
DISABLE_RELAY_MODE0Disable the relay mode.
ENABLE_RELAY_MODE1Enable the relay model.
DYNAMIC2Dynamic.
END_DEVICE_CONTROLLED3End-device controlled.

SecondChAckOffset

NameNumberDescription
KHZ_000 kHz.
KHZ_2001200 kHz.
KHZ_4002400 kHz.
KHZ_8003800 kHz.
KHZ_160041600 kHz.
KHZ_320053200 kHz.

DeviceProfileService

DeviceProfileService is the service providing API methods for managing device-profiles.

Method NameRequest TypeResponse TypeDescription
CreateCreateDeviceProfileRequestCreateDeviceProfileResponseCreate the given device-profile.
GetGetDeviceProfileRequestGetDeviceProfileResponseGet the device-profile for the given ID.
UpdateUpdateDeviceProfileRequest.google.protobuf.EmptyUpdate the given device-profile.
DeleteDeleteDeviceProfileRequest.google.protobuf.EmptyDelete the device-profile with the given ID.
ListListDeviceProfilesRequestListDeviceProfilesResponseList the available device-profiles.
ListAdrAlgorithms.google.protobuf.EmptyListDeviceProfileAdrAlgorithmsResponseList available ADR algorithms.

Top

api/device_profile_template.proto

CreateDeviceProfileTemplateRequest

FieldTypeLabelDescription
device_profile_templateDeviceProfileTemplateObject to create.

DeleteDeviceProfileTemplateRequest

FieldTypeLabelDescription
idstringID.

DeviceProfileTemplate

FieldTypeLabelDescription
idstringDevice-profile template ID.
namestringName.
descriptionstringDescription.
vendorstringVendor.
firmwarestringFirmware.
regioncommon.RegionRegion.
mac_versioncommon.MacVersionLoRaWAN mac-version.
reg_params_revisioncommon.RegParamsRevisionRegional parameters revision.
adr_algorithm_idstringADR algorithm ID.
payload_codec_runtimeCodecRuntimePayload codec runtime.
payload_codec_scriptstringPayload codec script.
flush_queue_on_activateboolFlush queue on device activation.
uplink_intervaluint32Uplink interval (seconds). This defines the expected uplink interval which the device uses for communication. When the uplink interval has expired and no uplink has been received, the device is considered inactive.
device_status_req_intervaluint32Device-status request interval (times / day). This defines the times per day that ChirpStack will request the device-status from the device.
supports_otaaboolSupports OTAA.
supports_class_bboolSupports Class B.
supports_class_cboolSupports Class-C.
class_b_timeoutuint32Class-B timeout (seconds). This is the maximum time ChirpStack will wait to receive an acknowledgement from the device (if requested).
class_b_ping_slot_nb_kuint32Class-B ping-slots per beacon period. Valid options are: 0 - 7.

The actual number of ping-slots per beacon period equals to 2^k. | | class_b_ping_slot_dr | uint32 | | Class-B ping-slot DR. | | class_b_ping_slot_freq | uint32 | | Class-B ping-slot freq (Hz). | | class_c_timeout | uint32 | | Class-C timeout (seconds). This is the maximum time ChirpStack will wait to receive an acknowledgement from the device (if requested). | | abp_rx1_delay | uint32 | | RX1 delay (for ABP). | | abp_rx1_dr_offset | uint32 | | RX1 DR offset (for ABP). | | abp_rx2_dr | uint32 | | RX2 DR (for ABP). | | abp_rx2_freq | uint32 | | RX2 frequency (for ABP, Hz). | | tags | DeviceProfileTemplate.TagsEntry | repeated | User defined tags. | | measurements | DeviceProfileTemplate.MeasurementsEntry | repeated | Measurements. If defined, ChirpStack will visualize these metrics in the web-interface. | | auto_detect_measurements | bool | | Auto-detect measurements. If set to true, measurements will be automatically added based on the keys of the decoded payload. In cases where the decoded payload contains random keys in the data, you want to set this to false. |

DeviceProfileTemplate.MeasurementsEntry

FieldTypeLabelDescription
keystring
valueMeasurement

DeviceProfileTemplate.TagsEntry

FieldTypeLabelDescription
keystring
valuestring

DeviceProfileTemplateListItem

FieldTypeLabelDescription
idstringDevice-profile template ID.
created_atgoogle.protobuf.TimestampCreated at timestamp.
updated_atgoogle.protobuf.TimestampLast update timestamp.
namestringName.
vendorstringVendor.
firmwarestringFirmware.
regioncommon.RegionRegion.
mac_versioncommon.MacVersionLoRaWAN mac-version.
reg_params_revisioncommon.RegParamsRevisionRegional parameters revision.
supports_otaaboolSupports OTAA.
supports_class_bboolSupports Class-B.
supports_class_cboolSupports Class-C.

GetDeviceProfileTemplateRequest

FieldTypeLabelDescription
idstringID.

GetDeviceProfileTemplateResponse

FieldTypeLabelDescription
device_profile_templateDeviceProfileTemplateDevice-profile template object.
created_atgoogle.protobuf.TimestampCreated at timestamp.
updated_atgoogle.protobuf.TimestampLast update timestamp.

ListDeviceProfileTemplatesRequest

FieldTypeLabelDescription
limituint32Max number of device-profile templates to return in the result-set.
offsetuint32Offset in the result-set (for pagination).

ListDeviceProfileTemplatesResponse

FieldTypeLabelDescription
total_countuint32Total number of device-profile templates.
resultDeviceProfileTemplateListItemrepeatedResult-set.

UpdateDeviceProfileTemplateRequest

FieldTypeLabelDescription
device_profile_templateDeviceProfileTemplateObject to update.

DeviceProfileTemplateService

DeviceProfileTemplateService is the service providing API methods for managing device-profile templates.

Method NameRequest TypeResponse TypeDescription
CreateCreateDeviceProfileTemplateRequest.google.protobuf.EmptyCreate the given device-profile template.
GetGetDeviceProfileTemplateRequestGetDeviceProfileTemplateResponseGet the device-profile template for the given ID.
UpdateUpdateDeviceProfileTemplateRequest.google.protobuf.EmptyUpdate the given device-profile template.
DeleteDeleteDeviceProfileTemplateRequest.google.protobuf.EmptyDelete the device-profile template with the given ID.
ListListDeviceProfileTemplatesRequestListDeviceProfileTemplatesResponseList the available device-profile templates.

Top

api/gateway.proto

CreateGatewayRequest

FieldTypeLabelDescription
gatewayGatewayGateway object.

DeleteGatewayRequest

FieldTypeLabelDescription
gateway_idstringGateway ID (EUI64).

Gateway

FieldTypeLabelDescription
gateway_idstringGateway ID (EUI64).
namestringName.
descriptionstringDescription.
locationcommon.LocationGateway location.
tenant_idstringTenant ID (UUID).
tagsGateway.TagsEntryrepeatedTags.
metadataGateway.MetadataEntryrepeatedMetadata (provided by the gateway).
stats_intervaluint32Stats interval (seconds). This defines the expected interval in which the gateway sends its statistics.

Gateway.MetadataEntry

FieldTypeLabelDescription
keystring
valuestring

Gateway.TagsEntry

FieldTypeLabelDescription
keystring
valuestring

GatewayListItem

FieldTypeLabelDescription
tenant_idstringTenant ID.
gateway_idstringGateway ID (EUI64).
namestringName.
descriptionstringDescription.
locationcommon.LocationLocation.
propertiesGatewayListItem.PropertiesEntryrepeatedGateway properties.
created_atgoogle.protobuf.TimestampCreated at timestamp.
updated_atgoogle.protobuf.TimestampLast update timestamp.
last_seen_atgoogle.protobuf.TimestampLast seen at timestamp.
stateGatewayStateGateway state. Please note that the state of the gateway is driven by the stats packages that are sent by the gateway.

GatewayListItem.PropertiesEntry

FieldTypeLabelDescription
keystring
valuestring

GenerateGatewayClientCertificateRequest

FieldTypeLabelDescription
gateway_idstringGateway ID (EUI64).

GenerateGatewayClientCertificateResponse

FieldTypeLabelDescription
tls_certstringTLS certificate.
tls_keystringTLS key.
ca_certstringCA certificate.
expires_atgoogle.protobuf.TimestampExpires at defines the expiration date of the certificate.

GetGatewayMetricsRequest

FieldTypeLabelDescription
gateway_idstringGateway ID (EUI64).
startgoogle.protobuf.TimestampInterval start timestamp.
endgoogle.protobuf.TimestampInterval end timestamp.
aggregationcommon.AggregationAggregation.

GetGatewayMetricsResponse

FieldTypeLabelDescription
rx_packetscommon.MetricRX packets.
tx_packetscommon.MetricTX packets.
tx_packets_per_freqcommon.MetricTX packets / frequency.
rx_packets_per_freqcommon.MetricRX packets / frequency.
tx_packets_per_drcommon.MetricTX packets / DR.
rx_packets_per_drcommon.MetricRX packets / DR.
tx_packets_per_statuscommon.MetricTX packets per status.

GetGatewayRequest

FieldTypeLabelDescription
gateway_idstringGateway ID (EUI64).

GetGatewayResponse

FieldTypeLabelDescription
gatewayGatewayGateway object.
created_atgoogle.protobuf.TimestampCreated at timestamp.
updated_atgoogle.protobuf.TimestampLast update timestamp.
last_seen_atgoogle.protobuf.TimestampLast seen at timestamp.

ListGatewaysRequest

FieldTypeLabelDescription
limituint32Max number of gateways to return in the result-set.
offsetuint32Offset in the result-set (for pagination).
searchstringIf set, the given string will be used to search on name (optional).
tenant_idstringTenant ID (UUID) to filter gateways on. To list all gateways as a global admin user, this field can be left blank.
multicast_group_idstringMulticast-group ID (UUID) to filter gateways on.

ListGatewaysResponse

FieldTypeLabelDescription
total_countuint32Total number of gateways.
resultGatewayListItemrepeatedResult-set.

UpdateGatewayRequest

FieldTypeLabelDescription
gatewayGatewayGateway object.

GatewayState

NameNumberDescription
NEVER_SEEN0The gateway has never sent any stats.
ONLINE1Online.
OFFLINE2Offline.

GatewayService

GatewayService is the service providing API methods for managing gateways.

Method NameRequest TypeResponse TypeDescription
CreateCreateGatewayRequest.google.protobuf.EmptyCreate creates the given gateway.
GetGetGatewayRequestGetGatewayResponseGet returns the gateway for the given Gateway ID.
UpdateUpdateGatewayRequest.google.protobuf.EmptyUpdate updates the given gateway.
DeleteDeleteGatewayRequest.google.protobuf.EmptyDelete deletes the gateway matching the given Gateway ID.
ListListGatewaysRequestListGatewaysResponseGet the list of gateways.
GenerateClientCertificateGenerateGatewayClientCertificateRequestGenerateGatewayClientCertificateResponseGenerate client-certificate for the gateway.
GetMetricsGetGatewayMetricsRequestGetGatewayMetricsResponseGetMetrics returns the gateway metrics.

Top

api/multicast_group.proto

AddDeviceToMulticastGroupRequest

FieldTypeLabelDescription
multicast_group_idstringMulticast group ID.
dev_euistringDevice EUI (HEX encoded).

AddGatewayToMulticastGroupRequest

FieldTypeLabelDescription
multicast_group_idstringMulticast group ID.
gateway_idstringGateway ID (HEX encoded).

CreateMulticastGroupRequest

FieldTypeLabelDescription
multicast_groupMulticastGroupMulticast group to create.

CreateMulticastGroupResponse

FieldTypeLabelDescription
idstringID of created multicast group (UUID).

DeleteMulticastGroupRequest

FieldTypeLabelDescription
idstringMulticast group iD.

EnqueueMulticastGroupQueueItemRequest

FieldTypeLabelDescription
queue_itemMulticastGroupQueueItemMulticast queue-item to enqueue.

EnqueueMulticastGroupQueueItemResponse

FieldTypeLabelDescription
f_cntuint32Frame-counter of the enqueued payload.

FlushMulticastGroupQueueRequest

FieldTypeLabelDescription
multicast_group_idstringMulticast group ID.

GetMulticastGroupRequest

FieldTypeLabelDescription
idstringMulticast group ID.

GetMulticastGroupResponse

FieldTypeLabelDescription
multicast_groupMulticastGroupMulticast group object.
created_atgoogle.protobuf.TimestampCreated at timestamp.
updated_atgoogle.protobuf.TimestampLast update timestamp.

ListMulticastGroupQueueRequest

FieldTypeLabelDescription
multicast_group_idstringMulticast group ID.

ListMulticastGroupQueueResponse

FieldTypeLabelDescription
itemsMulticastGroupQueueItemrepeated

ListMulticastGroupsRequest

FieldTypeLabelDescription
limituint32Max number of multicast groups to return in the result-set.
offsetuint32Offset in the result-set (for pagination).
searchstringIf set, the given string will be used to search on name.
application_idstringApplication ID to list the multicast groups for.

ListMulticastGroupsResponse

FieldTypeLabelDescription
total_countuint32Total number of multicast groups.
resultMulticastGroupListItemrepeatedResult-test.

MulticastGroup

FieldTypeLabelDescription
idstringID (UUID). This will be generated automatically on create.
namestringName.
application_idstringApplication ID. After creation, this can not be updated.
regioncommon.RegionRegion.
mc_addrstringMulticast address (HEX encoded DevAddr).
mc_nwk_s_keystringMulticast network session key (HEX encoded AES128 key).
mc_app_s_keystringMulticast application session key (HEX encoded AES128 key).
f_cntuint32Frame-counter.
group_typeMulticastGroupTypeMulticast group type.
druint32Data-rate.
frequencyuint32Frequency (Hz).
class_b_ping_slot_perioduint32Ping-slot period (only for Class-B).
class_c_scheduling_typeMulticastGroupSchedulingTypeScheduling type (only for Class-C).

MulticastGroupListItem

FieldTypeLabelDescription
idstringID.
created_atgoogle.protobuf.TimestampCreated at timestamp.
updated_atgoogle.protobuf.TimestampLast update timestamp.
namestringName.
regioncommon.RegionRegion.
group_typeMulticastGroupTypeMulticast group type.

MulticastGroupQueueItem

FieldTypeLabelDescription
multicast_group_idstringMulticast group ID.
f_cntuint32Downlink frame-counter. This will be automatically set on enqueue.
f_portuint32FPort (must be > 0).
databytesPayload.

RemoveDeviceFromMulticastGroupRequest

FieldTypeLabelDescription
multicast_group_idstringMulticast group ID.
dev_euistringDevice EUI (HEX encoded).

RemoveGatewayFromMulticastGroupRequest

FieldTypeLabelDescription
multicast_group_idstringMulticast group ID.
gateway_idstringGateway ID (HEX encoded).

UpdateMulticastGroupRequest

FieldTypeLabelDescription
multicast_groupMulticastGroupMulticast group object to update.

MulticastGroupSchedulingType

NameNumberDescription
DELAY0Delay. If multicast downlinks must be sent through multiple gateways, then these will be sent one by one with a delay between each gateway.
GPS_TIME1Time. If multicast downlinks must be sent through multiple gateways, then these will be sent simultaneously using GPS time synchronization. Note that this does require GPS time-synchronized LoRa gateways.

MulticastGroupType

NameNumberDescription
CLASS_C0Class C.
CLASS_B1Class-B.

MulticastGroupService

MulticastGroupService is the service managing multicast-groups.

Method NameRequest TypeResponse TypeDescription
CreateCreateMulticastGroupRequestCreateMulticastGroupResponseCreate the given multicast group.
GetGetMulticastGroupRequestGetMulticastGroupResponseGet returns the multicast group for the given ID.
UpdateUpdateMulticastGroupRequest.google.protobuf.EmptyUpdate the given multicast group.
DeleteDeleteMulticastGroupRequest.google.protobuf.EmptyDelete the multicast-group with the given ID.
ListListMulticastGroupsRequestListMulticastGroupsResponseList the available multicast groups.
AddDeviceAddDeviceToMulticastGroupRequest.google.protobuf.EmptyAdd a device to the multicast group.
RemoveDeviceRemoveDeviceFromMulticastGroupRequest.google.protobuf.EmptyRemove a device from the multicast group.
AddGatewayAddGatewayToMulticastGroupRequest.google.protobuf.EmptyAdd a gateway to the multicast group.
RemoveGatewayRemoveGatewayFromMulticastGroupRequest.google.protobuf.EmptyRemove a gateway from the multicast group.
EnqueueEnqueueMulticastGroupQueueItemRequestEnqueueMulticastGroupQueueItemResponseAdd the given item to the multicast group queue.
FlushQueueFlushMulticastGroupQueueRequest.google.protobuf.EmptyFlush the queue for the given multicast group.
ListQueueListMulticastGroupQueueRequestListMulticastGroupQueueResponseList the items in the multicast group queue.

Top

api/relay.proto

AddRelayDeviceRequest

FieldTypeLabelDescription
relay_dev_euistringRelay DevEUI (EUI64).
device_dev_euistringDevice DevEUI (EUI64).

ListRelayDevicesRequest

FieldTypeLabelDescription
limituint32Max number of multicast groups to return in the result-set.
offsetuint32Offset in the result-set (for pagination).
relay_dev_euistringRelay DevEUI (EUI64).

ListRelayDevicesResponse

FieldTypeLabelDescription
total_countuint32Total number of devices.
resultRelayDeviceListItemrepeatedResult-set.

ListRelaysRequest

FieldTypeLabelDescription
limituint32Max number of devices to return in the result-set.
offsetuint32Offset in the result-set (for pagination).
application_idstringApplication ID (UUID).

ListRelaysResponse

FieldTypeLabelDescription
total_countuint32Total number of relays.
resultRelayListItemrepeatedResult-set.

RelayDeviceListItem

FieldTypeLabelDescription
dev_euistringDevEUI (EUI64).
created_atgoogle.protobuf.TimestampCreated at timestamp.
namestringDevice name.

RelayListItem

FieldTypeLabelDescription
dev_euistringDevEUI (EUI64).
namestringName.

RemoveRelayDeviceRequest

FieldTypeLabelDescription
relay_dev_euistringRelay DevEUI (EUI64).
device_dev_euistringDevice DevEUI (EUI64).

RelayService

RelayService is the service providing API methos for managing relays.

Method NameRequest TypeResponse TypeDescription
ListListRelaysRequestListRelaysResponseList lists the relays for the given application id.
AddDeviceAddRelayDeviceRequest.google.protobuf.EmptyAddDevice adds the given device to the relay.
RemoveDeviceRemoveRelayDeviceRequest.google.protobuf.EmptyRemoveDevice removes the given device from the relay.
ListDevicesListRelayDevicesRequestListRelayDevicesResponseListDevices lists the devices for the given relay.

Top

api/tenant.proto

AddTenantUserRequest

FieldTypeLabelDescription
tenant_userTenantUserTenant user object.

CreateTenantRequest

FieldTypeLabelDescription
tenantTenantTenant object to create.

CreateTenantResponse

FieldTypeLabelDescription
idstringTenant ID.

DeleteTenantRequest

FieldTypeLabelDescription
idstringTenant ID.

DeleteTenantUserRequest

FieldTypeLabelDescription
tenant_idstringTenant ID (UUID).
user_idstringUser ID (UUID).

GetTenantRequest

FieldTypeLabelDescription
idstringTenant ID.

GetTenantResponse

FieldTypeLabelDescription
tenantTenantTenant object.
created_atgoogle.protobuf.TimestampCreated at timestamp.
updated_atgoogle.protobuf.TimestampLast update timestamp.

GetTenantUserRequest

FieldTypeLabelDescription
tenant_idstringTenant ID (UUID).
user_idstringUser ID (UUID).

GetTenantUserResponse

FieldTypeLabelDescription
tenant_userTenantUserTenant user object.
created_atgoogle.protobuf.TimestampCreated at timestamp.
updated_atgoogle.protobuf.TimestampLast update timestamp.

ListTenantUsersRequest

FieldTypeLabelDescription
tenant_idstringTenant ID (UUID).
limituint32Max number of tenants to return in the result-set.
offsetuint32Offset in the result-set (for pagination).

ListTenantUsersResponse

FieldTypeLabelDescription
total_countuint32Total number of tenants.
resultTenantUserListItemrepeatedResult-set.

ListTenantsRequest

FieldTypeLabelDescription
limituint32Max number of tenants to return in the result-set.
offsetuint32Offset in the result-set (for pagination).
searchstringIf set, the given string will be used to search on name.
user_idstringIf set, filters the result set to the tenants of the user. Only global API keys are able to filter by this field.

ListTenantsResponse

FieldTypeLabelDescription
total_countuint32Total number of tenants.
resultTenantListItemrepeatedResult-set.

Tenant

FieldTypeLabelDescription
idstringTenant ID (UUID). Note: this value will be automatically generated on create.
namestringTenant name,
descriptionstringTenant description.
can_have_gatewaysboolCan the tenant create and "own" Gateways?
max_gateway_countuint32Max. gateway count for tenant. When set to 0, the tenant can have unlimited gateways.
max_device_countuint32Max. device count for tenant. When set to 0, the tenant can have unlimited devices.
private_gateways_upboolPrivate gateways (uplink). If enabled, then uplink messages will not be shared with other tenants.
private_gateways_downboolPrivate gateways (downlink). If enabled, then other tenants will not be able to schedule downlink messages through the gateways of this tenant. For example, in case you do want to share uplinks with other tenants (private_gateways_up=false), but you want to prevent other tenants from using gateway airtime.
tagsTenant.TagsEntryrepeatedTags (user defined). These tags can be used to add additional information to the tenant. These tags are NOT exposed in the integration events.

Tenant.TagsEntry

FieldTypeLabelDescription
keystring
valuestring

TenantListItem

FieldTypeLabelDescription
idstringTenant ID (UUID).
created_atgoogle.protobuf.TimestampCreated at timestamp.
updated_atgoogle.protobuf.TimestampLast update timestamp.
namestringTenant name.
can_have_gatewaysboolCan the tenant create and "own" Gateways?
private_gateways_upboolPrivate gateways (uplink).
private_gateways_downboolPrivate gateways (downlink).
max_gateway_countuint32Max gateway count. 0 = unlimited.
max_device_countuint32Max device count. 0 = unlimited.

TenantUser

FieldTypeLabelDescription
tenant_idstringTenant ID (UUID).
user_idstringUser ID (UUID).
is_adminboolUser is admin within the context of the tenant. There is no need to set the is_device_admin and is_gateway_admin flags.
is_device_adminboolUser is able to modify device related resources (applications, device-profiles, devices, multicast-groups).
is_gateway_adminboolUser is able to modify gateways.
emailstringEmail (only used on get and when adding a user to a tenant).

TenantUserListItem

FieldTypeLabelDescription
tenant_idstringTenant ID (UUID).
user_idstringUser ID (UUID).
created_atgoogle.protobuf.TimestampCreated at timestamp.
updated_atgoogle.protobuf.TimestampLast update timestamp.
emailstringEmail.
is_adminboolUser is admin within the context of the tenant. There is no need to set the is_device_admin and is_gateway_admin flags.
is_device_adminboolUser is able to modify device related resources (applications, device-profiles, devices, multicast-groups).
is_gateway_adminboolUser is able to modify gateways.

UpdateTenantRequest

FieldTypeLabelDescription
tenantTenantTenant object.

UpdateTenantUserRequest

FieldTypeLabelDescription
tenant_userTenantUserTenant user object.

TenantService

TenantService is the service providing API methods for managing tenants.

Method NameRequest TypeResponse TypeDescription
CreateCreateTenantRequestCreateTenantResponseCreate a new tenant.
GetGetTenantRequestGetTenantResponseGet the tenant for the given ID.
UpdateUpdateTenantRequest.google.protobuf.EmptyUpdate the given tenant.
DeleteDeleteTenantRequest.google.protobuf.EmptyDelete the tenant with the given ID.
ListListTenantsRequestListTenantsResponseGet the list of tenants.
AddUserAddTenantUserRequest.google.protobuf.EmptyAdd an user to the tenant. Note: the user must already exist.
GetUserGetTenantUserRequestGetTenantUserResponseGet the the tenant user for the given tenant and user IDs.
UpdateUserUpdateTenantUserRequest.google.protobuf.EmptyUpdate the given tenant user.
DeleteUserDeleteTenantUserRequest.google.protobuf.EmptyDelete the given tenant user.
ListUsersListTenantUsersRequestListTenantUsersResponseGet the list of tenant users.

Top

api/user.proto

CreateUserRequest

FieldTypeLabelDescription
userUserUser object to create.
passwordstringPassword to set for the user.
tenantsUserTenantrepeatedAdd the user to the following tenants.

CreateUserResponse

FieldTypeLabelDescription
idstringUser ID.

DeleteUserRequest

FieldTypeLabelDescription
idstringUser ID.

GetUserRequest

FieldTypeLabelDescription
idstringUser ID.

GetUserResponse

FieldTypeLabelDescription
userUserUser object.
created_atgoogle.protobuf.TimestampCreated at timestamp.
updated_atgoogle.protobuf.TimestampLast update timestamp.

ListUsersRequest

FieldTypeLabelDescription
limituint32Max number of tenants to return in the result-set.
offsetuint32Offset in the result-set (for pagination).

ListUsersResponse

FieldTypeLabelDescription
total_countuint32Total number of users.
resultUserListItemrepeatedResult-set.

UpdateUserPasswordRequest

FieldTypeLabelDescription
user_idstringUser ID.
passwordstringPassword to set.

UpdateUserRequest

FieldTypeLabelDescription
userUserUser object.

User

FieldTypeLabelDescription
idstringUser ID (UUID). Will be set automatically on create.
is_adminboolSet to true to make the user a global administrator.
is_activeboolSet to false to disable the user.
emailstringE-mail of the user.
notestringOptional note to store with the user.

UserListItem

FieldTypeLabelDescription
idstringUser ID (UUID).
created_atgoogle.protobuf.TimestampCreated at timestamp.
updated_atgoogle.protobuf.TimestampLast update timestamp.
emailstringEmail of the user.
is_adminboolSet to true to make the user a global administrator.
is_activeboolSet to false to disable the user.

UserTenant

FieldTypeLabelDescription
tenant_idstringTenant ID.
is_adminboolUser is admin within the context of the tenant. There is no need to set the is_device_admin and is_gateway_admin flags.
is_device_adminboolUser is able to modify device related resources (applications, device-profiles, devices, multicast-groups).
is_gateway_adminboolUser is able to modify gateways.

UserService

UserService is the service providing API methods for managing users.

Method NameRequest TypeResponse TypeDescription
CreateCreateUserRequestCreateUserResponseCreate a new user.
GetGetUserRequestGetUserResponseGet the user for the given ID.
UpdateUpdateUserRequest.google.protobuf.EmptyUpdate the given user.
DeleteDeleteUserRequest.google.protobuf.EmptyDelete the user with the given ID.
ListListUsersRequestListUsersResponseGet the list of users.
UpdatePasswordUpdateUserPasswordRequest.google.protobuf.EmptyUpdate the password for the given user.

Scalar Value Types

.proto TypeNotesC++JavaPythonGoC#PHPRuby
doubledoubledoublefloatfloat64doublefloatFloat
floatfloatfloatfloatfloat32floatfloatFloat
int32Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint32 instead.int32intintint32intintegerBignum or Fixnum (as required)
int64Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint64 instead.int64longint/longint64longinteger/stringBignum
uint32Uses variable-length encoding.uint32intint/longuint32uintintegerBignum or Fixnum (as required)
uint64Uses variable-length encoding.uint64longint/longuint64ulonginteger/stringBignum or Fixnum (as required)
sint32Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s.int32intintint32intintegerBignum or Fixnum (as required)
sint64Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s.int64longint/longint64longinteger/stringBignum
fixed32Always four bytes. More efficient than uint32 if values are often greater than 2^28.uint32intintuint32uintintegerBignum or Fixnum (as required)
fixed64Always eight bytes. More efficient than uint64 if values are often greater than 2^56.uint64longint/longuint64ulonginteger/stringBignum
sfixed32Always four bytes.int32intintint32intintegerBignum or Fixnum (as required)
sfixed64Always eight bytes.int64longint/longint64longinteger/stringBignum
boolboolbooleanbooleanboolboolbooleanTrueClass/FalseClass
stringA string must always contain UTF-8 encoded or 7-bit ASCII text.stringStringstr/unicodestringstringstringString (UTF-8)
bytesMay contain any arbitrary sequence of bytes.stringByteStringstr[]byteByteStringstringString (ASCII-8BIT)