The Twilio CLI Microvisor Plugin

This utility adds Microvisor-oriented functionality to the Twilio CLI tool.

The Microvisor plugin requires Twilio CLI. You can find full instructions for your platform in the Twilio CLI Quickstart guide.

Run the following command:

twilio plugins:install @twilio/plugin-microvisor

After installation, you can keep the plugin up to date by running:

twilio plugins:update

The plugin operates with commands and sub-commands, separated by colons, and entered this way:

twilio microvisor:<COMMAND>:<SUB_COMMAND>

The plugin provides the following commands:

• apps — Upload application bundles.
• debug — Enable the decryption of remote debugging signals from a Microvisor-enabled device.
• deploy — Build and deploy an application to a specified Microvisor-enabled device.
• factory — Microvisor factory process tools.
• info — Get information from a connected Microvisor-enabled device.
• logs — View messages streamed from a Microvisor-enabled device.
• wificonfig — Set and check a Microvisor-enabled device's stored WiFi credentials.

The apps command provides the following sub-commands:

• bundle — Build an application bundle that can be uploaded. It has two required arguments:

  Copy code block

  twilio microvisor:apps:bundle /path/to/bin path/to/bundle/zip

  The latter is the path at which the bundle will be created: the path you will subsequently pass into the create call as shown below.
  If you are using remote debugging, include the debugging public key with the --debug-auth-pubkey switch as follows:

  Copy code block

  1
  twilio microvisor:apps:bundle /path/to/bin /path/to/bundle/zip \
  2
    --debug-auth-pubkey=/path/to/public/key/pem

  You can generate a suitable private-public key pair with the debug:generate_keypair sub-command.

• create — Upload an application bundle. It takes as its argument a path to the application bundle to upload:

  Copy code block

  twilio microvisor:apps:create /path/to/bundle/zip

  
  If you specify a path that doesn't reach a bundle file, or the uploaded file is not a bundle, an error will be thrown.
  Optionally, you may also provide a unique friendly name to help you locate and reference the bundle in future:

  Copy code block

  twilio microvisor:apps:create /path/to/app/bundle <OPTIONAL_UNIQUE_NAME>

  Optionally, add --bundle-out and provide a path to which a signed version of the bundle will be written:

  Copy code block

  twilio microvisor:apps:create /path/to/app/bundle --bundle-out /path/to/write/signed/bundle

The debug command takes a device SID and a path to a remote debugging private key as its arguments. For more information on why this key is required and how it is generated, please see Microvisor Remote Debugging.

twilio microvisor:debug $MV_DEVICE_SID /path/to/private/key/pem

Your call may also include the --listen-port flag, which is used to select the port through which debugging data will flow.

1
twilio microvisor:debug $MV_DEVICE_SID /path/to/private/key/pem \
2
  --listen-port=<PORT_NUMBER>

The default port is 8001. If you specify an alternative port number, you will need to update your .gdbinit file or run the command

target remote localhost:<PORT_NUMBER>

within gdb.

It also has the following sub-commands:

• generate_keypair — Generate private and public remote debugging encryption keys. It takes two arguments: paths to where the generated private and public keys should be stored:

  Copy code block

  1
  twilio microvisor:debug:generate_keypair \
  2
    --debug-auth-privkey=/path/to/private/key/pem \
  3
    --debug-auth-pubkey=/path/to/public/key/pem

  If you don't provide either or both key paths, your current working directory will be used.

This command provides a streamlined application build and deploy flow based on the standard Microvisor CMake-based workflow. It has no sub-commands, but takes the path to a CMake project directory (i.e., the directory containing the root CMakeLists.txt file) as a required argument.

The --devicesid switch is mandatory in cases where a deploy will take place, i.e., the call is made without the -b flag. It takes as a value the SID of the device you wish to deploy code to.

The deploy command also provides the following optional flags and switches:

• -b, --build — Build without deploying.
• -c, --clean — Clean the build folder first.
• -d, --deploy — Deploy the most recent build without rebuilding.
• --genkeys — Generate remote debugging key.
• --privatekey=``<value> — Path to your private key. Default: none.
• --publickey=``<value> — Path to your public key. Default: none.
• --log — Start logging after a deploy and/or build.
• --logonly — Start logging immediately without building or deploying.

The --privatekey and --publickey options can take paths to pre-existing keys or, if the --genkeys switch is included, will be used as paths to which the generated keys will be written. By default, plugin-generated keys are placed in the build directory.

Build and deploy the app in the working directory:

twilio microvisor:deploy . --devicesid $MV_DEVICE_SID

Build and deploy the app in the working directory, adding remote debugging keys, and initiating logging immediately:

twilio microvisor:deploy . --devicesid $MV_DEVICE_SID --genkeys --log

Build and deploy the app in the working directory, using pre-existingh remote debugging keys:

1
twilio microvisor:deploy . --devicesid $MV_DEVICE_SID \
2
  --publickey ~/rdkeys/pukey.pem \
3
  --privatekey ~/rdkeys/pvkey.pem

Build and deploy the app in the working directory, generating keys and specifying paths for those keys:

1
twilio microvisor:deploy . --devicesid $MV_DEVICE_SID \
2
  --genkeys --publickey ~/rdkeys --privatekey ~/rdkeys \

Just build the current code:

twilio microvisor:deploy . --build

From version 0.3.11, the plugin will automatically increment build numbers when they are defined in the application-level CMakeLists.txt file as follows:

set(BUILD_NUMBER "0")

The current build number is available to code by importing the header file app_version.h as the constant BUILD_NUM. This is demonstrated in the sample applications.

The factory command provides tools required by the Microvisor factory process by which devices on the assembly line are prepared for end-use.

• image — Generate an application SPI flash image for factory installation. It has one required argument:

  Copy code block

  twilio microvisor:factory:image /path/to/write/image

  The value is the path at which the image will be created. In addition, you will need to provide values for these flags:

  • --application — The path to your application bundle.
  • --application-test — The path to your application test bundle.
  • --microvisor — The path to a Microvisor kernel bundle, provided by us.
  • --microvisor-test — The path to a Microvisor kernel test bundle, provided by us.

  An additional, optional flag --purpose defaults to the value factory. This flag should not be used. It is intended to support alternative installation pathways which will be documented in due course.

To use the following sub-commands, connect a USB Micro A cable between your computer and the Nucleo Development Board's CONTROL port, then press the board's RESET button. The board's SYSTEM LED will turn solid blue and your application will halt.

The info command provides the following sub-commands, all of which require you to pass the Unix path to the device file, e.g., /dev/tty.usbmodem14244401 or /dev/ttyACM0.

If you are using Windows, replace /path/to/device in the following sub-commands with the COM port, e.g., COM7. See the wificonfig:ports sub-command, below, for more information.

• sid — Display the connected device's SID.

  Copy code block

  1
  twilio microvisor:info:sid /dev/cu.usbmodem14101
  2
  Device SID: UVxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

• version — Display the version of Microvisor installed on the connected device.

  Copy code block

  1
  twilio microvisor:info:version /dev/cu.usbmodem14101
  2
  Microvisor version: 0.5.1
  3
  Build date: Tue Mar  7 12:39:36 2023

sudo usermod -a -G dialout <username> 

The logs command provides the following sub-commands:

• stream — Initiate log streaming. It takes as its argument a device SID — the Microvisor-enabled device from which you wish to receive log messages:

  Copy code block

  twilio microvisor:logs:stream $MV_DEVICE_SID

  If you specify a device that isn't associated with your account, an Unknown device SID error will be thrown.
  Your call may also include the -o flag, which is used to output log messages either in plain text (the default) or in JSON format:

  Copy code block

  twilio microvisor:logs:stream $MV_DEVICE_SID -o=json

  If you select JSON output, you can pipe the output of the command through the JQ utility to present the JSON in a more reader-friendly form:

  Copy code block

  twilio microvisor:logs:stream $MV_DEVICE_SID -o=json | jq

  The contents of the JSON payload are described below. The plain text output is the value of a message object's message property.

The log output includes the reports issued by Microvisor when an application has crashed. Currently reports are presented in JSON form, and this is the case whether you are outputting to plain text or JSON. For the former, the report JSON is prettified; for the latter, whitespace is removed. For example:

Text

1
Connection established
2
Crash Report:
3
{
4
  "basic_registers": {
5
    "lr": 134219695,
6
    "pc": 134218520,
7
    "r0": 536870912,
8
    "r1": 0,
9
    "r12": 134219640,
10
    "r2": 0,
11
    "r3": 0,
12
    "xpsr": 1761608192
13
  },
14
  "crash_reason": "CPU_FAULT",
15
  "extended_registers": {
16
    "r10": 134219640,
17
    "r11": 134219640,
18
    "r4": 134219640,
19
    "r5": 134219640,
20
    "r6": 134219640,
21
    "r7": 537395196,
22
    "r8": 134219640,
23
    "r9": 134219640,
24
    "sp": 537395160
25
  },
26
  "fast_interrupt_data": null,
27
  "fault_registers": {
28
    "bfar": 0,
29
    "cfsr": 0,
30
    "fault": 7,
31
    "hfsr": 0,
32
    "mmfar": 0,
33
    "sfar": 0,
34
    "sfsr": 72,
35
    "shcsr": 0
36
  },
37
  "gtzc_registers": null,
38
  "special_registers": {
39
    "control": 0,
40
    "msp": 537395160,
41
    "msplim": 0,
42
    "psp": 0,
43
    "psplim": 0
44
  }
45
}
46
Connection dropped

JSON

1
{"category":"connection","connection_id":"c12cfe06-2f7b-11ed-af0e-0a9fcaaa3415","device_timestamp_usecs":null,"message":"Connection established","timestamp":"2022-09-08T13:40:08.731082Z"}
2
{"category":"app_crash","connection_id":"c12cfe06-2f7b-11ed-af0e-0a9fcaaa3415","device_timestamp_usecs":null,"message":"{\"basic_registers\":{\"lr\":134219695,\"pc\":134218520,\"r0\":536870912,\"r1\":0,\"r12\":134219640,\"r2\":0,\"r3\":0,\"xpsr\":1761608192},\"crash_reason\":\"CPU_FAULT\",\"extended_registers\":{\"r10\":134219640,\"r11\":134219640,\"r4\":134219640,\"r5\":134219640,\"r6\":134219640,\"r7\":537395196,\"r8\":134219640,\"r9\":134219640,\"sp\":537395160},\"fast_interrupt_data\":null,\"fault_registers\":{\"bfar\":0,\"cfsr\":0,\"fault\":7,\"hfsr\":0,\"mmfar\":0,\"sfar\":0,\"sfsr\":72,\"shcsr\":0},\"gtzc_registers\":null,\"special_registers\":{\"control\":0,\"msp\":537395160,\"msplim\":0,\"psp\":0,\"psplim\":0}}","timestamp":"2022-09-08T13:40:09.028666Z"}

The wificonfig command provides tools to allow you to get, set, and clear WiFi credentials stored on a Microvisor device.

To use these commands, connect a USB Micro A cable between your computer and, for example, the Nucleo Development Board's CONTROL port, then press the board's RESET button. The board's SYSTEM LED will turn solid blue and your application will halt.

The wificonfig command has the following sub-commands, all of which require you to pass the Unix path to the device file, e.g., /dev/tty.usbmodem14244401 or /dev/ttyACM0.

If you are using Windows, replace /path/to/device in the following sub-commands with the COM port, e.g., COM7. See the ports sub-command, below, for more information.

sudo usermod -a -G dialout <username> 

• get — Get and display the current WiFi credentials.

  Copy code block

  twilio microvisor:wificonfig:get /path/to/device

• set — Set the device's WiFi credentials, passed as follows:

  Copy code block

  twilio microvisor:wificonfig:set <SSID> <PASSWORD> /path/to/device

• clear — Clear any WiFi credentials stored on the device.

  Copy code block

  twilio microvisor:wificonfig:clear /path/to/device

There is an additional sub-command which does not require a device path or any other argument. Indeed it is intended to help you locate your connected Microvisor device by listing the serial devices currently connected to your computer:

• ports — List currently available device paths: Linux

  Copy code block

  1
  $ twilio microvisor:wificonfig:ports
  2
  Available ports on your computer:
  3
  1. /dev/ttyACM0

  macOS

  Copy code block

  1
  $ twilio microvisor:wificonfig:ports
  2
  Available ports on your computer:
  3
  1. /dev/tty.usbmodem14244401

  Windows

  Copy code block

  1
  C:\Users\user>twilio microvisor:wificonfig:ports
  2
  Available ports on your computer:
  3
  1. COM1
  4
  2. COM4

You can optionally set the log:stream command to output log messages in their source form, which is JSON. The default output mode emits the value of one of the JSON's properties, message. The other properties can be accessed by adding -o=json to the command.

• Further support for Factory Provisioning image creation.

• Initial support for Factory Provisioning image creation.
• Update WiFiConfig commands to use binary messaging.

• Add auto-incrementing build count to the deploy command.
• Compiler and linker output shown during deploy build rather than afterwards.
• Add dependency pre-flight checks to the deploy command.
• Pass the debug flag setting on to sub-commands.
• Better Windows support; exit on an unsupported platform.
• User permissions checking and warning on Linux for the wificonfig command.
• The create command issues signed bundles.

• Provide application deploy functionality based on the standard Microvisor demo code workflow.
• Provide device SID and Microvisor version information.
• Updated bundle encryption code to support Microvisor 0.5.1.

• Bug fixes and internal changes.

• JSON output reflects Twilio CLI standard format.
• Add WiFi credential get, set, and clear functionality.
• Application logging fixes.
• Dependency updates.