Defer device updates

A high-level application can temporarily defer updates to the Azure Sphere OS and to application images to prevent the update from interrupting critical processing. An Azure Sphere device in a kitchen appliance, for example, could defer updates during use. To have the opportunity to defer updates, the app registers for update notifications. After the OS downloads the update, it notifies the application, which can get details about the update and request deferral.

The Deferred Update sample shows how to use an event loop and system events to defer updates.

Real-time capable applications (RTApps) cannot receive update notifications or request deferrals. A high-level app is responsible for managing update deferral on behalf of RTApps on the device.

Deferral requirements

Applications that defer updates must include the appropriate header files and add deferral settings to the application manifest.

Header files

Include the eventloop and sysevent headers in your project:

 #include <applibs/eventloop.h>
 #include <applibs/sysevent.h>

Application manifest settings

To be notified about software update events and to have the opportunity to defer such updates, an application includes two capabilities in the application manifest file:

• SystemEventNotifications
• SoftwareUpdateDeferral

Set the SystemEventNotifications field to true in the app_manifest.json file to receive notifications of system update events. The application must also register for event notifications, as described in Notification mechanism. Set SoftwareUpdateDeferral to true to enable the app to defer and resume updates.

The following shows the app_manifest.json settings required to enable both notification and deferral:

"Capabilities": {
        "SystemEventNotifications" : true,
        "SoftwareUpdateDeferral" : true
    }

Notification mechanism

Azure Sphere supports update deferral through an event notification and event loop mechanism. The application creates an EventLoop, which is a single-threaded object through which the application is notified of pending events.

To receive notifications, an app calls SysEvent_RegisterForEventNotifications, passing these parameters:

• A pointer to the event loop
• An eventBitmask that specifies the events for which the app requests notification
• A pointer to an app-defined callback function
• An optional context pointer that is passed to the callback

Only one EventLoop object can be used with SysEvent_RegisterForEventNotifications per thread. A second call to SysEvent_RegisterForEventNotifications with a different EventLoop object will fail.

After registration, the application calls EventLoop_Run, which invokes the callback function if an event has changed status. The callback function receives a SysEvent_Events value, which identifies the type of event. In turn, the callback calls SysEvent_Info_GetUpdateData to find out whether the event is an OS or application update and how long the update can be deferred. The app can then determine how to handle the event notification.

Azure Sphere may send several status notifications for each update event:

An app can request deferral only after it receives a SysEvent_Status_Pending notification. To allow the update to occur immediately, the application can ignore the notification.

To defer the update, the application calls SysEvent_DeferEvent, passing the number of minutes to defer the update. For an OS update, the maximum deferral is 1440 minutes (24 hours). For an application update, the maximum deferral period is 10,020 minutes (167 hours).

An application can end an update deferral prematurely by calling SysEvent_ResumeEvent. For an application or OS update, a successful call to SysEvent_ResumeEvent restarts the notification process and thus sends a new SysEvent_Status_Pending notification. The app should not call SysEvent_DeferEvent again until it has received such a notification.

When the application receives the SysEvent_Status_Final notification, it should prepare to receive a SIGTERM signal from the Azure Sphere OS. When the SIGTERM signal is received, the app should perform final cleanup and exit. The application should not exit before the SIGTERM is received; otherwise, it could be restarted before the SIGTERM is sent. For an OS update, the application should do whatever cleanup is required before device reboot. For an application update, the high-level application should do whatever is necessary before it or any other application on the device is restarted. Application notification does not currently specify which application is being updated.

When notification is no longer required, the app should call SysEvent_UnregisterForEventNotifications and then EventLoop_Close to release the memory allocated for the event loop object. Note that after all event notifications have been unregistered, the app can use a new EventLoop object.