Wireless Build

Setup & Troubleshooting for ZMK Wireless Build

Github Action & Keymap Editor

1

Fork the relevant repository to your GitHub account. Make sure you have a GitHub account created beforehand. (eg. zmk-config-crkbd)

2

Untick this so it allows you to copy niceview and oled branches, then create Create fork.

3

Click Actions, I understand my workflows, go ahead and enable them.

4

Click the left .github/workflows/build..., and click Run workflow on right. Wait it run for a few minutes until a green tick.

5

Go to Keymap Editor to remap your own keymap, click Github.

6

Login with Github, sign in with your Github account.

7

Read and click Add Repository.

8

Tick Only select repositories, Select repository that you would like to remap. Then, Install.

9

Now you can start remapping. Click and remap to check the behavior. You may refer to the List of Keycodes for reference.

10

For some repositories, there is a branch for the OLED display. Please ensure that you have selected the correct branch. If your build includes an OLED display but the OLED branch does not appear and only 'master' or 'main' is available, you likely skipped Step 2, which requires you to untick 'Copy the main branch only'.

11

After setting up your keymap, click Save and leave a message in the box if you’d like. This will serve as a note for you on the changes made to the keymap.

12

Wait a few minutes for the compilation to complete. When 'Latest' shows a tick instead of 'Loading,' the firmware is ready to be downloaded. Click 'Latest'.

13

After clicking Latest, you will be automatically redirected to the GitHub Actions webpage. Scroll down, click Firmware, and download the ZIP file.

---

Flashing Firmware Uf2

You may refer to the demo for flashing procedure. Details as follow:

1. Extract the zip and drop the left and right uf2 on your desktop.

2. Connect left and right splits to your pc (both connect together using type c cable).

3. Put right into bootloader mode (press the reset button), one window is popped out showing "nicenano" folder. Dont do anything yet, remember this folder as right split.

4. Now press reset button on your left split, one window will be popped out as previous step.

5. Drag left and right uf2 to respective folders.

6. Do not disconnect right split yet.

7. Remove left split from type c cable. Proceed to pair your board throught Bluetooth of your pc. If successfully connected, you shall able to type without cable now.

8. If so, remove the right split from type c cable. Both should be working good now!

9. If you dont have extra usb c cable...You can do left first, then quickly move to right so the right can sync with left.

For future keymap updates, you only need to plug in the left side and flash the left UF2. Updating the right side is not required. If this shortcut doesn’t work, you can flash the right side again following the steps above.

If your repository comes pre-built with ZMK Studio enabled, you can remap directly using ZMK Studio. Connecting to the left side is sufficient to refresh the keymap. If ZMK Studio’s features are not sufficient for your needs, you can continue using Nick's Keymap Editor.

Keymap & Layout

1. Urob idea on zmk

2. Miryoku layout

3. Corne 5col by jporter

Nick's Keymap Editor Explanation

Keystroke

Tap as S

Mod/Tap

Example: Hold as Left Shift, Tap as Tab

Layer/Tap

Example: Hold to access Layer 2, Tap as Enter

Mod+Keystroke

Tick any modifier you wish to bind to

Hold-Tap Behavior

To address issues with interruptions when using Mod-Tap or Layer-Tap, consider enabling "Permissive Hold" like in Vial, it is called Balanced in ZMK.

Check Comparison to QMK on Zmk docs, "Balanced" is similar to QMK's Permissive Hold.

This setting is suitable for Home Row Mode (HRM). Eg. Hold as Lshft, tap as S.

This setting is suitable for Layer trigger. Eg. Hold as MO(Layer1), tap as Esc.

Tap-Dance

This is similar to Vial to perform double, triple taps etc. But in ZMK there is no "Tap and Hold" like in Vial. Read more on Tap-Dance Behavior. Example in this video:

Tap- W

Hold - Left Shift

Tap Twice - Right Click

Some special example on tap dance for mousekeys.

Tap - left click

Hold - left click (drag)

Double tap - right click

Macro

Keys press together to get another key

Enable Mouse Keys in ZMK

If the mouse keys you assigned not working, try this.

ZMK Studio

ZMK Studio was launched in November 2024 by ZMK to enable real-time key remapping. It allows remapping through a master connection or wirelessly. However, since it is still very new, it only supports basic key remapping and does not include advanced features such as macros, combos, mouse key setups, new behaviors, etc. (See ZMK StudioCapabilities).

Additionally, there may be keymap conflicts because changes made in ZMK Studio will not sync with GitHub Actions. This means that while ZMK Studio is convenient for simple key remapping, it becomes inconvenient when setting up macros, combos, or more advanced configurations via GitHub Actions as changes you made in ZMK Studio will not reflected in your Github (See Keymap Changes).

It is convenient to quickly test a new keymap using ZMK Studio; however, Nick's Keymap Editor provides a more comprehensive configuration experience.

Charging Instructions

1. Power Button: Flip the power button on while charging. If the power button is off, the device will not charge.

2. Charging Both Sides: You can charge both sides simultaneously using a USB-C cable without any issues.

3. Charging While Using: While it is possible to charge the device while in use, we recommend avoiding continuous plugging in.

4. Wired Mode: If you prefer to use the device in wired mode, plug it in and turn off the power button. This will prevent charging and help protect the battery from degradation.

Niceview Display

This Niceview display refers to hardware released by Nice (available at Nice Keyboards), including the model from Nologo (available at Nologo Tech).

Graphic Explanation

Niceview Explanation

Graphic Alternative

Since this is open-source software, you have the flexibility to customize it according to your needs. Alternatively, you can explore existing resources shared by other authors.

Nice-view-gem

Wireless Trackball: What You Need to Know

The wireless trackball for the Keyball series has a few setup challenges. Please keep these points in mind:

1. Uneven Movement Scaling – Horizontal and vertical movements do not use the same pixel scaling. Vertical (up/down) movements have smaller steps compared to horizontal movements.

2. Customization via GitHub Actions – Adjusting settings like DPI, scrolling speed, or sensitivity requires modifying the zmk-config in the product’s GitHub repository.

3. Wired Connection is Smoother – While Bluetooth works, a wired connection provides a smoother experience. For better performance, keeping the right half (master) connected via USB is recommended.

4. Community-Driven Project – This trackball is an open-source project powered by the ZMK community. It cannot be directly compared to established wireless brands. However, its advantage lies in seamless keyboard integration, reducing the need to lift your hand for cursor movements.