How To Ensure That System Software Updates Don’t Interrupt Devices During Critical Tasks
Polite deployment is the process by which a device and its agent, having been notified by the Electric Imp impCloud™ that an application or impOS™ update is available, can elect to delay the installation of that update rather than receive and apply it immediately. This allows critical tasks to be completed without interruption.
This document will focus on polite impOS deployments; please see the documentation here for assistance implementing polite Squirrel deployments.
Whenever a device reconnects to the server, whether manually through server.connect(), or after a warm start/deep sleep and subsequent server-access attempt (eg. agent.send() or server.log()), it is notified if there is a pending impOS update.
Without polite deployment, when impOS learns that such an update is available, it immediately initiates the update procedure: impOS restarts the device in emulation of a cold boot; this causes the update to be retrieved and installed.
Polite deployment makes use of two imp API calls: server.onshutdown() and server.restart().
The first of these methods registers a function which will be called when, upon reconnecting, the device receives a message from the Electric Imp impCloud™ that an impOS update is pending. By registering a shutdown handler function, developers can delay the upgrade and run code to perform housekeeping tasks such as storing device settings in persistent storage such as external SPI flash.
Note imps with nv storage will not persist the nv contents across impOS updates, so this device-side storage feature cannot be used in this context.
Until server.onshutdown() is called, any attempt to contact the server will cause the device to reconnect and, potentially, receive an impOS update message which will cause the device to restart. As such, it is essential to call server.onshutdown() as early as possible in your application code.
The function registered using server.onshutdown() takes a single parameter, reason, into which an integer constant is passed to inform your code why the restart has been requested. These are the possible values of reason:
*SHUTDOWN_OTHER is not currently used but is reserved for future usage.
Once the application is ready for the device to be restarted, it should call the second imp API method, server.restart(). This simply causes the device’s Squirrel virtual machine to restart. This time the impOS update will be retrieved before Squirrel is started and the function registered with server.onshutdown() becomes available.
Note Polite deployment is managed entirely through Squirrel, so there may be instances when impOS updates are applied even when polite deployment support is in place. For example, if a device is power-cycled, it may update impOS before Squirrel starts. Until Squirrel is running, any handler registered with server.onshutdown() cannot be executed. In short, polite deployment is only available when Squirrel is running.
In addition, if a device is moved from one Device Group to another, that will also operate as a forced deployment.
Developers who do not need to take advantage of polite impOS deployment can simply ignore server.onshutdown(). If no restart request handler is registered, restart requests from the impCloud will be processed by the agent and device as soon as they are received.
Once a restart handler function has been called, it is up to the application to call server.restart(). In normal circumstances, the impOS update will not be applied until this method is called. However, we do not recommend delaying the update indefinitely as this could compromise device security. In addition, Electric Imp reserves the right to force essential upgrades — for example, those containing critical security updates — if the device or agent takes too long to restart and update manually.
Applications which put devices into deep sleep should ensure they make their server.restart() call before they next sleep. Waking from deep sleep is a warm start: the device’s application code virtual machine is restarted so Squirrel begins afresh and your restart request handler will need to be re-registered if it is take effect from this point on.
Devices awaking from sleep do not connect to the impCloud automatically — connections are not made until the application attempts to talk to the server. server.restart() performs the equivalent of a cold boot so that the device connects automatically and the update delivered and installed as soon as possible.
Call server.onshutdown() as soon as possible in your application code to ensure that it is ready — polite deployment is not available to your application until this imp API method is called.
Take care that device and agent restarts are suitably timed to prevent post-restart communications with their own servers and third-party services from occurring simultaneously.
Any device which is manually power-cycled will receive and apply the impOS update irrespective of your use of polite deployment, and the server.onshutdown()-registered callback will not be executed.