Menu

Expand
Rate this page:

Applications and Bundles

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.

Application code is delivered to Microvisor-based devices in the form of Bundles. As a developer, you will use the Microvisor toolchain to create a bundle from your latest application build, upload it to the Twilio cloud, and trigger its deployment it to your development devices. Subsequent code changes follow the same path, and your final production release will also be transferred to devices on the assembly line by way of a bundle. Later, devices in the field will receive code updates in the form of bundles.

What is a bundle?

A bundle is how application code, generated as a linkable binary, is packaged for use by Microvisor. Bundles are zip files. The application code these archives contain is sliced up into a series of non-overlapping, discrete blocks called Layers. This allows bundles to be more readily transferred to devices over low-bandwidth connections. If the download is interrupted, Microvisor needs only reacquire the current layer, not those that preceded it. It also allows layers to be installed in any order. The layer files are generated by the bundle creation tool.

A Microvisor bundle's structure

A bundle’s layers are enumerated in its Manifest, a signed file that also includes metadata, such as the application’s debugging policy, or network configuration information. Microvisor downloads the manifest first and uses it to determine which layers it needs to retrieve.

What is a layer?

A layer is a block of opaque code that is stored in the cloud for subsequent installation in a device’s flash. The bundle’s manifest lists all the layers that make up the application. Each entry in the list includes the layer’s SHA-256, which Microvisor uses to request the required layer from the server.

As the developer, it’s up to you whether layers are encrypted or not. Layers can be encrypted by supplying a private key when the bundle is created. All of a bundle’s layers are encrypted with the same key. If a layer is encrypted, then its entry in the manifest will indicate how the code is to be decrypted by Microvisor after it has been downloaded. This indication is not a cryptography key itself but a reference to a public key that must already be present on the device and which will be used to decrypt the layer.

Whether the referenced layer is encrypted or not, the layer entry in the manifest also includes the layer’s SHA. We’ve already seen that this is used to request the layer from the server. It is also used to confirm that the layer has not been tampered with in flight and is safe to process. The authenticity of the recorded SHA itself is determined by verifying the manifest’s own signature; Microvisor does this when it retrieves the bundle.

Finally, the layer entry specifies where the layer’s bytes will eventually be written to in the device once the layer has been verified as safe to install. This indicates the storage medium of the device — for example, the STM32U585 microcontroller’s internal flash for a code update, or internal or external flash for application data. The address at which the code will be written, and its length within the bounds of the medium, are included too. Layer location is typically set by the bundle creation tool using data from the build process, but it can be specified manually.

How is the bundle processed?

Let’s say you have updated, built and signed a new version of your application. You then use the Twilio CLI tool and version 0.3.7 or above of its Microvisor Plugin to generate a bundle. Next, you use the Microvisor Plugin to upload the bundle to Twilio.

You deploy the bundle using the Twilio CLI to instruct Twilio to signal specified devices that an update has been staged for them to download.

On each device, Microvisor downloads the bundle’s manifest and verifies its authenticity by signature. It then confirms that all the decryption keys referenced in the manifest’s list of layers are present on the device. It will also check the bundle metadata to determine whether there are any other factors it needs to consider before proceeding with layer processing, such as whether remote debugging has been permitted for this build.

Microvisor then parses the manifest’s layer list and uses it to request each layer and store them in the QSPI staging area. Each layer is encrypted and authenticated using fresh keys generated for this purpose. Layers may be downloaded in any order, so you should not anticipate any specific sequence to layers’ arrival on the device. You cannot specify the layer download sequence.

When all of the update’s layers have been downloaded, Microvisor shuts down the application. It then works through the layers in the QSPI staging area. Microvisor decrypts each one using the keys generated when the layer was written to QSPI and then hashes it. It compares this value with the layer’s hash from the manifest; if they match, Microvisor moves on to the next layer. Once it has verified all the layers, Microvisor writes each layer to the location specified in the manifest.

When all the layers have been processed, and any metadata-specified configuration changes have been applied, Microvisor starts the updated application.

If any of the authenticity checks fail, or required keys are not present on the device, the installation process as whole fails. This ensures that updates are only ever installed fully.

Bundle upload limits

We expect to implement limits on the number of bundles you can have stored in the Twilio cloud at any one time, and the upload facility will also be rate-limited. The details of any such limitations have yet to be determined, but we will publish details as the Microvisor beta program progresses toward GA.

Create and upload bundles

You can create an application bundle and upload it to Twilio with the Twilio CLI tool and version 0.3.7 or above of the Microvisor Plugin.

Compiling your application with the Microvisor tools generates a new .bin file. If you build the Microvisor FreeRTOS Demo code, for example, the compiled .bin file will be located here:

twilio-microvisor-freertos/build/Demo/gpio_toggle_demo.bin

To bundle the compiled binary, run this command:

twilio microvisor:apps:bundle twilio-microvisor-freertos/build/Demo/gpio_toggle_demo.bin \
  twilio-microvisor-freertos/build/Demo/gpio_toggle_demo.zip

The new bundle can then be found at the location specified in the second argument. To upload it, run:

twilio microvisor:apps:create twilio-microvisor-freertos/build/Demo/gpio_toggle_demo.zip

Once uploaded, the application contained in the bundle is represented by a Microvisor API App resource, for which a new instance is been created when the app is uploaded. The new App’s details are returned by the upload request; these include the App’s SID, which can be used to deploy the App to devices.

You can also get the App’s SID by listing the Apps currently associated with your account:

twilio api:microvisor:v1:apps:list

To avoid using SIDs, you may choose to provide the App with a unique friendly name to make it easier to identify in future. For example:

twilio microvisor:apps:create /path/to/bundle <UNIQUE_APP_NAME>

You should view this name as the indentifier of a specific build, not of the application as a whole.

App deployment

To deploy an App to a Microvisor-empowered device, send a request to the Microvisor API Device resource that represents your hardware:

twilio api:microvisor:v1:devices:update --sid=$MV_DEVICE_SID \
  --target-app=<APP_SID_OR_NAME>

If you don’t have the Device SID handy, use the Twilio CLI to list your devices:

twilio api:microvisor:v1:devices:list

The device will be signalled that an application update is pending, and Microvisor will begin the download process, as described earlier.

Python utility

The following Python program can be used to bulk delete old bundles during development. By default, “stale” bundles — those uploaded more than 24 hours earlier — are automatically deleted. If a stale bundle is installed on a device, it cannot be deleted and is listed as such.

The script assumes you have your Twilio login credentials set as environment variables: $TWILIO_ACCOUNT_SID and $TWILIO_AUTH_TOKEN.

#!/usr/bin/env python3

import os
import sys
import json
import requests
from requests.auth import HTTPBasicAuth
from datetime import datetime, timedelta

list_only = False
app_list = None
to_delete = []
url = "https://microvisor.twilio.com/v1/Apps"
auth = HTTPBasicAuth(os.environ["TWILIO_ACCOUNT_SID"], os.environ["TWILIO_AUTH_TOKEN"])

if len(sys.argv) > 1:
  for index, item in enumerate(sys.argv):
    if item.lower() in ("-h", "--help"):
      print("Usage:   apps [--delete]")
      print("Options: --delete / -d   Delete all stale apps.")
      print("Stale apps are those more that 24 hours old. Strale apps")
      print("that are still assigned to a device will not be deleted")
      sys.exit()
    if item.lower() in ("-d", "--delete"):
      list_only = False
    if item.lower() in ("-l", "--list"):
      list_only = True

print("Listing your Microvisor applications...")
date_now = datetime.now()
resp = requests.get(url, auth=auth)
if resp.status_code == 200:
  try:
    app_list = resp.json()
    if "apps" in app_list:
      for app in app_list["apps"]:
        sid = app["sid"]
        date_then = datetime.strptime(app["date_created"], '%Y-%m-%dT%H:%M:%SZ')
        if date_now - date_then >= timedelta(days=1):
          to_delete.append(sid)
          print(sid,"is STALE")
        else:
          print(sid,"is OK")
  except Exception as e:
    print("[ERROR] Could not parse response from Twilio", e)
else:
  print("[ERROR] Unable to access your apps")

if list_only:
  sys.exit()

if len(to_delete) > 0:
  print("Deleting stale apps...")
  for sid in to_delete:
    resp = requests.delete(url + "/" + sid, auth=auth)
    if resp.status_code == 204:
      print(sid, "DELETED")
    else:
      print(sid, "NOT DELETED (" + str(resp.status_code) + ")")
Rate this page:

Need some help?

We all do sometimes; code is hard. Get help now from our support team, or lean on the wisdom of the crowd by visiting Twilio's Stack Overflow Collective or browsing the Twilio tag on Stack Overflow.

Thank you for your feedback!

Please select the reason(s) for your feedback. The additional information you provide helps us improve our documentation:

Sending your feedback...
🎉 Thank you for your feedback!
Something went wrong. Please try again.

Thanks for your feedback!

Refer us and get $10 in 3 simple steps!

Step 1

Get link

Get a free personal referral link here

Step 2

Give $10

Your user signs up and upgrade using link

Step 3

Get $10

1,250 free SMSes
OR 1,000 free voice mins
OR 12,000 chats
OR more