Microvisor Private Beta
Microvisor is in a pre-release phase and the information contained in this document is therefore provisional and subject to change. Some features referenced below may not yet be available in or supported by the current version of the Microvisor system calls or REST API.
The Twilio Microvisor Nucleo Development Board (NDB) is a complete evaluation and development platform for Twilio Microvisor and the STMicroelectronics STM32U585 microcontroller. It is based on the familiar STMicroelectronics Nucleo form-factor. You will use it to explore the Microvisor platform, and to develop and prototype your IoT applications.
This Quick Start Guide will help you get your NDB powered, connected, and running a sample application that you will deploy to the board over the air via the Twilio cloud.
Your NDB, which has been pre-registered with your Twilio account, comes with the following items:
- A USB-C cable to power the NDB.
- A USB AC power adapter.
- A Quectel EG21-G global cellular module PCIe card.
- A cellular antenna and connector cable.
- A Twilio Super SIM.
The supplied AC adapter is optional, but do not run the Nucleo board from a USB port on your computer if it is not able to deliver at least 15W (3A at 5V) peak. The Nucleo board draws more power than some older computers’ USB ports are usually able to deliver.
You will also need a Twilio account. Sign up now if you don’t have one.
Your NDB comes with a Twilio Super SIM that has been set up for you to provide you with global cellular connectivity. The SIM has already been fitted into your board, so you are ready to go.
- Unpack the cellular modem card and fit its connector into the slot on the NDB:
- Push the card gently down onto the board until the two restraining clips snap to hold it firmly in place:
- Fit the antenna cable’s female u.FL connector to the male connector on the modem card marked MAIN:
- Screw the large antenna onto the board’s jack:
- Remove the nano-size SIM card from the Super SIM packaging and slot it into the receptacle on the NDB. The contacts should be face down, and the edge with the notch inserted first. This may have been done for you:
- Plug in the AC adapter and use the USB-C cable to power the NDB:
Do not try to power the NDB through the Micro USB port, marked DEBUG. This connector is not able to deliver power to the board. It is currently not enabled and is reserved for future use.
On your first power up, it can take the cellular module a significant amount of time — 10 minutes or more — to attach to the network. See below for the signals shown on the NETLIGHT LED.
The Microvisor application development process goes like this. You will use your computer to build new versions of your application. You run each new build through Microvisor’s bundle creation tool to generate the file that will be uploaded to the Twilio Cloud from where it will be deployed to the device or devices that you specify, such as your NDB, at a time you choose.
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 Windows and macOS users will have to choose between interacting with the Microvisor development tools through Docker or from within a virtual machine running Ubuntu.
The first thing to do is set up your computer for Microvisor application development. Open up a terminal and run the following command sequences.
sudo apt install gcc-arm-none-eabi binutils-arm-none-eabi \ python3 python3-pip build-essential protobuf-compiler \ libsecret-1-dev cmake curl git jq
pip3 install cryptography protobuf~=3.0
wget -qO- 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
twilio plugins:install @twilio/plugin-microvisor
twilio login. You will be asked for your account SID and your account Auth Token, both of which you can call up from the Console if you don’t have them handy. Do keep them nearby — you’ll need them in the next section. You will also be prompted to enter a ‘shorthand identifier’, a local ID for your credentials. Enter your initials or any phrase you prefer.
git clone --recurse-submodules https://github.com/twilio/twilio-microvisor-freertos
Before you build your first application, let’s go on a quick tour of the NDB’s key features:
- GPIO header.
- Antenna jack.
- Reset button.
- Network activity LED.
- Power brownout LED.
- Application-controllable LED.
- STM32U585 with Microvisor.
- Quectel EG21-G global cellular modem.
- USB-C power input.
- Twilio Super SIM.
- ESP32 WiFi/BLE module.
- RJ-45 Ethernet jack.
The NDB incorporates an ESP32 WiFi/BLE module and Ethernet jack. These features have not yet been enabled, but will be activated in a future Microvisor pre-release.
The NDB has three LEDs, marked with the labels listed below, to provide you with status feedback:
- SYSTEM — This indicator signals system status using patterns of colors and flashes. For example, it slowly flashes green when the board is connected. The more commonly encountered patterns are shown below.
It’s important to understand that a pattern may take longer to complete than the time Microvisor spends in the indicated state. As soon as it moves to another state, Microvisor will signal the new state, even if it has not yet finished the previous state’s pattern. This means that you should watch this LED for error or success conditions — a pattern being displayed repeatedly without change — not to observe transient states.
- USER — This is a GPIO connected single-color LED that’s just for you and your application. It is connected to the STM32U585’s GPIO pin PA5. Set this pin high to turn on the LED. You’ll see this in operation in the sample application you’ll deploy shortly:
- NETLIGHT — This is the modem’s network activity indicator. You can see it in the picture below. This LED will blink slowly while the device is idling (long flash) or searching for the network (short flash), and blink rapidly during data transfer.
- BROWNOUT — This will light when the modem’s power draw has exceeded the power supplied to the board. You will usually see this happen when you are powering the board with your own AC adapter and it is not delivering sufficient power. Make sure your adapter delivers at least 15W (3A at 5V). The adapter and cable supplied with the NDB is rated to meet the peak power draw of the board and modem, so we recommend you use this in place of your own.
All of the STM32U585’s GPIO pins that are available to the user are broken out through the NDB’s two headers, marked CN11 and CN12. Any pins not present are reserved for Microvisor’s use both on this board and on customer implementations. Please see the STM32U585 data sheet for the functionality enabled at each pin. The headers are connected as follows (click on the image for a large view):
NC = Not Connected
CN11 pin 33 is not connected, but bridging W1 will connect it to VDD BAT IN.
You can manually trigger a device reboot at any time by pushing the RESET button:
The table below shows you some color and blink patterns that you may see on the SYSTEM LED. The first six of these signal the NDB’s progress as it comes online. This usually happens quite quickly so you may not see all of them before you see the steady green blink that indicates the NDB is online. The NETLIGHT LED will blink rapidly at this point.
If you do not see the even green blink, match the pattern you do see to those listed above. It will tell you how far the NDB progressed and the likely cause of its failure to connect. For example, if you see the Waiting for SIM pattern, you know to check that the board’s Super SIM has been inserted fully and correctly. A pattern further down the list might indicate a broken antenna connection.
If everything seems slotted correctly, and you’re still not connected — you‘ll see the Checking PPP Connection pattern — you may not have cellular connectivity where you are. Try moving the device to an alternative location. But don’t forget, Twilio Support is ready to assist.
Let’s build and deploy a classic ‘Hello, World’ application so you can see how you interact with the software you’ve just installed and your newly connected NDB. You’ll use the FreeRTOS demo code that you just installed. It flashes the NDB’s USER LED to signal its presence.
Switch to the
twilio-microvisor-freertos directory if you’re not already in it.
If you’re running under Ubuntu, natively or in a VM, run:
cmake -S . -B build/ cmake --build build --clean-first
If you’re using Docker, run:
docker build --build-arg UID=$(id -u) --build-arg GID=$(id -g) \ -t microvisor-gpio-sample-image .
docker run -it --rm -v $(pwd)/:/home/ --name microvisor-gpio-sample \ microvisor-gpio-sample-image
Applications are delivered to the Twilio cloud in the form of a ‘bundle’. This is a zip archive which contains a combination of executable code and data. It also includes a manifest, a signed metadata file which tells Microvisor where to install the code and the data. Build a basic bundle now — or jump to the next step if you’re working with the Docker container.
python3 twilio-microvisor-tools/bundler-py/bundler.py \ build/Demo/gpio_toggle_demo.elf \ build/Demo/gpio_toggle_demo.zip
curl -X POST https://microvisor-upload.twilio.com/v1/Apps \ -H 'Content-Type: multipart/form-data' \ -F File=@./build/Demo/gpio_toggle_demo.zip \ -u <YOUR_ACCOUNT_SID>:<YOUR_AUTH_TOKEN> \ -s | jq
You’ll need to edit the command to replace the bracketed values with your Account SID and Auth Token, or with credential-holding shell environment variables. If you don’t have your credentials handy, you can get them from the Console.
Uploaded bundles are accessed through the Microvisor Apps API, which represents each bundle upload as an App resource. Apps are uniquely identifiable by their SID. This allows you to quickly re-deploy an older version of your code if you need to.
Make a note of the new App’s SID in the JSON response to the command you just issued. It’s a 34-character string beginning with
KA. The JSON also includes the code’s SHA-256 and the hash value that Microvisor uses to ensure the integrity of Apps it downloads.
You can give the uploaded bundle a friendly name by including
-F 'UniqueName=My App Bundle' in the above
curl call. Replace
My App Bundle with any name you like. You can use it instead of the SID in Step 5, below.
Next, you need to determine the SID of the board itself. You’ll need this to instruct Twilio which device to deploy the uploaded bundle to. First, make a Microvisor API request to list all of your devices:
curl https://microvisor.twilio.com/v1/Devices \ -u <YOUR_ACCOUNT_SID>:<YOUR_AUTH_TOKEN> \ -s | jq
Again, you’ll need to replace the bracketed values with your own credentials.
This request will return JSON data listing all of the devices associated with your Twilio account. Look for the
devices key — its value is an array which likely contains only one object at this stage, your NDB. Make a note of its SID, beginning
Now ensure your NDB is powered up and connected to the Internet — the SYSTEM LED will be slowly blinking green — and deploy the code to it. To so, make a Microvisor API request like this:
curl -X POST https://microvisor.twilio.com/v1/Devices/<YOUR_NDB_SID> \ -d TargetApp=<YOUR_APP_SID> \ -u <YOUR_ACCOUNT_SID>:<YOUR_AUTH_TOKEN> \ -s | jq
Again, you’ll need to replace the bracketed values with your own credentials and your NDB’s SID.
You can avoid using the bulky SID by giving your device a friendly name:
curl -X POST https://microvisor.twilio.com/v1/Devices/<YOUR_NDB_SID> \ -d 'UniqueName=My NDB' \ -u <YOUR_ACCOUNT_SID>:<YOUR_AUTH_TOKEN> \ -s | jq
Use the friendly name wherever you’re asked to enter a device SID.
Twilio will signal the device that that an application update is pending, and Microvisor will reboot, reconnect to the Internet, and download your code. After a moment or two, while the NDB connects to the Internet, you’ll see the USER LED flash once a second.
Microvisor supports the relay of logging statements issued by your application code. To view logs from your device, you’ll use the Twilio CLI. If you didn’t run
twilio login when you installed the tool earlier, do so now. Then you can run:
twilio microvisor:logs:stream <YOUR_NDB_SID>
Sit back and watch some messages appear in your terminal.
How does it work? Logging leverages the standard Microvisor system calls for connection initiation and data-channel management. Take a look at the demo code’s source, specifically the
Demo/src/logging.c file, to see how to incorporate code into your own application which routes
printf() calls via Microvisor and through to your terminal.
If you make changes to the code and later want to revert to an earlier version, just list your Apps, find the SID of the version you want to redeploy, and use the
curl code above to send it to your NDB.
You have set up your development environment and your Microvisor Development Board. You’ve run a FreeRTOS-based sample application on the device by creating a bundle, transferring it to the Twilio cloud, and then deploying it to your board over the air. You have viewed logging information transmitted by your application.
What next? Microvisor now supports remote debugging: controlling running application on your Microvisor device wherever in the world it is located. To try out this powerful development functionality, work through our Microvisor Remote Debugging guide.
Here are some suggestions for further stages of your Microvisor journey.
- Get some further guidance on developing applications for Microvisor.
- Check out the functionality Microvisor can provide to your application through its system calls.
- Review STMicro’s STM32U585 Reference Manual and HAL documentation.
- Is designing hardware your focus? If so, find out how to design Microvisor-empowered IoT devices.
- Read about the Microvisor API you use to interact with the Twilio cloud.
We can’t wait to see what you build with Microvisor and the Nucleo Development Board. Make sure you let us know through one of the feedback channels discussed with you!