Add device to multicast group

Adds a device to a multicast group. This is a bookkeeping record on the server: the server sends nothing to the device itself and does not check group membership when sending a frame. For a device to receive group frames, the group address and keys must be written into the device separately — see How a device learns about the group.

Request and response: add_device_to_multicast_req → add_device_to_multicast_resp.
Access: high access level token only; the group is looked up among 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 differs from the v0.17 description:

• The device DevEUI comes in the dev_eui field, not devEui.
• The multicast_addr field holds the device DevAddr, not the group address.

Request

Fields not marked as required may be omitted.

Field	Type	Description
cmd	string	add_device_to_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
devEui	string	Required. Device DevEUI, 16 hex characters

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

Response

Field	Type	Description
cmd	string	add_device_to_multicast_resp
operation_id	string	Value from the request. Absent in responses with errors 1 and 3
status	uint8	1 — the device is added to the group, 2 — error
multicast_eui	string	Group EUI
multicast_addr	string	Device DevAddr — not the group address
dev_eui	string	Device DevEUI
error_code, error_text	uint8, string	Only on error, see below

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

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 or devEui is not 16 hex characters, multicast_addr is not 8
9	Multicast does not exists	The token owner has no group with this multicast_eui and multicast_addr
8	Device does not exists	No device with this devEui is found, or devEui is not given
10	Device already exist in Multicast	The device is already in this group
0	Unexpected error	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 neither field is given, the device is added to one of the owner's groups — there is no way to predict which one.
• Group membership cannot be requested. The WebSocket API has no command that returns the list of devices in a group — keep the list on your side.
• One device can be added to several groups, but only once to each.

See also

• Multicast groups — what a group is and in which order to call the commands.
• delete_device_from_multicast_req — remove a device from the group membership.