Menu

Expand
Rate this page:

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.7

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.

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.
  • logs — View messages streamed from a Microvisor-enabled device.

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.

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"}

The 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
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.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

0.1.0-0.1.2 April 27, 2022

  • Initial release and follow-up bug-fixes.
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