docs/PCB_GUIDE.md

   1 # Planck Firmware Guide
   2
   3 ## Setting up the environment
   4
   5 ### Windows
   6 1. Install [MHV AVR Tools](https://infernoembedded.com/sites/default/files/project/MHV_AVR_Tools_20131101.exe). Disable smatch, but **be sure to leave the option to add the tools to the PATH checked**.
   7 2. Install [MinGW](https://sourceforge.net/projects/mingw/files/Installer/mingw-get-setup.exe/download). During installation, uncheck the option to install a graphical user interface. **DO NOT change the default installation folder.** The scripts depend on the default location.
   8 3. Clone this repository. [This link will download it as a zip file, which you'll need to extract.](https://github.com/qmk/qmk_firmware/archive/master.zip) Open the extracted folder in Windows Explorer.
   9 4. Right-click on the 1-setup-path-win batch script, select "Run as administrator", and accept the User Account Control prompt. Press the spacebar to dismiss the success message in the command prompt that pops up.
  10 5. Right-click on the 2-setup-environment-win batch script, select "Run as administrator", and accept the User Account Control prompt. This part may take a couple of minutes, and you'll need to approve a driver installation, but once it finishes, your environment is complete!
  11
  12
  13 ### Mac
  14
  15 If you're using homebrew, you can use the following commands:
  16
  17     brew tap osx-cross/avr
  18     brew install avr-libc
  19     brew install dfu-programmer
  20
  21 Otherwise, these instructions will work:
  22
  23 1. Install Xcode from the App Store.
  24 2. Install the Command Line Tools from `Xcode->Preferences->Downloads`.
  25 3. Install [DFU-Programmer][dfu-prog].
  26
  27 ### Linux
  28 1. Install AVR GCC with your favorite package manager.
  29 2. Install [DFU-Programmer][dfu-prog].
  30
  31 Note that, since it will be directly accessing USB hardware, the
  32 `dfu-programmer` program needs to be run as root.
  33
  34 ## Verify Your Installation
  35 1. Clone the following repository: https://github.com/qmk/qmk_firmware
  36 2. Open a Terminal and `cd` into `qmk_firmware/keyboards/planck`
  37 3. Run `make`. This should output a lot of information about the build process.
  38
  39 ## Using the built-in functions
  40
  41 Here is a list of some of the functions available from the command line:
  42
  43 * `make clean`: clean the environment - may be required in-between builds
  44 * `make`: compile the code
  45 * `make KEYMAP=<keymap>`: compile with the extended keymap file `extended_keymaps/extended_keymap_<keymap>.c`
  46 * `make dfu`: build and flash the layout to the PCB
  47 * `make dfu-force`: build and force-flash the layout to the PCB (may be require for first flash)
  48
  49 Generally, the instructions to flash the PCB are as follows:
  50
  51 1. Make changes to the appropriate keymap file
  52 2. Save the file
  53 3. `make clean`
  54 4. Press the reset button on the PCB/press the key with the `RESET` keycode
  55 5. `make <arguments> dfu` - use the necessary `KEYMAP=<keymap>` and/or `COMMON=true` arguments here.
  56
  57 ## Troubleshooting
  58 If you see something like this
  59
  60           0 [main] sh 13384 sync_with_child: child 9716(0x178) died before initialization with status code 0xC0000142
  61         440 [main] sh 13384 sync_with_child: *** child state waiting for longjmp
  62     /usr/bin/sh: fork: Resource temporarily unavailable
  63
  64 after running 'make' on Windows than you are encountering a very popular issue with WinAVR on Windows 8.1 and 10.
  65 You can easily fix this problem by replacing msys-1.0.dll in WinAVR/utils/bin with [this one](http://www.madwizard.org/download/electronics/msys-1.0-vista64.zip).
  66 Restart your system and everything should work fine!
  67
  68
  69 If you see this
  70
  71     dfu-programmer atmega32u4 erase
  72     process_begin: CreateProcess(NULL, dfu-programmer atmega32u4 erase, ...) failed.
  73     make (e=2): The system cannot find the file specified.
  74     make: *** [dfu] Error 2
  75
  76 when trying to 'make dfu' on Windows you need to copy the dfu-programmer.exe to qmk_firmware/keyboards/planck.
  77
  78
  79 ## Quantum MK Firmware
  80
  81 ### Keymap
  82
  83 Unlike the other keymaps, prefixing the keycodes with `KC_` is required. A full list of the keycodes is available [here](https://github.com/qmk/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/qmk/qmk_firmware/blob/master/quantum/keymap_common.h).
  84
  85 You can use modifiers with keycodes like this:
  86
  87     LCTL(KC_C)
  88
  89 Which will generate Ctrl+c. These are daisy-chainable, meaning you can do things like:
  90
  91     LCTL(LALT(KC_C))
  92
  93 That will generate Ctrl+Alt+c. The entire list of these functions is here:
  94
  95 * `LCTL()`: Left control
  96 * `LSFT()` / `S()`: Left shift
  97 * `LALT()`: Left alt/opt
  98 * `LGUI()`: Left win/cmd
  99 * `RCTL()`: Right control
 100 * `RSFT()`: Right shift
 101 * `RALT()`: Right alt/opt
 102 * `RGUI()`: Right win/cmd
 103
 104 `S(KC_1)`-like entries are useful in writing keymaps for the Planck.
 105
 106 ### Other keycodes
 107
 108 A number of other keycodes have been added that you may find useful:
 109
 110 * `CM_<key>`: the Colemak equivalent of a key (in place of `KC_<key>`), when using Colemak in software (`CM_O` generates `KC_SCLN`)
 111 * `RESET`: jump to bootloader for flashing (same as press the reset button)
 112 * `BL_STEP`: step through the backlight brightnesses
 113 * `BL_<0-15>`: set backlight brightness to 0-15
 114 * `BL_DEC`: lower the backlight brightness
 115 * `BL_INC`: raise the backlight brightness
 116 * `BL_TOGG`: toggle the backlight on/off
 117
 118 ### Function layers
 119
 120 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.
 121
 122 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).
 123
 124 ### Macros
 125
 126 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)`):
 127
 128     switch(id) {
 129       case 0:
 130         return MACRODOWN(TYPE(KC_A), END);
 131         break;
 132       case 1:
 133         return MACRODOWN(TYPE(KC_B), END);
 134         break;
 135       case 2:
 136         return MACRODOWN(TYPE(KC_C), END);
 137         break;
 138       case 3:
 139         return MACRODOWN(TYPE(KC_D), END);
 140         break;
 141     }
 142     return MACRO_NONE;
 143
 144 `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.
 145
 146 [cygwin]:       https://www.cygwin.com/
 147 [mingw]:        http://www.mingw.org/
 148 [mhv]:          https://infernoembedded.com/products/avr-tools
 149 [winavr]:       http://winavr.sourceforge.net/
 150 [crosspack]:    http://www.obdev.at/products/crosspack/index.html
 151 [dfu-prog]:     http://dfu-programmer.sourceforge.net/