Return to parent post

ErgoBlue 2 Firmware

A number of firmware options are available. The recommended firmware is ZMK and this page will go over the process of setting up ZMK for ErgoBlue. Users who have questions about ZMK should join its Discord server.

ZMK is still a work in progress so there will be some rough edges. This will certainly improve with time. ZMK is also not as feature rich as QMK though development is happening at a very quick pace.

There are other firmware options such as BlueMicro and numerous QMK forks though I have no personal experience with those and can't speak to how well they work. In particular I recommend against QMK forks due to the setup difficulty, even for advanced users.

External Dongle/Controller

The external dongle maintains state between the two keyboard halves so things such as layers can work. The dongle also serves as a Bluetooth keyboard itself. ZMK allows multiple devices to it simultaneously and the user can switch between them with a custom defined keymap.

When plugged directly into a computer, the dongle also acts as a regular wired keyboard. If you're primarily using it with a laptop and/or mobile devices, you may plug it into an AC USB adapter at home or a portable charger on the go.

While it's possible to use one of the keyboard halves as the controller, it's not something I've personally tried. Doing so will negatively impact the battery life by a significant margin.

Setup Notes

You will need to download nRF Connect for your operating system. You may find the firmware setup video helpful. Note that this page will remain the authoritative source for ZMK on ErgoBlue. Details will be added and updated as necessary.

The Nordic nRF52840 Dongle has two buttons: one large white button facing facing up and a sideways button next to it. The sideways button is the reset button and you'll need to press that in order to update the firmware with nRF Connect.

Reset Button

ZMK Dongle Setup

  1. Start with the compiled binary file. On the ZMK configuration repository commit page, click the green check mark under the most recent commit and click "Details".
  2. Download the firmware file under "Artifacts".
  3. Load zmk.hex onto the external dongle.

Peripheral Setup (Left and Right Halves)

  1. Download compiled binaries.
  2. Load s140_nrf52_7.2.0_softdevice.hex with nordic-left.hex onto the left half. ZMK should automatically connect to it. Pressing a switch should cause a key to be pressed on the computer that the ZMK dongle is plugged into.
  3. Repeat the previous step with s140_nrf52_7.2.0_softdevice.hex and nordic-right.hex on the right half.

Customize via GitHub Actions

ZMK relies on GitHub Actions to compile the keyboard firmware so users do not need to have any compiler installed locally. The following steps will allow you to customize your keymap by making changes to a GitHub repository. If you had difficulty connecting the ZMK dongle to the keyboard halves in the previous section, this will also allow you to pinpoint the cause by enable logging/debugging.

  1. Fork the ZMK configuration repository.
  2. Go to the "Actions" tab on GitHub in your forked repository. Click "I understand my workflows, go ahead and enable them".

Enabling Logging/Debugging

If one or both keyboard halves are not working, the ZMK dongle can log via USB for debugging purposes. Add the following lines to config/ergoblue.conf.

# Turn on logging.

# Log via USB.

Saving and committing the file will trigger a new ZMK build. You will want to flash the new zmk.hex from GitHub Actions.

Users can use the Arduino IDE on most operating systems to view the USB console. Advanced users may choose a different program for this purpose. See ZMK's USB debugging page for more information along with other programs that display the logs.

When using Arduino:

  1. Select the device under Tools -> Port. On Linux, it will be something with the prefix /dev/ttyACM. On macOS, it will be something with the prefix /dev/tty.usbmodem.
  2. Go to Tools -> Serial Monitor.

Logging should be disabled again when it is no longer necessary for debugging. Depending on the operating system, there may be negative security implications for having logging enabled.

Keymap Customization

  1. Make changes to config/ergoblue.keymap as necessary. See ZMK documentation for a full list of codes.
  2. Wait for GitHub Actions to build your binary. Subsequently load the new zmk.hex onto your ZMK dongle.

Return to parent post