End Device APIs

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

POST /api/v3/applications/{end_device.ids.application_ids.application_id}/devices

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

GET /api/v3/applications/{end_device_ids.application_ids.application_id}/devices/{end_device_ids.device_id}

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

GET /api/v3/applications/{application_ids.application_id}/devices

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

PUT /api/v3/applications/{end_device.ids.application_ids.application_id}/devices/{end_device.ids.device_id}

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

DELETE /api/v3/applications/{application_ids.application_id}/devices/{device_id}

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

PUT /api/v3/js/applications/{end_device.ids.application_ids.application_id}/devices/{end_device.ids.device_id}

POST /api/v3/js/applications/{end_device.ids.application_ids.application_id}/devices

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

GET /api/v3/js/applications/{end_device_ids.application_ids.application_id}/devices/{end_device_ids.device_id}

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

DELETE /api/v3/js/applications/{application_ids.application_id}/devices/{device_id}

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

PUT /api/v3/ns/applications/{end_device.ids.application_ids.application_id}/devices/{end_device.ids.device_id}

POST /api/v3/ns/applications/{end_device.ids.application_ids.application_id}/devices

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

GET /api/v3/ns/applications/{end_device_ids.application_ids.application_id}/devices/{end_device_ids.device_id}

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

DELETE /api/v3/ns/applications/{application_ids.application_id}/devices/{device_id}

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

PUT /api/v3/as/applications/{end_device.ids.application_ids.application_id}/devices/{end_device.ids.device_id}

POST /api/v3/as/applications/{end_device.ids.application_ids.application_id}/devices

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

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

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

DELETE /api/v3/as/applications/{application_ids.application_id}/devices/{device_id}

Messages

Message CreateEndDeviceRequest

Field end_device
Type EndDevice
Description

required

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

required

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.

max_len: 50

Field description
Type string
Description

Description of the device. Stored in Entity Registry.

max_len: 2000

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.

max_pairs: 10

max_len (key): 36

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

max_len (value): 200

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.

max_len: 64

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.

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

Field 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.

max_len: 2048

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.

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

Field 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.

max_len: 2048

Field application_server_id
Type string
Description

The AS-ID of the Application Server to use. Stored in Join Server.

max_len: 100

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.

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

Field locations
Type map of string to Location
Description

Location of the device. Stored in Entity Registry.

max_len (key): 36

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

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.

defined_only

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.

defined_only

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.

max_len: 64

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.

defined_only

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.

gte: 0

lte: 1

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.

max_len: 36

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

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

pattern: ^[A-Z0-9]{1,32}$

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

max_len: 36

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

Field application_ids
Type ApplicationIdentifiers
Description

required

Field dev_eui
Type bytes
Description

The LoRaWAN DevEUI.

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

max_len: 36

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

Field model_id
Type string
Description

max_len: 36

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

Field hardware_version
Type string
Description

max_len: 32

Field firmware_version
Type string
Description

max_len: 32

Field band_id
Type string
Description

max_len: 32

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

Message GetEndDeviceRequest

Field end_device_ids
Type EndDeviceIdentifiers
Description

required

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.

max_len: 2048

Field encrypted_key
Type bytes
Description

max_len: 1024

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

Message ListEndDevicesRequest

Field application_ids
Type ApplicationIdentifiers
Description

required

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.

in: [ device_id -device_id join_eui -join_eui dev_eui -dev_eui name -name description -description created_at -created_at]

Field limit
Type uint32
Description

Limit the number of results per page.

lte: 1000

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.

defined_only

Field adr_tx_power_index
Type uint32
Description

ADR: transmission power index to use.

lte: 15

Field adr_nb_trans
Type uint32
Description

ADR: number of retransmissions.

lte: 15

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).

defined_only

Field rx1_data_rate_offset
Type uint32
Description

Data rate offset for Rx1.

lte: 7

Field rx2_data_rate_index
Type DataRateIndex
Description

Data rate index for Rx2.

defined_only

Field rx2_frequency
Type uint64
Description

Frequency for Rx2 (Hz).

gte: 100000

Field max_duty_cycle
Type AggregatedDutyCycle
Description

Maximum uplink duty cycle (of all channels).

defined_only

Field rejoin_time_periodicity
Type RejoinTimeExponent
Description

Time within which a rejoin-request must be sent.

defined_only

Field rejoin_count_periodicity
Type RejoinCountExponent
Description

Message count within which a rejoin-request must be sent.

defined_only

Field ping_slot_frequency
Type uint64
Description

Frequency of the class B ping slot (Hz).

gte: 100000

lte: 0

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).

gte: 100000

lte: 0

Field channels
Type repeated MACParameters.Channel
Description

Configured uplink channels and optionally Rx1 frequency.

min_items: 1

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.

gte: 100000

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.

gte: 100000

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.

lte: 7

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.

gte: 100000

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.

max_items: 96

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.

gte: 100000

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.

gte: 100000

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.

gte: 100000

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.

required

Field desired_parameters
Type MACParameters
Description

Desired LoRaWAN MAC parameters.

required

Field device_class
Type Class
Description

Currently active LoRaWAN device class

  • Device class is A by default
  • If device sets ClassB bit in uplink, this will be set to B
  • If device sent DeviceModeInd MAC message, this will be set to that value

defined_only

Field lorawan_version
Type MACVersion
Description

LoRaWAN MAC version.

defined_only

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 current_parameters.channels change. Elements are sorted in ascending order.

max_items: 15

defined_only

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.

max_items: 15

lte: 15

Field rejected_frequencies
Type repeated uint64
Description

Frequencies rejected by the device.

gte: 100000

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.

defined_only

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.

defined_only

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.

max_len: 2048

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

required

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.

max_len: 2048

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

required

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

required

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