Documentation

• 1: Getting Started
• 1.1: Connect to Your Device
• 1.2: Keymaps
• 1.2.1: Ferris Sweep Keymap
• 1.2.2: Ferris Sweep Pro Keymap
• 1.2.3: How to Update Keymaps
• 2: Firmware
• 2.1: How to Flash a Firmware
• 2.2: Build your own firmware

1 - Getting Started

Welcome to the next generation of typing comfort! This guide will help you set up your new split keyboard with the following steps:

What’s in the Box

When you receive your NXTKB, you’ll find:

• Two keyboard halves
• 2 USB charging cables (one c-to-c, one b-to-c)
• A bag for the keyboards
• other suprises…

Setup Instructions

This section contains detailed walkthroughs for getting your keyboard operational:

• Connecting to Your Device - Complete guide for USB and Bluetooth connections
• Keymaps - Default keymaps for each keyboard model, layer diagrams, and customization guides

Support Resources

• Check the Documentation for comprehensive guides
• Contact our team for any assistance: support

Now you’re ready to begin your ergonomic typing journey with NXTKB! Enjoy the health benefits and improved comfort your new keyboard will provide.

1.1 - Connect to Your Device

This guide will show you how to connect your NXTKB keyboard to your computer using various connection methods.

Connection Methods Overview

ZMK split keyboards support multiple connection methods:

• USB Wired Connection: Direct connection via USB cable
• Bluetooth Wireless Connection: Wireless connection to your device (up to 5 devices by default)

ZMK (Zephyr-based Modular Keyboard) uses a modular design where the secondary keyboard (right) sends keypress data to the main keyboard (usually left), which handles input processing and transmits the combined output to your target device through the selected connection method.

USB Connection

The USB connection is the most straightforward and reliable connection method.

Requirements

• USB-C cable (included in your package)
• USB port on your target device (computer, phone, tablet, etc.)

Steps

1. Prepare the connection: Secure your USB-C cable and ensure your device has a compatible USB port
2. Power on both keyboard halves: Turn on the power switch on both left and right halves (charging will only happen when power is switched on)
3. Connect the main half: Connect the left keyboard half to your target device using the USB-C cable
4. Test the connection: Begin typing to confirm that the keyboard is properly connected

Bluetooth Connection

Bluetooth offers wireless freedom but requires initial pairing to establish the connection.

Connecting New Devices

1. Enable Bluetooth: Ensure your target device has Bluetooth capability and that it’s turned on
2. Power on the keyboard: Turn on power switches on both halves of your keyboard
3. Put keyboard in pairing mode:
   • If connecting to a new device, you may need to clear the current device slot first
   • By default, keyboards start in device position 1
4. Clear existing pairings (optional): If the current position is already paired with another device, you may need to clear it first using BT_CLR key
5. Find your keyboard:
   • On your target device, scan for Bluetooth devices
   • Look for your keyboard’s specific name in the device list
   • Select and connect/pair with your keyboard
6. Switch connection mode (optional):
   • If your main keyboard is currently connected via USB, you can disconnect the USB cable
   • Or switch from USB to Bluetooth mode using the &tog key
7. Test the connection: Start typing to verify the connection is working

Reconnecting to Previously Paired Devices

1. Power on the keyboard: Turn on both halves
2. Ensure desired device slot is selected: Use BT_SEL 0 to BT_SEL 4 to select the proper device number
3. Wait for automatic reconnection: The keyboard will automatically attempt to connect to the previously paired device
4. Switch connection mode (optional):
   • If your main keyboard is still connected via USB, disconnect the USB cable
   • Or toggle between USB and Bluetooth modes using &tog
5. Test the connection: Type to confirm the connection

Device Switching

• Switch between bluetooth devices with BT_SEL <device_number>
• By default, USB input takes priority
• Use the &tog key to switch between USB and Bluetooth modes

Troubleshooting Common Issues

Bluetooth Pairing Fails

1. Ensure the keyboard is functioning in USB mode first
2. Check if other Bluetooth positions have existing connections - you may need to clear them first
3. Try pairing with a different target device to determine if the issue is with the keyboard or the target device

For additional help with connectivity issues, please consult our FAQ or contact support.

1.2 - Keymaps

NXTKB keyboards use ZMK (Zephyr-based Modular Keyboard) firmware. ZMK keymaps let you define what each key does, organize keys into switchable layers, and assign tap-hold behaviors — all through customizable configuration files.

Default Keymaps

Each NXTKB keyboard comes with a pre-configured keymap optimized for its layout:

• Ferris Sweep Pro Keymap
• Ferris Sweep Keymap

These pages contain visual layer diagrams and detailed explanations of each key function.

Customization

Want to change your keymap? See How to Update Keymaps for step-by-step instructions using ZMK Studio, the Keyboard Editor, or direct source code modification.

For more on ZMK, see the official ZMK documentation.

1.2.1 - Ferris Sweep Keymap

Introduction

The keymap images below are exported from keymap drawer, the latest keymap can also be viewed there.

The source code for this keymap is available at nxtkb/zmk-config-4-ferris-sweep, which provides the complete configuration for the NXTKB Ferris Sweep keyboard.

Keymap Layers

Characters (Default/Windows Layer)

• The default layer and windows layer is where you would type characters.
• they both have modifier keys CTRL, OPTION (ALT), COMMAND (WINDOWS) sharing same position with character keys on your ring finger, middle finger and pointing finger on both hands. Hold the key to trigger the modifier, or tap the key to type in character.

Numbers and Navigation

• Hold the right tab to enter right layer, then you can type in numbers or do some navigation.
• Release your right tab to return to default or windows layer.
• Special keys:
  • &bootloader: make right part of the split keyboard enter bootloader, then you can copy in your new firmware.

Symbols (Punctuations)

• Hold the left tab to enter left layer, then you can type in punctuations.
• Release your left tab to return to default or windows layer.
• Special keys:
  • &default_report: type out battery information
  • &bootloader: make left part of the split keyboard enter bootloader, then you can copy in your new firmware.
  • MOUSE toggle: switch to mouse layer

Functions

• Hold both the left and right tab to enter tri layer, then you can type function keys.
  • BT 0 to BT 4: select position of bluetooth device you are connecting or want to connect with.
  • BT CLR: clear the connection on selected position, then you can reconnect to this position with your device.
  • OUT TOG: toggle between usb and bluetooth connection, so you can connect up to 6 devices (5 with bluetooth, and 1 with usb)
  • WIN toggle: toggle windows layer, so you can switch between default and windows layer.
  • &studio_unlock: unlock keyboard so that you can use zmk studio to setup keys
  • &soft_off: enter soft off, like deep sleep which enters after an hour of inactivity, but soft off can only be woke up with wake up keys (set to left thumb key: shift)
• Release your tab keys to return to default or windows layer.

Mouse

• hold left tab (to enter left layer), and press space key to enter mouse layer
• press p or q to quit mouse layer
• MB4 is for going backward and MB5 is for going forward

References

• Sweep Repo
• keymap I initially copied

1.2.2 - Ferris Sweep Pro Keymap

Introduction

The keymap images below are exported from keymap drawer, the latest keymap can also be viewed there.

The source code for this keymap is available at nxtkb/Sweep-Pro, which provides the complete configuration for the NXTKB Ferris Sweep Pro keyboard.

Note: Here we need to set the layout override with this file: sweep.dtsi:

Keymap Layers

Characters (Default/Windows Layer)

• The default layer and windows layer is where you would type characters.
• they both have modifier keys CTRL, OPTION (ALT), COMMAND (WINDOWS) sharing same position with character keys on your ring finger, middle finger and pointing finger on both hands. Hold the key to trigger the modifier, or tap the key to type in character.
• left encoder:
  • rotation: adjust volume
  • click: toggle mute
• right encoder:
  • rotation: adjust brightness
  • click: unlock zmk studio

Numbers and Navigation

• Hold the right tab to enter right layer, then you can type in numbers or do some navigation.
• Release your right tab to return to default or windows layer.

Symbols (Punctuations)

• Hold the left tab to enter left layer, then you can type in punctuations.
• Release your left tab to return to default or windows layer.
• Special keys:
  • &default_report: type out battery information
  • MOUSE toggle: switch to mouse layer

Functions

• Hold both the left and right tab to enter tri layer, then you can type function keys.
  • BT 0 to BT 4: select position of bluetooth device you are connecting or want to connect with.
  • BT CLR: clear the connection on selected position, then you can reconnect to this position with your device.
  • OUT TOG: toggle between usb and bluetooth connection, so you can connect up to 6 devices (5 with bluetooth, and 1 with usb)
  • WIN toggle: toggle windows layer, so you can switch between default and windows layer.
  • &studio_unlock: unlock keyboard so that you can use zmk studio to setup keys
  • &soft_off: enter soft off, like deep sleep which enters after an hour of inactivity, but soft off can only be woke up with wake up keys (set to left thumb key: shift)
• Release your tab keys to return to default or windows layer.

Mouse

• hold left tab (to enter left layer), and press space key to enter mouse layer
• press p or q to quit mouse layer
• MB4 is for going backward and MB5 is for going forward

1.2.3 - How to Update Keymaps

There are three methods to update keymaps for NXTKB keyboards. We recommend Method 1 (fork and modify repository) for permanent changes and Method 3 (ZMK Studio) for quick adjustments without re-flashing.

Method 1: Fork and Modify Configuration Repository (Recommended for Permanent Changes)

This method involves forking the official configuration repository, making your changes, and then flashing the updated firmware.

Steps:

1. Fork the appropriate configuration repository:
   • For Ferris Sweep Pro: nxtkb/Sweep-Pro
   • For Ferris Sweep: nxtkb/zmk-config-4-ferris-sweep
2. Modify the keymap files in the repository
3. GitHub Actions will automatically compile the firmware
4. Flash the new firmware to your keyboard

Note: This method requires re-flashing the firmware after making changes, but provides full control over your configuration and is ideal for permanent keymap changes. For detailed instructions on flashing firmware, see How to Flash a Firmware.

Method 2: ZMK Studio (Recommended for Quick Adjustments)

ZMK Studio allows you to modify keymaps and store them directly on your keyboard without needing to re-flash the firmware.

Steps:

1. Visit ZMK Studio
2. Connect your keyboard via Bluetooth
3. Make your desired keymap modifications
4. Save the changes directly to your keyboard’s storage

Note: This method does not require firmware re-flashing, making it ideal for quick adjustments, testing, and temporary configurations.

Method 3: Keyboard Editor with Forked Repository (Alternative Approach)

This method uses the Keyboard Editor integrated with your forked repository for a more streamlined workflow.

Steps:

1. Fork the appropriate configuration repository:
   • For Ferris Sweep Pro: nxtkb/Sweep-Pro
   • For Ferris Sweep: nxtkb/zmk-config-4-ferris-sweep
2. Open the Keyboard Editor
3. In the Keyboard Editor, connect to your forked repository:
   • Click “GitHub” → “Connect to GitHub”
   • Authorize the editor to access your forked repository
   • Select your forked repository and the appropriate keymap file
4. Make your desired keymap modifications in the editor interface
5. Save changes - the editor will automatically:
   • Commit the changes to your forked repository
   • Push the commit to GitHub
   • Trigger the GitHub Actions workflow to build the new firmware
6. Once the build completes, download the firmware files from the GitHub Actions artifacts
7. Flash the new firmware to your keyboard

Note: This method still requires re-flashing the firmware after modifying the keymap, and has some limitations:

• The Keyboard Editor may not recognize all ZMK-specific features, custom macros, or advanced key behaviors
• Some existing key definitions might be lost or misinterpreted during the editing process
• For complex configurations, Method 1 (direct repository editing) is more reliable
• For detailed instructions on flashing firmware, see How to Flash a Firmware.

2 - Firmware

2.1 - How to Flash a Firmware

Flashing firmware is required when you make changes to your keyboard’s configuration files (such as keymaps, features, or device settings) that cannot be updated dynamically. This guide covers the complete process for flashing firmware to NXTKB keyboards.

When to Flash Firmware

You need to flash firmware when:

• You’ve modified keymap files in your configuration repository
• You’ve updated configuration files (e.g., sweep.conf)
• You need to reset Bluetooth pairing information or other stored information (like keymap updated from zmk studio)

Note: If you only need to change your keymap, consider using ZMK Studio instead, which allows keymap updates without firmware re-flashing.

Steps to Flash Firmware

1. Obtain Firmware Files

You can get firmware files through two methods:

Option A: From GitHub Actions (Recommended)

• After pushing changes to your forked configuration repository
• GitHub Actions will automatically build the firmware
• Download the .uf2 files from the workflow artifacts

Option B: From Official Releases

• Download pre-built firmware from the official repository releases:
  • Sweep-Pro Releases
  • zmk-config-4-ferris-sweep Releases

Option C: Build Your Own

• See Build Your Own Firmware for custom builds

2. Connect Your Keyboard Half with USB

1. Connect either the left or right half of your keyboard to your computer using a USB-C cable
2. for most changes (like keymap update), you only need to flash you main (left) half of keyboard.

3. Enter Bootloader Mode

Enter bootloader mode on the half you want to flash:

• Method 1: Press the &bootloader key (requires keyboard to be connected to a device for typing)
• Method 2: Double-click the physical reset button on the keyboard
• Method 3: If the reset button is not working, quickly short-circuit the reset button twice
• Method 4: As a last resort, quickly short-circuit the GND & RST pins of the controller twice (top left corner, second and third pins)

Note: When the keyboard enters bootloader mode, it will appear as a removable drive named “NICENANO” or similar.

4. Flash the Firmware

1. Once in bootloader mode, the keyboard will appear as a removable drive

2. Copy the appropriate .uf2 file to the drive:

   • xxx-left-xxx.uf2 → for the left half
   • xxx-right-xxx.uf2 → for the right half
   • xxx-reset-xxx.uf2 → for both halves. to clear Bluetooth pairing information (use when halves won’t connect)

3. The keyboard will automatically reboot after the file is copied

4. Repeat for the other half if needed

Version History

Check back regularly for new features and improvements to the firmware flashing process.

2.2 - Build your own firmware

Composing…