Implementazione libreria UART con I/O avanzato

Questo commit aggiunge una libreria completa per la comunicazione seriale UART su STM32.

Funzionalità principali:
- Funzioni di output simili a printf (serial_printf, serial_printfln)
- Input con supporto per editing di linea (backspace, gestione terminale)
- Funzioni di input formattato simili a scanf
- Comandi di controllo del terminale (clear screen)

Tutti i file sono ampiamente documentati con commenti in stile Doxygen.

Author: luca-software-developer

serial.c

@@ -0,0 +1,202 @@
+/**
+ * @file serial.c
+ * @brief Implementazione delle funzioni di I/O tramite UART per STM32.
+ *
+ * Questo file contiene l'implementazione delle funzioni necessarie per
+ * leggere e scrivere dati tramite UART, inclusi la lettura di righe,
+ * l'invio di stringhe e la gestione del formato di input.
+ */
+
+#include "serial.h"
+
+/**
+ * @brief Stampa una stringa su UART
+ *
+ * Questa funzione invia una stringa tramite UART, senza aggiungere newline.
+ *
+ * @param message Stringa da stampare
+ */
+void serial_print(char *message) {
+	// Utilizza la funzione HAL_UART_Transmit per inviare i caratteri della stringa
+	// attraverso la UART, considerando la lunghezza calcolata con strlen().
+	HAL_UART_Transmit(&hlpuart1, (uint8_t*) message, strlen(message),
+			HAL_MAX_DELAY);
+}
+
+/**
+ * @brief Stampa una nuova riga su UART ("\r\n")
+ *
+ * Invia un carattere di ritorno a capo seguito da newline, simile alla
+ * stampa di una nuova riga in un terminale.
+ */
+void serial_newline(void) {
+	// Utilizza la funzione serial_print per inviare i caratteri di ritorno a capo e newline.
+	serial_print("\r\n");
+}
+
+/**
+ * @brief Stampa una stringa seguita da una nuova riga
+ *
+ * Questa funzione invia una stringa tramite UART, seguita automaticamente
+ * da un ritorno a capo (`\r\n`).
+ *
+ * @param message Stringa da stampare
+ */
+void serial_println(char *message) {
+	// Stampa la stringa fornita utilizzando serial_print.
+	serial_print(message);
+
+	// Aggiunge una nuova riga alla fine della stringa.
+	serial_newline();
+}
+
+/**
+ * @brief Stampa una stringa formattata su UART (come printf)
+ *
+ * Questa funzione invia una stringa formattata tramite UART, simile
+ * alla funzione `printf`.
+ *
+ * @param format Formato della stringa
+ * @param ... Argomenti da formattare
+ * @return Numero di caratteri scritti
+ */
+int serial_printf(const char *format, ...) {
+	char buffer[256];
+
+	va_list args;
+
+	// Inizializza la lista degli argomenti variabili.
+	va_start(args, format);
+
+	// Scrive la stringa formattata nel buffer utilizzando vsnprintf.
+	int ret = vsnprintf(buffer, sizeof(buffer), format, args);
+
+	// Termina la gestione degli argomenti variabili.
+	va_end(args);
+
+	// Trasmette la stringa formattata tramite UART.
+	serial_print(buffer);
+
+	// Restituisce il numero di caratteri scritti.
+	return ret;
+}
+
+/**
+ * @brief Stampa una stringa formattata seguita da una nuova riga
+ *
+ * Questa funzione invia una stringa formattata tramite UART, seguita
+ * automaticamente da un ritorno a capo (`\r\n`), simile a `printf`.
+ *
+ * @param format Formato della stringa
+ * @param ... Argomenti da formattare
+ * @return Numero di caratteri scritti
+ */
+int serial_printfln(const char *format, ...) {
+	char buffer[256];
+
+	va_list args;
+
+	// Inizializza la lista degli argomenti variabili.
+	va_start(args, format);
+
+	// Scrive la stringa formattata nel buffer utilizzando vsnprintf.
+	int ret = vsnprintf(buffer, sizeof(buffer), format, args);
+
+	// Termina la gestione degli argomenti variabili.
+	va_end(args);
+
+	// Trasmette la stringa formattata tramite UART.
+	serial_print(buffer);
+
+	// Aggiunge una nuova riga alla fine della stringa trasmessa.
+	serial_newline();
+
+	// Restituisce il numero di caratteri scritti.
+	return ret;
+}
+
+/**
+ * @brief Legge una riga da UART con supporto a frecce sinistra/destra e backspace
+ *
+ * Questa funzione permette la lettura di una riga con un buffer di input,
+ * supportando la gestione del backspace per rimuovere i caratteri e
+ * la gestione di un terminale che simula il comportamento di frecce sinistra e destra.
+ *
+ * @param buffer Buffer dove salvare la stringa
+ * @param length Lunghezza massima del buffer (incluso null terminator)
+ */
+void serial_readline(char *buffer, int length) {
+	size_t i = 0;
+
+	// Itera fino a riempire il buffer o fino a rilevare un carattere di terminazione
+	while (i < length - 1) {
+		uint8_t c;
+
+		// Riceve un carattere dalla UART con un timeout massimo
+		if (HAL_UART_Receive(&hlpuart1, &c, 1, HAL_MAX_DELAY) == HAL_OK) {
+			// Se il carattere ricevuto è '\r' o '\n', termina la stringa
+			if (c == '\r' || c == '\n') {
+				buffer[i] = '\0'; // Aggiunge terminatore di stringa
+				serial_print("\r\n"); // Stampa ritorno a capo
+				break;
+			}
+			// Gestisce il backspace (127 o 8)
+			else if (c == 127 || c == 8) {
+				if (i > 0) {
+					i--; // Rimuove l'ultimo carattere
+					serial_print("\b \b"); // Emette sequenza per cancellare il carattere
+				}
+			}
+			// Gestisce caratteri normali
+			else {
+				buffer[i++] = c; // Aggiunge il carattere al buffer
+				HAL_UART_Transmit(&hlpuart1, &c, 1, HAL_MAX_DELAY); // Echo del carattere
+			}
+		}
+	}
+
+	buffer[i] = '\0'; // Termina la stringa con il carattere nullo
+}
+
+/**
+ * @brief Versione personalizzata di scanf che legge da UART
+ *
+ * Questa funzione legge una riga tramite `serial_readline()` e converte
+ * il formato dell'input con `sscanf()`, simile a come farebbe `scanf()`.
+ *
+ * @param format Stringa di formato come in scanf
+ * @param ... Argomenti variabili da riempire
+ * @return Numero di elementi letti con successo
+ */
+int serial_scanf(const char *format, ...) {
+	char buffer[128];
+
+	// Legge una riga di input dalla UART e la salva nel buffer.
+	serial_readline(buffer, sizeof(buffer));
+
+	va_list args;
+
+	// Inizializza la lista di argomenti variabili.
+	va_start(args, format);
+
+	// Usa sscanf per convertire il formato dell'input dal buffer in base ai parametri specificati.
+	int ret = vsscanf(buffer, format, args);
+
+	// Termina la gestione degli argomenti variabili.
+	va_end(args);
+
+	// Restituisce il numero di elementi letti con successo.
+	return ret;
+}
+
+/**
+ * @brief Pulisce lo schermo del terminale
+ *
+ * Invia una sequenza di escape per pulire lo schermo del terminale
+ * tramite UART, se supportato dal terminale stesso.
+ */
+void serial_clear(void) {
+	// Invia una sequenza di escape ANSI tramite UART per pulire
+	// lo schermo e riposizionare il cursore.
+	serial_print("\033[2J\033[H");
+}

serial.h

@@ -0,0 +1,101 @@
+/**
+ * @file serial.h
+ * @brief Interfaccia per la gestione dell'I/O su UART con comportamento da terminale
+ *
+ * Questo file header fornisce le dichiarazioni delle funzioni per la stampa,
+ * la lettura formattata e la gestione dell'input da UART con funzioni avanzate
+ * di editing linea e visualizzazione simile a un terminale.
+ */
+
+#ifndef INC_SERIAL_H_
+#define INC_SERIAL_H_
+
+#include "usart.h"
+#include "string.h"
+#include "stdio.h"
+#include "stdarg.h"
+
+/**
+ * @brief Stampa una stringa su UART
+ *
+ * Questa funzione invia una stringa tramite UART, senza aggiungere newline.
+ *
+ * @param message Stringa da stampare
+ */
+void serial_print(char *message);
+
+/**
+ * @brief Stampa una nuova riga su UART ("\r\n")
+ *
+ * Invia un carattere di ritorno a capo seguito da newline, simile alla
+ * stampa di una nuova riga in un terminale.
+ */
+void serial_newline(void);
+
+/**
+ * @brief Stampa una stringa seguita da una nuova riga
+ *
+ * Questa funzione invia una stringa tramite UART, seguita automaticamente
+ * da un ritorno a capo (`\r\n`).
+ *
+ * @param message Stringa da stampare
+ */
+void serial_println(char *message);
+
+/**
+ * @brief Stampa una stringa formattata su UART (come printf)
+ *
+ * Questa funzione invia una stringa formattata tramite UART, simile
+ * alla funzione `printf`.
+ *
+ * @param format Formato della stringa
+ * @param ... Argomenti da formattare
+ * @return Numero di caratteri scritti
+ */
+int serial_printf(const char *format, ...);
+
+/**
+ * @brief Stampa una stringa formattata seguita da una nuova riga
+ *
+ * Questa funzione invia una stringa formattata tramite UART, seguita
+ * automaticamente da un ritorno a capo (`\r\n`), simile a `printf`.
+ *
+ * @param format Formato della stringa
+ * @param ... Argomenti da formattare
+ * @return Numero di caratteri scritti
+ */
+int serial_printfln(const char *format, ...);
+
+/**
+ * @brief Legge una riga da UART con supporto a frecce sinistra/destra e backspace
+ *
+ * Questa funzione permette la lettura di una riga con un buffer di input,
+ * supportando la gestione del backspace per rimuovere i caratteri e
+ * la gestione di un terminale che simula il comportamento di frecce sinistra e destra.
+ *
+ * @param buffer Buffer dove salvare la stringa
+ * @param length Lunghezza massima del buffer (incluso null terminator)
+ */
+void serial_readline(char *buffer, int length);
+
+/**
+ * @brief Versione personalizzata di scanf che legge da UART
+ *
+ * Questa funzione legge una riga tramite `serial_readline()` e converte
+ * il formato dell'input con `sscanf()`, simile a come farebbe `scanf()`.
+ *
+ * @param format Stringa di formato come in scanf
+ * @param ... Argomenti variabili da riempire
+ * @return Numero di elementi letti con successo
+ */
+int serial_scanf(const char *format, ...);
+
+/**
+ * @brief Pulisce lo schermo del terminale
+ *
+ * Invia una sequenza di escape per pulire lo schermo del terminale
+ * tramite UART, se supportato dal terminale stesso.
+ */
+void serial_clear(void);
+
+#endif /* INC_SERIAL_H_ */