RgbLed - A Project and a Sample Project for multiple concepts

The Project itself

This thing serves as a controller for smart RGB leds like WS2811, WS2812, PL9823 or others. For this purpose it utilizes the Adafruit Neopixel library.

It receives commands via MQTT to send related code sequences to chains of those leds. It supports two commands, which it receives via two MQTT topics it subscribes.

The simple command accepts one or two arguments. When only one argument is given, this argument has to be a number between 0 and 255 and is interpreted as brightness. All three colors of all connected leds are driven with that value. When two arguments are given, the first argument is interpreted as the number of the led to drive, starting with 0 and the second argument is again the brightness.

The colorCommand accepts one, two, three or four arguments. With only one argument, this argument is interpreted as a color word (on or white, off, warmwhite, red, green, blue, purple, yellow). All connected leds will be driven with the given color combination. With two arguments, the first one is the led number, the second one is the color word. Three arguments have to be 8 bit numbers to control the color channels of all connected leds. With four arguments the first argument is the led number, the remaining three are again red, green and blue values.

Sample Project for ...

... a project to be used together with the build-env-arduino docker image

The build-env-arduino docker image, which can be loaded using the image name registry.gitlab.com/wolutator/build-env-arduino:latest is a tinned or preserved build environment for boards supported by the Arduino development system. Currently arduino:avr and esp8266:esp8266 are supported by this image.

It is maintained in to the project [https://gitlab.com/wolutator/build-env-arduino].

A preserved build environment, which easily can be installed or simply loaded for many developers in exactly the same way and which can easily be archived is a major topic is professional software engineering. If you have a team of lots of developers you don't want to waste time by letting everyone install his or her development environment manually, finally ending up with minor to major differences which makes it hard to compare or integrate software or let one developer investigate a bug another developer found. Furthermore you want to be able, especially in an industrial environment, to pick a development environment from the shelve to investigate and fix an issue reported in a years-old software. Both can be achieved with preserved environments.

This preserved Arduino build environment uses the Arduino CLI tool, which can be found at [https://downloads.arduino.cc/arduino-cli/arduino-cli-latest-linux64.tar.bz2] and which is discussed here [https://blog.arduino.cc/2018/08/24/announcing-the-arduino-command-line-interface-cli/].

This Arduino CLI tool expects your projects to be stored in the common sketchbook folder, where also the common (used by all projects) libraries folder is located. This is not my cup of tea. You want my projects separated from each other, together with all dependent libraries.

So, I created the following directory structure of my project repository:

RepoRoot/
|
+--- sketch/
|    |
|    +--- sketch.ino
|    +--- application.cpp
|    +--- application.h
|
+--- libraries/
|    |
|    +--- library1/
|    |
|    +--- library2/
|    |
|    +--- includes/   
|
+--- .gitignore
+--- .gitlab-ci.yml
+--- readme.md

To make the Arduino CLI use this structure, I point the variable ARDUINO_SKETCHBOOK_DIR to it, so the commandline to build a project is

env ARDUINO_SKETCHBOOK_DIR=$PROJECT_DIR arduino-cli compile --fqbn=esp8266:esp8266:nodemcu $PROJECT_DIR/sketch

The Arduino system expects a file with the extension .ino and same name as the directory within the sketchbook directory. Since in my setup every project lifes in a separate sketchbook directory, I call the directory with the main application sources sketch and the accordingly the ino-file sketch.ino. This file contain the typical main functions of each Arduino project, which are setup and loop.

In my projects, I do not put any meaningful code into the ino, I have everything in the companion cpp file, which is usually application.cpp (with its friend application.h)

When the Arduino system trys to find some included .h it has a powerful strategy, which works without any CFLAGS variable with -I options. It works just by convention. Thus, it searches in the Arduino core folders, in the sketch folder itself and in all subfolders of the libraries folder. For this reason I put a includes folder into the libraries folder where I place all header files, which are shared between the main application (the "sketch") and some libraries.

This approach can easily be implemented in a Gitlab CI script:

build:
    stage: build
    image: registry.gitlab.com/wolutator/build-env-arduino:latest
    variables:
            GIT_SUBMODULE_STRATEGY: recursive
    artifacts:
            paths:
                    - sketch.esp8266.esp8266.nodemcu.bin
    script:
            - env ARDUINO_SKETCHBOOK_DIR=$CI_PROJECT_DIR arduino-cli compile --fqbn=esp8266:esp8266:nodemcu $CI_PROJECT_DIR/sketch
            - cp sketch/sketch.esp8266.esp8266.nodemcu.* .

Uploading to the target

In a final step the CI script will put the generated firmware binary into the Gitlab release area. It can be downloaded there and uploaded to the device using the esptool.py.

esptool.py -p /dev/ttyUSB0 write_flash 0x0 sketch.esp8266.esp8266.nodemcu.bin