About Campaigns

About Campaigns

Contents

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

Device Status Device Detail Status
Device Accepted Device cleared all check so it can be added to the scheduled list.
Device Rejected Device not found.
Device Rejected Invalid Device IMEI.
Device Rejected Device not eligible for service.
Device Rejected Unknown client device type.
LicenseRemoveFailed License removal not allowed for devices that have ever upgraded firmware.
LicenseRemoveFailed Internal error.
Device Rejected Device scheduled for firmware-upgrade previously, it needs to be completed before another upgrade is schedule.
Device Rejected Device make/model do not meet firmware prerequisites.
Device Rejected Current device firmeware version does not meet firmware prerequisites.
Upgrade Failed Device is not in an active state or is not connected.
Upgrade Failed Current device module does not meet firmware prerequisites.
Upgrade Failed Firmware update to device failed.
Upgrade Failed Internal System Error. Please retry upgrade.
Upgrade Success The firmware upgrade was successful.

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

Device Status Device Detail Status
Accepted Device cleared all checks so it can be added to the scheduled list.
DeviceRejected Device not found.
DeviceRejected Device scheduled for firmware upgrade previously, needs to be completed before another upgrade is scheduled.
DeviceRejected Device not eligible for service (not FOTA capable)
DeviceRejected Invalid device IMEI.
DeviceRejected Current device software version does not meet software prerequisites.
DeviceRejected Device make/model does not meet softwware prerequisites.
DeviceRejected Device is not in active state or is not connected.
DeviceRejected Internal Error.
UpgradedFailed for UpgradePending RovaClientDidNotReportStatus
UpgradedFailed for UpgradePending RovaClientDownloadFailed
UpgradedFailed for UpgradePending RovaClientDownloadNotInstalledYet
UpgradedFailed for UpgradePending RovaClientDownloadedInstallFailed
UpgradedFailed for UpgradePending Uknown device error.
UpgradedFailed for UpgradePending Other.
CampaignCancelled Campaign canceled by user.
UpgradeSuccess Download and install succeeded.
CampaignAborted Campaign aborted by user.