Get a device record

Returns a device record: identifiers, keys, class, region code, ADR parameters, frame counters and coordinates. Use it to check how the device is registered on the server and to find out its current DevAddr: an OTAA device gets a new one on every join.

Request and response: get_devices_req → get_devices_resp.
Access: a low access level token sees the devices of its application and of applications that granted it access; a high access level token sees all devices of the owner.

Current ONS version

The server returns at most one device. Without devEui the response holds one arbitrary available device, not all of them as in the v0.17 description. Request devices one at a time, by devEui. The record has an active field that is not in v0.17.

Request

Fields not marked as required may be omitted.

Field	Type	Description
cmd	string	get_devices_req
operation_id	string	Any string; the server returns it in the response to match the request and the response
devEui	string	Device DevEUI, 16 hex characters in upper case — the server compares case-sensitively. Without the field the server returns one arbitrary device

{
    "cmd": "get_devices_req",
    "operation_id": "Qlg",
    "devEui": "D745F677B2412E03"
}

Response

Field	Type	Description
cmd	string	get_devices_resp
operation_id	string	Value from the request
status	uint8	1 — success, 2 — error
deviceCount	uint32	Number of devices in the list: 0 or 1
deviceList	array	Device records; their fields are in the table below
error_code, error_text	uint8, string	Only on error, see below

Record fields:

Field	Type	Description
devEui	string	DevEUI
devAddr	string	DevAddr. For an OTAA device, the address assigned on the last join
application_eui	string	AppEUI of the device application
description	string	Description; may be null
app_key	string	AppKey
nwks_key, apps_key	string	NwkSKey and AppSKey. For an OTAA device, the keys of the current session
node_class	uint8	LoRaWAN class: 1 — A, 2 — B, 3 — C
rx_window	uint8	Receive window for downlink: 1 — RX1, 2 — RX2
adr	bool	Whether ADR is on
adr_interval	uint16	How often the server recalculates the data rate, in uplink frames
adr_min, adr_max	uint8	DR limits for ADR; null — not set
adr_fix	uint8	Fixed DR; null — not set
duty_cycle	uint8	The server currently only stores the value
seq_up, seq_down	uint32	Uplink and downlink frame counters (FCntUp, FCntDown)
seq_chk	uint8	Frame counter check: 0 — Strict, 1 — Relaxed
region	uint8	Region code, see Region codes
activation	uint8	Activation method: 0 — OTAA, 1 — ABP
active	bool	Always true: the server does not return deleted devices
lat, lon	float	Latitude and longitude, WGS 84; null if no coordinates are set

{
    "cmd": "get_devices_resp",
    "operation_id": "Qlg",
    "status": 1,
    "deviceList": [
        {
            "devEui": "D745F677B2412E03",
            "devAddr": "D1FD37F0",
            "application_eui": "819EA8554FCD762A",
            "description": "",
            "app_key": "2B7E151628AED2A6ABF7158809CF4F3C",
            "nwks_key": "D745F677B2412E03268C11F3E1B6893C",
            "apps_key": "2D48A7ECFF70AF6323B7A57186C23E11",
            "node_class": 1,
            "rx_window": 1,
            "adr": true,
            "adr_interval": 20,
            "adr_min": 0,
            "adr_max": 5,
            "adr_fix": null,
            "duty_cycle": 0,
            "seq_up": 352,
            "seq_down": 7,
            "seq_chk": 0,
            "region": 6,
            "activation": 0,
            "active": true,
            "lat": 45.234232,
            "lon": 76.342534
        }
    ],
    "deviceCount": 1
}

Errors

error_code	error_text	What happened
3	Data is filled in with an error	devEui is not 16 hex characters
0	—	Internal server error — retry later

A device that does not exist or is not available with your token is not treated as an error: the response comes with deviceCount = 0. The server responds the same way to a devEui in lower case.

Good to know

• The response holds the device keys in clear text — including for requests with a low access level token. Do not write the response to public logs.
• The tariff and down_queue are not in the record. The tariff is set in create_device_req and changed in update_device_req.

See also

• create_device_req — what the fields and region codes mean.
• update_device_req — change device settings.
• get_device_coordinates_req — device coordinates only.