2021-03-07 13:06:15 +11:00
---
title: Display Configuration
sidebar_label: Displays
---
2022-04-30 12:22:13 +10:00
See the [displays feature page ](../features/displays.md ) for more details.
2021-03-07 13:06:15 +11:00
2022-04-30 12:22:13 +10:00
See [Configuration Overview ](index.md ) for instructions on how to change these settings.
2021-03-07 13:06:15 +11:00
## Kconfig
Definition files:
- [zmk/app/src/display/Kconfig ](https://github.com/zmkfirmware/zmk/blob/main/app/src/display/Kconfig )
- [zmk/app/src/display/widgets/Kconfig ](https://github.com/zmkfirmware/zmk/blob/main/app/src/display/widgets/Kconfig )
2022-12-02 10:58:31 +11:00
| Config | Type | Description | Default |
| -------------------------------------------------- | ---- | -------------------------------------------------------------- | ------- |
| `CONFIG_ZMK_DISPLAY` | bool | Enable support for displays | n |
| `CONFIG_ZMK_WIDGET_LAYER_STATUS` | bool | Enable a widget to show the highest, active layer | y |
| `CONFIG_ZMK_WIDGET_BATTERY_STATUS` | bool | Enable a widget to show battery charge information | y |
| `CONFIG_ZMK_WIDGET_BATTERY_STATUS_SHOW_PERCENTAGE` | bool | If battery widget is enabled, show percentage instead of icons | n |
| `CONFIG_ZMK_WIDGET_OUTPUT_STATUS` | bool | Enable a widget to show the current output (USB/BLE) | y |
| `CONFIG_ZMK_WIDGET_WPM_STATUS` | bool | Enable a widget to show words per minute | n |
2021-03-07 13:06:15 +11:00
2022-04-30 11:46:23 +10:00
If `CONFIG_ZMK_DISPLAY` is enabled, exactly zero or one of the following options must be set to `y` . The first option is used if none are set.
2021-03-07 13:06:15 +11:00
2022-04-30 11:46:23 +10:00
| Config | Description |
| ------------------------------------------- | ------------------------------ |
| `CONFIG_ZMK_DISPLAY_STATUS_SCREEN_BUILT_IN` | Use the built-in status screen |
| `CONFIG_ZMK_DISPLAY_STATUS_SCREEN_CUSTOM` | Use a custom status screen |
2021-03-07 13:06:15 +11:00
2022-04-30 11:46:23 +10:00
If `CONFIG_ZMK_DISPLAY` is enabled, exactly zero or one of the following options must be set to `y` . The first option is used if none are set.
2021-03-07 13:06:15 +11:00
2022-04-30 11:46:23 +10:00
| Config | Description |
| ----------------------------------------- | ----------------------------------------- |
| `CONFIG_ZMK_DISPLAY_WORK_QUEUE_SYSTEM` | Use the system main thread for UI updates |
| `CONFIG_ZMK_DISPLAY_WORK_QUEUE_DEDICATED` | Use a dedicated thread for UI updates |
Using a dedicated thread requires more memory but prevents displays with slow updates (e.g. E-paper) from delaying key scanning and other processes. If enabled, the following options configure the thread:
| Config | Type | Description | Default |
| ------------------------------------------------ | ---- | ---------------------------- | ------- |
| `CONFIG_ZMK_DISPLAY_DEDICATED_THREAD_STACK_SIZE` | int | Stack size for the UI thread | 2048 |
| `CONFIG_ZMK_DISPLAY_DEDICATED_THREAD_PRIORITY` | int | Priority for the UI thread | 5 |
You must also configure the driver for your display. ZMK provides the following display drivers:
- [IL0323 ](https://github.com/zmkfirmware/zmk/blob/main/app/drivers/display/Kconfig.il0323 )
Zephyr provides several display drivers as well. Search for the name of your display in [Zephyr's Kconfig options ](https://docs.zephyrproject.org/latest/kconfig.html ) documentation.
2021-03-07 13:06:15 +11:00
## Devicetree
2022-04-30 11:46:23 +10:00
See the Devicetree bindings for your display. Here are the bindings for common displays:
2021-03-07 13:06:15 +11:00
2022-04-30 11:46:23 +10:00
- [IL0323 ](https://github.com/zmkfirmware/zmk/blob/main/app/dts/bindings/display/gooddisplay%2Cil0323.yaml )
- [SSD1306 (i2c) ](https://docs.zephyrproject.org/latest/build/dts/api/bindings/display/solomon,ssd1306fb-i2c.html )
- [SSD1306 (spi) ](https://docs.zephyrproject.org/latest/build/dts/api/bindings/display/solomon,ssd1306fb-spi.html )
2021-03-07 13:06:15 +11:00
2022-04-30 11:46:23 +10:00
A full list of drivers provided by Zephyr can be found in [Zephyr's Devicetree bindings index ](https://docs.zephyrproject.org/latest/build/dts/api/bindings.html ).