Get Started with Microvisor

This Quick Start assumes you have a Twilio account and a Microvisor Nucleo Development board that is powered up and connected to the Internet using the supplied Super SIM.

The primary Microvisor development platform is Ubuntu 20.0.4.

Windows

The recommended solution for working with Microvisor on Windows 10 and 11 is via Windows Subsystem for Linux 2 (WSL). You will need Administrator privileges to install WSL.

1. Open an Administrator-level Powershell or Command Prompt instance.
2. Run wsl --install -d Ubuntu-20.04.
3. Open the Ubuntu 20.04 LTS shell from your Start menu.
4. Follow the command line instructions.

Alternatively, you can use Docker. You can also try native tools, but this is unsupported at this time.

macOS

The recommended solution for working with Microvisor on Mac is Docker, as outlined below. However, if you’re happy not to be supported, you can use native tools on macOS.

Command line

1. Install the prerequisites

sudo bash -c 'apt update && apt install -y gcc-arm-none-eabi binutils-arm-none-eabi \
  build-essential libsecret-1-dev cmake curl git jq wget'

2. Install the Twilio CLI

curl -sL https://twilio-cli-prod.s3.amazonaws.com/twilio_pub.asc | sudo apt-key add -
sudo touch /etc/apt/sources.list.d/twilio.list
echo 'deb https://twilio-cli-prod.s3.amazonaws.com/apt/ /' | sudo tee /etc/apt/sources.list.d/twilio.list
sudo apt update
sudo apt install -y twilio

3. Install the Twilio CLI Microvisor Plugin

Close your terminal window or tab, and open a new one. Now run:

twilio plugins:install @twilio/plugin-microvisor

4. Set up the Twilio CLI

twilio login

Enter your account SID and your account Auth Token, and provide an name for your profile when asked to do so.

twilio profiles:use <YOUR_PROFILE_NAME>

5. Set environment variables

Enter the following command to get your target device’s SID:

twilio api:microvisor:v1:devices:list

Set your device’s SID as an environment variable. It should be added to your shell profile:

export MV_DEVICE_SID=UVxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

6. Clone the Microvisor FreeRTOS demo

git clone --recurse-submodules https://github.com/twilio/twilio-microvisor-freertos
cd twilio-microvisor-freertos

7. Build and deploy the demo

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

Docker

This assumes you have Docker Desktop installed on your system and that you have started its daemon.

1. Set environment variables

Set your Twilio credentials as environment variables. You can get the first two from your Twilio Console account dashboard. The QR code on the back of your board and on the anti-static bag in which it shipped also contains your NDB’s SID. Scan the code with your mobile phone and a suitable app, and the board’s SID is the third /-separated field.

Mac

export TWILIO_ACCOUNT_SID=ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
export TWILIO_AUTH_TOKEN=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
export MV_DEVICE_SID=UVxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

They should be added to your shell profile.

Windows Powershell

$env:TWILIO_ACCOUNT_SID="ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
$env:TWILIO_AUTH_TOKEN="xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
$env:MV_DEVICE_SID="UVxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Windows Command Prompt

set TWILIO_ACCOUNT_SID=ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
set TWILIO_AUTH_TOKEN=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
set MV_DEVICE_SID=UVxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

2. Build the image

docker build --build-arg UID=$(id -u) --build-arg GID=$(id -g) \
  -t microvisor-freertos-image .

3. Run the build

docker run -it --rm -v $(pwd)/:/home/mvisor/project/ \
  --env-file env.list \
  --name microvisor-freertos microvisor-freertos-image

Under Docker, the demo is compiled, uploaded and deployed to your development board. It also initiates logging — hit ctrl-c to break out to the command prompt.