oled_driver.h (16860B)
1 /* 2 Copyright 2019 Ryan Caltabiano <https://github.com/XScorpion2> 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 #pragma once 18 19 #include <stdint.h> 20 #include <stdbool.h> 21 22 // an enumeration of the chips this driver supports 23 #define OLED_IC_SSD1306 0 24 #define OLED_IC_SH1106 1 25 #define OLED_IC_SH1107 2 26 27 #if defined(OLED_DISPLAY_CUSTOM) 28 // Expected user to implement the necessary defines 29 #elif defined(OLED_DISPLAY_128X64) 30 // Double height 128x64 31 # ifndef OLED_DISPLAY_WIDTH 32 # define OLED_DISPLAY_WIDTH 128 33 # endif 34 # ifndef OLED_DISPLAY_HEIGHT 35 # define OLED_DISPLAY_HEIGHT 64 36 # endif 37 # ifndef OLED_MATRIX_SIZE 38 # define OLED_MATRIX_SIZE (OLED_DISPLAY_HEIGHT / 8 * OLED_DISPLAY_WIDTH) // 1024 (compile time mathed) 39 # endif 40 # ifndef OLED_BLOCK_TYPE 41 # define OLED_BLOCK_TYPE uint16_t 42 # endif 43 # ifndef OLED_BLOCK_COUNT 44 # define OLED_BLOCK_COUNT (sizeof(OLED_BLOCK_TYPE) * 8) // 32 (compile time mathed) 45 # endif 46 # ifndef OLED_BLOCK_SIZE 47 # define OLED_BLOCK_SIZE (OLED_MATRIX_SIZE / OLED_BLOCK_COUNT) // 32 (compile time mathed) 48 # endif 49 # ifndef OLED_COM_PINS 50 # define OLED_COM_PINS COM_PINS_ALT 51 # endif 52 53 // For 90 degree rotation, we map our internal matrix to oled matrix using fixed arrays 54 // The OLED writes to it's memory horizontally, starting top left, but our memory starts bottom left in this mode 55 # ifndef OLED_SOURCE_MAP 56 # define OLED_SOURCE_MAP {0, 8, 16, 24, 32, 40, 48, 56} 57 # endif 58 # ifndef OLED_TARGET_MAP 59 # define OLED_TARGET_MAP {56, 48, 40, 32, 24, 16, 8, 0} 60 # endif 61 // If OLED_BLOCK_TYPE is uint32_t, these tables would look like: 62 // #define OLED_SOURCE_MAP { 32, 40, 48, 56 } 63 // #define OLED_TARGET_MAP { 24, 16, 8, 0 } 64 // If OLED_BLOCK_TYPE is uint16_t, these tables would look like: 65 // #define OLED_SOURCE_MAP { 0, 8, 16, 24, 32, 40, 48, 56 } 66 // #define OLED_TARGET_MAP { 56, 48, 40, 32, 24, 16, 8, 0 } 67 // If OLED_BLOCK_TYPE is uint8_t, these tables would look like: 68 // #define OLED_SOURCE_MAP { 0, 8, 16, 24, 32, 40, 48, 56, 64, 72, 80, 88, 96, 104, 112, 120 } 69 // #define OLED_TARGET_MAP { 56, 120, 48, 112, 40, 104, 32, 96, 24, 88, 16, 80, 8, 72, 0, 64 } 70 71 #elif defined(OLED_DISPLAY_64X32) 72 # ifndef OLED_DISPLAY_WIDTH 73 # define OLED_DISPLAY_WIDTH 64 74 # endif 75 # ifndef OLED_DISPLAY_HEIGHT 76 # define OLED_DISPLAY_HEIGHT 32 77 # endif 78 # ifndef OLED_COLUMN_OFFSET 79 # define OLED_COLUMN_OFFSET 32 80 # endif 81 # ifndef OLED_MATRIX_SIZE 82 # define OLED_MATRIX_SIZE (OLED_DISPLAY_HEIGHT / 8 * OLED_DISPLAY_WIDTH) 83 # endif 84 # ifndef OLED_BLOCK_TYPE 85 # define OLED_BLOCK_TYPE uint8_t 86 # endif 87 # ifndef OLED_BLOCK_COUNT 88 # define OLED_BLOCK_COUNT (sizeof(OLED_BLOCK_TYPE) * 8) // 8 (compile time mathed) 89 # endif 90 # ifndef OLED_BLOCK_SIZE 91 # define OLED_BLOCK_SIZE (OLED_MATRIX_SIZE / OLED_BLOCK_COUNT) // 32 (compile time mathed) 92 # endif 93 # ifndef OLED_COM_PINS 94 # define OLED_COM_PINS COM_PINS_ALT 95 # endif 96 97 # ifndef OLED_SOURCE_MAP 98 # define OLED_SOURCE_MAP {0, 8, 16, 24} 99 # endif 100 # ifndef OLED_TARGET_MAP 101 # define OLED_TARGET_MAP {24, 16, 8, 0} 102 # endif 103 104 #elif defined(OLED_DISPLAY_64X48) 105 # ifndef OLED_DISPLAY_WIDTH 106 # define OLED_DISPLAY_WIDTH 64 107 # endif 108 # ifndef OLED_DISPLAY_HEIGHT 109 # define OLED_DISPLAY_HEIGHT 48 110 # endif 111 # ifndef OLED_COLUMN_OFFSET 112 # define OLED_COLUMN_OFFSET 32 113 # endif 114 # ifndef OLED_MATRIX_SIZE 115 # define OLED_MATRIX_SIZE (OLED_DISPLAY_HEIGHT / 8 * OLED_DISPLAY_WIDTH) 116 # endif 117 # ifndef OLED_BLOCK_TYPE 118 # define OLED_BLOCK_TYPE uint32_t 119 # endif 120 # ifndef OLED_BLOCK_COUNT 121 # define OLED_BLOCK_COUNT 24 122 # endif 123 # ifndef OLED_BLOCK_SIZE 124 # define OLED_BLOCK_SIZE (OLED_MATRIX_SIZE / OLED_BLOCK_COUNT) 125 # endif 126 # ifndef OLED_COM_PINS 127 # define OLED_COM_PINS COM_PINS_ALT 128 # endif 129 130 # ifndef OLED_SOURCE_MAP 131 # define OLED_SOURCE_MAP {0, 8} 132 # endif 133 # ifndef OLED_TARGET_MAP 134 # define OLED_TARGET_MAP {8, 0} 135 # endif 136 137 #elif defined(OLED_DISPLAY_64X128) 138 # ifndef OLED_DISPLAY_WIDTH 139 # define OLED_DISPLAY_WIDTH 64 140 # endif 141 # ifndef OLED_DISPLAY_HEIGHT 142 # define OLED_DISPLAY_HEIGHT 128 143 # endif 144 # ifndef OLED_IC 145 # define OLED_IC OLED_IC_SH1107 146 # endif 147 # ifndef OLED_COM_PIN_OFFSET 148 # define OLED_COM_PIN_OFFSET 32 149 # endif 150 # ifndef OLED_MATRIX_SIZE 151 # define OLED_MATRIX_SIZE (OLED_DISPLAY_HEIGHT / 8 * OLED_DISPLAY_WIDTH) 152 # endif 153 # ifndef OLED_BLOCK_TYPE 154 # define OLED_BLOCK_TYPE uint16_t 155 # endif 156 # ifndef OLED_BLOCK_COUNT 157 # define OLED_BLOCK_COUNT (sizeof(OLED_BLOCK_TYPE) * 8) 158 # endif 159 # ifndef OLED_BLOCK_SIZE 160 # define OLED_BLOCK_SIZE (OLED_MATRIX_SIZE / OLED_BLOCK_COUNT) 161 # endif 162 # ifndef OLED_COM_PINS 163 # define OLED_COM_PINS COM_PINS_ALT 164 # endif 165 166 # ifndef OLED_SOURCE_MAP 167 # define OLED_SOURCE_MAP {0, 8, 16, 24, 32, 40, 48, 56} 168 # endif 169 # ifndef OLED_TARGET_MAP 170 # define OLED_TARGET_MAP {56, 48, 40, 32, 24, 16, 8, 0} 171 # endif 172 173 #elif defined(OLED_DISPLAY_128X128) 174 // Quad height 128x128 175 # ifndef OLED_DISPLAY_WIDTH 176 # define OLED_DISPLAY_WIDTH 128 177 # endif 178 # ifndef OLED_DISPLAY_HEIGHT 179 # define OLED_DISPLAY_HEIGHT 128 180 # endif 181 # ifndef OLED_IC 182 # define OLED_IC OLED_IC_SH1107 183 # endif 184 # ifndef OLED_MATRIX_SIZE 185 # define OLED_MATRIX_SIZE (OLED_DISPLAY_HEIGHT / 8 * OLED_DISPLAY_WIDTH) // 2048 (compile time mathed) 186 # endif 187 # ifndef OLED_BLOCK_TYPE 188 # define OLED_BLOCK_TYPE uint32_t 189 # endif 190 # ifndef OLED_BLOCK_COUNT 191 # define OLED_BLOCK_COUNT (sizeof(OLED_BLOCK_TYPE) * 8) // 32 (compile time mathed) 192 # endif 193 # ifndef OLED_BLOCK_SIZE 194 # define OLED_BLOCK_SIZE (OLED_MATRIX_SIZE / OLED_BLOCK_COUNT) // 64 (compile time mathed) 195 # endif 196 # ifndef OLED_COM_PINS 197 # define OLED_COM_PINS COM_PINS_ALT 198 # endif 199 200 // For 90 degree rotation, we map our internal matrix to oled matrix using fixed arrays 201 // The OLED writes to it's memory horizontally, starting top left, but our memory starts bottom left in this mode 202 # ifndef OLED_SOURCE_MAP 203 # define OLED_SOURCE_MAP {0, 8, 16, 24, 32, 40, 48, 56} 204 # endif 205 # ifndef OLED_TARGET_MAP 206 # define OLED_TARGET_MAP {56, 48, 40, 32, 24, 16, 8, 0} 207 # endif 208 #else // defined(OLED_DISPLAY_128X64) 209 // Default 128x32 210 # ifndef OLED_DISPLAY_WIDTH 211 # define OLED_DISPLAY_WIDTH 128 212 # endif 213 # ifndef OLED_DISPLAY_HEIGHT 214 # define OLED_DISPLAY_HEIGHT 32 215 # endif 216 # ifndef OLED_MATRIX_SIZE 217 # define OLED_MATRIX_SIZE (OLED_DISPLAY_HEIGHT / 8 * OLED_DISPLAY_WIDTH) // 512 (compile time mathed) 218 # endif 219 # ifndef OLED_BLOCK_TYPE 220 # define OLED_BLOCK_TYPE uint16_t // Type to use for segmenting the oled display for smart rendering, use unsigned types only 221 # endif 222 # ifndef OLED_BLOCK_COUNT 223 # define OLED_BLOCK_COUNT (sizeof(OLED_BLOCK_TYPE) * 8) // 16 (compile time mathed) 224 # endif 225 # ifndef OLED_BLOCK_SIZE 226 # define OLED_BLOCK_SIZE (OLED_MATRIX_SIZE / OLED_BLOCK_COUNT) // 32 (compile time mathed) 227 # endif 228 # ifndef OLED_COM_PINS 229 # define OLED_COM_PINS COM_PINS_SEQ 230 # endif 231 232 // For 90 degree rotation, we map our internal matrix to oled matrix using fixed arrays 233 // The OLED writes to it's memory horizontally, starting top left, but our memory starts bottom left in this mode 234 # ifndef OLED_SOURCE_MAP 235 # define OLED_SOURCE_MAP {0, 8, 16, 24} 236 # endif 237 # ifndef OLED_TARGET_MAP 238 # define OLED_TARGET_MAP {24, 16, 8, 0} 239 # endif 240 // If OLED_BLOCK_TYPE is uint8_t, these tables would look like: 241 // #define OLED_SOURCE_MAP { 0, 8, 16, 24, 32, 40, 48, 56 } 242 // #define OLED_TARGET_MAP { 48, 32, 16, 0, 56, 40, 24, 8 } 243 #endif // defined(OLED_DISPLAY_CUSTOM) 244 245 #if !defined(OLED_IC) 246 # define OLED_IC OLED_IC_SSD1306 247 #endif 248 249 // the column address corresponding to the first column in the display hardware 250 #if !defined(OLED_COLUMN_OFFSET) 251 # define OLED_COLUMN_OFFSET 0 252 #endif 253 254 // Address to use for the i2c oled communication 255 #if !defined(OLED_DISPLAY_ADDRESS) 256 # define OLED_DISPLAY_ADDRESS 0x3C 257 #endif 258 259 // Custom font file to use 260 #if !defined(OLED_FONT_H) 261 # define OLED_FONT_H "glcdfont.c" 262 #endif 263 // unsigned char value of the first character in the font file 264 #if !defined(OLED_FONT_START) 265 # define OLED_FONT_START 0 266 #endif 267 // unsigned char value of the last character in the font file 268 #if !defined(OLED_FONT_END) 269 # define OLED_FONT_END 223 270 #endif 271 // Font render width 272 #if !defined(OLED_FONT_WIDTH) 273 # define OLED_FONT_WIDTH 6 274 #endif 275 // Font render height 276 #if !defined(OLED_FONT_HEIGHT) 277 # define OLED_FONT_HEIGHT 8 278 #endif 279 // Default brightness level 280 #if !defined(OLED_BRIGHTNESS) 281 # define OLED_BRIGHTNESS 255 282 #endif 283 284 #if !defined(OLED_TIMEOUT) 285 # if defined(OLED_DISABLE_TIMEOUT) 286 # define OLED_TIMEOUT 0 287 # else 288 # define OLED_TIMEOUT 60000 289 # endif 290 #endif 291 292 #if !defined(OLED_FADE_OUT_INTERVAL) 293 # define OLED_FADE_OUT_INTERVAL 0x00 294 #endif 295 296 #if OLED_FADE_OUT_INTERVAL > 0x0F || OLED_FADE_OUT_INTERVAL < 0x00 297 # error OLED_FADE_OUT_INTERVAL must be between 0x00 and 0x0F 298 #endif 299 300 #if !defined(OLED_I2C_TIMEOUT) 301 # define OLED_I2C_TIMEOUT 100 302 #endif 303 304 #if !defined(OLED_UPDATE_INTERVAL) && defined(SPLIT_KEYBOARD) 305 # define OLED_UPDATE_INTERVAL 50 306 #endif 307 308 #if !defined(OLED_UPDATE_PROCESS_LIMIT) 309 # define OLED_UPDATE_PROCESS_LIMIT 1 310 #endif 311 312 typedef struct __attribute__((__packed__)) { 313 uint8_t *current_element; 314 uint16_t remaining_element_count; 315 } oled_buffer_reader_t; 316 317 // OLED Rotation enum values are flags 318 typedef enum { 319 OLED_ROTATION_0 = 0, 320 OLED_ROTATION_90 = 1, 321 OLED_ROTATION_180 = 2, 322 OLED_ROTATION_270 = 3, // OLED_ROTATION_90 | OLED_ROTATION_180 323 } oled_rotation_t; 324 325 // Initialize the oled display, rotating the rendered output based on the define passed in. 326 // Returns true if the OLED was initialized successfully 327 bool oled_init(oled_rotation_t rotation); 328 329 // Send commands and data to screen 330 bool oled_send_cmd(const uint8_t *data, uint16_t size); 331 bool oled_send_cmd_P(const uint8_t *data, uint16_t size); 332 bool oled_send_data(const uint8_t *data, uint16_t size); 333 void oled_driver_init(void); 334 335 // Called at the start of oled_init, weak function overridable by the user 336 // rotation - the value passed into oled_init 337 // Return new oled_rotation_t if you want to override default rotation 338 oled_rotation_t oled_init_kb(oled_rotation_t rotation); 339 oled_rotation_t oled_init_user(oled_rotation_t rotation); 340 341 // Clears the display buffer, resets cursor position to 0, and sets the buffer to dirty for rendering 342 void oled_clear(void); 343 344 // Alias to oled_render_dirty to avoid a change in api. 345 #define oled_render() oled_render_dirty(false) 346 347 // Renders all dirty blocks to the display at one time or a subset depending on the value of 348 // all. 349 void oled_render_dirty(bool all); 350 351 // Moves cursor to character position indicated by column and line, wraps if out of bounds 352 // Max column denoted by 'oled_max_chars()' and max lines by 'oled_max_lines()' functions 353 void oled_set_cursor(uint8_t col, uint8_t line); 354 355 // Advances the cursor to the next page, writing ' ' if true 356 // Wraps to the beginning when out of bounds 357 void oled_advance_page(bool clearPageRemainder); 358 359 // Moves the cursor forward 1 character length 360 // Advance page if there is not enough room for the next character 361 // Wraps to the beginning when out of bounds 362 void oled_advance_char(void); 363 364 // Writes a single character to the buffer at current cursor position 365 // Advances the cursor while writing, inverts the pixels if true 366 // Main handler that writes character data to the display buffer 367 void oled_write_char(const char data, bool invert); 368 369 // Writes a string to the buffer at current cursor position 370 // Advances the cursor while writing, inverts the pixels if true 371 void oled_write(const char *data, bool invert); 372 373 // Writes a string to the buffer at current cursor position 374 // Advances the cursor while writing, inverts the pixels if true 375 // Advances the cursor to the next page, wiring ' ' to the remainder of the current page 376 void oled_write_ln(const char *data, bool invert); 377 378 // Pans the buffer to the right (or left by passing true) by moving contents of the buffer 379 // Useful for moving the screen in preparation for new drawing 380 void oled_pan(bool left); 381 382 // Returns a pointer to the requested start index in the buffer plus remaining 383 // buffer length as struct 384 oled_buffer_reader_t oled_read_raw(uint16_t start_index); 385 386 // Writes a string to the buffer at current cursor position 387 void oled_write_raw(const char *data, uint16_t size); 388 389 // Writes a single byte into the buffer at the specified index 390 void oled_write_raw_byte(const char data, uint16_t index); 391 392 // Sets a specific pixel on or off 393 // Coordinates start at top-left and go right and down for positive x and y 394 void oled_write_pixel(uint8_t x, uint8_t y, bool on); 395 396 #if defined(__AVR__) 397 // Writes a PROGMEM string to the buffer at current cursor position 398 // Advances the cursor while writing, inverts the pixels if true 399 // Remapped to call 'void oled_write(const char *data, bool invert);' on ARM 400 void oled_write_P(const char *data, bool invert); 401 402 // Writes a PROGMEM string to the buffer at current cursor position 403 // Advances the cursor while writing, inverts the pixels if true 404 // Advances the cursor to the next page, wiring ' ' to the remainder of the current page 405 // Remapped to call 'void oled_write_ln(const char *data, bool invert);' on ARM 406 void oled_write_ln_P(const char *data, bool invert); 407 408 // Writes a PROGMEM string to the buffer at current cursor position 409 void oled_write_raw_P(const char *data, uint16_t size); 410 #else 411 # define oled_write_P(data, invert) oled_write(data, invert) 412 # define oled_write_ln_P(data, invert) oled_write_ln(data, invert) 413 # define oled_write_raw_P(data, size) oled_write_raw(data, size) 414 #endif // defined(__AVR__) 415 416 // Can be used to manually turn on the screen if it is off 417 // Returns true if the screen was on or turns on 418 bool oled_on(void); 419 420 // Can be used to manually turn off the screen if it is on 421 // Returns true if the screen was off or turns off 422 bool oled_off(void); 423 424 // Returns true if the oled is currently on, false if it is 425 // not 426 bool is_oled_on(void); 427 428 // Sets the brightness level of the display 429 uint8_t oled_set_brightness(uint8_t level); 430 431 // Gets the current brightness level of the display 432 uint8_t oled_get_brightness(void); 433 434 // Basically it's oled_render, but with timeout management and oled_task_user calling! 435 void oled_task(void); 436 437 // Called at the start of oled_task, weak function overridable by the user 438 bool oled_task_kb(void); 439 bool oled_task_user(void); 440 441 // Set the specific 8 lines rows of the screen to scroll. 442 // 0 is the default for start, and 7 for end, which is the entire 443 // height of the screen. For 128x32 screens, rows 4-7 are not used. 444 void oled_scroll_set_area(uint8_t start_line, uint8_t end_line); 445 446 // Sets scroll speed, 0-7, fastest to slowest. Default is three. 447 // Does not take effect until scrolling is either started or restarted 448 // the ssd1306 supports 8 speeds with the delay 449 // listed below between each frame of the scrolling effect 450 // 0=2, 1=3, 2=4, 3=5, 4=25, 5=64, 6=128, 7=256 451 void oled_scroll_set_speed(uint8_t speed); 452 453 // Begin scrolling the entire display right 454 // Returns true if the screen was scrolling or starts scrolling 455 // NOTE: display contents cannot be changed while scrolling 456 bool oled_scroll_right(void); 457 458 // Begin scrolling the entire display left 459 // Returns true if the screen was scrolling or starts scrolling 460 // NOTE: display contents cannot be changed while scrolling 461 bool oled_scroll_left(void); 462 463 // Turns off display scrolling 464 // Returns true if the screen was not scrolling or stops scrolling 465 bool oled_scroll_off(void); 466 467 // Returns true if the oled is currently scrolling, false if it is 468 // not 469 bool is_oled_scrolling(void); 470 471 // Inverts the display 472 // Returns true if the screen was or is inverted 473 bool oled_invert(bool invert); 474 475 // Returns the maximum number of characters that will fit on a line 476 uint8_t oled_max_chars(void); 477 478 // Returns the maximum number of lines that will fit on the oled 479 uint8_t oled_max_lines(void);