How do I convert an image for use on an OLED display?

OLED displays can be put to use in various ways, like you can read in What can you use an OLED display for on a keyboard? In this article, you'll read how to convert images for use on your display, so that you can show off your own image on your keyboard.

Your keymap will probably already have the OLED display enabled. Want to learn how to enable it first? Read the article OLED Driver in the QMK documentation.

Acquire an image

First off, you'll need an image. Depending on your display, you may want a specific size. These sizes are the most common:

• An image with a size of 128 pixels wide by 64 pixels tall is used on the larger OLED displays, such as on that of the Kyria.
• An image with a size of 128 pixels wide by 32 pixels tall is often used on other keyboards, like the Corne, Lily 58 and others. You may need to play with the rotation of your image, depending on the settings in your keymap.

For this tutorial, I'm using the following image of the Kyria logo:

Convert your image

To convert your image, there are various tools. One of the most popular ones is image2cpp. First off, upload your image. I found using a black and white bitmap (.bmp file) works well, but it can also deal with other files. In this case, I've chosen to upload a bitmap file like below:

Next up, we need to choose some image settings. It'll try to load some sensible settings for the image you've uploaded. Verify that the canvas size fits with your image and display, and set the background color to the appropriate color. I set it to black, meaning that the white pixels will be lit on the OLED display. You can toggle Invert image colors to have the background light up instead.

Now it's time to generate the output to be used in your keymap. For the settings, choose a Code output format of "plain bytes", and a Draw mode of "Vertical - 1 bit per pixel". This will give the proper output that QMK will understand.

Using the image in your keymap

With the image code generates, we can put it to use! Let's define a function first to more easily write the image. If you're adapting an existing keymap, you may find this function exists already, in which case you can alter it instead.

static void render_my_logo(void) {
  static const char PROGMEM my_logo[] = {
    // Paste the code from the previous step below this line!

  };

  oled_write_raw_P(my_logo, sizeof(my_logo));
}

bool oled_task_user(void) {
  if (is_keyboard_master()) {
    // If you want to put your image on the master side, put your function call here:
    render_my_logo();
  } else {
    // And if you want to put your image on the slave side, put it here instead:
    render_my_logo();
  }
  return true;
}

More resources

• OLED Driver on the official QMK documentation.
• What can you use an OLED display for on a keyboard? can give you more ideas on how to use your OLED display.
• A logo editor by Joric helps you alter font files.