Adding a New Arduino Library

In this text I describe what has to be done to add a new library to the open-roberta lab. Please mail errors and suggestions to reinhard.budde AT iais.fraunhofer.de.

As an example I will add the library LSM9DS1, which b.t.w. is part of the new nano33ble plugin. Note, that I'm using the git bash (because I've installed git on my windows machine and like the bash).

Overview

Adding a library relates to the code generation and cross compilation of user program. There exist layered resources to achieve that. The layering is realized using various git repos on github and layers of docker images.

• everything is based on the ubuntu:18.04 image
• on top of that all compilers needed by the lab are added resulting in the openroberta/ccbin-x64:1 image (abbreviated ccbin image) for the standard x64 architecture. Building the ccbin image takes a lot of time and occurs very infrequently.
• on top of that the resources for the crosscompiler are added (libraries, header files, ...). This can be done in a short time and occurs often. It generates the image base-x64:25 (abbreviated base or cc-rsc image). Adding a library to the arduino plugin will generate a base image with an increased version number.

Note, that the version number of ccbin image is 1 and that of the base image is currently 25, increasing much faster! It is very important to use a new version number when generating the base image. Overwriting an existing image may effect problems hard to debug. How these images are generated is described in the Docker/_README.md in detail.

The cross compiler resources for the base image are retrieved from the git repo ora-cc-rsc. This repo has one tag (e.g. 25) for one image (e.g. base-x64:25). The repo contains the resources for all the crosscompilers used by all plugins of the lab. The resources for a plugin are stored in a directory, whose name identifies the plugin easily.

For adding an arduino library we have to modify the directory RobotArdu. It contains the directory firmware, that contains for some arduino systems firmare that must (sometimes) be uploaded to the arduinos. We can ignore this.

The directory arduino-resources is our target. But it is not modified directly for the following reason:

• arduino libraries are usually distributed as source and header files. This is because it would be a tedious task to compile the library for all the variants supported by arduino.
• in the arduino IDE it is standard to compile for each project all libraries the project depends on. This takes a lot of time, but only for the first compile, a later compile uses cached data. We want to avoid this costly setup step and decided to precompile all libraries needed and then to squash them into one archive.
• At the moment of writing this text we support bob3, botnroll, festobionic, mbot, mega, nano, nana33ble, nucleo64, sensebox, uno, unowifirev2. Each variant has a library libora.a in their respective folder in the lib folder.
• Furthermore there are build scripts build_project_*.sh to call the crosscompiler, supply parameters and so on. When the user requests cross compilation, these build scripts are called from the lab server by spawning a new process.

To realize this idea, we created the git repo arduino-resources. Now we have to inspect this repo. It contains all arduino sources (header and code) and the scripts to generate the binaries from the sources. A global script compile_all.sh is responsible to do that. Have a look at this script, it is obvious how it works. Please read the README.md of the repo arduino-resources. It contains valuable information!

Adding a library step by step

My goal is to add the library LSM9DS1 to the arduino variant nano33ble.

• I use cd to change to my local repo arduino-resources and after pulling master I check out a new feature branch feature/LSM9DS1.

• I need the sources (code and header) of the library LSM9DS1. This is easy, after I have downloaded them using the Arduino IDE. The library manager does the job and uses as the default place to store them the directory :UserHome:/Documents/Arduino/libraries/Arduino_LSM9DS1/src. Copy the 3 files into the directory RobotArdu/libraries/Nano33blesense__Arduino_LSM9DS1 of the arduino-resources repo. Alternatively you can add a line in the Dockerfile to use the arduino-cli to do the job: arduino-cli lib install "LSM9DS1"@1.1.0. You get the version number from the IDE's library manager. BTW: the complete git repo related to the library is https://github.com/arduino-libraries/Arduino_LSM9DS1.

• I tell which arduino variants use the library. Here I add in sketch file nano33ble/nano33ble.ino the line #include <Arduino_LSM9DS1.h>

• I commit my changes, rebase (a conflict is unlikely), push, create a tag und push that. This will trigger the github action, which creates a container, generates the resources, zips them and creates a release. On the github page https://github.com/OpenRoberta/arduino-resources/releases I wait until I see the new release.

git add .;git commit -m "added the library LSM9DS1"
git fetch;git rebase master
git checkout master;git merge feature/LSM9DS1
git push
git tag v2020.12.09 -m v2020.12.09
git push --tags
git branch -d feature/LSM9DS1

• now I switch back to the repo ora-cc-rsc. In the pom.xml I provide the new tag name from above: <arduino-resources.tag>v2020.12.09</arduino-resources.tag>

• from the Docker/_README.md I copy and execute the lines from step 2: image with crosscompiler resources. Do not forget to increase the BASE_VERSION number. If that finishes, you have created a new base for the prod and all test server.

• if you want to deploy a new test server on the test system dev3 for instance, go to the docker setup of the test server, edit file :docker-setup:/server/dev3/decl.sh and set the new BASE_VERSION, and run :docker-setup:/scripts/run.sh deploy dev3. For deployments, read the Docker/_README.md carefully.

Adding and deploying the library is finished :-).

Please contact the open-roberta lab developer, if you want to add libraries to the public lab. You may prepare and test everything locally, but there must be an agreement on

• pushing to arduino-resources and adding tags
• increasing the BASE_VERSION number. Invalid BASE_VERSION numbers are dangerous.
• deploying test servers. If you deploy locally only, there is no problem with that.

Having git and docker installed on windows10 or linux is almost everything you need.