Software - joelspadin/NumBLE Wiki

Flashing the Bootloader

You will need a programmer so you can flash the bootloader onto the nRF module. IMO, the easiest programmer to use is a J-Link such the SEGGER J-Link EDU Mini. Cheaper options exist, but they may be more difficult to get working.

You can find several alternatives and more detailed instructions on the nRFMicro Wiki. NumBLE uses the same module as nRFMicro, so most of the instructions there apply to NumBLE as well. The main difference is that NumBLE has pads for a Tag-Connect cable, which has much smaller and more tightly spaced pads than the 0.1" pads on the nRFMicro.

The PCB supports a 6-pin Tag-Connect TC2030 no-legs cable. The cable with 10-pin micro-connector for Cortex processors fits the J-Link EDU Mini. If you don't want to buy an expensive cable, you can try holding wires against (or temporarily soldering them to) the SWD and SWC pins on the nRF52840 module.

Download the "numble_bootloader-*.hex" file from the latest release, then flash it to your NumBLE board using the programmer.

If you have a J-Link, you can use the programmer tool from nRF Connect:

  1. Connect the J-Link to the NumBLE board.
  2. Open nRF Connect Programmer.
  3. Use the drop down menu at the top left to select the device.
  4. Click "Add HEX file" at the top right and select the bootloader file.
  5. Click "Erase & write".

You can also use the nRF Command Line Tools:

nrfjprog -f nrf52 --program numble_bootloader-0.4.1-42-g881dac1-dirty_nosd.hex --sectorerase

If that fails, the module might be write protected. Try running this command, then the previous one again:

nrfjprog --recover --log

Once you have a working bootloader, you can use adafruit-nrfutil to flash bootloader updates with DFU over USB instead of using a hardware programmer.

Flashing the Firmware

Download the "numble-zmk.uf2" file from the latest release, or build your own firmware. To flash the firmware to NumBLE:

  1. Connect the NumBLE board to your PC with a USB cable.
  2. Remove the top of the case to expose the reset button, and quickly double tap the button. You should now see a new "NumBLE" USB storage device appear on your PC.
  3. Copy the .uf2 file and paste it to the root of the USB storage device.

If you see the file copy get very close to completion and then fail, that is normal. Flashing was successful, but the bootloader simply rebooted into the new firmware before telling the PC that the copy was done.

Customizing the Firmware

This is the default keymap:

Default keymap

Fn Key Description
Bootld Reset to bootloader
Unpair Clears the current Bluetooth profile
BT# Selects Bluetooth profile #
BT When connected to USB and Bluetooth, prefer Bluetooth
USB When connected to USB and Bluetooth, prefer USB

To customize the keymap:

  1. Fork this repo.
  2. Clone the repo to your PC.
  3. Optionally create and checkout a new branch. This will make it easier to pull in any improvements I make by syncing your main branch with upstream and merging that into your branch. For example:
    git checkout -b my-keymap
  4. Copy numble.keymap into the zmk-config folder.
  5. Create an empty text file named numble.conf in the zmk-config folder.
  6. Edit your copy of the keymap. See ZMK's documentation for more information.
  7. Commit your changes:
    git add .
    git commit
  8. Push your changes back to GitHub:
    git push

GitHub will automatically build the new firmware for you. You can check the status of the build and download the results from the "Actions" tab at the top of your repo page.


To enable the encoder, add the following to your numble.conf file:


Then open your numble.keymap file and uncomment the blocks of text below the // Uncomment to enable the encoder. comments.


The default keymap uses the 21-key layout. To use the 22 or 24-key layouts, open your numble.keymap file and look for the following line:

zmk,matrix_transform = &transform_numpad_21;

Change it according to which layout you want:

Layout Transform
21-key zmk,matrix_transform = &transform_numpad_21;
22-key zmk,matrix_transform = &transform_numpad_22;
24-key zmk,matrix_transform = &transform_macropad;

Then, fill in the gaps in the bindings arrays for the extra keys.

Bluetooth Profiles

By default, ZMK supports 5 Bluetooth profiles, and pressing Fn+# for 6-9 will do nothing. To increase or decrease the number of profiles, add the following to your numble.conf file (replacing 9 with the number you want):


See ZMK's Bluetooth documentation for more information on how profiles and pairing work.