Esercizio - Shell di RIOT con i comandi board, cpu ed echo (laboratorio 11)

Nota. I programmi di questa pagina non sono stati compilati in questo lavoro: servono il sorgente di RIOT 2023.04 e la toolchain AVR (gcc-avr, avr-libc), che qui non ci sono. Il codice segue le istruzioni del laboratorio e le API documentate di RIOT; va provato nella macchina virtuale del corso.

Preparazione (passaggi del laboratorio)

1. Spazio libero: almeno 500 MB (df -m /); si libera con sudo apt autoremove, sudo apt autoclean, sudo apt clean.
2. Compilatore e librerie C per il microcontrollore: sudo apt install gcc-avr avr-libc.
3. Sorgenti: scaricare RIOT 2023.04 (wget https://github.com/RIOT-OS/RIOT/archive/refs/tags/2023.04.zip) ed estrarlo (unzip 2023.04.zip): compare la cartella RIOT-2023.04.
4. Compilazione: cd RIOT-2023.04/examples/hello-world, poi make BOARD=arduino-mega2560; se va a buon fine c'è bin/arduino-mega2560/hello-world.elf.
5. Simulazione: aprire https://wokwi.com/projects/new/arduino-mega, premere F1 e scegliere "Upload Firmware and Start Simulation…", poi scegliere il file .elf: il simulatore stampa "Hello World" e altre informazioni su RIOT e sulla scheda.
6. Per un'applicazione propria si compila dalla sua cartella con make BOARD=arduino-mega2560 RIOTBASE=percorso-di-RIOT (per esempio RIOTBASE=/home/debianos/RIOT-2023.04). Il percorso non deve contenere spazi, altrimenti make fallisce.

La shell (Makefile e main.c)

Makefile: si aggiunge il modulo della shell:

USEMODULE += shell

main.c: la shell si avvia con shell_run(comandi, buffer, dimensione). Si passa NULL al posto dei comandi per avere solo quelli di base (help elenca i comandi disponibili). Per aggiungere i propri comandi:

1. una funzione per ogni comando, con la firma int nome(int argc, char **argv): argc è il numero di parole della riga (compreso il comando) e argv i puntatori alle parole (come nel main di un programma C);
2. un vettore di shell_command_t: nome, descrizione e funzione, terminato da { NULL, NULL, NULL };
3. la chiamata a shell_run con quel vettore.

#include <stdio.h>

#include "shell.h"

static int _board_handler(int argc, char **argv)
{
    (void)argc; /* non usati: evitano un avviso in compilazione */
    (void)argv;
    puts(RIOT_BOARD); /* macro predefinita: nome della scheda */
    return 0;
}

static int _cpu_handler(int argc, char **argv)
{
    (void)argc;
    (void)argv;
    puts(RIOT_CPU); /* macro predefinita: nome del processore */
    return 0;
}

/* echo: stampa gli argomenti separati da uno spazio */
static int _echo_handler(int argc, char **argv)
{
    for (int i = 1; i < argc; i++) { /* argv[0] e' "echo" stesso */
        printf("%s", argv[i]);
        if (i + 1 < argc) {
            printf(" ");
        }
    }
    puts("");
    return 0;
}

static const shell_command_t shell_commands[] = {
    { "board", "Print the board name", _board_handler },
    { "cpu", "Print the cpu name", _cpu_handler },
    { "echo", "Print the arguments", _echo_handler },
    { NULL, NULL, NULL }
};

int main(void)
{
    puts("RIOT shell");

    char line_buf[SHELL_DEFAULT_BUFSIZE];
    shell_run(shell_commands, line_buf, SHELL_DEFAULT_BUFSIZE);

    return 0;
}

Come funziona

• RIOT_BOARD e RIOT_CPU sono due macro definite dal sistema di compilazione di RIOT con il nome della scheda e della CPU per cui si compila (per la scheda, arduino-mega2560): sono stringhe e si stampano con puts.
• La shell legge una riga da tastiera (nel simulatore, dal terminale seriale), la divide in parole e cerca il comando nel vettore: se lo trova chiama la funzione con argc e argv. Per echo Hello world! si ha argc = 3, argv[0] = "echo", argv[1] = "Hello", argv[2] = "world!"; il ciclo parte da i = 1 e stampa Hello world!.
• shell_run non ritorna mai: il return 0 dopo la chiamata non viene eseguito, e tutto ciò che deve partire prima della shell (per esempio altri thread) va messo prima della chiamata (vedi Esercizio - Thread e mutex in RIOT con un buffer condiviso (laboratorio 12)).
• Provare in Wokwi: help mostra i comandi (quelli di base e i tre aggiunti); board, cpu e echo Hello world! mostrano i risultati.

Errori tipici

• Percorsi con spazi: make si interrompe.
• Dimenticare USEMODULE += shell nel Makefile: shell.h non si trova.
• Non terminare il vettore dei comandi con { NULL, NULL, NULL }: la shell scorre oltre la fine.
• Partire da i = 0 nell'echo: si stamperebbe anche il nome del comando.
• Mettere codice dopo shell_run aspettandosi che venga eseguito.