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.
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 given by the field mask.
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 applications. See request message for details.
Request type ListEndDevicesRequest
Response type EndDevices
HTTP bindings

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

Method EndDeviceRegistry.Update
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
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 Type Description
end_device EndDevice

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 Type Description
ids EndDeviceIdentifiers

required

created_at google.protobuf.Timestamp
updated_at google.protobuf.Timestamp
name string

Friendly name of the device. Stored in Entity Registry.

max_len: 50

description string

Description of the device. Stored in Entity Registry.

max_len: 2000

attributes map of string to string

Attributes of the device. Stored in Entity Registry.

version_ids EndDeviceVersionIdentifiers

Version Identifiers. Stored in Entity Registry, Network Server and Application Server.

service_profile_id string

Default service profile. Stored in Entity Registry.

max_len: 64

network_server_address string

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})?$|^$

network_server_kek_label string

The KEK label of the Network Server to use for wrapping network session keys. Stored in Join Server.

max_len: 2048

application_server_address string

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})?$|^$

application_server_kek_label string

The KEK label of the Application Server to use for wrapping the application session key. Stored in Join Server.

max_len: 2048

application_server_id string

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

max_len: 100

join_server_address string

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})?$|^$

locations map of string to Location

Location of the device. Stored in Entity Registry.

picture Picture

Stored in Entity Registry.

supports_class_b bool

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.

supports_class_c bool

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.

lorawan_version MACVersion

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

lorawan_phy_version PHYVersion

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

frequency_plan_id string

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

min_frequency uint64

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.

max_frequency uint64

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.

supports_join bool

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.

resets_join_nonces bool

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.

root_keys RootKeys

Device root keys. Stored in Join Server.

net_id bytes

Home NetID. Stored in Join Server.

mac_settings MACSettings

Settings for how the Network Server handles MAC layer for this device. Stored in Network Server.

mac_state MACState

MAC state of the device. Stored in Network Server.

pending_mac_state MACState

Pending MAC state of the device. Stored in Network Server.

session Session

Current session of the device. Stored in Network Server and Application Server.

pending_session Session

Pending session. Stored in Network Server and Application Server until RekeyInd is received.

last_dev_nonce uint32

Last DevNonce used. This field is only used for devices using LoRaWAN version 1.1 and later. Stored in Join Server.

used_dev_nonces repeated uint32

Used DevNonces sorted in ascending order. This field is only used for devices using LoRaWAN versions preceding 1.1. Stored in Join Server.

last_join_nonce uint32

Last JoinNonce/AppNonce(for devices using LoRaWAN versions preceding 1.1) used. Stored in Join Server.

last_rj_count_0 uint32

Last Rejoin counter value used (type 0/2). Stored in Join Server.

last_rj_count_1 uint32

Last Rejoin counter value used (type 1). Stored in Join Server.

last_dev_status_received_at google.protobuf.Timestamp

Time when last DevStatus MAC command was received. Stored in Network Server.

power_state PowerState

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

battery_percentage google.protobuf.FloatValue

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

downlink_margin int32

Demodulation signal-to-noise ratio (dB). Received via the DevStatus MAC command at last_dev_status_received_at. Stored in Network Server.

recent_adr_uplinks repeated UplinkMessage

Recent uplink messages with ADR bit set to 1 sorted by time. Stored in Network Server. The field is reset each time an uplink message carrying MACPayload is received with ADR bit set to 0. The number of messages stored is in the range [0,20];

recent_uplinks repeated UplinkMessage

Recent uplink messages sorted by time. Stored in Network Server. The number of messages stored may depend on configuration.

recent_downlinks repeated DownlinkMessage

Recent downlink messages sorted by time. Stored in Network Server. The number of messages stored may depend on configuration.

queued_application_downlinks repeated ApplicationDownlink

Queued Application downlink messages. Stored in Application Server, which sets them on the Network Server.

formatters MessagePayloadFormatters

The payload formatters for this end device. Stored in Application Server. Copied on creation from template identified by version_ids.

provisioner_id string

ID of the provisioner. Stored in Join Server.

max_len: 36

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

provisioning_data google.protobuf.Struct

Vendor-specific provisioning data. Stored in Join Server.

multicast bool

Indicates whether this device represents a multicast group.

claim_authentication_code EndDeviceAuthenticationCode

Authentication code to claim ownership of the end device. Stored in Join Server.

skip_payload_crypto bool

Skip decryption of uplink payloads and encryption of downlink payloads.

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,
  "recent_adr_uplinks": [],
  "recent_uplinks": [],
  "recent_downlinks": [],
  "queued_application_downlinks": [],
  "formatters": {},
  "provisioner_id": "",
  "provisioning_data": {},
  "multicast": false,
  "claim_authentication_code": {},
  "skip_payload_crypto": false,
}

Message EndDeviceAuthenticationCode

Authentication code for end devices.

Field Type Description
value string

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

valid_from google.protobuf.Timestamp
valid_to google.protobuf.Timestamp
Show object example
{
  "value": "",
  "valid_from": "0001-01-01T00:00:00Z",
  "valid_to": "0001-01-01T00:00:00Z",
}

Message EndDeviceIdentifiers

Field Type Description
device_id string

max_len: 36

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

application_ids ApplicationIdentifiers

required

dev_eui bytes

The LoRaWAN DevEUI.

join_eui bytes

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

dev_addr bytes

The LoRaWAN DevAddr.

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

Message EndDevices

Field Type Description
end_devices repeated EndDevice
Show object example
{
  "end_devices": [],
}

Message EndDeviceVersionIdentifiers

Identifies an end device model with version information.

Field Type Description
brand_id string

max_len: 36

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

model_id string

max_len: 36

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

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

Message GetEndDeviceRequest

Field Type Description
end_device_ids EndDeviceIdentifiers

required

field_mask google.protobuf.FieldMask
Show object example
{
  "end_device_ids": {},
  "field_mask": {},
}

Message KeyEnvelope

Field Type Description
key bytes

The unencrypted AES key.

kek_label string

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

max_len: 2048

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

Message ListEndDevicesRequest

Field Type Description
application_ids ApplicationIdentifiers

required

field_mask google.protobuf.FieldMask
order string

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]

limit uint32

Limit the number of results per page.

lte: 1000

page uint32

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 Type Description
max_eirp float

Maximum EIRP (dBm).

adr_data_rate_index DataRateIndex

ADR: data rate index to use.

defined_only

adr_tx_power_index uint32

ADR: transmission power index to use.

lte: 15

adr_nb_trans uint32

ADR: number of retransmissions.

lte: 15

adr_ack_limit uint32

ADR: number of messages to wait before setting ADRAckReq. This field is deprecated, use adr_ack_limit_exponent instead.

adr_ack_delay uint32

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.

rx1_delay RxDelay

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

defined_only

rx1_data_rate_offset uint32

Data rate offset for Rx1.

lte: 7

rx2_data_rate_index DataRateIndex

Data rate index for Rx2.

defined_only

rx2_frequency uint64

Frequency for Rx2 (Hz).

gte: 100000

max_duty_cycle AggregatedDutyCycle

Maximum uplink duty cycle (of all channels).

defined_only

rejoin_time_periodicity RejoinTimeExponent

Time within which a rejoin-request must be sent.

defined_only

rejoin_count_periodicity RejoinCountExponent

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

defined_only

ping_slot_frequency uint64

Frequency of the class B ping slot (Hz).

gte: 100000

lte: 0

ping_slot_data_rate_index DataRateIndex

Data rate index of the class B ping slot. This field is deprecated, use ping_slot_data_rate_index_value instead.

beacon_frequency uint64

Frequency of the class B beacon (Hz).

gte: 100000

lte: 0

channels repeated MACParameters.Channel

Configured uplink channels and optionally Rx1 frequency.

min_items: 1

uplink_dwell_time google.protobuf.BoolValue

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

downlink_dwell_time google.protobuf.BoolValue

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

adr_ack_limit_exponent ADRAckLimitExponentValue

ADR: number of messages to wait before setting ADRAckReq.

adr_ack_delay_exponent ADRAckDelayExponentValue

ADR: number of messages to wait after setting ADRAckReq and before changing TxPower or DataRate.

ping_slot_data_rate_index_value DataRateIndexValue

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 Type Description
class_b_timeout google.protobuf.Duration

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.

ping_slot_periodicity PingSlotPeriodValue

Periodicity of the class B ping slot. If unset, the default value from Network Server configuration will be used.

ping_slot_data_rate_index DataRateIndexValue

Data rate index of the class B ping slot. If unset, the default value from Network Server configuration will be used.

ping_slot_frequency google.protobuf.UInt64Value

Frequency of the class B ping slot (Hz). If unset, the default value from Network Server configuration will be used.

gte: 100000

beacon_frequency google.protobuf.UInt64Value

Frequency of the class B beacon (Hz). If unset, the default value from Network Server configuration will be used.

gte: 100000

class_c_timeout google.protobuf.Duration

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.

rx1_delay RxDelayValue

Class A Rx1 delay. If unset, the default value from Network Server configuration or regional parameters specification will be used.

rx1_data_rate_offset google.protobuf.UInt32Value

Rx1 data rate offset. If unset, the default value from Network Server configuration will be used.

lte: 7

rx2_data_rate_index DataRateIndexValue

Data rate index for Rx2. If unset, the default value from Network Server configuration or regional parameters specification will be used.

rx2_frequency google.protobuf.UInt64Value

Frequency for Rx2 (Hz). If unset, the default value from Network Server configuration or regional parameters specification will be used.

gte: 100000

factory_preset_frequencies repeated uint64

List of factory-preset frequencies. If unset, the default value from Network Server configuration or regional parameters specification will be used.

max_duty_cycle AggregatedDutyCycleValue

Maximum uplink duty cycle (of all channels).

supports_32_bit_f_cnt google.protobuf.BoolValue

Whether the device supports 32-bit frame counters. If unset, the default value from Network Server configuration will be used.

use_adr google.protobuf.BoolValue

Whether the Network Server should use ADR for the device. If unset, the default value from Network Server configuration will be used.

adr_margin google.protobuf.FloatValue

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.

resets_f_cnt google.protobuf.BoolValue

Whether the device resets the frame counters (not LoRaWAN compliant). If unset, the default value from Network Server configuration will be used.

status_time_periodicity google.protobuf.Duration

The interval after which a DevStatusReq MACCommand shall be sent. If unset, the default value from Network Server configuration will be used.

status_count_periodicity google.protobuf.UInt32Value

Number of uplink messages after which a DevStatusReq MACCommand shall be sent. If unset, the default value from Network Server configuration will be used.

desired_rx1_delay RxDelayValue

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.

desired_rx1_data_rate_offset google.protobuf.UInt32Value

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.

desired_rx2_data_rate_index DataRateIndexValue

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.

desired_rx2_frequency google.protobuf.UInt64Value

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

desired_max_duty_cycle AggregatedDutyCycleValue

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.

desired_adr_ack_limit_exponent ADRAckLimitExponentValue

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.

desired_adr_ack_delay_exponent ADRAckDelayExponentValue

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.

desired_ping_slot_data_rate_index DataRateIndexValue

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.

desired_ping_slot_frequency google.protobuf.UInt64Value

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

desired_beacon_frequency google.protobuf.UInt64Value

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 and is read only.

Field Type Description
current_parameters MACParameters

Current LoRaWAN MAC parameters.

required

desired_parameters MACParameters

Desired LoRaWAN MAC parameters.

required

device_class Class

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

lorawan_version MACVersion

LoRaWAN MAC version.

defined_only

last_confirmed_downlink_at google.protobuf.Timestamp

Time when the last confirmed downlink message or MAC command was scheduled.

last_dev_status_f_cnt_up uint32

Frame counter value of last uplink containing DevStatusAns.

ping_slot_periodicity PingSlotPeriodValue

Periodicity of the class B ping slot.

pending_application_downlink ApplicationDownlink

A confirmed application downlink, for which an acknowledgment is expected to arrive.

queued_responses repeated MACCommand

Queued MAC responses. Regenerated on each uplink.

pending_requests repeated MACCommand

Pending MAC requests(i.e. sent requests, for which no response has been received yet). Regenerated on each downlink.

queued_join_accept MACState.JoinAccept

Queued join-accept. Set each time a (re-)join request accept is received from Join Server and removed each time a downlink is scheduled.

pending_join_request JoinRequest

Pending join request. Set each time a join accept is scheduled and removed each time an uplink is received from the device.

rx_windows_available bool

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.

recent_uplinks repeated UplinkMessage

Recent data uplink messages sorted by time. The number of messages stored may depend on configuration.

recent_downlinks repeated DownlinkMessage

Recent data downlink messages sorted by time. The number of messages stored may depend on configuration.

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": [],
}

Message MessagePayloadFormatters

Field Type Description
up_formatter PayloadFormatter

Payload formatter for uplink messages, must be set together with its parameter.

defined_only

up_formatter_parameter string

Parameter for the up_formatter, must be set together.

down_formatter PayloadFormatter

Payload formatter for downlink messages, must be set together with its parameter.

defined_only

down_formatter_parameter string

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 Type Description
root_key_id string

Join Server issued identifier for the root keys.

max_len: 2048

app_key KeyEnvelope

The (encrypted) Application Key.

nwk_key KeyEnvelope

The (encrypted) Network Key.

Show object example
{
  "root_key_id": "",
  "app_key": {},
  "nwk_key": {},
}

Message Session

Field Type Description
dev_addr bytes

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.

keys SessionKeys

required

last_f_cnt_up uint32

Last uplink frame counter value used. Network Server only. Application Server assumes the Network Server checked it.

last_n_f_cnt_down uint32

Last network downlink frame counter value used. Network Server only.

last_a_f_cnt_down uint32

Last application downlink frame counter value used. Application Server only.

last_conf_f_cnt_down uint32

Frame counter of the last confirmed downlink message sent. Network Server only.

started_at google.protobuf.Timestamp

Time when the session started. Network Server only.

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",
}

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 Type Description
session_key_id bytes

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

f_nwk_s_int_key KeyEnvelope

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.

s_nwk_s_int_key KeyEnvelope

The (encrypted) Serving Network Session Integrity Key. This key is stored by the (serving) Network Server.

nwk_s_enc_key KeyEnvelope

The (encrypted) Network Session Encryption Key. This key is stored by the (serving) Network Server.

app_s_key KeyEnvelope

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 Type Description
end_device EndDevice

required

field_mask google.protobuf.FieldMask
Show object example
{
  "end_device": {},
  "field_mask": {},
}

Message UpdateEndDeviceRequest

Field Type Description
end_device EndDevice

required

field_mask google.protobuf.FieldMask
Show object example
{
  "end_device": {},
  "field_mask": {},
}

Enums

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

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