Librería para el módulo LCD HD44780 en STM32

Fork de: eziya/STM32_HAL_I2C_HD44780
Esta librería es un fork del trabajo original de Eziya, al cual se le añadió manejo robusto de errores mediante códigos de retorno en todas las funciones públicas, delays basados en DWT y caracteres especiales predefinidos.

Tabla de Contenidos

Librería para el módulo LCD HD44780 en STM32

Descripción

Librería desarrollada en C para la interfaz con el módulo LCD HD44780 utilizando microcontroladores STM32. Proporciona funciones para controlar el display a través de un expansor I/O PCF8574 por comunicación I2C, operando en modo de 4 bits. La librería está diseñada para ser fácil de usar, eficiente y compatible con la mayoría de las series STM32 (F1, F4, etc.) utilizando HAL.

Es adecuada para mostrar texto, valores de sensores, menús simples o cualquier información alfanumérica en aplicaciones embebidas.

Características

Comunicación I2C: Interfaz mediante expansor PCF8574 en modo 4 bits, reduciendo los pines GPIO necesarios a solo SDA y SCL.
Manejo robusto de errores: Todas las funciones públicas retornan HD44780_Status_t, con códigos específicos para error de I2C, timeout, módulo no inicializado o parámetro inválido.
Delays de alta precisión basados en DWT: Utiliza el contador de ciclos del núcleo Cortex-M para delays en microsegundos sin bloquear el scheduler.
Caracteres especiales predefinidos: Siete arrays const exportados en HD44780.h (heart, degrees, Flecha, Campana, etc.) listos para pasarse a HD44780_CreateSpecialChar(). Solo se cargan los que la aplicación necesita, eliminando bytes I2C innecesarios en la inicialización.
Control completo de display: Funciones para encender/apagar pantalla, cursor, parpadeo, retroiluminación y modo de desplazamiento.
Portabilidad: Compatible con múltiples familias STM32 mediante la capa HAL. Solo requiere cambiar el #include del encabezado HAL en HD44780.h.

Pinout y Conexiones

Pines requeridos

Pin HD44780 (PCF8574)	Dirección	Descripción	Tipo GPIO	Observaciones
VCC	Alimentación	5 V	N/A	El módulo PCF8574 opera a 5 V
GND	Tierra	—	N/A	—
SDA	Open-drain	Datos I2C	`GPIO_AF_OD`	Requiere resistencia pull-up (4.7 kΩ)
SCL	Open-drain	Reloj I2C	`GPIO_AF_OD`	Requiere resistencia pull-up (4.7 kΩ)

Note

Los módulos comerciales con PCF8574 generalmente incluyen resistencias pull-up integradas en la placa. Verifica si tu módulo ya las trae antes de agregar resistencias externas.

Warning

El LCD HD44780 opera a 5 V. Si tu STM32 trabaja a 3.3 V, verifica que los pines I2C sean tolerantes a 5 V o utiliza un convertidor de nivel lógico.

Configuración I2C

Configura tu periférico I2C en CubeMX/STM32CubeIDE:

Parámetro	Valor	Notas
Mode	I2C Master	El STM32 actúa como maestro
Speed Mode	Standard (100 kHz)	Fast Mode (400 kHz) también es compatible
Clock Speed	100000 Hz	Reducir si hay problemas de comunicación
Address Length	7 bits	—

Note

La dirección I2C del módulo es: 0x27 (7 bits). La librería la define internamente como HD44780_ADDRESS (0x27 << 1) en formato de 8 bits para HAL. Si tu módulo PCF8574 tiene una dirección diferente (p. ej. 0x3F), ajusta la macro en HD44780.h.

Instalación

Copia HD44780.c y HD44780.h a tu proyecto (ej: Drivers/HD44780/).

Ajusta el #include del encabezado HAL en HD44780.h según tu familia STM32:

// STM32F0xx:
#include "stm32f0xx_hal.h"
// STM32F1xx:
#include "stm32f1xx_hal.h"
// STM32F4xx:
#include "stm32f4xx_hal.h"

Incluye la librería en tu main.c o archivo principal:
```
#include "HD44780.h"
```
Configura I2C y GPIOs en CubeMX (ver sección anterior).
Genera código y compila.

Uso Básico

1. Inicialización

// En main() después de HAL_Init() y MX_I2C1_Init()
HD44780_Status_t status = HD44780_Init(&hi2c1, 2, 16);  // display de 2 filas y 16 columnas

if (status != HD44780_OK) {
    Error_Handler();  // Módulo no responde o handle NULL
}

2. Imprimir texto

// Posicionar el cursor en columna 0, fila 0 e imprimir
HD44780_SetCursor(0, 0);
HD44780_PrintStr("Hola STM32!");

// Segunda línea
HD44780_SetCursor(0, 1);
HD44780_PrintStr("Temp: 25.3 C");

3. Caracteres especiales

La librería exporta en HD44780.h siete arrays predefinidos listos para usar. Carga únicamente los que tu aplicación necesite después de HD44780_Init():

// Cargar solo los caracteres que se van a usar
HD44780_CreateSpecialChar(0, degrees);   // símbolo de grados en posición 0
HD44780_CreateSpecialChar(1, heart);     // corazón en posición 1

// Imprimir temperatura con símbolo de grados
HD44780_SetCursor(10, 1);
HD44780_PrintStr("25.3");
HD44780_PrintSpecialChar(0);   // imprime °
HD44780_PrintStr("C");

// También puedes definir tu propio carácter en cualquier posición (0-7):
uint8_t myChar[8] = {0x0E, 0x0E, 0x04, 0x1F, 0x04, 0x04, 0x04, 0x00};
HD44780_CreateSpecialChar(2, myChar);
HD44780_PrintSpecialChar(2);

Arrays predefinidos disponibles en HD44780.h:

Variable	Descripción
`special1`	Carácter especial 1
`special2`	Carácter especial 2
`heart`	Corazón ♥
`Cyrilic`	Carácter cirílico
`Flecha`	Flecha →
`Campana`	Campana
`degrees`	Símbolo de grados °

Note

La CGRAM del HD44780 permite almacenar hasta 8 caracteres personalizados (posiciones 0–7). Al no cargar ninguno automáticamente, todas las posiciones quedan disponibles para el usuario.

API Reference

1. Tipos de Datos

`HD44780_Status_t` - Estados de Retorno

Enumeración que define todos los códigos de retorno posibles para las funciones de la librería, permitiendo una gestión robusta de errores y estados del módulo.

typedef enum {
    HD44780_OK              = 0,    /**< Operación exitosa */
    HD44780_ERROR           = 1,    /**< Error en la operación */
    HD44780_TIMEOUT         = 2,    /**< Timeout en la operación */
    HD44780_NOT_INITIALIZED = 3,    /**< Módulo no inicializado */
    HD44780_INVALID_PARAM   = 4,    /**< Parámetro inválido */
} HD44780_Status_t;

Valor	Código	Significado
`HD44780_OK`	0	Operación completada sin errores
`HD44780_ERROR`	1	Error de I2C, parámetro inválido o condición inesperada
`HD44780_TIMEOUT`	2	Timeout de HAL durante la transmisión I2C
`HD44780_NOT_INITIALIZED`	3	`HD44780_Init()` no se llamó o falló
`HD44780_INVALID_PARAM`	4	Puntero NULL u otro parámetro fuera de rango

2. Funciones Públicas

`HD44780_Init()` - Inicialización del Driver

Inicializa el módulo HD44780: configura el handle I2C, ejecuta la secuencia de arranque en modo 4 bits y establece el display en estado por defecto (encendido, sin cursor, sin parpadeo). No carga caracteres en la CGRAM; el usuario llama a HD44780_CreateSpecialChar() para los caracteres que necesite.

HD44780_Status_t HD44780_Init(I2C_HandleTypeDef* hi2c, uint8_t rows, uint8_t cols);

Parámetro	Tipo	Descripción
`hi2c`	`I2C_HandleTypeDef*`	Puntero al handle I2C de HAL
`rows`	`uint8_t`	Número de filas del display (1 o 2)
`cols`	`uint8_t`	Número de columnas del display (p. ej. 16 o 20)

Retorna: HD44780_OK si la inicialización fue exitosa, HD44780_INVALID_PARAM si hi2c es NULL, rows es 0 o cols es 0, HD44780_ERROR / HD44780_TIMEOUT si falla la comunicación I2C.

Secuencia interna:

Valida parámetros y guarda el handle I2C.
Inicializa el contador DWT para delays en microsegundos.
Ejecuta la secuencia de reset en modo 4 bits según el datasheet del HD44780.
Configura el display: modo 4 bits, número de líneas, cursor apagado, retroiluminación encendida.

`HD44780_Clear()` - Borrar pantalla

Borra todo el contenido del display y retorna el cursor a la posición (0, 0).

HD44780_Status_t HD44780_Clear(void);

Retorna: HD44780_OK si la operación fue exitosa, HD44780_ERROR / HD44780_TIMEOUT si falla la comunicación I2C.

`HD44780_ClearLine()` - Borrar una fila

Borra el contenido de una fila específica escribiendo espacios en todas sus columnas, sin afectar el resto del display. Al terminar, deja el cursor al inicio de la fila borrada.

HD44780_Status_t HD44780_ClearLine(uint8_t row);

Parámetro	Tipo	Descripción	Rango
`row`	`uint8_t`	Fila a borrar (0-indexed)	0 – `rows-1`

Retorna: HD44780_OK si la operación fue exitosa, HD44780_NOT_INITIALIZED si el módulo no fue inicializado, HD44780_INVALID_PARAM si row es mayor o igual al número de filas configuradas, HD44780_ERROR / HD44780_TIMEOUT si falla la comunicación I2C.

// Borrar solo la segunda fila y escribir nuevo contenido
HD44780_ClearLine(1);
HD44780_PrintStr("Nuevo texto");

`HD44780_Home()` - Regresar al inicio

Retorna el cursor a la posición (0, 0) sin borrar el contenido del display.

HD44780_Status_t HD44780_Home(void);

Retorna: HD44780_OK si la operación fue exitosa, HD44780_ERROR / HD44780_TIMEOUT si falla la comunicación I2C.

`HD44780_SetCursor()` - Posicionar cursor

Mueve el cursor a la columna y fila indicadas.

HD44780_Status_t HD44780_SetCursor(uint8_t col, uint8_t row);

Parámetro	Tipo	Descripción	Rango
`col`	`uint8_t`	Columna destino (0-indexed)	0 – 15 (16 col)
`row`	`uint8_t`	Fila destino (0-indexed)	0 – `rows-1`

Retorna: HD44780_OK si la operación fue exitosa, HD44780_NOT_INITIALIZED si el módulo no fue inicializado, HD44780_ERROR / HD44780_TIMEOUT si falla la comunicación I2C.

`HD44780_PrintStr()` - Imprimir cadena

Imprime una cadena de caracteres terminada en \0 en la posición actual del cursor.

HD44780_Status_t HD44780_PrintStr(const char c[]);

Parámetro	Tipo	Descripción
`c`	`const char*`	Cadena de caracteres a imprimir

Retorna: HD44780_OK si la cadena se imprimió completa, HD44780_INVALID_PARAM si c es NULL, HD44780_NOT_INITIALIZED si el módulo no fue inicializado, HD44780_ERROR / HD44780_TIMEOUT si falla la comunicación I2C.

`HD44780_PrintInt()` - Imprimir número entero

Convierte un número entero a su representación decimal y lo imprime en la posición actual del cursor.

HD44780_Status_t HD44780_PrintInt(int num);

Parámetro	Tipo	Descripción
`num`	`int`	Número entero a imprimir

Retorna: HD44780_OK si el número se imprimió correctamente, HD44780_NOT_INITIALIZED si el módulo no fue inicializado, HD44780_ERROR si ocurrió un error interno al convertir el número.

// Imprimir un valor de sensor
HD44780_SetCursor(0, 0);
HD44780_PrintStr("Temp: ");
HD44780_PrintInt(25);
HD44780_PrintStr(" C");

`HD44780_PrintSpecialChar()` - Imprimir carácter especial

Imprime en la posición actual del cursor el carácter almacenado en la CGRAM en el índice indicado.

HD44780_Status_t HD44780_PrintSpecialChar(uint8_t index);

Parámetro	Tipo	Descripción	Rango
`index`	`uint8_t`	Índice del carácter en CGRAM	0 – 7

Retorna: HD44780_OK si la operación fue exitosa, HD44780_NOT_INITIALIZED si el módulo no fue inicializado, HD44780_ERROR / HD44780_TIMEOUT si falla la comunicación I2C.

Note

El índice debe coincidir con la posición location usada al llamar a HD44780_CreateSpecialChar(). Si no se cargó ningún carácter en esa posición, el resultado en pantalla es indefinido.

`HD44780_CreateSpecialChar()` - Crear carácter personalizado

Define un carácter personalizado de 5×8 píxeles y lo almacena en la CGRAM del LCD en la posición indicada.

HD44780_Status_t HD44780_CreateSpecialChar(uint8_t location, const uint8_t charmap[]);

Parámetro	Tipo	Descripción	Rango
`location`	`uint8_t`	Posición en CGRAM	0 – 7
`charmap`	`const uint8_t*`	Array de 8 bytes con el mapa de bits del carácter	—

Puedes pasar directamente cualquiera de los arrays predefinidos exportados en HD44780.h:

HD44780_CreateSpecialChar(0, degrees);
HD44780_CreateSpecialChar(1, heart);
HD44780_CreateSpecialChar(2, Campana);

Retorna: HD44780_OK si el carácter se almacenó correctamente, HD44780_INVALID_PARAM si charmap es NULL, HD44780_ERROR / HD44780_TIMEOUT si falla la comunicación I2C.

`HD44780_LoadCustomCharacter()` - Cargar carácter personalizado

Alias de HD44780_CreateSpecialChar(). Carga un carácter personalizado en la CGRAM.

HD44780_Status_t HD44780_LoadCustomCharacter(uint8_t char_num, const uint8_t *rows);

Parámetro	Tipo	Descripción
`char_num`	`uint8_t`	Posición en CGRAM (0–7)
`rows`	`const uint8_t*`	Array de 8 bytes con el mapa de bits del carácter

Retorna: HD44780_OK si la operación fue exitosa, HD44780_INVALID_PARAM si rows es NULL, HD44780_ERROR / HD44780_TIMEOUT si falla la comunicación I2C.