First Application

Before building and flashing a demonstration application on Vitro Shard, you need to install all programs and dependencies, and have a working IDE. This is the bare minimum needed. If you want to use our example, you will also need to provision (to send IoT Blocks to Vitro Cloud Infrastructure) both Vitro Shard and Vitro Crystal and install the Yocto-based OS on the latter.

📘
If you want to use the MQTT protocol, you can debug the application with the Mosquitto app.

Requirements

You will then need:

Vitro Crystal board.
Vitro Shard and Vitro Shard Edge boards.
Two 12V power Supplies with DC jack.
Two Micro USB cables.
An RJ11 cable (for the CAN connection).

🚧
The Vitro Crystal requires an RJ11 connection, while Vitro Shard is more flexible. It can receive input from the RJ12 or J29 ports. It is recommended the RJ12 cable as it is a direct connection and is compatible with the RJ11 port. There is no problem if only the RJ11 cable is available.

Setting up

There are three applications available for you to test your Vitro Shard. You can test it using the DHT22 sensor, sending dummy IoT Blocks, and using an USB.

📘
The DHT22 datasheet is available here.

Vitro Shard Edge has many input ports for your sensors. It has 10 GPIOs available on the pin header, four analog input channels, and four current loop channels. However, to keep it simple, let's just use the USB port.

To do that, download the repository:

git clone https://github.com/VitroTech/shard-v2-app-template.git

The command will create a folder named shard-v2-app-template. You can navigate to it by double-clicking it or using the change directory command:

cd shard-v2-app-template

We need to use another repository's branch called USB_MSD. You can do that by using the following commands:

git pull && git checkout USB_MSD

📘
MSD stands for Mass Storage Device. This is a hint on what the application will do!

Now we also need to load other repositories. In this case, they are the vitroio-sdk and the bootloader image. Just run this command:

git submodule update --init

📘
You can check the submodules used by opening the .gitmodules file with a text editor.

Building and Flashing

As mentioned in the Requirements documentation, we recommend the use of Docker. Therefore, we will use it to build the application.

Please connect the Micro USB cables on ports J54 (for UART and debugging) and J53 (for flashing). If the device is turn off, please turn it on by connecting the power supply. Don't forget to use a serial-port application to receive logs and information through UART.

📘
If you need help, just check the UART documentation! The default baud rate in our examples is 115200.

To make things modular and simple, there are two scripts that you will need: build_app.sh and docker_flash_image.sh. However, many more scripts are called.

When you run build_app.sh, the script checks if the system has the necessary dependencies and runs docker_build_image.sh. The script will then create a container using the docker-mbed-cli image and run the script build_image.sh. This script sets the secure boot and builds the app A and B images (by running the build script on each directory).

The process is similar when flashing the image. You first run the docker_flash_image.sh that also uses the docker-mbed-cli image, but now it has the necessary privileges. It then runs the flash_image.sh script. The script then uses ST-LINK Tools to flash the image to the MCU. If you don't know what ST-LINK Tools is, please check the Requirements documentation.

Finally, there is also the clean script. It is recommended, but not required, to run it before building a new image.

Before flashing the image, it is necessary to configure Vitro Shard and Vitro Shard Edge to enter bootloader mode. This process is better explained in the Hardware Guide and is talked about in Vitro Shard programming documentation. Just short the pins BOOT0 and 3.3V on the J64 header to be very concise.

Now, just run the following script:

./docker_build_image

🚧
We used docker_build_image instead of build_app.sh, because we were on the application branch (i.e., this is the only application available). But instead of doing git checkout USB_MSD, we could have used ./build_app.sh USB_MSD to build the image.

To flash the image, please follow the Vitro Shard Programming documentation. If you are using dfu-util, run the following command:

dfu-util -a 0 -i 0 -s 0x08000000:leave -D ./bin/image.bin

👍
You can also check if there is any DFU capable device connected by using dfu-util --list. If there is none, you probably forgot to short the J64 header.

This will build and flash the image to the MCU. If flashed correctly, reconnect the Micro USB cable on port J53. It should mount a 66 kB mass storage device with a test.txt file. You can then write anything on this file. The moment the USB cable on port J53 is disconnected, the information on that file will be encrypted and sent as an IoT Block.

🚧
Don't forget that you can now remove the jumper on the J64 header!

You will receive logs because the Micro USB cable connected to port J54 lets you know about a warning or error. The information written on the test.txt file will also appear on your screen, among other details.