Corne-ish Zen display improvements

zen-display-improvements.md

Display improvements for the Corne-ish Zen keyboard

This note details the changes made to the Zen and ZMK codebase to improve the experience of e-ink displays.

Getting the changes

You can test out below changes using your Zen config repo by modifying your config/west.yml file, following ZMK instructions:

manifest:
  remotes:
    - name: caksoylar
      url-base: https://github.com/caksoylar
  projects:
    - name: zmk
      remote: caksoylar
      revision: caksoylar/zen-v1+v2  # custom branch name
      import: app/west.yml
  self:
    path: config

...or alternatively, you can cherry-pick specific commits noted below to your own fork of ZMK.

Branches

The improvements for Corne-ish Zen v2 (for R3 of the GB) and v1 (R1/R2 GB) are in the caksoylar/zen-v1+v2 branch of my ZMK fork. (Note that you need to use corneish_zen_v1_left and corneish_zen_v1_right as the board names when building for v1.)

For convenience there is also a caksoylar/zen-v1+v2+experimental branch with the mouse keys feature incorporated from @urob's rebased branch and #1366 for the swapper behavior. Note that you need to un-pair and re-pair your BT profiles after enabling mouse keys for the first time.

Warning ⚠️: Going forward I will only maintain combined v1+v2 branches and not v2-only branches like caksoylar/zen-v2 and caksoylar/zen-v2+mouse.

Details of improvements

Below are the details of improvements, some are always in effect and some require setting corresponding config to be enabled, as detailed below.

1. Avoid unnecessarily refreshing the battery level widget (reduce ghosting)
   • https://github.com/caksoylar/zmk/commit/65ddbe3
2. Tweak battery level thresholds so the battery levels are more "accurate"
   • https://github.com/caksoylar/zmk/commit/0b55166
3. Add option to hide layer changes that are momentary (using &mo, &lt etc.) from the layer widget (reduces the number of partial refreshes)
   • https://github.com/caksoylar/zmk/commit/c5db4d2 and https://github.com/caksoylar/zmk/commit/e2d9519
   • Add CONFIG_ZMK_DISPLAY_HIDE_MOMENTARY_LAYERS=y to your corneish_zen.conf file to enable
4. Add a periodic full display refresh (to clear up ghosting) using zmkfirmware/zmk#969
   • https://github.com/caksoylar/zmk/commit/4c79085
   • Add CONFIG_ZMK_DISPLAY_FULL_REFRESH_PERIOD=N to your corneish_zen.conf file to refresh every N seconds
5. Add option to invert displays to white-on-black instead of black-on-white
   • https://github.com/caksoylar/zmk/commit/25a1d80
   • Add CONFIG_IL0323_INVERT=y to your corneish_zen.conf file to enable
6. Add option to hide the "LAYER" heading in the layer widget and realign all widgets
   • https://github.com/caksoylar/zmk/commit/eb0a2df
   • Add CONFIG_CUSTOM_WIDGET_LAYER_STATUS_HIDE_HEADING=y to your corneish_zen.conf file to enable
7. Add options to select different logo images to replace the "Corne-ish Zen" logo on the right half, from @manna-harbour:
   • https://github.com/caksoylar/zmk/commit/3f8e1b5
   • CONFIG_CUSTOM_WIDGET_LOGO_IMAGE_ZMK=y for ZMK logo instead of Zen
   • CONFIG_CUSTOM_WIDGET_LOGO_IMAGE_LPKB=y for LowProKB logo
   • CONFIG_CUSTOM_WIDGET_LOGO_IMAGE_MIRYOKU=y for Miryoku logo
8. Add option to enable @aumuell's driver tweak to reduce ghosting for partial refreshes
   • https://github.com/zmkfirmware/zmk/commit/08c307b
   • This causes a different fading pattern on partial refreshes, with vertical/horizontal banding rather than full screen. However it can make the fading stronger for some screens
   • Add CONFIG_IL0323_ALTERNATIVE_REFRESH=y to your corneish_zen.conf to enable

Contact

Feel free to contact me on Discord bravekarma#4601 or you can open an issue in https://github.com/caksoylar/zmk as well.

Hi there, thanks for the amazing work!

Do you mind briefly explaining the logo image format in case one would contribute/use different images?

Hey, you can create the image .c files with the LVGL image converter. Make sure to use the CF_INDEXED_1BIT color format and C array output type and I input 1-bit bmp files. I can't remember the dimension constraints right now exactly but you need the image to fit within ~80x40 dimensions. You also might need to experiment with black-on-white and white-on-black images to get the right output.