The Twilio CLI Microvisor Plugin
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.
Current version: 0.3.11
This utility adds Microvisor-oriented functionality to the Twilio CLI tool.
Installation
Prerequisites
The Microvisor plugin requires Twilio CLI. You can find full instructions for your platform in the Twilio CLI Quickstart guide.
Install the plugin
Run the following command:
twilio plugins:install @twilio/plugin-microvisor
Installing the plugin may result in a number of warnings being output by the installer. We are working to address this.
Update the plugin
After installation, you can keep the plugin up to date by running:
twilio plugins:update
We expect to make a number of improvements to the plugin as Microvisor continues through its pre-release phases and moves toward General Availability. We strongly recommend that you keep your installed plugin updated by running the command shown above regularly.
Plugin 0.3.10 or above is required for Microvisor 0.5.1 or above.
Usage
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.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.
apps
The apps
command provides the following sub-commands:
bundle
— Build an application bundle that can be uploaded. It has two required arguments: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:twilio microvisor:apps:bundle /path/to/bin /path/to/bundle/zip \ --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:
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.:
twilio microvisor:apps:create /path/to/app/bundle <OPTIONAL_UNIQUE_NAME>
debug
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.
twilio microvisor:debug $MV_DEVICE_SID /path/to/private/key/pem \
--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 shold be stored:twilio microvisor:debug:generate_keypair \ --debug-auth-privkey=/path/to/private/key/pem \ --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.
deploy
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.
Examples
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:
twilio microvisor:deploy . --devicesid $MV_DEVICE_SID \
--publickey ~/rdkeys/pukey.pem \
--privatekey ~/rdkeys/pvkey.pem
Build and deploy the app in the working directory, generating keys and specifying paths for those keys:
twilio microvisor:deploy . --devicesid $MV_DEVICE_SID \
--genkeys --publickey ~/rdkeys --privatekey ~/rdkeys \
Just build the current code:
twilio microvisor:deploy . --build
Auto-incrementing build numbers
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.
info
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.twilio microvisor:info:sid /dev/cu.usbmodem14101 Device SID: UVxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
version
— Display the version of Microvisor installed on the connected device.twilio microvisor:info:version /dev/cu.usbmodem14101 Microvisor version: 0.5.1 Build date: Tue Mar 7 12:39:36 2023
On Linux, you will need to perform these commands as root or as a member of the group dialout
. To add a user to that group, open a terminal and run:
sudo usermod -a -G dialout <username>
If you are in a GUI, you will need to log out and then back in again for this to take effect.
logs
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:
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: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:
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.
Only a single log stream can be open to a particular device. If you open a second terminal window and use a new instance of the Twilio CLI to view logs from the same device, the first connection will be closed automatically. You can, however, open multiple streams from multiple devices.
Crash reports
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
Connection established
Crash Report:
{
"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
}
}
Connection dropped
JSON
{"category":"connection","connection_id":"c12cfe06-2f7b-11ed-af0e-0a9fcaaa3415","device_timestamp_usecs":null,"message":"Connection established","timestamp":"2022-09-08T13:40:08.731082Z"}
{"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"}
wificonfig
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.
On Linux, you will need to perform these commands as root or as a member of the group dialout
. To add a user to that group, open a terminal and run:
sudo usermod -a -G dialout <username>
If you are in a GUI, you will need to log out and then back in again for this to take effect.
get
— Get and display the current WiFi credentials.
twilio microvisor:wificonfig:get /path/to/device
set
— Set the device’s WiFi credentials, passed as follows:
twilio microvisor:wificonfig:set <SSID> <PASSWORD> /path/to/device
clear
— Clear any WiFi credentials stored on the device.
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
$ twilio microvisor:wificonfig:ports Available ports on your computer: 1. /dev/ttyACM0
macOS
$ twilio microvisor:wificonfig:ports Available ports on your computer: 1. /dev/tty.usbmodem14244401
Windows
C:\Users\user>twilio microvisor:wificonfig:ports Available ports on your computer: 1. COM1 2. COM4
To determine which Windows COM port to use, open Device Manager after you have connected your Microvisor device and check which port listed under Ports (COM and LPT) is labelled USB Serial Port (COMx). This is the COM port you should pass into the get
, set
, and clear
sub-commands.
The list of properties included in the log messages output as JSON is still being defined and is therefore subject to change. You should not build against the following description, which is intended for information purposes only.
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.
Property Name | Value(s) | Notes |
---|---|---|
category |
connection |
Device-cloud connection status |
app_logging |
Application logging messages | |
ota_update |
Microvisor update messages | |
message |
Text | The exact message depends on the value of category . App logging values are the text issued by the application using mvServerLog() . Connection messages indicate connection status updates |
timestamp |
A Unix timestamp | The date and time at which the message was emitted by Twilio |
Changelog
0.3.11 May 15, 2023
- 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.
0.3.10 March 20, 2023
- 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.
0.3.9 February 1, 2023
- Bug fixes and internal changes.
0.3.8 January 10, 2023
- JSON output reflects Twilio CLI standard format.
- Add WiFi credential get, set, and clear functionality.
- Application logging fixes.
- Dependency updates.
0.3.7 September 22, 2022
- Add bundle creation. Note The Python-based bundler tool is now deprecated.
Note Plugin 0.3.6 was an unreleased internal development version.
0.3.5 September 13, 2022
- Change output switch
-o=json|text
to match the standard Twilio CLI name. This is a breaking change if you are using the existing switch,--output
.
0.3.4 September 12, 2022
- Add app uploading.
- Add application crash reports to log output.
- Add timestamp and message type to text log output.
- Add remote debugging encyption key generation.
Note Plugins 0.3.1-3 were unreleased internal development versions.
0.3.0 July 29, 2022
- Support Microvisor application logging system calls.
0.2.0 May 24, 2022
- Support Microvisor remote debugging with
debug
command. - Use end-to-end encryption for remote debugging sessions. BREAKING CHANGE
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.