serial.c

/**
 * @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");
}