Display Configuration
See the displays feature page for more details.
See Configuration Overview for instructions on how to change these settings.
Kconfig
Definition files:
| Config | Type | Description | Default |
|---|---|---|---|
CONFIG_ZMK_DISPLAY | bool | Enable support for displays | n |
CONFIG_ZMK_DISPLAY_BLANK_ON_IDLE | bool | Blank display on idle | y if SSD1306 |
CONFIG_ZMK_DISPLAY_TICK_PERIOD_MS | int | Period (in ms) between display task execution | 10 |
CONFIG_ZMK_DISPLAY_INVERT | bool | Invert display colors from black-on-white to white-on-black | 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 |
Note that CONFIG_ZMK_DISPLAY_INVERT setting might not work as expected with custom status screens that utilize images.
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.
| 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 |
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.
| 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:
Zephyr provides several display drivers as well. Search for the name of your display in Zephyr's Kconfig options documentation.
Devicetree
See the Devicetree bindings for your display. Here are the bindings for common displays:
A full list of drivers provided by Zephyr can be found in Zephyr's Devicetree bindings index.
Chosen nodes
Applies to: /chosen node
| Property | Type | Description |
|---|---|---|
zephyr,display | path | The display device to use. |
zmk,display-led | path | The LED device to use for on/off blanking, if the hardware requires it. Can be a PWM or GPIO LED device. |