lxndio

Journal of my ideas, thoughts and projects.


Programming your Planck keyboard #1 - Setting up the environment & Writing a macro

This is the first article on how to program your Planck keyboard. Firstly, this article has been entirely written on a Planck keyboard.
Usually Planck keyboards run the Quantum Firmware which I can absolutely recommend.

Update: This guide has been updated on the 15 of August 2017 to use the new Windows Subsystem for Linux instead of Cygwin.

Setting up the environment

Setting up the environment to start modifying the firmware is easy:

  1. Download the sources using the Git tool or by downloading the .zip file of GitHub (click on the bold Quantum above).
  2. On Linux install the following packages via the package manager: gcc-avr avr-libc dfu-programmer.
  3. On Windows install the Windows Subsystem for Linux (click for a guide on how to install WSL). After that, start Bash on Ubuntu on Windows and navigate to the firmware directory (see the tip below). Run util/wsl_install.sh and follow the instructions.
  4. Navigate to the folder keyboards/planck/keymaps/ inside the firmware directory and copy the default folder and name it as you like. This is the folder we are going to be working in.

Tip: All paths in Bash on Ubuntu on Windows are Linux paths. Your Windows filesystem is located at /mnt/. For example, the Windows path C:\Users\username\Desktop becomes /mnt/c/Users/username/Desktop/.

Writing a macro

Open the keymap.c file in the folder you've copied in your favorite editor.

At the top of the file right below these lines

#define _QWERTY 0
#define _COLEMAK 1
...

add a new line:

#define MYMACRO M(10)

I usually start with M(10) but you can also start with 1. M(10) in this case is the identifier of the macro. For better readability, we bind this ID to the name MYMACRO.

Now find a layer to which you want to add your macro. I am using the Adjust layer for this macro. In the matrix called _ADJUST add the name MYMACRO at some place where underscores mark a free position. Adding it there tells the keyboard to run your macro when the key you've bound on that layer is pressed.

Now, add a new function below the function called process_record_user:

const macro_t *action_get_macro(keyrecord_t *record, uint8_t id, uint8_t opt) {  
  switch (id) {
    case 10: // MYMACRO
      if (record->event.pressed) {
        return MACRO(D(LALT), T(F4), U(LALT), END);
      }
      break;
  }

  return MACRO_NONE;
}

Because the ID of the macro is 10, the switch will execute the code at case 10. The if-clause below tells the keyboard to only execute the code after the key has been pressed down and released. The macro in this case is typing the key combination ALT+F4. D means down (press the key down), T is type (press and release), U is up (release) and END ends the macro.

Compiling and uploading the firmware

To compile the firmware, browse to the folder you've copied and execute the command make (from Cygwin on Windows). If this command executes without errors you can upload the firmware.

To upload the firmware you first have to erase the firmware which currently is on your keyboard. To do this execute the following command (again Cygwin on Windows):

dfu-programmer atmega32u4 erase  

Change the processor to the processor in your keyboard. Important: If the device doesn't get detected, make sure that your keyboards is in programming mode (press the button on the PCB). Now upload the new file

dfu-programmer atmega32u4 flash fileofyourfirmware.hex  

The .hex file has been created in the folder you are working in. If the command was successful, reconnect your keyboard and try the macro.

Please notice that I can assist you if you have problems (Telegram @lxndio or /u/lxndio on Reddit) but I am not liable for any damages on your keyboard. Also contact me if you find any mistakes ;)

Don't know what to do now? Reading part #2 would be a possibility.

Till then,
lxndio