Dokumentacja pliku hd44780.h

Sterowanie wyświetlaczem alfanumerycznym HD44780. Więcej...

#include "macros.h"
#include <avr/io.h>
#include <avr/pgmspace.h>
#include <stdio.h>
#include "hd44780.c"

Idź do kodu źródłowego tego pliku.

Definicje

#define HD44780_PUTSTR(str)   hd44780_putStr(str, -1)

#define HD44780_PUTPSTR(str)   hd44780_putPStr(PSTR(str), sizeof(str) - 1)

#define HD44780_PUTINT(val)   hd44780_putInt(val, 10, 0)

#define HD44780_BIND_STREAM(stream_name)

Funkcje

void hd44780_init ()

void hd44780_clear ()

void hd44780_goto (uint8_t x, uint8_t y)

void hd44780_putChar (uint8_t c)

void hd44780_putStr (char *str, uint8_t length)

void hd44780_putPStr (const char *pstr, uint8_t length)

void hd44780_putInt (int val, uint8_t radix, uint8_t lpad)

void hd44780_loadChar (uint8_t addr, const uint8_t data[8])

void hd44780_loadCharSet (const uint8_t data[64])

Opis szczegółowy

Sterowanie wyświetlaczem alfanumerycznym HD44780.

Przed użyciem biblioteki, należy zdefiniować stałe:

HD44780_WIDTH, HD44780_HEIGHT - szerokość i wysokość wyświetlacza. Na podstawie tych wartości zostanie automatycznie zdefiniowana stała HD44780_DOUBLE, wskazująca na wyświetlacz z dwoma kontrolerami,
HD44780_DATA_GPIO - do którego portu jest podłączona szyna danych (np. C),
HD44780_DATA_HIGHHALFBYTE - w trybie 4bit: czy szyna danych zajmuje wyższe bity (DB4 = PORTC4, DB5 = PORTC5, DB6 = PORTC6, DB7 = PORTC7). Jeżeli stała jest wyzerowana, szyna danych zajmuje niższe bity (DB4 = PORTC0, DB5 = PORTC1, DB6 = PORTC2, DB7 = PORTC3),
HD44780_RS_GPIO, HD44780_RS_BIT - port (np. C) i bit (np. 0) zajmowany przez pin sterowania RS,
HD44780_E1_GPIO, HD44780_E1_BIT - port i bit zajmowany przez pin aktywacji (E) wyświetlacza. W wyświetlaczach posiadających dwie linie E, jest to pierwsza z nich,
HD44780_E2_GPIO, HD44780_E2_BIT - druga z linii E. Jeżeli wyświetlacz posiada tylko jedną linię E, można nie definiować tej stałej.

Ponadto, na początku programu powinna być wywołana funkcja hd44780_init().

Stałe opcjonalne:

HD44780_CHARSET - pozwala wybrać zestaw znaków, domyślnie ładowany przy inicjowaniu wyświetlacza. Lista dostępnych zestawów jest w dokumentacji pliku charsets.h,
HD44780_CODEPAGE - pozwala wybrać inny niż domyślny sposób kodowania liter (będących parametrami funkcji hd44780_putChar() i korzystających z niej). Lista dostępnych kodowań jest w dokumentacji pliku charsets.h,
HD44780_RW_GPIO, HD44780_RW_BIT - port (np. C) i bit (np. 0) zajmowany przez pin sterowania RW (potrzebny m.in. do odczytu flagi zajętości),
HD44780_DATA_CUSTOM - jeżeli jest konieczne indywidualne przypisanie wszystkich bitów szyny danych, należy ustawić tą stałą, oraz zdefiniować stałe HD44780_DATA_DBx_GPIO oraz HD44780_DATA_DBx_BIT, gdzie x jest liczbą 4-7. W tym przypadku nie trzeba definiować stałych HD44780_DATA_GPIO i HD44780_DATA_HIGHHALFBYTE. Należy pamiętać, że zmniejsza to wydajność programu oraz zwiększa jego rozmiar,
HD44780_DATA_8BIT - użycie trybu komunikacji 8bit - pozwala na zmniejszenie rozmiaru programu oraz nieznaczne zwiększenie wydajności. W tym trybie nie ma możliwości użycia HD44780_DATA_CUSTOM (linie do komunikacji zajmują cały port HD44780_DATA_GPIO) oraz nie należy definiować stałej HD44780_DATA_HIGHHALFBYTE,
HD44780_DOUBLE - jeżeli wyświetlacz korzysta z dwóch linii E, należy ustawić tą stałą oraz HD44780_E2_GPIO i HD44780_E2_BIT (domyślnie ustawiona dla wyświetlaczy posiadających więcej niż 80 znaków).

Uwaga:: Jeżeli sterowanie ma przebiegać bez odczytu flagi zajętości (nie są zdefiniowane stałe HD44780_RW_GPIO i HD44780_RW_BIT, pin RW wyświetlacza powinien być połączony z masą.

Nota:: Wykorzystanie odczytu flagi zajętości zwiększa szybkość (w przybliżeniu czterokrotne) komunikacji z wyświetlaczem. Ponadto, jeżeli jest wykorzystany HD44780_BIND_STREAM(), sterowanie linią RW pozwala na przewijanie ekranu.

Przykładowe wykorzystanie:

#define F_CPU 16000000

/* pod którym portem jest szyna danych */
#define HD44780_DATA_GPIO C

/* jaką część portu zajmuje szyna danych:
 * true: DB4 = bit 4, DB5 = bit 5, DB6 = bit 6, DB7 = bit 7
 * false: DB4 = bit 0, DB5 = bit 1, DB6 = bit 2, DB7 = bit 3
 */
#define HD44780_DATA_HIGHHALFBYTE 1

#define HD44780_RS_GPIO C
#define HD44780_RS_BIT 1

#define HD44780_E1_GPIO C
#define HD44780_E1_BIT 2

#define HD44780_E2_GPIO C
#define HD44780_E2_BIT 3

#define HD44780_WIDTH 40
#define HD44780_HEIGHT 4

#define HD44780_CHARSET HD44780_CHARSET_PL
#define HD44780_CODEPAGE HD44780_CODEPAGE_UTF8

#include <tAvrLib/hd44780.h>

int main()
{
        const char *p;

        /* inicjacja wyświetlacza */
        hd44780_init();

        /* powiązanie wyświetlacza ze standardowym wyjściem */
        HD44780_BIND_STREAM(stdout);
        
        /* wyświetlenie napisu [TEST] w rogach ekranu (poza prawym dolnym) */
        p = PSTR("[TEST]");
        hd44780_goto(0, 0);
        hd44780_putPStr(p, -1);
        hd44780_goto(HD44780_WIDTH - 6, 0);
        hd44780_putPStr(p, -1);
        hd44780_goto(0, HD44780_HEIGHT - 1);
        hd44780_putPStr(p, -1);
        
        /* wyświetlenie liczby 123 w prawym dolnym ekranie, w systemie
         * dziesiętnym, wyrównanej do prawej
         */
        hd44780_goto(HD44780_WIDTH - 6, HD44780_HEIGHT - 1);
        hd44780_putChar('|');
        hd44780_putInt(123, 10, 5);

        /* wyświetlenie przykładowego tekstu w drugiej linii, zaczynając od
         * drugiej kolumny
         */
        hd44780_goto(1, 1);
        HD44780_PUTPSTR("Przykład wykorzystania tAvrLib/hd44780");

        /* test standardowego wyjścia */
        printf("\n\tTest stdout: [%d]", 123);

        return 0;
}

Schemat połączeń dla powyższego przykładu (jeżeli wyświetlacz ma tylko jedną linię E, drugą należy pominąć, a PC3 zostawić nie podłączony):

Autor:: Tomasz Wasilczyk (http://www.wasilczyk.pl)

Dokumentacja definicji

#define HD44780_PUTSTR ( str ) hd44780_putStr(str, -1)

Makro wyświetlające tekst z pamięci RAM, zakończony znakiem NULL.

Parametry:

str

Tekst do wyświetlenia

Zobacz również:: hd44780_putStr()

#define HD44780_PUTPSTR ( str ) hd44780_putPStr(PSTR(str), sizeof(str) - 1)

Makro definiujące tekst w pamięci programu i go wyświetlające.

Nota:: Jeżeli w wielu miejscach programu wyświetlasz ten sam tekst, warto w celu oszczędzenia pamięci programu zdefiniować go tylko raz i wyświetlić ręcznie, za pomocą hd44780_putPStr().

Parametry:

str

Tekst do wyświetlenia

Zobacz również:: hd44780_putPStr()

#define HD44780_PUTINT ( val ) hd44780_putInt(val, 10, 0)

Makro wyświetlające liczbę w systemie dziesiętnym, bez wyrównania do prawej.

Parametry:

val

Wartość do wyświetlenia

Zobacz również:: hd44780_putInt()

#define HD44780_BIND_STREAM ( stream_name )

Wartość:

{ \
        fdev_setup_stream(&_hd44780_stream, _hd44780_putStreamChar, NULL, _FDEV_SETUP_WRITE); \
        stream_name = &_hd44780_stream; \
}

Związuje wybrany strumień z wyświetlaczem. Pozwala m.in. na korzystanie ze standardowego wyjścia. Można związać więcej niż jeden strumień (np. stdout i stderr).

Przykład użycia:

 HD44780_BIND_STREAM(stdout);
 printf("liczba: %d\n", 123);

Uwaga:: Użycie funkcji printf wymaga (jednorazowego) zużycia około 1kB - 3kB pamięci programu.

Implementacja funkcji printf występuje w trzech wersjach, różniących się możliwościami oraz rozmiarem. Domyślnie jest kompilowana wersja posiadająca wszystkie możliwości poza konwersją liczb zmiennoprzecinkowych (ok. 1.5kB). Aby dołączyć wersję zminimalizowaną (ok 1kB), należy do parametrów kompilatora dodać:

-Wl,-u,vfprintf -lprintf_min

Aby uzyskać wersję pełną (z możliwością przetwarzania liczb zmiennoprzecinkowych - 3kB) należy użyć parametrów:

-Wl,-u,vfprintf -lprintf_flt -lm

Parametry:

stream_name

Nazwa strumienia, który ma być związany

Dokumentacja funkcji

void hd44780_init ( )

Przygotowuje wyświetlacz do pracy. Należy jednorazowo wywołać tą funkcję przed rozpoczęciem korzystania z biblioteki.

void hd44780_clear ( )

Czyści zawartość wyświetlacza i ustawia kursor na początku pierwszego wiersza.

void hd44780_goto	(	uint8_t	x,
		uint8_t	y
	)

Przenosi kursor do podanej pozycji na wyświetlaczu.

Parametry:

	x	Żądana kolumna
	y	Żądany wiersz

void hd44780_putChar ( uint8_t c )

Wyświetla znak i przesuwa kursor do następnej pozycji. Jeżeli zdefiniowano HD44780_CODEPAGE inny niż HD44780_CODEPAGE_ASCII, litery z wybranej strony kodowej będą tłumaczone na identyfikatory znaków z wybranego (za pomocą HD44780_CHARSET) zestawu.

Uwaga:: W przypadku kodowania Unicode, wysłanie znaku odbywa się poprzez dwukrotne wywołanie funkcji. W związku z tym, przy rozwiązaniach wielowątkowych, należy zwrócić uwagę, aby funkcja w danej chwili była wywoływana tylko z jednego wątku.

Parametry:

c

Znak do wyświetlenia

void hd44780_putStr	(	char *	str,
		uint8_t	length
	)

Wyświetla ciąg length znaków z pamięci RAM. Jeżeli koniec ciągu (oznaczony znakiem NULL) wystąpi przed osiągnięciem podanej liczby znaków, wypisywanie zostanie przerwane.

Nota:: Aby długość ciągu była ustalana automatycznie (na podstawie znaku NULL), jako length podaj -1. Ta wartość zostanie rzutowana na 255, które jest maksymalną możliwą długością ciągu do wyświetlenia.

Parametry:

	str	Wskaźnik na pierwszy znak
	length	Długość ciągu (-1, jeżeli automatyczna)

void hd44780_putPStr	(	const char *	pstr,
		uint8_t	length
	)

Wyświetla ciąg znaków z pamięci programu.

Przykład użycia:

 const char *p = PSTR("tekst");
 hd44780_putPStr(p, -1);

Parametry:

	pstr	Wskaźnik na pierwszy znak (w pamięci programu)
	length	Długość ciągu (-1, jeżeli automatyczna)

Zobacz również:: hd44780_putStr()
HD44780_PUTPSTR()

void hd44780_putInt	(	int	val,
		uint8_t	radix,
		uint8_t	lpad
	)

Wyświetla wartość w określonym systemie liczbowym. Opcjonalnie wyrównuje cyfry do prawej.

Parametry:

	val	Wartość do wyświetlenia
	radix	System liczbowy (np. 10)
	lpad	Szerokość bloku wyrównanego do prawej (bez wyrównania - 0)

void hd44780_loadChar	(	uint8_t	addr,
		const uint8_t	data[8]
	)

Wczytuje z pamięci programu do pamięci wyświetlacza definicję znaku użytkownika. Kontroler HD44780 pozwala na zdefiniowanie ośmiu znaków.

Nota:: Funkcja powoduje zapisanie danych do pamięci CGRAM (i nadpisanie poprzedniej wartości). W związku z tym, jeżeli w chwili wywołania funkcji na wyświetlaczu był zapisywany znak, zostanie on zaktualizowany.

Parametry:

	addr	Identyfikator, pod którym będzie dostępny znak (0 - 7)
	data	Tablica ośmiu bajtów (w pamięci programu) z definicją znaku

Zobacz również:: hd44780_loadCharSet()

void hd44780_loadCharSet ( const uint8_t data[64] )

Wczytuje z pamięci programu do pamięci wyświetlacza definicję strony kodowej użytkownika. Odpowiada użyciu funkcji hd44780_loadChar() dla wszystkich znaków użytkownika.

Parametry:

data

Tablica 64 bajtów (w pamięci programu) z definicją strony kodowej

Zobacz również:: hd44780_charset_pl
hd44780_loadChar()


Definicje
#define	HD44780_PUTSTR(str) hd44780_putStr(str, -1)
#define	HD44780_PUTPSTR(str) hd44780_putPStr(PSTR(str), sizeof(str) - 1)
#define	HD44780_PUTINT(val) hd44780_putInt(val, 10, 0)
#define	HD44780_BIND_STREAM(stream_name)
Funkcje
void	hd44780_init ()
void	hd44780_clear ()
void	hd44780_goto (uint8_t x, uint8_t y)
void	hd44780_putChar (uint8_t c)
void	hd44780_putStr (char *str, uint8_t length)
void	hd44780_putPStr (const char *pstr, uint8_t length)
void	hd44780_putInt (int val, uint8_t radix, uint8_t lpad)
void	hd44780_loadChar (uint8_t addr, const uint8_t data[8])
void	hd44780_loadCharSet (const uint8_t data[64])