Skip to main content

Update multicast group

Changes the parameters of a multicast group: keys, class, frequency plan, description and application. The server looks up the group by multicast_eui, by multicast_addr or by both fields at once; the EUI and address themselves cannot be changed.

The command overwrites the parameters rather than merging them. The server resets the group_type, region, dr and ping_slot_period fields that are missing from the request to their defaults and erases the nwks_key and apps_key keys. Only description and the group's application stay unchanged. So first request the current parameters with get_multicast_req and pass all fields in the request — including those that do not change.

Request and response: update_multicast_req → update_multicast_resp.
Access: high access level token only; groups of all applications of the token owner are available. With a low access level token the server responds with error 1.

Current ONS version

Differences from the v0.17 description:

  • Fields that are not in the request do not keep their values but are reset: nwks_key and apps_key to an empty value, group_type to 3, region to 0, dr to 0, ping_slot_period to 128.
  • The server accepts freq but does not store it: the group frequency stays the same.
  • group_type in the response is always null.
  • A group has no app_key field: the server ignores it.
  • The response command is update_multicast_resp, not create_multicast_resp as in the v0.17 example.

Request​

Fields not marked as required may be omitted.

FieldTypeDescription
cmdstringupdate_multicast_req
operation_idstringAny string; the server returns it in the response to match the request and the response
multicast_euistringmulticast_eui or multicast_addr is required. EUI of the group to change, 16 hex characters
multicast_addrstringmulticast_eui or multicast_addr is required. Address of the group to change, 8 hex characters
nwks_keystringRequired. Group NwkSKey, 32 hex characters. The server does not check that the field is present: without it the server erases the group key
apps_keystringRequired. Group AppSKey, 32 hex characters. The server does not check that the field is present: without it the server erases the group key
regionuint8Region code — the frequency plan of the group, 0–23, see Region codes. Without the field it is reset to 0 (EU)
group_typeuint8Group class: 3 — C, 2 — B, 1 — A. Without the field it is reset to 3
druint8Group data rate (DR), 0–15. The server only stores the value. Without the field it is reset to 0
ping_slot_perioduint32Reserved. Without the field it is reset to 128
descriptionstringNew description, up to 255 characters. Without the field the description does not change
application_euistringAppEUI of the token owner's application to move the group to, 16 hex characters. Without the field the group stays in its application
freqfloatNot stored: the group frequency stays the same
{
    "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
}

Response​

FieldTypeDescription
cmdstringupdate_multicast_resp
operation_idstringValue from the request. Absent in responses with errors 1 and 3
statusuint81 — the group is changed, 2 — error
multicast_eui, multicast_addrstringEUI and address of the changed group
application_euistringAppEUI from the request. If the field was omitted — the AppEUI of one of the owner's applications, not necessarily the one the group belongs to
description, nwks_key, apps_key, ping_slot_period, freq, dr, regionGroup parameters after the change. Types are the same as in the request
group_typeuint8Always null. The stored class is returned by get_multicast_req
error_code, error_textuint8, stringOnly on error, see below
{
    "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
}

Errors​

error_codeerror_textWhat happened
1Unauthorized accessThe request came with a low access level token
3Data is filled in with an errorInvalid format: multicast_eui or application_eui is not 16 hex characters, multicast_addr is not 8, a key is not 32; group_type is not 1–3; dr is not 0–15; region is not 0–23; freq is not a number
9Multicast does not existsThe token owner has no group with this multicast_eui and multicast_addr
5Application does not existsThe token owner has no application with this application_eui
0Unexpected errorThe change was not stored: neither multicast_eui nor multicast_addr is given, or an internal server error occurred

Good to know​

  • Pass the whole group. A request with only multicast_eui and description erases both keys and resets the class, frequency plan and data rate (DR): the group is left without keys.
  • New keys must be written into the devices as well. The server sends nothing to the devices.
  • The group EUI and address do not change. To change them, delete the group and create a new one.

See also​