Library Functions

These functions are used for accessing the display. More...


Defines
#define	LCD_OFF 4
	Cursor Mode: Display completely off.
#define	LCD_ON_CURSOR_AND_BLINK 3
	Cursor Mode: Cursor and Blink (underline and blink the current character).
#define	LCD_ON_CURSOR_BLINK 2
	Cursor Mode: Blink the current character.
#define	LCD_ON_CURSOR_OFF 0
	Cursor Mode: No cursor.
#define	LCD_ON_CURSOR_ON 1
	Cursor Mode: Cursor on (underline the current character).
Functions
void	lcd_clear (void)
	Clear the LCD (takes 3ms to execute) and go back to the start position For two-controller displays: switch back to the first controller after this.
void	lcd_command (uint8_t data)
	Send a raw command and wait for the execution time (3ms for home and clear, 100µs for all other commands).
void	lcd_customchar (uint8_t number, uint8_t *data)
	Add a custom character.
void	lcd_customchar_P (uint8_t number, PGM_P data)
	Add a custom character from ROM This is like lcd_customchar(), but the character is stored in flash ROM and does not consume RAM space.
void	lcd_data (uint8_t data)
	Send data and wait 50µs.
void	lcd_home (void)
	Go to the start position (takes 3ms to execute) This also resets some shift-options that can be set by special LCD commands.
void	lcd_init (void)
	Initialise the LCD.
void	lcd_linewrap (void)
	(internal function) If the cursor has passed the end of a line, set the position to the beginning of the next line
void	lcd_nibble (uint8_t data)
	Write a half-byte in 4-bit-mode to the LCD.
void	lcd_print (char *str)
	Write a string after clearing the display.
void	lcd_putchar (char chr)
	Write a single char to the LCD at the current position.
void	lcd_putstr (char *str)
	Write a string starting at the current position.
void	lcd_putstr_P (PGM_P str)
	Write a string from ROM starting at the current position.
void	lcd_set_controller (uint8_t num)
	(internal function) Select the controller
void	lcd_set_cursor (uint8_t mode)
	Set the cursor mode, switches the LCD on or off.
void	lcd_set_line (uint8_t x)
	Go to the start of the specified line.
void	lcd_set_position (uint8_t position)
	Go to the specified position.
void	lcd_write (uint8_t data, uint8_t rs)
	Write data or commands to the LCD.
Variables
uint8_t	lcd_controller = 0
	global variable that stores the active controller (or 255 for all controllers).
uint8_t	lcd_cursor_mode = 0
	global variable that stores the last cursor mode
uint8_t	lcd_position = 0
	global variable that stores the current position.

Detailed Description

These functions are used for accessing the display.

Function Documentation

void lcd_customchar	(	uint8_t	number,
		uint8_t *	data
	)

Add a custom character.

This writes a custom character into character generator RAM. For displays with 5x8 pixel characters (the default), eight characters consisting of eight lines each can be stored. The eigth line is the cursor position which should be kept empty. Displays with 5x10 pixel characters can only store four characters consisting of eleven lines where the eleventh line is the cursor position.

Parameters:

	number	The number can be between 0 and 7 (or 0-3 for 5x10 char displays). The saved character can be accessed by this number: You can include your characters in a string like "hello\001". Due to technical limitations in C the character number zero can currently not really be used - 0x00 is the string terminating character so it cannot be included into strings. It can only be printed using lcd_putchar(0).
	data	The character is supplied as array of uint8_t. Each line is one byte, bit 4 is the leftmost pixel and bit 0 is the rightmost pixel. The top line is the first byte.

Example for 5x8 pixel character: This displays a black outlined box (the eight line is the cursor position).

uint8_t character_box[]= {
0b00011111,
0b00010001,
0b00010001,
0b00010001,
0b00010001,
0b00010001,
0b00011111,
0b00000000 }
lcd_customchar(1,character_box);
lcd_print("This is a box: \001");

Definition at line 479 of file lcd.c.

References lcd_command(), lcd_data(), lcd_home(), LCD_SET_CGRAM_ADDR, and LCD_SET_DDRAM_ADDR.

void lcd_customchar_P	(	uint8_t	number,
		PGM_P	data
	)

Add a custom character from ROM This is like lcd_customchar(), but the character is stored in flash ROM and does not consume RAM space.

Todo:: test this

Example:

// this needs to be global (out of any function, out of main):
const PROGMEM uint8_t character_box[]= {
0b00011111,
0b00010001,
0b00010001,
0b00010001,
0b00010001,
0b00010001,
0b00011111,
0b00000000 }

// in the function:
lcd_customchar_P(1,character_box);
lcd_print("This is a box: \001");

Definition at line 524 of file lcd.c.

References lcd_command(), lcd_data(), lcd_home(), LCD_SET_CGRAM_ADDR, and LCD_SET_DDRAM_ADDR.

void lcd_init ( void )

Initialise the LCD.

Call this function before using the LCD and 100ms after the supply voltage has become stable.

Todo:: automatisches Setzen von 2LINES austesten

Definition at line 181 of file lcd.c.

References LCD_EN(), LCD_FUNCTION, LCD_FUNCTION_2LINES, LCD_FUNCTION_4BIT, LCD_FUNCTION_5x10, LCD_FUNCTION_5x8, LCD_FUNCTION_8BIT, lcd_nibble(), lcd_position, LCD_RS(), and lcd_set_controller().

void lcd_linewrap ( void )

(internal function) If the cursor has passed the end of a line, set the position to the beginning of the next line

This internal function is used for automatic line wrapping. It is necessary because the memory addresses of a line are not always consecutive: A 2x8 character display has line 1 at address 0-7 and line 2 at address 40-47.

Definition at line 386 of file lcd.c.

References lcd_position, and lcd_set_position().

Referenced by lcd_putchar().

void lcd_print ( char * str )

Write a string after clearing the display.

This clears the display, and then writes a string starting at the home position.

Parameters:

str

The string to be displayed (zero-terminated array of char)

Definition at line 450 of file lcd.c.

References lcd_clear(), and lcd_putstr().

void lcd_putchar ( char chr )

Write a single char to the LCD at the current position.

This will print a single char and move to the next position (with automatic linewrapping). If the current character was the last character on the display, the cursor will remain at the end of the display.

Parameters:

chr

The character (even 0x00 is allowed and will be printed).

Definition at line 403 of file lcd.c.

References lcd_data(), lcd_linewrap(), lcd_position, and lcd_set_position().

Referenced by lcd_putstr(), and lcd_putstr_P().

void lcd_putstr ( char * str )

Write a string starting at the current position.

This will print a string with automatic linewrapping. If the string is longer than the display, it will be displayed in multiple parts without a delay inbetween.

Parameters:

str

The string to be displayed (zero-terminated array of char)

Definition at line 424 of file lcd.c.

References lcd_putchar().

Referenced by lcd_print().

void lcd_putstr_P ( PGM_P str )

Write a string from ROM starting at the current position.

This will print a string with automatic linewrapping. If the string is longer than the display, it will be displayed in multiple parts without a delay inbetween.

Parameters:

str

The string to be displayed (zero-terminated array of char in ROM)

Definition at line 437 of file lcd.c.

References lcd_putchar().

void lcd_set_controller ( uint8_t num ) [inline]

(internal function) Select the controller

Parameters:

num

The controller number (counted from zero) or LCD_ALL_CONTROLLERS.

Definition at line 267 of file lcd.c.

References lcd_controller.

Referenced by lcd_clear(), lcd_home(), lcd_init(), lcd_set_cursor(), and lcd_set_position().

void lcd_set_cursor ( uint8_t mode )

Set the cursor mode, switches the LCD on or off.

Parameters:

mode

LCD_CURSOR_OFF, LCD_CURSOR_ON, LCD_BLINK or LCD_CURSOR_AND_BLINK For two-controller LCDs: The cursor is only enabled for the current controller and disabled for the other controller. As soon as the cursor reaches the second display, the cursor is disabled on the first display and enabled on the second: When a controller change is done by lcd_set_position(), it calls lcd_set_cursor() again with the current mode, which is stored in the global variable lcd_cursor_mode. lcd_set_position is called automatically through lcd_linewrap() by lcd_putchar(), lcd_print() and lcd_putstr().

Todo:: test the new version of this function, especially two-controller cursor handling

Definition at line 351 of file lcd.c.

References lcd_command(), LCD_CONTROL, LCD_CONTROL_BLINK, LCD_CONTROL_CURSOR_OFF, LCD_CONTROL_CURSOR_ON, LCD_CONTROL_DISPLAY_OFF, LCD_CONTROL_DISPLAY_ON, lcd_controller, lcd_cursor_mode, LCD_OFF, LCD_ON_CURSOR_AND_BLINK, LCD_ON_CURSOR_BLINK, LCD_ON_CURSOR_OFF, LCD_ON_CURSOR_ON, and lcd_set_controller().

Referenced by lcd_home(), and lcd_set_position().

void lcd_set_position ( uint8_t position )

Go to the specified position.

The position is stored in the global variable lcd_position. The command LCD_SET_DDRAM_ADDR then sets the position in the LCD controller. This also affects the cursor.

Parameters:

position

The character number (Example: for a 4x20 character display the third line starts at 40)

Definition at line 292 of file lcd.c.

References lcd_command(), lcd_controller, lcd_cursor_mode, lcd_position, lcd_set_controller(), lcd_set_cursor(), and LCD_SET_DDRAM_ADDR.

Referenced by lcd_clear(), lcd_linewrap(), lcd_putchar(), and lcd_set_line().

void lcd_write	(	uint8_t	data,
		uint8_t	rs
	)

Write data or commands to the LCD.

Edit this function to add your own way of 8 interfacing the LCD in 8-bit-mode (e.g. by shift register). In 4-bit-mode this calls lcd_nibble() to send the half-bytes.

Definition at line 153 of file lcd.c.

References lcd_nibble(), and LCD_RS().

Referenced by lcd_command(), and lcd_data().