Multicast

Multicast in LoRaWAN is a single downlink frame sent to the shared address of a group. Every device that has the group address and session keys written into it receives the frame, so a command that all the devices need goes on air in one transmission. In ONS, groups are created, updated and deleted in the web interface and through the WebSocket API.

Warning

In the current ONS version, groups are only stored on the server. No frame to a group goes on air: not from the web interface, nor through the WebSocket API, integrations or the MCP server. Send a command intended for several devices to each device separately — see What to do now.

What a group consists of

On the server, a group is a record in the same table as devices, marked as a multicast group. That is why group parameters are stored in device fields:

Parameter	What it means in LoRaWAN	How ONS stores it
Group EUI	Group identifier, 16 hex characters. API commands use it to find the group	As the device DevEUI
Group address (DevAddr)	The address group frames are sent with, 8 hex characters	As the device DevAddr
NwkSKey	Network session key of the group, 32 hex characters: the frame is signed with it	The `nwks_key` field
AppSKey	Application session key of the group, 32 hex characters: frame data is encrypted with it	The `apps_key` field
Class	When the group devices listen	As the device class: 1 — A, 2 — B, 3 — C. Default in the WebSocket API and in the web interface — C
Region	Frequency plan of the group	The `region` field. Default in the WebSocket API — 0 (EU), in the web interface — 6 (KZ865-868)
Frequency	The frequency the group frame is sent on	A separate field. The server only stores it
DR	Data rate of the group frame	As the fixed data rate of a device. Default DR0. The server only stores it
`ping_slot_period`	Parameter of scheduled receive windows (class B)	In the device status request interval field (`dev_status_req_interval`). Default in the WebSocket API — 128. The server only stores it

A group has no AppKey: it has only an address and two session keys.
The group EUI and address are unique among all active records — both groups and devices. The EUI and address of a deleted group become free again.
ONS does not support class B: the server does not build a frame for a class B device or group. Choose class C — see Device classes.

What the server does and does not do

Action	In the current version
Create, update, delete a group	Works — in the web interface and with WebSocket API commands
Add a device to the group membership and remove it	Works — with WebSocket API commands only. The membership is stored in a separate table and serves bookkeeping only: nothing reads it when transmitting
Send the group address and keys to devices	Not done. There is neither a MAC command nor an application command for this: the server only writes the group parameters to the database
Send a frame to the group	Not done, see below

The group address, NwkSKey and AppSKey must be written into each device separately — see How a device learns about the group.

All group commands of the WebSocket API require a high access level token.

Ways to send data to a group

Method	In the current version
WebSocket API command `multicast_data_req`	The server validates the request format but does not queue the frame and does not respond to a valid request
Commands `get_multicast_data_req`, `multicast_data_ack_req`, `multicast_data_purge_req`	Not present in the server
Web interface	No such function. The group page has a parameter form and a read-only Data table. The built-in tools of the WebSocket Applications block do not use groups: "Lighting application v1", "Lighting application v2" and "Parser application" send `downlink_data_req` to each device separately
MQTT and other integrations, the MCP server	No group command
Web interface REST API (`/api/v1/multicast/`)	No data sending: list, read, create, update and delete groups plus service actions inherited from the device route — for example, counting groups and issuing a random address for a new group. None of them queues a frame
`downlink_data_req` with the group EUI in `devEui`	The server accepts the command and returns `status` 1 and a `dataId`, but the frame does not go on air and stays in the queue. The server builds a downlink frame only for an address it has already received an uplink from, and a group sends no uplinks. This is derived from the server code and has not been verified on air

What to do now

Send the frame to each device of the group separately:

with the WebSocket API command downlink_data_req — one request per device;
or through the MQTT integration — a tx command for each device;
or in the web interface — with the "Parser application" tool from the WebSocket Applications block of the application page: in its "Send data" form, list the DevEUIs in the "Node EUI" field one per line — the tool sends downlink_data_req to each device separately.

A class C device gets the frame right after queuing, without waiting for an uplink, provided the device has reported at least once after joining the network. A class A device gets it after its next uplink. For details, see Device classes.

How to prepare a group

Create the group: in the Multicasts section of the web interface or with create_multicast_req. Choose class C.
Write the group address, NwkSKey and AppSKey into each device — outside the server. The values in the devices and on the server must match.
Add the devices to the group membership for bookkeeping with add_device_to_multicast_req. To remove a device from the membership, use delete_device_from_multicast_req.

Good to know

The group membership affects nothing. When a device is added to a group, the server does not check its class, frequency plan or application.
Frequency, DR and ping_slot_period are only stored. The server writes them but does not use them when transmitting. The group frame stub in the server core is designed for immediate transmission at the RX2 frequency and data rate of the frequency plan, but processing never reaches it: a group has no uplink parameters.
update_multicast_req does not change the group frequency. The server accepts the freq field but does not write it.
Deletion is soft. The server marks the group inactive, and its EUI and address become free.
Groups are not counted as devices. Neither the application list nor the monitoring dashboard counts groups.
Only actions in the web interface are recorded in the user action log. Creating, updating and deleting groups in the web interface are logged; WebSocket API group commands are not logged — see Logs.

What a group consists of​

What the server does and does not do​

Ways to send data to a group​

What to do now​

How to prepare a group​

Good to know​

See also​