Campaign Timing

Campaign times vary depending on how they are scheduled and their protocol type. Skip to the section based on the protocol your device is using:

OMA-DM
HTTP(S)
LWM2M

Campaign time windows for OMA-DM FOTA devices (V1 API)

The ThingSpace Schedule Campaign API allows the user to schedule an "on-demand" update or for a day in the future. On-demand campaigns usually commence within 90 minutes of when they are scheduled, to allow all the pre-validation checks to occur. The campaign lifecycle flow is described here. Once the campaign is changed to “In progress” status, the devices will receive a “push” notification to begin the campaign.

An example schedule for an OMA-DM on-demand campaign is shown in the following image. Assuming the device is powered and connected to the network when “campaign begins,” the device should begin applying the firmware update immediately. If the device is not powered on, the device will be notified whenever it connects to the network; for example the next day at 3:00 AM UTC:

If the ThingSpace Schedule Campaign API is set to a date in the future, the campaign will commence around 12:00 AM UTC the day. Assuming the device is powered and connected to the network when “campaign begins,” the device should begin applying the firmware update immediately. If the device is not powered on, the device will be notified whenever it connects to the network; for example the same day at 3:00 AM UTC:

In any of these cases, if the device upgrade fails after that 4 hour window, ThingSpace and the Verizon network will queue this device in the network indefinitely for an upgrade. The next time it powers on, it will be notified for upgrade and the campaign will begin. If that campaign fails, it will be queued up again indefinitely. Use the Get Device List API to monitor specific reported firmware version on the device.

Campaign time windows for HTTP(S) FOTA devices (V2 API)

Devices using HTTP(S) for FOTA device management do not respond to “push” messages to start a campaign, but rather, devices check-in during periodic intervals as specified by the device OEM. To accommodate a campaign with variable start times, the Schedule Campaign API requires a start and end date. For example, the start date could be on a Sunday at 12:00 AM UTC and the end date could be on a Saturday at 11:59:59 PM UTC. When the device checks-in during that window, it will download and apply any new eligible firmware/software updates available.

An example on-demand campaign schedule for HTTP devices is shown below:

A set of optional parameters allow you to specify more discrete times within the start and end dates in the event that the device should only receive the update during those times. For example, if the device is a smart light that should not be updated during the evening, a time window can specify not only that the campaign runs from Sunday-Saturday, but that it must only happen during the late morning hours.

The Schedule Campaign API also offers an optional parameter that allows you to specify a discrete time window when the device should download the update, and a different time window when the device should apply the update. This is dependent on device support of this feature.

A campaign schedule for a future campaign with discrete time windows is shown below:

Campaign times for LWM2M FOTA devices (V1 API)

The scheduling behavior varies based on whether the LWM2M campaign is scheduled with the V1 or V3 FOTA API’s. The ThingSpace portal utilizes the V3 APIs to schedule LWM2M campaigns. V1 and V3 campaigns can both be monitored in the portal.

The ThingSpace Create Campaign API allows the user to schedule an "on-demand" update or a day in the future. On-demand updates usually occur within 90 minutes once they are scheduled, to allow all the pre-validation checks to occur. An example schedule for a LWM2M on-demand campaign is shown in the following image:

If the initial upgrade attempt was not successful, ThingSpace Software Management will try again 4 hours later. It will repeat this the next day and up to 3 days, six attempts in total.

Updates in the future normally begin around 12:00 AM UTC. For LWM2M devices, if the device does not respond, the system tries again around 4:00 AM UTC, and repeats this for up to 3 days. An example schedule for aLWM2M future campaign is shown in the following image:

These devices follow the LWM2M standard so these devices will respond to a push message with a response that the device has started, and eventually completed, the update. The Open Mobile Alliance has a well-documented FOTA state machine for the firmware update process.

Campaign times for LWM2M FOTA devices (V3 API)

Using the ThingSpace Software Management V3 FOTA API is an entirely different scheduling experience for LWM2M. Firmware update time considers user input, device availability, network availability and retry attempts. Like the V1 and V2 API’s, the campaign requires a list of devices and target firmware. Unlike the LWM2M V1 API the V3 API requires an end date. It also allows for time-windows in case the application should only be upgraded a particular time of day (for example in the morning, afternoon, evening, etc)

The ThingSpace Create Campaign API allows the user to schedule an "on-demand" update or a day in the future. On-demand updates usually occur within 30 minutes once they are scheduled, to allow all the pre-validation checks to occur. An example schedule for a LWM2M on-demand campaign

The ThingSpace portal utilizes the V3 APIs to schedule LWM2M campaigns. V1 and V3 campaigns can both be monitored in the portal:

A campaign schedule for a future campaign with discrete time windows is shown below:

Refer to the Get Device Status in a Campaign | ThingSpace (verizon.com) to get specific status including the next attempt projected timing.