MachineQ Developer Documentation logo DOCS
Back to Docs

Choosing Multicast Setup Time

The multicast_setup_time parameter is the trickiest campaign setting and is highly application-specific. This guide explains what it controls, how to pick a good value for Class A and Class C devices, and what happens if the value is too small or too large.

Before You Begin

You need:

  • A device group and a campaign you are ready to create. See Quick Start Guide.
  • Knowledge of the LoRaWAN class of your devices. See the FAQ if you are unsure.
  • $MQ_TOKEN exported from the authentication step. See Quick Start Guide.

Note: In API version v3.0 the start_in parameter was renamed to multicast_setup_time. The guidance below applies to both names.

What Is the Multicast Setup Time Parameter?

The multicast_setup_time parameter in the create campaign API defines when the multicast session starts. The start time is the same for all devices in the device group: it is the moment every device opens the multicast Class C window and starts listening for FragmentedData packets.

Because the configuration downlink that sets up the start of the multicast session comes last, there must be enough time to set up all devices before the session begins.

For API v2.0: The start_in parameter defines the multicast session start time relative to the campaign start, while start_at defines the absolute start time. This page discusses start_in, but the same principle applies to start_at.

How to Choose the Perfect Value

The best multicast_setup_time is long enough to accommodate the worst-case time-to-setup for any device in the group. Four (4) downlinks must reach each device in the campaign.

Class A

Note: Starting with v3.1, the FUOTA server selects multicast setup time automatically.

A Class A device can only receive a downlink when it sends an uplink. The FUOTA server needs to send four (4) downlinks to set up the Class C multicast session. Accounting for a maximum of 25% PER, the device would need six uplinks to receive all necessary downlinks. Because all devices must receive every setup message before the multicast_setup_time occurs, you must plan for the maximum uplink interval.

To summarize, find the longest period between two consecutive uplinks across all devices and multiply that number by 6 (to account for possible radio collisions).

Example: A device group has 15 MQflexes. All but one have a minimum reporting period of 15 minutes; one has 20 minutes. The multicast_setup_time would be 20 min * 6 = 120 min = 7200 sec.

Class C

The FUOTA server automatically selects the multicast_setup_time for Class C devices. However, if there are more than 1000 devices in the group, you must provide multicast_setup_time yourself.

Because Class C devices can receive a downlink at any moment, there is no exact way to determine the setup time for all devices. Generally, the more devices in a physical environment, the higher the chance of radio and uplink collisions. The minimum recommended time is 300 seconds for fewer than 20 devices, and the server automatically estimates the time when the group has fewer than 1000 devices.

What if Multicast Setup Time Is Too Small?

Some or all devices will not finish setup in time and will fail to update. If a device operates according to the LoRa Alliance Specifications, there should be no negative impact: the device continues to function normally.

What if Multicast Setup Time Is Too Large?

There is no negative impact from choosing a larger multicast_setup_time. A longer value gives devices more time to set up the multicast session and should not harm the battery or the update itself.

Warning: One potential drawback is an unstable device that might rejoin at any time. If a device rejoins after setting up the multicast session but before the session begins, it will not be able to receive the FragmentedData packets. This can be mitigated by storing the multicast group, session, and fragmentation details in flash memory and restoring them after the join procedure.

What's Next?

Gateway Selection Multicast Session Overlap Avoidance