How to Install the Microvisor SDK

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.

To begin developing applications for Microvisor, you first need to prepare your development environment. This guide will show you how to do so: you will install the Microvisor SDK, and essential Twilio and third-party components. When you’re done, you’ll be ready to begin work on your own Microvisor-hosted application, perhaps using our FreeRTOS demo code as a basis.

This guide is primarily aimed at developers who are new to embedded projects. Developers with extensive embedded development experience, or who have use-cases that require very specific project configurations — for example to support testing — may choose to use the guide solely as a list of prerequisites.

If you are an experienced STM32 developer, please be aware that Microvisor requires dedicated versions of some of the tools that you will be familiar with and may be expecting to use for Microvisor work, such as the STM32Cube U5 HAL. Please read this guide thoroughly to understand which of these Microvisor-specific versions you may need, and why.

Platform support

At this stage in Microvisor’s release schedule, we support Ubuntu 20.04 LTS Linux as a primary development environment. While we hope to support other platforms in due course, for now Mac and Windows users will have to choose between interacting with the Microvisor development tools through Docker or from within a virtual machine running Ubuntu. Instructions for both approaches are included below.

The following instructions assume you have a fresh Ubuntu 20.04 Desktop installation.

Inside the SDK

This section introduces the SDK and and its components. If you just want to crack on with installation, just jump down the page.

The Microvisor SDK comprises the following elements:

  • A header file declaring Microvisor’s non-secure callable (NSC) system calls and related data structures.
  • An object file which contains the entry points for Microvisor’s NSC functions.
  • A linker script which maps the memory to which user applications have access.

The following components are optional and build on the SDK:

All of these components are provided through a series of public git repositories. Dependencies are included as submodules.

To support the SDK, a small number of third-party pre-requisites are required too.

The NSC system calls

While a number of applications, particularly legacy ones, can run alongside Microvisor without being aware of its presence, to make the most of the functionality Microvisor provides, applications will need to interact with Microvisor using system calls.

Applications which make system calls will need to include the header file, mv_syscalls.h, and incorporate the object file mv_implib.o into their build process. Both files are part of the SDK.

You can learn more about the peripherals mediated by Microvisor in Develop Applications for Microvisor.

The linker script

Whether the application makes use of the Microvisor system calls or not, it will need to be built with the Microvisor SDK linker script, STM32U585xx_FLASH_mv.ld, which makes sure that the application is primed to use the STM32U585 microcontroller’s TrustZone-enabled non-secure SRAM and Flash allocated to you by Microvisor within the STM32U585.

Our recommended build management tool is CMake, and the linker script is accompanied by a CMakeLists.txt file which exports a library and linker flags to use in your application.

The Microvisor HAL

The optional Microvisor STM32U585 HAL library provides a set of convenience functions which your code can use to simplify its usage of the STM32U585’s peripherals. Most embedded developers should start off with the HAL unless they have very specific and very low-level peripheral-access requirements.

To work with a HAL in your code, you must use Twilio’s Microvisor STM32U585 HAL. STM’s generic STM32CubeU5 HAL will not work with Microvisor.

Microvisor does not allow non-secure code to access to the RCC peripheral or secure registers directly. This conflicts with a number of STM32CubeU5 HAL functions, so the Microvisor port modifies the bodies of these functions to safely intercept disallowed accesses and perform the target action in a permitted way.

This ensures that commonly called standard library functions, such as __HAL_RCC_GPIOA_CLK_ENABLE() and LL_RCC_WriteReg(), can be used without modification, and that your existing application code can largely operate as if Microvisor is not present. The intention is to make it as easy as possible to port a “bare metal” implementation to Microvisor.

The HAL also includes a header file, mv_bitops.h, which provides a comprehensive set of generically named macros for performing register operations — reading and writing registers; setting and clearing individual register bits, etc. These match equivalent STM32 HAL bit operation macros, so use of the latter can be converted to Microvisor versions just by adding the prefix MV_, e.g., SET_BIT() becomes MV_SET_BIT().

FreeRTOS demo code

Many embedded developers choose to build their IoT applications on top of a Real-time Operating System (RTOS) so that they can take advantage of the advanced services and functionality offered by the OS, such as multi-threading and scheduling. A popular RTOS for embedded products is FreeRTOS. We have provided a demo application that you can build and run on the upcoming Microvisor Nucleo Dev Board, or simply use as the basis for your own FreeRTOS-based IoT application.

The ARM CMSIS-RTOS API is used an an intermediary between the application and FreeRTOS to make it easier to swap out the RTOS layer for another should you need to do so.

Development tools

Microvisor’s development tools are used after you have generated an application build. They include tools that you use to package the built application and configuration information into a file ready for uploading to Twilio — and from there to be deployed to your devices. They also include a GDB server that will connect the standard gdb debugger to the Twilio cloud to enable remote debugging.

You use Twilio’s standard CLI tool and its Microvisor Plugin to perform these tasks.

Install the prerequisites

If you are installing under Ubuntu, please install the following components:

sudo apt install gcc-arm-none-eabi \
                 binutils-arm-none-eabi \
                 git cmake curl \

Install Docker Desktop or the Docker Engine if you plan to install the FreeRTOS demo or the HAL on Mac or Windows via Docker.

Install the SDK

You have three choices:

  • If you intend to work with an RTOS, such as FreeRTOS, you should install the demo application, which includes all the other SDK components, including the Microvisor STM32U585 HAL. Once you have built and run the demo code, you can use it as a foundation for your own application.
  • If you do not intend to work with an RTOS, install the Twilio STM32U585 HAL, which includes all the required SDK components. You can then begin building your own application.
  • Install the standalone SDK. This is an advanced, manual install option provided only for developers with specific project configuration needs and/or experience of working with Microvisor. If you do plan to install a HAL too, please use option 2 as STM’s generic U5 Cube HAL will not work with Microvisor.

Option 1: Install the FreeRTOS demo

The FreeRTOS demo is recommended as a starting point for any Microvisor-hosted application that will run under this popular RTOS. The code is provided as a standalone project: it includes the Microvisor SDK and STM32U585 HAL as git submodules.

Run the following commands. You can copy each one by clicking the copy button that appears when you mouse over each command:

git clone --recurse-submodules

If you are installing under Ubuntu, run:

  1. cd twilio-microvisor-freertos
  2. cmake -S . -B build/
  3. cmake --build build --clean-first

Alternatively, if you wish to build the demo using Docker, run the following commands:

  1. docker build --build-arg UID=$(id -u) --build-arg GID=$(id -g) \
      -t microvisor-gpio-sample-image .
  2. docker run -it --rm -v $(pwd)/:/home/ --name microvisor-gpio-sample \

The deliverable you can provision onto Microvisor will be built into build/Demo/gpio_toggle_demo.elf.

Like to be informed about new FreeRTOS demo releases, or updates to any of the other repos described here? Go to your chosen repo’s homepage — for example, — select Watch > Custom and then check Releases. You’ll receive an email notification whenever a new version of the the repo is released.

Option 2: Install the Microvisor STM32U585 HAL

Using the Microvisor-specific STM32U585 HAL in your application is optional, but we recommend it for all developers who are not planning to make use of FreeRTOS.

Run the following commands. You can copy each one by clicking the copy button that appears when you mouse over each command:

git clone --recurse-submodules

If you are installing under Ubuntu, run:

  1. cd twilio-microvisor-hal-stm32u585
  2. cmake -S . -B build/
  3. cmake --build build --clean-first

The library will be built into build/libtwilio-microvisor-hal-stm32u5.a.

The included CMakeFiles.txt is a “kitchen sink“ inclusion of the HAL. You may choose to restrict the included files from the HAL to just those your project may need. An example of this approach can be found in our FreeRTOS demo. You can then link your code against the Microvisor port of the Standard Peripheral Library.

Alternatively, you can import the entire repository instead of importing the Standard Peripheral Library.

If you wish to build the HAL library using Docker, run the following commands:

  1. docker build --build-arg UID=$(id -u) --build-arg \
      GID=$(id -g) -t twilio-microvisor-hal-stm32u5 .
  2. docker run -it --rm -v $(pwd)/:/home/ --name twilio-microvisor-hal-stm32u5 \

The file mv_prescalers.c is not required if you already have a target in your project that defines the relevant prescaler values.

Option 3: Install the NSC system calls components

Run the following command:

git clone

Using the NSC system calls components

With the repo downloaded, you can choose the best way to consume its contents within your project:

  1. Use CMake to reference the directory within your own CMake-based project’s CMakeLists.txt file by including the command add_subdirectory(<PATH_TO_TWILIO-MICROVISOR-SDK>). You must also specify the environment variable $MV_ARCH. At this time, it must be set to "stm32u5".
  2. #include the mv_syscalls.h header file in your application and link against stm32u5/mv_implib.o. Add stm32u5/STM32U585xx_FLASH_mv.ld to the linker flags in your project.

Install the development tools

Run each of the command sequences listed below to install the Microvisor development tools.

Twilio CLI

sudo apt install libsecret-1-dev
wget -qO- | sudo apt-key add -
sudo touch /etc/apt/sources.list.d/twilio.list
echo 'deb /' | sudo tee /etc/apt/sources.list.d/twilio.list
sudo apt update
sudo apt install -y twilio

Close your terminal window and open a new one, then run the following command to install the Microvisor plug-in:

twilio plugins:install @twilio/plugin-microvisor

We recommend that you update the Twilio CLI and the Plugin regularly. Your package manager will signal Twilio CLI updates. Run twilio plugins:update to install new versions of the Plugin.

DIY projects

If you prefer to start projects from scratch, you can assemble them by installing key components as git submodules and copying some dependencies from the FreeRTOS demo repo. We hope shortly to offer these by way of git templates.

To keep project dependencies up to date, run:

git submodule update --remote --recursive

A FreeRTOS project

To build a FreeRTOS project, create a directory and cd into it. Copy the ST_Code and config directories, and the CMakeLists.txt and toolchain.cmake files from the root of the FreeRTOS demo repo, and then run the following commands:

git init
git submodule add
git submodule add
git submodule update --init --recursive

Edit CMakeLists.txt to suit your project, specifying your source code directory (which will contain its own CMakeLists.txt file).

The sample code Basic HTTP Communications is a complete example of such a DIY project.

An RTOS-less project

To set up a fresh project that does not use FreeRTOS or another RTOS, create a directory and cd into it. Copy the ST_Code directory and the toolchain.cmake and CMakeLists.txt files from the FreeRTOS demo clone, and then run the following commands:

git init
git submodule add
git submodule update --init --recursive

Edit CMakeLists.txt to suit your project, and to remove the lines


and all FreeRTOS references. You can also delete both CMSIS_ directories from the ST_Code directory.

The sample code Remote Debugging Demo is a complete example of such a DIY project.