Skip to main content

System Configuration

These are general settings that control how the keyboard behaves and which features it supports. Several of these settings come from Zephyr and are not specific to ZMK, but they are listed here because they are relevant to how a keyboard functions.

See Configuration Overview for instructions on how to change these settings.

Kconfig

Definition file: zmk/app/Kconfig

General

ConfigTypeDescriptionDefault
CONFIG_ZMK_KEYBOARD_NAMEstringThe name of the keyboard (max 16 characters)
CONFIG_ZMK_SETTINGS_RESET_ON_STARTboolClears all persistent settings from the keyboard at startupn
CONFIG_ZMK_SETTINGS_SAVE_DEBOUNCEintMilliseconds to wait after a setting change before writing it to flash memory60000
CONFIG_ZMK_WPMboolEnable calculating words per minuten
CONFIG_HEAP_MEM_POOL_SIZEintSize of the heap memory pool8192

HID

Refreshing the HID descriptor

Making changes to any of the settings in this section modifies the HID report descriptor and requires it to be refreshed.

ConfigTypeDescriptionDefault
CONFIG_ZMK_HID_INDICATORSboolEnable receipt of HID/LED indicator state from connected hostsn
CONFIG_ZMK_HID_CONSUMER_REPORT_SIZEintNumber of consumer keys simultaneously reportable6
CONFIG_ZMK_HID_SEPARATE_MOD_RELEASE_REPORTboolSend modifier release event after non-modifier release eventn

Exactly zero or one of the following options may be set to y. The first is used if none are set.

ConfigDescription
CONFIG_ZMK_HID_REPORT_TYPE_HKROEnable CONFIG_ZMK_HID_KEYBOARD_REPORT_SIZE key roll over.
CONFIG_ZMK_HID_REPORT_TYPE_NKROEnable full N-key roll over. This may prevent the keyboard from working with some BIOS/UEFI versions.
NKRO usages

By default the NKRO max usage is set so as to maximize compatibility, however certain less frequently used keys (F13-F24 and INTL1-8) will not work with it. One solution is to set CONFIG_ZMK_HID_KEYBOARD_NKRO_EXTENDED_REPORT=y, however this is known to break compatibility with Android and thus not enabled by default.

If CONFIG_ZMK_HID_REPORT_TYPE_HKRO is enabled, it may be configured with the following options:

ConfigTypeDescriptionDefault
CONFIG_ZMK_HID_KEYBOARD_REPORT_SIZEintNumber of keyboard keys simultaneously reportable6

If CONFIG_ZMK_HID_REPORT_TYPE_NKRO is enabled, it may be configured with the following options:

ConfigTypeDescriptionDefault
CONFIG_ZMK_HID_KEYBOARD_NKRO_EXTENDED_REPORTboolEnable less frequently used key usages, at the cost of compatibilityn

Exactly zero or one of the following options may be set to y. The first is used if none are set.

ConfigDescription
CONFIG_ZMK_HID_CONSUMER_REPORT_USAGES_FULLEnable all consumer key codes, but may have compatibility issues with some host OSes
CONFIG_ZMK_HID_CONSUMER_REPORT_USAGES_BASICPrevents using some consumer key codes, but allows compatibility with more host OSes

USB

ConfigTypeDescriptionDefault
CONFIG_USBboolEnable USB drivers
CONFIG_USB_DEVICE_VIDintThe vendor ID advertised to USB0x1D50
CONFIG_USB_DEVICE_PIDintThe product ID advertised to USB0x615E
CONFIG_USB_DEVICE_MANUFACTURERstringThe manufacturer name advertised to USB"ZMK Project"
CONFIG_USB_HID_POLL_INTERVAL_MSintUSB polling interval in milliseconds1
CONFIG_ZMK_USBboolEnable ZMK as a USB keyboard
CONFIG_ZMK_USB_BOOTboolEnable USB Boot protocol supportn
CONFIG_ZMK_USB_INIT_PRIORITYintUSB init priority50
USB Boot protocol support

By default USB Boot protocol support is disabled, however certain situations such as the input of Bitlocker pins or FileVault passwords may require it to be enabled.

Bluetooth

See Zephyr's Bluetooth stack architecture documentation for more information on configuring Bluetooth.

ConfigTypeDescriptionDefault
CONFIG_BTboolEnable Bluetooth support
CONFIG_BT_BASboolEnable the Bluetooth BAS (battery reporting service)y
CONFIG_BT_MAX_CONNintMaximum number of simultaneous Bluetooth connections5
CONFIG_BT_MAX_PAIREDintMaximum number of paired Bluetooth devices5
CONFIG_ZMK_BLEboolEnable ZMK as a Bluetooth keyboard
CONFIG_ZMK_BLE_CLEAR_BONDS_ON_STARTboolClears all bond information from the keyboard on startupn
CONFIG_ZMK_BLE_CONSUMER_REPORT_QUEUE_SIZEintMax number of consumer HID reports to queue for sending over BLE5
CONFIG_ZMK_BLE_KEYBOARD_REPORT_QUEUE_SIZEintMax number of keyboard HID reports to queue for sending over BLE20
CONFIG_ZMK_BLE_INIT_PRIORITYintBLE init priority50
CONFIG_ZMK_BLE_THREAD_PRIORITYintPriority of the BLE notify thread5
CONFIG_ZMK_BLE_THREAD_STACK_SIZEintStack size of the BLE notify thread512
CONFIG_ZMK_BLE_PASSKEY_ENTRYboolExperimental: require typing passkey from host to pair BLE connectionn

Note that CONFIG_BT_MAX_CONN and CONFIG_BT_MAX_PAIRED should be set to the same value. On a split keyboard they should only be set for the central and must be set to one greater than the desired number of bluetooth profiles.

Logging

ConfigTypeDescriptionDefault
CONFIG_ZMK_USB_LOGGINGboolEnable USB CDC ACM logging for debuggingn
CONFIG_ZMK_LOG_LEVELintLog level for ZMK debug messages4

Split keyboards

Following split keyboard settings are defined in zmk/app/src/split/Kconfig (generic) and zmk/app/src/split/bluetooth/Kconfig (bluetooth).

ConfigTypeDescriptionDefault
CONFIG_ZMK_SPLITboolEnable split keyboard supportn
CONFIG_ZMK_SPLIT_ROLE_CENTRALbooly for central device, n for peripheral
CONFIG_ZMK_SPLIT_PERIPHERAL_HID_INDICATORSboolEnable split keyboard support for passing indicator state to peripheralsn
CONFIG_ZMK_SPLIT_BLEboolUse BLE to communicate between split keyboard halvesy
CONFIG_ZMK_SPLIT_BLE_CENTRAL_PERIPHERALSintNumber of peripherals that will connect to the central1
CONFIG_ZMK_SPLIT_BLE_CENTRAL_BATTERY_LEVEL_FETCHINGboolEnable fetching split peripheral battery levels to the central siden
CONFIG_ZMK_SPLIT_BLE_CENTRAL_BATTERY_LEVEL_PROXYboolEnable central reporting of split battery levels to hostsn
CONFIG_ZMK_SPLIT_BLE_CENTRAL_BATTERY_LEVEL_QUEUE_SIZEintMax number of battery level events to queue when received from peripheralsCONFIG_ZMK_SPLIT_BLE_CENTRAL_PERIPHERALS
CONFIG_ZMK_SPLIT_BLE_CENTRAL_POSITION_QUEUE_SIZEintMax number of key state events to queue when received from peripherals5
CONFIG_ZMK_SPLIT_BLE_CENTRAL_SPLIT_RUN_STACK_SIZEintStack size of the BLE split central write thread512
CONFIG_ZMK_SPLIT_BLE_CENTRAL_SPLIT_RUN_QUEUE_SIZEintMax number of behavior run events to queue to send to the peripheral(s)5
CONFIG_ZMK_SPLIT_BLE_PERIPHERAL_STACK_SIZEintStack size of the BLE split peripheral notify thread650
CONFIG_ZMK_SPLIT_BLE_PERIPHERAL_PRIORITYintPriority of the BLE split peripheral notify thread5
CONFIG_ZMK_SPLIT_BLE_PERIPHERAL_POSITION_QUEUE_SIZEintMax number of key state events to queue to send to the central10