Bluetooth Tutorial (ZMK Firmware)

Preparation

Before you attempt to have devices connect wirelessly, make sure the central is fully working over USB.

  • If you are using a dongle, the dongle is the central. Make sure you are able to type on both keyboard halves with the dongle plugged in.
  • If you are not using a dongle, the left half is the central. Make sure you are able to type on both keyboard halves with the left half plugged in via USB.

If your keyboard halves are not yet working, please start with the Getting Started Guide to setup your keyboard:

Recommendations for First Time Users

If you are not using a dongle (left half is central), keep the left half plugged when setting up wireless connections for the first time. This will make testing a bit easier.

If you are using a dongle (dongle is central), the dongle must always be plugged in. Your devices will connect wirelessly to the dongle and receive data from the keyboard halves via the dongle.

It is highly suggested that you test the keyboard wirelessly with a phone or tablet before trying it with a desktop/laptop.

  • This lets you easily try the multi-device feature, with USB output going to your computer (that the central is plugged into) and Bluetooth output going to your phone/tablet. The subsequent sections will provide more information on how to do this.
  • BT on Android and iOS is a lot more consistent than BT on desktops/laptops (Windows, macOS, and Linux). You are unlikely to experience problems connecting your phone/tablet.
  • It will be easier to setup your desktops/laptops once you are already familiar with how the wireless functionality works. ZMK supports all major operating systems (Windows, macOS, and Windows).

Introduction to BT Profile

ZMK by default is configured with 5 BT profiles. Each profile can be used with one wireless device. These devices can be laptops, desktops, phones, or tablets.

The profiles are numbered 0, 1, 2, 3, and 4. To activate a particular profile, press the corresponding &bt BT_SEL key on your keyboard.

  • If the active profile is not yet associated with a device, you can connect to it from any device. Once that connection is established, the profile will be associated with the device in question.
  • If the active profile is already associated with a device, you will not be able to connect from a new device. If you would like to add a device, you will need to first change the active profile to an empty profile.
  • Make sure you know which profile belongs to which device. In your keymap, you can use a custom "Name" for each profile key or make a note in the "Notes" section. This is of course optional and purely for your benefit.

BT Profile and Output Selection

In the default keymap, the profile and output selection keys are on the fn layer. The fn layer is a momentary layer so you need to hold the fn layer key while pressing the subsequent &bt key.

  • &out OUT_BLE will prioritize BT output.
    • If the active BT profile is connected, output will be sent via BT.
    • If the active BT profile is not connected:
      • If central is connected via USB, output will be sent via USB.
      • If central is not connected via USB, output will be discarded.
  • &out OUT_USB will prioritize USB output via the central.
    • If the central is connected via USB, output will be sent via USB.
    • If the central is not connected via USB:
      • If the active BT profile is connected, output will be sent via BT.
      • If the active BT profile is not connected, output will be discarded.
  • &out OUT_TOG will toggle between prioritizing BT output and prioritizing USB output.

Please keep in mind that changing the active BT profile does not automatically prioritize BT output. If you would like that to happen automatically, you can define a macro that triggers both &bt BT_SEL n and &out OUT_BLE with one key press.

Clearing BT Profiles

If you want to vacate a Bluetooth profile and use it with a different device:

  1. Identify the profile that you would like to use.
  2. Activate it by pressing the corresponding &bt BT_SEL key.
  3. Delete the "SliceMK ErgoDox" bond from the old device.
    • This step is important to ensure that the it does not continue to connect to the central.
    • Additionally, this should be done before proceeding to the next step.
  4. Clear the profile by pressing the &bt BT_CLR key.
  5. Once the profile has been cleared, the central will start advertising. You can then connect to "SliceMK ErgoDox" from the new device.

It's important to delete the bond on the old device before you delete it from the keyboard/dongle. If you do it in the opposite order, the old device may continue connecting and prevent the profile from being vacated for the new device.