Skip to content

Build system

Jump to bottom
CalebJ2 edited this page Jun 12, 2020 · 16 revisions

The goal of the build system is to make programming the robot as easy as possible. It allows code changes to be tested without having to worry about breaking things and allows automatic code deployment to the rover. This project's build system is based on the Continuous Integration (CI) and Continuous Delivery (CD) concepts. There are no large updates. Instead, everything is updated incrementally and put into production (on the robot) as soon as possible.

The entire process is managed by GitLab. GitLab markets themselves as a "complete DevOps platform" and a "complete CI/CD toolchain in a single application." The Computer Science Department provides a GitLab server for students to use for free. We use it to host our source code, track issues, host documentation, and manage CI/CD. One alternative to GitLab is GitHub combined with a Travis CI or Jenkins build server. Travis CI is expensive and Jenkins setup was a huge time sink so we went with GitLab.

This image shows the general CI/CD process:

build-system

After pushing a change to the git repository on GitLab, it will run any pipelines/jobs defined in the gitlab-ci.yml file (documentation). Each job in a stage must complete (unless it has the allow_failure parameter) before the next stage starts.

The first stage is Analysis which checks that the code is formatted nicely and doesn't have any obvious problems like an undeclared variable being used. Next, the Build stage compiles all the code and makes sure there aren't any compiler errors. Then the Test stage will run any unit tests on the code and make sure the changes didn't break anything. Finally, the Deploy stage copies the code to the robot and starts it.

GitLab has a feature that allows jobs to be run on different computers, or “runners.” Which runner the jobs run on is determined by the tags they have. The CS department provides a runner with the "docker" tag and is a docker executor, meaning all the commands run in it are done in a docker container. The docker image it uses is set by the image: line at the top of the gitlab-ci.yml file. In this case, it uses an image hosted on GitLab's container registry and currently needs to be manually updated because docker-in-docker is disabled on the CS department runner and would be fairly time consuming for the rover runner to upload.

The GitLab runner on the rover has the "rover_remote" tag and uses a shell executor, meaning it runs all its commands in a shell terminal. The two main things the rover runner needs to do when updating are rebuild/restart its docker image(s) and program any microcontrollers. The docker configuration handles which containers to start and what scripts to run when they start. See the ROS page for how the ROS startup works.

The benefit of doing everything with docker containers is that development can be done in a near identical clone of the software environment on the robot. An important thing to note is that the GitLab image is not automatically updated, so when changes are made to the docker configuration it needs to be manually updated. See the page on Docker for more information on how to use it.

Microcontroller programming

Arduino programming is done with PlatformIO because it is easy to use from the command line and automates a lot of setup. Any Arduino code can be ported to PlatformIO by changing the folder structure a little and adding a platformio.ini file. See the motor controller repo for an example. From the command line the code can be compiled and uploaded by installing PlatformIO and running platformio run --target upload. It also supports easy unit testing, even on a host machine.

To upload to Teensy from command line using the Arduino tools would require installing the Arduino CLI, gcc packages, and setting up Make, and the Teensyloader CLI. Unit testing would be even more work to set up.

Troubleshooting:

Clone this wiki locally