Добавить устройство в multicast-группу

Записывает устройство в состав multicast-группы. Это запись для учёта на сервере: самому устройству сервер ничего не передаёт и при отправке кадра состав группы не проверяет. Чтобы устройство принимало кадры группы, её адрес и ключи нужно записать в устройство отдельно — см. Как устройство узнаёт о группе.

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

Текущая версия ONS

Ответ отличается от описания v0.17:

• DevEUI устройства приходит в поле dev_eui, а не devEui.
• В поле multicast_addr приходит DevAddr устройства, а не адрес группы.

Запрос

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

Поле	Тип	Описание
cmd	string	add_device_to_multicast_req
operation_id	string	Произвольная строка; сервер вернёт её в ответе — по ней сопоставляют запрос и ответ
multicast_eui	string	Обязательно multicast_eui или multicast_addr. EUI группы, 16 hex-символов
multicast_addr	string	Обязательно multicast_eui или multicast_addr. Адрес группы, 8 hex-символов
devEui	string	Обязательно. DevEUI устройства, 16 hex-символов

{
    "cmd": "add_device_to_multicast_req",
    "operation_id": "xyw",
    "multicast_eui": "7DA50BE8C74CE6DC",
    "devEui": "6F1E570FFE14DBFC"
}

Ответ

Поле	Тип	Описание
cmd	string	add_device_to_multicast_resp
operation_id	string	Значение из запроса. В ответах с ошибками 1 и 3 поля нет
status	uint8	1 — устройство записано в группу, 2 — ошибка
multicast_eui	string	EUI группы
multicast_addr	string	DevAddr устройства — не адрес группы
dev_eui	string	DevEUI устройства
error_code, error_text	uint8, string	Только при ошибке, см. ниже

{
    "cmd": "add_device_to_multicast_resp",
    "operation_id": "xyw",
    "status": 1,
    "multicast_eui": "7DA50BE8C74CE6DC",
    "multicast_addr": "78130AE1",
    "dev_eui": "6F1E570FFE14DBFC"
}

Ошибки

error_code	error_text	Что случилось
1	Unauthorized access	Запрос пришёл с токеном низкого уровня
3	Data is filled in with an error	multicast_eui или devEui не из 16 hex-символов, multicast_addr не из 8
9	Multicast does not exists	Группы с такими multicast_eui и multicast_addr у владельца токена нет
8	Device does not exists	Устройство с таким devEui не найдено, либо devEui не передан
10	Device already exist in Multicast	Устройство уже записано в эту группу
0	Unexpected error	Внутренняя ошибка сервера — повторите запрос позже

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

• Всегда указывайте идентификатор группы. Сервер не проверяет, что передан multicast_eui или multicast_addr. Без обоих полей устройство попадёт в одну из групп владельца — в какую именно, предсказать нельзя.
• Состав группы нельзя запросить. Команды, которая возвращает список устройств группы, в WebSocket API нет — ведите список на своей стороне.
• Одно устройство можно записать в несколько групп, но в каждую — только один раз.

См. также

• Multicast-группы — что такое группа и в каком порядке вызывать команды.
• delete_device_from_multicast_req — убрать устройство из состава группы.