ZMK Raytac USB Dongle Module

This repository adds a ZMK board definition named mdbt50q_rx for the Raytac MDBT50Q-RX USB stick, with the intention of using it as a ZMK keyboard dongle.

Caveat: Buy One With A UF2 Bootloader Installed

The stock MDBT50Q-RX does not come with the UF2 bootloader installed—that's the bit of code that allows it to mount itself as a USB drive for flashing.

But! Some versions of the dongle do exist with the UF2 bootloader pre-installed, and that's what you want buy: Adafruit (USA) and Pi Hut (UK) sell them, and probably others if you search around. I used the one from Adafruit.

Update The Bootloader

I upgraded the version of the bootloader on my Raytac dongle and you should to. Someone on Reddit confirmed that you need to update to get it working. So go ahead and update, it's easy.

I used these instructions to update the bootloader to version 0.9.2. Specifically I used this exact one.

Once you update the bootloader, hold the button down while plugging it in, navigate to the drive in your file browser, and open INFO_UF2.TXT. You want to see this:

UF2 Bootloader 0.9.2 lib/nrfx (v2.0.0) lib/tinyusb (0.12.0-145-g9775e7691) lib/uf2 (remotes/origin/configupdate-9-gadbb8c7) # <-- Important, v0.9.2 from above
...
SoftDevice: S140 6.1.1 # <-- Important, v6.x of SoftDevice

ZMK Versioning

ZMK v0.4 introduced breaking changes which affect this module and you as a user.

You must pin your ZMK version and pin this module to match.

The remainder of this readme will detail how to use the module in ZMK v0.4.

If you are using an earlier version of ZMK, please refer to an earlier version of this readme.

Usage for ZMK 0.4

Add the following entries to remotes and projects in config/west.yml

manifest:
  remotes:
    - name: zmkfirmware
      url-base: https://github.com/zmkfirmware
    - name: rschenk
      url-base: https://github.com/rschenk
  projects:
    - name: zmk
      remote: zmkfirmware
      revision: v0.4 # <-- ZMK pinned to v0.4
      import: app/west.yml
    - name: zmk-component-raytac-dongle
      remote: rschenk
      revision: v0.4 # <-- This module pinned to the same version as ZMK
  self:
    path: config

Configuring Your Dongle

Follow the setup steps in the ZMK Keyboard Dongle docs to configure your keyboard and dongle. When you get to the Building the Firmware step, you will use board: mdbt50q_rx in your build.yml file like so:

include:
  # Config settings for the dongle
  - board: mdbt50q_rx
    shield: my_keyboard_dongle
    
  - board: mdbt50q_rx
    shield: settings_reset

  # Whatever your keyboard uses...
  - board: nice_nano
    shield: my_keyboard

Flashing The Raytac

Entering the bootloader mode is a bit annoying. Unplug the dongle, then hold the button down while plugging it back in.

For some reason you can't double-click the reset button like on many boards.