Get multicast group

Returns the parameters of one multicast group: address, session keys, class and frequency plan. The server looks up the group by multicast_eui, by multicast_addr or by both fields at once — in that case both must match.

The command returns one group per request. The WebSocket API does not provide a list of groups or a list of a group's devices.

Request and response: get_multicast_req → get_multicast_resp.
Access: high access level token only; it sees the groups of all applications of the token owner. With a low access level token the server responds with error 1.

Current ONS version

• The response does not contain the app_key field listed in the v0.17 description: a group has only the nwks_key and apps_key session keys.
• ping_slot_period in the response is always null: this command does not return the value set when the group was created.

Request

Fields not marked as required may be omitted.

Field	Type	Description
cmd	string	get_multicast_req
operation_id	string	Any string; the server returns it in the response to match the request and the response
multicast_eui	string	multicast_eui or multicast_addr is required. Group EUI, 16 hex characters
multicast_addr	string	multicast_eui or multicast_addr is required. Group address, 8 hex characters

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

Response

Field	Type	Description
cmd	string	get_multicast_resp
operation_id	string	Value from the request. Absent in responses with errors 1 and 3
status	uint8	1 — success, 2 — error
multicast_eui	string	Group EUI
multicast_addr	string	Group address — the DevAddr its frames are sent with
application_eui	string	AppEUI of the application the group belongs to
description	string	Group description
nwks_key	string	Group NwkSKey
apps_key	string	Group AppSKey
group_type	uint8	Group class: 1 — A, 2 — B, 3 — C
ping_slot_period	uint32	Always null
freq	float	Group frequency, MHz; null if not set. The server only stores the value
dr	uint8	Group data rate (DR), 0–15. The server only stores the value
region	uint8	Region code — the frequency plan of the group, see Region codes
error_code, error_text	uint8, string	Only on error, see below

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

Errors

error_code	error_text	What happened
1	Unauthorized access	The request came with a low access level token
3	Data is filled in with an error	multicast_eui is not 16 hex characters or multicast_addr is not 8
9	Multicast does not exists	The token owner has no group with this multicast_eui and multicast_addr
0	—	Internal server error — retry later

Good to know

• Always specify the group identifier. The server does not check that multicast_eui or multicast_addr is given. If both fields are omitted, the server returns one arbitrary record of the owner, which may turn out to be a regular device rather than a group.
• The keys come in clear text. The response contains the group's nwks_key and apps_key — do not write it to shared logs.

See also

• Multicast groups — what a group is and in which order to call the commands.
• create_multicast_req — create a group.