Customize your wireless keymap

This is a quick guide on using the amazing web app called keymap-editor along side github to customize and flash your keyboard.  In this guide I'll be using a Sofle Choc 59 key as example but this will work with any keyboard thats running ZMK (wireless).  You should find links in my listings with the repo location of each of my keyboards else just ask.

This guide is only for wireless keyboards using ZMK not wired keyboards.  My wired keyboards are flashed with Vial-QMK please download the Vial app for those.

Note: All wireless keyboards except the Totem now come flashed with ZMK.studio. Which lets you change basic keymap keys.  You can do this with your web browser without having to re flash.  It will only let you add keys that are already in your keymap so for more advanced changes like adding combos, macros and changing your encoder mappings follow the below guide.

If you get stuck reach out and I will be glad to help all of my customers.

All firmware files have update with new links.  If you have followed the guide in the past and are now getting build errors or display issues it could be out of date and I recommend using my new firmware. Links located below.

 -Jake 2/21/26

1. Go to my Github and find the desired repo based on your keyboard.  Here are my more popular keyboards.

2. While signed into your Github account,  fork the repo for your keyboard.

3. Go to your newly forked repo and click on the actions tab.

4.  Click "I understand workflows" 

5. Select ".github/workflows/build.yml" from the top left.  

6. Select "Run workflow" then choose "Use workflow from Branch: master" and click "Run workflow"

7.  Go back to "All workflows" under "Actions".  Wait for the workflow to finish(Turns green).  This ensures we have a base, working keymap to fall back on.  I highly recommend not making too many changes at first.  I would get this step done then if it compiles green try more advanced changes.

8. Once the workflow finishes and turns green that means it compiled without errors.  If it came back with errors chances are it did not like something and I recommend starting back from default and try to change small things to find the problem.  Now go to keymap-editor https://nickcoutsos.github.io/keymap-editor/ 

  • Log in with your Github account and authorize if needed.
  • Select the option "Only select repositories."
  • Click the drop-down "Select repositories" and search for the repo that you forked.
  • Click "Install"

10. This will reload and display a nice GUI where you can start making edits to your keymap as desired.  Please note I don't recommend spending an hour making a bunch of changes at first for example to ensure you understand how macros work try out one, save and compile if it works then you are good to go.

11. Select "Save" button at the top then select "Comit" when the box pops up.

 

12. Go back to your Github repo and navigate to the "Actions" tab, where you'll see another workflow automatically running.  Wait for it to finish.  As long as it turns green(blue depending on theme), all changes have compiled without error.

13.  Select the completed workflow shown above around the red square.  Then download the zip folder and extract the contents.   

NOTE 2/21/26: If on Windows you may need to add the .zip file extension after download.  Just rename file to "firmware.zip" then you should be able to extract.

14.  For the next process make sure both halves are powered on the entire time. Also when transferring files you may get an error.  This is due to auto unmounting.  You can ignore this error and continue to the next step.

  • Plug in the left half of the keyboard.  Once plugged in you need to press the physical reset button twice that is located on the sides of each half.  This will put the keyboard into bootloader mode and open a new directory on your computer.
  • Open the new directory and drag and drop the Settings_reset file shown with the green box in the image. 
  • Now unplug the left half and plug in the right half.  Press the reset button twice.
  • drag and drop the same Settings_reset file shown with the green box into the right half keyboard directory.
  • Now plug in the left half of the keyboard again.  Drag and drop sofle_left nice_view if you have a keyboard with screens shown with the red box otherwise if you dont have displays choose the other one sofle_left-nice_nano.
  • Now unplug the left half and plug in the right half. Press the reset button twice.  Drag and drop sofle_right nice_view shown with the red box if you have displays otherwise if you dont have displays choose the sofle_right-nice_nano
  • Now you need to go to your computer or device and find your bluetooth device history list.  You should see a sofle device thats not connected or maybe its even showing its connected then disconnects.  You need to delete this from your device list.
  • Pair the keyboard as a new device.

Please note there is a new error that may pop up when transferring files.  You can just hit cancel and proceed to the next step it should transfer fine.