Change device settings

Changes the settings of a registered device: keys, class, region code, ADR parameters, description, coordinates, application and tariff. The server looks up the device by DevEUI or DevAddr. Pass only the fields you want to change: the rest stay as they were.

The command changes the device record in the database but does not notify the network server about the changes — see "Good to know".

Request and response: update_device_req → update_device_resp.
Access: high access level token only; any device of the owner can be changed. With a low access level token the server responds with error 1.

Current ONS version

• Codes 7 (the tariff was already changed today) and 9 (device not found) from the v0.17 description are currently not returned: in both cases the server responds with code 0 without error_text.
• The server does not apply the values 0 and false — see "Good to know".
• The server accepts the tariff_code and active fields, which are not in the v0.17 request schema.

Request

Fields not marked as required may be omitted.

Field	Type	Description
cmd	string	update_device_req
operation_id	string	Any string; the server returns it in the response to match the request and the response
devEui	string	devEui or devAddr is required. Device DevEUI, 16 hex characters in upper case — the server compares case-sensitively. DevEUI cannot be changed
devAddr	string	devEui or devAddr is required. Device DevAddr, 8 hex characters in upper case. Used only for the lookup: this command cannot change DevAddr. If both fields are given, both must match
application_eui	string	Move the device to another application of the owner: application AppEUI, 16 hex characters in upper case
tariff_code	string	Change the tariff: a code from get_tariffs_req. For when it takes effect, see "Good to know"
app_key	string	AppKey, 32 hex characters
nwks_key	string	NwkSKey, 32 hex characters
apps_key	string	AppSKey, 32 hex characters
node_class	uint8	LoRaWAN class: 1 — A, 2 — B, 3 — C. The server does not validate the value
region	uint8	Region code 1–37, see Region codes. Code 0 is not applied. The server does not validate the code: with an unknown code the device stops being served
rx_window	uint8	Receive window for downlink: 1 — RX1, 2 — RX2
adr	bool	true only: this command cannot turn ADR off
adr_interval	uint16	How often the server recalculates the data rate, in uplink frames; from 1
adr_min, adr_max	uint8	DR limits for ADR, 1–15
adr_fix	uint8	Fixed DR, 1–15. Cannot be reset to null
seq_up, seq_down	uint32	Uplink and downlink frame counters, from 1
seq_chk	uint8	Frame counter check: 1 (Relaxed) only. The server currently only stores the value
activation	uint8	Activation method: 1 (ABP) only
duty_cycle, down_queue	uint8	From 1. The server currently only stores the values
description	string	Description, up to 255 characters. An empty string clears the description
lat, lon	float	New coordinates, WGS 84. Applied only together; coordinates cannot be cleared
active	bool	false — take the device out of service, as deletion does

{
    "cmd": "update_device_req",
    "operation_id": "rdk",
    "devEui": "7DA50BE8C74CE6DC",
    "application_eui": "6042366ED7A302CF",
    "app_key": "79AFAC4879C5A1E2BFEDF4A4E35C0C6B",
    "region": 2
}

Response

Field	Type	Description
cmd	string	update_device_resp
operation_id	string	Value from the request
status	uint8	1 — success, 2 — error
devEui, devAddr, application_eui, description, app_key, nwks_key, apps_key, node_class, rx_window, adr, adr_interval, adr_min, adr_max, adr_fix, duty_cycle, seq_up, seq_down, seq_chk, region, activation		Device record after the change — fields as in get_devices_req
down_queue, tariff_code, active		Values from the request; null if the field was not passed. tariff_code is not the current tariff of the device
lat, lon	float	Coordinates; null if not set
error_code, error_text	uint8, string	Only on error, see below

{
    "cmd": "update_device_resp",
    "operation_id": "rdk",
    "status": 1,
    "devEui": "7DA50BE8C74CE6DC",
    "devAddr": "2F1BA78D",
    "application_eui": "6042366ED7A302CF",
    "description": "",
    "app_key": "79AFAC4879C5A1E2BFEDF4A4E35C0C6B",
    "nwks_key": "FF93AB45868BC0ED652DB9A0698CCAD7",
    "apps_key": "B65466247DC7F5B5CCA383AD47233D86",
    "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": 118,
    "seq_down": 4,
    "seq_chk": 0,
    "region": 2,
    "activation": 0,
    "down_queue": null,
    "tariff_code": null,
    "active": null,
    "lon": 75.898052,
    "lat": 42.221848
}

Errors

error_code	error_text	What happened
1	Unauthorized access	The request came with a low access level token
2	Required field is not filled	Neither devEui nor devAddr is given
3	Data is filled in with an error	devEui, devAddr, application_eui or a key has an invalid format; lat or lon is not a number
5	Application does not exists	The owner has no application with this application_eui, or it is deleted
6	Tariff does not exists	There is no active tariff with the code tariff_code
0	—	The device is not found or belongs to another owner; the tariff was already changed and the new one has not taken effect yet; the database rejected a value, e.g. rx_window above 2; internal server error

Good to know

• The network server learns about the changes later. It keeps in memory the settings of a device that is currently online. Editing the device in the ONS interface resets them; this command does not. An OTAA device gets the new keys, region code, class, receive window, ADR parameters and application on its next join. The network server may keep serving an ABP device with the old settings: to apply the new ones right away, save the device in the ONS interface.
• 0 and false are not applied. The server changes only fields with a non-empty value and silently skips 0 and false, and the response is still successful. The exceptions are description, where an empty string clears the description, and active, where false is applied. So this command cannot turn ADR off, set DR0, reset the frame counters to zero, or restore seq_chk = 0, OTAA (activation = 0) or region code 0 (EU). Resetting adr_fix to null and clearing coordinates are not possible either. Make such changes in the ONS interface.
• Keys. For an OTAA device app_key is used on the next join: if the device has a different AppKey, it will not be able to rejoin. The server overwrites nwks_key and apps_key of an OTAA device on its next join. For an ABP device the keys must match the ones in the device firmware.
• Region code and class must match the device firmware. The server validates them only when the device is created; here it stores them as is.
• Tariff. If the device already has a tariff, the new one takes effect at 00:00 UTC of the next day. Until it takes effect, the tariff cannot be changed again — the server responds with error 0. If the device has no tariff, the new one takes effect right away. Passing the code of the current tariff changes nothing.
• active: false takes the device out of service as delete_device_req does: get_devices_req, update_device_req and delete_device_req no longer find it, and its DevEUI and DevAddr can be reused. This command cannot bring the device back.

See also

• create_device_req — all device fields and region codes.
• get_devices_req — device record.
• delete_device_req — delete a device.