@ -116,29 +116,29 @@ Use the `IS_LED_ON(usb_led, led_name)` and `IS_LED_OFF(usb_led, led_name)` macro
```c
```c
void led_set_user(uint8_t usb_led) {
void led_set_user(uint8_t usb_led) {
if (IS_LED_ON(usb_led, USB_LED_NUM_LOCK)) {
if (IS_LED_ON(usb_led, USB_LED_NUM_LOCK)) {
PORTB |= (1<<0);
writePinLow(B0);
} else {
} else {
PORTB &= ~(1<<0);
writePinHigh(B0);
}
}
if (IS_LED_ON(usb_led, USB_LED_CAPS_LOCK)) {
if (IS_LED_ON(usb_led, USB_LED_CAPS_LOCK)) {
PORTB |= (1<<1);
writePinLow(B1);
} else {
} else {
PORTB &= ~(1<<1);
writePinHigh(B1);
}
}
if (IS_LED_ON(usb_led, USB_LED_SCROLL_LOCK)) {
if (IS_LED_ON(usb_led, USB_LED_SCROLL_LOCK)) {
PORTB |= (1<<2);
writePinLow(B2);
} else {
} else {
PORTB &= ~(1<<2);
writePinHigh(B2);
}
}
if (IS_LED_ON(usb_led, USB_LED_COMPOSE)) {
if (IS_LED_ON(usb_led, USB_LED_COMPOSE)) {
PORTB |= (1<<3);
writePinLow(B3);
} else {
} else {
PORTB &= ~(1<<3);
writePinHigh(B3);
}
}
if (IS_LED_ON(usb_led, USB_LED_KANA)) {
if (IS_LED_ON(usb_led, USB_LED_KANA)) {
PORTB |= (1<<4);
writePinLow(B4);
} else {
} else {
PORTB &= ~(1<<4);
writePinHigh(B4);
}
}
}
}
```
```
@ -189,16 +189,18 @@ However, if you have hardware stuff that you need initialized, this is the best
### Example `keyboard_pre_init_user()` Implementation
### Example `keyboard_pre_init_user()` Implementation
This example, at the keyboard level, sets up B1, B2, and B3 as LED pins.
This example, at the keyboard level, sets up B0, B1, B2, B3, and B4 as LED pins.
```c
```c
void keyboard_pre_init_user(void) {
void keyboard_pre_init_user(void) {
// Call the keyboard pre init code.
// Call the keyboard pre init code.
// Set our LED pins as output
// Set our LED pins as output
DDRB |= (1<<1);
setPinOutput(B0);
DDRB |= (1<<2);
setPinOutput(B1);
DDRB |= (1<<3);
setPinOutput(B2);
setPinOutput(B3);
setPinOutput(B4);
}
}
```
```
@ -270,16 +272,13 @@ This is controlled by two functions: `suspend_power_down_*` and `suspend_wakeup_
### Example suspend_power_down_user() and suspend_wakeup_init_user() Implementation
### Example suspend_power_down_user() and suspend_wakeup_init_user() Implementation
This example, at the keyboard level, sets up B1, B2, and B3 as LED pins.
```c
```c
void suspend_power_down_user(void)
void suspend_power_down_user(void) {
{
rgb_matrix_set_suspend_state(true);
rgb_matrix_set_suspend_state(true);
}
}
void suspend_wakeup_init_user(void)
void suspend_wakeup_init_user(void) {
{
rgb_matrix_set_suspend_state(false);
rgb_matrix_set_suspend_state(false);
}
}
```
```
@ -356,11 +355,11 @@ user_config_t user_config;
This 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.
This 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.
We're using `rgb_layer_change`, for the `layer_state_set_*` function, and use `matrix_init_user` and `process_record_user` to configure everything.
We're using `rgb_layer_change`, for the `layer_state_set_*` function, and use `keyboard_post_init_user` and `process_record_user` to configure everything.
Now, 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:
Now, 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:
```
```
void matrix_init_user(void) {
void keyboard_post_init_user(void) {
// Call the keymap level matrix init.
// Call the keymap level matrix init.
// Read the user config from EEPROM
// 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
```
```
void eeconfig_init_user(void) { // EEPROM is getting reset!
void eeconfig_init_user(void) { // EEPROM is getting reset!
user_config.raw = 0;
user_config.rgb_layer_change = true; // We want this enabled by default
user_config.rgb_layer_change = true; // We want this enabled by default
eeconfig_update_user(user_config.raw); // Write default value to EEPROM now
eeconfig_update_user(user_config.raw); // Write default value to EEPROM now
Note that running `make` with `sudo` is generally *not* a good idea, and you should use one of the former methods, if possible.
Note that running `make` with `sudo` is generally ***not*** a good idea, and you should use one of the former methods, if possible.
### Linux `udev` Rules
### Linux `udev` Rules
On Linux, you'll need proper privileges to access the MCU. You can either use
On 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,
Re-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.
Re-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.
If 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.
If 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.
?> 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.
If 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.
## WINAVR is Obsolete
## WINAVR is Obsolete
It is no longer recommended and may cause some problem.
It is no longer recommended and may cause some problem.
?> This is inherited from TMK, and hasn't been updated - it's recommend that you use `SEND_STRING` and `process_record_user` instead.
## Advanced Macro Functions
There 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.
### `record->event.pressed`
This is a boolean value that can be tested to see if the switch is being pressed or released. An example of this is
```c
if (record->event.pressed) {
// on keydown
} else {
// on keyup
}
```
### `register_code(<kc>);`
This 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`.
### `unregister_code(<kc>);`
Parallel 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.
### `tap_code(<kc>);`
This 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).
If 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.
### `register_code16(<kc>);`, `unregister_code16(<kc>);` and `tap_code16(<kc>);`
These functions work similar to their regular counterparts, but allow you to use modded keycodes (with Shift, Alt, Control, and/or GUI applied to them).
Eg, you could use `register_code16(S(KC_5));` instead of registering the mod, then registering the keycode.
### `clear_keyboard();`
This will clear all mods and keys currently pressed.
### `clear_mods();`
This will clear all mods currently pressed.
### `clear_keyboard_but_mods();`
This will clear all keys besides the mods currently pressed.
## **(DEPRECATED)** The Old Way: `MACRO()`&`action_get_macro`
!> This is inherited from TMK, and hasn't been updated - it's recommended that you use `SEND_STRING` and `process_record_user` instead.
By default QMK assumes you don't have any macros. To define your macros you create an `action_get_macro()` function. For example:
By default QMK assumes you don't have any macros. To define your macros you create an `action_get_macro()` function. For example:
There 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.
### `record->event.pressed`
This is a boolean value that can be tested to see if the switch is being pressed or released. An example of this is
```c
if (record->event.pressed) {
// on keydown
} else {
// on keyup
}
```
### `register_code(<kc>);`
This 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`.
### `unregister_code(<kc>);`
Parallel 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.
### `tap_code(<kc>);`
This 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).
If 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.
### `clear_keyboard();`
This will clear all mods and keys currently pressed.
### `clear_mods();`
This will clear all mods currently pressed.
### `clear_keyboard_but_mods();`
This will clear all keys besides the mods currently pressed.
## Advanced Example: Single-Key Copy/Paste
### Advanced Example: Single-Key Copy/Paste
This example defines a macro which sends `Ctrl-C` when pressed down, and `Ctrl-V` when released.
This example defines a macro which sends `Ctrl-C` when pressed down, and `Ctrl-V` when released.
@ -49,6 +49,15 @@ To generate this bootloader, use the `bootloader` target, eg `make planck/rev4:d
To generate a production-ready .hex file (containing the application and the bootloader), use the `production` target, eg `make planck/rev4:default:production`.
To generate a production-ready .hex file (containing the application and the bootloader), use the `production` target, eg `make planck/rev4:default:production`.
### DFU commands
There are a number of DFU commands that you can use to flash firmware to a DFU device:
* `: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.
* `:dfu-ee` - This flashes an `eep` file instead of the normal hex. This is uncommon.
* `: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._
* `: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._
## Caterina
## Caterina
Arduino 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.
Arduino 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
When 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.
When 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.
## Halfkay
## Halfkay
Halfkay is a super-slim protocol developed by PJRC that uses HID, and come on all Teensys (namely the 2.0).
Halfkay 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:
* You will receive a warning about the DFU signature; Just ignore it
* You will receive a warning about the DFU signature; Just ignore it
4. Reset the device into application mode (may be done automatically)
4. Reset the device into application mode (may be done automatically)
* 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
* 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
### STM32 Commands
There are a number of DFU commands that you can use to flash firmware to a STM32 device:
* `:dfu-util` - The default command for flashing to STM32 devices.
* `: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.
@ -161,62 +161,6 @@ Some interesting things to note:
* We have used our `_______` definition to turn `KC_TRNS` into `_______`. This makes it easier to spot the keys that have changed on this layer.
* We have used our `_______` definition to turn `KC_TRNS` into `_______`. This makes it easier to spot the keys that have changed on this layer.
* While in this layer if you press one of the `_______` keys it will activate the key in the next lowest active layer.
* While in this layer if you press one of the `_______` keys it will activate the key in the next lowest active layer.
### Custom Functions
At 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.
#### `fn_actions[]`
We 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:
In this case we've instructed QMK to call the `ACTION_FUNCTION` callback, which we will define in the next section.
> 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.
You 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).
#### `action_function()`
To 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`.
@ -131,6 +131,16 @@ If you have any issues with this, you may need to this:
sudo make <my_keyboard>:<my_keymap>:dfu
sudo make <my_keyboard>:<my_keymap>:dfu
#### DFU commands
There are a number of DFU commands that you can use to flash firmware to a DFU device:
* `: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.
* `:dfu-ee` - This flashes an `eep` file instead of the normal hex. This is uncommon.
* `: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._
* `: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._
### Caterina
### Caterina
For 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:
For 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:
sudo make <my_keyboard>:<my_keymap>:avrdude
sudo make <my_keyboard>:<my_keymap>:avrdude
Additionally, if you want to flash multiple boards, use the following command:
make <keyboard>:<keymap>:avrdude-loop
When 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.
## HalfKay
## HalfKay
For 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:
For 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:
For 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:
make <my_keyboard>:<my_keymap>:dfu-util
For 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):
make planck/rev6:xyverz:dfu-util
Once the firmware finishes compiling, it will output something like this:
```
Linking: .build/planck_rev6_xyverz.elf [OK]
Creating binary load file for flashing: .build/planck_rev6_xyverz.bin [OK]
Creating load file for flashing: .build/planck_rev6_xyverz.hex [OK]
Drashna Jaelre
6 years ago
committed by