logo

qmk_firmware

custom branch of QMK firmware git clone https://anongit.hacktivis.me/git/qmk_firmware.git

oled_driver.h (17052B)

    

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