About Campaigns

About Campaigns

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 update “as soon as possible” or a day in the future. ASAP updates usually occur within two hours once they are scheduled, to allow all the pre-validation checks to occur. Updates in the future normally begin around 12:00 AM UTC. If the device does not respond, the system tries again around 4:00 AM UTC, and repeats this for up to 3 days. 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 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.

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.

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 prerequisites.
  2. After the campaign request from the user is sent, it is in “Request Pending” status.
    1. After passing parameter checks, it normally moves to “Queued” status.
    2. If parameter checks fail, it moves to "RequestFailed."
  3. It sits in “Queued” status while the systems are collecting requests.
    1. Normally it would move to "in progress." This is when the campaigns are executed.
    2. User could decide to cancel the campaign.
  4. After it starts, it is "in progress."
    1. Once the campaign finishes, it moves to "Finished."
    2. If the OMA-DM or LWM2M server fails parameter checks, it moves directly from "Queued" 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, it is in “Request Pending” status
    1. After passing parameter checks, it normally moves to "Queued" status.
    2. If parameter checks fail, it moves to "RequestFailed."
    3. If it is an on-demand campaign, it bypasses the "Queued" status."
  3. The campaign is in "Queued" status while the systems are collecting requests.
    1. Normally it would move to "Scheduled."
    2. The user could decide to cancel the campaign in "Queued" status.
  4. Once the start date begins, it moves into “scheduled” state. When devices check-in, they will learn about the 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.