Skip to main content

Bluetooth Guide

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 Profiles​

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.

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 Individual Profiles​

Clearing a profile is necessary if you want to vacate a Bluetooth profile and assign it to a different device. In certain cases, clearing the profile is useful for reestablishing the bond with the same device.

  1. Identify the profile that you would like to use.
  2. Activate the profile by pressing the corresponding &bt BT_SEL key.
  3. Delete the "SliceMK ErgoDox" bond from the device that previously occupied the profile.
    • This step ensures that the old device does not attempt to reconnect to the central.
    • It is important to complete this before proceeding to the next step. If the old device continues to reconnect, the profile may not vacate successfully.
  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.

Troubleshooting​

If a device is not able to connect wirelessly:

  • Check that the active profile is not in use by another device.
  • Check that the device is not associated with a different profile.
  • Check that the device supports Bluetooth 4.2 or newer.

When troubleshooting, the &bt BT_CLR_ALL key can be useful for clearing all 5 profiles at once.

The Bond Reset Instructions can also be used to clear all Bluetooth profiles. This option should only be tried as a last resort since this will also delete the bonds between the dongle and keyboard halves.