keyboard/planck/PCB_GUIDE.md

   1 # Planck Firmware Guide
   2
   3 ## Setting up the environment
   4
   5 ### Windows
   6 1. Install [MHV AVR Tools][mhv] for AVR GCC compiler and [Cygwin][cygwin](or [MinGW][mingw]) for shell terminal.
   7 2. Install [DFU-Programmer][dfu-prog] (the -win one).
   8 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.
   9
  10 ### Mac
  11 1. Install [CrossPack](https://www.obdev.at/downloads/crosspack/CrossPack-AVR-20131216.dmg).
  12 2. Install [DFU-Programmer][dfu-prog].
  13
  14 ### Linux
  15 1. Install AVR GCC with your favorite package manager.
  16 2. Install [DFU-Programmer][dfu-prog].
  17
  18 ##Verify Your Installation
  19 1. Clone the following repository: https://github.com/jackhumbert/tmk_keyboard
  20 2. Open a Terminal and `cd` into `tmk_keyboard/keyboard/planck`
  21 3. Run `make`. This should output a lot of information about the build process.
  22
  23 ## Using the built-in functions
  24
  25 Here is a list of some of the functions avaiable from the command line:
  26
  27 * `make clean`: clean the environment - may be required in-between builds
  28 * `make`: compile the code
  29 * `make COMMON=true`: compile with the common (non-extended) keymap
  30 * `make KEYMAP=<keymap>`: compile with the extended keymap file `extended_keymaps_extended_keymap_<keymap>.c`
  31 * `make COMMON=true KEYMAP=<keymap>`: compile with the common keymap file `common_keymaps/keymap_<keymap>.c`
  32 * `make dfu`: build and flash the layout to the PCB
  33 * `make dfu-force`: build and force-flash the layout to the PCB (may be require for first flash)
  34
  35 Generally, the instructions to flash the PCB are as follows:
  36
  37 1. Make changes to the appropriate keymap file
  38 2. Save the file
  39 3. `make clean`
  40 4. Press the reset button on the PCB/press the key with the `RESET` keycode
  41 5. `make <arguments> dfu` - use the necessary `KEYMAP=<keymap>` and/or `COMMON=true` arguments here.
  42
  43 ## Extended keymap
  44
  45 ### Keymap
  46
  47 Unlike the common keymap, prefixing the keycodes with `KC_` is required. A full list of the keycodes is available [here](https://github.com/jackhumbert/tmk_keyboard/blob/master/doc/keycode.txt). For the keycodes available only in the extended keymap, see this [header file](https://github.com/jackhumbert/tmk_keyboard/blob/master/keyboard/planck/extended_keymap_common.h).
  48
  49 You can use modifiers with keycodes like this:
  50
  51     LCTL(KC_C)
  52
  53 Which will generate Ctrl+c. These are daisy-chainable, meaning you can do things like:
  54
  55     LCTL(LALT(KC_C))
  56
  57 That will generate Ctrl+Alt+c. The entire list of these functions is here:
  58
  59 * `LCTL()`: Left control
  60 * `LSFT()` / `S()`: Left shift
  61 * `LALT()`: Left alt/opt
  62 * `LGUI()`: Left win/cmd
  63 * `RCTL()`: Right control
  64 * `RSFT()`: Right shift
  65 * `RALT()`: Right alt/opt
  66 * `RGUI()`: Right win/cmd
  67
  68 `S(KC_1)`-like entries are useful in writing keymaps for the Planck.
  69
  70 ### Other keycodes
  71
  72 A number of other keycodes have been added that you may find useful:
  73
  74 * `CM_<key>`: the Colemak equivalent of a key (in place of `KC_<key>`), when using Colemak in software (`CM_O` generates `KC_SCLN`)
  75 * `RESET`: jump to bootloader for flashing (same as press the reset button)
  76 * `BL_STEP`: step through the backlight brightnesses
  77 * `BL_<0-15>`: set backlight brightness to 0-15
  78 * `BL_DEC`: lower the backlight brightness
  79 * `BL_INC`: raise the backlight brightness
  80 * `BL_TOGG`: toggle the backlight on/off
  81
  82 ### Function layers
  83
  84 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 avaiable, but limited to `FN0`-`FN31`), you can use the `FUNC(<num>)` notation. `F(<num>)` is a shortcut for this.
  85
  86 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).
  87
  88 ### Macros
  89
  90 Macros have been setup in the `extended_keymaps/extended_keymaps_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)`):
  91
  92     switch(id) {
  93       case 0:
  94         return MACRODOWN(TYPE(KC_A), END);
  95         break;
  96       case 1:
  97         return MACRODOWN(TYPE(KC_B), END);
  98         break;
  99       case 2:
 100         return MACRODOWN(TYPE(KC_C), END);
 101         break;
 102       case 3:
 103         return MACRODOWN(TYPE(KC_D), END);
 104         break;
 105     }
 106     return MACRO_NONE;
 107
 108 `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.
 109
 110 [cygwin]:       https://www.cygwin.com/
 111 [mingw]:        http://www.mingw.org/
 112 [mhv]:          https://infernoembedded.com/products/avr-tools
 113 [winavr]:       http://winavr.sourceforge.net/
 114 [crosspack]:    http://www.obdev.at/products/crosspack/index.html
 115 [dfu-prog]:     http://dfu-programmer.sourceforge.net/