Получить multicast-группу

Возвращает параметры одной multicast-группы: адрес, сессионные ключи, класс и частотный план. Сервер ищет группу по multicast_eui, по multicast_addr или по обоим полям сразу — тогда должны совпасть оба.

За один запрос команда возвращает одну группу. Списка групп и списка устройств группы в WebSocket API нет.

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

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

• В ответе нет поля app_key, которое есть в описании v0.17: у группы только сессионные ключи nwks_key и apps_key.
• ping_slot_period в ответе всегда null: значение, заданное при создании группы, эта команда не возвращает.

Запрос

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

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

{
    "cmd": "get_multicast_req",
    "operation_id": "xyw",
    "multicast_eui": "7DA50BE8C74CE6DC"
}

Ответ

Поле	Тип	Описание
cmd	string	get_multicast_resp
operation_id	string	Значение из запроса. В ответах с ошибками 1 и 3 поля нет
status	uint8	1 — успех, 2 — ошибка
multicast_eui	string	EUI группы
multicast_addr	string	Адрес группы — DevAddr, с которым уходят её кадры
application_eui	string	AppEUI приложения, которому принадлежит группа
description	string	Описание группы
nwks_key	string	NwkSKey группы
apps_key	string	AppSKey группы
group_type	uint8	Класс группы: 1 — A, 2 — B, 3 — C
ping_slot_period	uint32	Всегда null
freq	float	Частота группы, МГц; null, если не задана. Сервер значение только хранит
dr	uint8	Скорость передачи (DR) группы, 0–15. Сервер значение только хранит
region	uint8	Код региона — частотного плана группы, см. Коды регионов
error_code, error_text	uint8, string	Только при ошибке, см. ниже

{
    "cmd": "get_multicast_resp",
    "operation_id": "xyw",
    "status": 1,
    "multicast_eui": "7DA50BE8C74CE6DC",
    "multicast_addr": "C74CE6DC",
    "application_eui": "819EA8554FCD762A",
    "description": "Street lights",
    "nwks_key": "EEFBF983C00B35240C9A7C2D8D011301",
    "apps_key": "6F17B97CEA2C63D1089EF4268FD68D38",
    "group_type": 3,
    "ping_slot_period": null,
    "freq": null,
    "dr": 0,
    "region": 6
}

Ошибки

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

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

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

См. также

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