Driver for the HD44780 based 16x2 liquid crystal display. More...

#include <stdbool.h>

Classes
struct	lcd_config_t
	Configuration struct, to be instantiated and values assigned before passing it's address into and calling lcd_init(). More...

Functions
void	init_lcd (lcd_config_t *p_config)
	Initialisation routine (run once at startup). More...

void	lcd_display_off (void)
	Turn display off (config settings are retained). More...

void	lcd_display_on (void)
	Turn display on. More...

void	lcd_print_string (const char *str)
	Prints a string of characters to the display. More...

void	lcd_print_integer (int16_t number)
	Prints an integer variable. More...

void	lcd_set_cursor (uint8_t column, uint8_t row)
	Sets cursor location using x and y coordinates. More...

void	lcd_fast_clear (void)
	Writes space characters to all 32 sections of display (or 16 if in 1 line mode). More...

void	lcd_reconfigure (void)
	Edits config settings on the display (lcd_config_t members must be changed first). More...

void	lcd_return_home (void)
	Sets DDRAM address 0 in address counter. More...

void	lcd_shift_cursor_left (uint8_t distance)
	Moves cursor left without changing DDRAM contents. More...

void	lcd_shift_cursor_right (uint8_t distance)
	Moves cursor right without changing DDRAM contents. More...

void	lcd_shift_display_left (uint8_t distance, bool delay)
	Shifts display left without changing DDRAM contents. More...

void	lcd_shift_display_right (uint8_t distance, bool delay)
	Shifts display right without changing DDRAM contents. More...

Detailed Description

Driver for the HD44780 based 16x2 liquid crystal display.

Copyright: Copyright © 2022 by Jason Duffy.

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Author: Jason Duffy

Date: 1st March 2022

This file provides the basic low-level functionality for the ubiquitous 16x2 display. Please note that it uses long blocking waits in the initialisation routine (100ms), and short blocking waits in other utility functions (2uS - 2mS). This was done to simplify the code as the busy flag read introduced pitfalls. This driver currently only allows for a single display to be used, but this might be improved on at a later date.

This driver was written using the datasheet for the HITACHI HD44780U LCD driver chip, which can be found at the link below.

See also: http://www.datasheet-pdf.com/PDF/HD44780U-Datasheet-Hitachi-1109874

Definition in file hd44780_lcd.h.

Function Documentation

◆ init_lcd()

void init_lcd ( lcd_config_t * p_config )

Initialisation routine (run once at startup).

This function is to be called immediately after powerup of the display module. Instantiate the lcd_config_t object first then pass it's address into init_lcd() before using any other lcd functions.

Parameters

p_config is a pointer to the lcd_config_t object.

Returns: Returns void.

Definition at line 105 of file hd44780_lcd.c.

{
    // copy address of config object pointer to a local pointer
    p_config_local = p_config;
 
    // Set data direction registers to output where applicable
    LCD_CTRL_DDR |= (1U << LCD_RS) | (1U << LCD_EN);
 
    // Test for bit mode and set appropriate bitmask
    if (p_config_local->eight_bit_mode)
    {
        data_length_bitmask = 0xff; // 0b11111111
    }
    else
    {
        data_length_bitmask |= (1U << LCD_D7) | (1U << LCD_D6);
        data_length_bitmask |= (1U << LCD_D5) | (1U << LCD_D4);
    }
 
    // Set relevant lcd data port direction to output
    LCD_DATA_DDR |= data_length_bitmask;
 
    // Delay to allow power ramp up in LCD controller
    _delay_ms(POWER_RAMP_DELAY_MS);
 
    // Begin initialising HD44780
    uint8_t byte = 0;
    byte |= FUNCTION_SET;
    byte |= (p_config_local->eight_bit_mode << DATA_LENGTH_BIT);
 
    for (uint8_t count = 0; count < 3; ++count)
    {
        lcd_command(byte);
        _delay_ms(LONG_INSTR_DELAY_MS);
    }
 
    byte = 0;
    byte |= FUNCTION_SET;
    byte |= (p_config_local->eight_bit_mode << DATA_LENGTH_BIT);
    byte |= (p_config_local->two_line_display << DISPLAY_LINES_BIT);
    byte |= (p_config_local->five_by_ten_font << FONT_SIZE_BIT);
    lcd_command(byte);
 
    byte = 0;
    byte |= ON_OFF_CTRL;
    byte |= (DISPLAY_OFF << ON_OFF_CTRL_BIT);
    byte |= (p_config_local->cursor_enable << CURSOR_ENABLE_BIT);
    byte |= (p_config_local->blink_enable << BLINK_ENABLE_BIT);
    lcd_command(byte);
 
    byte = 0;
    byte |= CLEAR_DISPLAY;
    lcd_command(byte);
 
    byte = 0;
    byte |= ENTRY_MODE_SET;
    byte |= (p_config_local->increment_counter << MOVE_DIRECTION_BIT);
    byte |= (p_config_local->display_shift << DISPLAY_SHIFT_BIT);
    lcd_command(byte);
 
    byte = 0;
    byte |= ON_OFF_CTRL;
    byte |= (DISPLAY_ON << ON_OFF_CTRL_BIT);
    byte |= (p_config_local->cursor_enable << CURSOR_ENABLE_BIT);
    byte |= (p_config_local->blink_enable << BLINK_ENABLE_BIT);
    lcd_command(byte);
    lcd_return_home();
}

◆ lcd_display_off()

void lcd_display_off ( void )

Turn display off (config settings are retained).

Side effect: cursor_enable and blink_enable variable states are written to the display during this command, so if they have been changed but lcd_reconfigure() was not called afterwards, this function will update those config bits on the display.

Returns: Returns void.

Definition at line 178 of file hd44780_lcd.c.

{
    uint8_t byte = 0;
    byte |= ON_OFF_CTRL; // Default is off
    byte |= (p_config_local->cursor_enable << CURSOR_ENABLE_BIT);
    byte |= (p_config_local->blink_enable << BLINK_ENABLE_BIT);
    lcd_command(byte);
}

◆ lcd_display_on()

void lcd_display_on ( void )

Turn display on.

Side effect: cursor_enable and blink_enable variable states are written to the display during this command, so if they have been changed but lcd_reconfigure() was not called afterwards, this function will update those config bits on the display.

Returns: Returns void.

Definition at line 191 of file hd44780_lcd.c.

{
    uint8_t byte = 0;
    byte |= ON_OFF_CTRL;
    byte |= (DISPLAY_ON << ON_OFF_CTRL_BIT);
    byte |= (p_config_local->cursor_enable << CURSOR_ENABLE_BIT);
    byte |= (p_config_local->blink_enable << BLINK_ENABLE_BIT);
    lcd_command(byte);
}

◆ lcd_print_string()

void lcd_print_string ( const char * str )

Prints a string of characters to the display.

This function takes a string literal (constant) as it's parameter. Be sure to enclose text passed in with "" quotation marks. eg: "Hello, World!".

Parameters

str	is a string literal.

Returns: Returns void.

Definition at line 205 of file hd44780_lcd.c.

{
    for (uint8_t index = 0; str[index] != 0; ++index)
    {
        lcd_char(str[index]);
    }
}

◆ lcd_print_integer()

void lcd_print_integer ( int16_t number )

Prints an integer variable.

This function prints a signed integer value to the display, values from -32768 to 32767 are acceptable.

Parameters

number is a signed, fixed width integer.

Returns: Returns void.

Definition at line 217 of file hd44780_lcd.c.

{
    if (number < 0)
    {
        lcd_char('-');
    }
 
    uint8_t count = 0;
    uint8_t digit = 0;
    char str[20];
 
    while (number > 0)
    {
        digit = number % 10;
        str[count] = (digit + '0');
        ++count;
        number /= 10;
    }
 
    while (count > 0)
    {
        lcd_char(str[count - 1]);
        --count;
    }
}

◆ lcd_set_cursor()

void lcd_set_cursor	(	uint8_t	column,
		uint8_t	row
	)

Sets cursor location using x and y coordinates.

Column is 0 for top row, 1 for bottom row (in 2 row mode). Row can be from 0 - 15, values outside of this range will be written to non visible spaces on the display.

Parameters

column	is the x coordinate.
row	is the y coordinate.

Returns: Returns void.

Definition at line 247 of file hd44780_lcd.c.

{
    uint8_t address = 0;
 
    if (row == 0)
    {
        address = column;
    }
 
    else if (row == 1)
    {
        address = (column + 64);
    }
 
    address |= 0x80U; // Write 1 to MSB
    lcd_command(address);
}

◆ lcd_fast_clear()

void lcd_fast_clear ( void )

Writes space characters to all 32 sections of display (or 16 if in 1 line mode).

This is much faster than the clear_display command, as that works by writing a space character to every single section of the display, even all the non-visible ones.

Returns: Returns void.

Definition at line 270 of file hd44780_lcd.c.

{
    lcd_set_cursor(0,0);
    for (uint8_t count = 0; count < 16; ++count)
    {
        lcd_char(' ');
    }
    
    if (p_config_local->two_line_display)
    {
        lcd_set_cursor(0,1);
        for (uint8_t count = 0; count < 16; ++count)
        {
            lcd_char(' ');
        }
    }
}

◆ lcd_reconfigure()

void lcd_reconfigure ( void )

Edits config settings on the display (lcd_config_t members must be changed first).

data_length, display_lines, and font_size cannot be changed after init_lcd() is called.

Returns: Returns void.

Definition at line 292 of file hd44780_lcd.c.

{
    uint8_t byte = 0;
    byte |= ENTRY_MODE_SET;
    byte |= (p_config_local->increment_counter << MOVE_DIRECTION_BIT);
    byte |= (p_config_local->display_shift << DISPLAY_SHIFT_BIT);
    lcd_command(byte);
 
    // Also resends cursor and blink settings
    lcd_display_on();
}

◆ lcd_return_home()

void lcd_return_home ( void )

Sets DDRAM address 0 in address counter.

Also returns display from being shifted to original position. DDRAM contents remain unchanged.

Returns: Returns void.

Definition at line 309 of file hd44780_lcd.c.

{
    lcd_command(CURSOR_HOME);
    _delay_ms(SHORT_INSTR_DELAY_MS);
}

◆ lcd_shift_cursor_left()

void lcd_shift_cursor_left ( uint8_t distance )

Moves cursor left without changing DDRAM contents.

Parameters

distance is used to specify how many spaces to move.

Returns: Returns void.

Definition at line 319 of file hd44780_lcd.c.

{
    uint8_t byte = 0;
    byte |= CURSOR_DISPLAY_SHIFT;
 
    for (uint8_t count = 0; count < distance; ++count)
    {
        lcd_command(byte);
    }
}

◆ lcd_shift_cursor_right()

void lcd_shift_cursor_right ( uint8_t distance )

Moves cursor right without changing DDRAM contents.

Parameters

distance is used to specify how many spaces to move.

Returns: Returns void.

Definition at line 334 of file hd44780_lcd.c.

{
    uint8_t byte = 0;
    byte |= CURSOR_DISPLAY_SHIFT;
    byte |= (1U << RIGHT_LEFT_BIT);
 
    for (uint8_t count = 0; count < distance; ++count)
    {
        lcd_command(byte);
    }
}

◆ lcd_shift_display_left()

void lcd_shift_display_left	(	uint8_t	distance,
		bool	delay
	)

Shifts display left without changing DDRAM contents.

Optional delay between shifts for scrolling effect.

Parameters

distance	is used to specify how many spaces to move.
delay	- pass in true for scrolling effect, false for no delay.

Returns: Returns void.

Definition at line 350 of file hd44780_lcd.c.

{
    uint8_t byte = 0U;
    byte |= CURSOR_DISPLAY_SHIFT;
    byte |= (1U << SHIFT_OR_CURSOR_BIT);
 
    for (uint8_t count = 0; count < distance; ++count)
    {
        lcd_command(byte);
        if (delay == true)
        {
            _delay_ms(SCROLL_DELAY_MS);
        }
    }
}

◆ lcd_shift_display_right()

void lcd_shift_display_right	(	uint8_t	distance,
		bool	delay
	)

Shifts display right without changing DDRAM contents.

Optional delay between shifts for scrolling effect.

Parameters

distance	is used to specify how many spaces to move.
delay	- pass in true for scrolling effect, false for no delay.

Returns: Returns void.

Definition at line 370 of file hd44780_lcd.c.

{
    uint8_t byte = 0;
    byte |= CURSOR_DISPLAY_SHIFT;
    byte |= (1U << SHIFT_OR_CURSOR_BIT);
    byte |= (1U << RIGHT_LEFT_BIT);
 
    for (uint8_t count = 0; count < distance; ++count)
    {
        lcd_command(byte);
        if (delay == true)
        {
            _delay_ms(SCROLL_DELAY_MS);
        }
    }
}

Classes

Functions

Detailed Description

Function Documentation

◆ init_lcd()

◆ lcd_display_off()

◆ lcd_display_on()

◆ lcd_print_string()

◆ lcd_print_integer()

◆ lcd_set_cursor()

◆ lcd_fast_clear()

◆ lcd_reconfigure()

◆ lcd_return_home()

◆ lcd_shift_cursor_left()

◆ lcd_shift_cursor_right()

◆ lcd_shift_display_left()

◆ lcd_shift_display_right()