hd44780.md (9021B)
1 # HD44780 LCD Driver {#hd44780-lcd-driver} 2 3 ## Supported Hardware {#supported-hardware} 4 5 LCD modules using [HD44780U](https://www.sparkfun.com/datasheets/LCD/HD44780.pdf) IC or equivalent, communicating in 4-bit mode. 6 7 |Module|Size |Notes | 8 |------|--------------|---------------------------------| 9 |1602A |16x2, 5x8 dots| | 10 |2004A |20x4, 5x8 dots|Untested, not currently supported| 11 12 To run these modules at 3.3V, an additional MAX660 voltage converter IC must be soldered on, along with two 10µF capacitors. See [this page](https://www.codrey.com/electronic-circuits/hack-your-16x2-lcd/) for more details. 13 14 ## Usage {#usage} 15 16 Add the following to your `rules.mk`: 17 18 ```make 19 HD44780_ENABLE = yes 20 ``` 21 22 ## Basic Configuration {#basic-configuration} 23 24 Add the following to your `config.h`: 25 26 |Define |Default |Description | 27 |-----------------------|--------------|-----------------------------------------------------------------------------------------------------| 28 |`HD44780_DATA_PINS` |*Not defined* |(Required) An array of four GPIO pins connected to the display's D4-D7 pins, eg. `{ B1, B3, B2, B6 }`| 29 |`HD44780_RS_PIN` |*Not defined* |(Required) The GPIO connected to the display's RS pin | 30 |`HD44780_RW_PIN` |*Not defined* |(Required) The GPIO connected to the display's RW pin | 31 |`HD44780_E_PIN` |*Not defined* |(Required) The GPIO connected to the display's E pin | 32 |`HD44780_DISPLAY_COLS` |`16` |The number of visible characters on a single line of the display | 33 |`HD44780_DISPLAY_LINES`|`2` |The number of visible lines on the display | 34 |`HD44780_WRAP_LINES` |*Not defined* |If defined, input characters will wrap to the next line | 35 36 ## Examples {#examples} 37 38 ### Hello World {#example-hello-world} 39 40 Add the following to your `keymap.c`: 41 42 ```c 43 void keyboard_post_init_user(void) { 44 hd44780_init(true, true); // Show blinking cursor 45 hd44780_puts_P(PSTR("Hello, world!\n")); 46 } 47 ``` 48 49 ### Custom Character Definition {#example-custom-character} 50 51 Up to eight custom characters can be defined. This data is stored in the Character Generator RAM (CGRAM), and is not persistent across power cycles. 52 53 This example defines the QMK Psi as the first custom character. The first 16 positions in the character set are reserved for the eight custom characters duplicated. 54 55 ``` 56 Byte | 16 8 4 2 1 57 1 | x x x ■ □ ■ □ ■ 58 2 | x x x ■ □ ■ □ ■ 59 3 | x x x ■ □ ■ □ ■ 60 4 | x x x □ ■ ■ ■ □ 61 5 | x x x □ □ ■ □ □ 62 6 | x x x □ □ ■ □ □ 63 7 | x x x □ □ ■ □ □ 64 8 | x x x □ □ □ □ □ 65 ``` 66 67 ```c 68 const uint8_t PROGMEM psi[8] = { 0x15, 0x15, 0x15, 0x0E, 0x04, 0x04, 0x04, 0x00 }; 69 70 void keyboard_post_init_user(void) { 71 hd44780_init(false, false); 72 hd44780_define_char_P(0, psi); 73 // Cursor is incremented while defining characters so must be reset 74 hd44780_home(); 75 // 0x08 to avoid null terminator 76 hd44780_puts_P(PSTR("\x08 QMK Firmware")); 77 } 78 ``` 79 80 ## API {#api} 81 82 ### `void hd44780_init(bool cursor, bool blink)` {#api-hd44780-init} 83 84 Initialize the display. 85 86 This function should be called only once, before any of the other functions can be called. 87 88 #### Arguments {#api-hd44780-init-arguments} 89 90 - `bool cursor` 91 Whether to show the cursor. 92 - `bool blink` 93 Whether to blink the cursor, if shown. 94 95 --- 96 97 ### `void hd44780_clear(void)` {#api-hd44780-clear} 98 99 Clear the display. 100 101 This function is called on init. 102 103 --- 104 105 ### `void hd44780_home(void)` {#api-hd44780-home} 106 107 Move the cursor to the home position. 108 109 This function is called on init. 110 111 --- 112 113 ### `void hd44780_on(bool cursor, bool blink)` {#api-hd44780-on} 114 115 Turn the display on, and/or set the cursor properties. 116 117 This function is called on init. 118 119 #### Arguments {#api-hd44780-on-arguments} 120 121 - `bool cursor` 122 Whether to show the cursor. 123 - `bool blink` 124 Whether to blink the cursor, if shown. 125 126 --- 127 128 ### `void hd44780_off(void)` {#api-hd44780-off} 129 130 Turn the display off. 131 132 --- 133 134 ### `void hd44780_set_cursor(uint8_t col, uint8_t line)` {#api-hd44780-set-cursor} 135 136 Move the cursor to the specified position on the display. 137 138 #### Arguments {#api-hd44780-set-cursor-arguments} 139 140 - `uint8_t col` 141 The column number to move to, from 0 to 15 on 16x2 displays. 142 - `bool line` 143 The line number to move to, either 0 or 1 on 16x2 displays. 144 145 --- 146 147 ### `void hd44780_putc(char c)` {#api-hd44780-putc} 148 149 Print a character to the display. The newline character `\n` will move the cursor to the start of the next line. 150 151 The exact character shown may depend on the ROM code of your particular display - refer to the datasheet for the full character set. 152 153 #### Arguments {#api-hd44780-putc-arguments} 154 155 - `char c` 156 The character to print. 157 158 --- 159 160 ### `void hd44780_puts(const char *s)` {#api-hd44780-puts} 161 162 Print a string of characters to the display. 163 164 #### Arguments {#api-hd44780-puts-arguments} 165 166 - `const char *s` 167 The string to print. 168 169 --- 170 171 ### `void hd44780_puts_P(const char *s)` {#api-hd44780-puts-p} 172 173 Print a string of characters from PROGMEM to the display. 174 175 On ARM devices, this function is simply an alias of `hd44780_puts()`. 176 177 #### Arguments {#api-hd44780-puts-p-arguments} 178 179 - `const char *s` 180 The PROGMEM string to print (ie. `PSTR("Hello")`). 181 182 --- 183 184 ### `void hd44780_define_char(uint8_t index, uint8_t *data)` {#api-hd44780-define-char} 185 186 Define a custom character. 187 188 #### Arguments {#api-hd44780-define-char-arguments} 189 190 - `uint8_t index` 191 The index of the custom character to define, from 0 to 7. 192 - `uint8_t *data` 193 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. 194 195 --- 196 197 ### `void hd44780_define_char_P(uint8_t index, const uint8_t *data)` {#api-hd44780-define-char-p} 198 199 Define a custom character from PROGMEM. 200 201 On ARM devices, this function is simply an alias of `hd44780_define_char()`. 202 203 #### Arguments {#api-hd44780-define-char-p-arguments} 204 205 - `uint8_t index` 206 The index of the custom character to define, from 0 to 7. 207 - `const uint8_t *data` 208 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. 209 210 --- 211 212 ### `bool hd44780_busy(void)` {#api-hd44780-busy} 213 214 Indicates whether the display is currently processing, and cannot accept instructions. 215 216 #### Return Value {#api-hd44780-busy-arguments} 217 218 `true` if the display is busy. 219 220 --- 221 222 ### `void hd44780_write(uint8_t data, bool isData)` {#api-hd44780-write} 223 224 Write a byte to the display. 225 226 #### Arguments {#api-hd44780-write-arguments} 227 228 - `uint8_t data` 229 The byte to send to the display. 230 - `bool isData` 231 Whether the byte is an instruction or character data. 232 233 --- 234 235 ### `uint8_t hd44780_read(bool isData)` {#api-hd44780-read} 236 237 Read a byte from the display. 238 239 #### Arguments {#api-hd44780-read-arguments} 240 241 - `bool isData` 242 Whether to read the current cursor position, or the character at the cursor. 243 244 #### Return Value {#api-hd44780-read-return} 245 246 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. 247 248 --- 249 250 ### `void hd44780_command(uint8_t command)` {#api-hd44780-command} 251 252 Send a command to the display. Refer to the datasheet and `hd44780.h` for the valid commands and defines. 253 254 This function waits for the display to clear the busy flag before sending the command. 255 256 #### Arguments {#api-hd44780-command-arguments} 257 258 - `uint8_t command` 259 The command to send. 260 261 --- 262 263 ### `void hd44780_data(uint8_t data)` {#api-hd44780-data} 264 265 Send a byte of data to the display. 266 267 This function waits for the display to clear the busy flag before sending the data. 268 269 #### Arguments {#api-hd44780-data-arguments} 270 271 - `uint8_t data` 272 The byte of data to send. 273 274 --- 275 276 ### `void hd44780_set_cgram_address(uint8_t address)` {#api-hd44780-set-cgram-address} 277 278 Set the CGRAM address. 279 280 This function is used when defining custom characters. 281 282 #### Arguments {#api-hd44780-set-cgram-address-arguments} 283 284 - `uint8_t address` 285 The CGRAM address to move to, from `0x00` to `0x3F`. 286 287 --- 288 289 ### `void hd44780_set_ddram_address(uint8_t address)` {#api-hd44780-set-ddram-address} 290 291 Set the DDRAM address. 292 293 This function is used when printing characters to the display, and setting the cursor. 294 295 #### Arguments {#api-hd44780-set-ddram-address-arguments} 296 297 - `uint8_t address` 298 The DDRAM address to move to, from `0x00` to `0x7F`.