zmk/docs/docs/config/system.md

title	sidebar_label
System Configuration	System

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

Config	Type	Description	Default
CONFIG_ZMK_KEYBOARD_NAME	string	The name of the keyboard (max 16 characters)
CONFIG_ZMK_SETTINGS_RESET_ON_START	bool	Clears all persistent settings from the keyboard at startup	n
CONFIG_ZMK_SETTINGS_SAVE_DEBOUNCE	int	Milliseconds to wait after a setting change before writing it to flash memory	60000
CONFIG_ZMK_WPM	bool	Enable calculating words per minute	n
CONFIG_HEAP_MEM_POOL_SIZE	int	Size of the heap memory pool	8192

HID

:::warning[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.

:::

Config	Type	Description	Default
CONFIG_ZMK_HID_INDICATORS	bool	Enable receipt of HID/LED indicator state from connected hosts	n
CONFIG_ZMK_HID_CONSUMER_REPORT_SIZE	int	Number of consumer keys simultaneously reportable	6
CONFIG_ZMK_HID_SEPARATE_MOD_RELEASE_REPORT	bool	Send modifier release event after non-modifier release event	n

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

Config	Description
CONFIG_ZMK_HID_REPORT_TYPE_HKRO	Enable CONFIG_ZMK_HID_KEYBOARD_REPORT_SIZE key roll over.
CONFIG_ZMK_HID_REPORT_TYPE_NKRO	Enable full N-key roll over. This may prevent the keyboard from working with some BIOS/UEFI versions.

:::note[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:

Config	Type	Description	Default
CONFIG_ZMK_HID_KEYBOARD_REPORT_SIZE	int	Number of keyboard keys simultaneously reportable	6

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

Config	Type	Description	Default
CONFIG_ZMK_HID_KEYBOARD_NKRO_EXTENDED_REPORT	bool	Enable less frequently used key usages, at the cost of compatibility	n

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

Config	Description
CONFIG_ZMK_HID_CONSUMER_REPORT_USAGES_FULL	Enable all consumer key codes, but may have compatibility issues with some host OSes
CONFIG_ZMK_HID_CONSUMER_REPORT_USAGES_BASIC	Prevents using some consumer key codes, but allows compatibility with more host OSes

USB

Config	Type	Description	Default
CONFIG_USB	bool	Enable USB drivers
CONFIG_USB_DEVICE_VID	int	The vendor ID advertised to USB	0x1D50
CONFIG_USB_DEVICE_PID	int	The product ID advertised to USB	0x615E
CONFIG_USB_DEVICE_MANUFACTURER	string	The manufacturer name advertised to USB	"ZMK Project"
CONFIG_USB_HID_POLL_INTERVAL_MS	int	USB polling interval in milliseconds	1
CONFIG_ZMK_USB	bool	Enable ZMK as a USB keyboard
CONFIG_ZMK_USB_BOOT	bool	Enable USB Boot protocol support	n
CONFIG_ZMK_USB_INIT_PRIORITY	int	USB init priority	50

:::note[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.

Config	Type	Description	Default
CONFIG_BT	bool	Enable Bluetooth support
CONFIG_BT_BAS	bool	Enable the Bluetooth BAS (battery reporting service)	y
CONFIG_BT_MAX_CONN	int	Maximum number of simultaneous Bluetooth connections	5
CONFIG_BT_MAX_PAIRED	int	Maximum number of paired Bluetooth devices	5
CONFIG_ZMK_BLE	bool	Enable ZMK as a Bluetooth keyboard
CONFIG_ZMK_BLE_CLEAR_BONDS_ON_START	bool	Clears all bond information from the keyboard on startup	n
CONFIG_ZMK_BLE_CONSUMER_REPORT_QUEUE_SIZE	int	Max number of consumer HID reports to queue for sending over BLE	5
CONFIG_ZMK_BLE_KEYBOARD_REPORT_QUEUE_SIZE	int	Max number of keyboard HID reports to queue for sending over BLE	20
CONFIG_ZMK_BLE_INIT_PRIORITY	int	BLE init priority	50
CONFIG_ZMK_BLE_THREAD_PRIORITY	int	Priority of the BLE notify thread	5
CONFIG_ZMK_BLE_THREAD_STACK_SIZE	int	Stack size of the BLE notify thread	512
CONFIG_ZMK_BLE_PASSKEY_ENTRY	bool	Experimental: require typing passkey from host to pair BLE connection	n

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

Config	Type	Description	Default
CONFIG_ZMK_USB_LOGGING	bool	Enable USB CDC ACM logging for debugging	n
CONFIG_ZMK_LOG_LEVEL	int	Log level for ZMK debug messages	4

Split keyboards

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

Config	Type	Description	Default
CONFIG_ZMK_SPLIT	bool	Enable split keyboard support	n
CONFIG_ZMK_SPLIT_ROLE_CENTRAL	bool	y for central device, n for peripheral
CONFIG_ZMK_SPLIT_PERIPHERAL_HID_INDICATORS	bool	Enable split keyboard support for passing indicator state to peripherals	n
CONFIG_ZMK_SPLIT_BLE	bool	Use BLE to communicate between split keyboard halves	y
CONFIG_ZMK_SPLIT_BLE_CENTRAL_PERIPHERALS	int	Number of peripherals that will connect to the central	1
CONFIG_ZMK_SPLIT_BLE_CENTRAL_BATTERY_LEVEL_FETCHING	bool	Enable fetching split peripheral battery levels to the central side	n
CONFIG_ZMK_SPLIT_BLE_CENTRAL_BATTERY_LEVEL_PROXY	bool	Enable central reporting of split battery levels to hosts	n
CONFIG_ZMK_SPLIT_BLE_CENTRAL_BATTERY_LEVEL_QUEUE_SIZE	int	Max number of battery level events to queue when received from peripherals	CONFIG_ZMK_SPLIT_BLE_CENTRAL_PERIPHERALS
CONFIG_ZMK_SPLIT_BLE_CENTRAL_POSITION_QUEUE_SIZE	int	Max number of key state events to queue when received from peripherals	5
CONFIG_ZMK_SPLIT_BLE_CENTRAL_SPLIT_RUN_STACK_SIZE	int	Stack size of the BLE split central write thread	512
CONFIG_ZMK_SPLIT_BLE_CENTRAL_SPLIT_RUN_QUEUE_SIZE	int	Max number of behavior run events to queue to send to the peripheral(s)	5
CONFIG_ZMK_SPLIT_BLE_PERIPHERAL_STACK_SIZE	int	Stack size of the BLE split peripheral notify thread	650
CONFIG_ZMK_SPLIT_BLE_PERIPHERAL_PRIORITY	int	Priority of the BLE split peripheral notify thread	5
CONFIG_ZMK_SPLIT_BLE_PERIPHERAL_POSITION_QUEUE_SIZE	int	Max number of key state events to queue to send to the central	10