About Campaigns

Contents

• Campaign Timing
• Pilot Campaigns
• Verbose Logging
• Campaign Lifecycle Flow for v1
• Campaign Lifecycle Flow for v2

Campaign times 

Campaign times vary depending on whether they are scheduled on OMA-DM and LWM2M FOTA devices versus HTTP FOTA devices.

Campaign times for OMA-DM and LWM2M FOTA devices

Devices using LWM2M or OMA-DM for device management respond to “push” messages to start a campaign. 

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

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 an OMA-DM or LWM2M future campaign is shown in the following image:

These devices follow the LWM2M and OMA-DM 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 time windows for HTTP FOTA devices

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.

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

Pilot campaigns for HTTP FOTA devices

For devices using HTTP for FOTA, the Schedule Campaign API now has a built-in requirement that a “pilot campaign” must be run with that firmware/software before a large scale campaign can run. The purpose of the pilot campaigns is to test a small number of devices to ensure that there are no unexpected delivery or compatibility problems with that firmware/software. The pilot campaign limit is in place until at least 5 devices and no more than 20 devices have had at least a 50% success rate. Users can run as many up to 20 device pilot campaigns as necessary; once the 50% success rate has been achieved, the 20 device limit will be lifted. 

Verbose Logging for HTTP FOTA devices

If pilot campaigns are not successful, developers have the option to enable and fetch logs for up to 20 devices. Developers initially need to enable logging with the Verbose Logging API. Logging turns off automatically after seven days to avoid unnecessary device resource usage. When the device checks in after that setting is enabled, the device starts collecting logs. The device periodically uploads those logs to ThingSpace and purges them from the device. After at least 24 hours, the developer can call the Verbose Logging API again to fetch the logs for analysis or can view the check-in history as reported by the FOTA server. After 30 days, the logs are purged from ThingSpace.

Campaign Lifecycle Flow for OMA-DM or LWM2M Devices using the /v1 Resource Path

1. The campaign always starts with a user scheduling the campaign with proper make, model, and current software prerequisites to be updated and identifying the software to be updated and when.
2. After the user sends the campaign request, the campaign changes to “Request Pending” status.
   1. After passing parameter checks, the campaign status moves to “Queued”.
      Parameter checks could include things like FOTA eligibility, unknown client type, make, model, firmware, and determining if the device is in another campaign.
   2. If parameter checks fail, it moves to "RequestFailed."
3. The campaign stays in “Queued” status while the systems collect requests.
   1. Normally the campaign would move to "in progress." This stage is is when the software updates are executed in the OMA-DM or LWM2M server.
   2. User can choose to cancel the campaign before the start date, or they can remove all devices from the queued campaign.
4. After the campaign starts, it is "in progress" during the device update.
   1. Once the campaign end date has been reached, the campaign status moves to "Finished."
   2. If the OMA-DM or LWM2M server schedule a campaign, it moves to "UpgradeFailed" status.

Device Lifecycle Flow for OMA-DM or LWM2M Devices using the /v1 Resource Path

Status and Error Messages for OMA-DM ro LWM2M Devices using the /v1 Resource Pat

Campaign Lifecycle Flow for HTTP Devices using the /v2 Resource Path

1. Creating a campaign starts with the user scheduling which devices with proper make, model and current software prerequisites need to be updated with which software at what date.
2. Once the user schedules a campaign request, the campaign changes to “Request Pending” status
   1. After passing parameter checks, campaign status typically moves to "Queued" status.
   2. If parameter checks fail, it moves to "RequestFailed" and may bypass "Pending." 
      Checks could include eligibility such as licenses, FOTA capable, prerequisistes or timing checks.
   3. If it is an on-demand campaign, it bypasses the "Queued" status and moves to "Scheduled."
3. The campaign normally stays in "Queued" status while the system collects requests.
   1. Once the start date has begun, it moves to "Scheduled."
   2. The user can choose to cancel the campaign in "Queued" status.
4. The campaign stays in "In Progress" during the device update.
   1. Once the campaign end date has been reached or if all devices were successfully upgraded, it moves to “ended.” For an on-demand campaign, the end date is one week after the start date.
   2. After the campaign begins but before it ends, the user could decide to “abort” the campaign. Some devices may have already been upgraded.

Device Lifecycle Flow for HTTP Devices using the /v2 Resource Path

Status and Error Messages for HTTP Devices using the /v2 Resource Path