Campaign times vary depending on whether they are scheduled on OMA-DM and LWM2M FOTA devices versus HTTP 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.
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.
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.
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.
|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.|
|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.|
|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.|
|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.|