Skip to main content

Create device

Registers a LoRaWAN device on the server. An OTAA device then joins the network by itself using its DevEUI and AppKey. An ABP device does not join, but the server must know its DevAddr and session keys in advance — they are passed in the request.

Request and response: create_device_req → create_device_resp.
Access: high access level token only; a device can be created in any application of the owner. With a low access level token the server responds with error 1.

Current ONS version
  • application_eui is not required: without it the device is created in the application you are connected to.
  • adr_fix is a DR number or null, not a bool; seq_chk is a number, 0 or 1.
  • There are 38 region codes (0–37), not 24 — see Region codes.
  • In the response down_queue repeats the request value rather than the stored one, and there is an extra active field.

Request​

Fields not marked as required may be omitted.

FieldTypeDescription
cmdstringcreate_device_req
operation_idstringAny string; the server returns it in the response to match the request and the response
devEuistringRequired. Device DevEUI, 16 hex characters. Case does not matter; the server strips spaces, : and -. Must be unique across the whole server
app_keystringRequired. AppKey, 32 hex characters. For OTAA it is the device root key: the server checks join requests with it. For ABP the server does not use it, but the field is still required
tariff_codestringRequired. Tariff code from get_tariffs_req
application_euistringAppEUI of the application to create the device in, 16 hex characters. Default — the application you are connected to
activationuint8Activation method: 0 — OTAA, 1 — ABP. Default 0
devAddrstringDevAddr, 8 hex characters. For ABP pass the address from the device firmware. For OTAA the field is not needed: without it the server assigns a free address, and it assigns a new one on every join anyway
nwks_keystringNwkSKey, 32 hex characters. For ABP pass the key from the firmware. Without the field the server generates a random key
apps_keystringAppSKey, 32 hex characters. For ABP pass the key from the firmware. Without the field the server generates a random key
regionuint8Region code — the device frequency plan, 0–37, see Region codes. Default 6 (KZ865-868)
node_classuint8LoRaWAN class: 1 — A, 2 — B, 3 — C. Default 1. See Device classes
rx_windowuint8Receive window for downlink: 1 — RX1, or RX2 if the server cannot make it to RX1; 2 — always RX2. Default 1
adrboolADR: the server chooses the device data rate and transmit power. Works only if ADR is enabled in the device too. Default true
adr_intervaluint16How often the server recalculates the data rate, in uplink frames; 0 — never. Default 20
adr_minuint8Lowest DR that ADR may lower the data rate to, 0–15. Default 0
adr_maxuint8Highest DR for ADR, 0–15. Default 5. See "Good to know"
adr_fixuint8Fixed DR, 0–15: ADR keeps this data rate and the highest power. Default null — not set
seq_upuint32Initial uplink frame counter (FCntUp). Default 0. Useful for an ABP device moved from another server; after that the server maintains the counters
seq_downuint32Initial downlink frame counter (FCntDown). Default 0
seq_chkuint8Frame counter check: 0 — Strict, 1 — Relaxed. Default 0. The server currently only stores the value
duty_cycleuint8Default 0. The server currently only stores the value
down_queueuint8Default 0. The server currently only stores the value
descriptionstringDescription, up to 255 characters. Default — empty string
latfloatLatitude, WGS 84. Applied only together with lon
lonfloatLongitude, WGS 84. Applied only together with lat

An OTAA device in a given application:

{
    "cmd": "create_device_req",
    "operation_id": "rnt",
    "devEui": "7DA50BE8C74CE6DC",
    "application_eui": "819EA8554FCD762A",
    "app_key": "948205A2939E8C999D641DE5CB731861",
    "tariff_code": "A1"
}

A class C ABP device — address and session keys from the firmware:

{
    "cmd": "create_device_req",
    "operation_id": "abp1",
    "devEui": "7DA50BE8C74CE6DD",
    "app_key": "948205A2939E8C999D641DE5CB731861",
    "tariff_code": "A1",
    "activation": 1,
    "devAddr": "26011F4A",
    "nwks_key": "EEFBF983C00B35240C9A7C2D8D011301",
    "apps_key": "6F17B97CEA2C63D1089EF4268FD68D38",
    "node_class": 3,
    "region": 7
}

Response​

FieldTypeDescription
cmdstringcreate_device_resp
operation_idstringValue from the request
statusuint81 — the device is created, 2 — error
devEui, devAddr, application_euistringIdentifiers of the created device, hex in upper case. devAddr — the one passed or assigned by the server
app_key, nwks_key, apps_keystringDevice keys, including the ones generated by the server
description, node_class, rx_window, adr, adr_interval, adr_min, adr_max, adr_fix, duty_cycle, seq_up, seq_down, seq_chk, region, activation, tariff_codeStored values: from the request or defaults. Types as in the request
down_queueuint8Value from the request; null if the field was not passed
activeboolRepeats the request field of the same name, usually null. Does not affect creation
lat, lonfloatCoordinates; null if not set
error_code, error_textuint8, stringOnly on error, see below

Response to the first request example:

{
    "cmd": "create_device_resp",
    "operation_id": "rnt",
    "status": 1,
    "devEui": "7DA50BE8C74CE6DC",
    "devAddr": "41410509",
    "application_eui": "819EA8554FCD762A",
    "description": "",
    "app_key": "948205A2939E8C999D641DE5CB731861",
    "nwks_key": "A3C51F0E9D27B4686F02E1CB5D7390AA",
    "apps_key": "1B9E04D7C26A58F3E0B4719DA2C86E5F",
    "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": 0,
    "seq_down": 0,
    "seq_chk": 0,
    "region": 6,
    "activation": 0,
    "down_queue": null,
    "tariff_code": "A1",
    "active": null,
    "lon": null,
    "lat": null
}

Errors​

error_codeerror_textWhat happened
1Unauthorized accessThe request came with a low access level token
2Required field is not filleddevEui, app_key or tariff_code is missing, or application_eui is empty
3Data is filled in with an errordevEui, application_eui, devAddr or a key has an invalid format; lat or lon is not a number; node_class is not 1–3; region is not 0–37
4Uniq failedA device with this DevEUI or DevAddr already exists on the server — under any owner
5Application does not existsThe owner has no application with this application_eui, or it is deleted
6Tariff does not existsThere is no active tariff with the code tariff_code
0Unexpected errorThe database rejected a value — e.g. rx_window above 2, a negative frame counter, a description longer than 255 characters — or an internal server error occurred

Region codes​

The code sets the device frequency plan: channels, the RX2 window, allowed data rates and the downlink frame size. For details, see Frequency plans. For US915 and AU915, the table gives the numbers of the enabled channels as defined in the LoRaWAN Regional Parameters specification.

CodeRegionUplink channels, MHzRX2
0EU868.1, 868.3, 868.5869.525 MHz, DR0
1KZ_OLD864.5–865.3, 5 channels865.6 MHz, DR0
2RU868.9, 869.1 and 864.1–864.9, 7 channels869.1 MHz, DR0
3BY868.1, 868.3, 868.5869.525 MHz, DR0
4UA868.1, 868.3, 868.5869.525 MHz, DR0
5KG863-865863.7–864.5, 5 channels869.1 MHz, DR0
6KZ865-868 — default865.1–865.9, 5 channels866.7 MHz, DR0
7EU863-870867.1–867.9 and 868.1–868.5, 8 channels869.525 MHz, DR0
8KZ864-868864.5–865.9, 8 channels866.7 MHz, DR0
9EU433433.175–434.775, 9 channels434.665 MHz, DR0
10AS923-1923.2–924.6, 8 channels — in the current version the server sends neither a Join Accept nor a downlink to a device or multicast group with this code; use code 11 or 13923.2 MHz, DR2
11AS923-2923.2–924.6, 8 channels — same as AS923-1 in the current server version923.2 MHz, DR2
12AS923-3916.0–917.4, 8 channels916.6 MHz, DR2
13AS923-4923.2–924.6, 8 channels — same as AS923-1 in the current server version923.2 MHz, DR2
14KR920923.2–924.6, 8 channels — same as AS923-1 in the current server version923.2 MHz, DR2
15US915-1channels 0–7 and 64923.3 MHz, DR8
16US915-2channels 8–15 and 65923.3 MHz, DR8
17US915-3channels 16–23 and 66923.3 MHz, DR8
18US915-4channels 24–31 and 67923.3 MHz, DR8
19US915-5channels 32–39 and 68923.3 MHz, DR8
20US915-6channels 40–47 and 69923.3 MHz, DR8
21US915-7channels 48–55 and 70923.3 MHz, DR8
22US915-8channels 0–7, 56–63 and 71923.3 MHz, DR8
23US915-9channels 0–15, 64 and 65923.3 MHz, DR8
24AU915-1channels 0–7 and 64923.3 MHz, DR8
25AU915-2channels 8–15 and 65923.3 MHz, DR8
26AU915-3channels 16–23 and 66923.3 MHz, DR8
27AU915-4channels 24–31 and 67923.3 MHz, DR8
28AU915-5channels 32–39 and 68923.3 MHz, DR8
29AU915-6channels 40–47 and 69923.3 MHz, DR8
30AU915-7channels 48–55 and 70923.3 MHz, DR8
31AU915-8channels 56–63 and 71923.3 MHz, DR8
32AU915-9channels 0–15, 64 and 65923.3 MHz, DR8
33UZ926926.4–927.8, 8 channels926.2 MHz, DR2
34UZ927926.4–927.8, 8 channels927.8 MHz, DR2
35KZ865-only865.1, 865.3, 865.5866.7 MHz, DR0
36IN865-867865.0625, 865.4025, 865.985866.55 MHz, DR2
37IN865+KZ865865.0625, 865.4025, 865.985 and 865.1–865.9, 8 channels866.55 MHz, DR2

Good to know​

  • OTAA. On every join the server assigns the device a new DevAddr and new session keys and writes them into the device record. So the devAddr, nwks_key and apps_key from the creation response are valid only until the first join.
  • ABP. The server does not check that devAddr, nwks_key and apps_key are passed for ABP: without them it generates random values and cannot process the device uplinks. Pass all three fields from the firmware.
  • DevEUI is unique across the whole server, not only within the application. A deleted device does not occupy its DevEUI and DevAddr.
  • The device was powered on before it was registered. If it has already tried to join, the server temporarily blocks its join requests. Creating the device lifts the block, and the next join attempt goes through.
  • Not all fields are validated. The server validates node_class and region itself. It does not validate rx_window, adr_*, seq_*, duty_cycle and down_queue: an invalid value is either stored as is or rejected by the database with error 0.
  • adr_max currently does not limit ADR when it is below the highest DR of the frequency plan: the server takes it into account only when it is above that DR. To limit the data rate, set adr_fix.

See also​