Microvisor Public Beta
Microvisor is in a pre-release phase and the information contained in this document is subject to change. Some features referenced below may not be fully available until Microvisor's General Availability (GA) release.
Polite deployment is the facility by which a running application is informed by Microvisor that there are application and/or Microvisor updates ready to be applied so that the application can choose to defer the installation of these updates if it is currently performing critical tasks which should not be interrupted.
By default, Microvisor applies updates as soon as they have been downloaded and verified. This involves restarting the application, and this may be undesirable in certain circumstances. Polite deployment puts the timing of update installations into the hands of the application.
Polite deployment is an opt-in feature. Developers enable it by setting specific values in their application bundles before they are uploaded for installation on Microvisor-enabled devices. Developers must also implement within the application a suitable mechanism to monitor notifications from Microvisor (so that the application is alerted when updates are pending) and code that triggers the update procedure immediately or at a time convenient to the application.
It is important to understand that whether a specific application bundle is politely deployed or not depends not on its own settings but on those of the currently running application bundle.
For example, if application 42 does not have polite deployment set, but its successor, application 43, does, then application 43 will not be installed politely. However, application 44 will be. So will application 45 — provided application 44 was uploaded with the polite deployment flag set in its manifest, as outlined in Step 2 below.
If there is no running application on the device, the first application bundle to be deployed to it will be installed immediately, even if its manifest has its polite deployment flag set. Any subsequent update will be deployed politely.
Polite deployment makes use of Microvisor's notifications mechanism. If you are unfamiliar with this system, please take a moment to review our notifications documentation.
When Microvisor has an application or Microvisor update it would like to install, and polite deployment has been enabled in that application's bundle (see below), it will issue a notification of type MV_EVENTTYPE_UPDATEDOWNLOADED. You should check for this event in your notification interrupt service routine.
This notification is only posted when application and/or Microvisor updates have been marked for polite deployment via the bundle. To receive this notification, your application needs to tell Microvisor to which notification center it should post polite deployment notifications. You do so by calling mvOpenSystemNotification(const struct MvOpenSystemNotificationParams* params, MvSystemEventHandle* handle) and passing in a pointer to a configuration structure and the address of a variable into which Microvisor will write a system event sender handle value, as demonstrated in the example code below.
On receipt of the above notification you will set a flag in the notification interrupt service routine (ISR), or enqueue an RTOS message, and exit. Your main code loop will read the flag and, if set, use its own business logic to determine when to permit the pending update to be installed and the application restarted.
If you fail to monitor polite deployment notifications from the system, and polite deployment is enabled, updates will not be applied — even if the next update disables polite deployment. You can force update installation by power-cycling the device or restarting it remotely using the Microvisor API.
To trigger the restart, call mvRestart(enum RestartMode mode). Its argument is currently a single value: MV_RESTARTMODE_AUTOAPPLYUPDATE.
It returns a value of type MvStatus. In the unlikely event that Microvisor is unable to restart the application, it will return a value indicating that this is the case and indicate why the system call failed. Otherwise, Microvisor will halt the running application (so the system call cannot return) and proceed to apply the update.
It is up to the application to call mvRestart(). In normal circumstances, Microvisor updates will not be applied until this function is called. However, we do not recommend delaying the update indefinitely as this could compromise device security. In addition, KORE reserves the right to force essential Microvisor upgrades — for example, those containing critical security updates — if the device takes too long to restart and update manually.
_86#define SYS_NT_BUFFER_SIZE_R 8 // Value in # of records, not bytes_86/*_86* Set up the system notification system -- typically in main()_86*/_86// Store the notification center handle_86MvNotificationHandle sys_notification_center_handle;_86MvSystemEventHandle sys_event_handle;_86volatile uint32_t current_notification_index = 0;_86volatile bool update_pending = false;_86_86// Central store for system notifications_86volatile struct MvNotification sys_notification_center[SYS_NT_BUFFER_SIZE_R] __attribute__((aligned(8)));_86_86// Clear the notification store_86memset((void *)sys_notification_center, 0xFF, sizeof(sys_notification_center));_86_86// Configure a notification center for system-centric notifications_86static struct MvNotificationSetup sys_notification_config = {_86 .irq = TIM1_BRK_IRQn,_86 .buffer = (struct MvNotification *)sys_notification_center,_86 .buffer_size = sizeof(sys_notification_center)_86};_86_86// Ask Microvisor to establish the notification center_86// and confirm that it has accepted the request_86enum MvStatus status = mvSetupNotifications(&sys_notification_config, &sys_notification_center_handle);_86assert(status == MV_STATUS_OKAY);_86assert(sys_notification_center_handle != 0);_86_86// Tell Microvisor to use the new notification center for system notifications_86const struct MvOpenSystemNotificationParams sys_notification_params = {_86 .notification_handle = sys_notification_center_handle,_86 .notification_tag = 0,_86 .notification_source = MV_SYSTEMNOTIFICATIONSOURCE_UPDATE_86};_86_86status = mvOpenSystemNotification(&sys_notification_params, &sys_event_handle);_86assert(status == MV_STATUS_OKAY);_86assert(sys_event_handle != 0);_86_86// Start the notification IRQ_86NVIC_ClearPendingIRQ(TIM1_BRK_IRQn);_86NVIC_EnableIRQ(TIM1_BRK_IRQn);_86_86..._86_86while(1) {_86 if (update_pending) {_86 // Update pending -- can we go ahead?_86 // NOTE `critical_task_running()` is a dummy function not provided here_86 if (!critical_task_running()) {_86 enum MvStatus status = mvRestart(MV_RESTART_AUTOAPPLYUPDATE);_86 // If the above call succeeds, the app with restart._86 // If not, report the failure code_86 char err_msg_buffer[40] = {0};_86 sprintf(buffer, "Application restart failed (code %lu)", status);_86 mvServerLog((const uint8_t*)buffer, (uint16_t)strlen(buffer));_86 }_86 }_86}_86_86..._86_86/*_86* Set up the notification ISR_86*/_86void TIM1_BRK_IRQHandler(void) {_86_86 // Check for a suitable event_86 bool got_notification = false;_86 volatile struct MvNotification notification = sys_notification_center[current_notification_index];_86 if (notification.event_type == MV_EVENTTYPE_UPDATEDOWNLOADED) {_86 // Flag there is an update pending_86 update_pending = true;_86 got_notification = true;_86 }_86_86 if (got_notification) {_86 // Point to the next record to be written_86 current_notification_index = (current_notification_index + 1) % SYS_NT_BUFFER_SIZE_R;_86_86 // Clear the current notifications event_86 // See https://www.twilio.com/docs/iot/microvisor/microvisor-notifications#buffer-overruns_86 notification.event_type = 0;_86 }_86}
The following tasks require updated Microvisor tooling that is currently in alpha release and only being made available to customers using polite deployment.
Compiled applications are uploaded as application bundles; bundles are generated from application binaries by the Microvisor tooling. To enable polite deployment, your bundles' manifests must be set accordingly: add the flag --polite-deployment to the bundle generation command:
_10microvisor app bundle /path/to/app-binary.bin /path/to/bundle.zip --polite-deployment
This will generate a bundle .zip file which you can upload to the Microvisor Cloud and then deploy to devices in the usual way. For example:
_10microvisor app upload /path/to/bundle.zip
The tooling will output the newly uploaded bundle’s SID. Use it to deploy the bundle to your device:
_10microvisor device assign {device SID} --app-sid {app bundle SID}
For more information on application bundles, please see Applications and Bundles.