Multicast groups
A multicast group is a shared address and shared keys written into several devices at once. A frame sent to the group address is received by all of the group's devices that can hear the gateway: one frame goes on air instead of a separate frame for each device. This is how you send something that all the devices need at once — for example, a command to switch the lighting on or a new setting.
The WebSocket API lets you create, update and delete groups. Group management commands require a high access level token.
The commands from the v0.17 description for sending data to a group — multicast_data_req, get_multicast_data_req, multicast_data_ack_req and multicast_data_purge_req — are not implemented in the current server version. The pages of these commands describe what happens when they are called.
What a group is on the server
On the server a group is a separate record, similar to a device. It has its own identifiers, keys and parameters:
| Parameter | Field | What it is |
|---|---|---|
| Group EUI | multicast_eui | Group identifier, 16 hex characters. API commands use it to find the group |
| Group address | multicast_addr | The DevAddr that group frames are sent with, 8 hex characters |
| Network key | nwks_key | Group NwkSKey, 32 hex characters: every frame is signed with it |
| Application key | apps_key | Group AppSKey, 32 hex characters: frame data is encrypted with it |
| Class | group_type | LoRaWAN class of the group: 3 — C, 2 — B, 1 — A |
| Region | region | Frequency plan of the group |
- The group EUI and address are unique across the whole server — among both groups and devices.
- A group is created in the application you are connected to.
How a device learns about the group
The server does not configure devices: it does not send them the group address and keys and does not tell a device it was added to a group. The group address, nwks_key and apps_key must be written into each device separately — during manufacturing, during setup, or by a command from your application. The values in the devices and on the server must match, otherwise the device discards the frame.
The group membership on the server (add_device_to_multicast_req) is a bookkeeping list: a group frame is received by any device that has the group address and keys.
Command order
- Create the group:
create_multicast_req. - Write the group address and keys into the devices. This is done outside the server.
- Add the devices to the group membership for bookkeeping:
add_device_to_multicast_req.
Commands of the group
| Command | Purpose | In the current version |
|---|---|---|
create_multicast_req | Create a group | Works |
get_multicast_req | Get group parameters | Works |
update_multicast_req | Change the group keys, class, frequency plan, description | Works |
delete_multicast_req | Delete a group | Works |
add_device_to_multicast_req | Add a device to the group membership | Works |
delete_device_from_multicast_req | Remove a device from the group membership | Works |
multicast_data_req | Send data to a group | Does not work: the server validates the request but sends no frame |
get_multicast_data_req | Get the history of group frames | Not implemented |
multicast_data_ack_req | Get the status of a group frame | Not implemented |
multicast_data_purge_req | Clear the group queue | Not implemented |