Minimal Requirements

If you want your computer ready to start using our API, you will need to install some programs and dependencies. In this section, we will work on an Ubuntu system that uses the package manager apt. However, other Linux distros are also supported! The not extensive list of supported OSs is shown below.

Windows and macOS installation procedures are also available.

❗️

Only x64 based operating system is supported

🚧

Each Linux distro will have some differences; please be aware of them before proceeding.

🚧

Please, don't run all the commands shown here before knowing what it does.

Programs used

Our API requires some programs to run smoothly. Nonetheless, not all of them are needed, but recommended. We will let you know if a program is only optional! Please, check the table below.

❗️

Mbed CLI 2 is available, but the API does not support it at this moment.

Ubuntu

The first step is to update your system. For that, please run the following command on the terminal:

sudo apt update && sudo apt full-upgrade

It is also recommended to remove unneeded packages and retrieved package files:

sudo apt autoremove && sudo apt clean && sudo apt autoclean

We can now install minicom and git. Some Linux distros already come with some of the packages used here.

sudo apt install minicom git

Mbed CLI

Mbed CLI 1 is a command-line interface for Mbed OS. The main advantages of Mbed OS are that it is an RTOS with fully integrated connectivity and security components, and its hardware abstraction layer (HAL) supports Arm Cortex-A, M, and R series.

Mbed OS is a very comprehensive tool, and right now, Mbed OS 6 is the newest release. However, the API supports, for now, Mbed OS 5 version 5.8.0 or greater.

We recommend you look at the Mbed CLI 1 installation manual, which can be found here. Either way, here we show the main steps to install on your computer.

First, we install the dependencies:

sudo apt install python3 python3-pip python3-dev mercurial 

Now we can install Mbed CLI 1:

python3 -m pip install mbed-cli

After installing it, there may be some dependencies left to install. Mbed OS has a text file with all the requirements needed. As it changes accordingly to the Mbed OS version, please check on mbed-os/requirements.txt.

If you want to have bash-completion for Mbed CLI 1 (optional), first, you need to install the following package:

sudo apt install bash-completion

Later, check if~/.bashcompletion.d folder exist. If it doesn't, please create it

mkdir -p ~/.bash_completion.d

Then, obtain the commands used by mbed-cli by cloning the repository

git clone https://github.com/ARMmbed/mbed-cli

If it was successful, save it on the directory created:

cp mbed-cli/tools/bash_completion/mbed ~/.bash_completion.d/
grep -wq '^source ~/.bash_completion.d/mbed' ~/.bashrc || \
echo 'source ~/.bash_completion.d/mbed'>>~/.bashrc
rm -rf mbed-cli

The Mbed OS is compatible with Arm Compiler and GNU Arm Embedded (GCC). If you install GCC, please note that the Ubuntu repository has an old version of it. You can install the most recent one by going here.

If you want to install GCC from the Ubuntu repository, just run the following command:

sudo apt install gcc-arm-none-eabi

It is also recommended to install the library:

sudo apt install libnewlib-arm-none-eabi

📘

For Arch and Manjaro users, the AUR repository has the most recent GCC version. As such, GCC works with no problem. However, it is recommended to install the arm-none-eabi-newlib package, otherwise, there will be no <stdint.h>.

Docker

The use of Docker is essential to build applications that use our API. However, you don't have to know how to use Docker to be able to create an application! Everything is automated for your convenience. In case you don't want to use Docker, you will need to install the toolchain to build the application.

To install Docker, we recommend their installation manual; for that, click here.

👍

They have an installation guide for other distributions, so please check there, especially if you are not an Ubuntu user.

To get it up and running, you can also follow the steps here. First and foremost, we consider you never installed Docker on your machine before. If you did, please uninstall any old version by running the following command on the terminal:

sudo apt remove docker docker-engine docker.io containerd runc

🚧

The remove command preserves some configuration files. If you want to do a clean installation, you can run the purge command instead. Old images, containers, volumes, or customized configuration files also need to be deleted. They are on /var/lib/docker and /var/lib/containerd directories. More details can be found here.

There are many ways to install Docker. In this guide, we use the recommended approach by Docker, i.e., by setting up Docker's repository and install from them. Now, to be able to use a repository over HTTPS, please install the following packages:

 sudo apt-get install apt-transport-https ca-certificates curl gnupg lsb-release

Now, add Docker's official GPG key:

curl -fsSL https://download.docker.com/linux/ubuntu/gpg | \
sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg

Then, to set up the repository:

echo \
"deb [arch=amd64 signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/ubuntu \
$(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

Afterwards, we need to update the package manager to be able to install the latest version of Docker:

sudo apt update

Finally, we can install Docker:

sudo apt-get install docker-ce docker-ce-cli containerd.io

We need to check if the group docker exists, if not create it:

grep -q -E "^docker:" /etc/group && sudo groupadd docker

Now check if the user is in the docker group. If not, add it.

id -nG "$USER" | grep -qw docker && sudo usermod -aG docker $USER

Finally, we only need to enable it to start when the computer starts:

sudo systemctl enable docker.service
sudo systemctl enable containerd.service

Flashing Application

Shard comes with USB programming capabilities through the USB connector attached to Shard Edge. The available software are:

• STM32CubeProgrammer
• DFU-Util

More information is available on the Vitro Shard Programming documentation.

STM32CubeProgrammer

STM32CubeProgrammer is an all-in-one multi-OS software tool for programming STM32 products delivered in GUI (graphical user interface) and CLI (command-line interface) versions. STM32CubeProgrammer provides an easy-to-use and efficient environment for reading, writing, and verifying device memory through both the debug interface (JTAG and SWD) and the bootloader interface (UART, USB DFU, I2C, SPI, and CAN).

To install it, just download it and follow the installer's instructions. For more details, you can also access the manual.

DFU-Util

The DFU stands for Device Firmware Update and it is an implementation of the DFU 1.0 and DFU 1.1 specifications. DFU is intended to download and upload firmware to/from devices connected over USB. It ranges from small devices like micro-controller boards to mobile phones. You can install it using this command:

sudo apt install dfu-util

An in-deep knowledge of how to use it is not required if our application template is used.
Our template comes with scripts that automate the building and flashing procedure!

Wrapping up

It is recommended that you clean up any leftovers. Thus, first, update the system:

sudo apt update && sudo apt full-upgrade

Afterwards, remove unneeded packages and retrieved package files:

sudo apt autoremove && sudo apt clean && sudo apt autoclean

You are done!