End devices are registered in multiple registries. The Identity Server has a registry with end device metadata, the Network Server’s registry contains the MAC configuration, MAC state and network session keys, the Application Server keeps payload formatters and application session keys, the Join Server keeps the root keys.
When registering end devices, we recommend registering them in the following order:
EndDeviceRegistry.Create
(Identity Server)JsEndDeviceRegistry.Set
(Join Server, only for OTAA devices)NsEndDeviceRegistry.Set
(Network Server)AsEndDeviceRegistry.Set
(Application Server)
When deleting end devices, we recommend deleting them in the reverse order
The EndDeviceRegistry
service
The Identity Server’s EndDeviceRegistry
is the first service, where end device is registered. The following EndDevice fields are registered in this registry:
ids
(with subfields)name
description
attributes
version_ids
(with subfields)network_server_address
application_server_address
join_server_address
(only for OTAA devices)service_profile_id
locations
picture
Method |
EndDeviceRegistry.Create
|
---|---|
Description |
Create a new end device within an application. After registering an end device, it also needs to be registered in the NsEndDeviceRegistry that is exposed by the Network Server, the AsEndDeviceRegistry that is exposed by the Application Server, and the JsEndDeviceRegistry that is exposed by the Join Server. |
Request type |
CreateEndDeviceRequest
|
Response type |
EndDevice
|
HTTP bindings |
|
Method |
EndDeviceRegistry.Get
|
---|---|
Description | Get the end device with the given identifiers, selecting the fields specified in the field mask. More or less fields may be returned, depending on the rights of the caller. |
Request type |
GetEndDeviceRequest
|
Response type |
EndDevice
|
HTTP bindings |
|
Method |
EndDeviceRegistry.List
|
---|---|
Description | List end devices in the given application. Similar to Get, this selects the fields given by the field mask. More or less fields may be returned, depending on the rights of the caller. |
Request type |
ListEndDevicesRequest
|
Response type |
EndDevices
|
HTTP bindings |
|
Method |
EndDeviceRegistry.Update
|
---|---|
Description | Update the OAuth client, changing the fields specified by the field mask to the provided values. |
Request type |
UpdateEndDeviceRequest
|
Response type |
EndDevice
|
HTTP bindings |
|
Method |
EndDeviceRegistry.Delete
|
---|---|
Description |
Delete the end device with the given IDs. Before deleting an end device it first needs to be deleted from the NsEndDeviceRegistry, the AsEndDeviceRegistry and the JsEndDeviceRegistry. This is NOT done automatically. |
Request type |
EndDeviceIdentifiers
|
Response type |
google.protobuf.Empty
|
HTTP bindings |
|
The JsEndDeviceRegistry
service
OTAA devices are registered in the Join Server’s JsEndDeviceRegistry
. The following EndDevice fields are registered in this registry:
ids
(with subfields)provisioner_id
(when provisioning with secure elements)provisioning_data
(when provisioning with secure elements)resets_join_nonces
root_keys
:root_key_id
app_key
nwk_key
net_id
network_server_address
network_server_kek_label
application_server_address
application_server_id
application_server_kek_label
claim_authentication_code
(when using end device claiming)
See the EndDevice message and its sub-messages for additional fields that can be read from the Join Server’s JsEndDeviceRegistry
.
Method |
JsEndDeviceRegistry.Set
|
---|---|
Description | Set creates or updates the device. |
Request type |
SetEndDeviceRequest
|
Response type |
EndDevice
|
HTTP bindings |
|
Method |
JsEndDeviceRegistry.Get
|
---|---|
Description | Get returns the device that matches the given identifiers. If there are multiple matches, an error will be returned. |
Request type |
GetEndDeviceRequest
|
Response type |
EndDevice
|
HTTP bindings |
|
Method |
JsEndDeviceRegistry.Delete
|
---|---|
Description | Delete deletes the device that matches the given identifiers. If there are multiple matches, an error will be returned. |
Request type |
EndDeviceIdentifiers
|
Response type |
google.protobuf.Empty
|
HTTP bindings |
|
The NsEndDeviceRegistry
service
The following EndDevice fields are registered in the Network Server’s NsEndDeviceRegistry
:
ids
(with subfields)frequency_plan_id
lorawan_phy_version
lorawan_version
mac_settings
(with subfields)mac_state
(with subfields)supports_join
multicast
supports_class_b
supports_class_c
session.dev_addr
session.keys
:session_key_id
f_nwk_s_int_key
s_nwk_s_int_key
nwk_s_enc_key
See the EndDevice message and its sub-messages for additional fields that can be read from the Network Server’s NsEndDeviceRegistry
.
Method |
NsEndDeviceRegistry.Set
|
---|---|
Description | Set creates or updates the device. |
Request type |
SetEndDeviceRequest
|
Response type |
EndDevice
|
HTTP bindings |
|
Method |
NsEndDeviceRegistry.Get
|
---|---|
Description | Get returns the device that matches the given identifiers. If there are multiple matches, an error will be returned. |
Request type |
GetEndDeviceRequest
|
Response type |
EndDevice
|
HTTP bindings |
|
Method |
NsEndDeviceRegistry.Delete
|
---|---|
Description | Delete deletes the device that matches the given identifiers. If there are multiple matches, an error will be returned. |
Request type |
EndDeviceIdentifiers
|
Response type |
google.protobuf.Empty
|
HTTP bindings |
|
The AsEndDeviceRegistry
service
The following EndDevice fields are registered in the Application Server’s AsEndDeviceRegistry
:
ids
(with subfields)formatters
:up_formatter
up_formatter_parameter
down_formatter
down_formatter_parameter
session.dev_addr
session.keys
:session_key_id
app_s_key
See the EndDevice message and its sub-messages for additional fields that can be read from the Application Server’s AsEndDeviceRegistry
.
Method |
AsEndDeviceRegistry.Set
|
---|---|
Description | Set creates or updates the device. |
Request type |
SetEndDeviceRequest
|
Response type |
EndDevice
|
HTTP bindings |
|
Method |
AsEndDeviceRegistry.Get
|
---|---|
Description | Get returns the device that matches the given identifiers. If there are multiple matches, an error will be returned. |
Request type |
GetEndDeviceRequest
|
Response type |
EndDevice
|
HTTP bindings |
|
Method |
AsEndDeviceRegistry.Delete
|
---|---|
Description | Delete deletes the device that matches the given identifiers. If there are multiple matches, an error will be returned. |
Request type |
EndDeviceIdentifiers
|
Response type |
google.protobuf.Empty
|
HTTP bindings |
|
Messages
Message CreateEndDeviceRequest
Field |
end_device
|
---|---|
Type | EndDevice |
Description |
|
Show object example
{
"end_device": {},
}
Message EndDevice
Defines an End Device registration and its state on the network. The persistence of the EndDevice is divided between the Network Server, Application Server and Join Server. SDKs are responsible for combining (if desired) the three.
Field |
ids
|
---|---|
Type | EndDeviceIdentifiers |
Description |
|
Field |
created_at
|
---|---|
Type | google.protobuf.Timestamp |
Field |
updated_at
|
---|---|
Type | google.protobuf.Timestamp |
Field |
name
|
---|---|
Type | string |
Description |
Friendly name of the device. Stored in Entity Registry.
|
Field |
description
|
---|---|
Type | string |
Description |
Description of the device. Stored in Entity Registry.
|
Field |
attributes
|
---|---|
Type | map of string to string |
Description |
Key-value attributes for this end device. Typically used for organizing end devices or for storing integration-specific data. Stored in Entity Registry.
|
Field |
version_ids
|
---|---|
Type | EndDeviceVersionIdentifiers |
Description |
Version Identifiers. Stored in Entity Registry, Network Server and Application Server. |
Field |
service_profile_id
|
---|---|
Type | string |
Description |
Default service profile. Stored in Entity Registry.
|
Field |
network_server_address
|
---|---|
Type | string |
Description |
The address of the Network Server where this device is supposed to be registered. Stored in Entity Registry and Join Server. The typical format of the address is “host:port”. If the port is omitted, the normal port inference (with DNS lookup, otherwise defaults) is used. The connection shall be established with transport layer security (TLS). Custom certificate authorities may be configured out-of-band.
|
Field |
network_server_kek_label
|
---|---|
Type | string |
Description |
The KEK label of the Network Server to use for wrapping network session keys. Stored in Join Server.
|
Field |
application_server_address
|
---|---|
Type | string |
Description |
The address of the Application Server where this device is supposed to be registered. Stored in Entity Registry and Join Server. The typical format of the address is “host:port”. If the port is omitted, the normal port inference (with DNS lookup, otherwise defaults) is used. The connection shall be established with transport layer security (TLS). Custom certificate authorities may be configured out-of-band.
|
Field |
application_server_kek_label
|
---|---|
Type | string |
Description |
The KEK label of the Application Server to use for wrapping the application session key. Stored in Join Server.
|
Field |
application_server_id
|
---|---|
Type | string |
Description |
The AS-ID of the Application Server to use. Stored in Join Server.
|
Field |
join_server_address
|
---|---|
Type | string |
Description |
The address of the Join Server where this device is supposed to be registered. Stored in Entity Registry. The typical format of the address is “host:port”. If the port is omitted, the normal port inference (with DNS lookup, otherwise defaults) is used. The connection shall be established with transport layer security (TLS). Custom certificate authorities may be configured out-of-band.
|
Field |
locations
|
---|---|
Type | map of string to Location |
Description |
Location of the device. Stored in Entity Registry.
|
Field |
picture
|
---|---|
Type | Picture |
Description |
Stored in Entity Registry. |
Field |
supports_class_b
|
---|---|
Type | bool |
Description |
Whether the device supports class B. Copied on creation from template identified by version_ids, if any or from the home Network Server device profile, if any. |
Field |
supports_class_c
|
---|---|
Type | bool |
Description |
Whether the device supports class C. Copied on creation from template identified by version_ids, if any or from the home Network Server device profile, if any. |
Field |
lorawan_version
|
---|---|
Type | MACVersion |
Description |
LoRaWAN MAC version. Stored in Network Server. Copied on creation from template identified by version_ids, if any or from the home Network Server device profile, if any.
|
Field |
lorawan_phy_version
|
---|---|
Type | PHYVersion |
Description |
LoRaWAN PHY version. Stored in Network Server. Copied on creation from template identified by version_ids, if any or from the home Network Server device profile, if any.
|
Field |
frequency_plan_id
|
---|---|
Type | string |
Description |
ID of the frequency plan used by this device. Copied on creation from template identified by version_ids, if any or from the home Network Server device profile, if any.
|
Field |
min_frequency
|
---|---|
Type | uint64 |
Description |
Minimum frequency the device is capable of using (Hz). Stored in Network Server. Copied on creation from template identified by version_ids, if any or from the home Network Server device profile, if any. |
Field |
max_frequency
|
---|---|
Type | uint64 |
Description |
Maximum frequency the device is capable of using (Hz). Stored in Network Server. Copied on creation from template identified by version_ids, if any or from the home Network Server device profile, if any. |
Field |
supports_join
|
---|---|
Type | bool |
Description |
The device supports join (it’s OTAA). Copied on creation from template identified by version_ids, if any or from the home Network Server device profile, if any. |
Field |
resets_join_nonces
|
---|---|
Type | bool |
Description |
Whether the device resets the join and dev nonces (not LoRaWAN compliant). Stored in Join Server. Copied on creation from template identified by version_ids, if any or from the home Network Server device profile, if any. |
Field |
root_keys
|
---|---|
Type | RootKeys |
Description |
Device root keys. Stored in Join Server. |
Field |
net_id
|
---|---|
Type | bytes |
Description |
Home NetID. Stored in Join Server. |
Field |
mac_settings
|
---|---|
Type | MACSettings |
Description |
Settings for how the Network Server handles MAC layer for this device. Stored in Network Server. |
Field |
mac_state
|
---|---|
Type | MACState |
Description |
MAC state of the device. Stored in Network Server. |
Field |
pending_mac_state
|
---|---|
Type | MACState |
Description |
Pending MAC state of the device. Stored in Network Server. |
Field |
session
|
---|---|
Type | Session |
Description |
Current session of the device. Stored in Network Server and Application Server. |
Field |
pending_session
|
---|---|
Type | Session |
Description |
Pending session. Stored in Network Server and Application Server until RekeyInd is received. |
Field |
last_dev_nonce
|
---|---|
Type | uint32 |
Description |
Last DevNonce used. This field is only used for devices using LoRaWAN version 1.1 and later. Stored in Join Server. |
Field |
used_dev_nonces
|
---|---|
Type | repeated uint32 |
Description |
Used DevNonces sorted in ascending order. This field is only used for devices using LoRaWAN versions preceding 1.1. Stored in Join Server. |
Field |
last_join_nonce
|
---|---|
Type | uint32 |
Description |
Last JoinNonce/AppNonce(for devices using LoRaWAN versions preceding 1.1) used. Stored in Join Server. |
Field |
last_rj_count_0
|
---|---|
Type | uint32 |
Description |
Last Rejoin counter value used (type 0/2). Stored in Join Server. |
Field |
last_rj_count_1
|
---|---|
Type | uint32 |
Description |
Last Rejoin counter value used (type 1). Stored in Join Server. |
Field |
last_dev_status_received_at
|
---|---|
Type | google.protobuf.Timestamp |
Description |
Time when last DevStatus MAC command was received. Stored in Network Server. |
Field |
power_state
|
---|---|
Type | PowerState |
Description |
The power state of the device; whether it is battery-powered or connected to an external power source. Received via the DevStatus MAC command at status_received_at. Stored in Network Server.
|
Field |
battery_percentage
|
---|---|
Type | google.protobuf.FloatValue |
Description |
Latest-known battery percentage of the device. Received via the DevStatus MAC command at last_dev_status_received_at or earlier. Stored in Network Server.
|
Field |
downlink_margin
|
---|---|
Type | int32 |
Description |
Demodulation signal-to-noise ratio (dB). Received via the DevStatus MAC command at last_dev_status_received_at. Stored in Network Server. |
Field |
queued_application_downlinks
|
---|---|
Type | repeated ApplicationDownlink |
Description |
Queued Application downlink messages. Stored in Application Server, which sets them on the Network Server. This field is deprecated and is always set equal to session.queued_application_downlinks. |
Field |
formatters
|
---|---|
Type | MessagePayloadFormatters |
Description |
The payload formatters for this end device. Stored in Application Server. Copied on creation from template identified by version_ids. |
Field |
provisioner_id
|
---|---|
Type | string |
Description |
ID of the provisioner. Stored in Join Server.
|
Field |
provisioning_data
|
---|---|
Type | google.protobuf.Struct |
Description |
Vendor-specific provisioning data. Stored in Join Server. |
Field |
multicast
|
---|---|
Type | bool |
Description |
Indicates whether this device represents a multicast group. |
Field |
claim_authentication_code
|
---|---|
Type | EndDeviceAuthenticationCode |
Description |
Authentication code to claim ownership of the end device. Stored in Join Server. |
Field |
skip_payload_crypto
|
---|---|
Type | bool |
Description |
Skip decryption of uplink payloads and encryption of downlink payloads. This field is deprecated, use skip_payload_crypto_override instead. |
Field |
skip_payload_crypto_override
|
---|---|
Type | google.protobuf.BoolValue |
Description |
Skip decryption of uplink payloads and encryption of downlink payloads. This field overrides the application-level setting. |
Show object example
{
"ids": {},
"created_at": "0001-01-01T00:00:00Z",
"updated_at": "0001-01-01T00:00:00Z",
"name": "",
"description": "",
"attributes": {},
"version_ids": {},
"service_profile_id": "",
"network_server_address": "",
"network_server_kek_label": "",
"application_server_address": "",
"application_server_kek_label": "",
"application_server_id": "",
"join_server_address": "",
"locations": {},
"picture": {},
"supports_class_b": false,
"supports_class_c": false,
"lorawan_version": "MAC_UNKNOWN",
"lorawan_phy_version": "PHY_UNKNOWN",
"frequency_plan_id": "",
"min_frequency": 0,
"max_frequency": 0,
"supports_join": false,
"resets_join_nonces": false,
"root_keys": {},
"net_id": "",
"mac_settings": {},
"mac_state": {},
"pending_mac_state": {},
"session": {},
"pending_session": {},
"last_dev_nonce": 0,
"used_dev_nonces": [],
"last_join_nonce": 0,
"last_rj_count_0": 0,
"last_rj_count_1": 0,
"last_dev_status_received_at": "0001-01-01T00:00:00Z",
"power_state": "POWER_UNKNOWN",
"battery_percentage": null,
"downlink_margin": 0,
"queued_application_downlinks": [],
"formatters": {},
"provisioner_id": "",
"provisioning_data": {},
"multicast": false,
"claim_authentication_code": {},
"skip_payload_crypto": false,
"skip_payload_crypto_override": null,
}
Message EndDeviceAuthenticationCode
Authentication code for end devices.
Field |
value
|
---|---|
Type | string |
Description |
|
Field |
valid_from
|
---|---|
Type | google.protobuf.Timestamp |
Field |
valid_to
|
---|---|
Type | google.protobuf.Timestamp |
Show object example
{
"value": "",
"valid_from": "0001-01-01T00:00:00Z",
"valid_to": "0001-01-01T00:00:00Z",
}
Message EndDeviceIdentifiers
Field |
device_id
|
---|---|
Type | string |
Description |
|
Field |
application_ids
|
---|---|
Type | ApplicationIdentifiers |
Description |
|
Field |
dev_eui
|
---|---|
Type | bytes |
Description |
The LoRaWAN DevEUI. |
Field |
join_eui
|
---|---|
Type | bytes |
Description |
The LoRaWAN JoinEUI (AppEUI until LoRaWAN 1.0.3 end devices). |
Field |
dev_addr
|
---|---|
Type | bytes |
Description |
The LoRaWAN DevAddr. |
Show object example
{
"device_id": "",
"application_ids": {},
"dev_eui": "",
"join_eui": "",
"dev_addr": "",
}
Message EndDevices
Field |
end_devices
|
---|---|
Type | repeated EndDevice |
Description |
Show object example
{
"end_devices": [],
}
Message EndDeviceVersionIdentifiers
Identifies an end device model with version information.
Field |
brand_id
|
---|---|
Type | string |
Description |
|
Field |
model_id
|
---|---|
Type | string |
Description |
|
Field |
hardware_version
|
---|---|
Type | string |
Description |
|
Field |
firmware_version
|
---|---|
Type | string |
Description |
|
Field |
band_id
|
---|---|
Type | string |
Description |
|
Show object example
{
"brand_id": "",
"model_id": "",
"hardware_version": "",
"firmware_version": "",
"band_id": "",
}
Message GetEndDeviceRequest
Field |
end_device_ids
|
---|---|
Type | EndDeviceIdentifiers |
Description |
|
Field |
field_mask
|
---|---|
Type | google.protobuf.FieldMask |
Description |
The names of the end device fields that should be returned. See the API reference for which fields can be returned by the different services. |
Show object example
{
"end_device_ids": {},
"field_mask": {},
}
Message KeyEnvelope
Field |
key
|
---|---|
Type | bytes |
Description |
The unencrypted AES key. |
Field |
kek_label
|
---|---|
Type | string |
Description |
The label of the RFC 3394 key-encryption-key (KEK) that was used to encrypt the key.
|
Field |
encrypted_key
|
---|---|
Type | bytes |
Description |
|
Show object example
{
"key": "",
"kek_label": "",
"encrypted_key": "",
}
Message ListEndDevicesRequest
Field |
application_ids
|
---|---|
Type | ApplicationIdentifiers |
Description |
|
Field |
field_mask
|
---|---|
Type | google.protobuf.FieldMask |
Description |
The names of the end device fields that should be returned. See the API reference for which fields can be returned by the different services. |
Field |
order
|
---|---|
Type | string |
Description |
Order the results by this field path (must be present in the field mask). Default ordering is by ID. Prepend with a minus (-) to reverse the order.
|
Field |
limit
|
---|---|
Type | uint32 |
Description |
Limit the number of results per page.
|
Field |
page
|
---|---|
Type | uint32 |
Description |
Page number for pagination. 0 is interpreted as 1. |
Show object example
{
"application_ids": {},
"field_mask": {},
"order": "",
"limit": 0,
"page": 0,
}
Message MACParameters
MACParameters represent the parameters of the device’s MAC layer (active or desired). This is used internally by the Network Server.
Field |
max_eirp
|
---|---|
Type | float |
Description |
Maximum EIRP (dBm). |
Field |
adr_data_rate_index
|
---|---|
Type | DataRateIndex |
Description |
ADR: data rate index to use.
|
Field |
adr_tx_power_index
|
---|---|
Type | uint32 |
Description |
ADR: transmission power index to use.
|
Field |
adr_nb_trans
|
---|---|
Type | uint32 |
Description |
ADR: number of retransmissions.
|
Field |
adr_ack_limit
|
---|---|
Type | uint32 |
Description |
ADR: number of messages to wait before setting ADRAckReq. This field is deprecated, use adr_ack_limit_exponent instead. |
Field |
adr_ack_delay
|
---|---|
Type | uint32 |
Description |
ADR: number of messages to wait after setting ADRAckReq and before changing TxPower or DataRate. This field is deprecated, use adr_ack_delay_exponent instead. |
Field |
rx1_delay
|
---|---|
Type | RxDelay |
Description |
Rx1 delay (Rx2 delay is Rx1 delay + 1 second).
|
Field |
rx1_data_rate_offset
|
---|---|
Type | uint32 |
Description |
Data rate offset for Rx1.
|
Field |
rx2_data_rate_index
|
---|---|
Type | DataRateIndex |
Description |
Data rate index for Rx2.
|
Field |
rx2_frequency
|
---|---|
Type | uint64 |
Description |
Frequency for Rx2 (Hz).
|
Field |
max_duty_cycle
|
---|---|
Type | AggregatedDutyCycle |
Description |
Maximum uplink duty cycle (of all channels).
|
Field |
rejoin_time_periodicity
|
---|---|
Type | RejoinTimeExponent |
Description |
Time within which a rejoin-request must be sent.
|
Field |
rejoin_count_periodicity
|
---|---|
Type | RejoinCountExponent |
Description |
Message count within which a rejoin-request must be sent.
|
Field |
ping_slot_frequency
|
---|---|
Type | uint64 |
Description |
Frequency of the class B ping slot (Hz).
|
Field |
ping_slot_data_rate_index
|
---|---|
Type | DataRateIndex |
Description |
Data rate index of the class B ping slot. This field is deprecated, use ping_slot_data_rate_index_value instead. |
Field |
beacon_frequency
|
---|---|
Type | uint64 |
Description |
Frequency of the class B beacon (Hz).
|
Field |
channels
|
---|---|
Type | repeated MACParameters.Channel |
Description |
Configured uplink channels and optionally Rx1 frequency.
|
Field |
uplink_dwell_time
|
---|---|
Type | google.protobuf.BoolValue |
Description |
Whether uplink dwell time is set (400ms). If this field is not set, then the value is either unknown or irrelevant(Network Server cannot modify it). |
Field |
downlink_dwell_time
|
---|---|
Type | google.protobuf.BoolValue |
Description |
Whether downlink dwell time is set (400ms). If this field is not set, then the value is either unknown or irrelevant(Network Server cannot modify it). |
Field |
adr_ack_limit_exponent
|
---|---|
Type | ADRAckLimitExponentValue |
Description |
ADR: number of messages to wait before setting ADRAckReq. |
Field |
adr_ack_delay_exponent
|
---|---|
Type | ADRAckDelayExponentValue |
Description |
ADR: number of messages to wait after setting ADRAckReq and before changing TxPower or DataRate. |
Field |
ping_slot_data_rate_index_value
|
---|---|
Type | DataRateIndexValue |
Description |
Data rate index of the class B ping slot. |
Show object example
{
"max_eirp": 0,
"adr_data_rate_index": "DATA_RATE_0",
"adr_tx_power_index": 0,
"adr_nb_trans": 0,
"adr_ack_limit": 0,
"adr_ack_delay": 0,
"rx1_delay": "RX_DELAY_0",
"rx1_data_rate_offset": 0,
"rx2_data_rate_index": "DATA_RATE_0",
"rx2_frequency": 0,
"max_duty_cycle": "DUTY_CYCLE_1",
"rejoin_time_periodicity": "REJOIN_TIME_0",
"rejoin_count_periodicity": "REJOIN_COUNT_16",
"ping_slot_frequency": 0,
"ping_slot_data_rate_index": "DATA_RATE_0",
"beacon_frequency": 0,
"channels": [],
"uplink_dwell_time": null,
"downlink_dwell_time": null,
"adr_ack_limit_exponent": {},
"adr_ack_delay_exponent": {},
"ping_slot_data_rate_index_value": {},
}
Message MACSettings
Field |
class_b_timeout
|
---|---|
Type | google.protobuf.Duration |
Description |
Maximum delay for the device to answer a MAC request or a confirmed downlink frame. If unset, the default value from Network Server configuration will be used. |
Field |
ping_slot_periodicity
|
---|---|
Type | PingSlotPeriodValue |
Description |
Periodicity of the class B ping slot. If unset, the default value from Network Server configuration will be used. |
Field |
ping_slot_data_rate_index
|
---|---|
Type | DataRateIndexValue |
Description |
Data rate index of the class B ping slot. If unset, the default value from Network Server configuration will be used. |
Field |
ping_slot_frequency
|
---|---|
Type | google.protobuf.UInt64Value |
Description |
Frequency of the class B ping slot (Hz). If unset, the default value from Network Server configuration will be used.
|
Field |
beacon_frequency
|
---|---|
Type | google.protobuf.UInt64Value |
Description |
Frequency of the class B beacon (Hz). If unset, the default value from Network Server configuration will be used.
|
Field |
class_c_timeout
|
---|---|
Type | google.protobuf.Duration |
Description |
Maximum delay for the device to answer a MAC request or a confirmed downlink frame. If unset, the default value from Network Server configuration will be used. |
Field |
rx1_delay
|
---|---|
Type | RxDelayValue |
Description |
Class A Rx1 delay. If unset, the default value from Network Server configuration or regional parameters specification will be used. |
Field |
rx1_data_rate_offset
|
---|---|
Type | google.protobuf.UInt32Value |
Description |
Rx1 data rate offset. If unset, the default value from Network Server configuration will be used.
|
Field |
rx2_data_rate_index
|
---|---|
Type | DataRateIndexValue |
Description |
Data rate index for Rx2. If unset, the default value from Network Server configuration or regional parameters specification will be used. |
Field |
rx2_frequency
|
---|---|
Type | google.protobuf.UInt64Value |
Description |
Frequency for Rx2 (Hz). If unset, the default value from Network Server configuration or regional parameters specification will be used.
|
Field |
factory_preset_frequencies
|
---|---|
Type | repeated uint64 |
Description |
List of factory-preset frequencies. If unset, the default value from Network Server configuration or regional parameters specification will be used.
|
Field |
max_duty_cycle
|
---|---|
Type | AggregatedDutyCycleValue |
Description |
Maximum uplink duty cycle (of all channels). |
Field |
supports_32_bit_f_cnt
|
---|---|
Type | google.protobuf.BoolValue |
Description |
Whether the device supports 32-bit frame counters. If unset, the default value from Network Server configuration will be used. |
Field |
use_adr
|
---|---|
Type | google.protobuf.BoolValue |
Description |
Whether the Network Server should use ADR for the device. If unset, the default value from Network Server configuration will be used. |
Field |
adr_margin
|
---|---|
Type | google.protobuf.FloatValue |
Description |
The ADR margin tells the network server how much margin it should add in ADR requests. A bigger margin is less efficient, but gives a better chance of successful reception. If unset, the default value from Network Server configuration will be used. |
Field |
resets_f_cnt
|
---|---|
Type | google.protobuf.BoolValue |
Description |
Whether the device resets the frame counters (not LoRaWAN compliant). If unset, the default value from Network Server configuration will be used. |
Field |
status_time_periodicity
|
---|---|
Type | google.protobuf.Duration |
Description |
The interval after which a DevStatusReq MACCommand shall be sent. If unset, the default value from Network Server configuration will be used. |
Field |
status_count_periodicity
|
---|---|
Type | google.protobuf.UInt32Value |
Description |
Number of uplink messages after which a DevStatusReq MACCommand shall be sent. If unset, the default value from Network Server configuration will be used. |
Field |
desired_rx1_delay
|
---|---|
Type | RxDelayValue |
Description |
The Rx1 delay Network Server should configure device to use via MAC commands or Join-Accept. If unset, the default value from Network Server configuration or regional parameters specification will be used. |
Field |
desired_rx1_data_rate_offset
|
---|---|
Type | google.protobuf.UInt32Value |
Description |
The Rx1 data rate offset Network Server should configure device to use via MAC commands or Join-Accept. If unset, the default value from Network Server configuration will be used. |
Field |
desired_rx2_data_rate_index
|
---|---|
Type | DataRateIndexValue |
Description |
The Rx2 data rate index Network Server should configure device to use via MAC commands or Join-Accept. If unset, the default value from frequency plan, Network Server configuration or regional parameters specification will be used. |
Field |
desired_rx2_frequency
|
---|---|
Type | google.protobuf.UInt64Value |
Description |
The Rx2 frequency index Network Server should configure device to use via MAC commands. If unset, the default value from frequency plan, Network Server configuration or regional parameters specification will be used.
|
Field |
desired_max_duty_cycle
|
---|---|
Type | AggregatedDutyCycleValue |
Description |
The maximum uplink duty cycle (of all channels) Network Server should configure device to use via MAC commands. If unset, the default value from Network Server configuration will be used. |
Field |
desired_adr_ack_limit_exponent
|
---|---|
Type | ADRAckLimitExponentValue |
Description |
The ADR ACK limit Network Server should configure device to use via MAC commands. If unset, the default value from Network Server configuration or regional parameters specification will be used. |
Field |
desired_adr_ack_delay_exponent
|
---|---|
Type | ADRAckDelayExponentValue |
Description |
The ADR ACK delay Network Server should configure device to use via MAC commands. If unset, the default value from Network Server configuration or regional parameters specification will be used. |
Field |
desired_ping_slot_data_rate_index
|
---|---|
Type | DataRateIndexValue |
Description |
The data rate index of the class B ping slot Network Server should configure device to use via MAC commands. If unset, the default value from Network Server configuration will be used. |
Field |
desired_ping_slot_frequency
|
---|---|
Type | google.protobuf.UInt64Value |
Description |
The frequency of the class B ping slot (Hz) Network Server should configure device to use via MAC commands. If unset, the default value from Network Server configuration or regional parameters specification will be used.
|
Field |
desired_beacon_frequency
|
---|---|
Type | google.protobuf.UInt64Value |
Description |
The frequency of the class B beacon (Hz) Network Server should configure device to use via MAC commands. If unset, the default value from Network Server configuration will be used.
|
Show object example
{
"class_b_timeout": "0s",
"ping_slot_periodicity": {},
"ping_slot_data_rate_index": {},
"ping_slot_frequency": null,
"beacon_frequency": null,
"class_c_timeout": "0s",
"rx1_delay": {},
"rx1_data_rate_offset": null,
"rx2_data_rate_index": {},
"rx2_frequency": null,
"factory_preset_frequencies": [],
"max_duty_cycle": {},
"supports_32_bit_f_cnt": null,
"use_adr": null,
"adr_margin": null,
"resets_f_cnt": null,
"status_time_periodicity": "0s",
"status_count_periodicity": null,
"desired_rx1_delay": {},
"desired_rx1_data_rate_offset": null,
"desired_rx2_data_rate_index": {},
"desired_rx2_frequency": null,
"desired_max_duty_cycle": {},
"desired_adr_ack_limit_exponent": {},
"desired_adr_ack_delay_exponent": {},
"desired_ping_slot_data_rate_index": {},
"desired_ping_slot_frequency": null,
"desired_beacon_frequency": null,
}
Message MACState
MACState represents the state of MAC layer of the device. MACState is reset on each join for OTAA or ResetInd for ABP devices. This is used internally by the Network Server.
Field |
current_parameters
|
---|---|
Type | MACParameters |
Description |
Current LoRaWAN MAC parameters.
|
Field |
desired_parameters
|
---|---|
Type | MACParameters |
Description |
Desired LoRaWAN MAC parameters.
|
Field |
device_class
|
---|---|
Type | Class |
Description |
Currently active LoRaWAN device class
|
Field |
lorawan_version
|
---|---|
Type | MACVersion |
Description |
LoRaWAN MAC version.
|
Field |
last_confirmed_downlink_at
|
---|---|
Type | google.protobuf.Timestamp |
Description |
Time when the last confirmed downlink message or MAC command was scheduled. |
Field |
last_dev_status_f_cnt_up
|
---|---|
Type | uint32 |
Description |
Frame counter value of last uplink containing DevStatusAns. |
Field |
ping_slot_periodicity
|
---|---|
Type | PingSlotPeriodValue |
Description |
Periodicity of the class B ping slot. |
Field |
pending_application_downlink
|
---|---|
Type | ApplicationDownlink |
Description |
A confirmed application downlink, for which an acknowledgment is expected to arrive. |
Field |
queued_responses
|
---|---|
Type | repeated MACCommand |
Description |
Queued MAC responses. Regenerated on each uplink. |
Field |
pending_requests
|
---|---|
Type | repeated MACCommand |
Description |
Pending MAC requests(i.e. sent requests, for which no response has been received yet). Regenerated on each downlink. |
Field |
queued_join_accept
|
---|---|
Type | MACState.JoinAccept |
Description |
Queued join-accept. Set each time a (re-)join request accept is received from Join Server and removed each time a downlink is scheduled. |
Field |
pending_join_request
|
---|---|
Type | MACState.JoinRequest |
Description |
Pending join request. Set each time a join-accept is scheduled and removed each time an uplink is received from the device. |
Field |
rx_windows_available
|
---|---|
Type | bool |
Description |
Whether or not Rx windows are expected to be open. Set to true every time an uplink is received. Set to false every time a successful downlink scheduling attempt is made. |
Field |
recent_uplinks
|
---|---|
Type | repeated UplinkMessage |
Description |
Recent data uplink messages sorted by time. The number of messages stored may depend on configuration. |
Field |
recent_downlinks
|
---|---|
Type | repeated DownlinkMessage |
Description |
Recent data downlink messages sorted by time. The number of messages stored may depend on configuration. |
Field |
last_network_initiated_downlink_at
|
---|---|
Type | google.protobuf.Timestamp |
Description |
Time when the last network-initiated downlink message was scheduled. |
Field |
rejected_adr_data_rate_indexes
|
---|---|
Type | repeated DataRateIndex |
Description |
ADR Data rate index values rejected by the device.
Reset each time
|
Field |
rejected_adr_tx_power_indexes
|
---|---|
Type | repeated uint32 |
Description |
ADR TX output power index values rejected by the device. Elements are sorted in ascending order.
|
Field |
rejected_frequencies
|
---|---|
Type | repeated uint64 |
Description |
Frequencies rejected by the device.
|
Field |
last_downlink_at
|
---|---|
Type | google.protobuf.Timestamp |
Description |
Time when the last downlink message was scheduled. |
Field |
rejected_data_rate_ranges
|
---|---|
Type | map of uint64 to MACState.DataRateRanges |
Description |
Data rate ranges rejected by the device per frequency. |
Field |
last_adr_change_f_cnt_up
|
---|---|
Type | uint32 |
Description |
Frame counter of uplink, which confirmed the last ADR parameter change. |
Show object example
{
"current_parameters": {},
"desired_parameters": {},
"device_class": "CLASS_A",
"lorawan_version": "MAC_UNKNOWN",
"last_confirmed_downlink_at": "0001-01-01T00:00:00Z",
"last_dev_status_f_cnt_up": 0,
"ping_slot_periodicity": {},
"pending_application_downlink": {},
"queued_responses": [],
"pending_requests": [],
"queued_join_accept": {},
"pending_join_request": {},
"rx_windows_available": false,
"recent_uplinks": [],
"recent_downlinks": [],
"last_network_initiated_downlink_at": "0001-01-01T00:00:00Z",
"rejected_adr_data_rate_indexes": [],
"rejected_adr_tx_power_indexes": [],
"rejected_frequencies": [],
"last_downlink_at": "0001-01-01T00:00:00Z",
"rejected_data_rate_ranges": {},
"last_adr_change_f_cnt_up": 0,
}
Message MessagePayloadFormatters
Field |
up_formatter
|
---|---|
Type | PayloadFormatter |
Description |
Payload formatter for uplink messages, must be set together with its parameter.
|
Field |
up_formatter_parameter
|
---|---|
Type | string |
Description |
Parameter for the up_formatter, must be set together. |
Field |
down_formatter
|
---|---|
Type | PayloadFormatter |
Description |
Payload formatter for downlink messages, must be set together with its parameter.
|
Field |
down_formatter_parameter
|
---|---|
Type | string |
Description |
Parameter for the down_formatter, must be set together. |
Show object example
{
"up_formatter": "FORMATTER_NONE",
"up_formatter_parameter": "",
"down_formatter": "FORMATTER_NONE",
"down_formatter_parameter": "",
}
Message RootKeys
Root keys for a LoRaWAN device. These are stored on the Join Server.
Field |
root_key_id
|
---|---|
Type | string |
Description |
Join Server issued identifier for the root keys.
|
Field |
app_key
|
---|---|
Type | KeyEnvelope |
Description |
The (encrypted) Application Key. |
Field |
nwk_key
|
---|---|
Type | KeyEnvelope |
Description |
The (encrypted) Network Key. |
Show object example
{
"root_key_id": "",
"app_key": {},
"nwk_key": {},
}
Message Session
Field |
dev_addr
|
---|---|
Type | bytes |
Description |
Device Address, issued by the Network Server or chosen by device manufacturer in case of testing range (beginning with 00-03). Known by Network Server, Application Server and Join Server. Owned by Network Server. |
Field |
keys
|
---|---|
Type | SessionKeys |
Description |
|
Field |
last_f_cnt_up
|
---|---|
Type | uint32 |
Description |
Last uplink frame counter value used. Network Server only. Application Server assumes the Network Server checked it. |
Field |
last_n_f_cnt_down
|
---|---|
Type | uint32 |
Description |
Last network downlink frame counter value used. Network Server only. |
Field |
last_a_f_cnt_down
|
---|---|
Type | uint32 |
Description |
Last application downlink frame counter value used. Application Server only. |
Field |
last_conf_f_cnt_down
|
---|---|
Type | uint32 |
Description |
Frame counter of the last confirmed downlink message sent. Network Server only. |
Field |
started_at
|
---|---|
Type | google.protobuf.Timestamp |
Description |
Time when the session started. Network Server only. |
Field |
queued_application_downlinks
|
---|---|
Type | repeated ApplicationDownlink |
Description |
Queued Application downlink messages. Stored in Application Server and Network Server. |
Show object example
{
"dev_addr": "",
"keys": {},
"last_f_cnt_up": 0,
"last_n_f_cnt_down": 0,
"last_a_f_cnt_down": 0,
"last_conf_f_cnt_down": 0,
"started_at": "0001-01-01T00:00:00Z",
"queued_application_downlinks": [],
}
Message SessionKeys
Session keys for a LoRaWAN session. Only the components for which the keys were meant, will have the key-encryption-key (KEK) to decrypt the individual keys.
Field |
session_key_id
|
---|---|
Type | bytes |
Description |
Join Server issued identifier for the session keys. This ID can be used to request the keys from the Join Server in case the are lost.
|
Field |
f_nwk_s_int_key
|
---|---|
Type | KeyEnvelope |
Description |
The (encrypted) Forwarding Network Session Integrity Key (or Network Session Key in 1.0 compatibility mode). This key is stored by the (forwarding) Network Server. |
Field |
s_nwk_s_int_key
|
---|---|
Type | KeyEnvelope |
Description |
The (encrypted) Serving Network Session Integrity Key. This key is stored by the (serving) Network Server. |
Field |
nwk_s_enc_key
|
---|---|
Type | KeyEnvelope |
Description |
The (encrypted) Network Session Encryption Key. This key is stored by the (serving) Network Server. |
Field |
app_s_key
|
---|---|
Type | KeyEnvelope |
Description |
The (encrypted) Application Session Key. This key is stored by the Application Server. |
Show object example
{
"session_key_id": "",
"f_nwk_s_int_key": {},
"s_nwk_s_int_key": {},
"nwk_s_enc_key": {},
"app_s_key": {},
}
Message SetEndDeviceRequest
Field |
end_device
|
---|---|
Type | EndDevice |
Description |
|
Field |
field_mask
|
---|---|
Type | google.protobuf.FieldMask |
Description |
The names of the end device fields that should be updated. See the API reference for which fields can be set on the different services. |
Show object example
{
"end_device": {},
"field_mask": {},
}
Message UpdateEndDeviceRequest
Field |
end_device
|
---|---|
Type | EndDevice |
Description |
|
Field |
field_mask
|
---|---|
Type | google.protobuf.FieldMask |
Description |
The names of the end device fields that should be updated. See the API reference for which fields can be set on the different services. |
Show object example
{
"end_device": {},
"field_mask": {},
}
Enums
Enum AggregatedDutyCycle
Name | Value | Description |
---|---|---|
DUTY_CYCLE_1 |
0 |
100%. |
DUTY_CYCLE_2 |
1 |
50%. |
DUTY_CYCLE_4 |
2 |
25%. |
DUTY_CYCLE_8 |
3 |
12.5%. |
DUTY_CYCLE_16 |
4 |
6.25%. |
DUTY_CYCLE_32 |
5 |
3.125%. |
DUTY_CYCLE_64 |
6 |
1.5625%. |
DUTY_CYCLE_128 |
7 |
Roughly 0.781%. |
DUTY_CYCLE_256 |
8 |
Roughly 0.390%. |
DUTY_CYCLE_512 |
9 |
Roughly 0.195%. |
DUTY_CYCLE_1024 |
10 |
Roughly 0.098%. |
DUTY_CYCLE_2048 |
11 |
Roughly 0.049%. |
DUTY_CYCLE_4096 |
12 |
Roughly 0.024%. |
DUTY_CYCLE_8192 |
13 |
Roughly 0.012%. |
DUTY_CYCLE_16384 |
14 |
Roughly 0.006%. |
DUTY_CYCLE_32768 |
15 |
Roughly 0.003%. |
Enum MACVersion
Name | Value | Description |
---|---|---|
MAC_UNKNOWN |
0 |
|
MAC_V1_0 |
1 |
|
MAC_V1_0_1 |
2 |
|
MAC_V1_0_2 |
3 |
|
MAC_V1_1 |
4 |
|
MAC_V1_0_3 |
5 |
|
MAC_V1_0_4 |
6 |
Enum PHYVersion
Name | Value | Description |
---|---|---|
PHY_UNKNOWN |
0 |
|
PHY_V1_0 |
1 |
|
PHY_V1_0_1 |
2 |
|
PHY_V1_0_2_REV_A |
3 |
|
PHY_V1_0_2_REV_B |
4 |
|
PHY_V1_1_REV_A |
5 |
|
PHY_V1_1_REV_B |
6 |
|
PHY_V1_0_3_REV_A |
7 |
Enum PowerState
Power state of the device.
Name | Value | Description |
---|---|---|
POWER_UNKNOWN |
0 |
|
POWER_BATTERY |
1 |
|
POWER_EXTERNAL |
2 |