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 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.
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.
This section introduces the SDK and its components. If you just want to crack on with installation, just jump down the page.
The Microvisor SDK comprises the following elements:
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.
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.
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 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 the 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 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()
.
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 use as the basis for your own FreeRTOS-based IoT application.
The ARM CMSIS-RTOS API is used 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.
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 the Microvisor cloud — and from there to be deployed to your devices. They also include a GDB server that will connect the standard gdb
debugger to the Microvisor cloud to enable remote debugging.
You use Twilio's standard CLI tool and its Microvisor Plugin to perform these tasks.
If you are installing under Ubuntu, please install the following components:
1sudo apt install gcc-arm-none-eabi \2binutils-arm-none-eabi \3git cmake curl \4build-essential
Install Docker Desktop or the Docker Engine if you plan to install the FreeRTOS demo or the HAL on Mac or Windows via Docker.
You have three choices:
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 https://github.com/korewireless/Microvisor-Demo-CMSIS-Freertos.git
If you are installing under Ubuntu, run:
cd Microvisor-Demo-CMSIS-Freertos
cmake -S . -B build
cmake --build build --clean-first
Alternatively, if you wish to build the demo using Docker, run the following commands:
1docker build --build-arg UID=$(id -u) --build-arg GID=$(id -g) \2-t microvisor-gpio-sample-image .
1docker run -it --rm -v $(pwd)/:/home/ --name microvisor-gpio-sample \2microvisor-gpio-sample-image
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, https://github.com/korewireless/Microvisor-Demo-CMSIS-Freertos.git — select Watch > Custom and then check Releases . You'll receive an email notification whenever a new version of the repo is released.
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 https://github.com/korewireless/Microvisor-HAL-STM32U5.git
If you are installing under Ubuntu, run:
cd Microvisor-HAL-STM32U5
cmake -S . -B build
cmake --build build --clean-first
The library will be built into build/libmicrovisor-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:
1docker build --build-arg UID=$(id -u) --build-arg \2GID=$(id -g) -t microvisor-hal-stm32u5-image .
1docker run -it --rm -v $(pwd)/:/home/ --name microvisor-hal-stm32u5-lib \2microvisor-hal-stm32u5-image3
The file mv_prescalers.c
is not required if you already have a target in your project that defines the relevant prescaler values.
Run the following command:
https://github.com/korewireless/Microvisor-SDK.git
With the repo downloaded, you can choose the best way to consume its contents within your project:
CMakeLists.txt
file by including the command
add_subdirectory(<PATH_TO_MICROVISOR_SDK>)
. You must also specify the environment variable
$MV_ARCH
. At this time, it must be set to
"stm32u5"
.
#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.
You will need to install the Twilio CLI and its Microvisor plugin. You can find instructions and guidance here.
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
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:
1git init2git submodule add https://github.com/FreeRTOS/FreeRTOS-Kernel3git submodule add https://github.com/korewireless/Microvisor-HAL-STM32U54git 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.
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:
1git init2git submodule add https://github.com/korewireless/Microvisor-HAL-STM32U53git submodule update --init --recursive
Edit CMakeLists.txt
to suit your project, and to remove the lines
1ST_Code/CMSIS_RTOS_V2/cmsis_os2.c2ST_Code/CMSIS_RTOS_V2
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.
We welcome all inquiries you may have about Microvisor and its implementation, and any support questions that arise once you've begun developing with Microvisor. Please submit your queries via a KORE Wireless ticket: log in to the Kore console and click the Contact Support button in the left-hand navbar.