hd44780.h (6408B)
1 /* 2 Copyright 2022 3 4 This program is free software: you can redistribute it and/or modify 5 it under the terms of the GNU General Public License as published by 6 the Free Software Foundation, either version 2 of the License, or 7 (at your option) any later version. 8 9 This program is distributed in the hope that it will be useful, 10 but WITHOUT ANY WARRANTY; without even the implied warranty of 11 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 12 GNU General Public License for more details. 13 14 You should have received a copy of the GNU General Public License 15 along with this program. If not, see <http://www.gnu.org/licenses/>. 16 */ 17 18 #pragma once 19 20 #include <stdint.h> 21 #include <stdbool.h> 22 23 /** 24 * \file 25 * 26 * \defgroup hd44780 HD44780 Character LCD Driver 27 * \{ 28 */ 29 30 /* 31 * HD44780 instructions 32 * https://www.sparkfun.com/datasheets/LCD/HD44780.pdf 33 * Table 6 (p24) 34 */ 35 // Clear display 36 #define HD44780_CMD_CLEAR_DISPLAY 0x01 37 // Return home 38 #define HD44780_CMD_RETURN_HOME 0x02 39 // Entry mode set 40 #define HD44780_CMD_ENTRY_MODE 0x04 41 #define HD44780_ENTRY_MODE_INC 0x02 // I/D 42 #define HD44780_ENTRY_MODE_SHIFT 0x01 // S 43 // Display on/off control 44 #define HD44780_CMD_DISPLAY 0x08 45 #define HD44780_DISPLAY_ON 0x04 // D 46 #define HD44780_DISPLAY_CURSOR 0x02 // C 47 #define HD44780_DISPLAY_BLINK 0x01 // B 48 // Cursor or display shift 49 #define HD44780_CMD_MOVE 0x10 50 #define HD44780_MOVE_DISPLAY 0x08 // S/C 51 #define HD44780_MOVE_RIGHT 0x04 // R/L 52 // Function set 53 #define HD44780_CMD_FUNCTION 0x20 54 #define HD44780_FUNCTION_8_BIT 0x10 // DL 55 #define HD44780_FUNCTION_2_LINES 0x08 // N 56 #define HD44780_FUNCTION_5X10_DOTS 0x04 // F 57 // Set CGRAM address 58 #define HD44780_CMD_SET_CGRAM_ADDRESS 0x40 59 // Set DDRAM address 60 #define HD44780_CMD_SET_DDRAM_ADDRESS 0x80 61 62 // Bitmask for busy flag when reading 63 #define HD44780_BUSY_FLAG 0x80 64 65 /** 66 * \brief Write a byte to the display. 67 * 68 * \param data The byte to send to the display. 69 * \param isData Whether the byte is an instruction or character data. 70 */ 71 void hd44780_write(uint8_t data, bool isData); 72 73 /** 74 * \brief Read a byte from the display. 75 * 76 * \param isData Whether to read the current cursor position, or the character at the cursor. 77 * 78 * \return If `isData` is `true`, the returned byte will be the character at the current DDRAM address. Otherwise, it will be the current DDRAM address and the busy flag. 79 */ 80 uint8_t hd44780_read(bool isData); 81 82 /** 83 * \brief Indicates whether the display is currently processing, and cannot accept instructions. 84 * 85 * \return `true` if the display is busy. 86 */ 87 bool hd44780_busy(void); 88 89 /** 90 * \brief Send a command to the display. Refer to the datasheet for the valid commands. 91 * 92 * This function waits for the display to clear the busy flag before sending the command. 93 * 94 * \param command The command to send. 95 */ 96 void hd44780_command(uint8_t command); 97 98 /** 99 * \brief Send a byte of data to the display. 100 * 101 * This function waits for the display to clear the busy flag before sending the data. 102 * 103 * \param data The byte of data to send. 104 */ 105 void hd44780_data(uint8_t data); 106 107 /** 108 * \brief Clear the display. 109 * 110 * This function is called on init. 111 */ 112 void hd44780_clear(void); 113 114 /** 115 * \brief Move the cursor to the home position. 116 * 117 * This function is called on init. 118 */ 119 void hd44780_home(void); 120 121 /** 122 * \brief Turn the display on, and/or set the cursor position. 123 * 124 * This function is called on init. 125 * 126 * \param cursor Whether to show the cursor. 127 * \param blink Whether to blink the cursor, if shown. 128 */ 129 void hd44780_on(bool cursor, bool blink); 130 131 /** 132 * \brief Turn the display off. 133 */ 134 void hd44780_off(void); 135 136 /** 137 * \brief Set the CGRAM address. 138 * 139 * This function is used when defining custom characters. 140 * 141 * \param address The CGRAM address to move to, from `0x00` to `0x3F`. 142 */ 143 void hd44780_set_cgram_address(uint8_t address); 144 145 /** 146 * \brief Set the DDRAM address. 147 * 148 * This function is used when printing characters to the display, and setting the cursor. 149 * 150 * \param address The DDRAM address to move to, from `0x00` to `0x7F`. 151 */ 152 void hd44780_set_ddram_address(uint8_t address); 153 154 /** 155 * \brief Initialize the display. 156 * 157 * This function should be called only once, before any of the other functions can be called. 158 * 159 * \param cursor Whether to show the cursor. 160 * \param blink Whether to blink the cursor, if shown. 161 */ 162 void hd44780_init(bool cursor, bool blink); 163 164 /** 165 * \brief Move the cursor to the specified position on the display. 166 * 167 * \param col The column number to move to, from 0 to 15 on 16x2 displays. 168 * \param line The line number to move to, either 0 or 1 on 16x2 displays. 169 */ 170 void hd44780_set_cursor(uint8_t col, uint8_t line); 171 172 /** 173 * \brief Define a custom character. 174 * 175 * \param index The index of the custom character to define, from 0 to 7. 176 * \param data An array of 8 bytes containing the 5-bit row data of the character, where the first byte is the topmost row, and the least significant bit of each byte is the rightmost column. 177 */ 178 void hd44780_define_char(uint8_t index, uint8_t *data); 179 180 /** 181 * \brief Print a character to the display. The newline character will move the cursor to the start of the next line. 182 * 183 * The exact character shown may depend on the ROM code of your particular display - refer to the datasheet for the full character set. 184 * 185 * \param c The character to print. 186 */ 187 void hd44780_putc(char c); 188 189 /** 190 * \brief Print a string of characters to the display. 191 * 192 * \param s The string to print. 193 */ 194 void hd44780_puts(const char *s); 195 196 #if defined(__AVR__) || defined(__DOXYGEN__) 197 /** 198 * \brief Define a custom character from PROGMEM. 199 * 200 * On ARM devices, this function is simply an alias of hd44780_define_char(). 201 * 202 * \param index The index of the custom character to define, from 0 to 7. 203 * \param data A PROGMEM array of 8 bytes containing the 5-bit row data of the character, where the first byte is the topmost row, and the least significant bit of each byte is the rightmost column. 204 */ 205 void hd44780_define_char_P(uint8_t index, const uint8_t *data); 206 207 /** 208 * \brief Print a string of characters from PROGMEM to the display. 209 * 210 * On ARM devices, this function is simply an alias of hd44780_puts(). 211 * 212 * \param s The PROGMEM string to print. 213 */ 214 void hd44780_puts_P(const char *s); 215 #else 216 # define hd44780_define_char_P(index, data) hd44780_define_char(index, data) 217 # define hd44780_puts_P(s) hd44780_puts(s) 218 #endif 219 220 /** \} */