The Clueboard is one of the officially supported keyboards in QMK. If you want to customize the firmware for your Clueboard you should start there.
All of the layouts that ship with QMK are provided as ready to flash hex files. You can browse the QMK.fm site to view and download the available layouts.
How To Enter Programming Mode
Getting your Clueboard into the "programming" or "bootloader" mode is easy. By default you can press
Fn+S+R to flash your Clueboard. If you are not able to use that for some reason you can also use the
RESET button on the bottom of your PCB. If you have an Alumunium case this is the button that is exposed next to one of the screw holes.
Fn+S+Ron the Keyboard
- Press RESET on the bottom of the PCB
Flashing A Firmware File (Windows and Mac)
Use the QMK Firmware Flasher to flash your Clueboard:
Flashing A Firmware File (Advanced Users)
If you install
dfu-programmer you can build and flash your firmware in one step. This is done by default if you follow the Mac and Linux directions below. To flash your firmware add
-dfu to your make target at compile time.
Make sure to enter programming mode after you press enter.
Building Your Own Firmware
If the layouts available on the QMK.fm site do not meet your needs, or you need to enable options that aren't enabled by default, you may setup your own build environment. If you are already familiar with QMK you can dive straight in:
Building a firmware requires using a terminal and running shell commands. If you have not done any work in the terminal before, or you have but still find it daunting, don't worry. You can always ask us for help if you get stuck!
Build Setup (Windows)
Build Setup (Mac)
Thanks to Homebrew setting up a build environment is easy. Start by installing Homebrew (if it's not already installed) and then run the following commands:
brew tap osx-cross/avr
brew install avr-libc
brew install dfu-programmer
git clone https://github.com/qmk/qmk_firmware.git
Leave this Terminal window open, you will use it in the next step.
You will also need a text editor that can save files as Plain Text. If you do not yet have one installed you should download and install TextMate. Use this program whenever you need to edit a source code file.
Build Setup (Debian Linux)
These instructions assume you are using Debian, or a Debian derivitive like Ubuntu. If you are using another distribution you will have to follow the QMK instructions.
install_depedencies.sh script to install all neccesary software:
git clone https://github.com/qmk/qmk_firmware.git
sudo util/install_dependencies.sh# Note: This will run
Create Your Own Keymap
In the previous step you setup your build environment. Now we will create a customized keymap. You should still have your terminal open from the previous step, so let's continue there.
Create a copy of the default keymap
Start by making a copy of the default keymap:
cp -R keyboards/clueboard/keymaps/default keyboards/clueboard/keymaps/my_keymap
You may use any name you like instead of
my_keymap. To avoid confusing the development environment you should keep your name short and avoid spaces, capital letters, and special characters. Whenever you see
my_keymap in these instructions you should replace it with the name you have chosen here.
Edit your keymap
Navigate to your keymap folder and open the
Windows Hint: Use "
start keyboards/clueboard/keymaps/my_keymap" to open an explorer window. Then right click the
keymap.cfile and open with Notepad.
Mac Hint: Use "
open keyboards/clueboard/keymaps/my_keymap" to open a finder window. Then right click or Control click the
Open With... TextMate.
Be careful as you make changes inside this file. The complier is very picky about the format, and adding or removing a comma, backslash, or other punctuation could create difficult to troubleshoot problems.
QMK provides a lot of documentation to help you edit this file. You should consult it as you make your changes:
Compile Your Keymap into a Firmware
Once you have prepared your
keymap.c file you can build a firmware file:
You will get a lot of output from the compiler and if it was successful you should see something like this:
Size after: text data bss dec hex filename 0 22622 0 22622 585e clueboard_rev2_my_keymap.hex
If you do not see this you can examine the compiler output to see where the problem lies. If you can't figure out what your problem is you can always ask us for help.
Contribute Your Keymap To The Community
Help the community learn from your work! Contribute your keymap back to QMK and others will be able to use your layout and benefit from your ideas. There are two ways to do this:
- Submit a Pull Request to the QMK repository.
- Email your
keymap.cto email@example.com and we will do the necessary work for you. Please make sure the following information is included:
- Keymap Name
- http://keyboard-layout-editor.com/ "Raw Code" for your layout
- How you'd like to be credited
We've listed some common problems and their solution below.
MS Windows Build Problems
We've experienced a number of problems building and flashing on Windows, particularly Windows 10. If you don't have a computer you can run Linux on, there are several workarounds:
- Install Linux in a VM, attach the USB device for your keyboard to this VM
- Email your keymap.c to firstname.lastname@example.org and ask us to compile it for you
MS Windows Flashing Problems
Some people have had difficulty getting their Clueboard to flash for the first time. So far it's always been due to a missing driver for the ATm32U4 device (the processor that powers the Clueboard.)
- Install qmk_firmware_flasher
- During installation you should be prompted to install a driver
- If you are not prompted to install the driver, check to Device Manager to see if the ATm32U4 device has a driver installed
- If not, manually install the driver found in
C:\Program Files\QMK Firmware Flasher\dfu\dfu-prog-usb-1.2.2