Обновить multicast-группу

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

Команда записывает параметры заново, а не дополняет их. Поля group_type, region, dr и ping_slot_period, которых нет в запросе, сервер сбросит на значения по умолчанию, а ключи nwks_key и apps_key сотрёт. Без изменений остаются только description и приложение группы. Поэтому сначала запросите текущие параметры командой get_multicast_req и передайте в запросе все поля — и те, что не меняются.

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

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

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

• Поля, которых нет в запросе, не остаются прежними, а сбрасываются: nwks_key и apps_key — на пустое значение, group_type — на 3, region — на 0, dr — на 0, ping_slot_period — на 128.
• freq сервер принимает, но не записывает: частота группы остаётся прежней.
• В ответе group_type всегда null.
• Поля app_key у группы нет: сервер его игнорирует.
• Команда ответа — update_multicast_resp, а не create_multicast_resp, как в примере v0.17.

Запрос

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

Поле	Тип	Описание
cmd	string	update_multicast_req
operation_id	string	Произвольная строка; сервер вернёт её в ответе — по ней сопоставляют запрос и ответ
multicast_eui	string	Обязательно multicast_eui или multicast_addr. EUI группы, которую нужно изменить, 16 hex-символов
multicast_addr	string	Обязательно multicast_eui или multicast_addr. Адрес группы, которую нужно изменить, 8 hex-символов
nwks_key	string	Обязательно. NwkSKey группы, 32 hex-символа. Сервер не проверяет, что поле передано: без него он сотрёт ключ группы
apps_key	string	Обязательно. AppSKey группы, 32 hex-символа. Сервер не проверяет, что поле передано: без него он сотрёт ключ группы
region	uint8	Код региона — частотного плана группы, 0–23, см. Коды регионов. Без поля сбрасывается на 0 (EU)
group_type	uint8	Класс группы: 3 — C, 2 — B, 1 — A. Без поля сбрасывается на 3
dr	uint8	Скорость передачи (DR) группы, 0–15. Сервер значение только хранит. Без поля сбрасывается на 0
ping_slot_period	uint32	Зарезервировано. Без поля сбрасывается на 128
description	string	Новое описание, до 255 символов. Без поля описание не меняется
application_eui	string	AppEUI приложения владельца токена, в которое нужно перенести группу, 16 hex-символов. Без поля группа остаётся в своём приложении
freq	float	Не записывается: частота группы остаётся прежней

{
    "cmd": "update_multicast_req",
    "operation_id": "xyw",
    "multicast_eui": "7DA50BE8C74CE6DC",
    "description": "Street lights, north district",
    "nwks_key": "EEFBF983C00B35240C9A7C2D8D011301",
    "apps_key": "6F17B97CEA2C63D1089EF4268FD68D38",
    "group_type": 3,
    "ping_slot_period": 128,
    "dr": 0,
    "region": 6
}

Ответ

Поле	Тип	Описание
cmd	string	update_multicast_resp
operation_id	string	Значение из запроса. В ответах с ошибками 1 и 3 поля нет
status	uint8	1 — группа изменена, 2 — ошибка
multicast_eui, multicast_addr	string	EUI и адрес изменённой группы
application_eui	string	AppEUI из запроса. Если поле не передавали — AppEUI одного из приложений владельца, не обязательно того, которому принадлежит группа
description, nwks_key, apps_key, ping_slot_period, freq, dr, region		Параметры группы после изменения. Типы — как в запросе
group_type	uint8	Всегда null. Записанный класс возвращает get_multicast_req
error_code, error_text	uint8, string	Только при ошибке, см. ниже

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

Ошибки

error_code	error_text	Что случилось
1	Unauthorized access	Запрос пришёл с токеном низкого уровня
3	Data is filled in with an error	Неверный формат: multicast_eui или application_eui не из 16 hex-символов, multicast_addr не из 8, ключ не из 32; group_type не 1–3; dr не 0–15; region не 0–23; freq не число
9	Multicast does not exists	Группы с такими multicast_eui и multicast_addr у владельца токена нет
5	Application does not exists	У владельца токена нет приложения с таким application_eui
0	Unexpected error	Изменение не записано: не указаны ни multicast_eui, ни multicast_addr, либо произошла внутренняя ошибка сервера

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

• Передавайте группу целиком. Запрос только с multicast_eui и description сотрёт оба ключа и сбросит класс, частотный план и скорость передачи (DR): группа останется без ключей.
• Новые ключи нужно записать и в устройства. Сервер устройствам ничего не передаёт.
• EUI и адрес группы не меняются. Чтобы сменить их, удалите группу и создайте новую.

См. также

• Multicast-группы — что такое группа и какие у неё ограничения.
• get_multicast_req — получить текущие параметры группы перед изменением.