Servidor CI para sistemas embebidos basado en una Raspberry Pi

Instalación del SO

Lo primero que necesitamos hacer es instalar el sistema operativo (SO) en la tarjeta SD que luego utilizaremos en la RPi. Para ello, nos descargamos la aplicación Raspberry Pi Imager la cual se encargará de descargar el SO e instalarlo en la tarjeta SD pudiendo configurar algunos parámetros del SO, como la conexión Wi-Fi.

Una vez descargado, abrimos la aplicación y seleccionamos como dispositivo el modelo RPi que utilicemos, como SO Raspberry Pi OS Full (64-bit en este caso), y finalmente nuestra tarjeta SD que habremos insertado previamente en nuestro ordenador mediante el adaptador correspondiente. En este caso, puesto que la RPi no hará grandes tareas de computación, mi recomendación es ir con el SO completo y con Escritorio.

Al clicar en Siguiente, la aplicación nos preguntará si queremos editar la configuración de algunos parámetros.

En este caso le diremos que Editar ajustes para configurar el nombre de la RPi (y así poderla encontrar fácilmente en la LAN), la conexión Wi-Fi, establecer un usuario y contraseña, y habilitar el SSH.

Finalmente, clicamos en Guardar y confirmamos todos los siguientes mensajes para iniciar la descarga del SO y formatear la tarjeta SD.

Habilitar Escritorio remoto

Una vez instalado el SO, insertamos la tarjeta en la RPi y conectamos a esta última la alimentación utilizando el transformador correspondiente. Al finalizarse la arrancada del sistema, la RPi se conectará directamente a la red Wi-Fi que le hemos configurado.

Para la primera conexión con la RPi utilizaremos la conexión SSH que hemos habilitado previamente en Raspberry Pi Imager. Para ello, estando en la misma red Wi-Fi que la RPi, abrimos un terminal y escribimos:

ssh albert@masbcicd.local

Nos pedirá la contraseña de nuestro usuario. Una vez introducida, ya estaremos dentro (en tu caso, en lugar de masbcicd.local, pon el nombre que le hayas dado a tu RPi).

Ahora normalmente instalaría VNC para poder habilitar un Escritorio remoto en la RPi, pero acabo de descubrir que existe el servicio gratuito Raspberry Pi Connect, que nos permitirá conectarnos a la RPi desde cualquier lugar mediante un navegador (y no solo desde nuestra LAN y una aplicación específica en el caso de usar VNC (a no ser que configuremos puertos en el router, DNS dinámicos, firewalls, etc.)). Para usar este servicio, nos creamos una cuenta en Raspberry Pi Connect. Una vez creada la cuenta, instalamos la aplicación en la RPi y la habilitamos:

sudo apt update && sudo apt -y install rpi-connect && rpi-connect on

Ahora, enlazaremos la RPi con nuestra cuenta. En la RPi ejecutamos el comando:

rpi-connect signin

Este comando nos devolverá un enlace. Lo abrimos desde el navegador de nuestro ordenador. Al abrirlo, nos pedirá un nombre para el dispositivo. Indicamos un nombre y con ellos ya tendremos nuestro dispositivo disponible para conectarnos remotamente. Simplemente, cuando queramos conectarnos al dispositivo, vamos a la página de Raspberry Pi Connect, iniciamos sesión, y seleccionamos nuestro dispositivo para conectarnos (podemos escoger entre Screen sharing para hacer un Escritorio Remoto o Remote shell para tener un terminal remoto).

Por lo general, todas las instrucciones las daré como comando de terminal, por lo que el Remote shell sería suficiente (de hecho, para una mayor calidad de conexión, cuando estoy en la LAN utilizo la conexión SSH mediante terminal), pero si te sientes más cómodo con el Escritorio Remoto, siéntete libre de usarlo 😉

Instalación de aplicaciones y librerías

Para realizar los test unitarios necesitaremos poder compilar y ejecutar el código desarrollado. En mi caso, les pido a los estudiantes que realicen los desarrollos en ficheros con extensión .cpp y no .ino. Es decir, tienen su archivo principal del proyecto con extensión .ino, pero cualquier desarrollo se hace en ficheros .cpp aparte y se incluye su correspondiente encabezado .h. ¿Por qué? Porque estamos en un curso de programación y mi objetivo es que la “magia” de Arduino no enmascare aspectos del lenguaje C/C++ que luego les pille por sorpresa. Para compilar esos ficheros C/C++ utilizaremos GNU gcc/g++ y como suite de test CppUTest. Vamos a instalarlo con el siguiente comando:

sudo apt install -y build-essential

Es probable que si has seguido mi recomendación de instalar el SO con todas las características recomendadas ya incluidas (Full), ya tengas las herramientas instaladas. No será el caso con CppUTest. Para instalarlo, ejecuta el siguiente comando:

sudo apt install -y autoconf libtool && sudo git clone https://github.com/cpputest/cpputest.git /opt/cpputest && sudo chown -R $(whoami):$(whoami) /opt/cpputest && cd /opt/cpputest && autoreconf . -i && ./configure && make tdd && echo 'export CPPUTEST_HOME=/opt/cpputest' >> ~/.bashrc && source ~/.bashrc

Con esto ya tendríamos las herramientas para poder hacer tests unitarios. Vamos ahora con los tests de aceptación. Estos requieren que el código sea compilado y flasheado en la EVB y luego que la RPi compruebe físicamente que la aplicación testeada cumple con los requerimientos del proyecto.

Iba escribiendo este documento a medida que iba configurando la RPi y después de darme 1000 cabezazos contra la pared, utilizaremos PlatformIO CLI para compilar y flashear código de Arduino en el microcontrolador. Actualmente el soporte del tooling de Arduino/STM32 para la arquitectura de la RPi es pobre (por no decir nula). PlatformIO ofrece un CLI que puede ejecutarse en la RPi y nos ofrece todas las herramientas que necesitamos.

Para el caso de los proyectos de STM32CubeIDE/MX, la historia se repite: no hay soporte para la arquitectura de la RPi. ¡Pero buenas noticias! PlatformIO CLI ya incluye un tool para poder flashear un STM32 y solo deberemos de ejecutar el siguiente comando cuando toque:

~/.platformio/packages/tool-stm32flash/stm32flash -w firmware.bin -v -g 0x08000000 $(ls /dev/ttyACM* 2>/dev/null | head -n 1)

Si no te aparece la carpeta ~/.platformio/packages/tool-stm32flash, en cuanto hagas un proyecto en PlatformIO CLI para STM32, se descargará. Si eres un impaciente y quieres forzarlo, una vez hayas instalado PlatformIO CLI con los comandos de más abajo, ejecuta los comandos:

cd ~
mkdir test
pio project init -d test -b nucleo_f401re
cd test
echo "debug_tool = stlink" >> platformio.ini
pio run --target upload
cd ..
rm -rf test

O también está la opción de usar OpenOCD que viene también con PlatformIO CLI y que es la opción que yo usaré por permitir usar ficheros .elf. En este caso, el comando sería:

openocd -d2 -s ~/.platformio/packages/tool-openocd/openocd/scripts -f ~/.platformio/packages/tool-openocd/openocd/scripts/board/st_nucleo_f4.cfg -c "program "$(readlink -f stm32cube/blink_led/Debug/*.elf | head -n1)" verify reset; shutdown;"

Ajusta el path al fichero .elf a tu aplicación, así como el archivo de configuración de tu placa. Los estudiantes incluirán el fichero .elf de las compilaciones en sus sistemas de control de versiones.

Estoy de acuerdo que no es la opción más purista, que de este modo puede generarse una inconsistencia entre el código fuente y el binario generado, y que lo ideal sería instalar toooodo el tooling de ARM en la RPi y cambiar la configuración de los proyectos de STM32CubeIDE para que sean proyectos basados en Make y no CLT.

Pero para un curso de iniciación, prefiero mantener los proyectos CLT y evitar a los estudiantes tener que trastear con el Makefile. Es una cuestión de tradeoff e intended use.

Para instalar PlatformIO CLI, simplemente seguimos las instrucciones de la documentación:

curl -fsSL -o get-platformio.py https://raw.githubusercontent.com/platformio/platformio-core-installer/master/get-platformio.py
python3 get-platformio.py
echo 'export PATH=$HOME/.platformio/penv/bin:$PATH' >> ~/.bashrc && source ~/.bashrc
curl -fsSL https://raw.githubusercontent.com/platformio/platformio-core/develop/platformio/assets/system/99-platformio-udev.rules | sudo tee /etc/udev/rules.d/99-platformio-udev.rules
sudo service udev restart

Una vez instalado, con el comando pio boards ststm32 podemos obtener todas las placas compatibles con PlatformIO de la familia STM32 (no indiques ststm32 en el comando para ver todas las placas). Así podremos saber el ID de nuestra placa, que en mi caso es la nucleo_f401re. Con esto ya tendríamos la parte de compilar proyectos de Arduino y la de flashear proyectos tanto de Arduino como de Stm32CubeIDE/MX cubiertas.

Ahora nos falta la guinda del pastel: el servicio de Self-Hosted GitHub Action. En mi caso, el self-hosted runner irá asociado a la organización de GitHub que utilizo con GitHub Classroom. Desde las settings de dicha organización, vamos a Actions > Runners y clicamos en New runner > New self-hosted runner. Como imagen escogemos Linux y como arquitectura ARM64. Seguimos las instrucciones que aparecen en la web e voilà, ya tenemos el self-hosted runner instalado. Normalmente, la RPi opera 24/7 sin que estemos pendientes. Por ello, es más interesante ejecutar el self-hosted runner como servicio. Para ello, en lugar de ejecutar el ./run-sh de la documentación, ejecutamos:

sudo ./svc.sh install
sudo ./svc.sh start

En el futuro, podríamos parar el servicio con sudo ./svc.sh stop y eliminarlo con sudo ./svc.sh uninstall.

Si todo ha ido bien, nuestro self-hosted runner debería aparecer como activo y a la espera.

Con esto ya lo tenemos todo listo.

Proyecto de Arduino

El añadir testing te obliga a organizar tu código siguiendo buenas prácticas. Estas prácticas quedan fuera del scope de esta entrada, pero a modo resumen: deberemos mover toda la gestión del LED a un fichero aparte del sketch principal. Esto lo haremos en los ficheros led.cpp y led.h. Son muy sencillos:

1
#ifndef LED_H__
2
#define LED_H__
3

4
void LED_config(void);
5
void LED_turn_off(void);
6
void LED_turn_on(void);
7

8
#endif /* LED_H__ */

1
#include "Arduino.h"
2

3
void LED_config(void) {
4
  pinMode(13, OUTPUT);
5
  digitalWrite(13, LOW);
6
}
7

8
void LED_turn_on(void) {
9
  digitalWrite(13, HIGH);
10
}
11

12
void LED_turn_off(void) {
13
  digitalWrite(13, LOW);
14
}

Luego en el sketch principal, simplemente usamos esas funciones:

1
#include "led.h"
2

3
void setup() { LED_config(); }
4

5
void loop() {
6
  LED_turn_on();
7
  delay(1000);
8
  LED_turn_off();
9
  delay(1000);
10
}

Tests unitarios

Los tests unitarios son configurados en la carpeta test/arduino/blink_led/unit. No voy a poner por aquí todo el contenido del makefile y demás. Esto puedes verlo directamente en el repositorio.

Como he dicho antes, como usar las suites de tests no es el objeto de la entrada, pero si queréis ver más sobre tests unitarios para sistema embebidos, nunca me cansaré de recomendar el libro "Test-Driven Development for Embedded C" de James W. Grenning. Si te consideras o quieres ser un ingeniero de sistemas embebidos, este libro debe de estar sí o sí en tu estantería. No sé cuántas veces me lo he leído. Es oro puro.

Lo más destacable de los tests unitarios es que debemos de mockear las llamadas a las funciones pinMode y digitalWrite para poder testear que son llamadas correctamente cuando corresponde. Esto lo hacemos con los siguientes ficheros auxiliares en los tests:

1
#ifndef Arduino_H__
2
#define Arduino_H__
3

4
#define OUTPUT 0x1
5
#define LOW 0x0
6
#define HIGH 0x1
7

8
void pinMode(uint32_t ulPin, uint32_t ulMode);
9
void digitalWrite(uint32_t ulPin, uint32_t ulVal);
10

11
#endif /* Arduino_H__ */

1
#include "Arduino.h"
2
#include "CppUTestExt/MockSupport.h"
3

4
void pinMode(uint32_t ulPin, uint32_t ulMode) {
5
  mock()
6
      .actualCall("pinMode")
7
      .withParameter("ulPin", ulPin)
8
      .withParameter("ulMode", ulMode);
9

10
  return;
11
}
12

13
void digitalWrite(uint32_t ulPin, uint32_t ulVal) {
14
  mock()
15
      .actualCall("digitalWrite")
16
      .withParameter("ulPin", ulPin)
17
      .withParameter("ulVal", ulVal);
18

19
  return;
20
}

De este modo, en los tests unitarios, podemos comprobar como al configurar el pin o apagar/encender el LED se llaman las funciones correctas con los parámetros pertinentes.

1
#include "led.h"
2
#include "Arduino.h"
3
#include "CppUTest/TestHarness.h"
4
#include "CppUTestExt/MockSupport.h"
5
#include <stdexcept>
6
#include <stdio.h>
7

8
TEST_GROUP(LED__management){};
9

10
TEST(LED__management, Pin__configuration) {
11
  mock()
12
      .expectOneCall("pinMode")
13
      .withParameter("ulPin", 13)
14
      .withParameter("ulMode", OUTPUT);
15

16
  mock()
17
      .expectOneCall("digitalWrite")
18
      .withParameter("ulPin", 13)
19
      .withParameter("ulVal", LOW);
20

21
  LED_config();
22

23
  mock().checkExpectations();
24
  mock().clear();
25
}
26

27
TEST(LED__management, Turn__on) {
28
  mock()
29
      .expectOneCall("digitalWrite")
30
      .withParameter("ulPin", 13)
31
      .withParameter("ulVal", HIGH);
32

33
  LED_turn_on();
34

35
  mock().checkExpectations();
36
  mock().clear();
37
}
38

39
TEST(LED__management, Turn__off) {
40
  mock()
41
      .expectOneCall("digitalWrite")
42
      .withParameter("ulPin", 13)
43
      .withParameter("ulVal", LOW);
44

45
  LED_turn_off();
46

47
  mock().checkExpectations();
48
  mock().clear();
49
}

Una vez implementados los tests, procedemos a automatizarlos en las GitHub Actions. Para ello tenemos el fichero .github/workflows/arduino_blink_led_check.yaml.

1
name: 🔌 Check Arduino Blink LED
2
on:
3
pull_request:
4
  paths:
5
    - arduino/blink_led/**
6
    - test/arduino/blink_led/**
7

8
jobs:
9
check_arduino_project:
10
  name: 🔧 Build Arduino Project
11
  runs-on: self-hosted
12
  steps:
13
    - name: 📥 Checkout code
14
      uses: actions/checkout@v4
15
    - name: 🛠️ Set up PlatformIO CLI project
16
      run: |
17
        mkdir ${{ github.workspace }}/build
18
        pio project init -d build -b nucleo_f401re
19
        cd ${{ github.workspace }}/build
20
        echo "debug_tool = stlink" >> platformio.ini
21
        cp ${{ github.workspace }}/arduino/blink_led/* ${{ github.workspace }}/build/src || true
22
        mv ${{ github.workspace }}/build/src/blink_led.ino ${{ github.workspace }}/build/src/blink_led.cpp
23
        sed -i '1i#include "Arduino.h"' ${{ github.workspace }}/build/src/blink_led.cpp
24
    - name: 🏗️ Build PlatformIO CLI project
25
      run: |
26
        cd ${{ github.workspace }}/build
27
        pio run
28
unit_tests:
29
  name: 🧪 Unit tests
30
  runs-on: self-hosted
31
  env:
32
    CPPUTEST_HOME: /opt/cpputest
33
  steps:
34
  - name: 📥 Checkout code
35
    uses: actions/checkout@v4
36
  - name: 🧬 Run unit tests
37
    run: |
38
      cd ${{ github.workspace }}/test/arduino/blink_led/unit
39
      make

La ejecución de los tests se da en el job unit_tests. Hay también un job llamado check_arduino_project que simplemente compila el proyecto de Arduino. Este último paso se hace de manera implícita durante los tests de aceptación, pero me gusta tener un job aparte solo para esto para evidenciar a los estudiantes que su proyecto no compila correctamente si es el caso. En este caso, podéis ver como ese job simplemente crea el proyecto en PlatformIO CLI, convierte el sketch principal a .cpp y compila.

En la automatización de los tests unitarios simplemente se ingresa a la carpeta test/arduino/blink_led/unit y se ejecuta el comando make.

A destacar en esta GitHub Action que se ejecuta en el self-hosted runner, como puede verse en runs-on, y que solo se lanza en los Pull Requests en los que se hayan modificado ficheros del proyecto blink_led de Arduino o sus tests, como puede verse en paths.

40
acceptance_tests:
41
  name: ✅ Acceptance tests
42
  runs-on: self-hosted
43
  steps:
44
    - name: 📥 Checkout code
45
      uses: actions/checkout@v4
46
    - name: 🛠️ Set up PlatformIO CLI project
47
      run: |
48
        mkdir ${{ github.workspace }}/build
49
        pio project init -d build -b nucleo_f401re
50
        cd ${{ github.workspace }}/build
51
        echo "debug_tool = stlink" >> platformio.ini
52
        cp ${{ github.workspace }}/arduino/blink_led/* ${{ github.workspace }}/build/src || true
53
        mv ${{ github.workspace }}/build/src/blink_led.ino ${{ github.workspace }}/build/src/blink_led.cpp
54
        sed -i '1i#include "Arduino.h"' ${{ github.workspace }}/build/src/blink_led.cpp
55
    - name: 🏗️ Build and upload PlatformIO CLI project
56
      run: |
57
        cd ${{ github.workspace }}/build
58
        pio run --target upload
59
    - name: 🧬 Run acceptance tests
60
      run: |
61
        cd ${{ github.workspace }}/test/arduino/blink_led/acceptance
62
        /usr/bin/python3 -m venv .venv
63
        source .venv/bin/activate
64
        pip install -r requirements.txt
65
        python -m pytest -v

Proyecto de STM32CubeIDE/MX

Para el proyecto de STM32CubeIDE/MX, lo mismo que con Arduino. En un módulo aparte gestionamos el LED:

1
#ifndef INC_LED_H_
2
#define INC_LED_H_
3

4
void LED_turn_off(void);
5
void LED_turn_on(void);
6

7
#endif /* INC_LED_H_ */

1
#include "main.h"
2

3
void LED_turn_on(void) {
4
  HAL_GPIO_WritePin(LD2_GPIO_Port, LD2_Pin, GPIO_PIN_SET);
5
}
6

7
void LED_turn_off(void) {
8
  HAL_GPIO_WritePin(LD2_GPIO_Port, LD2_Pin, GPIO_PIN_RESET);
9
}

Las únicas diferencias con el código de Arduino son que en este caso nos ahorramos la función LED_config puesto que ya nos lo configura STM32CubeMX en la función MX_GPIO_Init, y que en lugar de llamar las funciones de Arduino para apagar/encender el LED, utilizamos las funciones de las HAL de STM32.

Estas funciones las llamamos luego en el fichero main.c.

1
#ifndef Main_H__
2
#define Main_H__
3

4
#include <stdint.h>
5

6
#define GPIO_PIN_RESET 0x0
7
#define GPIO_PIN_SET 0x1
8
#define LD2_Pin 0x0020
9
#define LD2_GPIO_Port ((GPIO_TypeDef*)0x40020000)
10

11
typedef uint32_t GPIO_TypeDef;
12
typedef uint32_t GPIO_PinState;
13

14
void HAL_GPIO_WritePin(GPIO_TypeDef *GPIOx, uint16_t GPIO_Pin,
15
GPIO_PinState PinState);
16

17
#endif /* Main_H__ */

1
#include "main.h"
2
#include "CppUTestExt/MockSupport_c.h"
3

4
void HAL_GPIO_WritePin(GPIO_TypeDef *GPIOx, uint16_t GPIO_Pin,
5
GPIO_PinState PinState) {
6
  mock_c()
7
      ->actualCall("HAL_GPIO_WritePin")
8
      ->withPointerParameters("GPIOx", GPIOx)
9
      ->withUnsignedIntParameters("GPIO_Pin", GPIO_Pin)
10
      ->withUnsignedLongIntParameters("PinState", PinState);
11

12
  return;
13
}

1
#include "CppUTest/TestHarness.h"
2
#include "CppUTestExt/MockSupport.h"
3
#include <stdexcept>
4
#include <stdio.h>
5

6
extern "C" {
7
#include "led.h"
8
#include "main.h"
9
}
10

11
TEST_GROUP(LED__management){};
12

13
TEST(LED__management, Turn__on) {
14
  mock()
15
      .expectOneCall("HAL_GPIO_WritePin")
16
      .withParameter("GPIOx", LD2_GPIO_Port)
17
      .withParameter("GPIO_Pin", LD2_Pin)
18
      .withParameter("PinState", GPIO_PIN_SET);
19

20
  LED_turn_on();
21

22
  mock().checkExpectations();
23
  mock().clear();
24
}
25

26

27

28
TEST(LED__management, Turn__off) {
29
  mock()
30
      .expectOneCall("HAL_GPIO_WritePin")
31
      .withParameter("GPIOx", LD2_GPIO_Port)
32
      .withParameter("GPIO_Pin", LD2_Pin)
33
      .withParameter("PinState", GPIO_PIN_RESET);
34

35
  LED_turn_off();
36

37
  mock().checkExpectations();
38
  mock().clear();
39
}

1
name: 🔌 Check STM32Cube Blink LED
2
on:
3
pull_request:
4
  paths:
5
    - stm32cube/blink_led/**
6
    - test/stm32cube/blink_led/**
7

8
jobs:
9
unit_tests:
10
  name: 🧪 Unit tests
11
  runs-on: self-hosted
12
  env:
13
    CPPUTEST_HOME: /opt/cpputest
14
  steps:
15
  - name: 📥 Checkout code
16
    uses: actions/checkout@v4
17
  - name: 🧬 Run unit tests
18
    run: |
19
      cd ${{ github.workspace }}/test/stm32cube/blink_led/unit
20
      make

21
acceptance_tests:
22
  name: ✅ Acceptance tests
23
  runs-on: self-hosted
24
  steps:
25
  - name: 📥 Checkout code
26
    uses: actions/checkout@v4
27
  - name: 🏗️ Upload .elf file
28
    run: |
29
      openocd -d2 -s ~/.platformio/packages/tool-openocd/openocd/scripts -f ~/.platformio/packages/tool-openocd/openocd/scripts/board/st_nucleo_f4.cfg -c "program "$(readlink -f stm32cube/blink_led/Debug/*.elf | head -n1)" verify reset; shutdown;"
30
  - name: 🧬 Run acceptance tests
31
    run: |
32
      cd ${{ github.workspace }}/test/stm32cube/blink_led/acceptance
33
      /usr/bin/python3 -m venv .venv
34
      source .venv/bin/activate
35
      pip install -r requirements.txt
36
      python -m pytest -v