Skip to main content

Create multicast group

Creates a multicast group: a shared address and shared session keys that let several devices receive the same downlink. The group is created in the application you are connected to.

The command only creates a record on the server. The server sends nothing to the devices: the group address and keys must be written into them separately — see How a device learns about the group.

Request and response: create_multicast_req → create_multicast_resp.
Access: high access level token only. With a low access level token the server responds with error 1.

Current ONS version

Differences from the v0.17 description:

  • The group is always created in the application you are connected to. The server only validates the application_eui field.
  • region defaults to 0 (EU), not 6 (KZ865-868).
  • group_type also accepts the value 1 (class A).
  • multicast_addr is exactly 8 hex characters. The server rejects a 7-character address, as in the v0.17 example, with error 3.
  • A group has no app_key field: the server ignores it.
  • The server stores freq, dr and ping_slot_period but does not use them when transmitting frames.

Request​

Fields not marked as required may be omitted.

FieldTypeDescription
cmdstringcreate_multicast_req
operation_idstringAny string; the server returns it in the response to match the request and the response
multicast_euistringRequired. Group EUI, 16 hex characters. Must be unique across the whole server among groups and devices
multicast_addrstringRequired. Group address — the DevAddr its frames will be sent with, 8 hex characters. Must be unique across the whole server among groups and devices
nwks_keystringRequired. Group NwkSKey, 32 hex characters. The server does not check that the key is present and creates the group without it
apps_keystringRequired. Group AppSKey, 32 hex characters. The server does not check that the key is present and creates the group without it
regionuint8Region code — the frequency plan of the group, 0–23, see Region codes. Default 0 (EU).
group_typeuint8Group class: 3 — C, 2 — B, 1 — A. Default 3
descriptionstringGroup description, up to 255 characters
application_euistringAppEUI of one of the token owner's applications, 16 hex characters. The server only checks that such an application exists
freqfloatGroup frequency, MHz. The server only stores the value
druint8Group data rate (DR), 0–15. Default 0. The server only stores the value
ping_slot_perioduint32Reserved. Default 128
{
    "cmd": "create_multicast_req",
    "operation_id": "xyw",
    "multicast_eui": "7DA50BE8C74CE6DC",
    "multicast_addr": "C74CE6DC",
    "description": "Street lights",
    "nwks_key": "EEFBF983C00B35240C9A7C2D8D011301",
    "apps_key": "6F17B97CEA2C63D1089EF4268FD68D38",
    "group_type": 3,
    "region": 6
}

Response​

FieldTypeDescription
cmdstringcreate_multicast_resp
operation_idstringValue from the request. Absent in responses with errors 1 and 3
statusuint81 — the group is created, 2 — error
multicast_eui, multicast_addrstringEUI and address of the created 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 was created in
description, nwks_key, apps_key, group_type, ping_slot_period, freq, dr, regionStored values: from the request or defaults. Types are the same as in the request. A field that was not in the request and has no default is null
error_code, error_textuint8, stringOnly on error, see below
{
    "cmd": "create_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": 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
5Application does not existsThe token owner has no application with this application_eui
4Uniq failedThe token owner already has a group with this multicast_eui and multicast_addr
0Unexpected errorThe group was not created. Usually the reason is that multicast_eui or multicast_addr is already taken by another group or device on the server, or one of these fields is missing

Good to know​

  • The server does not configure devices. The group address, nwks_key and apps_key must be written into the devices as well — the same values as in the request.
  • Write the EUI and address in upper case. The server stores multicast_eui and multicast_addr as is and looks the group up by exact match.
  • Specify the region explicitly. The default value 0 is the EU plan: if your devices use another plan, pass region explicitly.

See also​