Skip to main content

Создать устройство

Регистрирует устройство LoRaWAN на сервере. Устройство OTAA после этого само подключается к сети (join) по DevEUI и AppKey. Устройству ABP активация не нужна, но серверу нужно заранее знать его DevAddr и сессионные ключи — их передают в запросе.

Запрос и ответ: create_device_req → create_device_resp.
Доступ: только токен высокого уровня; устройство можно создать в любом приложении владельца. С токеном низкого уровня сервер ответит ошибкой 1.

Текущая версия ONS
  • application_eui не обязателен: без него устройство создаётся в приложении, к которому выполнено подключение.
  • adr_fix — номер DR или null, а не bool; seq_chk — число 0 или 1.
  • Кодов регионов 38 (0–37), а не 24, — см. Коды регионов.
  • В ответе down_queue повторяет значение из запроса, а не записанное на сервере, и есть лишнее поле active.

Запрос​

Поля без пометки «обязательно» можно не передавать.

ПолеТипОписание
cmdstringcreate_device_req
operation_idstringПроизвольная строка; сервер вернёт её в ответе — по ней сопоставляют запрос и ответ
devEuistringОбязательно. DevEUI устройства, 16 hex-символов. Регистр не важен; пробелы, : и - сервер убирает. Должен быть уникален на всём сервере
app_keystringОбязательно. AppKey, 32 hex-символа. Для OTAA — корневой ключ устройства: по нему сервер проверяет запрос на активацию. Для ABP сервер его не использует, но поле всё равно обязательно
tariff_codestringОбязательно. Код тарифа из get_tariffs_req
application_euistringAppEUI приложения, в котором нужно создать устройство, 16 hex-символов. По умолчанию — приложение, к которому выполнено подключение
activationuint8Способ активации: 0 — OTAA, 1 — ABP. По умолчанию 0
devAddrstringDevAddr, 8 hex-символов. Для ABP передайте адрес из прошивки устройства. Для OTAA поле не нужно: без него сервер выдаст свободный адрес, а при каждой активации всё равно назначит новый
nwks_keystringNwkSKey, 32 hex-символа. Для ABP передайте ключ из прошивки. Без поля сервер сгенерирует случайный ключ
apps_keystringAppSKey, 32 hex-символа. Для ABP передайте ключ из прошивки. Без поля сервер сгенерирует случайный ключ
regionuint8Код региона — частотного плана устройства, 0–37, см. Коды регионов. По умолчанию 6 (KZ865-868)
node_classuint8Класс LoRaWAN: 1 — A, 2 — B, 3 — C. По умолчанию 1. См. Классы устройств
rx_windowuint8Окно приёма для downlink: 1 — RX1, а если сервер не успевает к нему, то RX2; 2 — всегда RX2. По умолчанию 1
adrboolADR: сервер сам подбирает устройству скорость и мощность передачи. Работает, только если ADR включён и в самом устройстве. По умолчанию true
adr_intervaluint16Раз в сколько кадров uplink сервер пересчитывает скорость; 0 — не пересчитывает. По умолчанию 20
adr_minuint8Наименьший DR, ниже которого ADR не опустит скорость, 0–15. По умолчанию 0
adr_maxuint8Наибольший DR для ADR, 0–15. По умолчанию 5. См. «Что важно знать»
adr_fixuint8Фиксированный DR, 0–15: ADR держит эту скорость и наибольшую мощность. По умолчанию null — не задан
seq_upuint32Начальный счётчик кадров uplink (FCntUp). По умолчанию 0. Пригодится для устройства ABP, перенесённого с другого сервера; дальше счётчики ведёт сервер
seq_downuint32Начальный счётчик кадров downlink (FCntDown). По умолчанию 0
seq_chkuint8Проверка счётчика кадров: 0 — Strict, 1 — Relaxed. По умолчанию 0. Сервер сейчас значение только хранит
duty_cycleuint8По умолчанию 0. Сервер сейчас значение только хранит
down_queueuint8По умолчанию 0. Сервер сейчас значение только хранит
descriptionstringОписание, до 255 символов. По умолчанию пустая строка
latfloatШирота, WGS 84. Учитывается только вместе с lon
lonfloatДолгота, WGS 84. Учитывается только вместе с lat

Устройство OTAA в заданном приложении:

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

Устройство ABP класса C — адрес и сессионные ключи из прошивки:

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

Ответ​

ПолеТипОписание
cmdstringcreate_device_resp
operation_idstringЗначение из запроса
statusuint81 — устройство создано, 2 — ошибка
devEui, devAddr, application_euistringИдентификаторы созданного устройства, hex заглавными буквами. devAddr — переданный или выданный сервером
app_key, nwks_key, apps_keystringКлючи устройства, в том числе сгенерированные сервером
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_codeЗаписанные значения: из запроса или по умолчанию. Типы — как в запросе
down_queueuint8Значение из запроса; null, если поле не передано
activeboolПовторяет одноимённое поле запроса, обычно null. На создание не влияет
lat, lonfloatКоординаты; null, если не заданы
error_code, error_textuint8, stringТолько при ошибке, см. ниже

Ответ на первый запрос из примеров:

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

Ошибки​

error_codeerror_textЧто случилось
1Unauthorized accessЗапрос пришёл с токеном низкого уровня
2Required field is not filledНе указан devEui, app_key или tariff_code, либо application_eui передан пустым
3Data is filled in with an errordevEui, application_eui, devAddr или ключ неверного формата; lat или lon — не число; node_class не 1–3; region не 0–37
4Uniq failedНа сервере уже есть устройство с таким DevEUI или DevAddr — у любого владельца
5Application does not existsУ владельца нет приложения с таким application_eui или оно удалено
6Tariff does not existsНет действующего тарифа с кодом tariff_code
0Unexpected errorБаза отклонила значение — например, rx_window больше 2, отрицательный счётчик кадров, описание длиннее 255 символов, — или внутренняя ошибка сервера

Коды регионов​

Код задаёт частотный план устройства: каналы, окно RX2, допустимые скорости и размер кадра downlink. Подробнее — в разделе Частотные планы. Для US915 и AU915 указаны номера включённых каналов по спецификации LoRaWAN Regional Parameters.

КодРегионКаналы uplink, МГцRX2
0EU868.1, 868.3, 868.5869.525 МГц, DR0
1KZ_OLD864.5–865.3, 5 каналов865.6 МГц, DR0
2RU868.9, 869.1 и 864.1–864.9, 7 каналов869.1 МГц, DR0
3BY868.1, 868.3, 868.5869.525 МГц, DR0
4UA868.1, 868.3, 868.5869.525 МГц, DR0
5KG863-865863.7–864.5, 5 каналов869.1 МГц, DR0
6KZ865-868 — по умолчанию865.1–865.9, 5 каналов866.7 МГц, DR0
7EU863-870867.1–867.9 и 868.1–868.5, 8 каналов869.525 МГц, DR0
8KZ864-868864.5–865.9, 8 каналов866.7 МГц, DR0
9EU433433.175–434.775, 9 каналов434.665 МГц, DR0
10AS923-1923.2–924.6, 8 каналов — в текущей версии сервер не отправляет устройству или группе рассылки с этим кодом ни Join Accept, ни downlink; выбирайте код 11 или 13923.2 МГц, DR2
11AS923-2923.2–924.6, 8 каналов — в текущей версии сервера совпадает с AS923-1923.2 МГц, DR2
12AS923-3916.0–917.4, 8 каналов916.6 МГц, DR2
13AS923-4923.2–924.6, 8 каналов — в текущей версии сервера совпадает с AS923-1923.2 МГц, DR2
14KR920923.2–924.6, 8 каналов — в текущей версии сервера совпадает с AS923-1923.2 МГц, DR2
15US915-1каналы 0–7 и 64923.3 МГц, DR8
16US915-2каналы 8–15 и 65923.3 МГц, DR8
17US915-3каналы 16–23 и 66923.3 МГц, DR8
18US915-4каналы 24–31 и 67923.3 МГц, DR8
19US915-5каналы 32–39 и 68923.3 МГц, DR8
20US915-6каналы 40–47 и 69923.3 МГц, DR8
21US915-7каналы 48–55 и 70923.3 МГц, DR8
22US915-8каналы 0–7, 56–63 и 71923.3 МГц, DR8
23US915-9каналы 0–15, 64 и 65923.3 МГц, DR8
24AU915-1каналы 0–7 и 64923.3 МГц, DR8
25AU915-2каналы 8–15 и 65923.3 МГц, DR8
26AU915-3каналы 16–23 и 66923.3 МГц, DR8
27AU915-4каналы 24–31 и 67923.3 МГц, DR8
28AU915-5каналы 32–39 и 68923.3 МГц, DR8
29AU915-6каналы 40–47 и 69923.3 МГц, DR8
30AU915-7каналы 48–55 и 70923.3 МГц, DR8
31AU915-8каналы 56–63 и 71923.3 МГц, DR8
32AU915-9каналы 0–15, 64 и 65923.3 МГц, DR8
33UZ926926.4–927.8, 8 каналов926.2 МГц, DR2
34UZ927926.4–927.8, 8 каналов927.8 МГц, DR2
35KZ865-only865.1, 865.3, 865.5866.7 МГц, DR0
36IN865-867865.0625, 865.4025, 865.985866.55 МГц, DR2
37IN865+KZ865865.0625, 865.4025, 865.985 и 865.1–865.9, 8 каналов866.55 МГц, DR2

Что важно знать​

  • OTAA. При каждой активации сервер выдаёт устройству новый DevAddr и новые сессионные ключи и записывает их в карточку устройства. Поэтому devAddr, nwks_key и apps_key из ответа на создание действуют только до первой активации.
  • ABP. Сервер не проверяет, что для ABP переданы devAddr, nwks_key и apps_key: без них он сгенерирует случайные значения и не сможет разобрать uplink устройства. Передавайте все три поля из прошивки.
  • DevEUI уникален на всём сервере, а не только в приложении. Удалённое устройство DevEUI и DevAddr не занимает.
  • Устройство включили раньше, чем зарегистрировали. Если оно уже пыталось подключиться, сервер временно блокирует его запросы на активацию. Создание устройства снимает блокировку, и активация пройдёт со следующей попытки.
  • Не все поля проверяются. node_class и region сервер проверяет сам. Значения rx_window, adr_*, seq_*, duty_cycle и down_queue он не проверяет: недопустимое значение либо запишется как есть, либо база отклонит его с ошибкой 0.
  • adr_max сейчас не ограничивает ADR, если он меньше наибольшего DR частотного плана: сервер учитывает его, только когда он больше этого DR. Чтобы ограничить скорость, задайте adr_fix.

См. также​