qmk

QMK Firmware
git clone git://git.z3bra.org/qmk.git
Log | Files | Refs | Submodules | LICENSE

feature_oled_driver.md (15639B)


      1 # OLED Driver
      2 
      3 ## OLED Supported Hardware
      4 
      5 OLED modules using SSD1306 or SH1106 driver ICs, communicating over I2C.
      6 Tested combinations:
      7 
      8 | IC driver |   Size | Keyboard Platform | Notes                    |
      9 |-----------|--------|-------------------|--------------------------|
     10 | SSD1306   | 128x32 | AVR               | Primary support          |
     11 | SSD1306   | 128x64 | AVR               | Verified working         |
     12 | SSD1306   | 128x32 | ARM               |                          |
     13 | SH1106    | 128x64 | AVR               | No rotation or scrolling |
     14 
     15 Hardware configurations using ARM-based microcontrollers or different sizes of OLED modules may be compatible, but are untested.
     16 
     17 !> Warning: This OLED Driver currently uses the new i2c_master driver from split common code. If your split keyboard uses I2C to communicate 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. In addition, the display timeout system to reduce OLED burn-in also uses split common to detect keypresses, so you will need to implement custom timeout logic for non-split common keyboards.
     18 
     19 ## Usage
     20 
     21 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.:
     22 
     23 ```
     24 OLED_DRIVER_ENABLE = yes
     25 ```
     26 
     27 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:
     28 
     29 ```C++
     30 #ifdef OLED_DRIVER_ENABLE
     31 void oled_task_user(void) {
     32   // Host Keyboard Layer Status
     33   oled_write_P(PSTR("Layer: "), false);
     34   switch (get_highest_layer(layer_state)) {
     35     case _QWERTY:
     36       oled_write_P(PSTR("Default\n"), false);
     37       break;
     38     case _FN:
     39       oled_write_P(PSTR("FN\n"), false);
     40       break;
     41     case _ADJ:
     42       oled_write_P(PSTR("ADJ\n"), false);
     43       break;
     44     default:
     45       // Or use the write_ln shortcut over adding '\n' to the end of your string
     46       oled_write_ln_P(PSTR("Undefined"), false);
     47   }
     48 
     49   // Host Keyboard LED Status
     50   uint8_t led_usb_state = host_keyboard_leds();
     51   oled_write_P(led_usb_state & (1<<USB_LED_NUM_LOCK) ? PSTR("NUMLCK ") : PSTR("       "), false);
     52   oled_write_P(led_usb_state & (1<<USB_LED_CAPS_LOCK) ? PSTR("CAPLCK ") : PSTR("       "), false);
     53   oled_write_P(led_usb_state & (1<<USB_LED_SCROLL_LOCK) ? PSTR("SCRLCK ") : PSTR("       "), false);
     54 }
     55 #endif
     56 ```
     57 
     58 ## Logo Example
     59 
     60 In the default font, ranges in the font file are reserved for a QMK Logo. To Render this logo to the oled screen, use the following code example:
     61 
     62 ```C++
     63 static void render_logo(void) {
     64   static const char PROGMEM qmk_logo[] = {
     65     0x80,0x81,0x82,0x83,0x84,0x85,0x86,0x87,0x88,0x89,0x8a,0x8b,0x8c,0x8d,0x8e,0x8f,0x90,0x91,0x92,0x93,0x94,
     66     0xa0,0xa1,0xa2,0xa3,0xa4,0xa5,0xa6,0xa7,0xa8,0xa9,0xaa,0xab,0xac,0xad,0xae,0xaf,0xb0,0xb1,0xb2,0xb3,0xb4,
     67     0xc0,0xc1,0xc2,0xc3,0xc4,0xc5,0xc6,0xc7,0xc8,0xc9,0xca,0xcb,0xcc,0xcd,0xce,0xcf,0xd0,0xd1,0xd2,0xd3,0xd4,0};
     68 
     69   oled_write_P(qmk_logo, false);
     70 }
     71 ```
     72 
     73 ## Other Examples
     74 
     75 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:
     76 
     77 ```C++
     78 #ifdef OLED_DRIVER_ENABLE
     79 oled_rotation_t oled_init_user(oled_rotation_t rotation) {
     80   if (!is_keyboard_master())
     81     return OLED_ROTATION_180;  // flips the display 180 degrees if offhand
     82   return rotation;
     83 }
     84 
     85 void oled_task_user(void) {
     86   if (is_keyboard_master()) {
     87     render_status();     // Renders the current keyboard state (layer, lock, caps, scroll, etc)
     88   } else {
     89     render_logo();       // Renders a statuc logo
     90     oled_scroll_left();  // Turns on scrolling
     91   }
     92 }
     93 #endif
     94 ```
     95 
     96 
     97  ## Basic Configuration
     98 
     99 | Define                     | Default           | Description                                                                                                                |
    100 |----------------------------|-------------------|----------------------------------------------------------------------------------------------------------------------------|
    101 | `OLED_DISPLAY_ADDRESS`     | `0x3C`            | The i2c address of the OLED Display                                                                                        |
    102 | `OLED_FONT_H`              | `"glcdfont.c"`    | The font code file to use for custom fonts                                                                                 |
    103 | `OLED_FONT_START`          | `0`               | The starting characer index for custom fonts                                                                               |
    104 | `OLED_FONT_END`            | `224`             | The ending characer index for custom fonts                                                                                 |
    105 | `OLED_FONT_WIDTH`          | `6`               | The font width                                                                                                             |
    106 | `OLED_FONT_HEIGHT`         | `8`               | The font height (untested)                                                                                                 |
    107 | `OLED_TIMEOUT`             | `60000`           | Turns off the OLED screen after 60000ms of keyboard inactivity. Helps reduce OLED Burn-in. Set to 0 to disable.            |
    108 | `OLED_SCROLL_TIMEOUT`      | `0`               | Scrolls the OLED screen after 0ms of OLED inactivity. Helps reduce OLED Burn-in. Set to 0 to disable.                      |
    109 | `OLED_SCROLL_TIMEOUT_RIGHT`| *Not defined*     | Scroll timeout direction is right when defined, left when undefined.                                                       |
    110 | `OLED_IC`                  | `OLED_IC_SSD1306` | Set to `OLED_IC_SH1106` if you're using the SH1106 OLED controller.                                                        |
    111 | `OLED_COLUMN_OFFSET`       | `0`               | (SH1106 only.) Shift output to the right this many pixels.<br />Useful for 128x64 displays centered on a 132x64 SH1106 IC. |
    112 
    113  ## 128x64 & Custom sized OLED Displays
    114 
    115  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.
    116 
    117 |Define                 |Default        |Description                                                      |
    118 |-----------------------|---------------|-----------------------------------------------------------------|
    119 |`OLED_DISPLAY_128X64`  |*Not defined*  |Changes the display defines for use with 128x64 displays.        |
    120 |`OLED_DISPLAY_CUSTOM`  |*Not defined*  |Changes the display defines for use with custom displays.<br />Requires user to implement the below defines. |
    121 |`OLED_DISPLAY_WIDTH`   |`128`          |The width of the OLED display.                                   |
    122 |`OLED_DISPLAY_HEIGHT`  |`32`           |The height of the OLED display.                                  |
    123 |`OLED_MATRIX_SIZE`     |`512`          |The local buffer size to allocate.<br />`(OLED_DISPLAY_HEIGHT / 8 * OLED_DISPLAY_WIDTH)`. |
    124 |`OLED_BLOCK_TYPE`      |`uint16_t`     |The unsigned integer type to use for dirty rendering. |
    125 |`OLED_BLOCK_COUNT`     |`16`           |The number of blocks the display is divided into for dirty rendering.<br />`(sizeof(OLED_BLOCK_TYPE) * 8)`. |
    126 |`OLED_BLOCK_SIZE`      |`32`           |The size of each block for dirty rendering<br />`(OLED_MATRIX_SIZE / OLED_BLOCK_COUNT)`. |
    127 |`OLED_COM_PINS`        |`COM_PINS_SEQ` |How the SSD1306 chip maps it's memory to display.<br />Options are `COM_PINS_SEQ`, `COM_PINS_ALT`, `COM_PINS_SEQ_LR`, & `COM_PINS_ALT_LR`. |
    128 |`OLED_SOURCE_MAP`      |`{ 0, ... N }` |Precalculated source array to use for mapping source buffer to target OLED memory in 90 degree rendering.         |
    129 |`OLED_TARGET_MAP`      |`{ 24, ... N }`|Precalculated target array to use for mapping source buffer to target OLED memory in 90 degree rendering.         |
    130 
    131 
    132 ### 90 Degree Rotation - Technical Mumbo Jumbo 
    133 
    134 !> Rotation is unsupported on the SH1106.
    135 
    136 ```C
    137 // OLED Rotation enum values are flags
    138 typedef enum {
    139     OLED_ROTATION_0   = 0,
    140     OLED_ROTATION_90  = 1,
    141     OLED_ROTATION_180 = 2,
    142     OLED_ROTATION_270 = 3, // OLED_ROTATION_90 | OLED_ROTATION_180
    143 } oled_rotation_t;
    144 ```
    145 
    146  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. 
    147  
    148  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:
    149 
    150 |   |   |   |   |   |   |
    151 |---|---|---|---|---|---|
    152 | 0 | 1 |   |   |   |   |
    153 | 2 | 3 |   |   |   |   |
    154 | 4 | 5 |   |   |   |   |
    155 | 6 | 7 |   |   |   |   |
    156 
    157 However the local buffer is stored as if it was Height x Width display instead of Width x Height, e.g:
    158 
    159 |   |   |   |   |   |   |
    160 |---|---|---|---|---|---|
    161 | 3 | 7 |   |   |   |   |
    162 | 2 | 6 |   |   |   |   |
    163 | 1 | 5 |   |   |   |   |
    164 | 0 | 4 |   |   |   |   |
    165 
    166 So those precalculated arrays just index the memory offsets in the order in which each one iterates its data.
    167 
    168 ## OLED API
    169 
    170 ```C++
    171 // OLED Rotation enum values are flags
    172 typedef enum {
    173     OLED_ROTATION_0   = 0,
    174     OLED_ROTATION_90  = 1,
    175     OLED_ROTATION_180 = 2,
    176     OLED_ROTATION_270 = 3, // OLED_ROTATION_90 | OLED_ROTATION_180
    177 } oled_rotation_t;
    178 
    179 // Initialize the OLED display, rotating the rendered output based on the define passed in.
    180 // Returns true if the OLED was initialized successfully
    181 bool oled_init(oled_rotation_t rotation);
    182 
    183 // Called at the start of oled_init, weak function overridable by the user
    184 // rotation - the value passed into oled_init
    185 // Return new oled_rotation_t if you want to override default rotation
    186 oled_rotation_t oled_init_user(oled_rotation_t rotation);
    187 
    188 // Clears the display buffer, resets cursor position to 0, and sets the buffer to dirty for rendering
    189 void oled_clear(void);
    190 
    191 // Renders the dirty chunks of the buffer to OLED display
    192 void oled_render(void);
    193 
    194 // Moves cursor to character position indicated by column and line, wraps if out of bounds
    195 // Max column denoted by 'oled_max_chars()' and max lines by 'oled_max_lines()' functions
    196 void oled_set_cursor(uint8_t col, uint8_t line);
    197 
    198 // Advances the cursor to the next page, writing ' ' if true
    199 // Wraps to the begining when out of bounds
    200 void oled_advance_page(bool clearPageRemainder);
    201 
    202 // Moves the cursor forward 1 character length
    203 // Advance page if there is not enough room for the next character
    204 // Wraps to the begining when out of bounds
    205 void oled_advance_char(void);
    206 
    207 // Writes a single character to the buffer at current cursor position
    208 // Advances the cursor while writing, inverts the pixels if true
    209 // Main handler that writes character data to the display buffer
    210 void oled_write_char(const char data, bool invert);
    211 
    212 // Writes a string to the buffer at current cursor position
    213 // Advances the cursor while writing, inverts the pixels if true
    214 void oled_write(const char *data, bool invert);
    215 
    216 // Writes a string to the buffer at current cursor position
    217 // Advances the cursor while writing, inverts the pixels if true
    218 // Advances the cursor to the next page, wiring ' ' to the remainder of the current page
    219 void oled_write_ln(const char *data, bool invert);
    220 
    221 // Writes a PROGMEM string to the buffer at current cursor position
    222 // Advances the cursor while writing, inverts the pixels if true
    223 // Remapped to call 'void oled_write(const char *data, bool invert);' on ARM
    224 void oled_write_P(const char *data, bool invert);
    225 
    226 // Writes a PROGMEM string to the buffer at current cursor position
    227 // Advances the cursor while writing, inverts the pixels if true
    228 // Advances the cursor to the next page, wiring ' ' to the remainder of the current page
    229 // Remapped to call 'void oled_write_ln(const char *data, bool invert);' on ARM
    230 void oled_write_ln_P(const char *data, bool invert);
    231 
    232 // Can be used to manually turn on the screen if it is off
    233 // Returns true if the screen was on or turns on
    234 bool oled_on(void);
    235 
    236 // Can be used to manually turn off the screen if it is on
    237 // Returns true if the screen was off or turns off
    238 bool oled_off(void);
    239 
    240 // Basically it's oled_render, but with timeout management and oled_task_user calling!
    241 void oled_task(void);
    242 
    243 // Called at the start of oled_task, weak function overridable by the user
    244 void oled_task_user(void);
    245 
    246 // Scrolls the entire display right
    247 // Returns true if the screen was scrolling or starts scrolling
    248 // NOTE: display contents cannot be changed while scrolling
    249 bool oled_scroll_right(void);
    250 
    251 // Scrolls the entire display left
    252 // Returns true if the screen was scrolling or starts scrolling
    253 // NOTE: display contents cannot be changed while scrolling
    254 bool oled_scroll_left(void);
    255 
    256 // Turns off display scrolling
    257 // Returns true if the screen was not scrolling or stops scrolling
    258 bool oled_scroll_off(void);
    259 
    260 // Returns the maximum number of characters that will fit on a line
    261 uint8_t oled_max_chars(void);
    262 
    263 // Returns the maximum number of lines that will fit on the OLED
    264 uint8_t oled_max_lines(void);
    265 ```
    266 
    267 !> Scrolling and rotation are unsupported on the SH1106.
    268 
    269 ## SSD1306.h driver conversion guide
    270 
    271 |Old API                    |Recommended New API                |
    272 |---------------------------|-----------------------------------|
    273 |`struct CharacterMatrix`   |*removed - delete all references*  |
    274 |`iota_gfx_init`            |`oled_init`                        |
    275 |`iota_gfx_on`              |`oled_on`                          |
    276 |`iota_gfx_off`             |`oled_off`                         |
    277 |`iota_gfx_flush`           |`oled_render`                      |
    278 |`iota_gfx_write_char`      |`oled_write_char`                  |
    279 |`iota_gfx_write`           |`oled_write`                       |
    280 |`iota_gfx_write_P`         |`oled_write_P`                     |
    281 |`iota_gfx_clear_screen`    |`oled_clear`                       |
    282 |`matrix_clear`             |*removed - delete all references*  |
    283 |`matrix_write_char_inner`  |`oled_write_char`                  |
    284 |`matrix_write_char`        |`oled_write_char`                  |
    285 |`matrix_write`             |`oled_write`                       |
    286 |`matrix_write_ln`          |`oled_write_ln`                    |
    287 |`matrix_write_P`           |`oled_write_P`                     |
    288 |`matrix_write_ln_P`        |`oled_write_ln_P`                  |
    289 |`matrix_render`            |`oled_render`                      |
    290 |`iota_gfx_task`            |`oled_task`                        |
    291 |`iota_gfx_task_user`       |`oled_task_user`                   |