docs/feature_oled_driver.md

   1 # OLED Driver
   2
   3 ## OLED Supported Hardware
   4
   5 128x32 OLED modules using SSD1306 driver IC over I2C. Supported on AVR based keyboards. Possible but untested hardware includes ARM based keyboards and other sized OLED modules using SSD1306 over I2C, such as 128x64.
   6
   7 !> Warning: This OLED Driver currently uses the new i2c_master driver from split common code. If your split keyboard uses i2c to communication between sides this driver could cause an address conflict (serial is fine). Please contact your keyboard vendor and ask them to migrate to the latest split common code to fix this.
   8
   9 ## Usage
  10
  11 To enable the OLED feature, there are three steps. First, when compiling your keyboard, you'll need to set `OLED_DRIVER_ENABLE=yes` in `rules.mk`, e.g.:
  12
  13 ```
  14 BOOTMAGIC_ENABLE = no
  15 MOUSEKEY_ENABLE = no
  16 STENO_ENABLE = no
  17 EXTRAKEY_ENABLE = yes
  18 OLED_DRIVER_ENABLE = yes
  19 ```
  20
  21 This enables the feature and the `OLED_DRIVER_ENABLE` define. Then in your `keymap.c` file, you will need to implement the user task call, e.g:
  22
  23 ```C++
  24 #ifdef OLED_DRIVER_ENABLE
  25 void oled_task_user(void) {
  26   // Host Keyboard Layer Status
  27   oled_write_P(PSTR("Layer: "), false);
  28   switch (biton32(layer_state)) {
  29     case _QWERTY:
  30       oled_write_P(PSTR("Default\n"), false);
  31       break;
  32     case _FN:
  33       oled_write_P(PSTR("FN\n"), false);
  34       break;
  35     case _ADJ:
  36       oled_write_P(PSTR("ADJ\n"), false);
  37       break;
  38     default:
  39       // Or use the write_ln shortcut
  40       oled_write_P(PSTR("Undefined\n"), false);
  41   }
  42
  43   // Host Keyboard LED Status
  44   uint8_t led_usb_state = host_keyboard_leds();
  45   oled_write_P(led_usb_state & (1<<USB_LED_NUM_LOCK) ? PSTR("NUMLCK ") : PSTR("       "), false);
  46   oled_write_P(led_usb_state & (1<<USB_LED_CAPS_LOCK) ? PSTR("CAPLCK ") : PSTR("       "), false);
  47   oled_write_P(led_usb_state & (1<<USB_LED_SCROLL_LOCK) ? PSTR("SCRLCK ") : PSTR("       "), false);
  48 }
  49 #endif
  50 ```
  51
  52
  53 ## Other Examples
  54
  55 In split keyboards, it is very common to have two OLED displays that each render different content and oriented flipped differently. You can do this by switching which content to render by using the return from `is_keyboard_master()` or `is_keyboard_left()` found in `split_util.h`, e.g:
  56
  57 ```C++
  58 #ifdef OLED_DRIVER_ENABLE
  59 oled_rotation_t oled_init_user(oled_rotation_t rotation) {
  60   if (!is_keyboard_master())
  61     return OLED_ROTATION_180;  // flips the display 180 degrees if offhand
  62   return rotation;
  63 }
  64
  65 void oled_task_user(void) {
  66   if (is_keyboard_master()) {
  67     render_status();     // Renders the current keyboard state (layer, lock, caps, scroll, etc)
  68   } else {
  69     render_logo();       // Renders a statuc logo
  70     oled_scroll_left();  // Turns on scrolling
  71   }
  72 }
  73 #endif
  74 ```
  75
  76
  77  ## Basic Configuration
  78
  79 |Define                 |Default        |Description                                     |
  80 |-----------------------|---------------|------------------------------------------------|
  81 |`OLED_DISPLAY_ADDRESS` |`0x3C`         |The i2c address of the OLED Display             |
  82 |`OLED_FONT_H`          |`"glcdfont.c"` |The font code file to use for custom fonts      |
  83 |`OLED_FONT_START`      |`0`            |The starting characer index for custom fonts    |
  84 |`OLED_FONT_END`        |`224`          |The ending characer index for custom fonts      |
  85 |`OLED_FONT_WIDTH`      |`6`            |The font width                                  |
  86 |`OLED_FONT_HEIGHT`     |`8`            |The font height (untested)                      |
  87 |`OLED_DISABLE_TIMEOUT` |*Not defined*  |Disables the built in OLED timeout feature. Useful when implementing custom timeout rules.|
  88
  89
  90
  91  ## 128x64 & Custom sized OLED Displays
  92
  93  The default display size for this feature is 128x32 and all necessary defines are precalculated with that in mind. We have added a define, `OLED_DISPLAY_128X64`, to switch all the values to be used in a 128x64 display, as well as added a custom define, `OLED_DISPLAY_CUSTOM`, that allows you to provide the necessary values to the driver.
  94
  95 |Define                 |Default        |Description                                                      |
  96 |-----------------------|---------------|-----------------------------------------------------------------|
  97 |`OLED_DISPLAY_128X64`  |*Not defined*  |Changes the display defines for use with 128x64 displays.        |
  98 |`OLED_DISPLAY_CUSTOM`  |*Not defined*  |Changes the display defines for use with custom displays.<br />Requires user to implement the below defines. |
  99 |`OLED_DISPLAY_WIDTH`   |`128`          |The width of the OLED display.                                   |
 100 |`OLED_DISPLAY_HEIGHT`  |`32`           |The height of the OLED display.                                  |
 101 |`OLED_MATRIX_SIZE`     |`512`          |The local buffer size to allocate.<br />`(OLED_DISPLAY_HEIGHT / 8 * OLED_DISPLAY_WIDTH)`|
 102 |`OLED_BLOCK_TYPE`      |`uint16_t`     |The unsigned integer type to use for dirty rendering.|
 103 |`OLED_BLOCK_COUNT`     |`16`           |The number of blocks the display is divided into for dirty rendering.<br />`(sizeof(OLED_BLOCK_TYPE) * 8)`|
 104 |`OLED_BLOCK_SIZE`      |`32`           |The size of each block for dirty rendering<br />`(OLED_MATRIX_SIZE / OLED_BLOCK_COUNT)`|
 105 |`OLED_SOURCE_MAP`      |`{ 0, ... N }` |Precalculated source array to use for mapping source buffer to target OLED memory in 90 degree rendering.         |
 106 |`OLED_TARGET_MAP`      |`{ 24, ... N }`|Precalculated target array to use for mapping source buffer to target OLED memory in 90 degree rendering.         |
 107
 108
 109 ### 90 Degree Rotation - Technical Mumbo Jumbo
 110
 111 ```C
 112 // OLED Rotation enum values are flags
 113 typedef enum {
 114     OLED_ROTATION_0   = 0,
 115     OLED_ROTATION_90  = 1,
 116     OLED_ROTATION_180 = 2,
 117     OLED_ROTATION_270 = 3, // OLED_ROTATION_90 | OLED_ROTATION_180
 118 } oled_rotation_t;
 119 ```
 120
 121  OLED displays driven by SSD1306 drivers only natively support in hard ware 0 degree and 180 degree rendering. This feature is done in software and not free. Using this feature will increase the time to calculate what data to send over i2c to the OLED. If you are strapped for cycles, this can cause keycodes to not register. In testing however, the rendering time on an `atmega32u4` board only went from 2ms to 5ms and keycodes not registering was only noticed once we hit 15ms.
 122
 123  90 Degree Rotated Rendering is achieved by using bitwise operations to rotate each 8 block of memory and uses two precalculated arrays to remap buffer memory to OLED memory. The memory map defines are precalculated for remap performance and are calculated based on the OLED Height, Width, and Block Size. For example, in the 128x32 implementation with a `uint8_t` block type, we have a 64 byte block size. This gives us eight 8 byte blocks that need to be rotated and rendered. The OLED renders horizontally two 8 byte blocks before moving down a page, e.g:
 124
 125 |   |   |   |   |   |   |
 126 |---|---|---|---|---|---|
 127 | 0 | 1 |   |   |   |   |
 128 | 2 | 3 |   |   |   |   |
 129 | 4 | 5 |   |   |   |   |
 130 | 6 | 7 |   |   |   |   |
 131
 132 However the local buffer is stored as if it was Height x Width display instead of Width x Height, e.g:
 133
 134 |   |   |   |   |   |   |
 135 |---|---|---|---|---|---|
 136 | 3 | 7 |   |   |   |   |
 137 | 2 | 6 |   |   |   |   |
 138 | 1 | 5 |   |   |   |   |
 139 | 0 | 4 |   |   |   |   |
 140
 141 So those precalculated arrays just index the memory offsets in the order in which each one iterates its data.
 142
 143 ## OLED API
 144
 145 ```C++
 146 // OLED Rotation enum values are flags
 147 typedef enum {
 148     OLED_ROTATION_0   = 0,
 149     OLED_ROTATION_90  = 1,
 150     OLED_ROTATION_180 = 2,
 151     OLED_ROTATION_270 = 3, // OLED_ROTATION_90 | OLED_ROTATION_180
 152 } oled_rotation_t;
 153
 154 // Initialize the OLED display, rotating the rendered output based on the define passed in.
 155 // Returns true if the OLED was initialized successfully
 156 bool oled_init(oled_rotation_t rotation);
 157
 158 // Called at the start of oled_init, weak function overridable by the user
 159 // rotation - the value passed into oled_init
 160 // Return new oled_rotation_t if you want to override default rotation
 161 oled_rotation_t oled_init_user(oled_rotation_t rotation);
 162
 163 // Clears the display buffer, resets cursor position to 0, and sets the buffer to dirty for rendering
 164 void oled_clear(void);
 165
 166 // Renders the dirty chunks of the buffer to OLED display
 167 void oled_render(void);
 168
 169 // Moves cursor to character position indicated by column and line, wraps if out of bounds
 170 // Max column denoted by 'oled_max_chars()' and max lines by 'oled_max_lines()' functions
 171 void oled_set_cursor(uint8_t col, uint8_t line);
 172
 173 // Advances the cursor to the next page, writing ' ' if true
 174 // Wraps to the begining when out of bounds
 175 void oled_advance_page(bool clearPageRemainder);
 176
 177 // Moves the cursor forward 1 character length
 178 // Advance page if there is not enough room for the next character
 179 // Wraps to the begining when out of bounds
 180 void oled_advance_char(void);
 181
 182 // Writes a single character to the buffer at current cursor position
 183 // Advances the cursor while writing, inverts the pixels if true
 184 // Main handler that writes character data to the display buffer
 185 void oled_write_char(const char data, bool invert);
 186
 187 // Writes a string to the buffer at current cursor position
 188 // Advances the cursor while writing, inverts the pixels if true
 189 void oled_write(const char *data, bool invert);
 190
 191 // Writes a string to the buffer at current cursor position
 192 // Advances the cursor while writing, inverts the pixels if true
 193 // Advances the cursor to the next page, wiring ' ' to the remainder of the current page
 194 void oled_write_ln(const char *data, bool invert);
 195
 196 // Writes a PROGMEM string to the buffer at current cursor position
 197 // Advances the cursor while writing, inverts the pixels if true
 198 // Remapped to call 'void oled_write(const char *data, bool invert);' on ARM
 199 void oled_write_P(const char *data, bool invert);
 200
 201 // Writes a PROGMEM string to the buffer at current cursor position
 202 // Advances the cursor while writing, inverts the pixels if true
 203 // Advances the cursor to the next page, wiring ' ' to the remainder of the current page
 204 // Remapped to call 'void oled_write_ln(const char *data, bool invert);' on ARM
 205 void oled_write_ln_P(const char *data, bool invert);
 206
 207 // Can be used to manually turn on the screen if it is off
 208 // Returns true if the screen was on or turns on
 209 bool oled_on(void);
 210
 211 // Can be used to manually turn off the screen if it is on
 212 // Returns true if the screen was off or turns off
 213 bool oled_off(void);
 214
 215 // Basically it's oled_render, but with timeout management and oled_task_user calling!
 216 void oled_task(void);
 217
 218 // Called at the start of oled_task, weak function overridable by the user
 219 void oled_task_user(void);
 220
 221 // Scrolls the entire display right
 222 // Returns true if the screen was scrolling or starts scrolling
 223 // NOTE: display contents cannot be changed while scrolling
 224 bool oled_scroll_right(void);
 225
 226 // Scrolls the entire display left
 227 // Returns true if the screen was scrolling or starts scrolling
 228 // NOTE: display contents cannot be changed while scrolling
 229 bool oled_scroll_left(void);
 230
 231 // Turns off display scrolling
 232 // Returns true if the screen was not scrolling or stops scrolling
 233 bool oled_scroll_off(void);
 234
 235 // Returns the maximum number of characters that will fit on a line
 236 uint8_t oled_max_chars(void);
 237
 238 // Returns the maximum number of lines that will fit on the OLED
 239 uint8_t oled_max_lines(void);
 240 ```
 241
 242 ## SSD1306.h driver conversion guide
 243
 244 |Old API                    |Recommended New API                |
 245 |---------------------------|-----------------------------------|
 246 |`struct CharacterMatrix`   |*removed - delete all references*  |
 247 |`iota_gfx_init`            |`oled_init`                        |
 248 |`iota_gfx_on`              |`oled_on`                          |
 249 |`iota_gfx_off`             |`oled_off`                         |
 250 |`iota_gfx_flush`           |`oled_render`                      |
 251 |`iota_gfx_write_char`      |`oled_write_char`                  |
 252 |`iota_gfx_write`           |`oled_write`                       |
 253 |`iota_gfx_write_P`         |`oled_write_P`                     |
 254 |`iota_gfx_clear_screen`    |`oled_clear`                       |
 255 |`matrix_clear`             |*removed - delete all references*  |
 256 |`matrix_write_char_inner`  |`oled_write_char`                  |
 257 |`matrix_write_char`        |`oled_write_char`                  |
 258 |`matrix_write`             |`oled_write`                       |
 259 |`matrix_write_ln`          |`oled_write_ln`                    |
 260 |`matrix_write_P`           |`oled_write_P`                     |
 261 |`matrix_write_ln_P`        |`oled_write_ln_P`                  |
 262 |`matrix_render`            |`oled_render`                      |
 263 |`iota_gfx_task`            |`oled_task`                        |
 264 |`iota_gfx_task_user`       |`oled_task_user`                   |