Bluetooth Behavior


The bluetooth behavior allows management of various settings and states related to the bluetooth connection(s) between the keyboard and the host. By default, ZMK supports five "profiles" for selecting which bonded host computer/laptop/keyboard should receive the keyboard input; many of the commands here operation on those profiles.

Bluetooth Command Defines

Bluetooth command defines are provided through the dt-bindings/zmk/bt.h header, which is added at the top of the keymap file:

#include <dt-bindings/zmk/bt.h>

This will allow you to reference the actions defined in this header such as BT_CLR_CMD.

Here is a table describing the command for each define:

BT_CLR_CMDClear bond information between the keyboard and host for the selected profile.
BT_NXT_CMDSwitch to the next profile, cycling through to the first one when the end is reached.
BT_PRV_CMDSwitch to the previous profile, cycling through to the last one when the beginning is reached.
BT_SEL_CMDSelect the 0-indexed profile by number.

Because at least one bluetooth commands takes an additional parameter, it is recommended to use the following aliases in your keymap to avoid having to specify an ignored second parameter:

BT_CLRAlias for BT_CLR_CMD 0 to clear the current profile's bond to the current host
BT_NXTAlias for BT_NXT_CMD 0 to select the next profile
BT_PRVAlias for BT_PRV_CMD 0 to select the previous profile
BT_SELAlias for BT_SEL_CMD to select the given profile, e.g. &bt BT_SEL 1

Bluetooth Behavior

The bluetooth behavior completes an bluetooth action given on press.

Behavior Binding

  • Reference: &bt
  • Parameter #1: The bluetooth command define, e.g. BT_CLR_CMD
  • Parameter #2: (Reserved for future bluetooth command types)


  1. Behavior binding to clear the paired host for the selected profile:

    &bt BT_CLR
  2. Behavior binding to select the next profile:

    &bt BT_NXT
  3. Behavior binding to select the previous profile:

    &bt BT_PRV
  4. Behavior binding to select the 2nd profile (passed parameters are zero based):

    &bt BT_SEL 1