Keyboard Programming

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.

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.

  • Press Fn+S+R on 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.

Example:

  • make clueboard-my_layout-dfu

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:

Build Setup

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)

TBD

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
  • cd qmk_firmware

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.

Use the install_depedencies.sh script to install all neccesary software:

  • git clone https://github.com/qmk/qmk_firmware.git
  • cd qmk_firmware
  • sudo util/install_dependencies.sh   # Note: This will run apt-get upgrade!

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 keymap.c file.

Windows Hint: Use "start keyboards/clueboard/keymaps/my_keymap" to open an explorer window. Then right click the keymap.c file 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 keymap.c file to 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:

  • make clueboard-my_keymap

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:

Common Problems

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 info@clueboard.co 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.)

  1. Install qmk_firmware_flasher
  2. During installation you should be prompted to install a driver
  3. If you are not prompted to install the driver, check to Device Manager to see if the ATm32U4 device has a driver installed
  4. If not, manually install the driver found in C:\Program Files\QMK Firmware Flasher\dfu\dfu-prog-usb-1.2.2