From a53efa45619ac81f516908a7a16c1e7aaaa04269 Mon Sep 17 00:00:00 2001 From: Jack Humbert Date: Sat, 30 May 2015 13:31:52 -0400 Subject: Create PCB_GUIDE.md --- keyboard/planck/PCB_GUIDE.md | 110 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 110 insertions(+) create mode 100644 keyboard/planck/PCB_GUIDE.md (limited to 'keyboard/planck/PCB_GUIDE.md') diff --git a/keyboard/planck/PCB_GUIDE.md b/keyboard/planck/PCB_GUIDE.md new file mode 100644 index 0000000000..e4c307b44a --- /dev/null +++ b/keyboard/planck/PCB_GUIDE.md @@ -0,0 +1,110 @@ +# Planck Firmware Guide + +## Setting up the environment + +### Windows +1. Install [MHV AVR Tools][mhv] for AVR GCC compiler and [Cygwin][cygwin](or [MinGW][mingw]) for shell terminal. +2. Install [DFU-Programmer][dfu-prog] (the -win one). +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. + +### Mac +1. Install [CrossPack](https://www.obdev.at/downloads/crosspack/CrossPack-AVR-20131216.dmg). +2. Install [DFU-Programmer][dfu-prog]. + +### Linux +1. Install AVR GCC with your favorite package manager. +2. Install [DFU-Programmer][dfu-prog]. + +## Using the built-in functions + +Here is a list of some of the functions avaiable from the command line: + +* `make clean`: clean the environment - may be required in-between builds +* `make`: compile the code +* `make COMMON=true`: compile with the common (non-extended) keymap +* `make KEYMAP=`: compile with the extended keymap file `extended_keymaps_extended_keymap_.c` +* `make COMMON=true KEYMAP=`: compile with the common keymap file `common_keymaps/keymap_.c` +* `make dfu`: build and flash the layout to the PCB +* `make dfu-force`: build and force-flash the layout to the PCB (may be require for first flash) + +Generally, the instructions to flash the PCB are as follows: + +1. Make changes to the appropriate keymap file +2. Save the file +3. `make clean` +4. Press the reset button on the PCB/press the key with the `RESET` keycode +5. `make dfu` - use the necessary `KEYMAP=` or `COMMON=true` here. + +## Extended keymap + +### Keymap + +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). + +You can use modifiers with keycodes like this: + + LCTL(KC_C) + +Which will generate Ctrl+c. These are daisy-chainable, meaning you can do things like: + + LCTL(LALT(KC_C)) + +That will generate Ctrl+Alt+c. The entire list of these functions is here: + +* `LCTL()`: Left control +* `LSFT()` / `S()`: Left shift +* `LALT()`: Left alt/opt +* `LGUI()`: Left win/cmd +* `RCTL()`: Right control +* `RSFT()`: Right shift +* `RALT()`: Right alt/opt +* `RGUI()`: Right win/cmd + +`S(KC_1)`-like entries are useful in writing keymaps for the Planck. + +### Other keycodes + +A number of other keycodes have been added that you may find useful: + +* `CM_`: the Colemak equivalent of a key (in place of `KC_`), when using Colemak in software (`CM_O` generates `KC_SCLN`) +* `RESET`: jump to bootloader for flashing (same as press the reset button) +* `BL_STEP`: step through the backlight brightnesses +* `BL_<0-15>`: set backlight brightness to 0-15 +* `BL_DEC`: lower the backlight brightness +* `BL_INC`: raise the backlight brightness +* `BL_TOGG`: toggle the backlight on/off + +### Function layers + +The extended keymap extends the number of function layers from 32 to the near-infinite value of 256. Rather than using `FN` notation (still avaiable, but limited to `FN0`-`FN31`), you can use the `FUNC()` notation. `F()` is a shortcut for this. + +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). + +### Macros + +Macros have been setup in the `extended_keymaps/extended_keymaps_default.c` file so that you can use `M()` 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)`): + + switch(id) { + case 0: + return MACRODOWN(TYPE(KC_A), END); + break; + case 1: + return MACRODOWN(TYPE(KC_B), END); + break; + case 2: + return MACRODOWN(TYPE(KC_C), END); + break; + case 3: + return MACRODOWN(TYPE(KC_D), END); + break; + } + return MACRO_NONE; + +`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. + +[cygwin]: https://www.cygwin.com/ +[mingw]: http://www.mingw.org/ +[mhv]: https://infernoembedded.com/products/avr-tools +[winavr]: http://winavr.sourceforge.net/ +[crosspack]: http://www.obdev.at/products/crosspack/index.html +[dfu-prog]: http://dfu-programmer.sourceforge.net/ -- cgit v1.2.3 From 68f48fcc58a44727a9da02c861b14ab20bb2c68e Mon Sep 17 00:00:00 2001 From: Jack Humbert Date: Sat, 30 May 2015 15:47:21 -0400 Subject: guide --- keyboard/planck/PCB_GUIDE.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'keyboard/planck/PCB_GUIDE.md') diff --git a/keyboard/planck/PCB_GUIDE.md b/keyboard/planck/PCB_GUIDE.md index e4c307b44a..833e144b3b 100644 --- a/keyboard/planck/PCB_GUIDE.md +++ b/keyboard/planck/PCB_GUIDE.md @@ -33,7 +33,7 @@ Generally, the instructions to flash the PCB are as follows: 2. Save the file 3. `make clean` 4. Press the reset button on the PCB/press the key with the `RESET` keycode -5. `make dfu` - use the necessary `KEYMAP=` or `COMMON=true` here. +5. `make dfu` - use the necessary `KEYMAP=` and/or `COMMON=true` arguments here. ## Extended keymap -- cgit v1.2.3 From af4f016b4fe52b7f53d5789cadc9449ab0c96fab Mon Sep 17 00:00:00 2001 From: John Lindquist Date: Mon, 1 Jun 2015 15:55:34 -0600 Subject: Update PCB_GUIDE.md --- keyboard/planck/PCB_GUIDE.md | 5 +++++ 1 file changed, 5 insertions(+) (limited to 'keyboard/planck/PCB_GUIDE.md') diff --git a/keyboard/planck/PCB_GUIDE.md b/keyboard/planck/PCB_GUIDE.md index 833e144b3b..f757407463 100644 --- a/keyboard/planck/PCB_GUIDE.md +++ b/keyboard/planck/PCB_GUIDE.md @@ -15,6 +15,11 @@ 1. Install AVR GCC with your favorite package manager. 2. Install [DFU-Programmer][dfu-prog]. +##Verify Your Installation +1. Clone the following repository: https://github.com/jackhumbert/tmk_keyboard +2. Open a Terminal and `cd` into `tmk_keyboard/keyboard/planck` +3. Run `make`. This should output a lot of information about the build process. + ## Using the built-in functions Here is a list of some of the functions avaiable from the command line: -- cgit v1.2.3 From bcb04570eaf80d3eeb89d79dec9336b47d65d622 Mon Sep 17 00:00:00 2001 From: cr3473 Date: Tue, 2 Jun 2015 13:58:45 -0700 Subject: PCB Guide edits and update to joe's keymap --- keyboard/planck/PCB_GUIDE.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) (limited to 'keyboard/planck/PCB_GUIDE.md') diff --git a/keyboard/planck/PCB_GUIDE.md b/keyboard/planck/PCB_GUIDE.md index f757407463..efe960abbf 100644 --- a/keyboard/planck/PCB_GUIDE.md +++ b/keyboard/planck/PCB_GUIDE.md @@ -22,12 +22,13 @@ ## Using the built-in functions -Here is a list of some of the functions avaiable from the command line: +Here is a list of some of the functions available from the command line: * `make clean`: clean the environment - may be required in-between builds * `make`: compile the code * `make COMMON=true`: compile with the common (non-extended) keymap -* `make KEYMAP=`: compile with the extended keymap file `extended_keymaps_extended_keymap_.c` +* `make MATRIX=`: compile with the referenced matrix file. Default if unspecified is `matrix_pcb.c`. For handwired boards, use `matrix_handwired.c`. +* `make KEYMAP=`: compile with the extended keymap file `extended_keymaps/extended_keymap_.c` * `make COMMON=true KEYMAP=`: compile with the common keymap file `common_keymaps/keymap_.c` * `make dfu`: build and flash the layout to the PCB * `make dfu-force`: build and force-flash the layout to the PCB (may be require for first flash) @@ -81,7 +82,7 @@ A number of other keycodes have been added that you may find useful: ### Function layers -The extended keymap extends the number of function layers from 32 to the near-infinite value of 256. Rather than using `FN` notation (still avaiable, but limited to `FN0`-`FN31`), you can use the `FUNC()` notation. `F()` is a shortcut for this. +The extended keymap extends the number of function layers from 32 to the near-infinite value of 256. Rather than using `FN` notation (still available, but limited to `FN0`-`FN31`), you can use the `FUNC()` notation. `F()` is a shortcut for this. 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). -- cgit v1.2.3 From ae2e7fdf26f9d26678bbe746ac3f1d4d076dd8e9 Mon Sep 17 00:00:00 2001 From: Jack Humbert Date: Sun, 7 Jun 2015 13:40:11 -0400 Subject: Update PCB_GUIDE.md --- keyboard/planck/PCB_GUIDE.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'keyboard/planck/PCB_GUIDE.md') diff --git a/keyboard/planck/PCB_GUIDE.md b/keyboard/planck/PCB_GUIDE.md index efe960abbf..59fc65bd08 100644 --- a/keyboard/planck/PCB_GUIDE.md +++ b/keyboard/planck/PCB_GUIDE.md @@ -3,12 +3,12 @@ ## Setting up the environment ### Windows -1. Install [MHV AVR Tools][mhv] for AVR GCC compiler and [Cygwin][cygwin](or [MinGW][mingw]) for shell terminal. +1. Install [WinAVR Tools](http://sourceforge.net/projects/winavr/) for AVR GCC compiler. 2. Install [DFU-Programmer][dfu-prog] (the -win one). 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. ### Mac -1. Install [CrossPack](https://www.obdev.at/downloads/crosspack/CrossPack-AVR-20131216.dmg). +1. Install [CrossPack](http://www.obdev.at/products/crosspack/index.html) or install Xcode from the App Store. 2. Install [DFU-Programmer][dfu-prog]. ### Linux -- cgit v1.2.3 From e12c0de608be5b3239222735bb6403e0fda3fb26 Mon Sep 17 00:00:00 2001 From: Jack Humbert Date: Mon, 3 Aug 2015 14:19:24 -0400 Subject: Update PCB_GUIDE.md --- keyboard/planck/PCB_GUIDE.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'keyboard/planck/PCB_GUIDE.md') diff --git a/keyboard/planck/PCB_GUIDE.md b/keyboard/planck/PCB_GUIDE.md index 59fc65bd08..c3004c75a4 100644 --- a/keyboard/planck/PCB_GUIDE.md +++ b/keyboard/planck/PCB_GUIDE.md @@ -8,7 +8,7 @@ 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. ### Mac -1. Install [CrossPack](http://www.obdev.at/products/crosspack/index.html) or install Xcode from the App Store. +1. Install [CrossPack](http://www.obdev.at/products/crosspack/index.html) or install Xcode from the App Store and install the Command Line Tools from `Xcode->Preferences->Downloads`. 2. Install [DFU-Programmer][dfu-prog]. ### Linux -- cgit v1.2.3