aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorDrashna Jaelre <drashna@live.com>2019-03-18 14:22:02 -0700
committerMechMerlin <30334081+mechmerlin@users.noreply.github.com>2019-03-18 14:22:02 -0700
commitc534a4c775098f2b6cc8e7f36d35cf642f4323a5 (patch)
treef025c6ade37e4fc6bc930e05fe9a734dd273c974
parent28e182bc8a2976562e0d76a1332527e0a4be81ea (diff)
downloadqmk_firmware-c534a4c775098f2b6cc8e7f36d35cf642f4323a5.tar.gz
qmk_firmware-c534a4c775098f2b6cc8e7f36d35cf642f4323a5.zip
[Docs] Smallish overhaul of the docs (#5281)
* Fix up Common functions doc * Add to extra commands to flashing doc * Rearrange and touch up Macros * Expand Newbs Flashing guide * Update process_record documentation * Add git to best practices name in sidebar * Expand FAQ for build/flashing * Add deprecated info to functions * Update docs/feature_macros.md Co-Authored-By: drashna <drashna@live.com> * Update docs/feature_macros.md Co-Authored-By: drashna <drashna@live.com> * Update docs/flashing.md Co-Authored-By: drashna <drashna@live.com> * Update docs/flashing.md Co-Authored-By: drashna <drashna@live.com> * Update docs/keymap.md Co-Authored-By: drashna <drashna@live.com> * Update docs/newbs_flashing.md Co-Authored-By: drashna <drashna@live.com> * Update docs/newbs_flashing.md Co-Authored-By: drashna <drashna@live.com> * Update docs/custom_quantum_functions.md Co-Authored-By: drashna <drashna@live.com> * Update docs/faq_build.md Co-Authored-By: drashna <drashna@live.com> * Update docs/feature_macros.md Co-Authored-By: drashna <drashna@live.com> * Update docs/keymap.md Co-Authored-By: drashna <drashna@live.com> * Fix up Common functions doc * Make pre-init example accurate * Update docs/custom_quantum_functions.md Co-Authored-By: drashna <drashna@live.com> * Zadig Driver catchall * Spelling Depriciated * Completely remove fn_actions section
-rw-r--r--docs/_summary.md2
-rw-r--r--docs/custom_quantum_functions.md44
-rw-r--r--docs/faq_build.md9
-rw-r--r--docs/feature_macros.md97
-rw-r--r--docs/flashing.md19
-rw-r--r--docs/keymap.md56
-rw-r--r--docs/newbs_flashing.md69
-rw-r--r--docs/understanding_qmk.md2
8 files changed, 172 insertions, 126 deletions
diff --git a/docs/_summary.md b/docs/_summary.md
index df876b794..c9d6c2bb1 100644
--- a/docs/_summary.md
+++ b/docs/_summary.md
@@ -3,7 +3,7 @@
3 * [Building Your First Firmware](newbs_building_firmware.md) 3 * [Building Your First Firmware](newbs_building_firmware.md)
4 * [Flashing Firmware](newbs_flashing.md) 4 * [Flashing Firmware](newbs_flashing.md)
5 * [Testing and Debugging](newbs_testing_debugging.md) 5 * [Testing and Debugging](newbs_testing_debugging.md)
6 * [Best Practices](newbs_best_practices.md) 6 * [Git Best Practices](newbs_best_practices.md)
7 * [Learning Resources](newbs_learn_more_resources.md) 7 * [Learning Resources](newbs_learn_more_resources.md)
8 8
9* [QMK Basics](README.md) 9* [QMK Basics](README.md)
diff --git a/docs/custom_quantum_functions.md b/docs/custom_quantum_functions.md
index f291fc2d2..655fa1578 100644
--- a/docs/custom_quantum_functions.md
+++ b/docs/custom_quantum_functions.md
@@ -116,29 +116,29 @@ Use the `IS_LED_ON(usb_led, led_name)` and `IS_LED_OFF(usb_led, led_name)` macro
116```c 116```c
117void led_set_user(uint8_t usb_led) { 117void led_set_user(uint8_t usb_led) {
118 if (IS_LED_ON(usb_led, USB_LED_NUM_LOCK)) { 118 if (IS_LED_ON(usb_led, USB_LED_NUM_LOCK)) {
119 PORTB |= (1<<0); 119 writePinLow(B0);
120 } else { 120 } else {
121 PORTB &= ~(1<<0); 121 writePinHigh(B0);
122 } 122 }
123 if (IS_LED_ON(usb_led, USB_LED_CAPS_LOCK)) { 123 if (IS_LED_ON(usb_led, USB_LED_CAPS_LOCK)) {
124 PORTB |= (1<<1); 124 writePinLow(B1);
125 } else { 125 } else {
126 PORTB &= ~(1<<1); 126 writePinHigh(B1);
127 } 127 }
128 if (IS_LED_ON(usb_led, USB_LED_SCROLL_LOCK)) { 128 if (IS_LED_ON(usb_led, USB_LED_SCROLL_LOCK)) {
129 PORTB |= (1<<2); 129 writePinLow(B2);
130 } else { 130 } else {
131 PORTB &= ~(1<<2); 131 writePinHigh(B2);
132 } 132 }
133 if (IS_LED_ON(usb_led, USB_LED_COMPOSE)) { 133 if (IS_LED_ON(usb_led, USB_LED_COMPOSE)) {
134 PORTB |= (1<<3); 134 writePinLow(B3);
135 } else { 135 } else {
136 PORTB &= ~(1<<3); 136 writePinHigh(B3);
137 } 137 }
138 if (IS_LED_ON(usb_led, USB_LED_KANA)) { 138 if (IS_LED_ON(usb_led, USB_LED_KANA)) {
139 PORTB |= (1<<4); 139 writePinLow(B4);
140 } else { 140 } else {
141 PORTB &= ~(1<<4); 141 writePinHigh(B4);
142 } 142 }
143} 143}
144``` 144```
@@ -189,16 +189,18 @@ However, if you have hardware stuff that you need initialized, this is the best
189 189
190### Example `keyboard_pre_init_user()` Implementation 190### Example `keyboard_pre_init_user()` Implementation
191 191
192This example, at the keyboard level, sets up B1, B2, and B3 as LED pins. 192This example, at the keyboard level, sets up B0, B1, B2, B3, and B4 as LED pins.
193 193
194```c 194```c
195void keyboard_pre_init_user(void) { 195void keyboard_pre_init_user(void) {
196 // Call the keyboard pre init code. 196 // Call the keyboard pre init code.
197 197
198 // Set our LED pins as output 198 // Set our LED pins as output
199 DDRB |= (1<<1); 199 setPinOutput(B0);
200 DDRB |= (1<<2); 200 setPinOutput(B1);
201 DDRB |= (1<<3); 201 setPinOutput(B2);
202 setPinOutput(B3);
203 setPinOutput(B4);
202} 204}
203``` 205```
204 206
@@ -270,16 +272,13 @@ This is controlled by two functions: `suspend_power_down_*` and `suspend_wakeup_
270 272
271### Example suspend_power_down_user() and suspend_wakeup_init_user() Implementation 273### Example suspend_power_down_user() and suspend_wakeup_init_user() Implementation
272 274
273This example, at the keyboard level, sets up B1, B2, and B3 as LED pins.
274 275
275```c 276```c
276void suspend_power_down_user(void) 277void suspend_power_down_user(void) {
277{
278 rgb_matrix_set_suspend_state(true); 278 rgb_matrix_set_suspend_state(true);
279} 279}
280 280
281void suspend_wakeup_init_user(void) 281void suspend_wakeup_init_user(void) {
282{
283 rgb_matrix_set_suspend_state(false); 282 rgb_matrix_set_suspend_state(false);
284} 283}
285``` 284```
@@ -356,11 +355,11 @@ user_config_t user_config;
356 355
357This sets up a 32 bit structure that we can store settings with in memory, and write to the EEPROM. Using this removes the need to define variables, since they're defined in this structure. Remember that `bool` (boolean) values use 1 bit, `uint8_t` uses 8 bits, `uint16_t` uses up 16 bits. You can mix and match, but changing the order can cause issues, as it will change the values that are read and written. 356This sets up a 32 bit structure that we can store settings with in memory, and write to the EEPROM. Using this removes the need to define variables, since they're defined in this structure. Remember that `bool` (boolean) values use 1 bit, `uint8_t` uses 8 bits, `uint16_t` uses up 16 bits. You can mix and match, but changing the order can cause issues, as it will change the values that are read and written.
358 357
359We're using `rgb_layer_change`, for the `layer_state_set_*` function, and use `matrix_init_user` and `process_record_user` to configure everything. 358We're using `rgb_layer_change`, for the `layer_state_set_*` function, and use `keyboard_post_init_user` and `process_record_user` to configure everything.
360 359
361Now, using the `matrix_init_user` code above, you want to add `eeconfig_read_user()` to it, to populate the structure you've just created. And you can then immediately use this structure to control functionality in your keymap. And It should look like: 360Now, using the `keyboard_post_init_user` code above, you want to add `eeconfig_read_user()` to it, to populate the structure you've just created. And you can then immediately use this structure to control functionality in your keymap. And It should look like:
362``` 361```
363void matrix_init_user(void) { 362void keyboard_post_init_user(void) {
364 // Call the keymap level matrix init. 363 // Call the keymap level matrix init.
365 364
366 // Read the user config from EEPROM 365 // Read the user config from EEPROM
@@ -447,6 +446,7 @@ And lastly, you want to add the `eeconfig_init_user` function, so that when the
447 446
448``` 447```
449void eeconfig_init_user(void) { // EEPROM is getting reset! 448void eeconfig_init_user(void) { // EEPROM is getting reset!
449 user_config.raw = 0;
450 user_config.rgb_layer_change = true; // We want this enabled by default 450 user_config.rgb_layer_change = true; // We want this enabled by default
451 eeconfig_update_user(user_config.raw); // Write default value to EEPROM now 451 eeconfig_update_user(user_config.raw); // Write default value to EEPROM now
452 452
diff --git a/docs/faq_build.md b/docs/faq_build.md
index be26a7c58..45d9439b4 100644
--- a/docs/faq_build.md
+++ b/docs/faq_build.md
@@ -15,7 +15,7 @@ or just:
15 15
16 $ sudo make <keyboard>:<keymap>:dfu 16 $ sudo make <keyboard>:<keymap>:dfu
17 17
18Note that running `make` with `sudo` is generally *not* a good idea, and you should use one of the former methods, if possible. 18Note that running `make` with `sudo` is generally ***not*** a good idea, and you should use one of the former methods, if possible.
19 19
20### Linux `udev` Rules 20### Linux `udev` Rules
21On Linux, you'll need proper privileges to access the MCU. You can either use 21On Linux, you'll need proper privileges to access the MCU. You can either use
@@ -47,7 +47,12 @@ If you're using Windows to flash your keyboard, and you are running into issues,
47 47
48Re-running the installation script for MSYS2 may help (eg run `./util/qmk_install.sh` from MSYS2/WSL) or reinstalling the QMK Toolbox may fix the issue. 48Re-running the installation script for MSYS2 may help (eg run `./util/qmk_install.sh` from MSYS2/WSL) or reinstalling the QMK Toolbox may fix the issue.
49 49
50If that doesn't work, then you may need to grab the [Zadig Utility](https://zadig.akeo.ie/). Download this, find the device in question, and select the `WinUS(libusb-1.0)` option, and hit "Reinstall driver". Once you've done that, try flashing your board, again. 50If that doesn't work, then you may need to grab the [Zadig Utility](https://zadig.akeo.ie/). Download this, find the device in question, and select the `WinUSB` option, and hit "Reinstall driver". Once you've done that, try flashing your board, again. If that doesn't work, try all of the options, until one works.
51
52?> There isn't a best option for which driver should be used here. Some options work better on some systems than others. libUSB and WinUSB seem to be the best options here.
53
54If the bootloader doesn't show up in the list for devices, you may need to enable the "List all devices" option in the `Options` menu, and then find the bootloader in question.
55
51 56
52## WINAVR is Obsolete 57## WINAVR is Obsolete
53It is no longer recommended and may cause some problem. 58It is no longer recommended and may cause some problem.
diff --git a/docs/feature_macros.md b/docs/feature_macros.md
index 79419abd2..743fc3ad5 100644
--- a/docs/feature_macros.md
+++ b/docs/feature_macros.md
@@ -146,9 +146,59 @@ send_string(my_str);
146SEND_STRING(".."SS_TAP(X_END)); 146SEND_STRING(".."SS_TAP(X_END));
147``` 147```
148 148
149## The Old Way: `MACRO()` & `action_get_macro`
150 149
151?> This is inherited from TMK, and hasn't been updated - it's recommend that you use `SEND_STRING` and `process_record_user` instead. 150## Advanced Macro Functions
151
152There are some functions you may find useful in macro-writing. Keep in mind that while you can write some fairly advanced code within a macro, if your functionality gets too complex you may want to define a custom keycode instead. Macros are meant to be simple.
153
154### `record->event.pressed`
155
156This is a boolean value that can be tested to see if the switch is being pressed or released. An example of this is
157
158```c
159 if (record->event.pressed) {
160 // on keydown
161 } else {
162 // on keyup
163 }
164```
165
166### `register_code(<kc>);`
167
168This sends the `<kc>` keydown event to the computer. Some examples would be `KC_ESC`, `KC_C`, `KC_4`, and even modifiers such as `KC_LSFT` and `KC_LGUI`.
169
170### `unregister_code(<kc>);`
171
172Parallel to `register_code` function, this sends the `<kc>` keyup event to the computer. If you don't use this, the key will be held down until it's sent.
173
174### `tap_code(<kc>);`
175
176This will send `register_code(<kc>)` and then `unregister_code(<kc>)`. This is useful if you want to send both the press and release events ("tap" the key, rather than hold it).
177
178If you're having issues with taps (un)registering, you can add a delay between the register and unregister events by setting `#define TAP_CODE_DELAY 100` in your `config.h` file. The value is in milliseconds.
179
180### `register_code16(<kc>);`, `unregister_code16(<kc>);` and `tap_code16(<kc>);`
181
182These functions work similar to their regular counterparts, but allow you to use modded keycodes (with Shift, Alt, Control, and/or GUI applied to them).
183
184Eg, you could use `register_code16(S(KC_5));` instead of registering the mod, then registering the keycode.
185
186### `clear_keyboard();`
187
188This will clear all mods and keys currently pressed.
189
190### `clear_mods();`
191
192This will clear all mods currently pressed.
193
194### `clear_keyboard_but_mods();`
195
196This will clear all keys besides the mods currently pressed.
197
198
199## **(DEPRECATED)** The Old Way: `MACRO()` & `action_get_macro`
200
201!> This is inherited from TMK, and hasn't been updated - it's recommended that you use `SEND_STRING` and `process_record_user` instead.
152 202
153By default QMK assumes you don't have any macros. To define your macros you create an `action_get_macro()` function. For example: 203By default QMK assumes you don't have any macros. To define your macros you create an `action_get_macro()` function. For example:
154 204
@@ -222,49 +272,8 @@ const uint16_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] = {
222}; 272};
223``` 273```
224 274
225## Advanced Macro Functions
226
227There are some functions you may find useful in macro-writing. Keep in mind that while you can write some fairly advanced code within a macro if your functionality gets too complex you may want to define a custom keycode instead. Macros are meant to be simple.
228
229### `record->event.pressed`
230
231This is a boolean value that can be tested to see if the switch is being pressed or released. An example of this is
232
233```c
234 if (record->event.pressed) {
235 // on keydown
236 } else {
237 // on keyup
238 }
239```
240
241### `register_code(<kc>);`
242
243This sends the `<kc>` keydown event to the computer. Some examples would be `KC_ESC`, `KC_C`, `KC_4`, and even modifiers such as `KC_LSFT` and `KC_LGUI`.
244
245### `unregister_code(<kc>);`
246
247Parallel to `register_code` function, this sends the `<kc>` keyup event to the computer. If you don't use this, the key will be held down until it's sent.
248
249### `tap_code(<kc>);`
250
251This will send `register_code(<kc>)` and then `unregister_code(<kc>)`. This is useful if you want to send both the press and release events ("tap" the key, rather than hold it).
252
253If you're having issues with taps (un)registering, you can add a delay between the register and unregister events by setting `#define TAP_CODE_DELAY 100` in your `config.h` file. The value is in milliseconds.
254
255### `clear_keyboard();`
256
257This will clear all mods and keys currently pressed.
258
259### `clear_mods();`
260
261This will clear all mods currently pressed.
262
263### `clear_keyboard_but_mods();`
264
265This will clear all keys besides the mods currently pressed.
266 275
267## Advanced Example: Single-Key Copy/Paste 276### Advanced Example: Single-Key Copy/Paste
268 277
269This example defines a macro which sends `Ctrl-C` when pressed down, and `Ctrl-V` when released. 278This example defines a macro which sends `Ctrl-C` when pressed down, and `Ctrl-V` when released.
270 279
diff --git a/docs/flashing.md b/docs/flashing.md
index bc418c415..cafb43910 100644
--- a/docs/flashing.md
+++ b/docs/flashing.md
@@ -49,6 +49,15 @@ To generate this bootloader, use the `bootloader` target, eg `make planck/rev4:d
49 49
50To generate a production-ready .hex file (containing the application and the bootloader), use the `production` target, eg `make planck/rev4:default:production`. 50To generate a production-ready .hex file (containing the application and the bootloader), use the `production` target, eg `make planck/rev4:default:production`.
51 51
52### DFU commands
53
54There are a number of DFU commands that you can use to flash firmware to a DFU device:
55
56* `:dfu` - This is the normal option and waits until a DFU device is available, and then flashes the firmware. This will check every 5 seconds, to see if a DFU device has appeared.
57* `:dfu-ee` - This flashes an `eep` file instead of the normal hex. This is uncommon.
58* `:dfu-split-left` - This flashes the normal firmware, just like the default option (`:dfu`). However, this also flashes the "Left Side" EEPROM file for split keyboards. _This is ideal for Elite C based split keyboards._
59* `:dfu-split-right` - This flashes the normal firmware, just like the default option (`:dfu`). However, this also flashes the "Right Side" EEPROM file for split keyboards. _This is ideal for Elite C based split keyboards._
60
52## Caterina 61## Caterina
53 62
54Arduino boards and their clones use the [Caterina bootloader](https://github.com/arduino/Arduino/tree/master/hardware/arduino/avr/bootloaders/caterina) (any keyboard built with a Pro Micro, or clone), and uses the avr109 protocol to communicate through virtual serial. Bootloaders like [A-Star](https://www.pololu.com/docs/0J61/9) are based on Caterina. 63Arduino boards and their clones use the [Caterina bootloader](https://github.com/arduino/Arduino/tree/master/hardware/arduino/avr/bootloaders/caterina) (any keyboard built with a Pro Micro, or clone), and uses the avr109 protocol to communicate through virtual serial. Bootloaders like [A-Star](https://www.pololu.com/docs/0J61/9) are based on Caterina.
@@ -84,6 +93,7 @@ or if you want to flash multiple boards, use the following command
84 93
85When you're done flashing boards, you'll need to hit Ctrl + C or whatever the correct keystroke is for your operating system to break the loop. 94When you're done flashing boards, you'll need to hit Ctrl + C or whatever the correct keystroke is for your operating system to break the loop.
86 95
96
87## Halfkay 97## Halfkay
88 98
89Halfkay is a super-slim protocol developed by PJRC that uses HID, and come on all Teensys (namely the 2.0). 99Halfkay is a super-slim protocol developed by PJRC that uses HID, and come on all Teensys (namely the 2.0).
@@ -131,3 +141,12 @@ Flashing sequence:
131 * You will receive a warning about the DFU signature; Just ignore it 141 * You will receive a warning about the DFU signature; Just ignore it
1324. Reset the device into application mode (may be done automatically) 1424. Reset the device into application mode (may be done automatically)
133 * If you are building from command line (e.g. `make planck/rev6:default:dfu-util`), make sure that `:leave` is passed to the `DFU_ARGS` variable inside your `rules.mk` (e.g. `DFU_ARGS = -d 0483:df11 -a 0 -s 0x08000000:leave`) so that your device resets after flashing 143 * If you are building from command line (e.g. `make planck/rev6:default:dfu-util`), make sure that `:leave` is passed to the `DFU_ARGS` variable inside your `rules.mk` (e.g. `DFU_ARGS = -d 0483:df11 -a 0 -s 0x08000000:leave`) so that your device resets after flashing
144
145### STM32 Commands
146
147There are a number of DFU commands that you can use to flash firmware to a STM32 device:
148
149* `:dfu-util` - The default command for flashing to STM32 devices.
150* `:dfu-util-wait` - This works like the default command, but it gives you a (configurable) 10 second timeout before it attempts to flash the firmware. You can use `TIME_DELAY=20` from the command line to change the timeout.
151 * Eg: `make <keyboard>:<keymap>:dfu-util TIME_DELAY=5`
152* `:st-link-cli` - This allows you to flash the firmware via ST-LINK's CLI utility, rather than dfu-util.
diff --git a/docs/keymap.md b/docs/keymap.md
index 49e6654a2..457dbf67e 100644
--- a/docs/keymap.md
+++ b/docs/keymap.md
@@ -161,62 +161,6 @@ Some interesting things to note:
161* We have used our `_______` definition to turn `KC_TRNS` into `_______`. This makes it easier to spot the keys that have changed on this layer. 161* We have used our `_______` definition to turn `KC_TRNS` into `_______`. This makes it easier to spot the keys that have changed on this layer.
162* While in this layer if you press one of the `_______` keys it will activate the key in the next lowest active layer. 162* While in this layer if you press one of the `_______` keys it will activate the key in the next lowest active layer.
163 163
164### Custom Functions
165
166At the bottom of the file we've defined a single custom function. This function defines a key that sends `KC_ESC` when pressed without modifiers and `KC_GRAVE` when modifiers are held. There are a couple pieces that need to be in place for this to work, and we will go over both of them.
167
168#### `fn_actions[]`
169
170We define the `fn_actions[]` array to point to custom functions. `F(N)` in a keymap will call element N of that array. For the Clueboard's that looks like this:
171
172 const uint16_t PROGMEM fn_actions[] = {
173 [0] = ACTION_FUNCTION(0), // Calls action_function()
174 };
175
176In this case we've instructed QMK to call the `ACTION_FUNCTION` callback, which we will define in the next section.
177
178> This `fn_actions[]` interface is mostly for backward compatibility. In QMK, you don't need to use `fn_actions[]`. You can directly use `ACTION_FUNCTION(N)` or any other action code value itself normally generated by the macro in `keymaps[][MATRIX_ROWS][MATRIX_COLS]`. N in `F(N)` can only be 0 to 31. Use of the action code directly in `keymaps` unlocks this limitation.
179
180You can get a full list of Action Functions in [action_code.h](https://github.com/qmk/qmk_firmware/blob/master/tmk_core/common/action_code.h).
181
182#### `action_function()`
183
184To actually handle the keypress event we define an `action_function()`. This function will be called when the key is pressed, and then again when the key is released. We have to handle both situations within our code, as well as determining whether to send/release `KC_ESC` or `KC_GRAVE`.
185
186 void action_function(keyrecord_t *record, uint8_t id, uint8_t opt) {
187 static uint8_t mods_pressed;
188
189 switch (id) {
190 case 0:
191 /* Handle the combined Grave/Esc key
192 */
193 mods_pressed = get_mods()&GRAVE_MODS; // Check to see what mods are pressed
194
195 if (record->event.pressed) {
196 /* The key is being pressed.
197 */
198 if (mods_pressed) {
199 add_key(KC_GRV);
200 send_keyboard_report();
201 } else {
202 add_key(KC_ESC);
203 send_keyboard_report();
204 }
205 } else {
206 /* The key is being released.
207 */
208 if (mods_pressed) {
209 del_key(KC_GRV);
210 send_keyboard_report();
211 } else {
212 del_key(KC_ESC);
213 send_keyboard_report();
214 }
215 }
216 break;
217 }
218 }
219
220# Nitty Gritty Details 164# Nitty Gritty Details
221 165
222This should have given you a basic overview for creating your own keymap. For more details see the following resources: 166This should have given you a basic overview for creating your own keymap. For more details see the following resources:
diff --git a/docs/newbs_flashing.md b/docs/newbs_flashing.md
index 9d2bf920f..a985e5d2b 100644
--- a/docs/newbs_flashing.md
+++ b/docs/newbs_flashing.md
@@ -131,6 +131,16 @@ If you have any issues with this, you may need to this:
131 131
132 sudo make <my_keyboard>:<my_keymap>:dfu 132 sudo make <my_keyboard>:<my_keymap>:dfu
133 133
134#### DFU commands
135
136There are a number of DFU commands that you can use to flash firmware to a DFU device:
137
138* `:dfu` - This is the normal option and waits until a DFU device is available, and then flashes the firmware. This will check every 5 seconds, to see if a DFU device has appeared.
139* `:dfu-ee` - This flashes an `eep` file instead of the normal hex. This is uncommon.
140* `:dfu-split-left` - This flashes the normal firmware, just like the default option (`:dfu`). However, this also flashes the "Left Side" EEPROM file for split keyboards. _This is ideal for Elite C based split keyboards._
141* `:dfu-split-right` - This flashes the normal firmware, just like the default option (`:dfu`). However, this also flashes the "Right Side" EEPROM file for split keyboards. _This is ideal for Elite C based split keyboards._
142
143
134### Caterina 144### Caterina
135 145
136For Arduino boards and their clones (such as the SparkFun ProMicro), when you're ready to compile and flash your firmware, open up your terminal window and run the build command: 146For Arduino boards and their clones (such as the SparkFun ProMicro), when you're ready to compile and flash your firmware, open up your terminal window and run the build command:
@@ -199,6 +209,14 @@ If you have any issues with this, you may need to this:
199 209
200 sudo make <my_keyboard>:<my_keymap>:avrdude 210 sudo make <my_keyboard>:<my_keymap>:avrdude
201 211
212
213Additionally, if you want to flash multiple boards, use the following command:
214
215 make <keyboard>:<keymap>:avrdude-loop
216
217When you're done flashing boards, you'll need to hit Ctrl + C or whatever the correct keystroke is for your operating system to break the loop.
218
219
202## HalfKay 220## HalfKay
203 221
204For the PJRC devices (Teensy's), when you're ready to compile and flash your firmware, open up your terminal window and run the build command: 222For the PJRC devices (Teensy's), when you're ready to compile and flash your firmware, open up your terminal window and run the build command:
@@ -226,12 +244,61 @@ Waiting for Teensy device...
226 244
227 ``` 245 ```
228 Found HalfKay Bootloader 246 Found HalfKay Bootloader
229Read "./.build/ergodox_ez_drashna.hex": 28532 bytes, 88.5% usage 247Read "./.build/ergodox_ez_xyverz.hex": 28532 bytes, 88.5% usage
230Programming............................................................................................................................................................................ 248Programming............................................................................................................................................................................
231................................................... 249...................................................
232Booting 250Booting
233``` 251```
234 252
253## STM32 (ARM)
254
255For a majority of ARM boards (including the Proton C, Planck Rev 6, and Preonic Rev 3), when you're ready to compile and flash your firmware, open up your terminal window and run the build command:
256
257 make <my_keyboard>:<my_keymap>:dfu-util
258
259For example, if your keymap is named "xyverz" and you're building a keymap for the Planck Revision 6 keyboard, you'll use this command and then reboot the keyboard to the bootloader (before it finishes compiling):
260
261 make planck/rev6:xyverz:dfu-util
262
263Once the firmware finishes compiling, it will output something like this:
264
265```
266Linking: .build/planck_rev6_xyverz.elf [OK]
267Creating binary load file for flashing: .build/planck_rev6_xyverz.bin [OK]
268Creating load file for flashing: .build/planck_rev6_xyverz.hex [OK]
269
270Size after:
271 text data bss dec hex filename
272 0 41820 0 41820 a35c .build/planck_rev6_xyverz.hex
273
274Copying planck_rev6_xyverz.bin to qmk_firmware folder [OK]
275dfu-util 0.9
276
277Copyright 2005-2009 Weston Schmidt, Harald Welte and OpenMoko Inc.
278Copyright 2010-2016 Tormod Volden and Stefan Schmidt
279This program is Free Software and has ABSOLUTELY NO WARRANTY
280Please report bugs to http://sourceforge.net/p/dfu-util/tickets/
281
282Invalid DFU suffix signature
283A valid DFU suffix will be required in a future dfu-util release!!!
284Opening DFU capable USB device...
285ID 0483:df11
286Run-time device DFU version 011a
287Claiming USB DFU Interface...
288Setting Alternate Setting #0 ...
289Determining device status: state = dfuERROR, status = 10
290dfuERROR, clearing status
291Determining device status: state = dfuIDLE, status = 0
292dfuIDLE, continuing
293DFU mode device DFU version 011a
294Device returned transfer size 2048
295DfuSe interface name: "Internal Flash "
296Downloading to address = 0x08000000, size = 41824
297Download [=========================] 100% 41824 bytes
298Download done.
299File downloaded successfully
300Transitioning to dfuMANIFEST state
301```
235 302
236## Test It Out! 303## Test It Out!
237 304
diff --git a/docs/understanding_qmk.md b/docs/understanding_qmk.md
index bf4b5eadc..a94c9c319 100644
--- a/docs/understanding_qmk.md
+++ b/docs/understanding_qmk.md
@@ -135,9 +135,11 @@ The `process_record()` function itself is deceptively simple, but hidden within
135* [`void process_record(keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/e1203a222bb12ab9733916164a000ef3ac48da93/tmk_core/common/action.c#L172) 135* [`void process_record(keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/e1203a222bb12ab9733916164a000ef3ac48da93/tmk_core/common/action.c#L172)
136 * [`bool process_record_quantum(keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/e1203a222bb12ab9733916164a000ef3ac48da93/quantum/quantum.c#L206) 136 * [`bool process_record_quantum(keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/e1203a222bb12ab9733916164a000ef3ac48da93/quantum/quantum.c#L206)
137 * [Map this record to a keycode](https://github.com/qmk/qmk_firmware/blob/e1203a222bb12ab9733916164a000ef3ac48da93/quantum/quantum.c#L226) 137 * [Map this record to a keycode](https://github.com/qmk/qmk_firmware/blob/e1203a222bb12ab9733916164a000ef3ac48da93/quantum/quantum.c#L226)
138 * [`void velocikey_accelerate(void)`](https://github.com/qmk/qmk_firmware/blob/c1c5922aae7b60b7c7d13d3769350eed9dda17ab/quantum/velocikey.c#L27)
138 * [`void preprocess_tap_dance(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/e1203a222bb12ab9733916164a000ef3ac48da93/quantum/process_keycode/process_tap_dance.c#L119) 139 * [`void preprocess_tap_dance(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/e1203a222bb12ab9733916164a000ef3ac48da93/quantum/process_keycode/process_tap_dance.c#L119)
139 * [`bool process_key_lock(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/e1203a222bb12ab9733916164a000ef3ac48da93/quantum/process_keycode/process_key_lock.c#L62) 140 * [`bool process_key_lock(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/e1203a222bb12ab9733916164a000ef3ac48da93/quantum/process_keycode/process_key_lock.c#L62)
140 * [`bool process_clicky(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/e1203a222bb12ab9733916164a000ef3ac48da93/quantum/process_keycode/process_clicky.c#L79) 141 * [`bool process_clicky(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/e1203a222bb12ab9733916164a000ef3ac48da93/quantum/process_keycode/process_clicky.c#L79)
142 * [`bool process_haptic(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/2cee371bf125a6ec541dd7c5a809573facc7c456/drivers/haptic/haptic.c#L216)
141 * [`bool process_record_kb(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/e1203a222bb12ab9733916164a000ef3ac48da93/keyboards/clueboard/card/card.c#L20) 143 * [`bool process_record_kb(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/e1203a222bb12ab9733916164a000ef3ac48da93/keyboards/clueboard/card/card.c#L20)
142 * [`bool process_record_user(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/e1203a222bb12ab9733916164a000ef3ac48da93/keyboards/clueboard/card/keymaps/default/keymap.c#L58) 144 * [`bool process_record_user(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/e1203a222bb12ab9733916164a000ef3ac48da93/keyboards/clueboard/card/keymaps/default/keymap.c#L58)
143 * [`bool process_rgb_matrix(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/e1203a222bb12ab9733916164a000ef3ac48da93/quantum/rgb_matrix.c#L139) 145 * [`bool process_rgb_matrix(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/e1203a222bb12ab9733916164a000ef3ac48da93/quantum/rgb_matrix.c#L139)