keyboard/planck/PCB_GUIDE.md

   1 # Planck Firmware Guide
   2
   3 ## Setting up the environment
   4
   5 ### Windows
   6
   7 1. Install [WinAVR Tools](http://sourceforge.net/projects/winavr/) for AVR GCC compiler.
   8 2. Install [DFU-Programmer][dfu-prog] (the -win one).
   9 3. Start DFU bootloader on the chip first time you will see 'Found New Hardware Wizard' to install driver. If you install device driver properly you can find chip name like 'ATmega32U4' under 'LibUSB-Win32 Devices' tree on 'Device Manager'. If not you will need to update its driver on 'Device Manager' to the `dfu-programmer` driver.
  10
  11 ### Mac
  12
  13 If you're using homebrew, you can use the following commands:
  14
  15     brew tap osx-cross/avr
  16     brew install avr-libc
  17     brew install dfu-programmer
  18
  19 Otherwise, these instructions will work:
  20
  21 1. Install Xcode from the App Store.
  22 2. Install the Command Line Tools from `Xcode->Preferences->Downloads`.
  23 3. Install [DFU-Programmer][dfu-prog].
  24
  25 ### Linux
  26 1. Install AVR GCC with your favorite package manager.
  27 2. Install [DFU-Programmer][dfu-prog].
  28
  29 Note that, since it will be directly accessing USB hardware, the
  30 `dfu-programmer` program needs to be run as root.
  31
  32 ## Verify Your Installation
  33 1. Clone the following repository: https://github.com/jackhumbert/qmk_firmware
  34 2. Open a Terminal and `cd` into `qmk_firmware/keyboard/planck`
  35 3. Run `make`. This should output a lot of information about the build process.
  36
  37 ## Using the built-in functions
  38
  39 Here is a list of some of the functions available from the command line:
  40
  41 * `make clean`: clean the environment - may be required in-between builds
  42 * `make`: compile the code
  43 * `make KEYMAP=<keymap>`: compile with the extended keymap file `extended_keymaps/extended_keymap_<keymap>.c`
  44 * `make dfu`: build and flash the layout to the PCB
  45 * `make dfu-force`: build and force-flash the layout to the PCB (may be require for first flash)
  46
  47 Generally, the instructions to flash the PCB are as follows:
  48
  49 1. Make changes to the appropriate keymap file
  50 2. Save the file
  51 3. `make clean`
  52 4. Press the reset button on the PCB/press the key with the `RESET` keycode
  53 5. `make <arguments> dfu` - use the necessary `KEYMAP=<keymap>` and/or `COMMON=true` arguments here.
  54
  55 ## Quantum MK Firmware
  56
  57 ### Keymap
  58
  59 Unlike the other keymaps, prefixing the keycodes with `KC_` is required. A full list of the keycodes is available [here](https://github.com/jackhumbert/qmk_firmware/blob/master/tmk_core/doc/keycode.txt). For the keycodes available only in the extended keymap, see this [header file](https://github.com/jackhumbert/qmk_firmware/blob/master/quantum/keymap_common.h).
  60
  61 You can use modifiers with keycodes like this:
  62
  63     LCTL(KC_C)
  64
  65 Which will generate Ctrl+c. These are daisy-chainable, meaning you can do things like:
  66
  67     LCTL(LALT(KC_C))
  68
  69 That will generate Ctrl+Alt+c. The entire list of these functions is here:
  70
  71 * `LCTL()`: Left control
  72 * `LSFT()` / `S()`: Left shift
  73 * `LALT()`: Left alt/opt
  74 * `LGUI()`: Left win/cmd
  75 * `RCTL()`: Right control
  76 * `RSFT()`: Right shift
  77 * `RALT()`: Right alt/opt
  78 * `RGUI()`: Right win/cmd
  79
  80 `S(KC_1)`-like entries are useful in writing keymaps for the Planck.
  81
  82 ### Other keycodes
  83
  84 A number of other keycodes have been added that you may find useful:
  85
  86 * `CM_<key>`: the Colemak equivalent of a key (in place of `KC_<key>`), when using Colemak in software (`CM_O` generates `KC_SCLN`)
  87 * `RESET`: jump to bootloader for flashing (same as press the reset button)
  88 * `BL_STEP`: step through the backlight brightnesses
  89 * `BL_<0-15>`: set backlight brightness to 0-15
  90 * `BL_DEC`: lower the backlight brightness
  91 * `BL_INC`: raise the backlight brightness
  92 * `BL_TOGG`: toggle the backlight on/off
  93
  94 ### Function layers
  95
  96 The extended keymap extends the number of function layers from 32 to the near-infinite value of 256. Rather than using `FN<num>` notation (still available, but limited to `FN0`-`FN31`), you can use the `FUNC(<num>)` notation. `F(<num>)` is a shortcut for this.
  97
  98 The function actions are unchanged, and you can see the full list of them [here](https://github.com/jackhumbert/tmk_keyboard/blob/master/common/action_code.h). They are explained in detail [here](https://github.com/jackhumbert/tmk_keyboard/blob/master/doc/keymap.md#2-action).
  99
 100 ### Macros
 101
 102 Macros have been setup in the `keymaps/keymap_default.c` file so that you can use `M(<num>)` to access a macro in the `action_get_macro` section on your keymap. The switch/case structure you see here is required, and is setup for `M(0)` - you'll need to copy and paste the code to look like this (e.g. to support `M(3)`):
 103
 104     switch(id) {
 105       case 0:
 106         return MACRODOWN(TYPE(KC_A), END);
 107         break;
 108       case 1:
 109         return MACRODOWN(TYPE(KC_B), END);
 110         break;
 111       case 2:
 112         return MACRODOWN(TYPE(KC_C), END);
 113         break;
 114       case 3:
 115         return MACRODOWN(TYPE(KC_D), END);
 116         break;
 117     }
 118     return MACRO_NONE;
 119
 120 `MACRODOWN()` is a shortcut for `(record->event.pressed ? MACRO(__VA_ARGS__) : MACRO_NONE)` which tells the macro to execute when the key is pressed. Without this, the macro will be executed on both the down and up stroke.
 121
 122 [cygwin]:       https://www.cygwin.com/
 123 [mingw]:        http://www.mingw.org/
 124 [mhv]:          https://infernoembedded.com/products/avr-tools
 125 [winavr]:       http://winavr.sourceforge.net/
 126 [crosspack]:    http://www.obdev.at/products/crosspack/index.html
 127 [dfu-prog]:     http://dfu-programmer.sourceforge.net/