* Hardware Availability: *Links to where you can find this hardware*
Make example for this keyboard (after setting up your build environment):
make %KEYBOARD%:default
make %(KEYBOARD)s:default
Flashing example for this keyboard:
make %KEYBOARD%:default:flash
make %(KEYBOARD)s:default:flash
See the [build environment setup](https://docs.qmk.fm/#/getting_started_build_tools) and the [make instructions](https://docs.qmk.fm/#/getting_started_make_guide) for more information. Brand new to QMK? Start with our [Complete Newbs Guide](https://docs.qmk.fm/#/newbs).
* Hardware Availability: *Links to where you can find this hardware*
Make example for this keyboard (after setting up your build environment):
make %KEYBOARD%:default
make %(KEYBOARD)s:default
Flashing example for this keyboard ([after setting up the bootloadHID flashing environment](https://docs.qmk.fm/#/flashing_bootloadhid))
make %KEYBOARD%:default:flash
make %(KEYBOARD)s:default:flash
See the [build environment setup](https://docs.qmk.fm/#/getting_started_build_tools) and the [make instructions](https://docs.qmk.fm/#/getting_started_make_guide) for more information. Brand new to QMK? Start with our [Complete Newbs Guide](https://docs.qmk.fm/#/newbs).
This command opens a new shell in your `qmk_firmware` directory.
Note that if you are already somewhere within `QMK_HOME` (for example, the `keyboards/` folder), nothing will happen.
To exit out into the parent shell, simply type `exit`.
**Usage**:
```
qmk cd
```
## `qmk console`
This command lets you connect to keyboard consoles to get debugging messages. It only works if your keyboard firmware has been compiled with `CONSOLE_ENABLE=yes`.
@ -373,6 +387,8 @@ qmk format-c -b branch_name
This command starts a local HTTP server which you can use for browsing or improving the docs. Default port is 8936.
Use the `-b`/`--browser` flag to automatically open the local webserver in your default browser.
This command runs `docsify serve` if `docsify-cli` is installed (which provides live reload), otherwise Python's builtin HTTP server module will be used.
@ -404,6 +404,8 @@ However, this will automatically disable the legacy TMK Macros and Functions fea
Use these to enable or disable building certain features. The more you have enabled the bigger your firmware will be, and you run the risk of building a firmware too large for your MCU.
* `MAGIC_ENABLE`
* MAGIC actions (BOOTMAGIC without the boot)
* `BOOTMAGIC_ENABLE`
* Virtual DIP switch configuration
* `MOUSEKEY_ENABLE`
@ -418,6 +420,8 @@ Use these to enable or disable building certain features. The more you have enab
* Key combo feature
* `NKRO_ENABLE`
* USB N-Key Rollover - if this doesn't work, see here: https://github.com/tmk/tmk_keyboard/wiki/FAQ#nkro-doesnt-work
* `RING_BUFFERED_6KRO_REPORT_ENABLE`
* USB 6-Key Rollover - Instead of stopping any new input once 6 keys are pressed, the oldest key is released and the new key is pressed.
@ -168,10 +168,16 @@ This mode sets continuous haptic feedback with the option to increase or decreas
The Haptic Exclusion is implemented as `__attribute__((weak)) bool get_haptic_enabled_key(uint16_t keycode, keyrecord_t *record)` in haptic.c. This allows a re-definition at the required level with the specific requirement / exclusion.
### NO_HAPTIC_MOD
With the entry of `#define NO_HAPTIC_MOD` in config.h, modifiers from Left Control to Right GUI will not trigger a feedback. This also includes modifiers in a Mod Tap configuration.
With the entry of `#define NO_HAPTIC_MOD` in config.h, the following keys will not trigger feedback:
* Usual modifier keys such as Control/Shift/Alt/Gui (For example `KC_LCTRL`)
* `MO()` momentary keys. See also [Layers](feature_layers.md).
* `LT()` layer tap keys, when held to activate a layer. However when tapped, and the key is quickly released, and sends a keycode, haptic feedback is still triggered.
* `TT()` layer tap toggle keys, when held to activate a layer. However when tapped `TAPPING_TOGGLE` times to permanently toggle the layer, on the last tap haptic feedback is still triggered.
* `MT()` mod tap keys, when held to keep a usual modifier key pressed. However when tapped, and the key is quickly released, and sends a keycode, haptic feedback is still triggered. See also [Mod-Tap](mod_tap.md).
### NO_HAPTIC_FN
With the entry of `#define NO_HAPTIC_FN` in config.h, layer keys will not rigger a feedback.
With the entry of `#define NO_HAPTIC_FN` in config.h, deprecated `fn_actions` type function keys will not trigger a feedback.
### NO_HAPTIC_ALPHA
With the entry of `#define NO_HAPTIC_ALPHA` in config.h, none of the alpha keys (A ... Z) will trigger a feedback.
If you want to just use RGB indicators without RGB matrix effect, it is not possible to disable the latter because toggling RGB off will disable everything. You can workaround it with solid effect and colors off using this init function:
In your keymap create a new layer for Plover. You will need to include `keymap_steno.h`. See `planck/keymaps/steno/keymap.c` for an example. Remember to create a key to switch to the layer as well as a key for exiting the layer. If you would like to switch modes on the fly you can use the keycodes `QK_STENO_BOLT` and `QK_STENO_GEMINI`. If you only want to use one of the protocols you may set it up in your initialization function:
```c
void matrix_init_user() {
steno_set_mode(STENO_MODE_GEMINI); // or STENO_MODE_BOLT
void eeconfig_init_user() {
steno_set_mode(STENO_MODE_GEMINI); // or STENO_MODE_BOLT
}
```
@ -129,7 +129,8 @@ As defined in `keymap_steno.h`.
|`STN_RES2`||(GeminiPR only)|
|`STN_PWR`||(GeminiPR only)|
If you do not want to hit two keys with one finger combined keycodes can be used. These are also defined in `keymap_steno.h`, and causes both keys to be reported as pressed or released. To use these keycodes define `STENO_COMBINEDMAP` in your `config.h` file
If you do not want to hit two keys with one finger combined keycodes can be used. These are also defined in `keymap_steno.h`, and causes both keys to be reported as pressed or released. To use these keycodes define `STENO_COMBINEDMAP` in your `config.h` file.
@ -29,7 +29,7 @@ After this, you'll want to use the `tap_dance_actions` array to specify what act
* `ACTION_TAP_DANCE_FN(fn)`: Calls the specified function - defined in the user keymap - with the final tap count of the tap dance action.
* `ACTION_TAP_DANCE_FN_ADVANCED(on_each_tap_fn, on_dance_finished_fn, on_dance_reset_fn)`: Calls the first specified function - defined in the user keymap - on every tap, the second function when the dance action finishes (like the previous option), and the last function when the tap dance action resets.
* ~~`ACTION_TAP_DANCE_FN_ADVANCED_TIME(on_each_tap_fn, on_dance_finished_fn, on_dance_reset_fn, tap_specific_tapping_term)`~~: This functions identically to the `ACTION_TAP_DANCE_FN_ADVANCED` function, but uses a custom tapping term for it, instead of the predefined `TAPPING_TERM`.
* This is deprecated in favor of the Per Key Tapping Term functionality, as outlined [here](custom_quantum_functions.md#Custom_Tapping_Term). You'd want to check for the specific `TD()` macro that you want to use (such as `TD(TD_ESC_CAPS)`) instead of using this specific Tap Dance function.
* This is deprecated in favor of the Per Key Tapping Term functionality, as outlined [here](tap_hold.md#tapping-term). You'd want to check for the specific `TD()` macro that you want to use (such as `TD(TD_ESC_CAPS)`) instead of using this specific Tap Dance function.
The first option is enough for a lot of cases, that just want dual roles. For example, `ACTION_TAP_DANCE_DOUBLE(KC_SPC, KC_ENT)` will result in `Space` being sent on single-tap, `Enter` otherwise.
ISP flashing (also known as ICSP flashing) is the process of programming a microcontroller directly. This allows you to replace the bootloader, or change the "fuses" on the controller, which control a number of hardware- and software-related functions, such as the speed of the controller, how it boots, and other options.
In order to flash a microcontroller over USB, it needs something called a bootloader. This bootloader lives in a specific section of the flash memory, and allows you to load the actual application firmware (in this case, QMK) into the rest of the flash.
The main use of ISP flashing for QMK is flashing or replacing the bootloader on your AVR-based controller (Pro Micros, or V-USB chips).
However, it can sometimes happen that the bootloader becomes corrupted and needs reflashing, or you may want to change the bootloader to another one. It's not possible to do this with the existing bootloader, because, of course, it is already running, and cannot overwrite itself. Instead, you will need to ISP flash the microcontroller.
?> This is only for programming AVR based boards, such as the Pro Micro or other ATmega controllers. It is not for Arm controllers, such as the Proton C.
There are several different kinds of bootloaders available for AVR microcontrollers. Most STM32 ARM-based microcontrollers already have a USB-capable bootloader in ROM, so generally do not need to be ISP flashed.
## Dealing with Corrupted Bootloaders
## Hardware
If you're having trouble flashing/erasing your board, and running into cryptic error messages like any of the following for a DFU based controller:
One of the following devices is required to perform the ISP flashing. The product links are to the official versions, however you can certainly source them elsewhere.
libusb: warning [darwin_transfer_status] transfer error: timed out
dfu.c:844: -ETIMEDOUT: Transfer timed out, NAK 0xffffffc4 (-60)
atmel.c:1627: atmel_flash: flash data dfu_download failed.
atmel.c:1629: Expected message length of 1072, got -60.
You'll also need some jumper wires to connect the ISP flasher and the target board. Some boards have an ISP header with the necessary pins broken out. If not, then you will need to temporarily solder the wires to the PCB -- usually to switch pins or directly to the MCU.
The wiring is fairly straightforward; for the most part, you'll be connecting like to like. Refer to the target MCU's datasheet for the exact `RESET`, `SCLK`, `MOSI` and `MISO` pins.
dfu.c:844: -EPIPE: a) Babble detect or b) Endpoint stalled 0xffffffe0 (-32)
Or, if you see this sort of message for a Pro Micro based controller:
[SparkFun Pro Micro](https://www.sparkfun.com/products/12640)
avrdude: butterfly_recv(): programmer is not responding
avrdude: butterfly_recv(): programmer is not responding
avrdude: verification error, first mismatch at byte 0x002a
0x2b != 0x75
avrdude: verification error; content mismatch
avrdude: verification error; content mismatch
To use a 5V/16MHz Pro Micro as an ISP flashing tool, you will first need to load a [special firmware](https://github.com/qmk/qmk_firmware/blob/master/util/pro_micro_ISP_B6_10.hex) onto it that emulates a hardware ISP flasher.
**AVRDUDE Programmer**: `avrisp`
**AVRDUDE Port**: Serial
You're likely going to need to ISP flash your board/device to get it working again.
#### Wiring
## Hardware Needed
|Pro Micro |Keyboard|
|-----------|--------|
|`VCC` |`VCC` |
|`GND` |`GND` |
|`10` (`B6`)|`RESET` |
|`15` (`B1`)|`SCLK` |
|`16` (`B2`)|`MOSI` |
|`14` (`B3`)|`MISO` |
You'll need one of the following to actually perform the ISP flashing (followed by the protocol they use):
!> Note that the `10` pin on the Pro Micro should be wired to the `RESET` pin on the keyboard's controller. ***DO NOT*** connect the `RESET` pin on the Pro Micro to the `RESET` on the keyboard.
There are other devices that can be used to ISP flash, but these are the main ones. Also, all product links are to the official versions. You can source them elsewhere.
You'll also need something to wire your "ISP Programmer" to the device that you're programming. Some PCBs may have ISP headers that you can use directly, but this often isn't the case, so you'll likely need to solder to the controller itself or to different switches or other components.
To use a Teensy 2.0 as an ISP flashing tool, you will first need to load a [special firmware](https://github.com/qmk/qmk_firmware/blob/master/util/teensy_2.0_ISP_B0.hex) onto it that emulates a hardware ISP flasher.
### The ISP Firmware
**AVRDUDE Programmer**: `avrisp`
**AVRDUDE Port**: Serial
The Teensy and Pro Micro controllers will need you to flash the ISP firmware to the controllers before you can use them as an ISP programmer. The rest of the hardware should come preprogrammed. So, for these controllers, download the correct hex file, and flash it first.
* Pro Micro: [`util/pro_micro_ISP_B6_10.hex`](https://github.com/qmk/qmk_firmware/blob/master/util/pro_micro_ISP_B6_10.hex) (`10/B6`)
|Teensy|Keyboard|
|------|--------|
|`VCC` |`VCC` |
|`GND` |`GND` |
|`B0` |`RESET` |
|`B1` |`SCLK` |
|`B2` |`MOSI` |
|`B3` |`MISO` |
Once you've flashed your controller, you won't need this hex file anymore.
!> Note that the `B0` pin on the Teensy should be wired to the `RESET` pin on the keyboard's controller. ***DO NOT*** connect the `RESET` pin on the Teensy to the `RESET` on the keyboard.
## Software Needed
### SparkFun PocketAVR / USBtinyISP / USBasp
The QMK Toolbox can be used for most (all) of this.
However, you can grab the [Teensy Loader](https://www.pjrc.com/teensy/loader.html) to flash your Teensy 2.0 board, if you are using that. Or you can use `avrdude` (installed as part of `qmk_install.sh`), or [AVRDUDESS](https://blog.zakkemble.net/avrdudess-a-gui-for-avrdude/) (for Windows) to flash the Pro Micro, and the ISP flashing.
**AVRDUDE Programmer**: `usbtiny` / `usbasp`
**AVRDUDE Port**: `usb`
#### Wiring
## Wiring
|ISP |Keyboard|
|---------|--------|
|`VCC` |`VCC` |
|`GND` |`GND` |
|`RST` |`RESET` |
|`SCLK` |`SCLK` |
|`MOSI` |`MOSI` |
|`MISO` |`MISO` |
This is pretty straight-forward - we'll be connecting like-things to like-things in the following manner.
### SparkFun Pocket AVR
### Bus Pirate
PocketAVR RST <-> Keyboard RESET
PocketAVR SCLK <-> Keyboard B1 (SCLK)
PocketAVR MOSI <-> Keyboard B2 (MOSI)
PocketAVR MISO <-> Keyboard B3 (MISO)
PocketAVR VCC <-> Keyboard VCC
PocketAVR GND <-> Keyboard GND
[Adafruit Bus Pirate](https://www.adafruit.com/product/237)
### USBasp
!> The 5-pin "ICSP" header is for ISP flashing the PIC microcontroller of the Bus Pirate. Connect your target board to the 10-pin header opposite the USB connector instead.
USBasp RST <-> Keyboard RESET
USBasp SCLK <-> Keyboard B1 (SCLK)
USBasp MOSI <-> Keyboard B2 (MOSI)
USBasp MISO <-> Keyboard B3 (MISO)
USBasp VCC <-> Keyboard VCC
USBasp GND <-> Keyboard GND
**AVRDUDE Programmer**: `buspirate`
**AVRDUDE Port**: Serial
### Teensy 2.0
#### Wiring
Teensy B0 <-> Keyboard RESET
Teensy B1 <-> Keyboard B1 (SCLK)
Teensy B2 <-> Keyboard B2 (MOSI)
Teensy B3 <-> Keyboard B3 (MISO)
Teensy VCC <-> Keyboard VCC
Teensy GND <-> Keyboard GND
!> Note that the B0 pin on the Teensy is wired to the RESET/RST pin on the keyboard's controller. ***DO NOT*** wire the RESET pin on the Teensy to the RESET on the keyboard.
### Pro Micro
Pro Micro 10 (B6) <-> Keyboard RESET
Pro Micro 15 (B1) <-> Keyboard B1 (SCLK)
Pro Micro 16 (B2) <-> Keyboard B2 (MOSI)
Pro Micro 14 (B3) <-> Keyboard B3 (MISO)
Pro Micro VCC <-> Keyboard VCC
Pro Micro GND <-> Keyboard GND
!> Note that the 10/B6 pin on the Pro Micro is wired to the RESET/RST pin on the keyboard's controller. ***DO NOT*** wire the RESET pin on the Pro Micro to the RESET on the keyboard.
## Flashing Your Keyboard
After you have your ISP programmer set up, and wired to your keyboard, it's time to flash your keyboard.
### The Bootloader File
The simplest and quickest way to get things back to normal is to flash only a bootloader to the keyboard. Once this is done, you can connect the keyboard normally and flash the keyboard like you normally would.
You can find the stock bootloaders in the [`util/` folder](https://github.com/qmk/qmk_firmware/tree/master/util). Be sure to flash the correct bootloader for your chip:
If you're not sure what your board uses, look in the `rules.mk` file for the keyboard in QMK. The `MCU` and `BOOTLOADER` lines will have the value you need. It may differ between different versions of the board.
### Production Techniques
If you'd like to flash both the bootloader **and** the regular firmware at the same time, there are two options to do so. Manually, or with the `:production` target when compiling.
To do this manually:
1. Open the original firmware .hex file in a text editor
2. Remove the last line (which should be `:00000001FF` - this is an EOF message)
3. Copy the entire bootloader's contents onto a new line (with no empty lines between) and paste it at the end of the original file
4. Save it as a new file by naming it `<keyboard>_<keymap>_production.hex`
|Bus Pirate|Keyboard|
|----------|--------|
|`+5V` |`VCC` |
|`GND` |`GND` |
|`RST` |`RESET` |
|`CLK` |`SCLK` |
|`MOSI` |`MOSI` |
|`MISO` |`MISO` |
?> It's possible to use other bootloaders here in the same way, but __you need a bootloader__, otherwise you'll have to use ISP again to write new firmware to your keyboard.
## Software
#### Create QMK DFU Bootloader and Production images
[QMK Toolbox](https://github.com/qmk/qmk_toolbox/releases) supports flashing both the ISP firmware and bootloader, but note that it cannot (currently) set the AVR fuse bytes for the actual ISP flashing step, so you may want to work with `avrdude` directly instead.
You can create the firmware, the QMK DFU Bootloader and the production firmware images for the board using the `:production` target when compiling. Once this is done, you'll see three files:
* `<keyboard>_<keymap>.hex`
* `<keyboard>_<keymap>_bootloader.hex`
* `<keyboard>_<keymap>_production.hex`
Setting up the [QMK environment](newbs.md) is highly recommended, as it automatically installs `avrdude` along with a host of other tools.
The QMK DFU bootloader has only really been tested on `atmega32u4` controllers (such as the AVR based Planck boards, and the Pro Micro), and hasn't been tested on other controllers. However, it will definitely not work on V-USB controllers, such as the `atmega32a` or `atmega328p`.
## Bootloader Firmware
You can flash either the bootloader or the production firmware file. The production firmware file will take a lot longer to flash, since it's flashing a lot more data.
One of these files is what you will be ISP flashing onto the board. The default fuses are also listed.
?> Note: You should stay with the same bootloader. If you're using DFU already, switching to QMK DFU is fine. But flashing QMK DFU onto a Pro Micro, for instance, has additional steps needed.
If you're not sure what your board uses, look in the `rules.mk` file for the keyboard in QMK. The `MCU` and `BOOTLOADER` lines will have the values you need. It may differ between different versions of the board.
## Flashing Your Bootloader/Production File
### Atmel DFU
Make sure your keyboard is unplugged from any device, and plug in your ISP Programmer.
These are the [factory default bootloaders](https://www.microchip.com/content/dam/mchp/documents/OTH/ProductDocuments/SoftwareLibraries/Firmware/megaUSB_DFU_Bootloaders.zip) shipped by Atmel (now Microchip). Note that the AT90USB64 and AT90USB128 bootloaders are [slightly modified](https://github.com/qmk/qmk_firmware/pull/14064), due to a bug causing them to not enumerate properly in Windows 8 and later.
If you want to change bootloader types, You'll need to use the command line.
1. `AVRISP device connected` or `USB Tiny device connected` will show up in yellow
2. Select the correct bootloader/production .hex file with the `Open` dialog (spaces can't be in the path)
3. Be sure the correct `Microcontroller` option for the keyboard you're flashing (not the ISP programmer) is selected
4. Hit `Flash`
5. Wait, as nothing will output for a while, especially with production files
This is the default Arduino-style bootloader derived from the [LUFA CDC bootloader](https://github.com/abcminiuser/lufa/tree/master/Bootloaders/CDC), and is only for the ATmega32U4.
If the verification and fuse checks are ok, you're done! Your board may restart automatically, otherwise, unplug your Teensy and plug in your keyboard - you can leave your Teensy wired to your keyboard while testing things, but it's recommended that you desolder it/remove the wiring once you're sure everything works.
There are several variants depending on the vendor, but they all mostly work the same way. The SparkFun variants, for example, require the `RESET` pin to be [grounded twice quickly](https://learn.sparkfun.com/tutorials/pro-micro--fio-v3-hookup-guide#ts-reset) in order to stay in bootloader mode for more than 750 ms.
|[SparkFun Pro Micro (3V3/8MHz)](https://github.com/sparkfun/Arduino_Boards/blob/master/sparkfun/avr/bootloaders/caterina/Caterina-promicro8.hex) |`0xFF`|`0xD8`|`0xFE` |`1B4F:9203`|
|[SparkFun Pro Micro (5V/16MHz)](https://github.com/sparkfun/Arduino_Boards/blob/master/sparkfun/avr/bootloaders/caterina/Caterina-promicro16.hex) |`0xFF`|`0xD8`|`0xFB` |`1B4F:9205`|
|[SparkFun LilyPadUSB (and some Pro Micro clones)](https://github.com/sparkfun/Arduino_Boards/blob/main/sparkfun/avr/bootloaders/caterina/Caterina-lilypadusb.hex)|`0xFF`|`0xD8`|`0xFE` |`1B4F:9207`|
Open a terminal (`cmd` on Windows, for instance) and navigate to your where your modified .hex file is. We'll pretend this file is called `main.hex`, and that your Teensy 2.0 is on the `COM3` port - if you're unsure, you can open your Device Manager, and look for `Ports > USB Serial Device`. Use that COM port here. You can confirm it's the right port with:
?> Files marked with a * have combined Arduino sketches, which runs by default and also appears as a serial port. However, this is *not* the bootloader device.
avrdude -c avrisp -P COM3 -p atmega32u4
### BootloadHID (PS2AVRGB)
and you should get something like the following output:
This bootloader is primarily for keyboards originally designed for the PS2AVRGB firmware and Bootmapper Client. It is not recommended for use in new designs.
avrdude: AVR device initialized and ready to accept instructions
USBaspLoader is a bootloader based on V-USB that emulates a hardware USBasp device. It runs on ATmega32A and ATmega328P MCUs.
avrdude: safemode: Fuses OK
Precompiled `.hex` files are generally not available, but you can compile it yourself by setting up the QMK environment and following Coseyfannitutti's guide for the appropriate MCU:
Since our keyboard uses an `atmega32u4` (common), that is the chip we'll specify. This is the full command:
Note that some boards may have their own specialized build of this bootloader in a separate repository. This will usually be linked to in the board's readme.
If your board uses an `atmega32a` (e.g. on a jj40), the command is this (the extra code at the end sets the fuses correctly):
Open a new Terminal window - if you are on Windows, use MSYS2 or QMK MSYS, not the Command Prompt. Navigate to the directory your bootloader `.hex` is in. Now it's time to run the `avrdude` command.
* `<programmer>` corresponds to the programmer type listed for each ISP flasher in the [Hardware](#hardware) section, for example `avrisp`.
* `<port>` is the serial port that appears when you plug the ISP flasher in, if any. For some programmers this is simply `usb` (or you can omit the `-P` argument completely) since they do not operate as a serial device.
* Windows: `COMx` - check Device Manager, under the "Ports (COM & LPT)" section
* Linux: `/dev/ttyACMx`
* macOS: `/dev/tty.usbmodemXXXXXX`
* `<mcu>` should be the lowercase name of the target AVR microcontroller, for example `atmega32u4`.
* `<filename>` is the absolute or relative path to the bootloader to be flashed, for example `Caterina-Micro.hex`.
avrdude: safemode: Fuses OK
You can also run `man avrdude` for more information.
avrdude done. Thank you.
If all goes well, you should get output similar to the following:
Which means everything should be ok! Your board may restart automatically, otherwise, unplug your Teensy and plug in your keyboard - you can leave your Teensy wired to your keyboard while testing things, but it's recommended that you desolder it/remove the wiring once you're sure everything works.
```
avrdude: AVR device initialized and ready to accept instructions
If you're using a SparkFun PocketAVR Programmer, or another USB Tiny based ISP programmer, you will want to use something like this:
If you're switching bootloaders, such as flashing QMK DFU on a Pro Micro, you will need to change the fuses, in additional to flashing the bootloader hex file. This is because `caterina` (the Pro Micro bootloader) and `dfu` handle the startup routines differently, and that behavior is controlled by the fuses.
avrdude: 32730 bytes of flash written
avrdude: verifying flash memory against Caterina-Micro.hex:
avrdude: load data flash data from input file Caterina-Micro.hex:
For this, we are assuming the 5V 16MHz versions of the `atmega32u4` (such as the 5V Pro Micro).
avrdude: verifying ...
avrdude: 32730 bytes of flash verified
For DFU on the `atmega32u4`, these are the fuse settings that you want:
avrdude: safemode: Fuses OK (E:CB, H:D8, L:FF)
| Fuse | Setting |
|----------|------------------|
| Low | `0x5E` |
| High | `0xD9` or `0x99` |
| Extended | `0xC3` |
avrdude done. Thank you.
```
The High fuse can be 0xD9 or 0x99. The difference is that 0xD9 disables JTAG, which QMK Firmware disables via software as well, while 0x99 doesn't disable JTAG.
### Setting the Fuses
To set this add `-U lfuse:w:0x5E:m -U hfuse:w:0xD9:m -U efuse:w:0xC3:m` to your command. So the final command should look something like:
This is a slightly more advanced topic, but may be necessary if you are switching from one bootloader to another (for example, Caterina to Atmel/QMK DFU on a Pro Micro). Fuses control some of the low-level functionality of the AVR microcontroller, such as clock speed, whether JTAG is enabled, and the size of the section of flash memory reserved for the bootloader, among other things. You can find a fuse calculator for many AVR parts [here](https://www.engbedded.com/conffuse/).
!> **WARNING:** Setting incorrect fuse values, in particular the clock-related bits, may render the MCU practically unrecoverable without high voltage programming (not covered here)! Make sure to double check the commands you enter before you execute them.
For Caterina on the `atmega32u4`, these are the fuse settings that you want:
To set the fuses, add the following to the `avrdude` command:
?> You may get a warning from `avrdude` that the extended fuse byte does not match what you provided when reading it back. If the second hex digit matches, this can usually be safely ignored, because the top four bits of this fuse do not actually exist on many AVR parts, and may read back as anything.
## Creating a "Production" Firmware
If you are using a different controller or want different configuration, you can use [this AVR Fuse Calculator](https://www.engbedded.com/fusecalc/) to find a better value for you.
For mass production purposes, it is possible to join the bootloader and QMK firmware together into a single file, due to the way the [Intel Hex format](https://en.wikipedia.org/wiki/Intel_HEX) works:
## Help
1. Open the QMK firmware and bootloader `.hex` files in a text editor.
2. Remove the last line of the QMK firmware (which should be `:00000001FF` - this is just an "end of file" marker).
3. Paste the contents of the bootloader `.hex` file onto a new line at the end of the QMK firmware file, with no empty lines between.
4. Save it as a new file, for example `<keyboard>_<keymap>_production.hex`.
If you have any questions/problems, feel free to [open an issue](https://github.com/qmk/qmk_firmware/issues/new)!
You can then ISP flash this combined firmware instead, which allows you to skip the extra step of flashing the QMK firmware over USB.
現在のところ、`MT()` の引数 `kc` は[基本的なキーコードセット](ja/keycodes_basic.md)に制限されています。つまり、`LCTL()`、`KC_TILD`、あるいは `0xFF` より大きなキーコードを使うことができません。これは、QMK が16ビットのキーコードを使うためです。3ビットは機能の識別のために使われ、1ビットは右または左の mod を選択するために使われ、4ビットはどの mod かを区別するために使われ、キーコードには8ビットしか残されていません。さらに、モッドタップで少なくとも1つの右手用のモディファイアが指定された場合、指定された全てのモディファイアが右手用になるため、2つをうまく組み合わせて一致させることはできません。例えば、左 Control と右 Shift は、右 Control と右 Shift になります。
original document: 0.13.15:docs/understanding_qmk.md
git diff 0.13.15 HEAD -- docs/understanding_qmk.md | cat
original document: 0.14.22:docs/understanding_qmk.md
git diff 0.14.22 HEAD -- docs/understanding_qmk.md | cat
-->
このドキュメントでは、QMK ファームウェアがどのように機能するかを非常に高いレベルから説明しようとしています。基本的なプログラミングの概念を理解していることを前提としていますが、(実例を示す必要がある場合を除き) C に精通していることを前提にはしていません。以下のドキュメントの基本的な知識があることを前提としています。
@ -61,6 +61,77 @@ You may also run into issues when using Remote Desktop Connection on Windows. Be
To fix this, open Remote Desktop Connection, click on "Show Options", open the the "Local Resources" tab, and in the keyboard section, change the drop down to "On this Computer". This will fix the issue, and allow the characters to work correctly.
It can also be mitigated by increasing [`TAP_CODE_DELAY`](config_options.md#behaviors-that-can-be-configured).
## Intercepting Mod-Taps
### Changing tap function
The basic keycode limitation with Mod-Tap can be worked around by intercepting it in `process_record_user`. For example, shifted keycode `KC_DQUO` cannot be used with `MT()` because it is a 16-bit keycode alias of `LSFT(KC_QUOT)`. Modifiers on `KC_DQUO` will be masked by `MT()`. But the following custom code can be used to intercept the "tap" function to manually send `KC_DQUO`:
return false; // Return false to ignore further processing of key
}
break;
}
return true;
}
```
### Changing hold function
Likewise, similar custom code can also be used to intercept the hold function to send custom user key code. The following example uses `LT(0, kc)` (layer-tap key with no practical use because layer 0 is always active) to add cut, copy and paste function to X,C and V keys when they are held down:
if (!record->tap.count && record->event.pressed) {
tap_code16(C(KC_X)); // Intercept hold function to send Ctrl-X
return false;
}
return true; // Return true for normal processing of tap keycode
case LT(0,KC_C):
if (!record->tap.count && record->event.pressed) {
tap_code16(C(KC_C)); // Intercept hold function to send Ctrl-C
return false;
}
return true; // Return true for normal processing of tap keycode
case LT(0,KC_V):
if (!record->tap.count && record->event.pressed) {
tap_code16(C(KC_V)); // Intercept hold function to send Ctrl-V
return false;
}
return true; // Return true for normal processing of tap keycode
}
return true;
}
```
Enabling `IGNORE_MOD_TAP_INTERRUPT` is recommended when using Mod-Tap on alphanumeric keys to avoid hold function taking precendence when the next key is pressed quickly. See [Ignore Mod Tap Interrupt](tap_hold.md#ignore-mod-tap-interrupt) for more details.
### Changing both tap and hold
This last example implements custom tap and hold function with `LT(0,KC_NO)` to create a single copy-on-tap, paste-on-hold key:
@ -4,22 +4,24 @@ This is a non-exhaustive checklist of what the QMK Collaborators will be checkin
If there are any inconsistencies with these recommendations, you're best off [creating an issue](https://github.com/qmk/qmk_firmware/issues/new) against this document, or getting in touch with a QMK Collaborator on [Discord](https://discord.gg/Uq7gcHh).
## General PRs
## Requirements for all PRs
- PR should be submitted using a non-`master` branch on the source repository
- this does not mean you target a different branch for your PR, rather that you're not working out of your own master branch
- if submitter _does_ use their own `master` branch, they'll be given a link to the ["how to git"](https://docs.qmk.fm/#/newbs_git_using_your_master_branch) page after merging -- (end of this document will contain the contents of the message)
- newly-added directories and filenames must be lowercase
- this rule may be relaxed if upstream sources originally had uppercase characters (e.g. ChibiOS, or imported files from other repositories etc.)
- if there is enough justification (i.e. consistency with existing core files etc.) this can be relaxed
- this rule may be relaxed if upstream sources originally had uppercase characters (e.g. LUFA, ChibiOS, or imported files from other repositories etc.)
- if there is valid justification (i.e. consistency with existing core files etc.) this can be relaxed
- a board designer naming their keyboard with uppercase letters is not enough justification
- valid license headers on all `*.c` and `*.h` source files
- GPL2/GPL3 recommended for consistency
- an example GPL2+ license header may be copied and modified from the bottom of this document
- other licenses are permitted, however they must be GPL-compatible and must allow for redistribution. Using a different license will almost certainly delay a PR getting merged.
- missing license headers will prevent PR merge due to ambiguity with license compatibility
- QMK Codebase "best practices" followed
- this is not an exhaustive list, and will likely get amended as time goes by
- `#pragma once` instead of `#ifndef` include guards in header files
- no "old-school" GPIO/I2C/SPI functions used -- must use QMK abstractions unless justifiable (and laziness is not valid justification)
- no "old-school" or other low-level GPIO/I2C/SPI functions may be used -- must use QMK abstractions unless justifiable (and laziness is not valid justification)
- timing abstractions should be followed too:
- `wait_ms()` instead of `_delay_ms()` (remove `#include <util/delay.h>` too)
- `timer_read()` and `timer_read32()` etc. -- see [timer.h](https://github.com/qmk/qmk_firmware/blob/master/tmk_core/common/timer.h) for the timing APIs
@ -28,7 +30,7 @@ If there are any inconsistencies with these recommendations, you're best off [cr
- discuss it with QMK Collaborators on Discord
- refactor it as a separate core change
- remove your specific copy in your board
- rebase and fix all merge conflicts before opening the PR (in case you need help or advice, reach out to QMK Collaborators on Discord)
- fix all merge conflicts before opening the PR (in case you need help or advice, reach out to QMK Collaborators on Discord)
- displays correctly in Configurator (press Ctrl+Shift+I to preview local file, turn on fast input to verify ordering)
- `readme.md`
- standard template should be present
- flash command has `:flash` at end
- standard template should be present -- [link to template](https://github.com/qmk/qmk_firmware/blob/master/data/templates/avr/readme.md)
- flash command is present, and has `:flash` at end
- valid hardware availability link (unless handwired) -- private groupbuys are okay, but one-off prototypes will be questioned. If open-source, a link to files should be provided.
- clear instructions on how to reset the board into bootloader mode
- a picture about the keyboard and preferably about the PCB, too
- images are not to be placed in the `qmk_firmware` repository
- images should be uploaded to an external image hosting service, such as [imgur](https://imgur.com/).
- `rules.mk`
- removed `MIDI_ENABLE`, `FAUXCLICKY_ENABLE` and `HD44780_ENABLE`
- modified `# Enable Bluetooth with the Adafruit EZ-Key HID` -> `# Enable Bluetooth`
- initialisation code for the matrix and critical devices
- mirroring existing functionality of a commercial board (like custom keycodes and special animations etc.) should be handled through non-`default` keymaps
- Vial-related files or changes will not be accepted, as they are not used by QMK firmware (no Vial-specific core code has been submitted or merged)
- `keyboard.c`
- `<keyboard>.c`
- empty `xxxx_xxxx_kb()` or other weak-defined default implemented functions removed
- commented-out functions removed too
- `matrix_init_board()` etc. migrated to `keyboard_pre_init_kb()`, see: [keyboard_pre_init*](https://docs.qmk.fm/#/custom_quantum_functions?id=keyboard_pre_init_-function-documentation)
- prefer `CUSTOM_MATRIX = lite` if custom matrix used, allows for standard debounce, see [custom matrix 'lite'](https://docs.qmk.fm/#/custom_matrix?id=lite)
- prefer LED indicator [Configuration Options](https://docs.qmk.fm/#/feature_led_indicators?id=configuration-options) to custom `led_update_*()` implementations where possible
- `keyboard.h`
- `<keyboard>.h`
- `#include "quantum.h"` appears at the top
- `LAYOUT` macros should use standard definitions if applicable
- use the Community Layout macro names where they apply (preferred above `LAYOUT`/`LAYOUT_all`)
- keymap `config.h`
- no duplication of `rules.mk` or `config.h` from keyboard
- `keymaps/default/keymap.c`
- `QMKBEST`/`QMKURL` removed (sheesh)
- `QMKBEST`/`QMKURL` removed
- if using `MO(_LOWER)` and `MO(_RAISE)` keycodes or equivalent, and the keymap has an adjust layer when holding both keys -- if the keymap has no "direct-to-adjust" keycode (such as `MO(_ADJUST)`) then you should prefer to write...
- submitters can have a personal (or bells-and-whistles) keymap showcasing capabilities in the same PR but it shouldn't be embedded in the 'default' keymap
- submitters can also have a "manufacturer-matching" keymap that mirrors existing functionality of the commercial product, if porting an existing board
- Do not include VIA json files in the PR. These do not belong in the QMK repository as they are not used by QMK firmware -- they belong in the [VIA Keyboard Repo](https://github.com/the-via/keyboards)
- Do not include source files from another keyboard or vendors keyboard folder. Including core files is fine.
- For instance, only `wilba_tech` boards using be including `keyboards/wilba_tech/wt_main.c` and `keyboards/wilba_tech/wt_rgb_backlight.c`. But including `drivers/sensors/pmw3360.c` is absolutely fine.
- Code that needs to be used by multiple boards is a candidate for core code changes, and should be separated out.
Also, specific to ChibiOS:
- **strong** preference to using existing ChibiOS board definitions.
@ -112,7 +118,7 @@ Also, specific to ChibiOS:
## Core PRs
- must now target `develop` branch, which will subsequently be merged back to `master` on the breaking changes timeline
- other notes TBD
- other requirements are at the discretion of QMK collaborators
- core is a lot more subjective given the breadth of posted changes
---
@ -134,6 +140,33 @@ Thanks for contributing!
## Review Process
In general, we want to see two (or more) approvals that are meaningful (e.g. that have inspected code) before a PR will be considered for merge. These reviews are not limited to collaborators -- any community member willing to put in the time is welcomed (and encouraged). The only difference is that your checkmark won't be green, and that's fine!
In general, we want to see two (or more) approvals that are meaningful (e.g. that have inspected code) before a PR will be considered for merge. These reviews are not limited to collaborators -- any community member willing to put in the time is welcomed (and encouraged). The only difference is that your checkmark won't be green, and that's fine!
Additionally, PR reviews are something that is done in our free time. We are not paid nor compensated for the time we spend reviewing, as it is a labor of love. As such, this means that it can take time for us to get to your Pull Request. Things like family, or life can get in the way of us getting to PRs, and burnout is a serious concern. The QMK firmware repository averages 200 PRs opened and 200 PRs merged every month, so please have patience.
## Example GPLv2 Header
```
/* Copyright 2021 Your Name (@yourgithub)
*
* This program is free software: you can redistribute it and/or modify
* it under the terms of the GNU General Public License as published by
* the Free Software Foundation, either version 2 of the License, or
* (at your option) any later version.
*
* This program is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU General Public License for more details.
*
* You should have received a copy of the GNU General Public License
* along with this program. If not, see <http://www.gnu.org/licenses/>.
*/
```
Or, optionally, using [SPDX identifier](https://spdx.org/licenses/) instead:
@ -9,33 +9,39 @@ You can create `info.json` files at every level under `qmk_firmware/keyboards/<n
The `info.json` file is a JSON formatted dictionary with the following keys available to be set. You do not have to set all of them, merely the keys that apply to your keyboard.
* `keyboard_name`
* A free-form text string describing the keyboard.
* Example: `Clueboard 66%`
* A free-form text string describing the keyboard.
* Example: `Clueboard 66%`
* `manufacturer`
* A free-form text string describing the keyboard's manufacturer.
* Example: `Clueboard`
* `url`
* A URL to the keyboard's product page, [QMK.fm/keyboards](https://qmk.fm/keyboards) page, or other page describing information about the keyboard.
* A URL to the keyboard's product page, [QMK.fm/keyboards](https://qmk.fm/keyboards) page, or other page describing information about the keyboard.
* Example: `https://clueboard.co`
* `maintainer`
* GitHub username of the maintainer, or `qmk` for community maintained boards
* GitHub username of the maintainer, or `qmk` for community maintained boards.
* Example: `skullydazed`
* `debounce`
* How many milliseconds (ms) to wait for debounce to happen. (Default: 5)
* The amount of time in milliseconds to wait for debounce to happen.
* Default: `5`
* `diode_direction`
* The direction diodes face. See [`DIRECT_PINS` in the hardware configuration](https://docs.qmk.fm/#/config_options?id=hardware-options) for more details.
* The direction diodes face. See [`DIRECT_PINS` in the hardware configuration](https://docs.qmk.fm/#/config_options?id=hardware-options) for more details.
* `layout_aliases`
* A dictionary containing layout aliases. The key is the alias and the value is a layout in `layouts` it maps to.
* A dictionary containing layout aliases. The key is the alias and the value is a layout in `layouts` it maps to.
* `layouts`
* Physical Layout representations. See the [Layout Format](#layout_format) section for more detail.
* Physical Layout representations. See the [Layout Format](#layout_format) section for more detail.
* `matrix_pins`
* Configure the pins corresponding to columns and rows, or direct pins. See [Matrix Pins](#matrix_pins) for more detail.
* Configure the pins corresponding to columns and rows, or direct pins. See the [Matrix Pins](#matrix_pins) section for more detail.
* `rgblight`
* Configure the [RGB Lighting feature](feature_rgblight.md). See the [RGB Lighting](#rgb_lighting) section for more detail.
* Configure the [RGB Lighting feature](feature_rgblight.md). See the [RGB Lighting](#rgb_lighting) section for more detail.
* `usb`
* Configure USB VID, PID, and other parameters. See [USB](#USB) for more detail.
* Configure USB VID, PID, and other parameters. See the [USB](#USB) section for more detail.
### Layout Format
Within our `info.json` file the `layouts` portion of the dictionary contains several nested dictionaries. The outer layer consists of QMK layout macros, for example `LAYOUT_ansi` or `LAYOUT_iso`.
* `layout`
* A list of Key Dictionaries describing the physical layout. See the next section for more details.
* A list of Key Dictionaries describing the physical layout. See the next section for more details.
### Key Dictionary Format
@ -44,18 +50,20 @@ Each Key Dictionary in a layout describes the physical properties of a key. If y
All key positions and rotations are specified in relation to the top-left corner of the keyboard, and the top-left corner of each key.
* `x`
* **Required**: The absolute position of the key in the horizontal axis, in Key Units.
* **Required**. The absolute position of the key in the horizontal axis, in Key Units.
* `y`
* **Required**: The absolute position of the key in the vertical axis, in Key Units.
* **Required**. The absolute position of the key in the vertical axis, in Key Units.
* `w`
* The width of the key, in Key Units. Ignored if `ks` is provided. Default: `1`
* The width of the key, in Key Units.
* Default: `1`
* `h`
* The height of the key, in Key Units. Ignored if `ks` is provided. Default: `1`
* The height of the key, in Key Units.
* Default: `1`
* `label`
* What to name this position in the matrix.
* This should usually correspond to the keycode for the first layer of the default keymap.
* What to name this position in the matrix. This should usually correspond to the keycode for the first layer of the default keymap.
* `matrix`
* A 2 item list describing the row and column location for this key.
* A two item list describing the row and column location for this key.
@ -10,11 +10,11 @@ Custom keyboard designed by RealEmanGaming aka 0xC7
Make example for this keyboard (after setting up your build environment):
make 61key:default
make 0xc7/61key:default
Flashing example for this keyboard:
make 61key:default:flash
make 0xc7/61key:default:flash
See the [build environment setup](https://docs.qmk.fm/#/getting_started_build_tools) and the [make instructions](https://docs.qmk.fm/#/getting_started_make_guide) for more information. Brand new to QMK? Start with our [Complete Newbs Guide](https://docs.qmk.fm/#/newbs).
Drashna Jael're
2 years ago