hd44780_lcd.c File Reference

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

#include <avr/io.h>
#include <util/delay.h>
#include "hd44780_lcd.h"
#include "pin_defines.h"

Go to the source code of this file.

Macros
#define	CLEAR_DISPLAY   0b00000001U
#define	CURSOR_HOME   0b00000010U
#define	ENTRY_MODE_SET   0b00000100U
#define	ON_OFF_CTRL   0b00001000U
#define	CURSOR_DISPLAY_SHIFT   0b00010000U
#define	FUNCTION_SET   0b00100000U
#define	DATA_LENGTH_BIT   4U
#define	DISPLAY_LINES_BIT   3U
#define	FONT_SIZE_BIT   2U
#define	MOVE_DIRECTION_BIT   1U
#define	DISPLAY_SHIFT_BIT   0U
#define	CURSOR_ENABLE_BIT   1U
#define	BLINK_ENABLE_BIT   0U
#define	ON_OFF_CTRL_BIT   2U
#define	RIGHT_LEFT_BIT   2U
#define	SHIFT_OR_CURSOR_BIT   3U
#define	BUSY_FLAG_BIT   7U
#define	DISPLAY_ON   true
#define	DISPLAY_OFF   false
#define	POWER_RAMP_DELAY_MS   100
#define	SHORT_INSTR_DELAY_MS   2
#define	LONG_INSTR_DELAY_MS   10
#define	SCROLL_DELAY_MS   400
#define	ENABLE_DELAY_US   2

Functions
void	lcd_command (uint8_t data)
void	lcd_char (char character)
void	pulse_enable (void)
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 blockign 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.

NOTE: Values used in bitwise operations MUST be of unsigned type.

This driver was written using the datasheet for the HITACHI HD44780U LCD driver chip, which can be found here:

See also

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

Definition in file hd44780_lcd.c.

Macro Definition Documentation

CLEAR_DISPLAY

#define CLEAR_DISPLAY   0b00000001U

Definition at line 64 of file hd44780_lcd.c.

CURSOR_HOME

#define CURSOR_HOME   0b00000010U

Definition at line 65 of file hd44780_lcd.c.

ENTRY_MODE_SET

#define ENTRY_MODE_SET   0b00000100U

Definition at line 66 of file hd44780_lcd.c.

ON_OFF_CTRL

#define ON_OFF_CTRL   0b00001000U

Definition at line 67 of file hd44780_lcd.c.

CURSOR_DISPLAY_SHIFT

#define CURSOR_DISPLAY_SHIFT   0b00010000U

Definition at line 68 of file hd44780_lcd.c.

FUNCTION_SET

#define FUNCTION_SET   0b00100000U

Definition at line 69 of file hd44780_lcd.c.

DATA_LENGTH_BIT

#define DATA_LENGTH_BIT   4U

Definition at line 72 of file hd44780_lcd.c.

DISPLAY_LINES_BIT

#define DISPLAY_LINES_BIT   3U

Definition at line 73 of file hd44780_lcd.c.

FONT_SIZE_BIT

#define FONT_SIZE_BIT   2U

Definition at line 74 of file hd44780_lcd.c.

MOVE_DIRECTION_BIT

#define MOVE_DIRECTION_BIT   1U

Definition at line 75 of file hd44780_lcd.c.

DISPLAY_SHIFT_BIT

#define DISPLAY_SHIFT_BIT   0U

Definition at line 76 of file hd44780_lcd.c.

CURSOR_ENABLE_BIT

#define CURSOR_ENABLE_BIT   1U

Definition at line 77 of file hd44780_lcd.c.

BLINK_ENABLE_BIT

#define BLINK_ENABLE_BIT   0U

Definition at line 78 of file hd44780_lcd.c.

ON_OFF_CTRL_BIT

#define ON_OFF_CTRL_BIT   2U

Definition at line 79 of file hd44780_lcd.c.

RIGHT_LEFT_BIT

#define RIGHT_LEFT_BIT   2U

Definition at line 80 of file hd44780_lcd.c.

SHIFT_OR_CURSOR_BIT

#define SHIFT_OR_CURSOR_BIT   3U

Definition at line 81 of file hd44780_lcd.c.

BUSY_FLAG_BIT

#define BUSY_FLAG_BIT   7U

Definition at line 82 of file hd44780_lcd.c.

DISPLAY_ON

#define DISPLAY_ON   true

Definition at line 85 of file hd44780_lcd.c.

DISPLAY_OFF

#define DISPLAY_OFF   false

Definition at line 86 of file hd44780_lcd.c.

POWER_RAMP_DELAY_MS

#define POWER_RAMP_DELAY_MS   100

Definition at line 89 of file hd44780_lcd.c.

SHORT_INSTR_DELAY_MS

#define SHORT_INSTR_DELAY_MS   2

Definition at line 90 of file hd44780_lcd.c.

LONG_INSTR_DELAY_MS

#define LONG_INSTR_DELAY_MS   10

Definition at line 91 of file hd44780_lcd.c.

SCROLL_DELAY_MS

#define SCROLL_DELAY_MS   400

Definition at line 92 of file hd44780_lcd.c.

ENABLE_DELAY_US

#define ENABLE_DELAY_US   2

Definition at line 93 of file hd44780_lcd.c.

Function Documentation

lcd_command()

void lcd_command

(

uint8_t

data

)

Definition at line 395 of file hd44780_lcd.c.

{
    LCD_CTRL_PORT &= ~(1U << LCD_RS);
 
    if (p_config_local->eight_bit_mode)
    {
        LCD_DATA_PORT = data;
        pulse_enable();
    }
    else
    {
        uint8_t byte = 0;
 
        LCD_DATA_PORT &= ~(data_length_bitmask); // Clear relevant bits in port
        byte = (data & 0b11110000); // Keep high 4 bits only
        byte = (byte >> (7U - LCD_D7)); // Shift nibble into place
        LCD_DATA_PORT |= byte; // Send first nibble to LCD
        pulse_enable();
        
        LCD_DATA_PORT &= ~(data_length_bitmask); // Clear relevant bits in port
        byte = (data & 0b00001111); // Keep low 4 bits only
        byte = (byte << (LCD_D7 - 3U)); // Shift nibble into place
        LCD_DATA_PORT |= byte; // Send second nibble to LCD
        pulse_enable();
    }
    _delay_ms(SHORT_INSTR_DELAY_MS);
}

lcd_char()

void lcd_char

(

char

character

)

Definition at line 427 of file hd44780_lcd.c.

{
    LCD_CTRL_PORT |= (1U << LCD_RS);
 
    if (p_config_local->eight_bit_mode)
    {
        LCD_DATA_PORT = character;
        pulse_enable();
    }
    else
    {
        uint8_t byte = 0;
 
        LCD_DATA_PORT &= ~(data_length_bitmask); // Clear relevant bits in port
        byte = (character & 0b11110000); // Keep high 4 bits only
        byte = (byte >> (7U - LCD_D7)); // Shift nibble into place
        LCD_DATA_PORT |= byte; // Send first nibble to LCD
        pulse_enable();
        
        LCD_DATA_PORT &= ~(data_length_bitmask); // Clear relevant bits in port
        byte = (character & 0b00001111); // Keep low 4 bits only
        byte = (byte << (LCD_D7 - 3U)); // Shift nibble into place
        LCD_DATA_PORT |= byte; // Send second nibble to LCD
        pulse_enable();
    }
    _delay_ms(SHORT_INSTR_DELAY_MS);
}

pulse_enable()

void pulse_enable

(

void

)

Definition at line 459 of file hd44780_lcd.c.

{
    LCD_CTRL_PORT |= (1U << LCD_EN);
    _delay_us(ENABLE_DELAY_US);
    LCD_CTRL_PORT &= ~(1U << LCD_EN);
    _delay_us(ENABLE_DELAY_US);
}

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 104 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 177 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 190 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 204 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 216 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 246 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 269 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 291 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 308 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 318 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 333 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 349 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 369 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);
        }
    }
}