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 the macOS installation procedures. However, Linux and Windows are also supported!

❗️

Only x64 based operating systems are supported. Furthermore, only Intel-based machines were tested.

🚧

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. Our guides consider that you installed all the programs (optional or not). We will let you know if a program is only optional though! Please, check the table below.

❗️

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

macOS

The installation for macOS is straightforward. The first step is to update your system, and make sure taht the macOS is version 10.14 or newer with at least 4 GB of RAM. However, if you have a Mac with Apple silicon, please install Rosetta 2:

softwareupdate --install-rosetta

Preparations

Before installing any of the required programs, you should consider installing Homebrew. It is a package manager for macOS and it is a handy tool even for everyday use. It is not mandatory to install it, but it makes your life easier.

It is really easy to install Homebrew. Just open the Terminal and type:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

After you follow the installation steps, you can install programs by typing:

brew install <program>

You are done!

📘

When software has a GUI, Homebrew lets you install it by using the --cask flag: brew --cask <program>.

👍

You can update Homebrew and all the programs managed by it by simply typing: brew update on the terminal.

Another important program is the Xcode. It is recommended that you install it now. You can install it through the Mac App Store.

Git

Git is a free and open-source distributed version control system. There are many ways to install Git on macOS. If you already installed Xcode, you can skip this step. Otherwise, the easiest way is through Homebrew. Just open the Terminal and type:

brew install git

📘

Every time we use Homebrew, it is implied that we go to the Terminal.

Python

When you install Xcode, you also install Python. Therefore, you can skip this step too. Otherwise, you can install python using Homebrew by typing:

brew install python

GCC

To install GCC, you can install the Apple Command Line Tools if you have an Apple developer account. But the easiest way is to use Homebrew:

brew install gcc

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 (up to 5.15).

We recommend you look at the Mbed CLI 1 installation manual, which can be found here. They have an installer for macOS. The latest version of the installer can be found here. Please, download it and follow the instructions.

The installer will install Mbed CLI 1, Git, Python 3, Mercurial, and GCC. If you want to install everything manually, please check Mbed CLI 1's installation guide.

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.

There are two installers: one for intel based Mac and another for Apple silicon-based Mac. Please follow the installer's instructions. If you need more information, please check their installation guide here.

However, the easiest way to install it is by using Homebrew:

brew install docker

CoolTerm

To establish a serial connection, Mac users can use CoolTerm. You can either download it from the link given or install it through Homebrew! To do that, just run this command on the terminal:

brew install --cask coolterm

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.

📘

If you are facing some problems with the installation process, please check this possible solution.

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 Homebrew:

brew 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

After finishing installing everything, it is recommended to clean the computer. First, update it:

brew update
brew upgrade

When the process is finished, you can remove any leftovers:

brew cleanup

Finally, reboot the computer, and you are done.