gitbot/qmk_firmware
0
0
Fork 0
mirror of https://github.com/qmk/qmk_firmware.git synced 2025-07-17 13:12:08 +00:00
Code Issues Packages Projects Releases Wiki Activity

Merge branch 'master' of https://github.com/qmk/qmk_firmware

Browse Source
This commit is contained in:
Takeshi Nishio 2020-07-08 20:41:28 +09:00
commit 3faa0fe82c
2229 changed files with 98983 additions and 24341 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

49
.github/workflows/info.yml vendored Normal file
View File

@ -0,0 +1,49 @@
name: PR Lint keyboards
on:
pull_request:
paths:
- 'keyboards/**'
jobs:
info:
runs-on: ubuntu-latest
container: qmkfm/base_container
steps:
- uses: actions/checkout@v2
with:
fetch-depth: 0
- name: Print info
run: |
git rev-parse --short HEAD
echo ${{ github.event.pull_request.base.sha }}
git diff --name-only ${{ github.event.pull_request.base.sha }}...
- name: Run qmk info
shell: 'bash {0}'
run: |
QMK_CHANGES=$(git diff --name-only ${{ github.event.pull_request.base.sha }}...)
QMK_KEYBOARDS=$(qmk list-keyboards)
exit_code=0
for KB in $QMK_KEYBOARDS; do
KEYBOARD_CHANGES=$(echo "$QMK_CHANGES" | grep -E '^(keyboards/'${KB}'/)')
if [[ -z "$KEYBOARD_CHANGES" ]]; then
# skip as no changes for this keyboard
continue
fi
KEYMAP_ONLY=$(echo "$KEYBOARD_CHANGES" | grep -cv /keymaps/)
if [[ $KEYMAP_ONLY -gt 0 ]]; then
echo "linting ${KB}"
# TODO: info info always returns 0 - right now the only way to know failure is to inspect log lines
qmk info -kb ${KB} 2>&1 | tee /tmp/$$
!(grep -cq ☒ /tmp/$$)
: $((exit_code = $exit_code + $?))
fi
done
exit $exit_code

8
.gitmodules vendored
View File

@ -12,7 +12,13 @@
branch = master
[submodule "lib/googletest"]
path = lib/googletest
url = https://github.com/google/googletest
url = https://github.com/qmk/googletest
[submodule "lib/lufa"]
path = lib/lufa
url = https://github.com/qmk/lufa
[submodule "lib/vusb"]
path = lib/vusb
url = https://github.com/qmk/v-usb
[submodule "lib/printf"]
path = lib/printf
url = https://github.com/qmk/printf

10
Makefile
View File

@ -294,8 +294,8 @@ define PARSE_RULE
$$(info | QMK's make format recently changed to use folder locations and colons:)
$$(info | make project_folder:keymap[:target])
$$(info | Examples:)
$$(info | make planck/rev4:default:dfu)
$$(info | make planck:default)
$$(info | make dz60:default)
$$(info | make planck/rev6:default:flash)
$$(info |)
endif
endef
@ -562,14 +562,16 @@ endef
%:
# Check if we have the CMP tool installed
cmp $(ROOT_DIR)/Makefile $(ROOT_DIR)/Makefile >/dev/null 2>&1; if [ $$? -gt 0 ]; then printf "$(MSG_NO_CMP)"; exit 1; fi;
# Ensure that python3 is installed. This check can be removed after python is used in more places.
if ! python3 --version 1> /dev/null 2>&1; then printf "$(MSG_PYTHON_MISSING)"; fi
# Ensure that bin/qmk works. This will be a failing check after the next develop merge on 2020 Aug 29.
if ! bin/qmk hello 1> /dev/null 2>&1; then printf "$(MSG_PYTHON_MISSING)"; fi
# Check if the submodules are dirty, and display a warning if they are
ifndef SKIP_GIT
if [ ! -e lib/chibios ]; then git submodule sync lib/chibios && git submodule update --depth 50 --init lib/chibios; fi
if [ ! -e lib/chibios-contrib ]; then git submodule sync lib/chibios-contrib && git submodule update --depth 50 --init lib/chibios-contrib; fi
if [ ! -e lib/ugfx ]; then git submodule sync lib/ugfx && git submodule update --depth 50 --init lib/ugfx; fi
if [ ! -e lib/lufa ]; then git submodule sync lib/lufa && git submodule update --depth 50 --init lib/lufa; fi
if [ ! -e lib/vusb ]; then git submodule sync lib/vusb && git submodule update --depth 50 --init lib/vusb; fi
if [ ! -e lib/printf ]; then git submodule sync lib/printf && git submodule update --depth 50 --init lib/printf; fi
git submodule status --recursive 2>/dev/null | \
while IFS= read -r x; do \
case "$$x" in \

2
Vagrantfile vendored
View File

@ -89,7 +89,7 @@ Vagrant.configure(2) do |config|
Examples:
make planck/rev4:default:dfu
make planck:default
make planck/rev4:default
EOT
end

13
build_layout.mk
View File

@ -3,8 +3,14 @@ LAYOUTS_REPOS := $(patsubst %/,%,$(sort $(dir $(wildcard $(LAYOUTS_PATH)/*/))))
define SEARCH_LAYOUTS_REPO
LAYOUT_KEYMAP_PATH := $$(LAYOUTS_REPO)/$$(LAYOUT)/$$(KEYMAP)
LAYOUT_KEYMAP_JSON := $$(LAYOUT_KEYMAP_PATH)/keymap.json
LAYOUT_KEYMAP_C := $$(LAYOUT_KEYMAP_PATH)/keymap.c
ifneq ("$$(wildcard $$(LAYOUT_KEYMAP_C))","")
ifneq ("$$(wildcard $$(LAYOUT_KEYMAP_JSON))","")
-include $$(LAYOUT_KEYMAP_PATH)/rules.mk
KEYMAP_C := $(KEYBOARD_OUTPUT)/src/keymap.c
KEYMAP_JSON := $$(LAYOUT_KEYMAP_JSON)
KEYMAP_PATH := $$(LAYOUT_KEYMAP_PATH)
else ifneq ("$$(wildcard $$(LAYOUT_KEYMAP_C))","")
-include $$(LAYOUT_KEYMAP_PATH)/rules.mk
KEYMAP_C := $$(LAYOUT_KEYMAP_C)
KEYMAP_PATH := $$(LAYOUT_KEYMAP_PATH)
@ -24,4 +30,7 @@ ifneq ($(FORCE_LAYOUT),)
endif
endif
$(foreach LAYOUT,$(LAYOUTS),$(eval $(call SEARCH_LAYOUTS)))
$(foreach LAYOUT,$(LAYOUTS),$(eval $(call SEARCH_LAYOUTS)))
# Use rule from build_json.mk, but update prerequisite in case KEYMAP_JSON was updated
$(KEYBOARD_OUTPUT)/src/keymap.c: $(KEYMAP_JSON)

16
common_features.mk
View File

@ -70,7 +70,7 @@ ifeq ($(strip $(POINTING_DEVICE_ENABLE)), yes)
SRC += $(QUANTUM_DIR)/pointing_device.c
endif
VALID_EEPROM_DRIVER_TYPES := vendor custom transient i2c
VALID_EEPROM_DRIVER_TYPES := vendor custom transient i2c spi
EEPROM_DRIVER ?= vendor
ifeq ($(filter $(EEPROM_DRIVER),$(VALID_EEPROM_DRIVER_TYPES)),)
$(error EEPROM_DRIVER="$(EEPROM_DRIVER)" is not a valid EEPROM driver)
@ -85,6 +85,11 @@ else
COMMON_VPATH += $(DRIVER_PATH)/eeprom
QUANTUM_LIB_SRC += i2c_master.c
SRC += eeprom_driver.c eeprom_i2c.c
else ifeq ($(strip $(EEPROM_DRIVER)), spi)
OPT_DEFS += -DEEPROM_DRIVER -DEEPROM_SPI
COMMON_VPATH += $(DRIVER_PATH)/eeprom
QUANTUM_LIB_SRC += spi_master.c
SRC += eeprom_driver.c eeprom_spi.c
else ifeq ($(strip $(EEPROM_DRIVER)), transient)
OPT_DEFS += -DEEPROM_DRIVER -DEEPROM_TRANSIENT
COMMON_VPATH += $(DRIVER_PATH)/eeprom
@ -139,7 +144,7 @@ ifeq ($(strip $(RGBLIGHT_ENABLE)), yes)
endif
endif
VALID_MATRIX_TYPES := yes IS31FL3731 IS31FL3733 IS31FL3737 WS2812 custom
VALID_MATRIX_TYPES := yes IS31FL3731 IS31FL3733 IS31FL3737 IS31FL3741 WS2812 custom
LED_MATRIX_ENABLE ?= no
ifneq ($(strip $(LED_MATRIX_ENABLE)), no)
@ -200,6 +205,13 @@ ifeq ($(strip $(RGB_MATRIX_ENABLE)), IS31FL3737)
QUANTUM_LIB_SRC += i2c_master.c
endif
ifeq ($(strip $(RGB_MATRIX_ENABLE)), IS31FL3741)
OPT_DEFS += -DIS31FL3741 -DSTM32_I2C -DHAL_USE_I2C=TRUE
COMMON_VPATH += $(DRIVER_PATH)/issi
SRC += is31fl3741.c
QUANTUM_LIB_SRC += i2c_master.c
endif
ifeq ($(strip $(RGB_MATRIX_ENABLE)), WS2812)
OPT_DEFS += -DWS2812
WS2812_DRIVER_REQUIRED := yes

239
docs/ChangeLog/20200530.md Normal file
View File

@ -0,0 +1,239 @@
# QMK Breaking Change - 2020 May 30 Changelog
Four times a year QMK runs a process for merging Breaking Changes. A Breaking Change is any change which modifies how QMK behaves in a way that is incompatible or potentially dangerous. We limit these changes to 4 times per year so that users can have confidence that updating their QMK tree will not break their keymaps.
The list of changes follows.
## Core Changes
### Converting V-USB usbdrv to a submodule
[#8321](https://github.com/qmk/qmk_firmware/pull/8321) and [qmk_compiler#62](https://github.com/qmk/qmk_compiler/pull/62).
These PRs move the V-USB driver code out of the qmk_firmware repository and into a submodule pointed at https://github.com/obdev/v-usb. This will make it easier to update the codebase if needed, while applying any potential QMK-specific modifications by forking it to the QMK GitHub organization.
### Unify Tap Hold functions and documentation
[#8348](https://github.com/qmk/qmk_firmware/pull/8348)
Updates all of the per key tap-hold functions to pass the `keyrecord_t` structure, and include documentation changes.
Any remaining versions or code outside of the main repo will need to be converted:
| Old function | New Function |
|------------------------------------------------------|---------------------------------------------------------------------------|
|`uint16_t get_tapping_term(uint16_t keycode)` |`uint16_t get_tapping_term(uint16_t keycode, keyrecord_t *record)` |
|`bool get_ignore_mod_tap_interrupt(uint16_t keycode)` |`bool get_ignore_mod_tap_interrupt(uint16_t keycode, keyrecord_t *record)` |
### Python Required In The Build Process
[#9000](https://github.com/qmk/qmk_firmware/pull/9000)
This is the last release of QMK that will work without having Python 3.6 (or later) installed. If your environment is not fully setup you will get a warning instructing you to set it up.
After the next breaking change you will not be able to build if `bin/qmk hello` does not work.
### Upgrade from tinyprintf to mpaland/printf
[#8269](https://github.com/qmk/qmk_firmware/pull/8269)
- Provides debug functionality on ChibiOS/ARM that is more compliant than previous integrations.
- Less maintenence, fewer QMK customisations, and allows QMK to sidestep previous compile and runtime issues.
- A `make git-submodule` may be required after pulling the latest QMK Firmware code to update to the new dependency.
### Fixed RGB_DISABLE_AFTER_TIMEOUT to be seconds based & small internals cleanup
[#6480](https://github.com/qmk/qmk_firmware/pull/6480)
- Changes `RGB_DISABLE_AFTER_TIMEOUT` to be based on milliseconds instead of ticks.
- Includes a code cleanup, resulting in a savings of 100 bytes, depending on features used.
- Fixed issues with timeouts / suspending at the wrong time not turning off all LEDs in some cases.
The `RGB_DISABLE_AFTER_TIMEOUT` definition is now deprecated, and has been superseded by `RGB_DISABLE_TIMEOUT`. To use the new definition, rename `RGB_DISABLE_AFTER_TIMEOUT` to `RGB_DISABLE_TIMEOUT` in your `config.h` file, and multiply the value set by 1200.
Before: `#define RGB_DISABLE_AFTER_TIMEOUT 100`
After: `#define RGB_DISABLE_TIMEOUT 120000`
### Switch to qmk forks for everything
[#9019](https://github.com/qmk/qmk_firmware/pull/9019)
Fork all QMK submodules to protect against upstream repositories disappearing.
### code cleanup regarding deprecated macro PLAY_NOTE_ARRAY by replacing it with PLAY_SONG
[#8484](https://github.com/qmk/qmk_firmware/pull/8484)
Removes the deprecated `PLAY_NOTE_ARRAY` macro. References to it are replaced with `PLAY_SONG`, which references the same function.
### fixing wrong configuration of AUDIO feature
[#8903](https://github.com/qmk/qmk_firmware/pull/8903) and [#8974](https://github.com/qmk/qmk_firmware/pull/8974)
`audio_avr.c` does not default to any pin; there has to be a #define XX_AUDIO in config.h at some level for Audio to actually work. Otherwise, the Audio code ends up cluttering the firmware, possibly breaking builds because the maximum allowed firmware size is exceeded.
These changes fix this by disabling Audio on keyboards that have the feature misconfigured, and therefore non-functional.
Also, add a compile-time error to alert the user to a missing pin-configuration (on AVR boards) when `AUDIO_ENABLE = yes` is set.
## Keyboard Refactors
### Migrating Lily58 to use split_common
[#6260](https://github.com/qmk/qmk_firmware/pull/6260)
Modifies the default firmware for Lily58 to use the `split_common` library, instead of including and depending on its own set of libraries for the following functionality:
- SSD1306 display
- i2c for OLED
- Serial Communication
This allows current lily58 firmware to advance with updates to the `split_common` library, which is shared with many other split keyboards.
#### To migrate existing Lily58 firmware:
[Changes to `config.h`](https://github.com/qmk/qmk_firmware/pull/6260/files#diff-445ac369c8717dcd6fc6fc3630836fc1):
- Remove `#define SSD1306OLED` from config.h
[Changes to `keymap.c`](https://github.com/qmk/qmk_firmware/pull/6260/files#diff-20943ea59856e9bdf3d99ecb2eee40b7):
- Find/Replace each instance of `#ifdef SSD1306OLED` with `#ifdef OLED_DRIVER_ENABLE`
- The following changes are for compatibility with the OLED driver. If you don't use the OLED driver you may safely delete [this section](https://github.com/qmk/qmk_firmware/blob/e6b9980bd45c186f7360df68c24b6e05a80c10dc/keyboards/lily58/keymaps/default/keymap.c#L144-L190)
- Alternatively, if you did not change the OLED code from that in `default`, you may find it easier to simply copy the [relevant section](https://github.com/qmk/qmk_firmware/blob/4ac310668501ae6786c711ecc8f01f62ddaa1c0b/keyboards/lily58/keymaps/default/keymap.c#L138-L172). Otherwise, the changes you need to make are as follows (sample change [here](https://github.com/qmk/qmk_firmware/pull/6260/files#diff-20943ea59856e9bdf3d99ecb2eee40b7R138-R173))
- [Remove](https://github.com/qmk/qmk_firmware/pull/6260/files#diff-20943ea59856e9bdf3d99ecb2eee40b7L138-L141) the block
```c
#ifdef SSD1306OLED
iota_gfx_init(!has_usb()); // turns on the display
#endif
```
- Within the block bounded by `#ifdef OLED_DRIVER_ENABLE` and `#endif // OLED_DRIVER_ENABLE`, add the following block to ensure that your two OLEDs are rotated correctly across the left and right sides:
```c
oled_rotation_t oled_init_user(oled_rotation_t rotation) {
if (!is_keyboard_master())
return OLED_ROTATION_180; // flips the display 180 degrees if offhand
return rotation;
}
```
- Remove the functions `matrix_scan_user`, `matrix_update` and `iota_gfx_task_user`
- Find/Replace `matrix_render_user(struct CharacterMatrix *matrix)` with `iota_gfx_task_user(void)`
- Find/Replace `is_master` with `is_keyboard_master()`
- For each instance of `matrix_write_ln(matrix, display_fn())`, rewrite it as `oled_write_ln(read_layer_state(), false);`
- For each instance of `matrix_write(matrix, read_logo());`, replace with `oled_write(read_logo(), false);`
### Refactor zinc to use split_common
[#7114](https://github.com/qmk/qmk_firmware/pull/7114) and [#9171](https://github.com/qmk/qmk_firmware/pull/9171)
* Refactor to use split_common and remove split codes under the zinc/revx/
* Add - backlight RGB LED and/or underglow RGB LED option
* Add - continuous RGB animations feature (between L and R halves)
* Fix - keymap files to adapt to changes
* all authors of keymaps confirmed this PR
* Update - documents and rules.mk
### Refactor of TKC1800 to use common OLED code
[#8472](https://github.com/qmk/qmk_firmware/pull/8472)
Modifies the default firmware for TKC1800 to use the in-built I2C and OLED drivers, instead of including and depending on its own set of libraries for the following functionality:
- SSD1306 display
- i2c for OLED
This allows current TKC1800 firmware to advance with updates to those drivers, which are shared with other keyboards.
#### To migrate existing TKC1800 firmware:
[Changes to `config.h`](https://github.com/qmk/qmk_firmware/pull/8472/files#diff-d10b26e676b4a55cbb00d71955116526):
- Remove `#define SSD1306OLED` from config.h
[Changes to `tkc1800.c`](https://github.com/qmk/qmk_firmware/pull/8472/files#diff-3b35bd30abe89c8110717c6972cd2cc5):
- Add the following to avoid debug errors on HID_listen if the screen is not present
```c
void keyboard_pre_init_kb(void) {
setPinInputHigh(D0);
setPinInputHigh(D1);
keyboard_pre_init_user();
}
```
[Changes to `keymap.c`](https://github.com/qmk/qmk_firmware/pull/8472/files#diff-05a2a344ce27e4d045fe68520ccd4771):
- Find/Replace each instance of `#ifdef SSD1306OLED` with `#ifdef OLED_DRIVER_ENABLE`
- The following changes are for compatibility with the OLED driver. If you don't use the OLED driver you may safely delete [this section](https://github.com/qmk/qmk_firmware/blob/e6b9980bd45c186f7360df68c24b6e05a80c10dc/keyboards/lily58/keymaps/default/keymap.c#L144-L190)
- [Remove](https://github.com/qmk/qmk_firmware/pull/6260/files#diff-20943ea59856e9bdf3d99ecb2eee40b7L91-L158) the block
```c
#ifdef SSD1306OLED
iota_gfx_init(!has_usb()); // turns on the display
#endif
```
- Within the block bounded by `#ifdef OLED_DRIVER_ENABLE` and `#endif // OLED_DRIVER_ENABLE`, add the following block to ensure that your two OLEDs are rotated correctly across the left and right sides:
```c
oled_rotation_t oled_init_user(oled_rotation_t rotation) {
if (!is_keyboard_master())
return OLED_ROTATION_180; // flips the display 180 degrees if offhand
return rotation;
}
```
- Remove the function `iota_gfx_task_user`
### Split HHKB to ANSI and JP layouts and Add VIA support for each
[#8582](https://github.com/qmk/qmk_firmware/pull/8582)
- Splits the HHKB codebase into two separate folders `keyboards/hhkb/ansi` and `keyboards/hhkb/jp`.
- Adds VIA Configurator support for both versions.
#### Migrating existing HHKB keymaps
- Remove any checks for the `HHKB_JP` definition
- All checks for this definition have been removed, and each version uses the source that is appropriate to that version.
- Move the directory for your keymap into the appropriate `keymaps` directory
- `keyboards/hhkb/ansi/keymaps/` for ANSI HHKBs
- `keyboards/hhkb/jp/keymaps/` for HHKB JPs
- Compile with the new keyboard names
- This PR changes the compilation instructions for the HHKB Alternate Controller. To compile firmware for this controller moving forward, use:
- `make hhkb/ansi` for ANSI-layout HHKBs
- `make hhkb/jp` for HHKB JP keyboards
## Keyboard Moves
- [#8412](https://github.com/qmk/qmk_firmware/pull/8412 "Changing board names to prevent confusion") by blindassassin111
- [#8499](https://github.com/qmk/qmk_firmware/pull/8499 "Move the Keyboardio Model01 to a keyboardio/ subdir") by algernon
- [#8830](https://github.com/qmk/qmk_firmware/pull/8830 "Move spaceman keyboards") by Spaceman (formerly known as Rionlion100)
- [#8537](https://github.com/qmk/qmk_firmware/pull/8537 "Organizing my keyboards (plaid, tartan, ergoinu)") by hsgw
Keyboards by Keyboardio, Spaceman, and hsgw move to vendor folders, while PCBs designed by blindassassin111 are renamed.
Old Name | New Name
:----------------- | :-----------------
2_milk | spaceman/2_milk
at101_blackheart | at101_bh
ergoinu | dm9records/ergoinu
model01 | keyboardio/model01
omnikey_blackheart | omnikey_bh
pancake | spaceman/pancake
plaid | dm9records/plaid
tartan | dm9records/tartan
z150_blackheart | z150_bh
If you own one of these PCBs, please use the new names to compile your firmware moving forward.
## Keycode Migration PRs
[#8954](https://github.com/qmk/qmk_firmware/pull/8954 "Migrate `ACTION_LAYER_TOGGLE` to `TG()`"), [#8957](https://github.com/qmk/qmk_firmware/pull/8957 "Migrate `ACTION_MODS_ONESHOT` to `OSM()`"), [#8958](https://github.com/qmk/qmk_firmware/pull/8958 "Migrate `ACTION_DEFAULT_LAYER_SET` to `DF()`"), [#8959](https://github.com/qmk/qmk_firmware/pull/8959 "Migrate `ACTION_LAYER_MODS` to `LM()`"), [#8968](https://github.com/qmk/qmk_firmware/pull/8968 "Migrate `ACTION_MODS_TAP_KEY` to `MT()`"), [#8977](https://github.com/qmk/qmk_firmware/pull/8977 "Migrate miscellaneous `fn_actions` entries"), and [#8979](https://github.com/qmk/qmk_firmware/pull/8979 "Migrate `ACTION_MODS_KEY` to chained mod keycodes")
Authored by fauxpark, these pull requests remove references to deprecated TMK macros that have been superseded by native QMK keycodes.
Old `fn_actions` action | New QMK keycode
:---------------------- | :--------------
`ACTION_DEFAULT_LAYER_SET(layer)` | `DF(layer)`
`ACTION_LAYER_MODS(layer, mod)` | `LM(layer, mod)`
`ACTION_LAYER_ONESHOT(mod)` | `OSL(mod)`
`ACTION_LAYER_TOGGLE(layer)` | `TG(layer)`
`ACTION_MODS_ONESHOT(mod)` | `OSM(mod)`
`ACTION_MODS_TAP_KEY(mod, kc)` | `MT(mod, kc)`
`ACTION_MODS_KEY(mod, kc)`<br>e.g. `ACTION_MODS_KEY(MOD_LCTL, KC_0)` | `MOD(kc)`<br>e.g. `LCTL(KC_0)`

8
docs/_summary.md
View File

@ -34,7 +34,9 @@
* [Customizing Functionality](custom_quantum_functions.md)
* [Driver Installation with Zadig](driver_installation_zadig.md)
* [Keymap Overview](keymap.md)
* [Vagrant Guide](getting_started_vagrant.md)
* Development Environments
* [Docker Guide](getting_started_docker.md)
* [Vagrant Guide](getting_started_vagrant.md)
* Flashing
* [Flashing](flashing.md)
* [Flashing ATmega32A (ps2avrgb)](flashing_bootloadhid.md)
@ -53,6 +55,7 @@
* Simple Keycodes
* [Full List](keycodes.md)
* [Basic Keycodes](keycodes_basic.md)
* [Language-Specific Keycodes](reference_keymap_extras.md)
* [Modifier Keys](feature_advanced_keycodes.md)
* [Quantum Keycodes](quantum_keycodes.md)
@ -112,6 +115,7 @@
* [Overview](breaking_changes.md)
* [My Pull Request Was Flagged](breaking_changes_instructions.md)
* History
* [2020 May 30](ChangeLog/20200530.md)
* [2020 Feb 29](ChangeLog/20200229.md)
* [2019 Aug 30](ChangeLog/20190830.md)
@ -126,6 +130,7 @@
* [SPI Driver](spi_driver.md)
* [WS2812 Driver](ws2812_driver.md)
* [EEPROM Driver](eeprom_driver.md)
* ['serial' Driver](serial_driver.md)
* [GPIO Controls](internals_gpio_control.md)
* [Keyboard Guidelines](hardware_keyboard_guidelines.md)
@ -140,6 +145,7 @@
* Hardware Platform Development
* Arm/ChibiOS
* [Selecting an MCU](platformdev_selecting_arm_mcu.md)
* [Early initialization](platformdev_chibios_earlyinit.md)
* QMK Reference

4
docs/adc_driver.md
View File

@ -22,7 +22,7 @@ Then place this include at the top of your code:
### AVR
|Channel|AT90USB64/128|ATmega16/32U4|ATmega32A|ATmega328P|
|Channel|AT90USB64/128|ATmega16/32U4|ATmega32A|ATmega328/P|
|-------|-------------|-------------|---------|----------|
|0 |`F0` |`F0` |`A0` |`C0` |
|1 |`F1` |`F1` |`A1` |`C1` |
@ -39,7 +39,7 @@ Then place this include at the top of your code:
|12 | |`B5` | | |
|13 | |`B6` | | |
<sup>\* The ATmega328P possesses two extra ADC channels; however, they are not present on the DIP pinout, and are not shared with GPIO pins. You can use `adc_read()` directly to gain access to these.</sup>
<sup>\* The ATmega328/P possesses two extra ADC channels; however, they are not present on the DIP pinout, and are not shared with GPIO pins. You can use `adc_read()` directly to gain access to these.</sup>
### ARM

47
docs/breaking_changes.md
View File

@ -6,27 +6,28 @@ The breaking change period is when we will merge PR's that change QMK in dangero
## What has been included in past Breaking Changes?
* [2020 May 30](ChangeLog/20200530.md)
* [2020 Feb 29](ChangeLog/20200229.md)
* [2019 Aug 30](ChangeLog/20190830.md)
## When is the next Breaking Change?
The next Breaking Change is scheduled for May 30, 2020.
The next Breaking Change is scheduled for Aug 29, 2020.
### Important Dates
* [x] 2020 Feb 29 - `future` is created. It will be rebased weekly.
* [ ] 2020 May 2 - `future` closed to new PR's.
* [ ] 2020 May 2 - Call for testers.
* [ ] 2020 May 28 - `master` is locked, no PR's merged.
* [ ] 2020 May 30 - Merge `future` to `master`.
* [ ] 2020 May 30 - `master` is unlocked. PR's can be merged again.
* [x] 2020 May 30 - `develop` is created. It will be rebased weekly.
* [ ] 2020 Aug 1 - `develop` closed to new PR's.
* [ ] 2020 Aug 1 - Call for testers.
* [ ] 2020 Aug 27 - `master` is locked, no PR's merged.
* [ ] 2020 Aug 29 - Merge `develop` to `master`.
* [ ] 2020 Aug 29 - `master` is unlocked. PR's can be merged again.
## What changes will be included?
To see a list of breaking change candidates you can look at the [`breaking_change` label](https://github.com/qmk/qmk_firmware/pulls?q=is%3Aopen+label%3Abreaking_change+is%3Apr). New changes might be added between now and when `future` is closed, and a PR with that label applied is not guaranteed to be merged.
To see a list of breaking change candidates you can look at the [`breaking_change` label](https://github.com/qmk/qmk_firmware/pulls?q=is%3Aopen+label%3Abreaking_change+is%3Apr). New changes might be added between now and when `develop` is closed, and a PR with that label applied is not guaranteed to be merged.
If you want your breaking change to be included in this round you need to create a PR with the `breaking_change` label and have it accepted before `future` closes. After `future` closes no new breaking changes will be accepted.
If you want your breaking change to be included in this round you need to create a PR with the `breaking_change` label and have it accepted before `develop` closes. After `develop` closes no new breaking changes will be accepted.
Criteria for acceptance:
@ -37,9 +38,9 @@ Criteria for acceptance:
This section documents various processes we use when running the Breaking Changes process.
## Rebase `future` from `master`
## Rebase `develop` from `master`
This is run every Friday while `future` is open.
This is run every Friday while `develop` is open.
Process:
@ -47,31 +48,31 @@ Process:
cd qmk_firmware
git checkout master
git pull --ff-only
git checkout future
git checkout develop
git rebase master
git push --force
```
## Creating the `future` branch
## Creating the `develop` branch
This happens immediately after the previous `future` branch is merged.
This happens immediately after the previous `develop` branch is merged.
* `qmk_firmware` git commands
* [ ] `git checkout master`
* [ ] `git pull --ff-only`
* [ ] `git checkout -b future`
* [ ] `git checkout -b develop`
* [ ] Edit `readme.md`
* [ ] Add a big notice at the top that this is a testing branch.
* [ ] Include a link to this document
* [ ] `git commit -m 'Branch point for <DATE> Breaking Change'`
* [ ] `git tag breakpoint_<YYYY>_<MM>_<DD>`
* [ ] `git tag <next_version>` # Prevent the breakpoint tag from confusing version incrementing
* [ ] `git push origin future`
* [ ] `git push origin develop`
* [ ] `git push --tags`
## 4 Weeks Before Merge
* `future` is now closed to new PR's, only fixes for current PR's may be merged
* `develop` is now closed to new PR's, only fixes for current PR's may be merged
* Post call for testers
* [ ] Discord
* [ ] GitHub PR
@ -94,15 +95,15 @@ This happens immediately after the previous `future` branch is merged.
## Day Of Merge
* `qmk_firmware` git commands
* [ ] `git checkout future`
* [ ] `git checkout develop`
* [ ] `git pull --ff-only`
* [ ] `git rebase origin/master`
* [ ] Edit `readme.md`
* [ ] Remove the notes about `future`
* [ ] Remove the notes about `develop`
* [ ] Roll up the ChangeLog into one file.
* [ ] `git commit -m 'Merge point for <DATE> Breaking Change'`
* [ ] `git push origin future`
* Github Actions
* [ ] Create a PR for `future`
* [ ] `git push origin develop`
* GitHub Actions
* [ ] Create a PR for `develop`
* [ ] Make sure travis comes back clean
* [ ] Merge `future` PR
* [ ] Merge `develop` PR

2
docs/breaking_changes_instructions.md
View File

@ -27,7 +27,7 @@ If you are contributing core code, and the only reason it needs to go through br
We require submissions that go through the Breaking Change process to include a changelog entry. The entry should be a short summary of the changes your pull request makes &ndash; [each section here started as a changelog](ChangeLog/20190830.md "n.b. This should link to the 2019 Aug 30 Breaking Changes doc - @noroadsleft").
Your changelog should be located at `docs/ChangeLog/YYYYMMDD/PR####.md`, where `YYYYMMDD` is the date on which QMK's breaking change branch &ndash; usually named `future` &ndash; will be merged into the `master` branch, and `####` is the number of your pull request.
Your changelog should be located at `docs/ChangeLog/YYYYMMDD/PR####.md`, where `YYYYMMDD` is the date on which QMK's breaking change branch &ndash; usually named `develop` &ndash; will be merged into the `master` branch, and `####` is the number of your pull request.
If your submission requires action on the part of users, your changelog should instruct users what action(s) must be taken, or link to a location that does so.

9
docs/cli.md
View File

@ -13,18 +13,17 @@ QMK requires Python 3.6 or greater. We try to keep the number of requirements sm
If you have installed [Homebrew](https://brew.sh) you can tap and install QMK:
```
brew tap qmk/qmk
brew install qmk
brew install qmk/qmk/qmk
export QMK_HOME='~/qmk_firmware' # Optional, set the location for `qmk_firmware`
qmk setup # This will clone `qmk/qmk_firmware` and optionally set up your build environment
```
### Install Using easy_install or pip :id=install-using-easy_install-or-pip
### Install Using pip :id=install-using-easy_install-or-pip
If your system is not listed above you can install QMK manually. First ensure that you have python 3.6 (or later) installed and have installed pip. Then install QMK with this command:
If your system is not listed above you can install QMK manually. First ensure that you have Python 3.6 (or later) installed and have installed pip. Then install QMK with this command:
```
pip3 install qmk
python3 -m pip install qmk
export QMK_HOME='~/qmk_firmware' # Optional, set the location for `qmk_firmware`
qmk setup # This will clone `qmk/qmk_firmware` and optionally set up your build environment
```

37
docs/cli_commands.md
View File

@ -6,6 +6,8 @@
This command allows you to compile firmware from any directory. You can compile JSON exports from <https://config.qmk.fm>, compile keymaps in the repo, or compile the keyboard in the current working directory.
This command is directory aware. It will automatically fill in KEYBOARD and/or KEYMAP if you are in a keyboard or keymap directory.
**Usage for Configurator Exports**:
```
@ -73,8 +75,9 @@ $ qmk compile -kb dz60
## `qmk flash`
This command is similar to `qmk compile`, but can also target a bootloader. The bootloader is optional, and is set to `:flash` by default.
To specify a different bootloader, use `-bl <bootloader>`. Visit the [Flashing Firmware](flashing.md) guide for more details of the available bootloaders.
This command is similar to `qmk compile`, but can also target a bootloader. The bootloader is optional, and is set to `:flash` by default. To specify a different bootloader, use `-bl <bootloader>`. Visit the [Flashing Firmware](flashing.md) guide for more details of the available bootloaders.
This command is directory aware. It will automatically fill in KEYBOARD and/or KEYMAP if you are in a keyboard or keymap directory.
**Usage for Configurator Exports**:
@ -128,6 +131,32 @@ Check your environment and report problems only:
qmk doctor -n
## `qmk info`
Displays information about keyboards and keymaps in QMK. You can use this to get information about a keyboard, show the layouts, display the underlying key matrix, or to pretty-print JSON keymaps.
**Usage**:
```
qmk info [-f FORMAT] [-m] [-l] [-km KEYMAP] [-kb KEYBOARD]
```
This command is directory aware. It will automatically fill in KEYBOARD and/or KEYMAP if you are in a keyboard or keymap directory.
**Examples**:
Show basic information for a keyboard:
qmk info -kb planck/rev5
Show the matrix for a keyboard:
qmk info -kb ergodox_ez -m
Show a JSON keymap for a keyboard:
qmk info -kb clueboard/california -km default
## `qmk json2c`
Creates a keymap.c from a QMK Configurator export.
@ -152,6 +181,8 @@ qmk list-keyboards
This command lists all the keymaps for a specified keyboard (and revision).
This command is directory aware. It will automatically fill in KEYBOARD if you are in a keyboard directory.
**Usage**:
```
@ -162,6 +193,8 @@ qmk list-keymaps -kb planck/ez
This command creates a new keymap based on a keyboard's existing default keymap.
This command is directory aware. It will automatically fill in KEYBOARD and/or KEYMAP if you are in a keyboard or keymap directory.
**Usage**:
```

2
docs/cli_configuration.md
View File

@ -108,7 +108,7 @@ compile.keymap: skully -> None
|-----|---------------|-------------|
| user.keyboard | None | The keyboard path (Example: `clueboard/66/rev4`) |
| user.keymap | None | The keymap name (Example: `default`) |
| user.name | None | The user's github username. |
| user.name | None | The user's GitHub username. |
# All Configuration Options

2
docs/cli_development.md
View File

@ -210,7 +210,7 @@ Our tests can be found in `lib/python/qmk/tests/`. You will find both unit and i
If your PR does not include a comprehensive set of tests please add comments like this to your code so that other people know where they can help:
# TODO(unassigned/<yourGithubUsername>): Write <unit|integration> tests
# TODO(unassigned/<your_github_username>): Write <unit|integration> tests
We use [nose2](https://nose2.readthedocs.io/en/latest/getting_started.html) to run our tests. You can refer to the nose2 documentation for more details on what you can do in your test functions.

1
docs/compatible_microcontrollers.md
View File

@ -14,6 +14,7 @@ Certain MCUs which do not have native USB will use [V-USB](https://www.obdev.at/
* [ATmega32A](https://www.microchip.com/wwwproducts/en/ATmega32A)
* [ATmega328P](https://www.microchip.com/wwwproducts/en/ATmega328P)
* [ATmega328](https://www.microchip.com/wwwproducts/en/ATmega328)
## ARM

7
docs/config_options.md
View File

@ -197,6 +197,8 @@ If you define these options you will enable the associated feature, which may in
* Note: Increasing the maximum will increase the firmware size and slow sync on split keyboards.
* `#define RGBLIGHT_LAYER_BLINK`
* Adds ability to [blink](feature_rgblight.md?id=lighting-layer-blink) a lighting layer for a specified number of milliseconds (e.g. to acknowledge an action).
* `#define RGBLIGHT_LAYERS_OVERRIDE_RGB_OFF`
* If defined, then [lighting layers](feature_rgblight?id=overriding-rgb-lighting-onoff-status) will be shown even if RGB Light is off.
* `#define RGBLED_NUM 12`
* number of LEDs
* `#define RGBLIGHT_SPLIT`
@ -248,7 +250,10 @@ There are a few different ways to set handedness for split keyboards (listed in
* `#define SPLIT_HAND_PIN B7`
* For using high/low pin to determine handedness, low = right hand, high = left hand. Replace `B7` with the pin you are using. This is optional, and if you leave `SPLIT_HAND_PIN` undefined, then you can still use the EE_HANDS method or MASTER_LEFT / MASTER_RIGHT defines like the stock Let's Split uses.
* `#define EE_HANDS` (only works if `SPLIT_HAND_PIN` is not defined)
* `#define SPLIT_HAND_MATRIX_GRID <out_pin>,<in_pin>`
* The handedness is determined by using the intersection of the keyswitches in the key matrix, which does not exist. Normally, when this intersection is shorted (level low), it is considered left. If you define `#define SPLIT_HAND_MATRIX_GRID_LOW_IS_RIGHT`, it is determined to be right when the level is low.
* `#define EE_HANDS` (only works if `SPLIT_HAND_PIN` and `SPLIT_HAND_MATRIX_GRID` are not defined)
* Reads the handedness value stored in the EEPROM after `eeprom-lefthand.eep`/`eeprom-righthand.eep` has been flashed to their respective halves.
* `#define MASTER_RIGHT`

2
docs/configurator_step_by_step.md
View File

@ -12,7 +12,7 @@ I'll say that again because it's important:
!> **MAKE SURE YOU SELECT THE RIGHT VERSION!**
If your keyboard has been advertised to be powered by QMK but is not in the list, chances are a developer hasn't gotten to it yet or we haven't had a chance to merge it in yet. File an issue at [qmk_firmware](https://github.com/qmk/qmk_firmware/issues) requesting to support that particular keyboard, if there is no active [Pull Request](https://github.com/qmk/qmk_firmware/pulls?q=is%3Aopen+is%3Apr+label%3Akeyboard) for it. There are also QMK powered keyboards that are in their manufacturer's own github accounts. Double check for that as well. <!-- FIXME(skullydazed): This feels too wordy and I'm not sure we want to encourage these kinds of issues. Also, should we prompt them to bug the manufacutrer? -->
If your keyboard has been advertised to be powered by QMK but is not in the list, chances are a developer hasn't gotten to it yet or we haven't had a chance to merge it in yet. File an issue at [qmk_firmware](https://github.com/qmk/qmk_firmware/issues) requesting to support that particular keyboard, if there is no active [Pull Request](https://github.com/qmk/qmk_firmware/pulls?q=is%3Aopen+is%3Apr+label%3Akeyboard) for it. There are also QMK powered keyboards that are in their manufacturer's own GitHub accounts. Double check for that as well. <!-- FIXME(skullydazed): This feels too wordy and I'm not sure we want to encourage these kinds of issues. Also, should we prompt them to bug the manufacutrer? -->
## Step 2: Select Your Keyboard Layout

57
docs/custom_quantum_functions.md
View File

@ -57,7 +57,7 @@ bool process_record_user(uint16_t keycode, keyrecord_t *record) {
case KC_ENTER:
// Play a tone when enter is pressed
if (record->event.pressed) {
PLAY_NOTE_ARRAY(tone_qwerty);
PLAY_SONG(tone_qwerty);
}
return true; // Let QMK send the enter press/release events
default:
@ -438,7 +438,7 @@ bool process_record_user(uint16_t keycode, keyrecord_t *record) {
case KC_ENTER:
// Play a tone when enter is pressed
if (record->event.pressed) {
PLAY_NOTE_ARRAY(tone_qwerty);
PLAY_SONG(tone_qwerty);
}
return true; // Let QMK send the enter press/release events
case RGB_LYR: // This allows me to use underglow as layer indication, or as normal
@ -486,56 +486,3 @@ And you're done. The RGB layer indication will only work if you want it to. And
* Keymap: `void eeconfig_init_user(void)`, `uint32_t eeconfig_read_user(void)` and `void eeconfig_update_user(uint32_t val)`
The `val` is the value of the data that you want to write to EEPROM. And the `eeconfig_read_*` function return a 32 bit (DWORD) value from the EEPROM.
# Custom Tapping Term
By default, the tapping term and related options (such as `IGNORE_MOD_TAP_INTERRUPT`) are defined globally, and are not configurable by key. For most users, this is perfectly fine. But in some cases, dual function keys would be greatly improved by different timeout behaviors than `LT` keys, or because some keys may be easier to hold than others. Instead of using custom key codes for each, this allows for per key configurable timeout behaviors.
There are two configurable options to control per-key timeout behaviors:
- `TAPPING_TERM_PER_KEY`
- `IGNORE_MOD_TAP_INTERRUPT_PER_KEY`
You need to add `#define` lines to your `config.h` for each feature you want.
```
#define TAPPING_TERM_PER_KEY
#define IGNORE_MOD_TAP_INTERRUPT_PER_KEY
```
## Example `get_tapping_term` Implementation
To change the `TAPPING_TERM` based on the keycode, you'd want to add something like the following to your `keymap.c` file:
```c
uint16_t get_tapping_term(uint16_t keycode) {
switch (keycode) {
case SFT_T(KC_SPC):
return TAPPING_TERM + 1250;
case LT(1, KC_GRV):
return 130;
default:
return TAPPING_TERM;
}
}
```
## Example `get_ignore_mod_tap_interrupt` Implementation
To change the `IGNORE_MOD_TAP_INTERRUPT` value based on the keycode, you'd want to add something like the following to your `keymap.c` file:
```c
bool get_ignore_mod_tap_interrupt(uint16_t keycode) {
switch (keycode) {
case SFT_T(KC_SPC):
return true;
default:
return false;
}
}
```
## `get_tapping_term` / `get_ignore_mod_tap_interrupt` Function Documentation
Unlike many of the other functions here, there isn't a need (or even reason) to have a quantum or keyboard level function. Only user level functions are useful here, so no need to mark them as such.

2
docs/de/README.md
View File

@ -13,7 +13,7 @@ QMK (*Quantum Mechanical Keyboard*) ist eine Open-Source-Community, welche die Q
## Bezugsquelle für QMK
Wenn Du vorhast, deine Tastatur, Tastaturbelegung oder Features zu QMK beizusteuern, geht das am einfachsten, indem Du das [Repository auf Github](https://github.com/qmk/qmk_firmware#fork-destination-box) forkst, die Änderungen in deinem lokalen Repo vornimmst und anschließend einen [Pull Request](https://github.com/qmk/qmk_firmware/pulls) einreichst.
Wenn Du vorhast, deine Tastatur, Tastaturbelegung oder Features zu QMK beizusteuern, geht das am einfachsten, indem Du das [Repository auf GitHub](https://github.com/qmk/qmk_firmware#fork-destination-box) forkst, die Änderungen in deinem lokalen Repo vornimmst und anschließend einen [Pull Request](https://github.com/qmk/qmk_firmware/pulls) einreichst.
Ansonsten kannst Du es als [zip](https://github.com/qmk/qmk_firmware/zipball/master) oder [tar](https://github.com/qmk/qmk_firmware/tarball/master) herunterladen, oder es direkt via git klonen (`git clone git@github.com:qmk/qmk_firmware.git` bzw. `git clone https://github.com/qmk/qmk_firmware.git`).

2
docs/de/_summary.md
View File

@ -11,7 +11,7 @@
* [QMK CLI](de/cli.md)
* [QMK CLI Konfiguration](de/cli_configuration.md)
* [Zu QMK beitragen](de/contributing.md)
* [Anleitung für Github](de/getting_started_github.md)
* [Anleitung für GitHub](de/getting_started_github.md)
* [Nach Hilfe fragen](de/getting_started_getting_help.md)
* [Breaking Changes](de/breaking_changes.md)

2
docs/de/newbs_learn_more_resources.md
View File

@ -6,7 +6,7 @@ Git Ressourcen:
* [Gutes allgemeines Tutorial](https://www.codecademy.com/learn/learn-git) (auf Englisch)
* [Git spielerisch anhand von Beispielen lernen](https://learngitbranching.js.org/) (auf Englisch)
* [Mehr über den allgemeinen Umgang mit Github](getting_started_github.md)
* [Mehr über den allgemeinen Umgang mit GitHub](getting_started_github.md)
* [Mehr über Git im Bezug zu QMK](contributing.md)
Mehr über die Arbeit mit der Befehlszeile:

2
docs/documentation_best_practices.md
View File

@ -61,4 +61,4 @@ This page describes my cool feature. You can use my cool feature to make coffee
|KC_SUGAR||Order Sugar|
```
Place your documentation into `docs/feature_<my_cool_feature>.md`, and add that file to the appropriate place in `docs/_sidebar.md`. If you have added any keycodes be sure to add them to `docs/keycodes.md` with a link back to your feature page.
Place your documentation into `docs/feature_<my_cool_feature>.md`, and add that file to the appropriate place in `docs/_summary.md`. If you have added any keycodes be sure to add them to `docs/keycodes.md` with a link back to your feature page.

29
docs/eeprom_driver.md
View File

@ -1,4 +1,4 @@
# EEPROM Driver Configuration
# EEPROM Driver Configuration :id=eeprom-driver-configuration
The EEPROM driver can be swapped out depending on the needs of the keyboard, or whether extra hardware is present.
@ -6,15 +6,20 @@ Driver | Description
-----------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
`EEPROM_DRIVER = vendor` (default) | Uses the on-chip driver provided by the chip manufacturer. For AVR, this is provided by avr-libc. This is supported on ARM for a subset of chips -- STM32F3xx, STM32F1xx, and STM32F072xB will be emulated by writing to flash. STM32L0xx and STM32L1xx will use the onboard dedicated true EEPROM. Other chips will generally act as "transient" below.
`EEPROM_DRIVER = i2c` | Supports writing to I2C-based 24xx EEPROM chips. See the driver section below.
`EEPROM_DRIVER = spi` | Supports writing to SPI-based 25xx EEPROM chips. See the driver section below.
`EEPROM_DRIVER = transient` | Fake EEPROM driver -- supports reading/writing to RAM, and will be discarded when power is lost.
## Vendor Driver Configuration
## Vendor Driver Configuration :id=vendor-eeprom-driver-configuration
#### STM32 L0/L1 Configuration :id=stm32l0l1-eeprom-driver-configuration
!> Resetting EEPROM using an STM32L0/L1 device takes up to 1 second for every 1kB of internal EEPROM used.
No configurable options are available.
`config.h` override | Description | Default Value
------------------------------------|--------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------
`#define STM32_ONBOARD_EEPROM_SIZE` | The size of the EEPROM to use, in bytes. Erase times can be high, so it's configurable here, if not using the default value. | Minimum required to cover base _eeconfig_ data, or `1024` if VIA is enabled.
## I2C Driver Configuration
## I2C Driver Configuration :id=i2c-eeprom-driver-configuration
Currently QMK supports 24xx-series chips over I2C. As such, requires a working i2c_master driver configuration. You can override the driver configuration via your config.h:
@ -41,7 +46,21 @@ MB85RC256V FRAM | `#define EEPROM_I2C_MB85RC256V` | <https://www.adafruit.com/p
?> If you find that the EEPROM is not cooperating, ensure you've correctly shifted up your EEPROM address by 1. For example, the datasheet might state the address as `0b01010000` -- the correct value of `EXTERNAL_EEPROM_I2C_BASE_ADDRESS` needs to be `0b10100000`.
## Transient Driver configuration
## SPI Driver Configuration :id=spi-eeprom-driver-configuration
Currently QMK supports 25xx-series chips over SPI. As such, requires a working spi_master driver configuration. You can override the driver configuration via your config.h:
`config.h` override | Description | Default Value
-----------------------------------------------|--------------------------------------------------------------------------------------|--------------
`#define EXTERNAL_EEPROM_SPI_SLAVE_SELECT_PIN` | SPI Slave select pin in order to inform that the EEPROM is currently being addressed | _none_
`#define EXTERNAL_EEPROM_SPI_CLOCK_DIVISOR` | Clock divisor used to divide the peripheral clock to derive the SPI frequency | `64`
`#define EXTERNAL_EEPROM_BYTE_COUNT` | Total size of the EEPROM in bytes | 8192
`#define EXTERNAL_EEPROM_PAGE_SIZE` | Page size of the EEPROM in bytes, as specified in the datasheet | 32
`#define EXTERNAL_EEPROM_ADDRESS_SIZE` | The number of bytes to transmit for the memory location within the EEPROM | 2
!> There's no way to determine if there is an SPI EEPROM actually responding. Generally, this will result in reads of nothing but zero.
## Transient Driver configuration :id=transient-eeprom-driver-configuration
The only configurable item for the transient EEPROM driver is its size:

2
docs/es/README.md
View File

@ -13,7 +13,7 @@ QMK (*Quantum Mechanical Keyboard*) es una comunidad open source que mantiene el
## Cómo conseguirlo
Si estás pensando en contribuir con un keymap, teclado, or característica a QMK, la manera más sencilla es hacer un [fork del repositorio en Github](https://github.com/qmk/qmk_firmware#fork-destination-box), y clonar tu repositorio localmente para hacer los cambios, subirlos, y abir un [Pull Request](https://github.com/qmk/qmk_firmware/pulls) desde tu fork.
Si estás pensando en contribuir con un keymap, teclado, or característica a QMK, la manera más sencilla es hacer un [fork del repositorio en GitHub](https://github.com/qmk/qmk_firmware#fork-destination-box), y clonar tu repositorio localmente para hacer los cambios, subirlos, y abir un [Pull Request](https://github.com/qmk/qmk_firmware/pulls) desde tu fork.
De cualquier manera, también puedes descargarlo directamente en formatos ([zip](https://github.com/qmk/qmk_firmware/zipball/master), [tar](https://github.com/qmk/qmk_firmware/tarball/master)), o clonarlo via git (`git@github.com:qmk/qmk_firmware.git`), o https (`https://github.com/qmk/qmk_firmware.git`).

2
docs/es/_summary.md
View File

@ -11,7 +11,7 @@
* [QMK CLI](es/cli.md)
* [Configuración de QMK CLI](es/cli_configuration.md)
* [Contribuyendo a QMK](es/contributing.md)
* [Cómo usar Github](es/getting_started_github.md)
* [Cómo usar GitHub](es/getting_started_github.md)
* [Obtener ayuda](es/getting_started_getting_help.md)
* [Cambios incompatibles](es/breaking_changes.md)

2
docs/es/newbs_best_practices.md
View File

@ -6,7 +6,7 @@ Este documento procura instruir a los novatos en las mejores prácticas para ten
En este documento suponemos un par de cosas:
1. Tienes una cuenta de Github, y has hecho un [fork del repo qmk_firmware](getting_started_github.md) en tu cuenta.
1. Tienes una cuenta de GitHub, y has hecho un [fork del repo qmk_firmware](getting_started_github.md) en tu cuenta.
2. Has [configurado tu entorno de desarrollo](newbs_getting_started.md?id=environment-setup).

2
docs/es/newbs_building_firmware_configurator.md
View File

@ -21,7 +21,7 @@ Lo diré otra vez porque es importante
!> **ASEGÚRATE DE QUE SELECCIONAS LA VERSIÓN CORRECTA!**
Si se ha anunciado que tu teclado funciona con QMK pero no está en la lista, es probable que un desarrollador no se haya encargado de él aún o que todavía no hemos tenido la oportunidad de incluirlo. Abre un issue en [qmk_firmware](https://github.com/qmk/qmk_firmware/issues) solicitando soportar ese teclado un particular, si no hay un [Pull Request](https://github.com/qmk/qmk_firmware/pulls?q=is%3Aopen+is%3Apr+label%3Akeyboard) activo para ello. Hay también teclados que funcionan con QMK que están en las cuentas de github de sus manufacturantes. Acuérdate de comprobar esto también.
Si se ha anunciado que tu teclado funciona con QMK pero no está en la lista, es probable que un desarrollador no se haya encargado de él aún o que todavía no hemos tenido la oportunidad de incluirlo. Abre un issue en [qmk_firmware](https://github.com/qmk/qmk_firmware/issues) solicitando soportar ese teclado un particular, si no hay un [Pull Request](https://github.com/qmk/qmk_firmware/pulls?q=is%3Aopen+is%3Apr+label%3Akeyboard) activo para ello. Hay también teclados que funcionan con QMK que están en las cuentas de GitHub de sus manufacturantes. Acuérdate de comprobar esto también.
## Eligiendo el layout de tu teclado

2
docs/es/newbs_learn_more_resources.md
View File

@ -6,7 +6,7 @@ Recursos de Git:
* [Excelente tutorial general](https://www.codecademy.com/learn/learn-git)
* [Juego de Git para aprender usando ejemplos](https://learngitbranching.js.org/)
* [Recursos de Git para aprender más sobre Github](getting_started_github.md)
* [Recursos de Git para aprender más sobre GitHub](getting_started_github.md)
* [Recursos de Git dirigidos específicamente a QMK](contributing.md)

45
docs/faq_build.md
View File

@ -28,35 +28,32 @@ sudo udevadm trigger
**/etc/udev/rules.d/50-atmel-dfu.rules:**
```
# Atmel ATMega32U4
SUBSYSTEMS=="usb", ATTRS{idVendor}=="03eb", ATTRS{idProduct}=="2ff4", MODE:="0666"
SUBSYSTEMS=="usb", ATTRS{idVendor}=="03eb", ATTRS{idProduct}=="2ff4", TAG+="uaccess", RUN{builtin}+="uaccess"
# Atmel USBKEY AT90USB1287
SUBSYSTEMS=="usb", ATTRS{idVendor}=="03eb", ATTRS{idProduct}=="2ffb", MODE:="0666"
SUBSYSTEMS=="usb", ATTRS{idVendor}=="03eb", ATTRS{idProduct}=="2ffb", TAG+="uaccess", RUN{builtin}+="uaccess"
# Atmel ATMega32U2
SUBSYSTEMS=="usb", ATTRS{idVendor}=="03eb", ATTRS{idProduct}=="2ff0", MODE:="0666"
SUBSYSTEMS=="usb", ATTRS{idVendor}=="03eb", ATTRS{idProduct}=="2ff0", TAG+="uaccess", RUN{builtin}+="uaccess"
```
**/etc/udev/rules.d/52-tmk-keyboard.rules:**
```
# tmk keyboard products https://github.com/tmk/tmk_keyboard
SUBSYSTEMS=="usb", ATTRS{idVendor}=="feed", MODE:="0666"
```
**/etc/udev/rules.d/54-input-club-keyboard.rules:**
```
# Input Club keyboard bootloader
SUBSYSTEMS=="usb", ATTRS{idVendor}=="1c11", MODE:="0666"
SUBSYSTEMS=="usb", ATTRS{idVendor}=="1c11", ATTRS{idProduct}=="b007", TAG+="uaccess", RUN{builtin}+="uaccess"
```
**/etc/udev/rules.d/55-caterina.rules:**
```
# ModemManager should ignore the following devices
ATTRS{idVendor}=="2a03", ENV{ID_MM_DEVICE_IGNORE}="1"
ATTRS{idVendor}=="2341", ENV{ID_MM_DEVICE_IGNORE}="1"
SUBSYSTEMS=="usb", ATTRS{idVendor}=="2a03", ATTRS{idProduct}=="0036", TAG+="uaccess", RUN{builtin}+="uaccess", ENV{ID_MM_DEVICE_IGNORE}="1"
SUBSYSTEMS=="usb", ATTRS{idVendor}=="2341", ATTRS{idProduct}=="0036", TAG+="uaccess", RUN{builtin}+="uaccess", ENV{ID_MM_DEVICE_IGNORE}="1"
SUBSYSTEMS=="usb", ATTRS{idVendor}=="1b4f", ATTRS{idProduct}=="9205", TAG+="uaccess", RUN{builtin}+="uaccess", ENV{ID_MM_DEVICE_IGNORE}="1"
SUBSYSTEMS=="usb", ATTRS{idVendor}=="1b4f", ATTRS{idProduct}=="9203", TAG+="uaccess", RUN{builtin}+="uaccess", ENV{ID_MM_DEVICE_IGNORE}="1"
```
**Note:** ModemManager filtering only works when not in strict mode, the following commands can update that settings:
**Note:** With older (before 1.12) ModemManager, filtering only works when not in strict mode, the following commands can update that settings:
```console
sudo sed -i 's/--filter-policy=strict/--filter-policy=default/' /lib/systemd/system/ModemManager.service
printf '[Service]\nExecStart=\nExecStart=/usr/sbin/ModemManager --filter-policy=default' | sudo tee /etc/systemd/system/ModemManager.service.d/policy.conf
sudo systemctl daemon-reload
sudo systemctl restart ModemManager
```
@ -64,15 +61,15 @@ sudo systemctl restart ModemManager
**/etc/udev/rules.d/56-dfu-util.rules:**
```
# stm32duino
SUBSYSTEMS=="usb", ATTRS{idVendor}=="1eaf", ATTRS{idProduct}=="0003", MODE:="0666"
SUBSYSTEMS=="usb", ATTRS{idVendor}=="1eaf", ATTRS{idProduct}=="0003", TAG+="uaccess", RUN{builtin}+="uaccess"
# Generic stm32
SUBSYSTEMS=="usb", ATTRS{idVendor}=="0483", ATTRS{idProduct}=="df11", MODE:="0666"
SUBSYSTEMS=="usb", ATTRS{idVendor}=="0483", ATTRS{idProduct}=="df11", TAG+="uaccess", RUN{builtin}+="uaccess"
```
**/etc/udev/rules.d/57-bootloadhid.rules:**
```
# bootloadHID
SUBSYSTEMS=="usb", ATTRS{idVendor}=="16c0", ATTRS{idProduct}=="05df", MODE:="0666"
SUBSYSTEMS=="usb", ATTRS{idVendor}=="16c0", ATTRS{idProduct}=="05df", TAG+="uaccess", RUN{builtin}+="uaccess"
```
### Serial device is not detected in bootloader mode on Linux
@ -113,26 +110,16 @@ OPT_DEFS += -DBOOTLOADER_SIZE=2048
```
## `avr-gcc: internal compiler error: Abort trap: 6 (program cc1)` on MacOS
This is an issue with updating on brew, causing symlinks that avr-gcc depend on getting mangled.
The solution is to remove and reinstall all affected modules.
```
brew rm avr-gcc
brew rm avr-gcc@8
brew rm dfu-programmer
brew rm dfu-util
brew rm gcc-arm-none-eabi
brew rm arm-gcc-bin@8
brew rm avrdude
brew install avr-gcc@8
brew install dfu-programmer
brew install dfu-util
brew install arm-gcc-bin@8
brew install avrdude
brew rm avr-gcc avr-gcc@8 dfu-programmer dfu-util gcc-arm-none-eabi arm-gcc-bin@8 avrdude qmk
brew install qmk/qmk/qmk
brew link --force avr-gcc@8
brew link --force arm-gcc-bin@8
```
### `avr-gcc` and LUFA

249
docs/feature_backlight.md
View File

@ -1,4 +1,4 @@
# Backlighting
# Backlighting :id=backlighting
Many keyboards support backlit keys by way of individual LEDs placed through or underneath the keyswitches. This feature is distinct from both the [RGB underglow](feature_rgblight.md) and [RGB matrix](feature_rgb_matrix.md) features as it usually allows for only a single colour per switch, though you can obviously install multiple different single coloured LEDs on a keyboard.
@ -6,103 +6,106 @@ QMK is able to control the brightness of these LEDs by switching them on and off
The MCU can only supply so much current to its GPIO pins. Instead of powering the backlight directly from the MCU, the backlight pin is connected to a transistor or MOSFET that switches the power to the LEDs.
## Feature Configuration
Most keyboards have backlighting enabled by default if they support it, but if it is not working for you, check that your `rules.mk` includes the following:
```makefile
BACKLIGHT_ENABLE = yes
```
## Keycodes
Once enabled the following keycodes below can be used to change the backlight level.
## Keycodes :id=keycodes
|Key |Description |
|---------|------------------------------------------|
|`BL_TOGG`|Turn the backlight on or off |
|`BL_STEP`|Cycle through backlight levels |
|`BL_ON` |Set the backlight to max brightness |
|`BL_OFF` |Turn the backlight off |
|`BL_INC` |Increase the backlight level |
|`BL_DEC` |Decrease the backlight level |
|`BL_BRTG`|Toggle backlight breathing |
Once enabled, the following keycodes below can be used to change the backlight level.
## Backlight Functions
|Key |Description |
|---------|-----------------------------------|
|`BL_TOGG`|Turn the backlight on or off |
|`BL_STEP`|Cycle through backlight levels |
|`BL_ON` |Set the backlight to max brightness|
|`BL_OFF` |Turn the backlight off |
|`BL_INC` |Increase the backlight level |
|`BL_DEC` |Decrease the backlight level |
|`BL_BRTG`|Toggle backlight breathing |
|Function |Description |
|----------|-----------------------------------------------------------|
|`backlight_toggle()` |Turn the backlight on or off |
|`backlight_enable()` |Turn the backlight on |
|`backlight_disable()` |Turn the backlight off |
|`backlight_step()` |Cycle through backlight levels |
|`backlight_increase()` |Increase the backlight level |
|`backlight_decrease()` |Decrease the backlight level |
|`backlight_level(x)` |Sets the backlight level to specified level |
|`get_backlight_level()` |Return the current backlight level |
|`is_backlight_enabled()`|Return whether the backlight is currently on |
## Functions :id=functions
### Backlight Breathing Functions
These functions can be used to change the backlighting in custom code:
|Function |Description |
|----------|---------------------------------------------------|
|`breathing_toggle()` |Turn the backlight breathing on or off |
|`breathing_enable()` |Turns on backlight breathing |
|`breathing_disable()` |Turns off backlight breathing |
|Function |Description |
|------------------------|--------------------------------------------|
|`backlight_toggle()` |Turn the backlight on or off |
|`backlight_enable()` |Turn the backlight on |
|`backlight_disable()` |Turn the backlight off |
|`backlight_step()` |Cycle through backlight levels |
|`backlight_increase()` |Increase the backlight level |
|`backlight_decrease()` |Decrease the backlight level |
|`backlight_level(x)` |Sets the backlight level to specified level |
|`get_backlight_level()` |Return the current backlight level |
|`is_backlight_enabled()`|Return whether the backlight is currently on|
## Driver Configuration
If backlight breathing is enabled (see below), the following functions are also available:
|Function |Description |
|---------------------|--------------------------------------|
|`breathing_toggle()` |Turn the backlight breathing on or off|
|`breathing_enable()` |Turns on backlight breathing |
|`breathing_disable()`|Turns off backlight breathing |
## Configuration :id=configuration
To select which driver to use, configure your `rules.mk` with the following:
```makefile
BACKLIGHT_DRIVER = software # Valid driver values are 'pwm,software,no'
BACKLIGHT_DRIVER = software
```
See below for help on individual drivers.
Valid driver values are `pwm`, `software`, `custom` or `no`. See below for help on individual drivers.
## Common Driver Configuration
To configure the backlighting, `#define` these in your `config.h`:
To change the behavior of the backlighting, `#define` these in your `config.h`:
|Define |Default |Description |
|---------------------|-------------|-------------------------------------------------------------------------------------|
|`BACKLIGHT_PIN` |*Not defined*|The pin that controls the LED(s) |
|`BACKLIGHT_LEVELS` |`3` |The number of brightness levels (maximum 31 excluding off) |
|`BACKLIGHT_CAPS_LOCK`|*Not defined*|Enable Caps Lock indicator using backlight (for keyboards without dedicated LED) |
|`BACKLIGHT_BREATHING`|*Not defined*|Enable backlight breathing, if supported |
|`BREATHING_PERIOD` |`6` |The length of one backlight "breath" in seconds |
|`BACKLIGHT_ON_STATE` |`1` |The state of the backlight pin when the backlight is "on" - `1` for high, `0` for low|
|Define |Default |Description |
|---------------------|-------------|--------------------------------------------------------------------------------------|
|`BACKLIGHT_LEVELS` |`3` |The number of brightness levels (maximum 31 excluding off) |
|`BACKLIGHT_CAPS_LOCK`|*Not defined*|Enable Caps Lock indicator using backlight (for keyboards without dedicated LED) |
|`BACKLIGHT_BREATHING`|*Not defined*|Enable backlight breathing, if supported |
|`BREATHING_PERIOD` |`6` |The length of one backlight "breath" in seconds |
|`BACKLIGHT_ON_STATE` |`0` |The state of the backlight pin when the backlight is "on" - `1` for high, `0` for low |
Unless you are designing your own keyboard, you generally should not need to change the `BACKLIGHT_PIN` or `BACKLIGHT_ON_STATE`.
### Backlight On State
### Backlight On State :id=backlight-on-state
Most backlight circuits are driven by an N-channel MOSFET or NPN transistor. This means that to turn the transistor *on* and light the LEDs, you must drive the backlight pin, connected to the gate or base, *high*.
Sometimes, however, a P-channel MOSFET, or a PNP transistor is used. In this case, when the transistor is on, the pin is driven *low* instead.
This functionality is configured at the keyboard level with the `BACKLIGHT_ON_STATE` define.
## AVR driver
### AVR Driver :id=avr-driver
The `pwm` driver is configured by default, however the equivalent setting within `rules.mk` would be:
On AVR boards, the default driver currently sniffs the configuration to pick the best scenario. The driver is configured by default, however the equivalent setting within rules.mk would be:
```makefile
BACKLIGHT_DRIVER = pwm
```
### Caveats
#### Caveats :id=avr-caveats
Hardware PWM is supported according to the following table:
On AVR boards, QMK automatically decides which driver to use according to the following table:
|Backlight Pin|AT90USB64/128|ATmega16/32U4|ATmega16/32U2|ATmega32A|ATmega328P|
|-------------|-------------|-------------|-------------|---------|----------|
|`B1` | | | | |Timer 1 |
|`B2` | | | | |Timer 1 |
|`B5` |Timer 1 |Timer 1 | | | |
|`B6` |Timer 1 |Timer 1 | | | |
|`B7` |Timer 1 |Timer 1 |Timer 1 | | |
|`C4` |Timer 3 | | | | |
|`C5` |Timer 3 | |Timer 1 | | |
|`C6` |Timer 3 |Timer 3 |Timer 1 | | |
|`D4` | | | |Timer 1 | |
|`D5` | | | |Timer 1 | |
|Backlight Pin|AT90USB64/128|ATmega16/32U4|ATmega16/32U2|ATmega32A|ATmega328/P|
|-------------|-------------|-------------|-------------|---------|-----------|
|`B1` | | | | |Timer 1 |
|`B2` | | | | |Timer 1 |
|`B5` |Timer 1 |Timer 1 | | | |
|`B6` |Timer 1 |Timer 1 | | | |
|`B7` |Timer 1 |Timer 1 |Timer 1 | | |
|`C4` |Timer 3 | | | | |
|`C5` |Timer 3 | |Timer 1 | | |
|`C6` |Timer 3 |Timer 3 |Timer 1 | | |
|`D4` | | | |Timer 1 | |
|`D5` | | | |Timer 1 | |
All other pins will use software PWM. If the [Audio](feature_audio.md) feature is disabled or only using one timer, the backlight PWM can be triggered by a hardware timer:
All other pins will use timer-assisted software PWM:
|Audio Pin|Audio Timer|Software PWM Timer|
|---------|-----------|------------------|
@ -113,44 +116,9 @@ All other pins will use software PWM. If the [Audio](feature_audio.md) feature i
|`B6` |Timer 1 |Timer 3 |
|`B7` |Timer 1 |Timer 3 |
When both timers are in use for Audio, the backlight PWM will not use a hardware timer, but will instead be triggered during the matrix scan. In this case, breathing is not supported, and the backlight might flicker, because the PWM computation may not be called with enough timing precision.
When both timers are in use for Audio, the backlight PWM cannot use a hardware timer, and will instead be triggered during the matrix scan. In this case, breathing is not supported, and the backlight might flicker, because the PWM computation may not be called with enough timing precision.
### AVR Configuration
To change the behavior of the backlighting, `#define` these in your `config.h`:
|Define |Default |Description |
|---------------------|-------------|-------------------------------------------------------------------------------------------------------------|
|`BACKLIGHT_PIN` |`B7` |The pin that controls the LEDs. Unless you are designing your own keyboard, you shouldn't need to change this|
|`BACKLIGHT_PINS` |*Not defined*|experimental: see below for more information |
|`BACKLIGHT_LEVELS` |`3` |The number of brightness levels (maximum 31 excluding off) |
|`BACKLIGHT_CAPS_LOCK`|*Not defined*|Enable Caps Lock indicator using backlight (for keyboards without dedicated LED) |
|`BACKLIGHT_BREATHING`|*Not defined*|Enable backlight breathing, if supported |
|`BREATHING_PERIOD` |`6` |The length of one backlight "breath" in seconds |
|`BACKLIGHT_ON_STATE` |`1` |The state of the backlight pin when the backlight is "on" - `1` for high, `0` for low |
### Backlight On State
Most backlight circuits are driven by an N-channel MOSFET or NPN transistor. This means that to turn the transistor *on* and light the LEDs, you must drive the backlight pin, connected to the gate or base, *high*.
Sometimes, however, a P-channel MOSFET, or a PNP transistor is used. In this case, when the transistor is on, the pin is driven *low* instead.
This functionality is configured at the keyboard level with the `BACKLIGHT_ON_STATE` define.
### Multiple backlight pins
Most keyboards have only one backlight pin which control all backlight LEDs (especially if the backlight is connected to an hardware PWM pin).
In software PWM, it is possible to define multiple backlight pins. All those pins will be turned on and off at the same time during the PWM duty cycle.
This feature allows to set for instance the Caps Lock LED (or any other controllable LED) brightness at the same level as the other LEDs of the backlight. This is useful if you have mapped LCTRL in place of Caps Lock and you need the Caps Lock LED to be part of the backlight instead of being activated when Caps Lock is on.
To activate multiple backlight pins, you need to add something like this to your user `config.h`:
```c
#define BACKLIGHT_LED_COUNT 2
#undef BACKLIGHT_PIN
#define BACKLIGHT_PINS { F5, B2 }
```
### Hardware PWM Implementation
#### Hardware PWM Implementation :id=hardware-pwm-implementation
When using the supported pins for backlighting, QMK will use a hardware timer configured to output a PWM signal. This timer will count up to `ICRx` (by default `0xFFFF`) before resetting to 0.
The desired brightness is calculated and stored in the `OCRxx` register. When the counter reaches this value, the backlight pin will go low, and is pulled high again when the counter resets.
@ -159,7 +127,7 @@ In this way `OCRxx` essentially controls the duty cycle of the LEDs, and thus th
The breathing effect is achieved by registering an interrupt handler for `TIMER1_OVF_vect` that is called whenever the counter resets, roughly 244 times per second.
In this handler, the value of an incrementing counter is mapped onto a precomputed brightness curve. To turn off breathing, the interrupt handler is simply disabled, and the brightness reset to the level stored in EEPROM.
### Timer Assisted PWM Implementation
#### Timer Assisted PWM Implementation :id=timer-assisted-implementation
When `BACKLIGHT_PIN` is not set to a hardware backlight pin, QMK will use a hardware timer configured to trigger software interrupts. This time will count up to `ICRx` (by default `0xFFFF`) before resetting to 0.
When resetting to 0, the CPU will fire an OVF (overflow) interrupt that will turn the LEDs on, starting the duty cycle.
@ -168,81 +136,84 @@ In this way `OCRxx` essentially controls the duty cycle of the LEDs, and thus th
The breathing effect is the same as in the hardware PWM implementation.
## ARM Driver
### ARM Driver :id=arm-configuration
While still in its early stages, ARM backlight support aims to eventually have feature parity with AVR. The `pwm` driver is configured by default, however the equivalent setting within `rules.mk` would be:
While still in its early stages, ARM backlight support aims to eventually have feature parity with AVR. The driver is configured by default, however the equivalent setting within rules.mk would be:
```makefile
BACKLIGHT_DRIVER = pwm
```
### Caveats
#### ChibiOS Configuration :id=arm-configuration
The following `#define`s apply only to ARM-based keyboards:
|Define |Default|Description |
|-----------------------|-------|-----------------------------------|
|`BACKLIGHT_PWM_DRIVER` |`PWMD4`|The PWM driver to use |
|`BACKLIGHT_PWM_CHANNEL`|`3` |The PWM channel to use |
|`BACKLIGHT_PAL_MODE` |`2` |The pin alternative function to use|
See the ST datasheet for your particular MCU to determine these values. Unless you are designing your own keyboard, you generally should not need to change them.
#### Caveats :id=arm-caveats
Currently only hardware PWM is supported, not timer assisted, and does not provide automatic configuration.
?> Backlight support for STMF072 has had limited testing, YMMV. If unsure, set `BACKLIGHT_ENABLE = no` in your rules.mk.
?> Backlight support for STM32F072 has had limited testing, so YMMV. If unsure, set `BACKLIGHT_ENABLE = no` in your `rules.mk`.
### ARM Configuration
### Software PWM Driver :id=software-pwm-driver
To change the behavior of the backlighting, `#define` these in your `config.h`:
In this mode, PWM is "emulated" while running other keyboard tasks. It offers maximum hardware compatibility without extra platform configuration. The tradeoff is the backlight might jitter when the keyboard is busy. To enable, add this to your `rules.mk`:
|Define |Default |Description |
|------------------------|-------------|-------------------------------------------------------------------------------------------------------------|
|`BACKLIGHT_PIN` |`B7` |The pin that controls the LEDs. Unless you are designing your own keyboard, you shouldn't need to change this|
|`BACKLIGHT_PWM_DRIVER` |`PWMD4` |The PWM driver to use, see ST datasheets for pin to PWM timer mapping. Unless you are designing your own keyboard, you shouldn't need to change this|
|`BACKLIGHT_PWM_CHANNEL` |`3` |The PWM channel to use, see ST datasheets for pin to PWM channel mapping. Unless you are designing your own keyboard, you shouldn't need to change this|
|`BACKLIGHT_PAL_MODE` |`2` |The pin alternative function to use, see ST datasheets for pin AF mapping. Unless you are designing your own keyboard, you shouldn't need to change this|
## Software PWM Driver :id=software-pwm-driver
Emulation of PWM while running other keyboard tasks, it offers maximum hardware compatibility without extra platform configuration. The tradeoff is the backlight might jitter when the keyboard is busy. To enable, add this to your rules.mk:
```makefile
BACKLIGHT_DRIVER = software
```
### Software PWM Configuration
To change the behavior of the backlighting, `#define` these in your `config.h`:
|Define |Default |Description |
|-----------------|-------------|-------------------------------------------------------------------------------------------------------------|
|`BACKLIGHT_PIN` |`B7` |The pin that controls the LEDs. Unless you are designing your own keyboard, you shouldn't need to change this|
|`BACKLIGHT_PINS` |*Not defined*|experimental: see below for more information |
### Multiple backlight pins
#### Multiple Backlight Pins :id=multiple-backlight-pins
Most keyboards have only one backlight pin which control all backlight LEDs (especially if the backlight is connected to an hardware PWM pin).
In software PWM, it is possible to define multiple backlight pins. All those pins will be turned on and off at the same time during the PWM duty cycle.
This feature allows to set for instance the Caps Lock LED (or any other controllable LED) brightness at the same level as the other LEDs of the backlight. This is useful if you have mapped LCTRL in place of Caps Lock and you need the Caps Lock LED to be part of the backlight instead of being activated when Caps Lock is on.
In software PWM, it is possible to define multiple backlight pins, which will be turned on and off at the same time during the PWM duty cycle.
To activate multiple backlight pins, you need to add something like this to your user `config.h`:
This feature allows to set, for instance, the Caps Lock LED's (or any other controllable LED) brightness at the same level as the other LEDs of the backlight. This is useful if you have mapped Control in place of Caps Lock and you need the Caps Lock LED to be part of the backlight instead of being activated when Caps Lock is on, as it is usually wired to a separate pin from the backlight.
To activate multiple backlight pins, add something like this to your `config.h`, instead of `BACKLIGHT_PIN`:
```c
#undef BACKLIGHT_PIN
#define BACKLIGHT_PINS { F5, B2 }
```
## Custom Driver
### Custom Driver :id=custom-driver
To enable, add this to your rules.mk:
If none of the above drivers apply to your board (for example, you are using a separate IC to control the backlight), you can implement a custom backlight driver using this simple API provided by QMK. To enable, add this to your `rules.mk`:
```makefile
BACKLIGHT_DRIVER = custom
```
When implementing the custom driver API, the provided keyboard hooks are as follows:
Then implement any of these hooks:
```c
void backlight_init_ports(void) {
// Optional - Run on startup
// - usually you want to configure pins here
// Optional - runs on startup
// Usually you want to configure pins here
}
void backlight_set(uint8_t level) {
// Optional - Run on level change
// - usually you want to respond to the new value
// Optional - runs on level change
// Usually you want to respond to the new value
}
void backlight_task(void) {
// Optional - Run periodically
// - long running actions here can cause performance issues
// Optional - runs periodically
// Note that this is called in the main keyboard loop,
// so long running actions here can cause performance issues
}
```
## Example Schematic
In this typical example, the backlight LEDs are all connected in parallel towards an N-channel MOSFET. Its gate pin is wired to one of the microcontroller's GPIO pins through a 470Ω resistor to avoid ringing.
A pulldown resistor is also placed between the gate pin and ground to keep it at a defined state when it is not otherwise being driven by the MCU.
The values of these resistors are not critical - see [this Electronics StackExchange question](https://electronics.stackexchange.com/q/68748) for more information.
![Backlight example circuit](https://i.imgur.com/BmAvoUC.png)

14
docs/feature_dip_switch.md
View File

@ -7,9 +7,17 @@ DIP switches are supported by adding this to your `rules.mk`:
and this to your `config.h`:
```c
// Connects each switch in the dip switch to the GPIO pin of the MCU
#define DIP_SWITCH_PINS { B14, A15, A10, B9 }
```
or
```c
// Connect each switch in the DIP switch to an unused intersections in the key matrix.
#define DIP_SWITCH_MATRIX_GRID { {0,6}, {1,6}, {2,6} } // List of row and col pairs
```
## Callbacks
The callback functions can be inserted into your `<keyboard>.c`:
@ -87,4 +95,10 @@ void dip_switch_update_mask_user(uint32_t state) {
## Hardware
### Connects each switch in the dip switch to the GPIO pin of the MCU
One side of the DIP switch should be wired directly to the pin on the MCU, and the other side to ground. It should not matter which side is connected to which, as it should be functionally the same.
### Connect each switch in the DIP switch to an unused intersections in the key matrix.
As with the keyswitch, a diode and DIP switch connect the ROW line to the COL line.

2
docs/feature_dynamic_macros.md
View File

@ -18,7 +18,7 @@ That should be everything necessary.
To start recording the macro, press either `DYN_REC_START1` or `DYN_REC_START2`.
To finish the recording, press the `DYN_REC_STOP` layer button.
To finish the recording, press the `DYN_REC_STOP` layer button. You can also press `DYN_REC_START1` or `DYN_REC_START2` again to stop the recording.
To replay the macro, press either `DYN_MACRO_PLAY1` or `DYN_MACRO_PLAY2`.

2
docs/feature_encoders.md
View File

@ -26,7 +26,7 @@ If your encoder's clockwise directions are incorrect, you can swap the A & B pad
#define ENCODER_DIRECTION_FLIP
```
Additionally, the resolution can be specified in the same file (the default & suggested is 4):
Additionally, the resolution, which defines how many pulses the encoder registers between each detent, can be defined with:
```c
#define ENCODER_RESOLUTION 4

2
docs/feature_layers.md
View File

@ -19,7 +19,7 @@ These functions allow you to activate layers in various ways. Note that layers a
### Caveats :id=caveats
Currently, `LT()` and `MT()` are limited to the [Basic Keycode set](keycodes_basic.md), meaning you can't use keycodes like `LCTL()`, `KC_TILD`, or anything greater than `0xFF`. Specifically, dual function keys like `LT` and `MT` use a 16 bit keycode. 4 bits are used for the function identifier, the next 12 are divided into the parameters. Layer Tap uses 4 bits for the layer (and is why it's limited to layers 0-16, actually), while Mod Tap does the same, 4 bits for the identifier, 4 bits for which mods are used, and all of them use 8 bits for the keycode. Because of this, the keycode used is limited to `0xFF` (0-255), which are the basic keycodes only.
Currently, `LT()` and `MT()` are limited to the [Basic Keycode set](keycodes_basic.md), meaning you can't use keycodes like `LCTL()`, `KC_TILD`, or anything greater than `0xFF`. Specifically, dual function keys like `LT` and `MT` use a 16 bit keycode. 4 bits are used for the function identifier, the next 12 are divided into the parameters. Layer Tap uses 4 bits for the layer (and is why it's limited to layers 0-15, actually), while Mod Tap does the same, 4 bits for the identifier, 4 bits for which mods are used, and all of them use 8 bits for the keycode. Because of this, the keycode used is limited to `0xFF` (0-255), which are the basic keycodes only.
Expanding this would be complicated, at best. Moving to a 32-bit keycode would solve a lot of this, but would double the amount of space that the keymap matrix uses. And it could potentially cause issues, too. If you need to apply modifiers to your tapped keycode, [Tap Dance](feature_tap_dance.md#example-5-using-tap-dance-for-advanced-mod-tap-and-layer-tap-keys) can be used to accomplish this.

2
docs/feature_leader_key.md
View File

@ -5,7 +5,7 @@ If you've ever used Vim, you know what a Leader key is. If not, you're about to
That's what `KC_LEAD` does. Here's an example:
1. Pick a key on your keyboard you want to use as the Leader key. Assign it the keycode `KC_LEAD`. This key would be dedicated just for this -- it's a single action key, can't be used for anything else.
2. Include the line `#define LEADER_TIMEOUT 300` in your `config.h`. This sets the timeout for the `KC_LEAD` key. Specifically, when you press the `KC_LEAD` key, you only have a certain amount of time to complete the Leader Key sequence. The `300` here sets that to 300ms, and you can increase this value to give you more time to hit the sequence. But any keys pressed during this timeout are intercepted and not sent, so you may want to keep this value low. .
2. Include the line `#define LEADER_TIMEOUT 300` in your `config.h`. This sets the timeout for the `KC_LEAD` key. Specifically, when you press the `KC_LEAD` key, you only have a certain amount of time to complete the Leader Key sequence. The `300` here sets that to 300ms, and you can increase this value to give you more time to hit the sequence. But any keys pressed during this timeout are intercepted and not sent, so you may want to keep this value low.
* By default, this timeout is how long after pressing `KC_LEAD` to complete your entire sequence. This may be very low for some people. So you may want to increase this timeout. Optionally, you may want to enable the `LEADER_PER_KEY_TIMING` option, which resets the timeout after each key is tapped. This allows you to maintain a low value here, but still be able to use the longer sequences. To enable this option, add `#define LEADER_PER_KEY_TIMING` to your `config.h`.
3. Within your `matrix_scan_user` function, add something like this:

89
docs/feature_macros.md
View File

@ -6,34 +6,34 @@ Macros allow you to send multiple keystrokes when pressing just one key. QMK has
## The New Way: `SEND_STRING()` & `process_record_user`
Sometimes you just want a key to type out words or phrases. For the most common situations we've provided `SEND_STRING()`, which will type out your string (i.e. a sequence of characters) for you. All ASCII characters that are easily translated to a keycode are supported (e.g. `\n\t`).
Sometimes you want a key to type out words or phrases. For the most common situations, we've provided `SEND_STRING()`, which will type out a string (i.e. a sequence of characters) for you. All ASCII characters that are easily translatable to a keycode are supported (e.g. `qmk 123\n\t`).
Here is an example `keymap.c` for a two-key keyboard:
```c
enum custom_keycodes {
QMKBEST = SAFE_RANGE,
QMKBEST = SAFE_RANGE,
};
bool process_record_user(uint16_t keycode, keyrecord_t *record) {
switch (keycode) {
switch (keycode) {
case QMKBEST:
if (record->event.pressed) {
// when keycode QMKBEST is pressed
SEND_STRING("QMK is the best thing ever!");
} else {
// when keycode QMKBEST is released
}
break;
}
return true;
if (record->event.pressed) {
// when keycode QMKBEST is pressed
SEND_STRING("QMK is the best thing ever!");
} else {
// when keycode QMKBEST is released
}
break;
}
return true;
};
const uint16_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] = {
[0] = {
{QMKBEST, KC_ESC}
}
[0] = {
{QMKBEST, KC_ESC},
// ...
},
};
```
@ -49,42 +49,45 @@ You can do that by adding another keycode and adding another case to the switch
```c
enum custom_keycodes {
QMKBEST = SAFE_RANGE,
QMKURL,
MY_OTHER_MACRO
QMKBEST = SAFE_RANGE,
QMKURL,
MY_OTHER_MACRO,
};
bool process_record_user(uint16_t keycode, keyrecord_t *record) {
switch (keycode) {
switch (keycode) {
case QMKBEST:
if (record->event.pressed) {
// when keycode QMKBEST is pressed
SEND_STRING("QMK is the best thing ever!");
} else {
// when keycode QMKBEST is released
}
break;
if (record->event.pressed) {
// when keycode QMKBEST is pressed
SEND_STRING("QMK is the best thing ever!");
} else {
// when keycode QMKBEST is released
}
break;
case QMKURL:
if (record->event.pressed) {
// when keycode QMKURL is pressed
SEND_STRING("https://qmk.fm/\n");
} else {
// when keycode QMKURL is released
}
break;
if (record->event.pressed) {
// when keycode QMKURL is pressed
SEND_STRING("https://qmk.fm/\n");
} else {
// when keycode QMKURL is released
}
break;
case MY_OTHER_MACRO:
if (record->event.pressed) {
SEND_STRING(SS_LCTL("ac")); // selects all and copies
}
break;
}
return true;
if (record->event.pressed) {
SEND_STRING(SS_LCTL("ac")); // selects all and copies
}
break;
}
return true;
};
const uint16_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] = {
[0] = {
{MY_CUSTOM_MACRO, MY_OTHER_MACRO}
}
[0] = {
{MY_CUSTOM_MACRO, MY_OTHER_MACRO},
// ...
},
};
```

22
docs/feature_pointing_device.md
View File

@ -21,26 +21,28 @@ Keep in mind that a report_mouse_t (here "mouseReport") has the following proper
* `mouseReport.h` - this is a signed int from -127 to 127 (not 128, this is defined in USB HID spec) representing horizontal scrolling (+ right, - left).
* `mouseReport.buttons` - this is a uint8_t in which the last 5 bits are used. These bits represent the mouse button state - bit 3 is mouse button 5, and bit 7 is mouse button 1.
When the mouse report is sent, the x, y, v, and h values are set to 0 (this is done in "pointing_device_send()", which can be overridden to avoid this behavior). This way, button states persist, but movement will only occur once. For further customization, both `pointing_device_init` and `pointing_device_task` can be overridden.
Once you have made the necessary changes to the mouse report, you need to send it:
* `pointing_device_send()` - Sends the mouse report to the host and zeroes out the report.
When the mouse report is sent, the x, y, v, and h values are set to 0 (this is done in `pointing_device_send()`, which can be overridden to avoid this behavior). This way, button states persist, but movement will only occur once. For further customization, both `pointing_device_init` and `pointing_device_task` can be overridden.
In the following example, a custom key is used to click the mouse and scroll 127 units vertically and horizontally, then undo all of that when released - because that's a totally useful function. Listen, this is an example:
```c
case MS_SPECIAL:
report_mouse_t currentReport = pointing_device_get_report();
if (record->event.pressed)
{
report_mouse_t currentReport = pointing_device_get_report();
if (record->event.pressed) {
currentReport.v = 127;
currentReport.h = 127;
currentReport.buttons |= MOUSE_BTN1; //this is defined in report.h
}
else
{
currentReport.h = 127;
currentReport.buttons |= MOUSE_BTN1; // this is defined in report.h
} else {
currentReport.v = -127;
currentReport.h = -127;
currentReport.buttons &= ~MOUSE_BTN1;
}
pointing_device_set_report(currentReport);
pointing_device_set_report(currentReport);
pointing_device_send();
break;
```

10
docs/feature_ps2_mouse.md
View File

@ -294,3 +294,13 @@ To debug the mouse, add `debug_mouse = true` or enable via bootmagic.
#define PS2_MOUSE_DEBUG_HID
#define PS2_MOUSE_DEBUG_RAW
```
### Movement Hook :id=movement-hook
Process mouse movement in the keymap before it is sent to the host. Example
uses include filtering noise, adding acceleration, and automatically activating
a layer. To use, define the following function in your keymap:
```c
void ps2_mouse_moved_user(report_mouse_t *mouse_report);
```

6
docs/feature_rawhid.md
View File

@ -44,7 +44,11 @@ To connect your host computer to your keyboard with raw HID you need four pieces
3. Usage Page
4. Usage
The first two can easily be found in your keyboard's `config.h` in the keyboard's main directory under `VENDOR_ID` and `PRODUCT_ID`. **Usage Page** is **`0xFF60`** and **Usage** is **`0x0061`**.
The first two can easily be found in your keyboard's `config.h` in the keyboard's main directory under `VENDOR_ID` and `PRODUCT_ID`.
The final two can be overridden in your keyboard's `config.h` in the keyboard's main directory by redefining the values: `#define RAW_USAGE_PAGE 0xFF60` and `#define RAW_USAGE_ID 0x61`.
By default, **Usage Page** is `0xFF60` and **Usage** is `0x61`.
### Building your host

30
docs/feature_rgb_matrix.md
View File

@ -186,8 +186,16 @@ All RGB keycodes are currently shared with the RGBLIGHT system:
|`RGB_VAD` | |Decrease value (brightness), increase value when Shift is held |
|`RGB_SPI` | |Increase effect speed (does not support eeprom yet), decrease speed when Shift is held|
|`RGB_SPD` | |Decrease effect speed (does not support eeprom yet), increase speed when Shift is held|
|`RGB_MODE_PLAIN` |`RGB_M_P `|Static (no animation) mode |
|`RGB_MODE_BREATHE` |`RGB_M_B` |Breathing animation mode |
|`RGB_MODE_RAINBOW` |`RGB_M_R` |Full gradient scrolling left to right (uses the `RGB_MATRIX_CYCLE_LEFT_RIGHT` mode) |
|`RGB_MODE_SWIRL` |`RGB_M_SW`|Full gradient spinning pinwheel around center of keyboard (uses `RGB_MATRIX_CYCLE_PINWHEEL` mode) |
* `RGB_MODE_*` keycodes will generally work, but are not currently mapped to the correct effects for the RGB Matrix system
* `RGB_MODE_*` keycodes will generally work, but not all of the modes are currently mapped to the correct effects for the RGB Matrix system.
`RGB_MODE_PLAIN`, `RGB_MODE_BREATHE`, `RGB_MODE_RAINBOW`, and `RGB_MATRIX_SWIRL` are the only ones that are mapped properly. The rest don't have a direct equivalent, and are not mapped.
!> By default, if you have both the [RGB Light](feature_rgblight.md) and the RGB Matrix feature enabled, these keycodes will work for both features, at the same time. You can disable the keycode functionality by defining the `*_DISABLE_KEYCODES` option for the specific feature.
## RGB Matrix Effects :id=rgb-matrix-effects
@ -374,7 +382,8 @@ These are defined in [`rgblight_list.h`](https://github.com/qmk/qmk_firmware/blo
```c
#define RGB_MATRIX_KEYPRESSES // reacts to keypresses
#define RGB_MATRIX_KEYRELEASES // reacts to keyreleases (instead of keypresses)
#define RGB_DISABLE_AFTER_TIMEOUT 0 // number of ticks to wait until disabling effects
#define RGB_DISABLE_TIMEOUT 0 // number of milliseconds to wait until rgb automatically turns off
#define RGB_DISABLE_AFTER_TIMEOUT 0 // OBSOLETE: number of ticks to wait until disabling effects
#define RGB_DISABLE_WHEN_USB_SUSPENDED false // turn off effects when suspended
#define RGB_MATRIX_LED_PROCESS_LIMIT (DRIVER_LED_TOTAL + 4) / 5 // limits the number of LEDs to process in an animation per task run (increases keyboard responsiveness)
#define RGB_MATRIX_LED_FLUSH_LIMIT 16 // limits in milliseconds how frequently an animation will update the LEDs. 16 (16ms) is equivalent to limiting to 60fps (increases keyboard responsiveness)
@ -384,6 +393,7 @@ These are defined in [`rgblight_list.h`](https://github.com/qmk/qmk_firmware/blo
#define RGB_MATRIX_STARTUP_SAT 255 // Sets the default saturation value, if none has been set
#define RGB_MATRIX_STARTUP_VAL RGB_MATRIX_MAXIMUM_BRIGHTNESS // Sets the default brightness value, if none has been set
#define RGB_MATRIX_STARTUP_SPD 127 // Sets the default animation speed, if none has been set
#define RGB_MATRIX_DISABLE_KEYCODES // disables control of rgb matrix by keycodes (must use code functions to control the feature)
```
## EEPROM storage :id=eeprom-storage
@ -437,12 +447,16 @@ Where `28` is an unused index from `eeconfig.h`.
|`rgb_matrix_sethsv_noeeprom(h, s, v)` |Set LEDs to the given HSV value where `h`/`s`/`v` are between 0 and 255 (not written to EEPROM) |
### Query Current Status :id=query-current-status
|Function |Description |
|-----------------------|-----------------|
|`rgb_matrix_get_mode()` |Get current mode |
|`rgb_matrix_get_hue()` |Get current hue |
|`rgb_matrix_get_sat()` |Get current sat |
|`rgb_matrix_get_val()` |Get current val |
|Function |Description |
|---------------------------------|---------------------------|
|`rgb_matrix_is_enabled()` |Gets current on/off status |
|`rgb_matrix_get_mode()` |Gets current mode |
|`rgb_matrix_get_hue()` |Gets current hue |
|`rgb_matrix_get_sat()` |Gets current sat |
|`rgb_matrix_get_val()` |Gets current val |
|`rgb_matrix_get_hsv()` |Gets hue, sat, and val and returns a [`HSV` structure](https://github.com/qmk/qmk_firmware/blob/7ba6456c0b2e041bb9f97dbed265c5b8b4b12192/quantum/color.h#L56-L61)|
|`rgb_matrix_get_speed()` |Gets current speed |
|`rgb_matrix_get_suspend_state()` |Gets current suspend state |
## Callbacks :id=callbacks

22
docs/feature_rgblight.md
View File

@ -64,6 +64,9 @@ Changing the **Value** sets the overall brightness.<br>
|`RGB_MODE_GRADIENT`|`RGB_M_G` |Static gradient animation mode |
|`RGB_MODE_RGBTEST` |`RGB_M_T` |Red, Green, Blue test animation mode |
!> By default, if you have both the RGB Light and the [RGB Matrix](feature_rgb_matrix.md) feature enabled, these keycodes will work for both features, at the same time. You can disable the keycode functionality by defining the `*_DISABLE_KEYCODES` option for the specific feature.
## Configuration
Your RGB lighting can be configured by placing these `#define`s in your `config.h`:
@ -76,6 +79,7 @@ Your RGB lighting can be configured by placing these `#define`s in your `config.
|`RGBLIGHT_LIMIT_VAL` |`255` |The maximum brightness level |
|`RGBLIGHT_SLEEP` |*Not defined*|If defined, the RGB lighting will be switched off when the host goes to sleep|
|`RGBLIGHT_SPLIT` |*Not defined*|If defined, synchronization functionality for split keyboards is added|
|`RGBLIGHT_DISABLE_KEYCODES`|*not defined*|If defined, disables the ability to control RGB Light from the keycodes. You must use code functions to control the feature|
## Effects and Animations
@ -278,6 +282,10 @@ void post_process_record_user(uint16_t keycode, keyrecord_t *record) {
}
```
### Overriding RGB Lighting on/off status
Normally lighting layers are not shown when RGB Lighting is disabled (e.g. with `RGB_TOG` keycode). If you would like lighting layers to work even when the RGB Lighting is otherwise off, add `#define RGBLIGHT_LAYERS_OVERRIDE_RGB_OFF` to your `config.h`.
## Functions
If you need to change your RGB lighting in code, for example in a macro to change the color whenever you switch layers, QMK provides a set of functions to assist you. See [`rgblight.h`](https://github.com/qmk/qmk_firmware/blob/master/quantum/rgblight.h) for the full list, but the most commonly used functions include:
@ -376,12 +384,14 @@ rgblight_sethsv(HSV_GREEN, 2); // led 2
|`rgblight_set_layer_state(i, is_on)` |Enable or disable lighting layer `i` based on value of `bool is_on` |
#### query
|Function |Description |
|-----------------------|-----------------|
|`rgblight_get_mode()` |Get current mode |
|`rgblight_get_hue()` |Get current hue |
|`rgblight_get_sat()` |Get current sat |
|`rgblight_get_val()` |Get current val |
|Function |Description |
|-----------------------|---------------------------|
|`rgblight_is_enabled()`|Gets current on/off status |
|`rgblight_get_mode()` |Gets current mode |
|`rgblight_get_hue()` |Gets current hue |
|`rgblight_get_sat()` |Gets current sat |
|`rgblight_get_val()` |Gets current val |
|`rgblight_get_speed()` |Gets current speed |
## Colors

31
docs/feature_split_keyboard.md
View File

@ -8,9 +8,20 @@ QMK Firmware has a generic implementation that is usable by any board, as well a
For this, we will mostly be talking about the generic implementation used by the Let's Split and other keyboards.
!> ARM is not yet supported for Split Keyboards. Progress is being made, but we are not quite there, yet.
!> ARM is not yet fully supported for Split Keyboards and has many limitations. Progress is being made, but we have not yet reached 100% feature parity.
## Compatibility Overview
| Transport | AVR | ARM |
|------------------------------|--------------------|--------------------|
| ['serial'](serial_driver.md) | :heavy_check_mark: | :white_check_mark: <sup>1</sup> |
| I2C | :heavy_check_mark: | |
Notes:
1. Both hardware and software limitations are detailed within the [driver documentation](serial_driver.md).
## Hardware Configuration
This assumes that you're using two Pro Micro-compatible controllers, and are using TRRS jacks to connect to two halves.
@ -79,6 +90,24 @@ You can configure the firmware to read a pin on the controller to determine hand
This will read the specified pin. If it's high, then the controller assumes it is the left hand, and if it's low, it's assumed to be the right side.
#### Handedness by Matrix Pin
You can configure the firmware to read key matrix pins on the controller to determine handedness. To do this, add the following to your `config.h` file:
```c
#define SPLIT_HAND_MATRIX_GRID D0, F1
```
The first pin is the output pin and the second is the input pin.
Some keyboards have unused intersections in the key matrix. This setting uses one of these unused intersections to determine the handness.
Normally, when a diode is connected to an intersection, it is judged to be left. If you add the following definition, it will be judged to be right.
```c
#define SPLIT_HAND_MATRIX_GRID_LOW_IS_RIGHT
```
#### Handedness by EEPROM
This method sets the keyboard's handedness by setting a flag in the persistent storage (`EEPROM`). This is checked when the controller first starts up, and determines what half the keyboard is, and how to orient the keyboard layout.

534
docs/feature_tap_dance.md
View File

@ -1,31 +1,24 @@
# Tap Dance: A Single Key Can Do 3, 5, or 100 Different Things
## Introduction
## Introduction :id=introduction
Hit the semicolon key once, send a semicolon. Hit it twice, rapidly -- send a colon. Hit it three times, and your keyboard's LEDs do a wild dance. That's just one example of what Tap Dance can do. It's one of the nicest community-contributed features in the firmware, conceived and created by [algernon](https://github.com/algernon) in [#451](https://github.com/qmk/qmk_firmware/pull/451). Here's how algernon describes the feature:
With this feature one can specify keys that behave differently, based on the amount of times they have been tapped, and when interrupted, they get handled before the interrupter.
## Explanatory Comparison with `ACTION_FUNCTION_TAP`
`ACTION_FUNCTION_TAP` can offer similar functionality to Tap Dance, but it's worth noting some important differences. To do this, let's explore a certain setup! We want one key to send `Space` on single-tap, but `Enter` on double-tap.
## How to Use Tap Dance :id=how-to-use
With `ACTION_FUNCTION_TAP`, it is quite a rain-dance to set this up, and has the problem that when the sequence is interrupted, the interrupting key will be sent first. Thus, `SPC a` will result in `a SPC` being sent, if `SPC` and `a` are both typed within `TAPPING_TERM`. With the Tap Dance feature, that'll come out correctly as `SPC a` (even if both `SPC` and `a` are typed within the `TAPPING_TERM`.
To achieve this correct handling of interrupts, the implementation of Tap Dance hooks into two parts of the system: `process_record_quantum()`, and the matrix scan. These two parts are explained below, but for now the point to note is that we need the latter to be able to time out a tap sequence even when a key is not being pressed. That way, `SPC` alone will time out and register after `TAPPING_TERM` time.
## How to Use Tap Dance
But enough of the generalities; lets look at how to actually use Tap Dance!
First, you will need `TAP_DANCE_ENABLE=yes` in your `rules.mk`, because the feature is disabled by default. This adds a little less than 1k to the firmware size.
First, you will need `TAP_DANCE_ENABLE = yes` in your `rules.mk`, because the feature is disabled by default. This adds a little less than 1k to the firmware size.
Optionally, you might want to set a custom `TAPPING_TERM` time by adding something like this in you `config.h`:
```
```c
#define TAPPING_TERM 175
```
The `TAPPING_TERM` time is the maximum time allowed between taps of your Tap Dance key, and is measured in milliseconds. For example, if you used the above `#define` statement and set up a Tap Dance key that sends `Space` on single-tap and `Enter` on double-tap, then this key will send `ENT` only if you tap this key twice in less than 175ms. If you tap the key, wait more than 175ms, and tap the key again you'll end up sending `SPC SPC` instead.
The `TAPPING_TERM` time is the maximum time allowed between taps of your Tap Dance key, and is measured in milliseconds. For example, if you used the above `#define` statement and set up a Tap Dance key that sends `Space` on single-tap and `Enter` on double-tap, then this key will send `ENT` only if you tap this key twice in less than 175ms. If you tap the key, wait more than 175ms, and tap the key again you'll end up sending `SPC SPC` instead.
Next, you will want to define some tap-dance keys, which is easiest to do with the `TD()` macro, that - similar to `F()` - takes a number, which will later be used as an index into the `tap_dance_actions` array.
Next, you will want to define some tap-dance keys, which is easiest to do with the `TD()` macro, that takes a number which will later be used as an index into the `tap_dance_actions` array.
After this, you'll want to use the `tap_dance_actions` array to specify what actions shall be taken when a tap-dance key is in action. Currently, there are five possible options:
@ -43,11 +36,12 @@ The first option is enough for a lot of cases, that just want dual roles. For ex
Similar to the first option, the second option is good for simple layer-switching cases.
For more complicated cases, use the third or fourth options (examples of each are listed below).
For more complicated cases, use the third or fourth options (examples of each are listed below).
Finally, the fifth option is particularly useful if your non-Tap-Dance keys start behaving weirdly after adding the code for your Tap Dance keys. The likely problem is that you changed the `TAPPING_TERM` time to make your Tap Dance keys easier for you to use, and that this has changed the way your other keys handle interrupts.
## Implementation Details
## Implementation Details :id=implementation
Well, that's the bulk of it! You should now be able to work through the examples below, and to develop your own Tap Dance functionality. But if you want a deeper understanding of what's going on behind the scenes, then read on for the explanation of how it all works!
The main entry point is `process_tap_dance()`, called from `process_record_quantum()`, which is run for every keypress, and our handler gets to run early. This function checks whether the key pressed is a tap-dance key. If it is not, and a tap-dance was in action, we handle that first, and enqueue the newly pressed key. If it is a tap-dance key, then we check if it is the same as the already active one (if there's one active, that is). If it is not, we fire off the old one first, then register the new one. If it was the same, we increment the counter and reset the timer.
@ -58,9 +52,9 @@ Our next stop is `matrix_scan_tap_dance()`. This handles the timeout of tap-danc
For the sake of flexibility, tap-dance actions can be either a pair of keycodes, or a user function. The latter allows one to handle higher tap counts, or do extra things, like blink the LEDs, fiddle with the backlighting, and so on. This is accomplished by using an union, and some clever macros.
# Examples
## Examples :id=examples
## Simple Example
### Simple Example :id=simple-example
Here's a simple example for a single definition:
@ -69,23 +63,26 @@ Here's a simple example for a single definition:
3. In your `keymap.c` file, define the variables and definitions, then add to your keymap:
```c
//Tap Dance Declarations
// Tap Dance declarations
enum {
TD_ESC_CAPS = 0
TD_ESC_CAPS,
};
//Tap Dance Definitions
// Tap Dance definitions
qk_tap_dance_action_t tap_dance_actions[] = {
//Tap once for Esc, twice for Caps Lock
[TD_ESC_CAPS] = ACTION_TAP_DANCE_DOUBLE(KC_ESC, KC_CAPS)
// Other declarations would go here, separated by commas, if you have them
// Tap once for Escape, twice for Caps Lock
[TD_ESC_CAPS] = ACTION_TAP_DANCE_DOUBLE(KC_ESC, KC_CAPS),
};
//In Layer declaration, add tap dance item in place of a key code
TD(TD_ESC_CAPS)
// Add tap dance item in place of a key code
const uint16_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] = {
// ...
TD(TD_ESC_CAPS)
// ...
};
```
## Complex Examples
### Complex Examples :id=complex-examples
This section details several complex tap dance examples.
All the enums used in the examples are declared like this:
@ -93,104 +90,105 @@ All the enums used in the examples are declared like this:
```c
// Enums defined for all examples:
enum {
CT_SE = 0,
CT_CLN,
CT_EGG,
CT_FLSH,
X_TAP_DANCE
CT_SE,
CT_CLN,
CT_EGG,
CT_FLSH,
X_TAP_DANCE
};
```
### Example 1: Send `:` on Single Tap, `;` on Double Tap
#### Example 1: Send `:` on Single Tap, `;` on Double Tap :id=example-1
```c
void dance_cln_finished (qk_tap_dance_state_t *state, void *user_data) {
if (state->count == 1) {
register_code (KC_RSFT);
register_code (KC_SCLN);
} else {
register_code (KC_SCLN);
}
void dance_cln_finished(qk_tap_dance_state_t *state, void *user_data) {
if (state->count == 1) {
register_code16(KC_COLN);
} else {
register_code(KC_SCLN);
}
}
void dance_cln_reset (qk_tap_dance_state_t *state, void *user_data) {
if (state->count == 1) {
unregister_code (KC_RSFT);
unregister_code (KC_SCLN);
} else {
unregister_code (KC_SCLN);
}
void dance_cln_reset(qk_tap_dance_state_t *state, void *user_data) {
if (state->count == 1) {
unregister_code16(KC_COLN);
} else {
unregister_code(KC_SCLN);
}
}
//All tap dance functions would go here. Only showing this one.
// All tap dance functions would go here. Only showing this one.
qk_tap_dance_action_t tap_dance_actions[] = {
[CT_CLN] = ACTION_TAP_DANCE_FN_ADVANCED (NULL, dance_cln_finished, dance_cln_reset)
[CT_CLN] = ACTION_TAP_DANCE_FN_ADVANCED(NULL, dance_cln_finished, dance_cln_reset),
};
```
### Example 2: Send "Safety Dance!" After 100 Taps
#### Example 2: Send "Safety Dance!" After 100 Taps :id=example-2
```c
void dance_egg (qk_tap_dance_state_t *state, void *user_data) {
if (state->count >= 100) {
SEND_STRING ("Safety dance!");
reset_tap_dance (state);
}
void dance_egg(qk_tap_dance_state_t *state, void *user_data) {
if (state->count >= 100) {
SEND_STRING("Safety dance!");
reset_tap_dance(state);
}
}
qk_tap_dance_action_t tap_dance_actions[] = {
[CT_EGG] = ACTION_TAP_DANCE_FN (dance_egg)
[CT_EGG] = ACTION_TAP_DANCE_FN(dance_egg),
};
```
### Example 3: Turn LED Lights On Then Off, One at a Time
#### Example 3: Turn LED Lights On Then Off, One at a Time :id=example-3
```c
// on each tap, light up one led, from right to left
// on the forth tap, turn them off from right to left
// On each tap, light up one LED, from right to left
// On the fourth tap, turn them off from right to left
void dance_flsh_each(qk_tap_dance_state_t *state, void *user_data) {
switch (state->count) {
case 1:
ergodox_right_led_3_on();
break;
case 2:
ergodox_right_led_2_on();
break;
case 3:
ergodox_right_led_1_on();
break;
case 4:
ergodox_right_led_3_off();
_delay_ms(50);
ergodox_right_led_2_off();
_delay_ms(50);
ergodox_right_led_1_off();
}
switch (state->count) {
case 1:
ergodox_right_led_3_on();
break;
case 2:
ergodox_right_led_2_on();
break;
case 3:
ergodox_right_led_1_on();
break;
case 4:
ergodox_right_led_3_off();
wait_ms(50);
ergodox_right_led_2_off();
wait_ms(50);
ergodox_right_led_1_off();
}
}
// on the fourth tap, set the keyboard on flash state
// On the fourth tap, set the keyboard on flash state
void dance_flsh_finished(qk_tap_dance_state_t *state, void *user_data) {
if (state->count >= 4) {
reset_keyboard();
reset_tap_dance(state);
}
if (state->count >= 4) {
reset_keyboard();
}
}
// if the flash state didn't happen, then turn off LEDs, left to right
// If the flash state didn't happen, then turn off LEDs, left to right
void dance_flsh_reset(qk_tap_dance_state_t *state, void *user_data) {
ergodox_right_led_1_off();
_delay_ms(50);
ergodox_right_led_2_off();
_delay_ms(50);
ergodox_right_led_3_off();
ergodox_right_led_1_off();
wait_ms(50);
ergodox_right_led_2_off();
wait_ms(50);
ergodox_right_led_3_off();
}
//All tap dances now put together. Example 3 is "CT_FLASH"
// All tap dances now put together. Example 3 is "CT_FLASH"
qk_tap_dance_action_t tap_dance_actions[] = {
[CT_SE] = ACTION_TAP_DANCE_DOUBLE (KC_SPC, KC_ENT)
,[CT_CLN] = ACTION_TAP_DANCE_FN_ADVANCED (NULL, dance_cln_finished, dance_cln_reset)
,[CT_EGG] = ACTION_TAP_DANCE_FN (dance_egg)
,[CT_FLSH] = ACTION_TAP_DANCE_FN_ADVANCED (dance_flsh_each, dance_flsh_finished, dance_flsh_reset)
[CT_SE] = ACTION_TAP_DANCE_DOUBLE(KC_SPC, KC_ENT),
[CT_CLN] = ACTION_TAP_DANCE_FN_ADVANCED(NULL, dance_cln_finished, dance_cln_reset),
[CT_EGG] = ACTION_TAP_DANCE_FN(dance_egg),
[CT_FLSH] = ACTION_TAP_DANCE_FN_ADVANCED(dance_flsh_each, dance_flsh_finished, dance_flsh_reset)
};
```
### Example 4: 'Quad Function Tap-Dance'
#### Example 4: 'Quad Function Tap-Dance' :id=example-4
By [DanielGGordon](https://github.com/danielggordon)
@ -201,40 +199,37 @@ Below is a specific example:
* Double Tap = Send `Escape`
* Double Tap and Hold = Send `Alt`
## Setup
You will need a few things that can be used for 'Quad Function Tap-Dance'.
You'll need to add these to the top of your `keymap.c` file, before your keymap.
```c
typedef struct {
bool is_press_action;
int state;
bool is_press_action;
uint8_t state;
} tap;
enum {
SINGLE_TAP = 1,
SINGLE_HOLD = 2,
DOUBLE_TAP = 3,
DOUBLE_HOLD = 4,
DOUBLE_SINGLE_TAP = 5, //send two single taps
TRIPLE_TAP = 6,
TRIPLE_HOLD = 7
SINGLE_TAP = 1,
SINGLE_HOLD,
DOUBLE_TAP,
DOUBLE_HOLD,
DOUBLE_SINGLE_TAP, // Send two single taps
TRIPLE_TAP,
TRIPLE_HOLD
};
//Tap dance enums
// Tap dance enums
enum {
X_CTL = 0,
SOME_OTHER_DANCE
X_CTL,
SOME_OTHER_DANCE
};
int cur_dance (qk_tap_dance_state_t *state);
//for the x tap dance. Put it here so it can be used in any keymap
void x_finished (qk_tap_dance_state_t *state, void *user_data);
void x_reset (qk_tap_dance_state_t *state, void *user_data);
uint8_t cur_dance(qk_tap_dance_state_t *state);
// For the x tap dance. Put it here so it can be used in any keymap
void x_finished(qk_tap_dance_state_t *state, void *user_data);
void x_reset(qk_tap_dance_state_t *state, void *user_data);
```
Now, at the bottom of your `keymap.c` file, you'll need to add the following:
@ -267,65 +262,62 @@ Now, at the bottom of your `keymap.c` file, you'll need to add the following:
* For the third point, there does exist the 'DOUBLE_SINGLE_TAP', however this is not fully tested
*
*/
int cur_dance (qk_tap_dance_state_t *state) {
if (state->count == 1) {
if (state->interrupted || !state->pressed) return SINGLE_TAP;
//key has not been interrupted, but they key is still held. Means you want to send a 'HOLD'.
else return SINGLE_HOLD;
}
else if (state->count == 2) {
/*
* DOUBLE_SINGLE_TAP is to distinguish between typing "pepper", and actually wanting a double tap
* action when hitting 'pp'. Suggested use case for this return value is when you want to send two
* keystrokes of the key, and not the 'double tap' action/macro.
*/
if (state->interrupted) return DOUBLE_SINGLE_TAP;
else if (state->pressed) return DOUBLE_HOLD;
else return DOUBLE_TAP;
}
//Assumes no one is trying to type the same letter three times (at least not quickly).
//If your tap dance key is 'KC_W', and you want to type "www." quickly - then you will need to add
//an exception here to return a 'TRIPLE_SINGLE_TAP', and define that enum just like 'DOUBLE_SINGLE_TAP'
if (state->count == 3) {
if (state->interrupted || !state->pressed) return TRIPLE_TAP;
else return TRIPLE_HOLD;
}
else return 8; //magic number. At some point this method will expand to work for more presses
uint8_t cur_dance(qk_tap_dance_state_t *state) {
if (state->count == 1) {
if (state->interrupted || !state->pressed) return SINGLE_TAP;
// Key has not been interrupted, but the key is still held. Means you want to send a 'HOLD'.
else return SINGLE_HOLD;
} else if (state->count == 2) {
// DOUBLE_SINGLE_TAP is to distinguish between typing "pepper", and actually wanting a double tap
// action when hitting 'pp'. Suggested use case for this return value is when you want to send two
// keystrokes of the key, and not the 'double tap' action/macro.
if (state->interrupted) return DOUBLE_SINGLE_TAP;
else if (state->pressed) return DOUBLE_HOLD;
else return DOUBLE_TAP;
}
// Assumes no one is trying to type the same letter three times (at least not quickly).
// If your tap dance key is 'KC_W', and you want to type "www." quickly - then you will need to add
// an exception here to return a 'TRIPLE_SINGLE_TAP', and define that enum just like 'DOUBLE_SINGLE_TAP'
if (state->count == 3) {
if (state->interrupted || !state->pressed) return TRIPLE_TAP;
else return TRIPLE_HOLD;
} else return 8; // Magic number. At some point this method will expand to work for more presses
}
//instanalize an instance of 'tap' for the 'x' tap dance.
// Create an instance of 'tap' for the 'x' tap dance.
static tap xtap_state = {
.is_press_action = true,
.state = 0
.is_press_action = true,
.state = 0
};
void x_finished (qk_tap_dance_state_t *state, void *user_data) {
xtap_state.state = cur_dance(state);
switch (xtap_state.state) {
case SINGLE_TAP: register_code(KC_X); break;
case SINGLE_HOLD: register_code(KC_LCTRL); break;
case DOUBLE_TAP: register_code(KC_ESC); break;
case DOUBLE_HOLD: register_code(KC_LALT); break;
case DOUBLE_SINGLE_TAP: register_code(KC_X); unregister_code(KC_X); register_code(KC_X);
//Last case is for fast typing. Assuming your key is `f`:
//For example, when typing the word `buffer`, and you want to make sure that you send `ff` and not `Esc`.
//In order to type `ff` when typing fast, the next character will have to be hit within the `TAPPING_TERM`, which by default is 200ms.
}
void x_finished(qk_tap_dance_state_t *state, void *user_data) {
xtap_state.state = cur_dance(state);
switch (xtap_state.state) {
case SINGLE_TAP: register_code(KC_X); break;
case SINGLE_HOLD: register_code(KC_LCTRL); break;
case DOUBLE_TAP: register_code(KC_ESC); break;
case DOUBLE_HOLD: register_code(KC_LALT); break;
// Last case is for fast typing. Assuming your key is `f`:
// For example, when typing the word `buffer`, and you want to make sure that you send `ff` and not `Esc`.
// In order to type `ff` when typing fast, the next character will have to be hit within the `TAPPING_TERM`, which by default is 200ms.
case DOUBLE_SINGLE_TAP: tap_code(KC_X); register_code(KC_X);
}
}
void x_reset (qk_tap_dance_state_t *state, void *user_data) {
switch (xtap_state.state) {
case SINGLE_TAP: unregister_code(KC_X); break;
case SINGLE_HOLD: unregister_code(KC_LCTRL); break;
case DOUBLE_TAP: unregister_code(KC_ESC); break;
case DOUBLE_HOLD: unregister_code(KC_LALT);
case DOUBLE_SINGLE_TAP: unregister_code(KC_X);
}
xtap_state.state = 0;
void x_reset(qk_tap_dance_state_t *state, void *user_data) {
switch (xtap_state.state) {
case SINGLE_TAP: unregister_code(KC_X); break;
case SINGLE_HOLD: unregister_code(KC_LCTRL); break;
case DOUBLE_TAP: unregister_code(KC_ESC); break;
case DOUBLE_HOLD: unregister_code(KC_LALT);
case DOUBLE_SINGLE_TAP: unregister_code(KC_X);
}
xtap_state.state = 0;
}
qk_tap_dance_action_t tap_dance_actions[] = {
[X_CTL] = ACTION_TAP_DANCE_FN_ADVANCED(NULL,x_finished, x_reset)
[X_CTL] = ACTION_TAP_DANCE_FN_ADVANCED(NULL, x_finished, x_reset)
};
```
@ -335,90 +327,91 @@ If you want to implement this in your userspace, then you may want to check out
> In this configuration "hold" takes place **after** tap dance timeout (see `ACTION_TAP_DANCE_FN_ADVANCED_TIME`). To achieve instant hold, remove `state->interrupted` checks in conditions. As a result you may use comfortable longer tapping periods to have more time for taps and not to wait too long for holds (try starting with doubled `TAPPING_TERM`).
### Example 5: Using tap dance for advanced mod-tap and layer-tap keys :id=example-5-using-tap-dance-for-advanced-mod-tap-and-layer-tap-keys
#### Example 5: Using tap dance for advanced mod-tap and layer-tap keys :id=example-5
Tap dance can be used to emulate `MT()` and `LT()` behavior when the tapped code is not a basic keycode. This is useful to send tapped keycodes that normally require `Shift`, such as parentheses or curly braces—or other modified keycodes, such as `Control + X`.
Below your layers and custom keycodes, add the following:
```c
// tapdance keycodes
// Tap Dance keycodes
enum td_keycodes {
ALT_LP // Our example key: `LALT` when held, `(` when tapped. Add additional keycodes for each tapdance.
ALT_LP // Our example key: `LALT` when held, `(` when tapped. Add additional keycodes for each tapdance.
};
// define a type containing as many tapdance states as you need
// Define a type containing as many tapdance states as you need
typedef enum {
SINGLE_TAP,
SINGLE_HOLD,
DOUBLE_SINGLE_TAP
SINGLE_TAP,
SINGLE_HOLD,
DOUBLE_SINGLE_TAP
} td_state_t;
// create a global instance of the tapdance state type
// Create a global instance of the tapdance state type
static td_state_t td_state;
// declare your tapdance functions:
// Declare your tapdance functions:
// function to determine the current tapdance state
int cur_dance (qk_tap_dance_state_t *state);
// Function to determine the current tapdance state
uint8_t cur_dance(qk_tap_dance_state_t *state);
// `finished` and `reset` functions for each tapdance keycode
void altlp_finished (qk_tap_dance_state_t *state, void *user_data);
void altlp_reset (qk_tap_dance_state_t *state, void *user_data);
void altlp_finished(qk_tap_dance_state_t *state, void *user_data);
void altlp_reset(qk_tap_dance_state_t *state, void *user_data);
```
Below your `LAYOUT`, define each of the tapdance functions:
```c
// determine the tapdance state to return
int cur_dance (qk_tap_dance_state_t *state) {
if (state->count == 1) {
if (state->interrupted || !state->pressed) { return SINGLE_TAP; }
else { return SINGLE_HOLD; }
}
if (state->count == 2) { return DOUBLE_SINGLE_TAP; }
else { return 3; } // any number higher than the maximum state value you return above
}
// handle the possible states for each tapdance keycode you define:
// Determine the tapdance state to return
uint8_t cur_dance(qk_tap_dance_state_t *state) {
if (state->count == 1) {
if (state->interrupted || !state->pressed) return SINGLE_TAP;
else return SINGLE_HOLD;
}
void altlp_finished (qk_tap_dance_state_t *state, void *user_data) {
td_state = cur_dance(state);
switch (td_state) {
case SINGLE_TAP:
register_code16(KC_LPRN);
break;
case SINGLE_HOLD:
register_mods(MOD_BIT(KC_LALT)); // for a layer-tap key, use `layer_on(_MY_LAYER)` here
break;
case DOUBLE_SINGLE_TAP: // allow nesting of 2 parens `((` within tapping term
tap_code16(KC_LPRN);
register_code16(KC_LPRN);
}
if (state->count == 2) return DOUBLE_SINGLE_TAP;
else return 3; // Any number higher than the maximum state value you return above
}
void altlp_reset (qk_tap_dance_state_t *state, void *user_data) {
switch (td_state) {
case SINGLE_TAP:
unregister_code16(KC_LPRN);
break;
case SINGLE_HOLD:
unregister_mods(MOD_BIT(KC_LALT)); // for a layer-tap key, use `layer_off(_MY_LAYER)` here
break;
case DOUBLE_SINGLE_TAP:
unregister_code16(KC_LPRN);
}
// Handle the possible states for each tapdance keycode you define:
void altlp_finished(qk_tap_dance_state_t *state, void *user_data) {
td_state = cur_dance(state);
switch (td_state) {
case SINGLE_TAP:
register_code16(KC_LPRN);
break;
case SINGLE_HOLD:
register_mods(MOD_BIT(KC_LALT)); // For a layer-tap key, use `layer_on(_MY_LAYER)` here
break;
case DOUBLE_SINGLE_TAP: // Allow nesting of 2 parens `((` within tapping term
tap_code16(KC_LPRN);
register_code16(KC_LPRN);
}
}
// define `ACTION_TAP_DANCE_FN_ADVANCED()` for each tapdance keycode, passing in `finished` and `reset` functions
void altlp_reset(qk_tap_dance_state_t *state, void *user_data) {
switch (td_state) {
case SINGLE_TAP:
unregister_code16(KC_LPRN);
break;
case SINGLE_HOLD:
unregister_mods(MOD_BIT(KC_LALT)); // For a layer-tap key, use `layer_off(_MY_LAYER)` here
break;
case DOUBLE_SINGLE_TAP:
unregister_code16(KC_LPRN);
}
}
// Define `ACTION_TAP_DANCE_FN_ADVANCED()` for each tapdance keycode, passing in `finished` and `reset` functions
qk_tap_dance_action_t tap_dance_actions[] = {
[ALT_LP] = ACTION_TAP_DANCE_FN_ADVANCED(NULL, altlp_finished, altlp_reset)
[ALT_LP] = ACTION_TAP_DANCE_FN_ADVANCED(NULL, altlp_finished, altlp_reset)
};
```
Wrap each tapdance keycode in `TD()` when including it in your keymap, e.g. `TD(ALT_LP)`.
### Example 6: Using tap dance for momentary-layer-switch and layer-toggle keys
#### Example 6: Using tap dance for momentary-layer-switch and layer-toggle keys :id=example-6
Tap Dance can be used to mimic MO(layer) and TG(layer) functionality. For this example, we will set up a key to function as `KC_QUOT` on single-tap, as `MO(_MY_LAYER)` on single-hold, and `TG(_MY_LAYER)` on double-tap.
@ -426,97 +419,92 @@ The first step is to include the following code towards the beginning of your `k
```c
typedef struct {
bool is_press_action;
int state;
bool is_press_action;
uint8_t state;
} tap;
//Define a type for as many tap dance states as you need
// Define a type for as many tap dance states as you need
enum {
SINGLE_TAP = 1,
SINGLE_HOLD = 2,
DOUBLE_TAP = 3
SINGLE_TAP = 1,
SINGLE_HOLD,
DOUBLE_TAP
};
enum {
QUOT_LAYR = 0 //Our custom tap dance key; add any other tap dance keys to this enum
QUOT_LAYR, // Our custom tap dance key; add any other tap dance keys to this enum
};
//Declare the functions to be used with your tap dance key(s)
// Declare the functions to be used with your tap dance key(s)
//Function associated with all tap dances
int cur_dance (qk_tap_dance_state_t *state);
// Function associated with all tap dances
uint8_t cur_dance(qk_tap_dance_state_t *state);
//Functions associated with individual tap dances
void ql_finished (qk_tap_dance_state_t *state, void *user_data);
void ql_reset (qk_tap_dance_state_t *state, void *user_data);
// Functions associated with individual tap dances
void ql_finished(qk_tap_dance_state_t *state, void *user_data);
void ql_reset(qk_tap_dance_state_t *state, void *user_data);
```
Towards the bottom of your `keymap.c`, include the following code:
```c
//Determine the current tap dance state
int cur_dance (qk_tap_dance_state_t *state) {
if (state->count == 1) {
if (!state->pressed) {
return SINGLE_TAP;
} else {
return SINGLE_HOLD;
}
} else if (state->count == 2) {
return DOUBLE_TAP;
}
else return 8;
// Determine the current tap dance state
uint8_t cur_dance(qk_tap_dance_state_t *state) {
if (state->count == 1) {
if (!state->pressed) return SINGLE_TAP;
else return SINGLE_HOLD;
} else if (state->count == 2) return DOUBLE_TAP;
else return 8;
}
//Initialize tap structure associated with example tap dance key
// Initialize tap structure associated with example tap dance key
static tap ql_tap_state = {
.is_press_action = true,
.state = 0
.is_press_action = true,
.state = 0
};
//Functions that control what our tap dance key does
void ql_finished (qk_tap_dance_state_t *state, void *user_data) {
ql_tap_state.state = cur_dance(state);
switch (ql_tap_state.state) {
case SINGLE_TAP:
tap_code(KC_QUOT);
break;
case SINGLE_HOLD:
layer_on(_MY_LAYER);
break;
case DOUBLE_TAP:
//check to see if the layer is already set
if (layer_state_is(_MY_LAYER)) {
//if already set, then switch it off
// Functions that control what our tap dance key does
void ql_finished(qk_tap_dance_state_t *state, void *user_data) {
ql_tap_state.state = cur_dance(state);
switch (ql_tap_state.state) {
case SINGLE_TAP:
tap_code(KC_QUOT);
break;
case SINGLE_HOLD:
layer_on(_MY_LAYER);
break;
case DOUBLE_TAP:
// Check to see if the layer is already set
if (layer_state_is(_MY_LAYER)) {
// If already set, then switch it off
layer_off(_MY_LAYER);
} else {
// If not already set, then switch the layer on
layer_on(_MY_LAYER);
}
break;
}
}
void ql_reset(qk_tap_dance_state_t *state, void *user_data) {
// If the key was held down and now is released then switch off the layer
if (ql_tap_state.state == SINGLE_HOLD) {
layer_off(_MY_LAYER);
} else {
//if not already set, then switch the layer on
layer_on(_MY_LAYER);
}
break;
}
}
ql_tap_state.state = 0;
}
void ql_reset (qk_tap_dance_state_t *state, void *user_data) {
//if the key was held down and now is released then switch off the layer
if (ql_tap_state.state==SINGLE_HOLD) {
layer_off(_MY_LAYER);
}
ql_tap_state.state = 0;
}
//Associate our tap dance key with its functionality
// Associate our tap dance key with its functionality
qk_tap_dance_action_t tap_dance_actions[] = {
[QUOT_LAYR] = ACTION_TAP_DANCE_FN_ADVANCED_TIME(NULL, ql_finished, ql_reset, 275)
[QUOT_LAYR] = ACTION_TAP_DANCE_FN_ADVANCED_TIME(NULL, ql_finished, ql_reset, 275)
};
```
The above code is similar to that used in previous examples. The one point to note is that we need to be able to check which layers are active at any time so we can toggle them if needed. To do this we use the `layer_state_is( layer )` function which returns `true` if the given `layer` is active.
The above code is similar to that used in previous examples. The one point to note is that we need to be able to check which layers are active at any time so we can toggle them if needed. To do this we use the `layer_state_is(layer)` function which returns `true` if the given `layer` is active.
The use of `cur_dance()` and `ql_tap_state` mirrors the above examples.
The `case:SINGLE_TAP` in `ql_finished` is similar to the above examples. The `case:SINGLE_HOLD` works in conjunction with `ql_reset()` to switch to `_MY_LAYER` while the tap dance key is held, and to switch away from `_MY_LAYER` when the key is released. This mirrors the use of `MO(_MY_LAYER)`. The `case:DOUBLE_TAP` works by checking whether `_MY_LAYER` is the active layer, and toggling it on or off accordingly. This mirrors the use of `TG(_MY_LAYER)`.
The `case:SINGLE_TAP` in `ql_finished` is similar to the above examples. The `SINGLE_HOLD` case works in conjunction with `ql_reset()` to switch to `_MY_LAYER` while the tap dance key is held, and to switch away from `_MY_LAYER` when the key is released. This mirrors the use of `MO(_MY_LAYER)`. The `DOUBLE_TAP` case works by checking whether `_MY_LAYER` is the active layer, and toggling it on or off accordingly. This mirrors the use of `TG(_MY_LAYER)`.
`tap_dance_actions[]` works similar to the above examples. Note that I used `ACTION_TAP_DANCE_FN_ADVANCED_TIME()` instead of `ACTION_TAP_DANCE_FN_ADVANCED()`. This is because I like my `TAPPING_TERM` to be short (~175ms) for my non-tap-dance keys but find that this is too quick for me to reliably complete tap dance actions - thus the increased time of 275ms here.
`tap_dance_actions[]` works similar to the above examples. Note that I used `ACTION_TAP_DANCE_FN_ADVANCED_TIME()` instead of `ACTION_TAP_DANCE_FN_ADVANCED()`. This is because I like my `TAPPING_TERM` to be short (\~175ms) for my non-tap-dance keys but find that this is too quick for me to reliably complete tap dance actions - thus the increased time of 275ms here.
Finally, to get this tap dance key working, be sure to include `TD(QUOT_LAYR)` in your `keymaps[]`.

178
docs/feature_unicode.md
View File

@ -2,11 +2,25 @@
Unicode characters can be input straight from your keyboard! There are some limitations, however.
QMK has three different methods for enabling Unicode input and defining keycodes:
In order to enable Unicode support on your keyboard, you will need to do the following:
## Basic Unicode
1. Choose one of three supported Unicode implementations: [Basic Unicode](#basic-unicode), [Unicode Map](#unicode-map), [UCIS](#ucis).
2. Find which [input mode](#input-modes) is the best match for your operating system and setup.
3. [Set](#setting-the-input-mode) the appropriate input mode (or modes) in your configuration.
4. Add Unicode keycodes to your keymap.
This method supports Unicode code points up to `0x7FFF`. This covers characters for most modern languages, as well as symbols, but it doesn't cover emoji.
## 1. Methods :id=methods
QMK supports three different methods for enabling Unicode input and adding Unicode characters to your keymap. Each has its pros and cons in terms of flexibility and ease of use. Choose the one that best fits your use case.
The Basic method should be enough for most users. However, if you need a wider range of supported characters (including emoji, rare symbols etc.), you should use Unicode Map.
<br>
### 1.1. Basic Unicode :id=basic-unicode
The easiest to use method, albeit somewhat limited. It stores Unicode characters as keycodes in the keymap itself, so it only supports code points up to `0x7FFF`. This covers characters for most modern languages (including East Asian), as well as symbols, but it doesn't cover emoji.
Add the following to your `rules.mk`:
@ -14,11 +28,13 @@ Add the following to your `rules.mk`:
UNICODE_ENABLE = yes
```
Then add `UC(c)` keycodes to your keymap, where _c_ is the code point (preferably in hexadecimal, up to 4 digits long). For example: `UC(0x45B)`, `UC(0x30C4)`.
Then add `UC(c)` keycodes to your keymap, where _c_ is the code point of the desired character (preferably in hexadecimal, up to 4 digits long). For example, `UC(0x40B)` will output [Ћ](https://unicode-table.com/en/040B/), and `UC(0x30C4)` will output [ツ](https://unicode-table.com/en/30C4).
## Unicode Map
<br>
This method supports all possible code points (up to `0x10FFFF`); however, you need to maintain a separate mapping table in your keymap file, which may contain at most 16384 entries.
### 1.2. Unicode Map :id=unicode-map
In addition to standard character ranges, this method also covers emoji, ancient scripts, rare symbols etc. In fact, all possible code points (up to `0x10FFFF`) are supported. Here, Unicode characters are stored in a separate mapping table. You need to maintain a `unicode_map` array in your keymap file, which may contain at most 16384 entries.
Add the following to your `rules.mk`:
@ -26,7 +42,7 @@ Add the following to your `rules.mk`:
UNICODEMAP_ENABLE = yes
```
Then add `X(i)` keycodes to your keymap, where _i_ is an array index into the mapping table:
Then add `X(i)` keycodes to your keymap, where _i_ is the desired character's index in the mapping table. This can be a numeric value, but it's recommended to keep the indices in an enum and access them by name.
```c
enum unicode_names {
@ -44,15 +60,17 @@ const uint32_t PROGMEM unicode_map[] = {
Then you can use `X(BANG)`, `X(SNEK)` etc. in your keymap.
### Lower and Upper Case
#### Lower and Upper Case
Characters often come in lower and upper case pairs, such as å and Å. To make inputting these characters easier, you can use `XP(i, j)` in your keymap, where _i_ and _j_ are the mapping table indices of the lower and upper case character, respectively. If you're holding down Shift or have Caps Lock turned on when you press the key, the second (upper case) character will be inserted; otherwise, the first (lower case) version will appear.
This is most useful when creating a keymap for an international layout with special characters. Instead of having to put the lower and upper case versions of a character on separate keys, you can have them both on the same key by using `XP()`. This helps blend Unicode keys in with regular alphas.
Due to keycode size constraints, _i_ and _j_ can each only refer to one of the first 128 characters in your `unicode_map`. In other words, 0 ≤ _i_ ≤ 127 and 0 ≤ _j_ ≤ 127. This is enough for most use cases, but if you'd like to customize the index calculation, you can override the [`unicodemap_index()`](https://github.com/qmk/qmk_firmware/blob/71f640d47ee12c862c798e1f56392853c7b1c1a8/quantum/process_keycode/process_unicodemap.c#L40) function. This also allows you to, say, check Ctrl instead of Shift/Caps.
Due to keycode size constraints, _i_ and _j_ can each only refer to one of the first 128 characters in your `unicode_map`. In other words, 0 ≤ _i_ ≤ 127 and 0 ≤ _j_ ≤ 127. This is enough for most use cases, but if you'd like to customize the index calculation, you can override the [`unicodemap_index()`](https://github.com/qmk/qmk_firmware/blob/71f640d47ee12c862c798e1f56392853c7b1c1a8/quantum/process_keycode/process_unicodemap.c#L36) function. This also allows you to, say, check Ctrl instead of Shift/Caps.
## UCIS
<br>
### 1.3. UCIS :id=ucis
This method also supports all possible code points. As with the Unicode Map method, you need to maintain a mapping table in your keymap file. However, there are no built-in keycodes for this feature — you have to create a custom keycode or function that invokes this functionality.
@ -66,15 +84,18 @@ Then define a table like this in your keymap file:
```c
const qk_ucis_symbol_t ucis_symbol_table[] = UCIS_TABLE(
UCIS_SYM("poop", 0x1F4A9), // 💩
UCIS_SYM("rofl", 0x1F923), // 🤣
UCIS_SYM("kiss", 0x1F619) // 😙
UCIS_SYM("poop", 0x1F4A9), // 💩
UCIS_SYM("rofl", 0x1F923), // 🤣
UCIS_SYM("cuba", 0x1F1E8, 0x1F1FA), // 🇨🇺
UCIS_SYM("look", 0x0CA0, 0x005F, 0x0CA0), // ಠ_ಠ
);
```
To use it, call `qk_ucis_start()`. Then, type the mnemonic for the character (such as "rofl"), and hit Space or Enter. QMK should erase the "rofl" text and insert the laughing emoji.
By default, each table entry may be up to 3 code points long. This number can be changed by adding `#define UCIS_MAX_CODE_POINTS n` to your `config.h` file.
### Customization
To use UCIS input, call `qk_ucis_start()`. Then, type the mnemonic for the character (such as "rofl") and hit Space, Enter or Esc. QMK should erase the "rofl" text and insert the laughing emoji.
#### Customization
There are several functions that you can define in your keymap to customize the functionality of this feature.
@ -84,63 +105,77 @@ There are several functions that you can define in your keymap to customize the
You can find the default implementations of these functions in [`process_ucis.c`](https://github.com/qmk/qmk_firmware/blob/master/quantum/process_keycode/process_ucis.c).
## Input Modes
## 2. Input Modes :id=input-modes
Unicode input in QMK works by inputting a sequence of characters to the OS, sort of like a macro. Unfortunately, the way this is done differs for each platform. Specifically, each platform requires a different combination of keys to trigger Unicode input. Therefore, a corresponding input mode has to be set in QMK.
The following input modes are available:
* **`UC_MAC`**: macOS built-in Unicode hex input. Supports code points up to `0xFFFF` (`0x10FFFF` with Unicode Map).
* **`UC_MAC`**: macOS built-in Unicode hex input. Supports code points up to `0x10FFFF` (all possible code points).
To enable, go to _System Preferences > Keyboard > Input Sources_, add _Unicode Hex Input_ to the list (it's under _Other_), then activate it from the input dropdown in the Menu Bar.
By default, this mode uses the left Option key (`KC_LALT`) for Unicode input, but this can be changed by defining [`UNICODE_KEY_MAC`](#input-key-configuration) with another keycode.
By default, this mode uses the left Option key (`KC_LALT`) for Unicode input, but this can be changed by defining [`UNICODE_KEY_MAC`](#input-key-configuration) with a different keycode.
!> Using the _Unicode Hex Input_ input source may disable some Option based shortcuts, such as Option + Left Arrow and Option + Right Arrow.
!> Using the _Unicode Hex Input_ input source may disable some Option-based shortcuts, such as Option+Left and Option+Right.
!> `UC_OSX` is a deprecated alias of `UC_MAC` that will be removed in a future version of QMK.
!> `UC_OSX` is a deprecated alias of `UC_MAC` that will be removed in future versions of QMK. All new keymaps should use `UC_MAC`.
* **`UC_LNX`**: Linux built-in IBus Unicode input. Supports code points up to `0x10FFFF` (all possible code points).
Enabled by default and works almost anywhere on IBus-enabled distros. Without IBus, this mode works under GTK apps, but rarely anywhere else.
By default, this mode uses Ctrl+Shift+U (`LCTL(LSFT(KC_U))`) to start Unicode input, but this can be changed by defining [`UNICODE_KEY_LNX`](#input-key-configuration) with another keycode. This might be required for IBus versions ≥1.5.15, where Ctrl+Shift+U behavior is consolidated into Ctrl+Shift+E.
By default, this mode uses Ctrl+Shift+U (`LCTL(LSFT(KC_U))`) to start Unicode input, but this can be changed by defining [`UNICODE_KEY_LNX`](#input-key-configuration) with a different keycode. This might be required for IBus versions ≥1.5.15, where Ctrl+Shift+U behavior is consolidated into Ctrl+Shift+E.
* **`UC_WIN`**: _(not recommended)_ Windows built-in hex numpad Unicode input. Supports code points up to `0xFFFF`.
To enable, create a registry key under `HKEY_CURRENT_USER\Control Panel\Input Method\EnableHexNumpad` of type `REG_SZ` called `EnableHexNumpad` and set its value to `1`. This can be done from the Command Prompt by running `reg add "HKCU\Control Panel\Input Method" -v EnableHexNumpad -t REG_SZ -d 1` with administrator privileges. Reboot afterwards.
To enable, create a registry key under `HKEY_CURRENT_USER\Control Panel\Input Method` of type `REG_SZ` called `EnableHexNumpad` and set its value to `1`. This can be done from the Command Prompt by running `reg add "HKCU\Control Panel\Input Method" -v EnableHexNumpad -t REG_SZ -d 1` with administrator privileges. Reboot afterwards.
This mode is not recommended because of reliability and compatibility issues; use the `UC_WINC` mode instead.
* **`UC_BSD`**: _(non implemented)_ Unicode input under BSD. Not implemented at this time. If you're a BSD user and want to help add support for it, please [open an issue on GitHub](https://github.com/qmk/qmk_firmware/issues).
* **`UC_WINC`**: Windows Unicode input using [WinCompose](https://github.com/samhocevar/wincompose). As of v0.9.0, supports code points up to `0x10FFFF` (all possible code points).
To enable, install the [latest release](https://github.com/samhocevar/wincompose/releases/latest). Once installed, WinCompose will automatically run on startup. Works reliably under all version of Windows supported by the app.
By default, this mode uses right Alt (`KC_RALT`) as the Compose key, but this can be changed in the WinCompose settings and by defining [`UNICODE_KEY_WINC`](#input-key-configuration) with another keycode.
To enable, install the [latest release](https://github.com/samhocevar/wincompose/releases/latest). Once installed, WinCompose will automatically run on startup. This mode works reliably under all version of Windows supported by the app.
By default, this mode uses right Alt (`KC_RALT`) as the Compose key, but this can be changed in the WinCompose settings and by defining [`UNICODE_KEY_WINC`](#input-key-configuration) with a different keycode.
### Switching Input Modes
There are two ways to set the input mode for Unicode: by keycode or by function. Keep in mind that both methods write to persistent storage (EEPROM), and are loaded each time the keyboard starts. So once you've set it the first time, you don't need to set it again unless you want to change it, or you've reset the EEPROM settings.
## 3. Setting the Input Mode :id=setting-the-input-mode
You can switch the input mode at any time by using one of the following keycodes. The easiest way is to add the ones you use to your keymap.
|Keycode |Alias |Input Mode |Description |
|----------------------|---------|------------|--------------------------------------------------------------|
|`UNICODE_MODE_FORWARD`|`UC_MOD` |Next in list|[Cycle](#input-mode-cycling) through selected modes |
|`UNICODE_MODE_REVERSE`|`UC_RMOD`|Prev in list|[Cycle](#input-mode-cycling) through selected modes in reverse|
|`UNICODE_MODE_MAC` |`UC_M_MA`|`UC_MAC` |Switch to macOS input |
|`UNICODE_MODE_LNX` |`UC_M_LN`|`UC_LNX` |Switch to Linux input |
|`UNICODE_MODE_WIN` |`UC_M_WI`|`UC_WIN` |Switch to Windows input |
|`UNICODE_MODE_BSD` |`UC_M_BS`|`UC_BSD` |Switch to BSD input (not implemented) |
|`UNICODE_MODE_WINC` |`UC_M_WC`|`UC_WINC` |Switch to Windows input using WinCompose |
You can also switch the input mode by calling `set_unicode_input_mode(x)` in your code, where _x_ is one of the above input mode constants (e.g. `UC_LNX`). Since the function only needs to be called once, it's recommended that you do it in `eeconfig_init_user()` (or a similar function). For example:
To set your desired input mode, add the following define to your `config.h`:
```c
void eeconfig_init_user(void) {
set_unicode_input_mode(UC_LNX);
}
#define UNICODE_SELECTED_MODES UC_LNX
```
### Audio Feedback
This example sets the board's default input mode to `UC_LNX`. You can replace this with `UC_MAC`, `UC_WINC`, or any of the other modes listed [above](#input-modes). The board will automatically use the selected mode on startup, unless you manually switch to another mode (see [below](#keycodes)).
You can also select multiple input modes, which allows you to easily cycle through them using the `UC_MOD`/`UC_RMOD` keycodes.
```c
#define UNICODE_SELECTED_MODES UC_MAC, UC_LNX, UC_WINC
```
Note that the values are separated by commas. The board will remember the last used input mode and will continue using it on next power-up. You can disable this and force it to always start with the first mode in the list by adding `#define UNICODE_CYCLE_PERSIST false` to your `config.h`.
#### Keycodes
You can switch the input mode at any time by using the following keycodes. Adding these to your keymap allows you to quickly switch to a specific input mode, including modes not listed in `UNICODE_SELECTED_MODES`.
|Keycode |Alias |Input Mode |Description |
|----------------------|---------|------------|-----------------------------------------------------------------------------|
|`UNICODE_MODE_FORWARD`|`UC_MOD` |Next in list|Cycle through selected modes, reverse direction when Shift is held |
|`UNICODE_MODE_REVERSE`|`UC_RMOD`|Prev in list|Cycle through selected modes in reverse, forward direction when Shift is held|
|`UNICODE_MODE_MAC` |`UC_M_MA`|`UC_MAC` |Switch to macOS input |
|`UNICODE_MODE_LNX` |`UC_M_LN`|`UC_LNX` |Switch to Linux input |
|`UNICODE_MODE_WIN` |`UC_M_WI`|`UC_WIN` |Switch to Windows input |
|`UNICODE_MODE_BSD` |`UC_M_BS`|`UC_BSD` |Switch to BSD input _(not implemented)_ |
|`UNICODE_MODE_WINC` |`UC_M_WC`|`UC_WINC` |Switch to Windows input using WinCompose |
You can also switch the input mode by calling `set_unicode_input_mode(x)` in your code, where _x_ is one of the above input mode constants (e.g. `UC_LNX`).
?> Using `UNICODE_SELECTED_MODES` is preferable to calling `set_unicode_input_mode()` in `matrix_init_user()` or similar functions, since it's better integrated into the Unicode system and has the added benefit of avoiding unnecessary writes to EEPROM.
#### Audio Feedback
If you have the [Audio feature](feature_audio.md) enabled on the board, you can set melodies to be played when you press the above keys. That way you can have some audio feedback when switching input modes.
@ -154,20 +189,21 @@ For instance, you can add these definitions to your `config.h` file:
#define UNICODE_SONG_WINC UNICODE_WINDOWS
```
### Additional Customization
## Additional Customization
Because Unicode is a large and versatile feature, there are a number of options you can customize to make it work better on your system.
#### Start and Finish Input Functions
### Start and Finish Input Functions
The functions for starting and finishing Unicode input on your platform can be overridden locally. Possible uses include customizing input mode behavior if you don't use the default keys, or adding extra visual/audio feedback to Unicode input.
* `void unicode_input_start(void)` – This sends the initial sequence that tells your platform to enter Unicode input mode. For example, it presses Ctrl+Shift+U on Linux and holds the Option key on macOS.
* `void unicode_input_finish(void)` – This is called to exit Unicode input mode, for example by pressing Space or releasing the Option key.
* `void unicode_input_start(void)` – This sends the initial sequence that tells your platform to enter Unicode input mode. For example, it holds the left Alt key followed by Num+ on Windows, and presses the `UNICODE_KEY_LNX` combination (default: Ctrl+Shift+U) on Linux.
* `void unicode_input_finish(void)` – This is called to exit Unicode input mode, for example by pressing Space or releasing the Alt key.
You can find the default implementations of these functions in [`process_unicode_common.c`](https://github.com/qmk/qmk_firmware/blob/master/quantum/process_keycode/process_unicode_common.c).
#### Input Key Configuration
### Input Key Configuration
You can customize the keys used to trigger Unicode input for macOS, Linux and WinCompose by adding corresponding defines to your `config.h`. The default values match the platforms' default settings, so you shouldn't need to change this unless Unicode input isn't working, or you want to use a different key (e.g. in order to free up left or right Alt).
@ -177,54 +213,47 @@ You can customize the keys used to trigger Unicode input for macOS, Linux and Wi
|`UNICODE_KEY_LNX` |`uint16_t`|`LCTL(LSFT(KC_U))`|`#define UNICODE_KEY_LNX LCTL(LSFT(KC_E))`|
|`UNICODE_KEY_WINC`|`uint8_t` |`KC_RALT` |`#define UNICODE_KEY_WINC KC_RGUI` |
#### Input Mode Cycling
You can choose which input modes are available for cycling through. By default, this is disabled. If you want to enable it, limiting it to just the modes you use makes sense. Note that the values in the list are comma-delimited.
## Sending Unicode Strings
```c
#define UNICODE_SELECTED_MODES UC_MAC, UC_LNX, UC_WIN, UC_WINC
```
QMK provides several functions that allow you to send Unicode input to the host programmatically:
You can cycle through the selected modes by using the `UC_MOD`/`UC_RMOD` keycodes, or by calling `cycle_unicode_input_mode(offset)` in your code (`offset` is how many modes to move forward by, so +1 corresponds to `UC_MOD`).
### `send_unicode_string()`
By default, when the keyboard boots, it will initialize the input mode to the last one you used. You can disable this and make it start with the first mode in the list every time by adding the following to your `config.h`:
```c
#define UNICODE_CYCLE_PERSIST false
```
!> Using `UNICODE_SELECTED_MODES` means you don't have to initially set the input mode in `matrix_init_user()` (or a similar function); the Unicode system will do that for you on startup. This has the added benefit of avoiding unnecessary writes to EEPROM.
## `send_unicode_string()`
This function is much like `send_string()` but allows you to input UTF-8 characters directly, and supports all code points (provided the selected input method also supports it). Make sure your `keymap.c` is formatted in UTF-8 encoding.
This function is much like `send_string()`, but it allows you to input UTF-8 characters directly. It supports all code points, provided the selected input mode also supports it. Make sure your `keymap.c` file is formatted using UTF-8 encoding.
```c
send_unicode_string("(ノಠ痊ಠ)ノ彡┻━┻");
```
## `send_unicode_hex_string()`
Example uses include sending Unicode strings when a key is pressed, as described in [Macros](feature_macros.md).
Similar to `send_unicode_string()`, but the characters are represented by their code point values in ASCII, separated by spaces. For example, the table flip above would be achieved with:
### `send_unicode_hex_string()`
Similar to `send_unicode_string()`, but the characters are represented by their Unicode code points, written in hexadecimal and separated by spaces. For example, the table flip above would be achieved with:
```c
send_unicode_hex_string("0028 30CE 0CA0 75CA 0CA0 0029 30CE 5F61 253B 2501 253B");
```
An easy way to convert your Unicode string to this format is by using [this site](https://r12a.github.io/app-conversion/), and taking the result in the "Hex/UTF-32" section.
An easy way to convert your Unicode string to this format is to use [this site](https://r12a.github.io/app-conversion/) and take the result in the "Hex/UTF-32" section.
## Additional Language Support
In `quantum/keymap_extras/`, you'll see various language files - these work the same way as the alternative layout ones do. Most are defined by their two letter country/language code followed by an underscore and a 4-letter abbreviation of its name. `FR_UGRV` which will result in a `ù` when using a software-implemented AZERTY layout. It's currently difficult to send such characters in just the firmware.
In `quantum/keymap_extras`, you'll see various language files — these work the same way as the ones for alternative layouts such as Colemak or BÉPO. When you include one of these language headers, you gain access to keycodes specific to that language / national layout. Such keycodes are defined by a 2-letter country/language code, followed by an underscore and a 4-letter abbreviation of the character to which the key corresponds. For example, including `keymap_french.h` and using `FR_UGRV` in your keymap will output `ù` when typed on a system with a native French AZERTY layout.
If the primary system layout you use on your machine is different from US ANSI, using these language-specific keycodes can help your QMK keymaps better match what will actually be output on the screen. However, keep in mind that these keycodes are just aliases for the corresponding default US keycodes under the hood, and that the HID protocol used by keyboards is itself inherently based on US ANSI.
## International Characters on Windows
### AutoHotkey allows Windows users to create custom hotkeys among others.
### AutoHotkey
The method does not require Unicode support in the keyboard itself but depends instead of [AutoHotkey](https://autohotkey.com) running in the background.
The method does not require Unicode support in the keyboard itself but instead depends on [AutoHotkey](https://autohotkey.com) running in the background.
First you need to select a modifier combination that is not in use by any of your programs.
CtrlAltWin is not used very widely and should therefore be perfect for this.
Ctrl+Alt+Win is not used very widely and should therefore be perfect for this.
There is a macro defined for a mod-tab combo `LCAG_T`.
Add this mod-tab combo to a key on your keyboard, e.g.: `LCAG_T(KC_TAB)`.
This makes the key behave like a tab key if pressed and released immediately but changes it to the modifier if used with another key.
@ -239,8 +268,5 @@ AutoHotkey inserts the Text right of `Send, ` when this combination is pressed.
### US International
If you enable the US International layout on the system, it will use punctuation to accent the characters.
For instance, typing "\`a" will result in à.
If you enable the US International layout on the system, it will use punctuation to accent the characters. For instance, typing "\`a" will result in à.
You can find details on how to enable this [here](https://support.microsoft.com/en-us/help/17424/windows-change-keyboard-layout).

8
docs/feature_userspace.md
View File

@ -1,6 +1,6 @@
# Userspace: Sharing Code Between Keymaps
If you use more than one keyboard with a similar keymap, you might see the benefit in being able to share code between them. Create your own folder in `users/` named the same as your keymap (ideally your github username, `<name>`) with the following structure:
If you use more than one keyboard with a similar keymap, you might see the benefit in being able to share code between them. Create your own folder in `users/` named the same as your keymap (ideally your GitHub username, `<name>`) with the following structure:
* `/users/<name>/` (added to the path automatically)
* `readme.md` (optional, recommended)
@ -73,7 +73,7 @@ The reason for this, is that `<name>.h` won't be added in time to add settings (
## Readme (`readme.md`)
Please include authorship (your name, github username, email), and optionally [a license that's GPL compatible](https://www.gnu.org/licenses/license-list.html#GPLCompatibleLicenses).
Please include authorship (your name, GitHub username, email), and optionally [a license that's GPL compatible](https://www.gnu.org/licenses/license-list.html#GPLCompatibleLicenses).
You can use this as a template:
```
@ -93,7 +93,7 @@ You should have received a copy of the GNU General Public License
along with this program. If not, see <http://www.gnu.org/licenses/>.
```
You'd want to replace the year, name, email and github username with your info.
You'd want to replace the year, name, email and GitHub username with your info.
Additionally, this is a good place to document your code, if you wish to share it with others.
@ -111,7 +111,7 @@ This is ideal for when you want ensure everything compiles successfully when pre
## Examples
For a brief example, checkout [`/users/_example/`](https://github.com/qmk/qmk_firmware/tree/master/users/drashna).
For a brief example, checkout [`/users/_example/`](https://github.com/qmk/qmk_firmware/tree/master/users/_example).
For a more complicated example, checkout [`/users/drashna/`](https://github.com/qmk/qmk_firmware/tree/master/users/drashna)'s userspace.

6
docs/fr-fr/README.md
View File

@ -4,8 +4,8 @@
[![Statut du build](https://travis-ci.org/qmk/qmk_firmware.svg?branch=master)](https://travis-ci.org/qmk/qmk_firmware)
[![Discord](https://img.shields.io/discord/440868230475677696.svg)](https://discord.gg/Uq7gcHh)
[![Statut de la doc](https://img.shields.io/badge/docs-ready-orange.svg)](https://docs.qmk.fm)
[![Contributeurs Github](https://img.shields.io/github/contributors/qmk/qmk_firmware.svg)](https://github.com/qmk/qmk_firmware/pulse/monthly)
[![Forks Github](https://img.shields.io/github/forks/qmk/qmk_firmware.svg?style=social&label=Fork)](https://github.com/qmk/qmk_firmware/)
[![Contributeurs GitHub](https://img.shields.io/github/contributors/qmk/qmk_firmware.svg)](https://github.com/qmk/qmk_firmware/pulse/monthly)
[![Forks GitHub](https://img.shields.io/github/forks/qmk/qmk_firmware.svg?style=social&label=Fork)](https://github.com/qmk/qmk_firmware/)
## Qu'est-ce que QMK Firmware ?
@ -13,7 +13,7 @@ QMK (*Quantum Mechanical Keyboard*) est une communauté open source qui maintien
## Comment l'obtenir
Si vous souhaitez contribuer à une disposition de clavier (keymap), ou à des fonctionnalités de QMK alors le plus simple est de [forker le dépôt avec Github](https://github.com/qmk/qmk_firmware#fork-destination-box) puis cloner le dépôt localement pour y faire des changements. Vous pourrez pousser vos changements sur github puis ouvrir un [Pull Request](https://github.com/qmk/qmk_firmware/pulls) depuis votre fork Github.
Si vous souhaitez contribuer à une disposition de clavier (keymap), ou à des fonctionnalités de QMK alors le plus simple est de [forker le dépôt avec GitHub](https://github.com/qmk/qmk_firmware#fork-destination-box) puis cloner le dépôt localement pour y faire des changements. Vous pourrez pousser vos changements sur GitHub puis ouvrir un [Pull Request](https://github.com/qmk/qmk_firmware/pulls) depuis votre fork GitHub.
Sinon, vous pouvez aussi le télécharger directement en ([zip](https://github.com/qmk/qmk_firmware/zipball/master), [tar](https://github.com/qmk/qmk_firmware/tarball/master)), ou le cloner avec git en ssh (`git@github.com:qmk/qmk_firmware.git`), ou https (`https://github.com/qmk/qmk_firmware.git`).

2
docs/fr-fr/breaking_changes.md
View File

@ -101,7 +101,7 @@ Ceci est fait immédiatement après la fusion de la branche `future` précédent
* [ ] Regroupe ChangeLog dans un fichier.
* [ ] `git commit -m 'Merge point for <DATE> Breaking Change'`
* [ ] `git push origin future`
* Actions sur Github
* Actions sur GitHub
* [ ] Crée un PR pour `future`
* [ ] S'assurer que Travis ne relève aucun problème
* [ ] Fusion le PR `future`

4
docs/fr-fr/getting_started_github.md
View File

@ -6,11 +6,11 @@ GitHub peut être un peu compliqué pour ceux qui n'y sont pas familier. Ce guid
Commencez par la [page GitHub de QMK](https://github.com/qmk/qmk_firmware), et vous verrez un bouton dans le coin en haut à droite qui indique "Fork":
![Fork on Github](http://i.imgur.com/8Toomz4.jpg)
![Fork on GitHub](http://i.imgur.com/8Toomz4.jpg)
Si vous faites partie d'une organisation, vous aurez besoin de savoir quel compte utiliser pour le fork. Dans la plupart des cas, vous voudrez créer le fork dans votre compte personnel. Une fois le fork complet (cela peut quelques fois prendre un peu de temps), appuyez sur le bouton "Clone or download":
![Download from Github](http://i.imgur.com/N1NYcSz.jpg)
![Download from GitHub](http://i.imgur.com/N1NYcSz.jpg)
Faites attention à sélectionner "HTTPS", et sélectionnez le lien et copiez-le:

2
docs/fr-fr/newbs_best_practices.md
View File

@ -44,7 +44,7 @@ git pull upstream master
git push origin master
```
Cela vous change la branche courante en master, synchronise les données de références du dépôt QMK vers votre ordinateur. La commande pull tire les données de références vers votre branche courante puis les y téleverse. La commande push permet de pousser la branche courante (master) vers votre fork github.
Cela vous change la branche courante en master, synchronise les données de références du dépôt QMK vers votre ordinateur. La commande pull tire les données de références vers votre branche courante puis les y téleverse. La commande push permet de pousser la branche courante (master) vers votre fork GitHub.
### Faire des changements

47
docs/getting_started_docker.md Normal file
View File

@ -0,0 +1,47 @@
# Docker Quick Start
This project includes a Docker workflow that will allow you to build a new firmware for your keyboard very easily without major changes to your primary operating system. This also ensures that when you clone the project and perform a build, you have the exact same environment as anyone else and the QMK build infrastructure. This makes it much easier for people to help you troubleshoot any issues you encounter.
## Requirements
The main prerequisite is a working `docker` install.
* [Docker CE](https://docs.docker.com/install/#supported-platforms)
## Usage
Acquire a local copy of the QMK's repository (including submodules):
```bash
git clone --recurse-submodules https://github.com/qmk/qmk_firmware.git
cd qmk_firmware
```
Run the following command to build a keymap:
```bash
util/docker_build.sh <keyboard>:<keymap>
# For example: util/docker_build.sh planck/rev6:default
```
This will compile the desired keyboard/keymap and leave the resulting `.hex` or `.bin` file in the QMK directory for you to flash. If `:keymap` is omitted, all keymaps are used. Note that the parameter format is the same as when building with `make`.
There is also support for building _and_ flashing the keyboard straight from Docker by specifying the `target` as well:
```bash
util/docker_build.sh keyboard:keymap:target
# For example: util/docker_build.sh planck/rev6:default:flash
```
You can also start the script without any parameters, in which case it will ask you to input the build parameters one by one, which you may find easier to use:
```bash
util/docker_build.sh
# Reads parameters as input (leave blank for all keyboards/keymaps)
```
## FAQ
### Why can't I flash on Windows/macOS
On Windows and macOS, it requires [Docker Machine](http://gw.tnode.com/docker/docker-machine-with-usb-support-on-windows-macos/) to be running. This is tedious to set up, so it's not recommended; use [QMK Toolbox](https://github.com/qmk/qmk_toolbox) instead.
!> Docker for Windows requires [Hyper-V](https://docs.microsoft.com/en-us/virtualization/hyper-v-on-windows/quick-start/enable-hyper-v) to be enabled. This means that it cannot work on versions of Windows which don't have Hyper-V, such as Windows 7, Windows 8 and **Windows 10 Home**.

12
docs/getting_started_github.md
View File

@ -1,16 +1,16 @@
# How to Use Github with QMK
# How to Use GitHub with QMK
Github can be a little tricky to those that aren't familiar with it - this guide will walk through each step of forking, cloning, and submitting a pull request with QMK.
GitHub can be a little tricky to those that aren't familiar with it - this guide will walk through each step of forking, cloning, and submitting a pull request with QMK.
?> This guide assumes you're somewhat comfortable with running things at the command line, and have git installed on your system.
Start on the [QMK Github page](https://github.com/qmk/qmk_firmware), and you'll see a button in the upper right that says "Fork":
Start on the [QMK GitHub page](https://github.com/qmk/qmk_firmware), and you'll see a button in the upper right that says "Fork":
![Fork on Github](http://i.imgur.com/8Toomz4.jpg)
![Fork on GitHub](http://i.imgur.com/8Toomz4.jpg)
If you're a part of an organization, you'll need to choose which account to fork it to. In most circumstances, you'll want to fork it to your personal account. Once your fork is completed (sometimes this takes a little while), click the "Clone or Download" button:
![Download from Github](http://i.imgur.com/N1NYcSz.jpg)
![Download from GitHub](http://i.imgur.com/N1NYcSz.jpg)
And be sure to select "HTTPS", and select the link and copy it:
@ -54,7 +54,7 @@ To https://github.com/whoeveryouare/qmk_firmware.git
+ 20043e64...7da94ac5 master -> master
```
Your changes now exist on your fork on Github - if you go back there (`https://github.com/<whoeveryouare>/qmk_firmware`), you can create a "New Pull Request" by clicking this button:
Your changes now exist on your fork on GitHub - if you go back there (`https://github.com/<whoeveryouare>/qmk_firmware`), you can create a "New Pull Request" by clicking this button:
![New Pull Request](http://i.imgur.com/DxMHpJ8.jpg)

2
docs/he-il/README.md
View File

@ -14,7 +14,7 @@ QMK (*Quantum Mechanical Keyboard*) היא קהילת קוד פתוח (open sour
## איך להשיג אותה
אם אתם מתכננים לתרום מיפוי מקשים, מקלדת או יכולת ל QMK, הדבר הקל ביותר הוא [לעשות פורק לריפו בGithub](https://github.com/qmk/qmk_firmware#fork-destination-box), ולעשות קלון לריפו בסביבה המקומית ושם לבצע את השינויים שלכם, לדחוף אותם ולפתוח [Pull Request](https://github.com/qmk/qmk_firmware/pulls) מהפורק שלך.
אם אתם מתכננים לתרום מיפוי מקשים, מקלדת או יכולת ל QMK, הדבר הקל ביותר הוא [לעשות פורק לריפו בGitHub](https://github.com/qmk/qmk_firmware#fork-destination-box), ולעשות קלון לריפו בסביבה המקומית ושם לבצע את השינויים שלכם, לדחוף אותם ולפתוח [Pull Request](https://github.com/qmk/qmk_firmware/pulls) מהפורק שלך.
אחרת, אפשר להוריד את הקושחה באופן ישיר ([zip](https://github.com/qmk/qmk_firmware/zipball/master), [tar](https://github.com/qmk/qmk_firmware/tarball/master)), או לשכפל אותה באמצעות git (`git@github.com:qmk/qmk_firmware.git`), או https (`https://github.com/qmk/qmk_firmware.git`).

4
docs/he-il/_summary.md
View File

@ -5,7 +5,7 @@
* [מקורות ללמידה](he-il/newbs_learn_more_resources.md)
* [בסיס QMK](he-il/README.md)
* [מבוא לQMK](he-il/getting_started_introduction.md)
* [איך להשתמש בGithub](he-il/getting_started_github.md)
* [איך להשתמש בGitHub](he-il/getting_started_github.md)
* [קבלת עזרה](he-il/getting_started_getting_help.md)
* [שאלות נפוצות](he-il/faq.md)
* [שאלות נפוצות כלליות](he-il/faq_general.md)
@ -27,7 +27,7 @@
* [QMK CLI](he-il/cli.md)
* [QMK CLI Config](he-il/cli_configuration.md)
* [תרומה ל QMK](he-il/contributing.md)
* [איך להשתמש בGithub](he-il/getting_started_github.md)
* [איך להשתמש בGitHub](he-il/getting_started_github.md)
* [קבלת עזרה](he-il/getting_started_getting_help.md)
* [שינויים משמעותיים](he-il/breaking_changes.md)

2
docs/he-il/getting_started_getting_help.md
View File

@ -11,7 +11,7 @@
הפורום הרשמי של QMK נמצא ב - [/r/olkb](https://reddit.com/r/olkb) באתר [reddit.com](https://reddit.com).
## סוגיות Github
## סוגיות GitHub
ניתן לפתוח [סוגייה ב-GitHub](https://github.com/qmk/qmk_firmware/issues). הדבר שימושי במיוחד כאשר הסוגיה דורשת דיון עמוק וארוך או דיבאגינג.
</div>

10
docs/he-il/getting_started_github.md
View File

@ -1,17 +1,17 @@
<div dir="rtl" markdown="1">
# איך להשתמש ב-Github עם QMK
# איך להשתמש ב-GitHub עם QMK
Github עלול להיות קצת טריקי למי שלא מכיר את העבודה איתו - מדריך זה ילווה אתכם שלב אחר שלב דרך ביצוע פעולות fork, clone ו-pull request עם QMK.
GitHub עלול להיות קצת טריקי למי שלא מכיר את העבודה איתו - מדריך זה ילווה אתכם שלב אחר שלב דרך ביצוע פעולות fork, clone ו-pull request עם QMK.
?> מדריך זה מניח שאתם מרגישים בנוח עם הרצה של פקודות בסביבת command line (שורת הפקודה) ו-git מותקן במערכת שלכם.
התחילו ב- [עמוד של QMK ב-Github](https://github.com/qmk/qmk_firmware), ותצמאו כפתור בחלק העליון מימין עם התיכוב "Fork":
התחילו ב- [עמוד של QMK ב-GitHub](https://github.com/qmk/qmk_firmware), ותצמאו כפתור בחלק העליון מימין עם התיכוב "Fork":
![Fork ב-Github](http://i.imgur.com/8Toomz4.jpg)
![Fork ב-GitHub](http://i.imgur.com/8Toomz4.jpg)
אם אתם חלק מארגון, תצטרכו לבחור לאיזה חשבון לבצע פעולת fork. ברוב המבקרים, תרצו לבצע fork לתוך החשבון הפרטי שלכם. ברגע שה-fork הסתיים (לפעמים זה יכול לקחת קצת זמן) הקליקו על כפתור ה-"Clone or Download":
![הורדה מ-Github](http://i.imgur.com/N1NYcSz.jpg)
![הורדה מ-GitHub](http://i.imgur.com/N1NYcSz.jpg)
תוודאו שאתם בוחרים באופצייה של "HTTPS", בחרו את הקישור והעתיקו אותו:

2
docs/ja/_summary.md
View File

@ -106,7 +106,7 @@
* [Velocikey](ja/feature_velocikey.md)
* QMK の開発
* 破壊的な変更
* 互換性を破る変更/Breaking changes
* [概要](ja/breaking_changes.md)
* [プルリクエストにフラグが付けられた](ja/breaking_changes_instructions.md)
* 履歴

120
docs/ja/breaking_changes.md Normal file
View File

@ -0,0 +1,120 @@
# Breaking changes/互換性を破る変更
<!---
grep --no-filename "^[ ]*git diff" docs/ja/*.md | sh
original document: 0.9.0:docs/breaking_changes.md
git diff 0.9.0 HEAD -- docs/breaking_changes.md | cat
-->
このドキュメントは QMK の互換性を破る変更(Breaking change) のプロセスについて説明します。
互換性を破る変更とは、互換性がなかったり潜在的な危険が生じるように QMK の動作を変える変更を指します。
ユーザが QMK ツリーを更新しても自分のキーマップが壊れない事を確信できるように、これらの変更を制限します。(訳注：以後、原文のまま Breaking change を用語として使用します。)
Breaking change ピリオドとは、危険な変更、または予想外の変更を QMK へ行なう PR をマージする時のことです。
付随するテスト期間があるため、問題が起きることはまれか、有りえないと確信しています。
## 過去の Breaking change には何が含まれますか？
* [2020年5月30日](ja/ChangeLog/20200530.md)
* [2020年2月29日](ja/ChangeLog/20200229.md)
* [2019年8月30日](ja/ChangeLog/20190830.md)
## 次の Breaking change はいつですか？
次の Breaking change は2020年8月29日に予定されています。
### 重要な日付
* [x] 2020年 5月30日 - `develop` が作成されました。毎週リベースされます。
* [ ] 2020年 8月 1日 - `develop` は新しいPRを取り込みません。
* [ ] 2020年 8月 1日 - テスターの募集。
* [ ] 2020年 8月27日 - `master`がロックされ、PR はマージされません。
* [ ] 2020年 8月29日 - `develop` を `master` にマージします。
* [ ] 2020年 8月29日 - `master` のロックが解除されます。PR を再びマージすることができます。
## どのような変更が含まれますか？
最新の Breaking change 候補を見るには、[`breaking_change` ラベル](https://github.com/qmk/qmk_firmware/pulls?q=is%3Aopen+label%3Abreaking_change+is%3Apr)を参照してください。
現在から `develop` が閉じられるまでの間に新しい変更が追加される可能性があり、そのラベルが適用された PR はマージされることは保証されていません。
このラウンドに、あなたの Breaking change を含めたい場合は、`breaking_change` ラベルを持つ PR を作成し、`develop` が閉じる前に承認してもらう必要があります。
`develop` が閉じた後は、新しい Breaking change は受け付けられません。
受け入れの基準:
* PR が完了し、マージの準備ができている
* PR が ChangeLog を持つ
# チェックリスト
ここでは、Breaking change プロセスを実行する時に使用する様々なプロセスについて説明します。
## `master` から `develop` をリベースします
これは `develop` が開いている間、毎週金曜日に実行されます。
プロセス:
```
cd qmk_firmware
git checkout master
git pull --ff-only
git checkout develop
git rebase master
git push --force
```
## `develop` ブランチの作成
以前の `develop` ブランチがマージされた直後に、これが発生します。
* `qmk_firmware` git commands
* [ ] `git checkout master`
* [ ] `git pull --ff-only`
* [ ] `git checkout -b develop`
* [ ] Edit `readme.md`
* [ ] これがテストブランチであることを上部に大きな通知で追加します。
* [ ] このドキュメントへのリンクを含めます
* [ ] `git commit -m 'Branch point for <DATE> Breaking Change'`
* [ ] `git tag breakpoint_<YYYY>_<MM>_<DD>`
* [ ] `git tag <next_version>` # ブレーキング ポイント タグがバージョンの増分を混乱させないようにします
* [ ] `git push origin develop`
* [ ] `git push --tags`
## マージの 4 週間前
* `develop` は新しい PR に対して閉じられ、現在の PR の修正のみがマージされる可能性があります。
* テスターの呼び出しを投稿します
* [ ] Discord
* [ ] GitHub PR
* [ ] https://reddit.com/r/olkb
## マージの 1 週間前
* master が < 2 日前> から <マージの日> まで閉じられることを発表します
* [ ] Discord
* [ ] GitHub PR
* [ ] https://reddit.com/r/olkb
## マージの 2 日前
* master が 2 日間閉じられることを発表します
* [ ] Discord
* [ ] GitHub PR
* [ ] https://reddit.com/r/olkb
## マージの日
* `qmk_firmware` git commands
* [ ] `git checkout develop`
* [ ] `git pull --ff-only`
* [ ] `git rebase origin/master`
* [ ] Edit `readme.md`
* [ ] `develop` についてのメモを削除
* [ ] ChangeLog を 1 つのファイルにまとめます。
* [ ] `git commit -m 'Merge point for <DATE> Breaking Change'`
* [ ] `git push origin develop`
* GitHub Actions
* [ ] `develop`の PR を作成します
* [ ] travis がクリーンに戻ったことを確認します
* [ ] `develop` PR をマージします

51
docs/ja/breaking_changes_instructions.md Normal file
View File

@ -0,0 +1,51 @@
# breaking changes/互換性を破る変更: プルリクエストにフラグが付けられた
<!---
grep --no-filename "^[ ]*git diff" docs/ja/*.md | sh
original document: 0.9.0:docs/breaking_changes_instructions.md
git diff 0.9.0 HEAD -- docs/breaking_changes_instructions.md | cat
-->
QMK のメンバーがあなたのプルリクエストに返信し、あなたの提出したものは Breaking change (互換性を破る変更) であると述べている場合があります。メンバーの判断では、あなたが提案した変更は QMK やその利用者にとってより大きな影響を持つと考えられます。
プルリクエストにフラグが立てられる原因となるものには、以下のようなものがあります:
- **ユーザーのキーマップに対する編集**
ユーザーが自分のキーマップを QMK に提出した後、しばらくしてさらに更新してプルリクエストを開いたところ、それが `qmk/qmk_firmware` リポジトリで編集されていたためにマージできなかったことに気づくことがあるかもしれません。すべてのユーザーが Git や GitHub を使いこなせるわけではないので、ユーザー自身で問題を修正できないことに気づくかもしれません。
- **期待される動作の変更**
QMK の動作を変更すると、既存の QMK 機能への変更を組み込んだ新しいファームウェアをフラッシュした場合、ユーザはハードウェアまたは QMK が壊れていると考え、希望する動作を復元する手段がないことに気付くことがあります。
- **ユーザーのアクションを必要とする変更**
変更には、ツールチェインを更新したり、Git で何らかのアクションを取るなど、ユーザーがアクションを行う必要がある場合もあります。
- **精査が必要な変更**
時には、投稿がプロジェクトとしての QMK に影響を与えることもあります。これは、著作権やライセンスの問題、コーディング規約、大規模な機能のオーバーホール、コミュニティによるより広範なテストを必要とする「リスクの高い」変更、あるいは全く別のものである可能性があります。
- **エンドユーザーとのコミュニケーションを必要とする変更**
これには、将来の非推奨化への警告、時代遅れの慣習、その他伝えなければならないが上記のカテゴリのどれかに当てはまらないものが含まれます。
## 何をすればいいのか?
提出したものが Breaking change だと判断された場合、手続きをスムーズに進めるためにできることがいくつかあります。
### PR を分割することを検討する
あなたがコアコードを投稿していて、それが Breaking change プロセスを経る必要がある唯一の理由が、あなたの変更に合わせてキーマップを更新していることである場合、古いキーマップが機能し続けるような方法であなたの機能を投稿できるかどうかを検討してください。
そののち、Breaking change プロセスを経て古いコードを削除する別の PR を提出してください。
### ChangeLog エントリの提供
Breaking change プロセスを経て提出する際には、変更ログのエントリを含めることを我々は要請します。
エントリーは、あなたのプルリクエストが行う変更の短い要約としてください &ndash; [ここの各セクションは changelog として開始されました](ja/ChangeLog/20190830.md "n.b. This should link to the 2019 Aug 30 Breaking Changes doc - @noroadsleft")。
変更ログは `docs/ChangeLog/YYYYMMDD/PR####.md` に置いてください。
ここで、`YYYYMMDD` は QMK の breaking change ブランチ &ndash; 通常は `develop` という名称 &ndash; が `master` ブランチにマージされる日付、`####` はプルリクエストの番号です。
ユーザー側でのアクションを必要とする場合、あなたの変更ログは、どのようなアクションを取らなければならないかをユーザーに指示するか、そのようなアクションを指示する場所にリンクする必要があります。
### 変更点を文書化する
提出物の目的を理解し、それが必要とする可能性のある意味合いやアクションを理解することで、レビュープロセスをより簡単にすることができます。この目的のためには変更履歴で十分かもしれませんが、より広範囲の変更を行う場合には、変更履歴には不向きな詳細レベルが必要になるかもしれません。
あなたのプルリクエストにコメントしたり、質問やコメント、変更要求に対応したりすることは、非常にありがたいことです。
### 助けを求める
あなたの提出物にフラグが立ったことで、あなたはびっくりしてしまったかもしれません。もし、あなた自身が脅されたり、圧倒されたりしていると感じたら、私たちに知らせてください。プルリクエストにコメントするか、[Discord で QMK チームに連絡を取ってください](https://discord.gg/Uq7gcHh)。

15
docs/ja/cli.md
View File

@ -1,8 +1,8 @@
# QMK CLI :id=qmk-cli
<!---
original document: 0.8.58:docs/cli.md
git diff 0.8.58 HEAD -- docs/cli.md | cat
original document: 0.9.19:docs/cli.md
git diff 0.9.19 HEAD -- docs/cli.md | cat
-->
## 概要 :id=overview
@ -11,25 +11,24 @@ QMK CLI を使用すると QMK キーボードの構築と作業が簡単にな
### 必要事項 :id=requirements
CLI は Python 3.5 以上を必要とします。我々は必要事項の数を少なくしようとしていますが、[`requirements.txt`](https://github.com/qmk/qmk_firmware/blob/master/requirements.txt) に列挙されているパッケージもインストールする必要があります。これらは QMK CLI をインストールするときに自動的にインストールされます。
QMK は Python 3.6 以上を必要とします。我々は必要事項の数を少なくしようとしていますが、[`requirements.txt`](https://github.com/qmk/qmk_firmware/blob/master/requirements.txt) に列挙されているパッケージもインストールする必要があります。これらは QMK CLI をインストールするときに自動的にインストールされます。
### Homebrew を使ったインストール (macOS、いくつかの Linux) :id=install-using-homebrew
[Homebrew](https://brew.sh) をインストールしている場合は、タップして QMK をインストールすることができます:
```
brew tap qmk/qmk
brew install qmk
brew install qmk/qmk/qmk
export QMK_HOME='~/qmk_firmware' # オプション、`qmk_firmware` の場所を設定します
qmk setup # これは `qmk/qmk_firmware` をクローンし、オプションでビルド環境をセットアップします
```
### easy_install あるいは pip を使ってインストール :id=install-using-easy_install-or-pip
### pip を使ってインストール :id=install-using-easy_install-or-pip
上のリストにあなたのシステムがない場合は、QMK を手動でインストールすることができます。最初に、python 3.5 (以降)をインストールしていて、pip をインストールしていることを確認してください。次に以下のコマンドを使って QMK をインストールします:
上で列挙した中にあなたのシステムがない場合は、QMK を手動でインストールすることができます。最初に、python 3.6 (以降)をインストールしていて、pip をインストールしていることを確認してください。次に以下のコマンドを使って QMK をインストールします:
```
pip3 install qmk
python3 -m pip install qmk
export QMK_HOME='~/qmk_firmware' # オプション、`qmk_firmware` の場所を設定します
qmk setup # これは `qmk/qmk_firmware` をクローンし、オプションでビルド環境をセットアップします
```

188
docs/ja/cli_commands.md
View File

@ -1,48 +1,18 @@
# QMK CLI コマンド
<!---
original document: 0.8.58:docs/cli.md
git diff 0.8.58 HEAD -- docs/cli.md | cat
original document: 0.9.19:docs/cli_command.md
git diff 0.9.19 HEAD -- docs/cli_command.md | cat
-->
# CLI コマンド
## `qmk cformat`
このコマンドは clang-format を使って C コードを整形します。
引数無しで実行すると、変更された全てのコアコードを整形します。デフォルトでは `git diff` で `origin/master` をチェックし、ブランチは `-b <branch_name>` を使って変更できます。
`-a` で全てのコアコードを整形するか、コマンドラインでファイル名を渡して特定のファイルに対して実行します。
**指定したファイルに対する使い方**:
```
qmk cformat [file1] [file2] [...] [fileN]
```
**全てのコアファイルに対する使い方**:
```
qmk cformat -a
```
**origin/master で変更されたファイルのみに対する使い方**:
```
qmk cformat
```
**branch_name で変更されたファイルのみに対する使い方**:
```
qmk cformat -b branch_name
```
# ユーザー用コマンド
## `qmk compile`
このコマンドにより、任意のディレクトリからファームウェアをコンパイルすることができます。<https://config.qmk.fm> からエクスポートした JSON をコンパイルするか、リポジトリ内でキーマップをコンパイルするか、現在の作業ディレクトリでキーボードをコンパイルすることができます。
このコマンドはディレクトリを認識します。キーボードやキーマップのディレクトリにいる場合、自動的に KEYBOARD や KEYMAP を入力します。
**Configurator Exports での使い方**:
```
@ -113,6 +83,8 @@ $ qmk compile -kb dz60
このコマンドは `qmk compile` に似ていますが、ブートローダを対象にすることもできます。ブートローダはオプションで、デフォルトでは `:flash` に設定されています。
違うブートローダを指定するには、`-bl <bootloader>` を使ってください。利用可能なブートローダの詳細については、[ファームウェアを書き込む](ja/flashing.md)を見てください。
このコマンドはディレクトリを認識します。キーボードやキーマップのディレクトリにいる場合、自動的に KEYBOARD や KEYMAP を入力します。
**Configurator Exports での使い方**:
```
@ -141,16 +113,6 @@ qmk flash -b
qmk config [-ro] [config_token1] [config_token2] [...] [config_tokenN]
```
## `qmk docs`
このコマンドは、ドキュメントを参照または改善するために使うことができるローカル HTTP サーバを起動します。デフォルトのポートは 8936 です。
**使用法**:
```
qmk docs [-p PORT]
```
## `qmk doctor`
このコマンドは環境を調査し、潜在的なビルドあるいは書き込みの問題について警告します。必要に応じてそれらの多くを修正できます。
@ -175,6 +137,32 @@ qmk doctor [-y] [-n]
qmk doctor -n
## `qmk info`
QMK のキーボードやキーマップに関する情報を表示します。キーボードに関する情報を取得したり、レイアウトを表示したり、基礎となるキーマトリックスを表示したり、JSON キーマップをきれいに印刷したりするのに使用できます。
**使用法**:
```
qmk info [-f FORMAT] [-m] [-l] [-km KEYMAP] [-kb KEYBOARD]
```
このコマンドはディレクトリを認識します。キーボードやキーマップのディレクトリにいる場合、自動的に KEYBOARD や KEYMAP を入力します。
**例**:
キーボードの基本情報を表示する:
qmk info -kb planck/rev5
キーボードのマトリクスを表示する:
qmk info -kb ergodox_ez -m
キーボードの JSON キーマップを表示する:
qmk info -kb clueboard/california -km default
## `qmk json2c`
QMK Configurator からエクスポートしたものから keymap.c を生成します。
@ -185,6 +173,86 @@ QMK Configurator からエクスポートしたものから keymap.c を生成
qmk json2c [-o OUTPUT] filename
```
## `qmk list-keyboards`
このコマンドは現在 `qmk_firmware` で定義されている全てのキーボードを列挙します。
**使用法**:
```
qmk list-keyboards
```
## `qmk list-keymaps`
このコマンドは指定されたキーボード(とリビジョン)の全てのキーマップを列挙します。
このコマンドはディレクトリを認識します。キーボードのディレクトリにいる場合、自動的に KEYBOARD を入力します。
**使用法**:
```
qmk list-keymaps -kb planck/ez
```
## `qmk new-keymap`
このコマンドは、キーボードの既存のデフォルトのキーマップに基づいて新しいキーマップを作成します。
このコマンドはディレクトリを認識します。キーボードやキーマップのディレクトリにいる場合、自動的に KEYBOARD や KEYMAP を入力します。
**使用法**:
```
qmk new-keymap [-kb KEYBOARD] [-km KEYMAP]
```
---
# 開発者用コマンド
## `qmk cformat`
このコマンドは clang-format を使って C コードを整形します。
引数無しで実行すると、変更された全てのコアコードを整形します。デフォルトでは `git diff` で `origin/master` をチェックし、ブランチは `-b <branch_name>` を使って変更できます。
`-a` で全てのコアコードを整形するか、コマンドラインでファイル名を渡して特定のファイルに対して実行します。
**指定したファイルに対する使い方**:
```
qmk cformat [file1] [file2] [...] [fileN]
```
**全てのコアファイルに対する使い方**:
```
qmk cformat -a
```
**origin/master で変更されたファイルのみに対する使い方**:
```
qmk cformat
```
**branch_name で変更されたファイルのみに対する使い方**:
```
qmk cformat -b branch_name
```
## `qmk docs`
このコマンドは、ドキュメントを参照または改善するために使うことができるローカル HTTP サーバを起動します。デフォルトのポートは 8936 です。
**使用法**:
```
qmk docs [-p PORT]
```
## `qmk kle2json`
このコマンドにより、生の KLE データから QMK Configurator の JSON へ変換することができます。絶対パスあるいは現在のディレクトリ内のファイル名のいずれかを受け取ります。デフォルトでは、`info.json` が既に存在している場合は上書きしません。上書きするには、`-f` あるいは `--force` フラグを使ってください。
@ -207,36 +275,6 @@ $ qmk kle2json -f kle.txt -f
Ψ Wrote out to info.json
```
## `qmk list-keyboards`
このコマンドは現在 `qmk_firmware` で定義されている全てのキーボードを列挙します。
**使用法**:
```
qmk list-keyboards
```
## `qmk list-keymaps`
このコマンドは指定されたキーボード(とリビジョン)の全てのキーマップを列挙します。
**使用法**:
```
qmk list-keymaps -kb planck/ez
```
## `qmk new-keymap`
このコマンドは、キーボードの既存のデフォルトのキーマップに基づいて新しいキーマップを作成します。
**使用法**:
```
qmk new-keymap [-kb KEYBOARD] [-km KEYMAP]
```
## `qmk pyformat`
このコマンドは `qmk_firmware` 内の python コードを整形します。

6
docs/ja/cli_configuration.md
View File

@ -1,8 +1,8 @@
# QMK CLI 設定
<!---
original document: d598f01cb:docs/cli_configuration.md
git diff d598f01cb HEAD -- docs/cli_configuration.md | cat
original document: 0.9.0:docs/cli_configuration.md
git diff 0.9.0 HEAD -- docs/cli_configuration.md | cat
-->
このドキュメントは `qmk config` がどのように動作するかを説明します。
@ -113,7 +113,7 @@ compile.keymap: skully -> None
|-----|---------------|-------------|
| user.keyboard | None | キーボードのパス (例: `clueboard/66/rev4`) |
| user.keymap | None | キーマップ名 (例: `default`) |
| user.name | None | ユーザの github のユーザ名。 |
| user.name | None | ユーザの GitHub のユーザ名。 |
# 全ての設定オプション

42
docs/ja/compatible_microcontrollers.md Normal file
View File

@ -0,0 +1,42 @@
# 互換性のあるマイクロコントローラ
<!---
original document: 0.9.19:docs/compatible_microcontrollers.md
git diff 0.9.19 HEAD -- docs/compatible_microcontrollers.md | cat
-->
QMK は十分な容量のフラッシュメモリを備えた USB 対応 AVR または ARM マイクロコントローラで実行されます - 一般的に 32kB 以上ですが、ほとんどの機能を無効にすると*ほんの* 16kB に詰め込むことができます。
## Atmel AVR
以下は、USB スタックとして [LUFA](https://www.fourwalledcubicle.com/LUFA.php) を使います:
* [ATmega16U2](https://www.microchip.com/wwwproducts/en/ATmega16U2) / [ATmega32U2](https://www.microchip.com/wwwproducts/en/ATmega32U2)
* [ATmega16U4](https://www.microchip.com/wwwproducts/en/ATmega16U4) / [ATmega32U4](https://www.microchip.com/wwwproducts/en/ATmega32U4)
* [AT90USB64](https://www.microchip.com/wwwproducts/en/AT90USB646) / [AT90USB128](https://www.microchip.com/wwwproducts/en/AT90USB1286)
組み込みの USB インターフェースを持たない、いくつかの MCU は代わりに [V-USB](https://www.obdev.at/products/vusb/index.html) を使います:
* [ATmega32A](https://www.microchip.com/wwwproducts/en/ATmega32A)
* [ATmega328P](https://www.microchip.com/wwwproducts/en/ATmega328P)
* [ATmega328](https://www.microchip.com/wwwproducts/en/ATmega328)
## ARM
[ChibiOS](http://www.chibios.org) がサポートする USB 付きの ARM チップを使うこともできます。ほとんどのチップには十分な容量のフラッシュメモリがあります。動作するとわかっているのは:
### STMicroelectronics (STM32)
* [STM32F0x2](https://www.st.com/en/microcontrollers-microprocessors/stm32f0x2.html)
* [STM32F103](https://www.st.com/en/microcontrollers-microprocessors/stm32f103.html)
* [STM32F303](https://www.st.com/en/microcontrollers-microprocessors/stm32f303.html)
### NXP (Kinetis)
* [MKL26Z64](https://www.nxp.com/products/processors-and-microcontrollers/arm-microcontrollers/general-purpose-mcus/kl-series-cortex-m0-plus/kinetis-kl2x-72-96-mhz-usb-ultra-low-power-microcontrollers-mcus-based-on-arm-cortex-m0-plus-core:KL2x)
* [MK20DX128](https://www.nxp.com/products/processors-and-microcontrollers/arm-microcontrollers/general-purpose-mcus/k-series-cortex-m4/k2x-usb/kinetis-k20-50-mhz-full-speed-usb-mixed-signal-integration-microcontrollers-based-on-arm-cortex-m4-core:K20_50)
* [MK20DX256](https://www.nxp.com/products/processors-and-microcontrollers/arm-microcontrollers/general-purpose-mcus/k-series-cortex-m4/k2x-usb/kinetis-k20-72-mhz-full-speed-usb-mixed-signal-integration-microcontrollers-mcus-based-on-arm-cortex-m4-core:K20_72)
## Atmel ATSAM
Atmel の ATSAM マイクロコントローラの一つである、[Massdrop keyboards](https://github.com/qmk/qmk_firmware/tree/master/keyboards/massdrop) で使用されている [ATSAMD51J18A](https://www.microchip.com/wwwproducts/en/ATSAMD51J18A) には限定的なサポートがあります。

67
docs/ja/configurator_step_by_step.md Normal file
View File

@ -0,0 +1,67 @@
# QMK Configurator: ステップ・バイ・ステップ
<!---
grep --no-filename "^[ ]*git diff" docs/ja/*.md | sh
original document: 0.9.0:docs/configurator_step_by_step.md
git diff 0.9.0 HEAD -- docs/configurator_step_by_step.md | cat
-->
このページでは、QMK Configurator でファームウェアを構築する手順を説明します。
## ステップ 1: キーボードを選ぶ
ドロップダウンボックスをクリックして、キーマップを作成するキーボードを選択します。
?> **キーボードに複数のバージョンがある場合は、正しいバージョンを選択してください。**
大事なことなのでもう一度言います。
!> **正しいバージョンを選択してください!**
キーボードが QMK を搭載していると宣伝されていてもリストにない場合は、開発者がまだ作業中か、私たちがまだマージするきっかけがなかった可能性があります。
アクティブな [プルリクエスト](https://github.com/qmk/qmk_firmware/pulls?q=is%3Aopen+is%3Apr+label%3Akeyboard) がない場合、[qmk_firmware](https://github.com/qmk/qmk_firmware/issues)で報告して、その特定のキーボードのサポートをリクエストします。
製作者自身の GitHub アカウントにある QMK 搭載キーボードもあります。
それも再確認してください。
## ステップ2: キーボードのレイアウトを選択する
作成したいと思うキーマップに最も近いレイアウトを選択します。一部のキーボードには、まだ十分なレイアウトや正しいレイアウトが定義されていません。これらは将来サポートされる予定です。
## ステップ3: キーマップの名前を決める
お好みの名前をキーマップにつけます。
?> コンパイル時に問題が発生した場合は、もしかすると QMK ファームウェアリポジトリに既に同じ名前が存在しているのかもしれません。名前を変更してみてください。
## ステップ4: キーマップを定義する
キーコードの入力は、3つの方法のいずれかで行います。
1. ドラッグ・アンド・ドロップ
2. レイアウト上の空の場所をクリックして、希望するキーコードをクリックします
3. レイアウト上の空の場所をクリックして、キーボードの物理キーを押します
?> マウスをキーの上に置くと、そのキーコードの機能の短い説明文が出ます。より詳細な説明については以下を見てください:
* [基本的なキーコードリファレンス](ja/keycodes_basic.md)
* [高度なキーコードリファレンス](ja/feature_advanced_keycodes.md)
!> 選択したレイアウトが物理的なビルドと一致しない場合は、使用していないキーは空白のままにしておきます。どのキーが使用されているかわからない場合、例えば、バックスペースキーは1つだが `LAYOUT_all` には2つのキーがある場合は、同じキーコードを両方の場所に配置してください。
## ステップ5: 後日のためにキーマップを保存する
キーマップに満足するか、または後で作業したい場合は、`Export Keymap' ボタンを押します。
これでキーマップがあなたのコンピュータに保存されます。
その後、`Import Keymap` ボタンを押すことで、この .json ファイルを後で読み込むことができます。
!> **注意:** このファイルは、kbfirmware.com またはその他のツールに使用される .json ファイルと同じ形式ではありません。これらのツールにこの .json を使用したり、QMK Configurator でこれらのツールの .json を使用しようとすると、問題が発生します。
## ステップ6: ファームウェアをコンパイルする
緑色の `Compile` ボタンを押します。
コンパイルが完了すると、緑色の `Download Firmware` ボタンを押すことができます。
## 次のステップ: キーボードに書き込む(フラッシュする)
[ファームウェアを書きこむ](ja/newbs_flashing.md) を参照してください。

32
docs/ja/configurator_troubleshooting.md Normal file
View File

@ -0,0 +1,32 @@
# Configurator トラブルシューティング
<!---
grep --no-filename "^[ ]*git diff" docs/ja/*.md | sh
original document: 0.9.0:docs/configurator_troubleshooting.md
git diff 0.9.0 HEAD -- docs/configurator_troubleshooting.md | cat
-->
## 私の .json ファイルが動きません
.json ファイルが QMK Configurator で作ったものの場合、おめでとうございます。バグに遭遇しました。 [qmk_configurator](https://github.com/qmk/qmk_configurator/issues) で報告してください。
そうでない場合は、... 他の .json ファイルを使用しないようにという、上に書いた注意書きを見逃してませんか？
#### レイアウトに余分なスペースがありますか？どうすればいいですか？
もしスペースバーが3つに分かれている場合は、全てスペースバーで埋めるのが最善の方法です。バックスペースや Shift キーについても同じことができます。
#### キーコードってなに？
以下を見てください。
* [基本的なキーコードリファレンス](ja/keycodes_basic.md)
* [高度なキーコードリファレンス](ja/feature_advanced_keycodes.md)
#### コンパイルできません
キーマップの他のレイヤーを再確認して、おかしなキーが存在しないことを確認してください。
## 問題とバグ
私たちは利用者の依頼やバグレポートを常に受け入れています。[qmk_configurator](https://github.com/qmk/qmk_configurator/issues) で報告してください。

8
docs/ja/custom_quantum_functions.md
View File

@ -62,7 +62,7 @@ bool process_record_user(uint16_t keycode, keyrecord_t *record) {
case KC_ENTER:
// enter が押された時に音を再生します
if (record->event.pressed) {
PLAY_NOTE_ARRAY(tone_qwerty);
PLAY_SONG(tone_qwerty);
}
return true; // QMK に enter のプレスまたはリリースイベントを送信させます
default:
@ -440,7 +440,7 @@ bool process_record_user(uint16_t keycode, keyrecord_t *record) {
case KC_ENTER:
// enter が押された時に音を再生します
if (record->event.pressed) {
PLAY_NOTE_ARRAY(tone_qwerty);
PLAY_SONG(tone_qwerty);
}
return true; // QMK に enter のプレスまたはリリースイベントを送信させます
case RGB_LYR: // これにより、アンダーグローをレイヤー表示として、あるいは通常通りに使うことができます。
@ -511,7 +511,7 @@ void eeconfig_init_user(void) { // EEPROM がリセットされます！
キーコードに基づいて `TAPPING_TERM` を変更するには、次のようなものを `keymap.c` ファイルに追加します:
```c
uint16_t get_tapping_term(uint16_t keycode) {
uint16_t get_tapping_term(uint16_t keycode, keyrecord_t *record) {
switch (keycode) {
case SFT_T(KC_SPC):
return TAPPING_TERM + 1250;
@ -528,7 +528,7 @@ uint16_t get_tapping_term(uint16_t keycode) {
キーコードに基づいて `IGNORE_MOD_TAP_INTERRUPT` の値を変更するには、次のようなものを `keymap.c` ファイルに追加します:
```c
bool get_ignore_mod_tap_interrupt(uint16_t keycode) {
bool get_ignore_mod_tap_interrupt(uint16_t keycode, keyrecord_t *record) {
switch (keycode) {
case SFT_T(KC_SPC):
return true;

69
docs/ja/documentation_best_practices.md Normal file
View File

@ -0,0 +1,69 @@
# ドキュメントベストプラクティス
<!---
original document: 0.9.19:docs/documentation_best_practices.md
git diff 0.9.19 HEAD -- docs/documentation_best_practices.md | cat
-->
このページは QMK のためのドキュメントを作成する時のベストプラクティスを文章化するためのものです。これらのガイドラインに従うことで、一貫したトーンとスタイルを維持することでき、他の人が QMK をより理解しやすくすることができます。
# ページの開始
ドキュメントページは通常 H1 ヘッダで始まり、最初の段落を使ってこのページの内容を説明します。この見出しと段落は目次の次にあるため、見出しは短くして空白の無い長い文字列を避けるように気を付けてください。
例:
```
# My Page Title
This page covers my super cool feature. You can use this feature to make coffee, squeeze fresh oj, and have an egg mcmuffin and hashbrowns delivered from your local macca's by drone.
```
# 見出し
通常、ページには複数の "H1" 見出しが有るべきです。H1 と H2 見出しのみが目次に含まれるので、適切に計画してください。目次が広くなりすぎないように、H1 と H2 の見出しでは幅を広げないようにしてください。
# スタイル付きのヒントブロック
注意を引くためにテキストの周りにスタイル付きのヒントブロックを描くことができます。
### 重要なもの
```
!> This is important
```
以下のように表示されます:
!> This is important
### 一般的なヒント
```
?> This is a helpful tip.
```
以下のように表示されます:
?> This is a helpful tip.
# 機能を文章化する
QMK のために新しい機能を作成した場合、そのドキュメントページを作成してください。長い必要は無く、機能を説明する幾つかの文と、関連するキーコードを列挙した表で十分です。以下は基本的なテンプレートです:
```markdown
# My Cool Feature
This page describes my cool feature. You can use my cool feature to make coffee and order cream and sugar to be delivered via drone.
## My Cool Feature Keycodes
|Long Name|Short Name|Description|
|---------|----------|-----------|
|KC_COFFEE||Make Coffee|
|KC_CREAM||Order Cream|
|KC_SUGAR||Order Sugar|
```
ドキュメントを `docs/feature_<my_cool_feature>.md` に配置し、そのファイルを `docs/_summary.md` の適切な場所に追加します。キーコードを追加した場合は、機能ページに戻るリンクとともに `docs/keycodes.md` に追加するようにしてください。

45
docs/ja/documentation_templates.md Normal file
View File

@ -0,0 +1,45 @@
# ドキュメントテンプレート
<!---
original document: 0.9.19:docs/documentation_templates.md
git diff 0.9.19 HEAD -- docs/documentation_templates.md | cat
-->
このページでは、新しいキーマップやキーボードを QMK に提出する際に使うべきテンプレートをまとめています。
## キーマップ `readme.md` テンプレート :id=keyboard-readmemd-template
ほとんどのキーマップには、レイアウトを表す画像があります。画像を作成するには、[Keyboard Layout Editor](http://keyboard-layout-editor.com) を使うことができます。画像は [Imgur](http://imgur.com) や別のホスティングサービスにアップロードし、プルリクエストに画像を含めないでください。
画像の下には、キーマップを理解してもらうための簡単な説明文を書いてください。
```
![Clueboard Layout Image](http://i.imgur.com/7Capi8W.png)
# Default Clueboard Layout
This is the default layout that comes flashed on every Clueboard. For the most
part it's a straightforward and easy to follow layout. The only unusual key is
the key in the upper left, which sends Escape normally, but Grave when any of
the Ctrl, Alt, or GUI modifiers are held down.
```
## キーボード `readme.md` テンプレート
```
# Planck
![Planck](http://i.imgur.com/q2M3uEU.jpg)
A compact 40% (12x4) ortholinear keyboard kit made and sold by OLKB and Massdrop. [More info on qmk.fm](http://qmk.fm/planck/)
* Keyboard Maintainer: [Jack Humbert](https://github.com/jackhumbert)
* Hardware Supported: Planck PCB rev1, rev2, rev3, rev4, Teensy 2.0
* Hardware Availability: [OLKB.com](https://olkb.com), [Massdrop](https://www.massdrop.com/buy/planck-mechanical-keyboard?mode=guest_open)
Make example for this keyboard (after setting up your build environment):
make planck/rev4:default
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).
```

4
docs/ja/driver_installation_zadig.md
View File

@ -1,8 +1,8 @@
# Zadig を使ったブートローダドライバのインストール
<!---
original document: d598f01cb:docs/driver_installation_zadig.md
git diff d598f01cb HEAD -- docs/driver_installation_zadig.md | cat
original document: 0.9.0:docs/driver_installation_zadig.md
git diff 0.9.0 HEAD -- docs/driver_installation_zadig.md | cat
-->
QMK はホストにたいして通常の HID キーボードデバイスとして振る舞うため特別なドライバは必要ありません。しかし、Windows でのキーボードへの書き込みは、多くの場合、キーボードをリセットした時に現れるブートローダデバイスで*行います*。

46
docs/ja/faq_build.md
View File

@ -1,8 +1,8 @@
# よくあるビルドの質問
<!---
original document: 0f43c2652:docs/faq_build.md
git diff 0f43c2652 HEAD -- docs/faq_build.md | cat
original document: 0.9.10:docs/faq_build.md
git diff 0.9.10 HEAD -- docs/faq_build.md | cat
-->
このページは QMK のビルドに関する質問を説明します。まだビルドをしていない場合は、[ビルド環境のセットアップ](ja/getting_started_build_tools.md) および [Make 手順](ja/getting_started_make_guide.md)ガイドを読むべきです。
@ -32,33 +32,30 @@ sudo udevadm trigger
**/etc/udev/rules.d/50-atmel-dfu.rules:**
```
# Atmel ATMega32U4
SUBSYSTEMS=="usb", ATTRS{idVendor}=="03eb", ATTRS{idProduct}=="2ff4", MODE:="0666"
SUBSYSTEMS=="usb", ATTRS{idVendor}=="03eb", ATTRS{idProduct}=="2ff4", TAG+="uaccess", RUN{builtin}+="uaccess"
# Atmel USBKEY AT90USB1287
SUBSYSTEMS=="usb", ATTRS{idVendor}=="03eb", ATTRS{idProduct}=="2ffb", MODE:="0666"
SUBSYSTEMS=="usb", ATTRS{idVendor}=="03eb", ATTRS{idProduct}=="2ffb", TAG+="uaccess", RUN{builtin}+="uaccess"
# Atmel ATMega32U2
SUBSYSTEMS=="usb", ATTRS{idVendor}=="03eb", ATTRS{idProduct}=="2ff0", MODE:="0666"
SUBSYSTEMS=="usb", ATTRS{idVendor}=="03eb", ATTRS{idProduct}=="2ff0", TAG+="uaccess", RUN{builtin}+="uaccess"
```
**/etc/udev/rules.d/52-tmk-keyboard.rules:**
```
# tmk keyboard products https://github.com/tmk/tmk_keyboard
SUBSYSTEMS=="usb", ATTRS{idVendor}=="feed", MODE:="0666"
```
**/etc/udev/rules.d/54-input-club-keyboard.rules:**
```
# Input Club keyboard bootloader
SUBSYSTEMS=="usb", ATTRS{idVendor}=="1c11", MODE:="0666"
SUBSYSTEMS=="usb", ATTRS{idVendor}=="1c11", ATTRS{idProduct}=="b007", TAG+="uaccess", RUN{builtin}+="uaccess"
```
**/etc/udev/rules.d/55-caterina.rules:**
```
# ModemManager should ignore the following devices
ATTRS{idVendor}=="2a03", ENV{ID_MM_DEVICE_IGNORE}="1"
ATTRS{idVendor}=="2341", ENV{ID_MM_DEVICE_IGNORE}="1"
SUBSYSTEMS=="usb", ATTRS{idVendor}=="2a03", ATTRS{idProduct}=="0036", TAG+="uaccess", RUN{builtin}+="uaccess", ENV{ID_MM_DEVICE_IGNORE}="1"
SUBSYSTEMS=="usb", ATTRS{idVendor}=="2341", ATTRS{idProduct}=="0036", TAG+="uaccess", RUN{builtin}+="uaccess", ENV{ID_MM_DEVICE_IGNORE}="1"
SUBSYSTEMS=="usb", ATTRS{idVendor}=="1b4f", ATTRS{idProduct}=="9205", TAG+="uaccess", RUN{builtin}+="uaccess", ENV{ID_MM_DEVICE_IGNORE}="1"
SUBSYSTEMS=="usb", ATTRS{idVendor}=="1b4f", ATTRS{idProduct}=="9203", TAG+="uaccess", RUN{builtin}+="uaccess", ENV{ID_MM_DEVICE_IGNORE}="1"
```
**注意:** ModemManager フィルタリングは厳格モードでは無い場合のみ動作します。以下のコマンドでその設定を変更することができます:
**注意:** 古い(1.12以前の) ModemManager では、フィルタリングは厳密なモードではない場合にのみ動作し、以下のコマンドはその設定を更新することができます。
```console
sudo sed -i 's/--filter-policy=strict/--filter-policy=default/' /lib/systemd/system/ModemManager.service
sudo systemctl daemon-reload
@ -68,15 +65,15 @@ sudo systemctl restart ModemManager
**/etc/udev/rules.d/56-dfu-util.rules:**
```
# stm32duino
SUBSYSTEMS=="usb", ATTRS{idVendor}=="1eaf", ATTRS{idProduct}=="0003", MODE:="0666"
SUBSYSTEMS=="usb", ATTRS{idVendor}=="1eaf", ATTRS{idProduct}=="0003", TAG+="uaccess", RUN{builtin}+="uaccess"
# Generic stm32
SUBSYSTEMS=="usb", ATTRS{idVendor}=="0483", ATTRS{idProduct}=="df11", MODE:="0666"
SUBSYSTEMS=="usb", ATTRS{idVendor}=="0483", ATTRS{idProduct}=="df11", TAG+="uaccess", RUN{builtin}+="uaccess"
```
**/etc/udev/rules.d/57-bootloadhid.rules:**
```
# bootloadHID
SUBSYSTEMS=="usb", ATTRS{idVendor}=="16c0", ATTRS{idProduct}=="05df", MODE:="0666"
SUBSYSTEMS=="usb", ATTRS{idVendor}=="16c0", ATTRS{idProduct}=="05df", TAG+="uaccess", RUN{builtin}+="uaccess"
```
### Linux のブートローダモードで Serial デバイスが検知されない
@ -116,23 +113,14 @@ OPT_DEFS += -DBOOTLOADER_SIZE=2048
```
## MacOS での `avr-gcc: internal compiler error: Abort trap: 6 (program cc1)`
これは brew での更新に関する問題で、avr-gcc が依存するシンボリックリンクを壊します。
解決法は全ての影響を受けたモジュールを削除し再インストールすることです。
```
brew rm avr-gcc
brew rm avr-gcc@8
brew rm dfu-programmer
brew rm dfu-util
brew rm gcc-arm-none-eabi
brew rm arm-gcc-bin@8
brew rm avrdude
brew install avr-gcc@8
brew install dfu-programmer
brew install dfu-util
brew install arm-gcc-bin@8
brew install avrdude
brew rm avr-gcc avr-gcc@8 dfu-programmer dfu-util gcc-arm-none-eabi arm-gcc-bin@8 avrdude qmk
brew install qmk/qmk/qmk
brew link --force avr-gcc@8
brew link --force arm-gcc-bin@8
```

4
docs/ja/faq_debug.md
View File

@ -1,8 +1,8 @@
# デバッグの FAQ
<!---
original document: 376419a4f:docs/faq_debug.md
git diff 376419a4f HEAD -- docs/faq_debug.md | cat
original document: 0.9.10:docs/faq_debug.md
git diff 0.9.10 HEAD -- docs/faq_debug.md | cat
-->
このページは、キーボードのトラブルシューティングについての様々な一般的な質問を説明します。

57
docs/ja/feature_advanced_keycodes.md
View File

@ -1,53 +1,10 @@
# レイヤーの切り替えとトグル :id=switching-and-toggling-layers
# 修飾キー :id=modifier-keys
<!---
original document: 5d5ff80:docs/feature_advanced_keycodes.md
git diff 5d5ff80 HEAD -- docs/feature_advanced_keycodes.md | cat
original document: 0.9.0:docs/feature_advanced_keycodes.md
git diff 0.9.0 HEAD -- docs/feature_advanced_keycodes.md | cat
-->
これらの機能により、様々な方法でレイヤーをアクティブ化することができます。レイヤーは一般的に独立したレイアウトでは無いことに注意してください -- 複数のレイヤーを一度にアクティブ化することができ、レイヤーが `KC_TRNS` を使ってキーの押下を下のレイヤーに渡すことが一般的です。レイヤーの詳細については、[キーマップの概要](ja/keymap.md#keymap-and-layers)を見てください。MO()、LM()、TT() あるいは LT() を使って一時的なレイヤーの切り替えを使う場合、上のレイヤーのキーを透過にするようにしてください。さもないと意図したように動作しないかもしれません。
* `DF(layer)` - デフォルトレイヤーを切り替えます。デフォルトレイヤーは、他のレイヤーがその上に積み重なっている、常にアクティブな基本レイヤーです。デフォルトレイヤーの詳細については以下を見てください。これは QWERTY から Dvorak レイアウトに切り替えるために使うことができます。(これは一時的な切り替えであり、キーボードの電源が切れるまでしか持続しないことに注意してください。デフォルトレイヤーを永続的に変更するには、[process_record_user](ja/custom_quantum_functions.md#programming-the-behavior-of-any-keycode) 内で `set_single_persistent_default_layer` 関数を呼び出すなど、より深いカスタマイズが必要です。)
* `MO(layer)` - 一時的に*レイヤー*をアクティブにします。キーを放すとすぐに、レイヤーは非アクティブになります。
* `LM(layer, mod)` - (`MO` のように)一時的に*レイヤー*をアクティブにしますが、モディファイア *mod* がアクティブな状態です。layer 0-15 と、左モディファイアのみをサポートします: `MOD_LCTL`、`MOD_LSFT`、`MOD_LALT`、`MOD_LGUI` (`KC_` の代わりに `MOD_` 定数を使うことに注意してください)。これらのモディファイアは、例えば `LM(_RAISE, MOD_LCTL | MOD_LALT)` のように、ビット単位の OR を使って組み合わせることができます。
* `LT(layer, kc)` - ホールドされた時に*レイヤー*を一時的にアクティブにし、タップされた時に *kc* を送信します。layer 0-15 のみをサポートします。
* `OSL(layer)` - 次のキーが押されるまで、一時的に*レイヤー*をアクティブにします。詳細と追加機能については、[ワンショットキー](ja/one_shot_keys.md)を見てください。
* `TG(layer)` - *レイヤー*を切り替えます。非アクティブな場合はアクティブにし、逆も同様です。
* `TO(layer)` - *レイヤー*をアクティブにし、他の全てのレイヤー(デフォルトレイヤーを除く)を非アクティブにします。この関数は特別です。1つのレイヤーをアクティブなレイヤースタックに追加/削除する代わりに、現在のアクティブなレイヤーを完全に置き換え、唯一上位のレイヤーを下位のレイヤーで置き換えることができるからです。これはキーダウンで(キーが押されるとすぐに)アクティブになります。
* `TT(layer)` - レイヤーのタップ切り替え。キーを押したままにすると*レイヤー*がアクティブにされ、放すと非アクティブになります (`MO` 風)。繰り返しタップすると、レイヤーはオンあるいはオフを切り替えます (`TG` 風)。デフォルトでは5回のタップが必要ですが、`TAPPING_TOGGLE` を定義することで変更することができます -- 例えば、2回のタップだけで切り替えるには、`#define TAPPING_TOGGLE 2` を定義します。
## 注意事項
現在のところ、`LT()` と `MT()` は[基本的なキーコードセット](ja/keycodes_basic.md)に制限されています。つまり、`LCTL()`、`KC_TILD` あるいは `0xFF` より大きなキーコードを使うことができません。レイヤータップあるいはモッドタップのキーコードの一部として指定されたモディファイアは無視されます。タップしたキーコードにモディファイアを適用する必要がある場合は、[タップダンス](ja/feature_tap_dance.md#example-5-using-tap-dance-for-advanced-mod-tap-and-layer-tap-keys)を使うことができます。
さらに、モッドタップあるいはレイヤータップで少なくとも1つの右手用のモディファイアが指定された場合、指定された全てのモディファイアが右手用になるため、2つをうまく組み合わせて一致させることはできません。
# レイヤーの使用
レイヤーを切り替える時は注意してください。(キーボードを取り外さずに)そのレイヤーを非アクティブにすることができずレイヤーから移動できなくなる可能性があります。最も一般的な問題を避けるためのガイドラインを作成しました。
## 初心者
QMK を使い始めたばかりの場合は、全てを単純にしたいでしょう。レイヤーをセットアップする時は、これらのガイドラインに従ってください:
* デフォルトの "base" レイヤーとして、layer 0 をセットアップします。これは通常の入力レイヤーであり、任意のレイアウト (qwerty、dvorak、colemak など)にすることができます。通常はキーボードのキーのほとんどまたは全てが定義されているため、これを最下位のレイヤーとして設定することが重要です。そうすることで、もしそれが他のレイヤーの上 (つまりレイヤー番号が大きい)にある場合の影響を防ぎます。
* layer 0 をルートとして、レイヤーを "ツリー" レイアウトに配置します。他の複数のレイヤーから同じレイヤーに行こうとしないでください。
* 各レイヤーのキーマップでは、より高い番号のレイヤーのみを参照します。レイヤーは最大の番号(最上位)のアクティブレイヤーから処理されるため、下位レイヤーの状態を変更するのは難しくエラーが発生しやすくなります。
## 中級ユーザ
複数の基本レイヤーが必要な場合があります。例えば、QWERTY と Dvorak を切り替える場合、国ごとに異なるレイアウトを切り替える場合、あるいは異なるビデオゲームごとにレイアウトを切り替える場合などです。基本レイヤーは常に最小の番号のレイヤーである必要があります。複数の基本レイヤーがある場合、常にそれらを相互排他的に扱う必要があります。1つの基本レイヤーがオンの場合、他をオフにします。
## 上級ユーザ
レイヤーがどのように動作し、何ができるかを理解したら、より創造的になります。初心者のセクションで列挙されている規則は、幾つかの巧妙な詳細を回避するのに役立ちますが、特に超コンパクトなキーボードのユーザにとって制約になる場合があります。レイヤーの仕組みを理解することで、レイヤーをより高度な方法で使うことができます。
レイヤーは番号順に上に積み重なっています。キーの押下の動作を決定する時に、QMK は上から順にレイヤーを走査し、`KC_TRNS` に設定されていない最初のアクティブなレイヤーに到達すると停止します。結果として、現在のレイヤーよりも数値的に低いレイヤーをアクティブにし、現在のレイヤー(あるいはアクティブでターゲットレイヤーよりも高い別のレイヤー)に `KC_TRNS` 以外のものがある場合、それが送信されるキーであり、アクティブ化したばかりのレイヤー上のキーではありません。これが、ほとんどの人の "なぜレイヤーが切り替わらないのか" 問題の原因です。
場合によっては、マクロ内あるいはタップダンスルーチンの一部としてレイヤーを切り替えほうが良いかもしれません。`layer_on` はレイヤーをアクティブにし、`layer_off` はそれを非アクティブにします。もっと多くのレイヤーに関する関数は、[action_layer.h](https://github.com/qmk/qmk_firmware/blob/master/tmk_core/common/action_layer.h) で見つけることができます。
# 修飾キー :id=modifier-keys
以下のようにキーコードとモディファイアを組み合わせることができます。押すと、モディファイアのキーダウンイベントが送信され、次に `kc` のキーダウンイベントが送信されます。放すと、`kc` のキーアップイベントが送信され、次にモディファイアのキーアップイベントが送信されます。
| キー | エイリアス | 説明 |
@ -66,12 +23,16 @@ QMK を使い始めたばかりの場合は、全てを単純にしたいでし
| `MEH(kc)` | | 左 Control、左 Shift、左 Alt を押しながら `kc` を押します。 |
| `HYPR(kc)` | | 左 Control、左 Shift、左 Alt、左 GUI を押しながら `kc` を押します。 |
また、それらを繋げることができます。例えば、`LCTL(LALT(KC_DEL))` は1回のキー押下で Control+Alt+Delete を送信するキーを作成します。
また、それらを繋げることができます。例えば、`LCTL(LALT(KC_DEL))` または `C(A(KC_DEL))` は1回のキー押下で Control+Alt+Delete を送信するキーを作成します。
# 過去の内容
# 過去の内容 :id=legacy-content
このページには多くの機能が含まれていました。このページを構成していた多くのセクションをそれぞれのページに移動しました。これより下は全て単なるリダイレクトであるため、web上で古いリンクをたどっている人は探しているものを見つけることができます。
## レイヤー :id=switching-and-toggling-layers
* [レイヤー](ja/feature_layers.md)
## モッドタップ :id=mod-tap
* [モッドタップ](ja/mod_tap.md)

4
docs/ja/feature_audio.md
View File

@ -1,8 +1,8 @@
# オーディオ
<!---
original document: 5d5ff80:docs/feature_audio.md
git diff 5d5ff80 HEAD -- docs/feature_audio.md | cat
original document: 0.9.0:docs/feature_audio.md
git diff 0.9.0 HEAD -- docs/feature_audio.md | cat
-->
キーボードは音を出すことができます！Planck、Preonic あるいは特定の PWM 対応ピンにアクセスできる AVR キーボードがある場合は、単純なスピーカーを接続してビープ音を鳴らすことができます。これらのビープ音を使ってレイヤーの変化、モディファイア、特殊キーを示したり、あるいは単にイカした8ビットの曲を鳴らすことができます。

4
docs/ja/feature_auto_shift.md
View File

@ -1,8 +1,8 @@
# 自動シフト: なぜシフトキーが必要ですか？
<!---
original document: 5d5ff80:docs/feature_auto_shift.md
git diff 5d5ff80 HEAD -- docs/feature_auto_shift.md | cat
original document: 0.9.0:docs/feature_auto_shift.md
git diff 0.9.0 HEAD -- docs/feature_auto_shift.md | cat
-->
キーをタップすると、その文字を取得します。キーをタップするが、*わずかに*長く押し続けると、シフト状態になります。ほら！シフトキーは必要ありません！

58
docs/ja/feature_backlight.md
View File

@ -1,8 +1,8 @@
# バックライト
<!---
original document: 5d5ff80:docs/feature_backlight.md
git diff 5d5ff80 HEAD -- docs/feature_backlight.md | cat
original document: 0.9.10:docs/feature_backlight.md
git diff 0.9.10 HEAD -- docs/feature_backlight.md | cat
-->
多くのキーボードは、キースイッチを貫通して配置されたり、キースイッチの下に配置された個々の LED によって、バックライトキーをサポートします。この機能は通常スイッチごとに単一の色しか使用できないため、[RGB アンダーグロー](ja/feature_rgblight.md)および [RGB マトリックス](ja/feature_rgb_matrix.md)機能のどちらとも異なりますが、キーボードに複数の異なる単一色の LED を取り付けることは当然可能です。
@ -94,29 +94,29 @@ BACKLIGHT_DRIVER = pwm
ハードウェア PWM は以下の表に従ってサポートされます:
| バックライトピン | AT90USB64/128 | ATmega16/32U4 | ATmega16/32U2 | ATmega32A | ATmega328P |
| バックライトピン | AT90USB64/128 | ATmega16/32U4 | ATmega16/32U2 | ATmega32A | ATmega328/P |
|-------------|-------------|-------------|-------------|---------|----------|
| `B1` | | | | | Timer 1 |
| `B2` | | | | | Timer 1 |
| `B5` | Timer 1 | Timer 1 | | | |
| `B6` | Timer 1 | Timer 1 | | | |
| `B7` | Timer 1 | Timer 1 | Timer 1 | | |
| `C4` | Timer 3 | | | | |
| `C5` | Timer 3 | | Timer 1 | | |
| `C6` | Timer 3 | Timer 3 | Timer 1 | | |
| `D4` | | | | Timer 1 | |
| `D5` | | | | Timer 1 | |
| `B1` | | | | | Timer 1 |
| `B2` | | | | | Timer 1 |
| `B5` | Timer 1 | Timer 1 | | | |
| `B6` | Timer 1 | Timer 1 | | | |
| `B7` | Timer 1 | Timer 1 | Timer 1 | | |
| `C4` | Timer 3 | | | | |
| `C5` | Timer 3 | | Timer 1 | | |
| `C6` | Timer 3 | Timer 3 | Timer 1 | | |
| `D4` | | | | Timer 1 | |
| `D5` | | | | Timer 1 | |
他の全てのピンはソフトウェア PWM を使います。[オーディオ](ja/feature_audio.md)機能が無効あるいは1つのタイマだけを使っている場合は、ハードウェアタイマによってバックライト PWM を引き起こすことができます:
| オーディオピン | オーディオタイマ | ソフトウェア PWM タイマ |
|---------|-----------|------------------|
| `C4` | Timer 3 | Timer 1 |
| `C5` | Timer 3 | Timer 1 |
| `C6` | Timer 3 | Timer 1 |
| `B5` | Timer 1 | Timer 3 |
| `B6` | Timer 1 | Timer 3 |
| `B7` | Timer 1 | Timer 3 |
| `C4` | Timer 3 | Timer 1 |
| `C5` | Timer 3 | Timer 1 |
| `C6` | Timer 3 | Timer 1 |
| `B5` | Timer 1 | Timer 3 |
| `B6` | Timer 1 | Timer 3 |
| `B7` | Timer 1 | Timer 3 |
両方のタイマーがオーディオのために使われている場合、バックライト PWM はハードウェアタイマを使いませんが、代わりにマトリックススキャンの間に引き起こされます。この場合、PWM の計算は十分なタイミングの精度で呼ばれないかもしれないため、バックライトの明滅はサポートされず、バックライトもちらつくかもしれません。
@ -126,13 +126,13 @@ BACKLIGHT_DRIVER = pwm
| 定義 | デフォルト | 説明 |
|---------------------|-------------|--------------------------------------------------------------------------------------------------------------|
| `BACKLIGHT_PIN` | `B7` | LED を制御するピン。自身のキーボードを設計している場合を除き、これを変更する必要はないはずです |
| `BACKLIGHT_PINS` | *定義なし* | 実験的: 詳細は以下を見てください |
| `BACKLIGHT_LEVELS` | `3` | 輝度のレベルの数 (オフを除いて最大 31) |
| `BACKLIGHT_PIN` | `B7` | LED を制御するピン。自身のキーボードを設計している場合を除き、これを変更する必要はないはずです |
| `BACKLIGHT_PINS` | *定義なし* | 実験的: 詳細は以下を見てください |
| `BACKLIGHT_LEVELS` | `3` | 輝度のレベルの数 (オフを除いて最大 31) |
| `BACKLIGHT_CAPS_LOCK` | *定義なし* | バックライトを使って Caps Lock のインジケータを有効にする (専用 LED の無いキーボードのため) |
| `BACKLIGHT_BREATHING` | *定義なし* | サポートされる場合は、バックライトの明滅動作を有効にする |
| `BREATHING_PERIOD` | `6` | 各バックライトの "明滅" の長さ（秒） |
| `BACKLIGHT_ON_STATE` | `1` | バックライトが "オン" の時のバックライトピンの状態 - high の場合は `1`、low の場合は `0` |
| `BREATHING_PERIOD` | `6` | 各バックライトの "明滅" の長さ（秒） |
| `BACKLIGHT_ON_STATE` | `1` | バックライトが "オン" の時のバックライトピンの状態 - high の場合は `1`、low の場合は `0` |
### バックライトオン状態
@ -192,10 +192,10 @@ BACKLIGHT_DRIVER = pwm
| 定義 | デフォルト | 説明 |
|------------------------|-------------|-------------------------------------------------------------------------------------------------------------|
| `BACKLIGHT_PIN` | `B7` | LED を制御するピン。自身のキーボードを設計している場合を除き、これを変更する必要はないはずです |
| `BACKLIGHT_PWM_DRIVER` | `PWMD4` | 使用する PWM ドライバ。ピンから PWM タイマへのマッピングについては、ST データシートを見てください。自身のキーボードを設計している場合を除き、これを変更する必要はないはずです |
| `BACKLIGHT_PWM_CHANNEL` | `3` | 使用する PWM チャンネル。ピンから PWM チャンネルへのマッピングについては、ST データシートを見てください。自身のキーボードを設計している場合を除き、これを変更する必要はないはずです |
| `BACKLIGHT_PAL_MODE` | `2` | 使用するピンの代替機能。ピンの AF マッピングについては ST データシートを見てください。自身のキーボードを設計している場合を除き、これを変更する必要はないはずです |
| `BACKLIGHT_PIN` | `B7` | LED を制御するピン。自身のキーボードを設計している場合を除き、これを変更する必要はないはずです |
| `BACKLIGHT_PWM_DRIVER` | `PWMD4` | 使用する PWM ドライバ。ピンから PWM タイマへのマッピングについては、ST データシートを見てください。自身のキーボードを設計している場合を除き、これを変更する必要はないはずです |
| `BACKLIGHT_PWM_CHANNEL` | `3` | 使用する PWM チャンネル。ピンから PWM チャンネルへのマッピングについては、ST データシートを見てください。自身のキーボードを設計している場合を除き、これを変更する必要はないはずです |
| `BACKLIGHT_PAL_MODE` | `2` | 使用するピンの代替機能。ピンの AF マッピングについては ST データシートを見てください。自身のキーボードを設計している場合を除き、これを変更する必要はないはずです |
## Software PWM Driver :id=software-pwm-driver
@ -210,7 +210,7 @@ BACKLIGHT_DRIVER = software
| 定義 | デフォルト | 説明 |
|-----------------|-------------|-------------------------------------------------------------------------------------------------------------|
| `BACKLIGHT_PIN` | `B7` | LED を制御するピン。自身のキーボードを設計している場合を除き、これを変更する必要はないはずです |
| `BACKLIGHT_PIN` | `B7` | LED を制御するピン。自身のキーボードを設計している場合を除き、これを変更する必要はないはずです |
| `BACKLIGHT_PINS` | *定義なし* | 実験的: 詳細は以下を見てください |
### 複数のバックライトピン

4
docs/ja/feature_bluetooth.md
View File

@ -1,8 +1,8 @@
# Bluetooth
<!---
original document: 5d5ff80:docs/feature_bluetooth.md
git diff 5d5ff80 HEAD -- docs/feature_bluetooth.md | cat
original document: 0.9.0:docs/feature_bluetooth.md
git diff 0.9.0 HEAD -- docs/feature_bluetooth.md | cat
-->
## Bluetooth の既知のサポートハードウェア

15
docs/ja/feature_bootmagic.md
View File

@ -1,8 +1,8 @@
# ブートマジック
<!---
original document: 5d5ff80:docs/feature_bootmagic.md
git diff 5d5ff80 HEAD -- docs/feature_bootmagic.md | cat
original document: 0.9.0:docs/feature_bootmagic.md
git diff 0.9.0 HEAD -- docs/feature_bootmagic.md | cat
-->
再書き込みせずにキーボードの挙動を変更することができる、3つの独立した関連する機能があります。それぞれは似たような機能を持ちますが、キーボードがどのように設定されているかによって異なる方法でアクセスされます。
@ -149,6 +149,17 @@ BOOTMAGIC_ENABLE = lite
!> ブートマジックライトを使用すると、EEPROM を**常にリセットします**。つまり保存された全ての設定は失われます。
## 分割キーボード
`SPLIT_HAND_PIN` のようなオプションで、左右の設定があらかじめ決められている場合は、キーボードの左右で別のキーを設定する必要があるかもしれません。これを行うには、`config.h` ファイルに以下のエントリを追加します。
```c
#define BOOTMAGIC_LITE_ROW_RIGHT 4
#define BOOTMAGIC_LITE_COLUMN_RIGHT 1
```
デフォルトでは、これらの値は設定されていません。
## 高度なブートマジックライト
`bootmagic_lite` 関数は必要に応じてコード内で置き換えることができるように、弱く定義されています。これの良い例は Zeal60 キーボードで、追加の処理が必要です。

99
docs/ja/feature_layers.md Normal file
View File

@ -0,0 +1,99 @@
# レイヤー :id=layers
<!---
original document: 0.9.20:docs/feature_layers.md
git diff 0.9.20 HEAD -- docs/feature_layers.md | cat
-->
QMK ファームウェアの最も強力で良く使われている機能の一つは、レイヤーを使う機能です。ほとんどの人にとって、これはラップトップやタブレットキーボードにあるのと同じように、様々なキーを可能にするファンクションキーに相当します。
レイヤースタックがどのように動作するかの詳細な説明については、[キーマップの概要](ja/keymap.md#keymap-and-layers)を調べてください。
## レイヤーの切り替えとトグル :id=switching-and-toggling-layers
以下の関数により、様々な方法でレイヤーをアクティブにすることができます。レイヤーは通常、独立したレイアウトでは無いことに注意してください -- 複数のレイヤーを一度にアクティブにすることができ、レイヤーが `KC_TRNS` を使ってキーの押下を下のレイヤーへと透過させることが一般的です。MO()、LM()、TT() あるいは LT() を使って一時的なレイヤーの切り替えを使う場合、上のレイヤーのキーを透過にするようにしてください。さもないと意図したように動作しないかもしれません。
* `DF(layer)` - デフォルトレイヤーを切り替えます。デフォルトレイヤーは、他のレイヤーがその上に積み重なっている、常にアクティブな基本レイヤーです。デフォルトレイヤーの詳細については以下を見てください。これは QWERTY から Dvorak レイアウトに切り替えるために使うことができます。(これは一時的な切り替えであり、キーボードの電源が切れるまでしか持続しないことに注意してください。デフォルトレイヤーを永続的に変更するには、[process_record_user](ja/custom_quantum_functions.md#programming-the-behavior-of-any-keycode) 内で `set_single_persistent_default_layer` 関数を呼び出すなど、より深いカスタマイズが必要です。)
* `MO(layer)` - 一時的に*レイヤー*をアクティブにします。キーを放すとすぐに、レイヤーは非アクティブになります。
* `LM(layer, mod)` - (`MO` のように)一時的に*レイヤー*をアクティブにしますが、モディファイア *mod* がアクティブな状態です。layer 0-15 と、左モディファイアのみをサポートします: `MOD_LCTL`、`MOD_LSFT`、`MOD_LALT`、`MOD_LGUI` (`KC_` 定数の代わりに `MOD_` 定数を使うことに注意してください)。これらのモディファイアは、例えば `LM(_RAISE, MOD_LCTL | MOD_LALT)` のように、ビット単位の OR を使って組み合わせることができます。
* `LT(layer, kc)` - ホールドされた時に*レイヤー*を一時的にアクティブにし、タップされた時に *kc* を送信します。layer 0-15 のみをサポートします。
* `OSL(layer)` - 次のキーが押されるまで、一時的に*レイヤー*をアクティブにします。詳細と追加機能については、[ワンショットキー](ja/one_shot_keys.md)を見てください。
* `TG(layer)` - *レイヤー*を切り替えます。非アクティブな場合はアクティブにし、逆も同様です。
* `TO(layer)` - *レイヤー*をアクティブにし、他の全てのレイヤー(デフォルトレイヤーを除く)を非アクティブにします。この関数は特別です。1つのレイヤーをアクティブなレイヤースタックに追加/削除する代わりに、現在のアクティブなレイヤーを完全に置き換え、唯一上位のレイヤーを下位のレイヤーで置き換えることができるからです。これはキーダウンで(キーが押されるとすぐに)アクティブになります。
* `TT(layer)` - レイヤーのタップ切り替え。キーを押したままにすると*レイヤー*がアクティブにされ、放すと非アクティブになります (`MO` 風)。繰り返しタップすると、レイヤーはオンあるいはオフを切り替えます (`TG` 風)。デフォルトでは5回のタップが必要ですが、`TAPPING_TOGGLE` を定義することで変更することができます -- 例えば、2回のタップだけで切り替えるには、`#define TAPPING_TOGGLE 2` を定義します。
### 注意事項 :id=caveats
現在のところ、`LT()` と `MT()` は[基本的なキーコードセット](ja/keycodes_basic.md)に制限されています。つまり、`LCTL()`、`KC_TILD` あるいは `0xFF` より大きなキーコードを使うことができません。特に、`LT` と `MT` のような二重の機能キーは16ビットキーコードを使います。4ビットは機能の識別のために使われ、次の12ビットはパラメータに分かれます。レイヤータップはレイヤーに4ビットを使います(実はレイヤータップがレイヤー 0-15 に制限されている理由です)。モッドタップも同じですが、識別子に4ビット、モッドのために4ビットが使われ、全体でキーコードに8ビットを使います。このため、使用されるキーコードは `0xFF` (0-255) に制限され、基本的なキーコードのみです。
これを拡張してもせいぜい複雑になるだけでしょう。32ビットキーコードに移行すると、これの多くが解決されますが、キーマップマトリックスが使用する領域が2倍になります。また、問題が起きる可能性もあります。タップしたキーコードにモディファイアを適用する必要がある場合は、[タップダンス](ja/feature_tap_dance.md#example-5-using-tap-dance-for-advanced-mod-tap-and-layer-tap-keys)を使うことができます。
さらに、モッドタップあるいはレイヤータップで少なくとも1つの右手用のモディファイアが指定された場合、指定された全てのモディファイアが右手用になるため、2つをうまく組み合わせて一致させることはできません。
## レイヤーとの連携 :id=working-with-layers
レイヤーを切り替える時は注意してください。(キーボードを取り外さずに)そのレイヤーを非アクティブにすることができずレイヤーから移動できなくなる可能性があります。最も一般的な問題を避けるためのガイドラインを作成しました。
### 初心者 :id=beginners
QMK を使い始めたばかりの場合は、全てを単純にしたいでしょう。レイヤーをセットアップする時は、これらのガイドラインに従ってください:
* デフォルトの "base" レイヤーとして、layer 0 をセットアップします。これは通常の入力レイヤーであり、任意のレイアウト (qwerty、dvorak、colemak など)にすることができます。通常はキーボードのキーのほとんどまたは全てが定義されているため、これを最下位のレイヤーとして設定することが重要です。そうすることで、もしそれが他のレイヤーの上 (つまりレイヤー番号が大きい)にある場合の影響を防ぎます。
* layer 0 をルートとして、レイヤーを "ツリー" レイアウトに配置します。他の複数のレイヤーから同じレイヤーに行こうとしないでください。
* 各レイヤーのキーマップでは、より高い番号のレイヤーのみを参照します。レイヤーは最大の番号(最上位)のアクティブレイヤーから処理されるため、下位レイヤーの状態を変更するのは難しくエラーが発生しやすくなります。
### 中級ユーザ :id=intermediate-users
複数の基本レイヤーが必要な場合があります。例えば、QWERTY と Dvorak を切り替える場合、国ごとに異なるレイアウトを切り替える場合、あるいは異なるビデオゲームごとにレイアウトを切り替える場合などです。基本レイヤーは常に最小の番号のレイヤーである必要があります。複数の基本レイヤーがある場合、常にそれらを相互排他的に扱う必要があります。1つの基本レイヤーがオンの場合、他をオフにします。
### 上級ユーザ :id=advanced-users
レイヤーがどのように動作し、何ができるかを理解したら、より創造的になります。初心者のセクションで列挙されている規則は、幾つかの巧妙な詳細を回避するのに役立ちますが、特に超コンパクトなキーボードのユーザにとって制約になる場合があります。レイヤーの仕組みを理解することで、レイヤーをより高度な方法で使うことができます。
レイヤーは番号順に上に積み重なっています。キーの押下の動作を決定する時に、QMK は上から順にレイヤーを走査し、`KC_TRNS` に設定されていない最初のアクティブなレイヤーに到達すると停止します。結果として、現在のレイヤーよりも数値的に低いレイヤーをアクティブにし、現在のレイヤー(あるいはアクティブでターゲットレイヤーよりも高い別のレイヤー)に `KC_TRNS` 以外のものがある場合、それが送信されるキーであり、アクティブ化したばかりのレイヤー上のキーではありません。これが、ほとんどの人の "なぜレイヤーが切り替わらないのか" 問題の原因です。
場合によっては、マクロ内あるいはタップダンスルーチンの一部としてレイヤーを切り替えほうが良いかもしれません。`layer_on` はレイヤーをアクティブにし、`layer_off` はそれを非アクティブにします。もっと多くのレイヤーに関する関数は、[action_layer.h](https://github.com/qmk/qmk_firmware/blob/master/tmk_core/common/action_layer.h) で見つけることができます。
## 関数 :id=functions
レイヤーの使用あるいは操作に関係する多くの関数(と変数)があります。
| 関数 | 説明 |
|----------------------------------------------|---------------------------------------------------------------------------------------------------------|
| `layer_state_set(layer_mask)` | 直接レイヤーの状態を設定する (推奨。何をしているのか分かっていない場合は使わないでください)。 |
| `layer_clear()` | 全てのレイヤーを消去する (全てをオフにします)。 |
| `layer_move(layer)` | 指定されたレイヤーをオンにし、それ以外をオフにする。 |
| `layer_on(layer)` | 指定されたレイヤーをオンにし、それ以外を既存の状態のままにする。 |
| `layer_off(layer)` | 指定されたレイヤーをオフにし、それ以外を既存の状態のままにする。 |
| `layer_invert(layer)` | 指定されたレイヤーの状態を反転/トグルする。 |
| `layer_or(layer_mask)` | 指定されたレイヤーと既存のレイヤー状態の間で一致するビットに基づいてレイヤーをオンにする。 |
| `layer_and(layer_mask)` | 指定されたレイヤーと既存のレイヤー状態の間で有効なビットに基づいてレイヤーをオンにする。 |
| `layer_xor(layer_mask)` | 指定されたレイヤーと既存のレイヤー状態の間で一致しないビットに基づいてレイヤーをオンにする。 |
| `layer_debug(layer_mask)` | デバッガのコンソールに現在のビットマスクと最も高いレイヤーを出力する。 |
| `default_layer_set(layer_mask)` | 直接デフォルトレイヤーの状態を設定する (推奨。何をしているのか分かっていない場合は使わないでください)。 |
| `default_layer_or(layer_mask)` | 指定されたレイヤーと既存のデフォルトレイヤー状態の間で一致するビットに基づいてレイヤーをオンにする。 |
| `default_layer_and(layer_mask)` | 指定されたレイヤーと既存のデフォルトレイヤー状態の間で一致する有効なビットに基づいてレイヤーをオンにする。 |
| `default_layer_xor(layer_mask)` | 指定されたレイヤーと既存のデフォルトレイヤー状態の間で一致しないビットに基づいてレイヤーをオンにする。 |
| `default_layer_debug(layer_mask)` | デバッガのコンソールに現在のビットマスクと最も高いアクティブなレイヤーを出力する。 |
| [`set_single_persistent_default_layer(layer)`](ja/ref_functions.md#setting-the-persistent-default-layer) | デフォルトレイヤーを設定し、それを永続化メモリ (EEPROM) に書き込む。 |
| [`update_tri_layer(x, y, z)`](ja/ref_functions.md#update_tri_layerx-y-z) | レイヤー `x` と `y` の両方がオンであるかを調べ、それに基づいて `z` を設定する(両方がオンの場合オン、そうでなければオフ)。 |
| [`update_tri_layer_state(state, x, y, z)`](ja/ref_functions.md#update_tri_layer_statestate-x-y-z) | `update_tri_layer(x, y, z)` と同じことをするが、`layer_state_set_*` 関数から呼ばれる。 |
呼び出すことができる関数に加えて、レイヤーが変更されるたびに呼び出されるコールバック関数が幾つかあります。これはレイヤー状態を関数に渡し、読み取りや変更することができます。
| コールバック | 説明 |
|-----------------------------------------------------|----------------------------------------------------------------------------------------|
| `layer_state_set_kb(layer_state_t state)` | キーボードレベルのレイヤー関数のためのコールバック。 |
| `layer_state_set_user(layer_state_t state)` | ユーザレベルのレイヤー関数のためのコールバック。 |
| `default_layer_state_set_kb(layer_state_t state)` | キーボードレベルのデフォルトレイヤー関数のためのコールバック。キーボードの初期化時に呼ばれます。 |
| `default_layer_state_set_user(layer_state_t state)` | ユーザレベルのデフォルトレイヤー関数のためのコールバック。キーボードの初期化時に呼ばれます。 |
?> これらのコールバックを使うための追加の情報については、[レイヤー変換コード](ja/custom_quantum_functions.md#layer-change-code)のドキュメントを調べてください。
| チェック関数 | 説明 |
|-------------------------------------------|------------------------------------------------------------------------------|
| `layer_state_cmp(cmp_layer_state, layer)` | これは `cmp_layer_state` を調べて、指定された `layer` が有効かどうかを確認します。これは、レイヤーコールバックで使うためのものです。 |
| `layer_state_is(layer)` | これはレイヤーの状態を調べて、指定された `layer` が有効かどうかを確認します。(グローバルレイヤー状態については、`layer_state_cmp` を呼びます)。 |
!> `IS_LAYER_ON(layer)` もありますが、`layer_state_cmp` 関数には、レイヤー0で正しい値を返すようにするために追加の処理があります。さもないと、レイヤー0がオンになっているかどうかを確認する時に誤った値が返されることがあります。

114
docs/ja/feature_layouts.md Normal file
View File

@ -0,0 +1,114 @@
# レイアウト: 複数のキーボードで1つのキーマップを使用
<!---
original document: 0.8.134:docs/feature_layouts.md
git diff 0.8.134 HEAD -- docs/feature_layouts.md | cat
-->
`layouts/` フォルダは、様々なキーボードに適用できる色々な物理キーレイアウトを含みます。
```
layouts/
+ default/
| + 60_ansi/
| | + readme.md
| | + layout.json
| | + a_good_keymap/
| | | + keymap.c
| | | + readme.md
| | | + config.h
| | | + rules.mk
| | + <keymap folder>/
| | + ...
| + <layout folder>/
+ community/
| + <layout folder>/
| + ...
```
`layouts/default/` と `layouts/community/` は、レイアウト「repositories」の2つの例です。現在のところ、`default` にはユーザの参考用に、レイアウトに関する全ての情報および、`default_<layout>` という名前の1つのデフォルトのキーマップが含まれています。`community` には全ての共有キーマップが含まれており、それらはユーザが `layouts/` にクローンするための別のリポジトリに分割することを最終的な目的としていますQMK は `layouts/` 内のすべてのフォルダを検索するため、ここに複数のリポジトリを持つことができます。
各レイアウトフォルダは、レイアウトの物理的な側面に基づいて、可能な限り一般的な名称で(`[a-z0-9_]`)という名前が付けられ、キーボードで定義されるレイアウトと一緒に `readme.md` を含みます。
```md
# 60_ansi
LAYOUT_60_ansi
```
新しい名前は既存のレイアウトで設定された標準に準拠しようと努力する必要があり、必要に応じて PR/Issue で議論することができます。
## レイアウトのサポート
キーボードがレイアウトをサポートするために、変数は `<keyboard>.h` で定義し、引数/キー (できれば物理レイアウト)の数に一致している必要があります。
#define LAYOUT_60_ansi KEYMAP_ANSI
レイアウトの名前は次の正規表現に一致しなければなりません: `[a-z0-9_]+`
フォルダ名はキーボードの `rules.mk` に追加する必要があります:
LAYOUTS = 60_ansi
`LAYOUTS` は任意のキーボードフォルダレべルの `rules.mk` に設定することができます:
LAYOUTS = 60_iso
ただし、`LAYOUT_<layout>` 変数は `<folder>.h` でも定義する必要があります。
## キーマップのビルド
以下の形式でコマンドを使ってキーボードキーマップを作成できるはずです:
make <keyboard>:<layout>
### レイアウトの競合
キーボードが複数のレイアウトオプションをサポートし、
LAYOUTS = ortho_4x4 ortho_4x12
なおかつ両方のオプションについてレイアウトが存在する場合、
```
layouts/
+ community/
| + ortho_4x4/
| | + <layout>/
| | | + ...
| + ortho_4x12/
| | + <layout>/
| | | + ...
| + ...
```
FORCE_LAYOUT 引数はどのレイアウトをビルドするかを指定するために使うことができます
make <keyboard>:<layout> FORCE_LAYOUT=ortho_4x4
make <keyboard>:<layout> FORCE_LAYOUT=ortho_4x12
## キーボードに依存しないレイアウトを作成するためのヒント
### インクルード
`#include "planck.h"` を使う代わりに、以下の行を使ってコンパイルされる `<keyboard>.h` (`<folder>.h` はここでインクルードすべきではありません)ファイルをインクルードすることができます:
#include QMK_KEYBOARD_H
キーボード固有のコードを保持したい場合は、これらの変数を使って `#ifdef` 文でエスケープすることができます:
* `KEYBOARD_<folder1>_<folder2>`
例えば:
```c
#ifdef KEYBOARD_planck
#ifdef KEYBOARD_planck_rev4
planck_rev4_function();
#endif
#endif
```
名前は小文字でキーボード/リビジョンのフォルダ/ファイル名と正確に一致することに注意してください。
### キーマップ
同じレイアウトで分割および非分割キーボードをサポートするためには、キーマップでキーボード非依存の `LAYOUT_<layout name>` マクロを使う必要があります。例えば、Let's Split および Planck が同じレイアウトを共有するには、`LAYOUT_planck_grid` や C 配列の場合の単なる `{}` の代わりに、`LAYOUT_ortho_4x12` を使う必要があります。

151
docs/ja/feature_leader_key.md Normal file
View File

@ -0,0 +1,151 @@
# リーダーキー: 新しい種類のモディファイア
<!---
original document: 0.8.134:docs/feature_leader_key.md
git diff 0.8.134 HEAD -- docs/feature_leader_key.md | cat
-->
もしあなたが Vim を使ったことがある場合、リーダーキーは何であるかを知っています。そうでなければ、素晴らしい概念を発見しようとしています。:) 例えば、Alt+Shift+W を押す(3つのキーを同時に押す)代わりに、キーの_シーケンス_を押すことができたらどうでしょう？つまり、特別なモディファイア (リーダーキー)を押して、続けて W と C を押すと (単純にキーを高速に繋げます)、何かが起こります。
それが `KC_LEAD` の機能です。以下は例です:
1. リーダーキーとして使いたいキーボードのキーを選択します。それにキーコード `KC_LEAD` を割り当てます。このキーはこのためだけの専用です -- 単一アクションのキーで、他の用途には使うことができません。
2. `config.h` に `#define LEADER_TIMEOUT 300` という行を追加します。これによって `KC_LEAD` キーのタイムアウトを設定します。具体的には、`KC_LEAD` キーを押してからリーダーキーのシーケンスを完了するまで一定の時間しかありません。ここでの `300` はそれを300msに設定します。この値を増やして、シーケンスを入力する時間を増やすことができます。ただし、この時間中に押されたキーは全て途中で遮られ、送信されません。そのためこの値は小さくしておいたほうが良いかもしれません。
* デフォルトでは、このタイムアウトは、`KC_LEAD` を押してからシーケンス全体が完了するまでに掛かる時間です。これは一部の人にとっては非常に短いかもしれません。そのため、このタイムアウトを増やしたほうが良い場合もあります。必要に応じて、`LEADER_PER_KEY_TIMING` オプションを有効にしたほうが良い場合もあります。これは各キーがタップされる度にタイムアウトまでの時間をリセットする機能です。これにより、タイムアウト時間を短くしつつも、比較的長いシーケンスを使うことができます。このオプションを有効にするには、`config.h` に `#define LEADER_PER_KEY_TIMING` を追加します。
3. `matrix_scan_user` 関数の中で、以下のようなものを追加します:
```c
LEADER_EXTERNS();
void matrix_scan_user(void) {
LEADER_DICTIONARY() {
leading = false;
leader_end();
SEQ_ONE_KEY(KC_F) {
// マクロ内でできること
SEND_STRING("QMK is awesome.");
}
SEQ_TWO_KEYS(KC_D, KC_D) {
SEND_STRING(SS_LCTL("a") SS_LCTL("c"));
}
SEQ_THREE_KEYS(KC_D, KC_D, KC_S) {
SEND_STRING("https://start.duckduckgo.com\n");
}
SEQ_TWO_KEYS(KC_A, KC_S) {
register_code(KC_LGUI);
register_code(KC_S);
unregister_code(KC_S);
unregister_code(KC_LGUI);
}
}
}
```
ご覧のとおり、幾つかの関数があります。`SEQ_ONE_KEY` を単一キーシーケンス (リーダーの後に1つのキーのみ)に使い、より長いシーケンスについては `SEQ_TWO_KEYS`、`SEQ_THREE_KEYS` から `SEQ_FIVE_KEYS` を使うことができます。
これらはそれぞれ1つ以上のキーコードを引数として受け付けます。これは重要な点です: **キーボードの任意のレイヤー**のキーコードを使うことができます。当たり前ですが、リーダーマクロが発動するにはそのレイヤーがアクティブである必要があります
## `rules.mk` にリーダーキーサポートを追加
リーダーキーのサポートを追加するには、単純にキーマップの `rules.mk` に1行を追加します:
```make
LEADER_ENABLE = yes
```
## リーダーキーのキーごとのタイミング
長いリーダーキー文字列のためや 200wpm のタイピングスキルが無い場合に、非常に長いタイムアウト時間に頼るのではなく、キーを押すごとに入力を完了するまでの時間を増やす機能を使用することができます。これは、リーダーキーを使ってタップダンスを再現する場合に非常に役立ちます (C, C, C のような同じキーを複数回タップする場合)。
これを有効にするには、以下を `config.h` に配置します:
```c
#define LEADER_PER_KEY_TIMING
```
この後、`LEADER_TIMEOUT` を 300ms 未満に下げることをお勧めします。
```c
#define LEADER_TIMEOUT 250
```
これで、リーダーキーのタイムアウト時間を 1000ms に設定することなく以下のようなことが可能になると思われます。
```c
SEQ_THREE_KEYS(KC_C, KC_C, KC_C) {
SEND_STRING("Per key timing is great!!!");
}
```
## 厳密なキー処理
デフォルトでは、リーダーキー機能は、リーダーシーケンスの確認時に [`モッドタップ`](ja/mod_tap.md) および [`レイヤータップ`](ja/feature_layers.md#switching-and-toggling-layers) 機能からのキーコードをフィルターします。つまり、`LT(3, KC_A)` を使っている場合、`LT(3, KC_A)` ではなくシーケンスの `KC_A` として取り出され、新しいユーザにとってより期待される動作を提供します。
ほとんどの場合これで問題ありませんが、シーケンスでキーコード全体(例えば、上の例での `LT(3, KC_A)`) を指定したい場合は、`config.h` ファイルに `#define LEADER_KEY_STRICT_KEY_PROCESSING` を追加することこのような機能を有効にすることができます。これでフィルタリングが無効になり、キーコード全体を指定する必要があります。
## カスタマイズ
リーダーキー機能には、リーダーキー機能の動作にいくらかのカスタマイズを追加する方法があります。リーダーキー機能のプロセスの特定の部分で呼び出すことができる2つの関数、`leader_start()` と `leader_end()` です。
`KC_LEAD` キーがタップされた時に `leader_start()` 関数が呼ばれ、リーダーシーケンスが完了するか、リーダータイムアウトの時間に達した時に `leader_end()` 関数が呼ばれます。
リーダーシーケンスにフィードバック(ビープまたは音楽を再生するなど)を追加するために、これらの関数をコード (通常 は`keymap.c`)に追加することができます。
```c
void leader_start(void) {
// シーケンスの開始
}
void leader_end(void) {
// シーケンスの終了 (成功しない/失敗を検知)
}
```
### 例
この例では、リーダーシーケンスを開始するために `KC_LEAD` を押すとマリオの "One Up" 音が再生され、正常に完了した場合は "All Star" が再生され、失敗した場合は "Rick Roll" を再生されます。
```c
bool did_leader_succeed;
#ifdef AUDIO_ENABLE
float leader_start[][2] = SONG(ONE_UP_SOUND );
float leader_succeed[][2] = SONG(ALL_STAR);
float leader_fail[][2] = SONG(RICK_ROLL);
#endif
LEADER_EXTERNS();
void matrix_scan_user(void) {
LEADER_DICTIONARY() {
did_leader_succeed = leading = false;
SEQ_ONE_KEY(KC_E) {
// マクロ内でできること
SEND_STRING(SS_LCTL(SS_LSFT("t")));
did_leader_succeed = true;
} else
SEQ_TWO_KEYS(KC_E, KC_D) {
SEND_STRING(SS_LGUI("r") "cmd\n" SS_LCTL("c"));
did_leader_succeed = true;
}
leader_end();
}
}
void leader_start(void) {
#ifdef AUDIO_ENABLE
PLAY_SONG(leader_start);
#endif
}
void leader_end(void) {
if (did_leader_succeed) {
#ifdef AUDIO_ENABLE
PLAY_SONG(leader_succeed);
#endif
} else {
#ifdef AUDIO_ENABLE
PLAY_SONG(leader_fail);
#endif
}
}
```

95
docs/ja/feature_led_matrix.md Normal file
View File

@ -0,0 +1,95 @@
# LED マトリックスライト
<!---
original document: 0.8.141:docs/feature_led_matrix.md
git diff 0.8.141 HEAD -- docs/feature_led_matrix.md | cat
-->
この機能により、外部ドライバによって駆動される LED マトリックスを使うことができます。この機能は、バックライト制御と同じキーコードを使えるようにするため、バックライトシステムに接続します。
RGB LED を使いたい場合は、代わりに [RGB マトリックスサブシステム](ja/feature_rgb_matrix.md) を使うべきです。
## ドライバ設定
### IS31FL3731
I2C IS31FL3731 RGB コントローラを使ったアドレス指定可能な LED マトリックスライトのための基本的なサポートがあります:有効にするには、`rules.mk` に以下を追加します:
LED_MATRIX_ENABLE = IS31FL3731
1から4個の IS31FL3731 IC を使うことができます。キーボード上に存在しない IC の `LED_DRIVER_ADDR_<N>` 定義を指定しないでください。`config.h` に以下の項目を定義することができます:
| 変数 | 説明 | デフォルト |
|----------|-------------|---------|
| `ISSI_TIMEOUT` | (オプション) i2c メッセージを待つ時間 | 100 |
| `ISSI_PERSISTENCE` | (オプション) 失敗したメッセージをこの回数再試行する | 0 |
| `LED_DRIVER_COUNT` | (必須) LED ドライバ IC の数 | |
| `LED_DRIVER_LED_COUNT` | (必須) 全てのドライバの LED ライトの数 | |
| `LED_DRIVER_ADDR_1` | (必須) 最初の LED ドライバのアドレス | |
| `LED_DRIVER_ADDR_2` | (オプション) 2番目の LED ドライバのアドレス | |
| `LED_DRIVER_ADDR_3` | (オプション) 3番目の LED ドライバのアドレス | |
| `LED_DRIVER_ADDR_4` | (オプション) 4番目の LED ドライバのアドレス | |
2つのドライバを使う例です。
// これは7ビットのアドレスで、左シフトされます
// ビット0に0を設定すると書き込み、1を設定すると読み込みです (I2C プロトコルに従う)
// アドレスは配線によって変わります:
// 0b1110100 AD <-> GND
// 0b1110111 AD <-> VCC
// 0b1110101 AD <-> SCL
// 0b1110110 AD <-> SDA
#define LED_DRIVER_ADDR_1 0b1110100
#define LED_DRIVER_ADDR_2 0b1110110
#define LED_DRIVER_COUNT 2
#define LED_DRIVER_1_LED_COUNT 25
#define LED_DRIVER_2_LED_COUNT 24
#define LED_DRIVER_LED_COUNT LED_DRIVER_1_LED_TOTAL + LED_DRIVER_2_LED_TOTAL
現在、2つのドライバのみがサポートされますが、4つの組み合わせ全てをサポートすることは簡単です。
`<keyboard>.c` に全ての LED を列挙する配列を定義します:
const is31_led g_is31_leds[DRIVER_LED_TOTAL] = {
/* これらの位置については IS31 マニュアルを参照してください
* driver
* | LED address
* | | */
{0, C3_3},
....
}
ここで、`Cx_y` は[データシート](http://www.issi.com/WW/pdf/31FL3731.pdf)およびヘッダファイル `drivers/issi/is31fl3731-simple.h` で定義されるマトリックス内の LED の位置です。`driver` は `config.h` で定義したドライバのインデックス(`0`、`1`、`2`、`3`のいずれか)です。
## キーコード
現在のところ、全ての LED マトリックスのキーコードは[バックライトシステム](ja/feature_backlight.md)と共有されます。
## LED マトリックス効果
現在のところ、LED マトリックス効果は作成されていません。
## カスタムレイヤー効果
カスタムレイヤー効果は `<keyboard>.c` 内で以下を定義することで行うことができます:
void led_matrix_indicators_kb(void) {
led_matrix_set_index_value(index, value);
}
同様の関数がキーマップ内で `led_matrix_indicators_user` として動作します。
## サスペンド状態
サスペンド機能を使うには、以下を `<keyboard>.c` に追加します:
void suspend_power_down_kb(void)
{
led_matrix_set_suspend_state(true);
}
void suspend_wakeup_init_kb(void)
{
led_matrix_set_suspend_state(false);
}

399
docs/ja/feature_macros.md Normal file
View File

@ -0,0 +1,399 @@
# マクロ
<!---
original document: 0.8.169:docs/feature_macros.md
git diff 0.8.169 HEAD -- docs/feature_macros.md | cat
-->
マクロにより、1つのキーを押すだけで複数のキーストロークを送信することができます。QMK にはマクロを定義し使う方法が幾つかあります。これらはなんでもすることができます: よく使うフレーズの入力、コピーペースト、反復的なゲームの動き、あるいはコードを書くことさえ手助けします。
!> **セキュリティの注意**: マクロを使って、パスワード、クレジットカード番号、その他の機密情報のいずれも送信することが可能ですが、それは非常に悪い考えです。あなたのキーボードを手に入れた人は誰でもテキストエディタを開いてその情報にアクセスすることができます。
## 新しい方法: `SEND_STRING()` と `process_record_user`
単語またはフレーズを入力するキーが欲しい時があります。最も一般的な状況のために `SEND_STRING()` を提供しています。これは文字列(つまり、文字のシーケンス)を入力します。簡単にキーコードに変換することができる全ての ASCII 文字がサポートされています (例えば、`\n\t`)。
以下は2キーのキーボードのための `keymap.c` の例です:
```c
enum custom_keycodes {
QMKBEST = SAFE_RANGE,
};
bool process_record_user(uint16_t keycode, keyrecord_t *record) {
switch (keycode) {
case QMKBEST:
if (record->event.pressed) {
// キーコード QMKBEST が押された時
SEND_STRING("QMK is the best thing ever!");
} else {
// キーコード QMKBEST が放された時
}
break;
}
return true;
};
const uint16_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] = {
[0] = {
{QMKBEST, KC_ESC}
}
};
```
ここで起きることは以下の通りです:
最初に他のキーコードで使用されていない範囲で新しいカスタムキーコードを定義します。
次に、`process_record_user` 関数を使います。これはキーが押されるか放されるたびに呼び出され、カスタムキーコードがアクティブかどうかを確認します。
アクティブな場合、`SEND_STRING` マクロ (これは C プロセッサのマクロで、QMK のマクロと混同しないでください)を介して文字列 `"QMK is the best thing ever!"` をコンピュータに送信します。
呼び出し元に、処理したばかりのキー押下を通常通り(機能を置き換えたり変更したりしなかったので)処理し続けるよう指示するため、`true` を返します。
最後に、最初のボタンがマクロをアクティブにし、2番目のボタンが単なるエスケープボタンになるようにキーマップを定義します。
複数のマクロを追加することもできます。
以下のように、別のキーコードを追加し、switch 文に別の case ラベルを追加することで、それを行うことができます:
```c
enum custom_keycodes {
QMKBEST = SAFE_RANGE,
QMKURL,
MY_OTHER_MACRO
};
bool process_record_user(uint16_t keycode, keyrecord_t *record) {
switch (keycode) {
case QMKBEST:
if (record->event.pressed) {
// キーコード QMKBEST が押された時
SEND_STRING("QMK is the best thing ever!");
} else {
// キーコード QMKBEST が放された時
}
break;
case QMKURL:
if (record->event.pressed) {
// キーコード QMKURL が押された場合
SEND_STRING("https://qmk.fm/\n");
} else {
// キーコード QMKURL が放された場合
}
break;
case MY_OTHER_MACRO:
if (record->event.pressed) {
SEND_STRING(SS_LCTL("ac")); // 全てを選択しコピーします
}
break;
}
return true;
};
const uint16_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] = {
[0] = {
{MY_CUSTOM_MACRO, MY_OTHER_MACRO}
}
};
```
### 高度なマクロ
`process_record_user()` 関数のほかに、`post_process_record_user()` 関数があります。これは `process_record` の後に実行され、キーストロークが送信された後の処理に使用できます。これは例えば、通常のキーの前に押され、通常のキーの後で放されるキーがほしい場合に便利です。
この例では、通常のキー入力を変更して、キーストロークが通常送信される前に `F22` が押されるようにし、キーが放された__後にのみ__ `F22` キーを放します。
```c
static uint8_t f22_tracker;
bool process_record_user(uint16_t keycode, keyrecord_t *record) {
switch (keycode) {
case KC_A ... KC_F21: // F22 をスキップする方法に注意してください
case KC_F23 ... KC_EXSEL: //exsel は修飾キーの直前のキーです
if (record->event.pressed) {
register_code(KC_F22); //これは F22 を押したことを送信することを意味します
f22_tracker++;
register_code(keycode);
return false;
}
break;
}
return true;
}
void post_process_record_user(uint16_t keycode, keyrecord_t *record) {
switch (keycode) {
case KC_A ... KC_F21: // F22 をスキップする方法に注意してください
case KC_F23 ... KC_EXSEL: //exsel は修飾キーの直前のキーです
if (!record->event.pressed) {
f22_tracker--;
if (!f22_tracker) {
unregister_code(KC_F22); //これは F22 を放したことを送信することを意味します
}
}
break;
}
}
```
### タップ、ダウン、アップ
`Ctrl` あるいは `Home` など、ソースコードに文字列として表記できないキーをマクロで使うこともできます。
以下のようにラップすることで任意のコードを送信することができます:
* `SS_TAP()` キーを押して放します。
* `SS_DOWN()` キーを押します (ただし、放しません)。
* `SS_UP()` キーを放します。
例えば:
SEND_STRING(SS_TAP(X_HOME));
`KC_HOME` をタップします - プリフィックスが `X_` で `KC_` ではないことに注意してください。以下のように、他の文字列と組み合わせることもできます:
SEND_STRING("VE"SS_TAP(X_HOME)"LO");
これは "VE" に続けて `KC_HOME` をタップ、そして "LO" (新しい行の場合は "LOVE" と綴る)を送信します。
文字列に遅延を追加することもできます:
* `SS_DELAY(msecs)` は指定されたミリ秒だけ遅らせます。
例えば:
SEND_STRING("VE" SS_DELAY(1000) SS_TAP(X_HOME) "LO");
これは "VE" 、1秒の遅延、`KC_HOME` をタップ、"LO" (新しい行の場合は "LOVE" と綴るが、中間に遅延がある) を送信します。
使用できるモッドショートカットもいくつかあります:
* `SS_LCTL(文字列)`
* `SS_LSFT(文字列)`
* `SS_LALT(文字列)`、`SS_LOPT(文字列)`
* `SS_LGUI(文字列)`、`SS_LCMD(文字列)`、`SS_LWIN(文字列)`
* `SS_RCTL(文字列)`
* `SS_RSFT(文字列)`
* `SS_RALT(文字列)`、`SS_ROPT(文字列)`、`SS_ALGR(文字列)`
* `SS_RGUI(文字列)`、`SS_RCMD(文字列)`、`SS_RWIN(文字列)`
これらはそれぞれの修飾キーを押し、指定された文字列を送信してから、修飾キーを解放します。
それらは以下のように使うことができます:
SEND_STRING(SS_LCTL("a"));
これは、左 Control +`a` (左 Control をダウンし、`a`、左 Control をアップ)を送信します - それらは文字列(例えば `"k"`)であり、`X_K` キーコードでは無いことに注意してください。
### 代替キーマップ
デフォルトでは、QWERTY レイアウトの US キーマップを想定しています; それを変更したい場合(例えば OS がソフトウェア Colemak を使う場合)、キーマップのどこかに以下を含めます:
#include <sendstring_colemak.h>
### メモリ内の文字列
何らかの理由で文字列を操作していて、(リテラル、文字列定数の代わりに)生成したばかりのものを出力する必要がある場合は、以下のように `send_string()` を使うことができます:
```c
char my_str[4] = "ok.";
send_string(my_str);
```
上で定義したショートカットは `send_string()` では動作しないですが、必要に応じて別の行に分けることができます:
```c
char my_str[4] = "ok.";
SEND_STRING("I said: ");
send_string(my_str);
SEND_STRING(".."SS_TAP(X_END));
```
## 高度なマクロ関数
マクロの生成に役立つ関数が幾つかあります。マクロの中にかなり高度なコードを書くことができますが、機能が複雑になりすぎる場合は、代わりにカスタムキーコードを定義することをお勧めします。マクロはシンプルにしなければなりません。
?> 追加の機能として、[便利な関数](ja/ref_functions.md) の中で説明される関数を使うこともできます。例えば `reset_keyboard()` によりマクロの一部としてキーボードをリセットすることができます。
### `record->event.pressed`
これでスイッチが押されているか放されているかどうかをテストすることができます。以下が例です。
```c
if (record->event.pressed) {
// キーダウン時
} else {
// キーアップ時
}
```
### `register_code(<kc>);`
これはコンピュータに `<kc>` キーダウンイベントを送信します。例として `KC_ESC`、`KC_C`、`KC_4` や、`KC_LSFT` と `KC_LGUI` のような修飾キーなどもあります。
### `unregister_code(<kc>);`
`register_code` 関数と対応して、これは `<kc>` キーアップイベントをコンピュータに送信します。これを使わない場合、キーは送信されるまで押し続けられます。
### `tap_code(<kc>);`
これは `register_code(<kc>)` を送信し、その後 `unregister_code(<kc>)` を送信します。押下とリリースイベントの両方を送信する場合に便利です (押し続けるのではなく、キーを"タップ"する)。
タップの登録(解除)に問題がある場合、`config.h` ファイルで `#define TAP_CODE_DELAY 100` を設定することで、登録イベントと解除イベントの間に遅延を追加することができます。値はミリ秒です。
### `register_code16(<kc>);`、`unregister_code16(<kc>);`、`tap_code16(<kc>);`
これらの関数は対応する通常の関数と同様に機能しますが、修飾キーで修飾されたキーコードを使うことができます (Shift、Alt、Control、GUI を適用)。
例えば、修飾キーを押して(`register_code()`して)、キーコードを押す(`register_code()`する)代わりに、`register_code16(S(KC_5));` を使うことができます。
### `clear_keyboard();`
これは現在押されている全ての修飾キーとキーをクリアします。
### `clear_mods();`
これは現在押されている全ての修飾キーをクリアします。
### `clear_keyboard_but_mods();`
これは現在押されている修飾キー以外の全てのキーをクリアします。
## 高度な例:
### スーパー ALT↯TAB
このマクロは `KC_LALT` を登録し、`KC_TAB` をタップして、1000ms 待ちます。キーが再度タップされると、別の `KC_TAB` が送信されます; タップが無い場合、`KC_LALT` が登録解除され、ウィンドウを切り替えることができます。
```c
bool is_alt_tab_active = false; # keymap.c の先頭付近にこれを追加します
uint16_t alt_tab_timer = 0; # すぐにそれらを使います
enum custom_keycodes { # 素晴らしいキーコードを用意してください
ALT_TAB = SAFE_RANGE,
};
bool process_record_user(uint16_t keycode, keyrecord_t *record) {
switch (keycode) { # これはキーコードを利用したつまらない作業のほとんどを行います。
case ALT_TAB:
if (record->event.pressed) {
if (!is_alt_tab_active) {
is_alt_tab_active = true;
register_code(KC_LALT);
}
alt_tab_timer = timer_read();
register_code(KC_TAB);
} else {
unregister_code(KC_TAB);
}
break;
}
return true;
}
void matrix_scan_user(void) { # とても重要なタイマー
if (is_alt_tab_active) {
if (timer_elapsed(alt_tab_timer) > 1000) {
unregister_code(KC_LALT);
is_alt_tab_active = false;
}
}
}
```
---
## **(非推奨)** 古い方法: `MACRO()` と `action_get_macro`
!> これは TMK から継承されており、更新されていません - 代わりに `SEND_STRING` と `process_record_user` を使うことをお勧めします。
デフォルトでは、QMK はマクロが無いことを前提としています。マクロを定義するには、`action_get_macro()` 関数を作成します。例えば:
```c
const macro_t *action_get_macro(keyrecord_t *record, uint8_t id, uint8_t opt) {
if (record->event.pressed) {
switch(id) {
case 0:
return MACRO(D(LSFT), T(H), U(LSFT), T(I), D(LSFT), T(1), U(LSFT), END);
case 1:
return MACRO(D(LSFT), T(B), U(LSFT), T(Y), T(E), D(LSFT), T(1), U(LSFT), END);
}
}
return MACRO_NONE;
};
```
これは割り当てられているキーが押された時に実行される2つのマクロを定義します。キーが放された時にそれらを実行したい場合は、if 文を変更することができます。
if (!record->event.pressed) {
### マクロコマンド
マクロは以下のコマンドを含めることができます:
* I() はストロークの間隔をミリ秒単位で変更します。
* D() はキーを押します。
* U() はキーを放します。
* T() はキーをタイプ(押して放す)します。
* W() は待ちます (ミリ秒)。
* END 終了マーク。
### マクロをキーにマッピングする
マクロを呼び出すにはキーマップ内で `M()` 関数を使います。例えば、2キーのキーボードのキーマップは以下の通りです:
```c
const uint16_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] = {
[0] = LAYOUT(
M(0), M(1)
),
};
const macro_t *action_get_macro(keyrecord_t *record, uint8_t id, uint8_t opt) {
if (record->event.pressed) {
switch(id) {
case 0:
return MACRO(D(LSFT), T(H), U(LSFT), T(I), D(LSFT), T(1), U(LSFT), END);
case 1:
return MACRO(D(LSFT), T(B), U(LSFT), T(Y), T(E), D(LSFT), T(1), U(LSFT), END);
}
}
return MACRO_NONE;
};
```
左側のキーを押すと、"Hi!" を入力し、右側のキーを押すと "Bye!" を入力します。
### マクロに名前を付ける
キーマップを読みやすくしながらキーマップから参照したいマクロがたくさんある場合は、ファイルの先頭で `#define` を使って名前を付けることができます。
```c
#define M_HI M(0)
#define M_BYE M(1)
const uint16_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] = {
[0] = LAYOUT(
M_HI, M_BYE
),
};
```
## 高度な例:
### 単一キーのコピーと貼り付け
この例は、押された時に `Ctrl-C` を送信し、放される時に `Ctrl-V` を送信するマクロを定義します。
```c
const macro_t *action_get_macro(keyrecord_t *record, uint8_t id, uint8_t opt) {
switch(id) {
case 0: {
if (record->event.pressed) {
return MACRO( D(LCTL), T(C), U(LCTL), END );
} else {
return MACRO( D(LCTL), T(V), U(LCTL), END );
}
break;
}
}
return MACRO_NONE;
};
```

127
docs/ja/feature_mouse_keys.md Normal file
View File

@ -0,0 +1,127 @@
# マウスキー
<!---
original document: 0.8.141:docs/feature_mouse_keys.md
git diff 0.8.141 HEAD -- docs/feature_mouse_keys.md | cat
-->
マウスキーは、キーボードを使ってマウスをエミュレートできる機能です。様々な速度でポインタを移動し、5つのボタンを押し、8方向にスクロールすることができます。
## キーボードにマウスキーを追加
マウスキーを使うためには、少なくともマウスキーサポートを有効にし、マウスアクションをキーボードのキーにマップする必要があります。
### マウスキーを有効にする
マウスキーを有効にするには、キーマップの `rules.mk` に以下の行を追加します:
```c
MOUSEKEY_ENABLE = yes
```
### マウスアクションのマッピング
キーマップでキー押下をマウスアクションにマップするために、以下のキーコードを使うことができます:
| キー | エイリアス | 説明 |
|----------------|---------|-----------------|
| `KC_MS_UP` | `KC_MS_U` | カーソルを上に移動 |
| `KC_MS_DOWN` | `KC_MS_D` | カーソルを下に移動 |
| `KC_MS_LEFT` | `KC_MS_L` | カーソルを左に移動 |
| `KC_MS_RIGHT` | `KC_MS_R` | カーソルを右に移動 |
| `KC_MS_BTN1` | `KC_BTN1` | ボタン1を押す |
| `KC_MS_BTN2` | `KC_BTN2` | ボタン2を押す |
| `KC_MS_BTN3` | `KC_BTN3` | ボタン3を押す |
| `KC_MS_BTN4` | `KC_BTN4` | ボタン4を押す |
| `KC_MS_BTN5` | `KC_BTN5` | ボタン5を押す |
| `KC_MS_WH_UP` | `KC_WH_U` | ホイールを向こう側に回転 |
| `KC_MS_WH_DOWN` | `KC_WH_D` | ホイールを手前側に回転 |
| `KC_MS_WH_LEFT` | `KC_WH_L` | ホイールを左に倒す |
| `KC_MS_WH_RIGHT` | `KC_WH_R` | ホイールを右に倒す |
| `KC_MS_ACCEL0` | `KC_ACL0` | 速度を0に設定 |
| `KC_MS_ACCEL1` | `KC_ACL1` | 速度を1に設定 |
| `KC_MS_ACCEL2` | `KC_ACL2` | 速度を2に設定 |
## マウスキーの設定
マウスキーはカーソルを移動するための2つの異なるモードをサポートします:
* **加速 (デフォルト):** 移動キーを押したままにすると、カーソルが最大速度に達するまでカーソルを加速します。
* **定速:** 移動キーを押したままにすると、カーソルを一定の速度で移動します。
同じ原則がスクロールにも適用されます。
時間、間隔、遅延の設定オプションは、ミリ秒で指定されます。スクロール速度はデフォルトスクロールステップの倍数として渡されます。例えば、スクロール速度8は、各スクロールアクションがオペレーティングシステムまたはアプリケーションで定義されるデフォルトのスクロールステップの8倍の距離進むことを意味します。
### 加速モード
これはデフォルトのモードです。キーマップの `config.h` ファイルの以下の設定を使ってカーソルとスクロールの加速を調整することができます:
| 定義 | デフォルト | 説明 |
|----------------------------|-------|---------------------------------------------------------|
| `MOUSEKEY_DELAY` | 300 | 移動キーを押してからカーソルが移動するまでの遅延 |
| `MOUSEKEY_INTERVAL` | 50 | カーソル移動間の時間 |
| `MOUSEKEY_MAX_SPEED` | 10 | 加速が停止する最大のカーソル速度 |
| `MOUSEKEY_TIME_TO_MAX` | 20 | 最大カーソル速度に達するまでの時間 |
| `MOUSEKEY_WHEEL_DELAY` | 300 | ホイールキーを押してからホイールが動くまでの遅延 |
| `MOUSEKEY_WHEEL_INTERVAL` | 100 | ホイールの動きの間の時間 |
| `MOUSEKEY_WHEEL_MAX_SPEED` | 8 | スクロールアクションごとのスクロールステップの最大数 |
| `MOUSEKEY_WHEEL_TIME_TO_MAX` | 40 | 最大スクロール速度に達するまでの時間 |
ヒント:
* `MOUSEKEY_DELAY` の設定が低すぎるとカーソルが応答しなくなります。設定が高すぎると小さな動きが難しくなります。
* カーソルの動きをスムーズにするには、`MOUSEKEY_INTERVAL` の値を低くします。ディスプレイのリフレッシュレートが60Hzの場合、`16` (1/60) に設定することができます。これによりカーソルの速度が大幅に向上するため、`MOUSEKEY_MAX_SPEED` を下げた方が良いかもしれません。
* `MOUSEKEY_TIME_TO_MAX` または `MOUSEKEY_WHEEL_TIME_TO_MAX` を `0` に設定すると、それぞれカーソルの速度またはスクロールの加速が無効になります。この方法では、一方を加速しながら他方を一定にすることができますが、これは定速モードでは不可能です。
* `MOUSEKEY_WHEEL_INTERVAL` の設定が低すぎるとスクロールがとても速くなります。設定が高すぎるとホイールキーを押したままにした時にスクロールがとても遅くなります
カーソルの加速は、X Window System MouseKeysAccel 機能と同じアルゴリズムを使います。詳細については [Wikipedia](https://en.wikipedia.org/wiki/Mouse_keys) をご覧ください。
### 定速モード
このモードでは、カーソルおよびマウスホイールの両方について複数の異なる速度を定義することができます。加速はありません。`KC_ACL0`、`KC_ACL1` および `KC_ACL2` は、カーソルとスクロールの速度をそれぞれの設定に変更します。
速度の選択は、一時的とタップ選択のどちらかを選べます:
* **一時的:** 選択された速度は、それぞれのキーを押している間のみアクティブになります。キーを放すと、マウスキーは変更される前の速度に戻ります。
* **タップ選択:** それぞれのキーを押すと選択された速度がアクティブになり、キーを放した後もアクティブのままになります。デフォルトの速度は `KC_ACL1` です。未変更の速度はありません。
最も遅い速度から最も速い速度までのデフォルトの速度は以下の通りです:
* **一時的:** `KC_ACL0` < `KC_ACL1` < *変更無し* < `KC_ACL2`
* **タップ選択:** `KC_ACL0` < `KC_ACL1` < `KC_ACL2`
定速モードを使うには、少なくともキーマップの keymaps ディレクトリの `config.h` ファイルに `MK_3_SPEED` を定義する必要があります。
```c
#define MK_3_SPEED
```
一時的モードを有効にするには、`MK_MOMENTARY_ACCEL` も定義します:
```c
#define MK_MOMENTARY_ACCEL
```
カーソル移動あるいはスクロールを調整する場合は、以下の設定を使います:
| 定義 | デフォルト | 説明 |
|---------------------|-------------|-------------------------------------------|
| `MK_3_SPEED` | *定義なし* | 定速カーソルを有効にする |
| `MK_MOMENTARY_ACCEL` | *定義なし* | 一時的モードを有効にする |
| `MK_C_OFFSET_UNMOD` | 16 | 移動ごとのカーソルオフセット (変更無し) |
| `MK_C_INTERVAL_UNMOD` | 16 | カーソルの移動間の時間 (変更無し) |
| `MK_C_OFFSET_0` | 1 | 移動ごとのカーソルオフセット (`KC_ACL0`) |
| `MK_C_INTERVAL_0` | 32 | カーソル移動間の時間 (`KC_ACL0`) |
| `MK_C_OFFSET_1` | 4 | 移動ごとのカーソルオフセット (`KC_ACL1`) |
| `MK_C_INTERVAL_1` | 16 | カーソル移動間の時間 (`KC_ACL1`) |
| `MK_C_OFFSET_2` | 32 | 移動ごとのカーソルオフセット (`KC_ACL2`) |
| `MK_C_INTERVAL_2` | 16 | カーソル移動間の時間 (`KC_ACL2`) |
| `MK_W_OFFSET_UNMOD` | 1 | スクロールアクションごとのスクロールステップ (変更無し) |
| `MK_W_INTERVAL_UNMOD` | 40 | スクロールステップ間の時間 (変更無し) |
| `MK_W_OFFSET_0` | 1 | スクロールアクションごとのスクロールステップ (`KC_ACL0`) |
| `MK_W_INTERVAL_0` | 360 | スクロールステップ間の時間 (`KC_ACL0`) |
| `MK_W_OFFSET_1` | 1 | スクロールアクションごとのスクロールステップ (`KC_ACL1`) |
| `MK_W_INTERVAL_1` | 120 | スクロールステップ間の時間 (`KC_ACL1`) |
| `MK_W_OFFSET_2` | 1 | スクロールアクションごとのスクロールステップ (`KC_ACL2`) |
| `MK_W_INTERVAL_2` | 20 | スクロールステップ間の時間 (`KC_ACL2`) |

49
docs/ja/feature_pointing_device.md Normal file
View File

@ -0,0 +1,49 @@
# ポインティングデバイス :id=pointing-device
<!---
original document: 0.8.182:docs/feature_pointing_device.md
git diff 0.8.182 HEAD -- docs/feature_pointing_device.md | cat
-->
ポインティングデバイスは汎用的な機能の総称です: システムポインタを移動します。マウスキーのような他のオプションも確かにありますが、これは簡単に変更可能で軽量であることを目指しています。機能を制御するためにカスタムキーを実装したり、他の周辺機器から情報を収集してここに直接挿入したりできます - QMK に処理を任せてください。
ポインティングデバイスを有効にするには、rules.mk の以下の行のコメントを解除します:
```makefile
POINTING_DEVICE_ENABLE = yes
```
マウスレポートを操作するために、以下の関数を使うことができます:
* `pointing_device_get_report()` - ホストコンピュータに送信された情報を表す現在の report_mouse_t を返します。
* `pointing_device_set_report(report_mouse_t newMouseReport)` - ホストコンピュータに送信される report_mouse_t を上書き保存します。
report_mouse_t (ここでは "mouseReport") が以下のプロパティを持つことを覚えておいてください:
* `mouseReport.x` - これは、x軸の動き(+ 右へ、- 左へ)を表す -127 から 127 (128ではなく、USB HID 仕様で定義されています)の符号付き整数です。
* `mouseReport.y` - これは、y軸の動き(+ 上へ、- 下へ)を表す -127 から 127 (128ではなく、USB HID 仕様で定義されています)の符号付き整数です。
* `mouseReport.v` - これは、垂直スクロール(+ 上へ、- 下へ)を表す -127 から 127 (128ではなく、USB HID 仕様で定義されています)の符号付き整数です。
* `mouseReport.h` - これは、水平スクロール(+ 右へ、- 左へ)を表す -127 から 127 (128ではなく、USB HID 仕様で定義されています)の符号付き整数です。
* `mouseReport.buttons` - これは uint8_t で、上位の5ビットを使っています。これらのビットはマウスボタンの状態を表します - ビット 3 はマウスボタン 5、ビット 7 はマウスボタン 1 です。
マウスレポートが送信されると、x、y、v、h のいずれの値も 0 に設定されます (これは "pointing_device_send()" で行われます。この挙動を回避するためにオーバーライドすることができます)。このように、ボタンの状態は持続しますが、動きは1度だけ起こります。さらにカスタマイズするために、`pointing_device_init` と `pointing_device_task` のどちらもオーバーライドすることができます。
以下の例では、カスタムキーを使ってマウスをクリックし垂直および水平方向に127単位スクロールし、リリースされた時にそれを全て元に戻します - なぜならこれは完全に便利な機能だからです。いいですか、以下はひとつの例です:
```c
case MS_SPECIAL:
report_mouse_t currentReport = pointing_device_get_report();
if (record->event.pressed) {
currentReport.v = 127;
currentReport.h = 127;
currentReport.buttons |= MOUSE_BTN1; // this is defined in report.h
} else {
currentReport.v = -127;
currentReport.h = -127;
currentReport.buttons &= ~MOUSE_BTN1;
}
pointing_device_set_report(currentReport);
break;
```
マウスレポートは送信されるたびに 0 (ボタンを除く)に設定されることを思い出してください。そのため、スクロールはそれぞれの場合に1度だけ発生します。

293
docs/ja/feature_ps2_mouse.md Normal file
View File

@ -0,0 +1,293 @@
# PS/2 マウスサポート :id=ps2-mouse-support
<!---
original document: 0.8.147:docs/feature_ps2_mouse.md
git diff 0.8.147 HEAD -- docs/feature_ps2_mouse.md | cat
-->
PS/2 マウス (例えばタッチパッドあるいはトラックポイント)を複合デバイスとしてキーボードに接続することができます。
トラックポイントを接続するには、トラックポイントモジュールを入手し (つまり、Thinkpad キーボードから部品を取って)、モジュールの各ピンの機能を特定し、コントローラとトラックポイントモジュールの間に必要な回路を作成する必要があります。詳細については、Deskthority Wiki の[トラックポイントハードウェア](https://deskthority.net/wiki/TrackPoint_Hardware)ページを参照してください。
PS/2 デバイスの接続は、USART(最善)、割り込み(次善)、 または busywait(非推奨)の3つのやり方が有ります。
## トラックポイントとコントローラ間の回路 :id=the-circuitry-between-trackpoint-and-controller
動作させるには、DATA と CLK のふたつのラインを 4.7k の抵抗で 5V にプルアップしてやる必要があります。
```
DATA ----------+--------- PIN
|
4.7K
|
MODULE 5+ --------+--+--------- PWR CONTROLLER
|
4.7K
|
CLK ------+------------ PIN
```
## Busywait バージョン :id=busywait-version
注意: これは非推奨です。ギクシャクした動きや、未送信の入力が発生するかもしれません。可能であれば、割り込みまたは USART バージョンを使ってください。
rules.mk で:
```makefile
PS2_MOUSE_ENABLE = yes
PS2_USE_BUSYWAIT = yes
```
キーボードの config.h で:
```c
#ifdef PS2_USE_BUSYWAIT
# define PS2_CLOCK_PORT PORTD
# define PS2_CLOCK_PIN PIND
# define PS2_CLOCK_DDR DDRD
# define PS2_CLOCK_BIT 1
# define PS2_DATA_PORT PORTD
# define PS2_DATA_PIN PIND
# define PS2_DATA_DDR DDRD
# define PS2_DATA_BIT 2
#endif
```
## 割り込みバージョン :id=interrupt-version
以下の例はクロックのために D2 を、データのために D5 を使います。クロックには任意の INT あるいは PCINT ピンを、データには任意のピンを使うことができます。
rules.mk で:
```makefile
PS2_MOUSE_ENABLE = yes
PS2_USE_INT = yes
```
キーボードの config.h で:
```c
#ifdef PS2_USE_INT
#define PS2_CLOCK_PORT PORTD
#define PS2_CLOCK_PIN PIND
#define PS2_CLOCK_DDR DDRD
#define PS2_CLOCK_BIT 2
#define PS2_DATA_PORT PORTD
#define PS2_DATA_PIN PIND
#define PS2_DATA_DDR DDRD
#define PS2_DATA_BIT 5
#define PS2_INT_INIT() do { \
EICRA |= ((1<<ISC21) | \
(0<<ISC20)); \
} while (0)
#define PS2_INT_ON() do { \
EIMSK |= (1<<INT2); \
} while (0)
#define PS2_INT_OFF() do { \
EIMSK &= ~(1<<INT2); \
} while (0)
#define PS2_INT_VECT INT2_vect
#endif
```
## USART バージョン :id=usart-version
ATMega32u4 で USART を使うには、クロックのために PD5 を、データのために PD2 を使う必要があります。それらのいずれかが利用できない場合は、割り込みバージョンを使う必要があります。
rules.mk で:
```makefile
PS2_MOUSE_ENABLE = yes
PS2_USE_USART = yes
```
キーボードの config.h で:
```c
#ifdef PS2_USE_USART
#define PS2_CLOCK_PORT PORTD
#define PS2_CLOCK_PIN PIND
#define PS2_CLOCK_DDR DDRD
#define PS2_CLOCK_BIT 5
#define PS2_DATA_PORT PORTD
#define PS2_DATA_PIN PIND
#define PS2_DATA_DDR DDRD
#define PS2_DATA_BIT 2
/* 同期、奇数パリティ、1-bit ストップ、8-bit データ、立ち下がりエッジでサンプル */
/* CLOCK の DDR を入力としてスレーブに設定 */
#define PS2_USART_INIT() do { \
PS2_CLOCK_DDR &= ~(1<<PS2_CLOCK_BIT); \
PS2_DATA_DDR &= ~(1<<PS2_DATA_BIT); \
UCSR1C = ((1 << UMSEL10) | \
(3 << UPM10) | \
(0 << USBS1) | \
(3 << UCSZ10) | \
(0 << UCPOL1)); \
UCSR1A = 0; \
UBRR1H = 0; \
UBRR1L = 0; \
} while (0)
#define PS2_USART_RX_INT_ON() do { \
UCSR1B = ((1 << RXCIE1) | \
(1 << RXEN1)); \
} while (0)
#define PS2_USART_RX_POLL_ON() do { \
UCSR1B = (1 << RXEN1); \
} while (0)
#define PS2_USART_OFF() do { \
UCSR1C = 0; \
UCSR1B &= ~((1 << RXEN1) | \
(1 << TXEN1)); \
} while (0)
#define PS2_USART_RX_READY (UCSR1A & (1<<RXC1))
#define PS2_USART_RX_DATA UDR1
#define PS2_USART_ERROR (UCSR1A & ((1<<FE1) | (1<<DOR1) | (1<<UPE1)))
#define PS2_USART_RX_VECT USART1_RX_vect
#endif
```
## 追加の設定 :id=additional-settings
### PS/2 マウス機能 :id=ps2-mouse-features
以下の PS/2 マウスプロトコルによってサポートされる設定を有効にします。
```c
/* デフォルトのストリームモードの代わりにリモートモードを使います (リンクを見てください) */
#define PS2_MOUSE_USE_REMOTE_MODE
/* マウスあるいはタッチパッドでスクロールホイールあるいはスクロールジェスチャーを有効にします */
#define PS2_MOUSE_ENABLE_SCROLLING
/* 一部のマウスでは、スクロールマスクを設定する必要があります。デフォルトは 0xFF です。*/
#define PS2_MOUSE_SCROLL_MASK 0x0F
/* ホストに送信する前に、動きに変換を適用します (リンクを見てください) */
#define PS2_MOUSE_USE_2_1_SCALING
/* ps2ホストを初期化した後の待機時間 */
#define PS2_MOUSE_INIT_DELAY 1000 /* Default */
```
ps2_mouse.h をインクルードして、以下の関数を呼び出すこともできます。
```c
void ps2_mouse_disable_data_reporting(void);
void ps2_mouse_enable_data_reporting(void);
void ps2_mouse_set_remote_mode(void);
void ps2_mouse_set_stream_mode(void);
void ps2_mouse_set_scaling_2_1(void);
void ps2_mouse_set_scaling_1_1(void);
void ps2_mouse_set_resolution(ps2_mouse_resolution_t resolution);
void ps2_mouse_set_sample_rate(ps2_mouse_sample_rate_t sample_rate);
```
### 細かい調整 :id=fine-control
マウスの感度と速度を変更するには以下の定義を使います。
注意: 同じ効果のために `ps2_mouse_set_resolution` も使うことができます (ほとんどのタッチパッドではサポートされません)。
```c
#define PS2_MOUSE_X_MULTIPLIER 3
#define PS2_MOUSE_Y_MULTIPLIER 3
#define PS2_MOUSE_V_MULTIPLIER 1
```
### スクロールボタン :id=scroll-button
トラックポイントを使っている場合は、スクロールのためにそれを使えるようにしたいでしょう。
押された時にマウスを移動させる代わりにスクロールさせる「スクロールボタン」を有効にすることができます。
この機能を有効にするには、以下のようにスクロールボタンマスクを設定する必要があります:
```c
#define PS2_MOUSE_SCROLL_BTN_MASK (1<<PS2_MOUSE_BUTTON_MIDDLE) /* Default */
```
スクロールボタン機能を無効にするには:
```c
#define PS2_MOUSE_SCROLL_BTN_MASK 0
```
利用可能なボタンは:
```c
#define PS2_MOUSE_BTN_LEFT 0
#define PS2_MOUSE_BTN_RIGHT 1
#define PS2_MOUSE_BTN_MIDDLE 2
```
ボタン定数を `|` で結合したマスクでボタンを組み合わせることができます。
スクロールボタンマスクを設定したら、スクロールボタンの送信間隔を設定する必要があります。
これは、スクロールボタンが離された場合に、スクロールボタンがホストに送信されるまでの間隔です。
この時間が経過すると、マウスはスクロールして送信されなくなります。
```c
#define PS2_MOUSE_SCROLL_BTN_SEND 300 /* Default */
```
スクロールボタンの送信を無効にするには:
```c
#define PS2_MOUSE_SCROLL_BTN_SEND 0
```
以下の定義でスクロールの細かい制御がサポートされます:
```c
#define PS2_MOUSE_SCROLL_DIVISOR_H 2
#define PS2_MOUSE_SCROLL_DIVISOR_V 2
```
### マウスとスクロールの軸の反転 :id=invert-mouse-and-scroll-axes
X 軸と Y 軸を反転するには、以下を config.h に配置します:
```c
#define PS2_MOUSE_INVERT_X
#define PS2_MOUSE_INVERT_Y
```
スクロールの軸を逆にするには、以下を config.h に配置します:
```c
#define PS2_MOUSE_INVERT_H
#define PS2_MOUSE_INVERT_V
```
### マウスの軸の回転 :id=rotate-mouse-axes
デバイスの出力を時計回りに 90 か 180 か 270 度変換します。
デバイスの向きを補正する場合は、出力を逆の方向に同じ量だけ回転します。例えば、通常のデバイスの向きが北向きの場合、以下のように補正します:
```c
#define PS2_MOUSE_ROTATE 270 /* 東向きのデバイスの向きの補正*/
```
```c
#define PS2_MOUSE_ROTATE 180 /* 南向きのデバイスの向きの補正*/
```
```c
#define PS2_MOUSE_ROTATE 90 /* 西向きのデバイスの向きの補正*/
```
### デバッグ設定 :id=debug-settings
マウスをデバッグするには、`debug_mouse = true` を追加するか、ブートマジックを使って有効にします。
```c
/* マウスレポートをデバッグするには */
#define PS2_MOUSE_DEBUG_HID
#define PS2_MOUSE_DEBUG_RAW
```

232
docs/ja/feature_split_keyboard.md Normal file
View File

@ -0,0 +1,232 @@
# 分割キーボード
<!---
original document:0.9.5:docs/feature_split_keyboard.md
git diff 0.9.5 HEAD -- docs/feature_split_keyboard.md | cat
-->
QMK ファームウェアリポジトリの多くのキーボードは、"分割"キーボードです。それらは2つのコントローラを使います — 1つは USB に接続し、もう1つは TRRS または同様のケーブルを介してシリアルまたは I<sup>2</sup>C 接続で接続します。
分割キーボードには多くの利点がありますが、有効にするには追加の作業が必要です。
QMK ファームウェアには、任意のキーボードで使用可能な一般的な実装と、多くのキーボード固有の実装があります。
このため、主に Let's Split とその他のキーボードで使われる一般的な実装について説明します。
!> ARM はまだ完全には分割キーボードをサポートしておらず、様々な制限があります。進捗はしていますが、機能の100%にはまだ達していません。
## 互換性の概要
| Transport | AVR | ARM |
|------------------------------|--------------------|--------------------|
| ['serial'](serial_driver.md) | :heavy_check_mark: | :white_check_mark: <sup>1</sup> |
| I2C | :heavy_check_mark: | |
注意:
1. ハードウェアとソフトウェアの両方の制限は、[ドライバーのドキュメント](serial_driver.md)の中で説明されます。
## ハードウェア設定
2つの Pro Micro 互換のコントローラを使っており、キーボードの左右を接続するために TRRS ジャックを使っていることを前提とします。
### ハードウェア要件
左右それぞれのキーボードマトリックスのためのダイオードとスイッチとは別に、2個の TRRS ソケットと 1本の TRRS ケーブルが必要です。
あるいは、少なくとも3本のワイヤがあるケーブルとソケットを使うことができます。
キーボードの左右間で通信するために I<sup>2</sup>C を使いたい場合は、少なくとも4本のワイヤを備えたケーブルと 2個の 4.7kΩ プルアップ抵抗が必要です。
#### 考慮事項
最も一般的に使われる接続は、TRRS ケーブルとジャックです。これらは4本のワイヤを提供し、分割キーボードに非常に有用で、簡単に見つけることができます。
ただし、ワイヤのうちの1本が Vcc を供給するため、キーボードはホットプラグ不可能です。TRRS ケーブルを抜き差しする前に、必ずキーボードのUSB接続をはずす必要があります。そうしなければ、コントローラを短絡させたり、もっと悪いことが起こるかもしれません。
別のオプションは電話ケーブルを使うことです (例えば、旧式の RJ-11/RJ-14 ケーブル)。実際に4本のワイヤ/レーンをサポートするものを使うようにしてください。
ただし、USB ケーブル、SATA ケーブル、そして単に4本の電線でもコントローラ間の通信に使用できることがわかっています。
!> コントローラ間の通信に USB ケーブルを使っても問題ありませんが、コネクタは通常の USB 接続と間違えられるかもしれず、配線方法によってはキーボードが短絡する可能性があります。このため、分割キーボードの接続のためにはお勧めできません。
### シリアル配線
2つの Pro Micro 間で GND、Vcc、D0 (別名 PDO あるいは pin 3) を TRS/TRRS ケーブルの3本のワイヤで接続します。
?> ここで使われるピンは実際には以下の `SOFT_SERIAL_PIN` によって設定されることに注意してください。
![シリアル配線](https://i.imgur.com/C3D1GAQ.png)
### I<sup>2</sup>C 配線
2つの Pro Micro 間で GND、Vcc、さらに SCL と SDA (それぞれ 別名 PD0/ピン3 および PD1/ピン2) を TRRS ケーブルの4本のワイヤで接続します。
プルアップ抵抗はキーボードの左右どちら側にも配置することができます。もし各側を単独で使いたい場合は、4つの抵抗を使い、両側にプルアップ抵抗を配置することもできます。
![I2C 配線](https://i.imgur.com/Hbzhc6E.png)
## ファームウェア設定
分割キーボード機能を有効にするには、以下を `rules.mk` に追加してください:
```make
SPLIT_KEYBOARD = yes
```
カスタムトランスポート (通信メソッド)を使っている場合は、以下を追加する必要もあります:
```make
SPLIT_TRANSPORT = custom
```
### 左右の設定
デフォルトでは、ファームウェアはどちら側がどちらであるかを認識しません; 決定するには幾つかの助けが必要です。これを行うには幾つかの方法があり、以下に優先順に列挙します。
#### ピンによる左右の設定
左右を決定するためにコントローラ上のピンを読むようにファームウェアを設定することができます。これを行うには、以下を `config.h` ファイルに追加します:
```c
#define SPLIT_HAND_PIN B7
```
これは指定されたピンを読み込みます。high の場合、コントローラはそれを左側だと仮定し、low の場合、それは右側であると仮定します。
#### EEPROM による左右の設定
このメソッドは永続ストレージ(`EEPROM`)のフラグを設定することで、キーボードの左右を設定します。これはコントローラが最初に起動する時にチェックされ、キーボードのどちら側であるかとキーボードのレイアウトの向きを決定します。
このメソッドを有効にするには、以下を `config.h` ファイルに追加します:
```c
#define EE_HANDS
```
ただし、各コントローラに正しい側の EEPROM ファイルを書き込む必要があります。これを手動で行うこともできますが、ファームウェアを書き込む時にこれを行う avrdude および dfu のターゲットが存在します。
* `:avrdude-split-left`
* `:avrdude-split-right`
* `:dfu-split-left`
* `:dfu-split-right`
* `:dfu-util-split-left`
* `:dfu-util-split-right`
この設定は、`EEP_RST` キーや `eeconfig_init()` 関数を使って EEPROM を再初期化する時には変更されません。ただし、ファームウェアの組み込みオプション以外で EEPROM をリセット([QMK Toolbox]() の "Reset EEPROM" ボタンの動作のように、`EEPROM` を上書きするファイルを書きこむなど)した場合、`EEPROM` ファイルを再書き込みする必要があります。
`EEPROM` ファイルは、QMK ファームウェアのリポジトリ内の[ここ](https://github.com/qmk/qmk_firmware/tree/master/quantum/split_common)にあります。
#### `#define` による左右の設定
コンパイル時に左右を設定することができます。これは以下を `config.h` ファイルに追加することで行うことができます:
```c
#define MASTER_RIGHT
```
あるいは
```c
#define MASTER_LEFT
```
どちらも定義されていない場合、左右のデフォルトは `MASTER_LEFT` になります。
### 通信オプション
全ての分割キーボードが同一であるとは限らないため、`config.h` ファイル内で設定することができる多くの追加のオプションがあります。
```c
#define USE_I2C
```
これは分割キーボードの I<sup>2</sup>C サポートを有効にします。これは厳密には通信用ではありませんが、OLED あるいは I<sup>2</sup>C ベースのデバイスに使うことができます。
```c
#define SOFT_SERIAL_PIN D0
```
これはシリアル通信用に使われるピンを設定します。シリアルを使っていない場合は、これを定義する必要はありません。
ただし、キーボード上でシリアルおよび I<sup>2</sup>C を使っている場合は、これを設定し、D0 および D1 以外の値に設定する必要があります (これらは I<sup>2</sup>C 通信のために使われます)。
```c
#define SELECT_SOFT_SERIAL_SPEED {#}`
```
シリアル通信に問題がある場合は、この値を変更して、シリアル用の通信速度を制御することができます。デフォルトは1で、可能な値は以下の通りです:
* **`0`**: 約189kbps (実験用途専用)
* **`1`**: 約137kbps (デフォルト)
* **`2`**: 約75kbps
* **`3`**: 約39kbps
* **`4`**: 約26kbps
* **`5`**: 約20kbps
### ハードウェア設定オプション
ハードウェアのセットアップ方法に基づいて、設定する必要のある設定が幾つかあります。
```c
#define MATRIX_ROW_PINS_RIGHT { <row pins> }
#define MATRIX_COL_PINS_RIGHT { <col pins> }
```
これにより、右側のマトリックスに異なるピンのセットを指定することができます。これは、左右の形が違うキーボード (Keebio の Quefrency など)で、左右で別の構成が必要な場合に便利です。
```c
#define DIRECT_PINS_RIGHT { { F1, F0, B0, C7 }, { F4, F5, F6, F7 } }
```
これにより右側のための異なる直接ピンのセットを指定することができます。
```c
#define ENCODERS_PAD_A_RIGHT { encoder1a, encoder2a }
#define ENCODERS_PAD_B_RIGHT { encoder1b, encoder2b }
```
これにより右側のための異なるエンコーダピンのセットを指定することができます。
```c
#define RGBLIGHT_SPLIT
```
このオプションは、分割キーボードのコントローラ間で RGB ライトモードの同期を有効にします。これはコントローラに直接配線されている RGB LED を持つキーボード用です (つまり、それらは TRRS ケーブルで "追加データ"オプションを使っていません)。
```c
#define RGBLED_SPLIT { 6, 6 }
```
これは各コントローラに直接接続されている LED の数を設定します。最初の数は左側、2番目の数は右側です。
?> この設定は `RGBLIGHT_SPLIT` が有効になっていることを意味し、有効になっていない場合は強制的に有効にします。
```c
#define SPLIT_USB_DETECT
```
このオプションは、スタートアップの挙動を変更して、マスタ/スレーブの決定時にアクティブな USB 接続を検出します。このオプションがタイムアウトになった場合、その片側はスレーブと見なされます。これは ARM のデフォルトの挙動で、AVR Teensy ボードに必要です (ハードウェアの制限のため)。
?> この設定はバッテリパックを使ったデモの機能を停止します。
```c
#define SPLIT_USB_TIMEOUT 2000
```
これは、`SPLIT_USB_DETECT` を使う時のマスタ/スレーブを検出する場合の最大タイムアウトを設定します。
```c
#define SPLIT_USB_TIMEOUT_POLL 10
```
これは `SPLIT_USB_DETECT` を使う時のマスタ/スレーブを検出する場合のポーリング頻度を設定します
## 追加のリソース(英語)
Nicinabox には Let's Split キーボードのための[非常に優れた詳細なガイド](https://github.com/nicinabox/lets-split-guide)があり、トラブルシューティング情報を含む知っておくべきほとんど全てをカバーします。
ただし、RGB ライトセクションは、RGB Split コードが QMK ファームウェアに追加されるずっと前に書かれたため、古くなっています。ガイドに従う代わりに、各 LED テーブ(訳注: LED strip とも呼びます)を直接コントローラに配線します。
<!-- I may port this information later, but for now ... it's very nice, and covers everything -->

36
docs/ja/feature_swap_hands.md Normal file
View File

@ -0,0 +1,36 @@
# スワップハンドアクション
<!---
original document: 0.8.177:docs/feature_swap_hands.md
git diff 0.8.177 HEAD -- docs/feature_swap_hands.md | cat
-->
スワップハンドアクションにより、別のレイヤーを必要とせずに片手入力をサポートします。Makefile に `SWAP_HANDS_ENABLE` を設定し、キーマップに `hand_swap_config` エントリを定義します。これで `ACTION_SWAP_HANDS` コマンドキーが押されるたびにキーボードがミラーされます。例えば、QWERTY で "Hello, World" を入力するには、`^Ge^s^s^w^c W^wr^sd` を入力します。
## 設定
設定テーブルは列/行から新しい列/行にマップするための単純な2次元配列です。Planck の `hand_swap_config` の例:
```C
const keypos_t hand_swap_config[MATRIX_ROWS][MATRIX_COLS] = {
{{11, 0}, {10, 0}, {9, 0}, {8, 0}, {7, 0}, {6, 0}, {5, 0}, {4, 0}, {3, 0}, {2, 0}, {1, 0}, {0, 0}},
{{11, 1}, {10, 1}, {9, 1}, {8, 1}, {7, 1}, {6, 1}, {5, 1}, {4, 1}, {3, 1}, {2, 1}, {1, 1}, {0, 1}},
{{11, 2}, {10, 2}, {9, 2}, {8, 2}, {7, 2}, {6, 2}, {5, 2}, {4, 2}, {3, 2}, {2, 2}, {1, 2}, {0, 2}},
{{11, 3}, {10, 3}, {9, 3}, {8, 3}, {7, 3}, {6, 3}, {5, 3}, {4, 3}, {3, 3}, {2, 3}, {1, 3}, {0, 3}},
};
```
配列のインデックスはマトリックスと同様に逆になり、値の型は `{col, row}` である `keypos_t` で、全ての値はゼロベースであることに注意してください。上の例では、`hand_swap_config[2][4]` (第3行, 第5列)は `{7, 2}` (第3行, 第8列) を返します。はい。紛らわしいです。
## キーコードの入れ替え
| キー | 説明 |
|-----------|-------------------------------------------------------------------------|
| `SH_T(key)` | タップで `key` を送信する。押している時の一時的な入れ替え。 |
| `SH_ON` | 入れ替えをオンにして、そのままにする。 |
| `SH_OFF` | 入れ替えをオフにして、そのままにする。既知の状態に戻るのに適しています。 |
| `SH_MON` | 押すとスワップハンドし、放すと通常に戻る (一時的)。 |
| `SH_MOFF` | 一時的に入れ替えをオフする。 |
| `SH_TG` | キーを押すたびに入れ替えのオンとオフを切り替える。 |
| `SH_TT` | タップで切り替える。押されている時の一時的なもの。 |
| `SH_OS` | ワンショットスワップハンド: 押されている時あるいは次のキーを押すまで切り替える。 |

4
docs/ja/feature_tap_dance.md
View File

@ -1,8 +1,8 @@
# タップダンス: 1つのキーが3つ、5つまたは100の異なる動作をします
<!---
original document: 634b277b0:docs/feature_tap_dance.md
git diff 634b277b0 HEAD -- docs//feature_tap_dance.md | cat
original document: 0.9.0:docs/feature_tap_dance.md
git diff 0.9.0 HEAD -- docs/feature_tap_dance.md | cat
-->
## イントロダクション

112
docs/ja/feature_terminal.md Normal file
View File

@ -0,0 +1,112 @@
# ターミナル
<!---
original document: 0.8.147:docs/feature_terminal.md
git diff 0.8.147 HEAD -- docs/feature_terminal.md | cat
-->
> この機能は現在のところ*巨大*であり、おそらく大量のメモリを搭載したキーボード、または楽しみのためにのみ配置する必要があります。
ターミナル機能はテキストエディタを介してキーストロークで通信するように設計されたコマンドラインのようなインタフェースです。エディタで自動インデント機能をオフにすることは有益です。
有効にするには、以下を `rules.mk` または `Makefile` に貼り付けます:
TERMINAL_ENABLE = yes
そして、オンまたはオフにするために、`TERM_ON` および `TERM_OFF` キーコードを使います。
有効な場合、`> ` プロンプトが現れ、ここでコマンドやバックスペース(オーディオが有効な場合は、先頭に到達するとベルが鳴ります)を入力することができ、エンターを入力するとコマンドを送信します。矢印キーは現在のところ無効なため、混乱することはありません。マウスでカーソルを移動することはお勧めしません。
`#define TERMINAL_HELP` は、このページでは実際には必要のない他の出力ヘルパーを有効にします。
"上矢印" および "下矢印" により、過去に入力した5つのコマンドを順に切り替えることができます。
## 今後のアイデア
* キーボード/ユーザ拡張可能なコマンド
* より小さなフットプリント
* 矢印キーのサポート
* コマンド履歴 - 完了
* SD カードのサポート
* バッファディスプレイのための LCD サポート
* キーコード -> 名称の対応表
* レイヤー状態
* *アナログ/デジタル ポートの読み込み/書き込み*
* RGB モード関連機能
* マクロ定義
* EEPROM の読み込み/書き込み
* オーディオ制御
## 現在のコマンド
### `about`
現在の QMK のバージョンとビルドした日の出力:
```
> about
QMK Firmware
v0.5.115-7-g80ed73-dirty
Built: 2017-08-29-20:24:44
```
### `print-buffer`
最後に入力した5つのコマンドの出力
```
> print-buffer
0. print-buffer
1. help
2. about
3. keymap 0
4. help
5. flush-buffer
```
### `flush-buffer`
コマンドバッファをクリア
```
> flush-buffer
Buffer cleared!
```
### `help`
利用可能なコマンドの出力:
```
> help
commands available:
about help keycode keymap exit print-buffer flush-buffer
```
### `keycode <layer> <row> <col>`
特定のレイヤー、行および列のキーコード値の出力:
```
> keycode 0 1 0
0x29 (41)
```
### `keymap <layer>`
特定のレイヤーの全てのキーマップの出力
```
> keymap 0
0x002b, 0x0014, 0x001a, 0x0008, 0x0015, 0x0017, 0x001c, 0x0018, 0x000c, 0x0012, 0x0013, 0x002a,
0x0029, 0x0004, 0x0016, 0x0007, 0x0009, 0x000a, 0x000b, 0x000d, 0x000e, 0x000f, 0x0033, 0x0034,
0x00e1, 0x001d, 0x001b, 0x0006, 0x0019, 0x0005, 0x0011, 0x0010, 0x0036, 0x0037, 0x0038, 0x0028,
0x5cd6, 0x00e0, 0x00e2, 0x00e3, 0x5cd4, 0x002c, 0x002c, 0x5cd5, 0x0050, 0x0051, 0x0052, 0x004f,
>
```
### `exit`
ターミナルの終了 - `TERM_OFF` と同じ。

15
docs/ja/feature_thermal_printer.md Normal file
View File

@ -0,0 +1,15 @@
# 感熱式プリンタ
<!---
original document: 0.8.147:docs/feature_thermal_printer.md
git diff 0.8.147 HEAD -- docs/feature_thermal_printer.md | cat
-->
<!-- FIXME: Describe thermal printers support here. -->
## 感熱式プリンタのキーコード
| キー | 説明 |
|-----------|----------------------------------------|
| `PRINT_ON` | ユーザが入力した全ての印刷を開始 |
| `PRINT_OFF` | ユーザが入力した全ての印刷を停止 |

260
docs/ja/feature_userspace.md Normal file
View File

@ -0,0 +1,260 @@
# ユーザスペース: キーマップ間でのコードの共有
<!---
original document: 0.9.0:docs/feature_userspace.md
git diff 0.9.0 HEAD -- docs/feature_userspace.md | cat
-->
似たキーマップを複数のキーボードで使う場合、それらの間でコードを共有できるという利点が得られることがあります。`users/`に以下の構造でキーマップ(理想的には GitHub のユーザ名、`<name>`)と同じ名前の独自のフォルダを作成します:
* `/users/<name>/` (パスに自動的に追加されます)
* `readme.md` (オプション、推奨)
* `rules.mk` (自動的に含まれます)
* `config.h` (自動的に含まれます)
* `<name>.h` (オプション)
* `<name>.c` (オプション)
* `cool_rgb_stuff.c` (オプション)
* `cool_rgb_stuff.h` (オプション)
以下のように、`<name>` という名前のキーマップをビルドする時のみ、これが全て起きます:
make planck:<name>
例えば、
make planck:jack
は、`/users/jack/rules.mk` に加えて、パスに `/users/jack/` フォルダを含めます。
!> この `name` は必要に応じて[上書き](#override-default-userspace)することができます。
## `Rules.mk`
`rules.mk` は自動的に処理される2つファイルのうちの1つです。これにより、コンパイル時に追加のソースファイル( `<name>.c` など)を追加できます。
追加されるデフォルトのソースファイルとして `<name>.c` を使うことを強くお勧めします。それを追加するために、以下のように `rules.mk` に SRC を追加する必要があります:
SRC += <name>.c
追加のファイルも同じ方法で追加できます - ただし、`<name>`.c/.h という名前のファイルを最初に用意することをお勧めします。
ビルド時に `/users/<name>/rules.mk` ファイルはキーマップの `rules.mk` の_後_でインクルードされます。これにより、キーボードによっては利用できないことのある個々の QMK 機能を利用する機能をユーザスペース `rules.mk` に持つことができます。
例えば、RGB ライトをサポートする全てのキーボード間で RGB 制御機能を共有する場合、RGBLIGHT 機能が有効であればサポートを追加することができます:
```make
ifeq ($(strip $(RGBLIGHT_ENABLE)), yes)
# ここにファンシーな rgb 関数のソースを含める
SRC += cool_rgb_stuff.c
endif
```
別のやり方として、キーマップの `rules.mk` で `define RGB_ENABLE` と定義し、以下のようにユーザスペースの `rules.mk` で変数をチェックすることができます:
```make
ifdef RGB_ENABLE
# ここにファンシーな rgb 関数のソースを含める
SRC += cool_rgb_stuff.c
endif
```
### デフォルトのユーザスペースの上書き :id=override-default-userspace
デフォルトでは、使用されるユーザスペース名はキーマップ名と同じです。状況によってはこれは望ましくありません。例えば、[レイアウト](ja/feature_layouts.md)機能を使う場合、異なるキーマップに同じ名前 (例えば、ANSI および ISO) を使うことができません。レイアウトに `mylayout-ansi` や `mylayout-iso` という名前を付け、以下の行をレイアウトの `rules.mk` に追加します:
```
USER_NAME := mylayout
```
これは、基板上に物理的に異なる機能を備えた、複数の異なるキーボード(RGBライトを備えたキーボード、オーディオを備えたキーボード、LEDの数が異なる、コントローラ上の異なるPINに接続されているなど)がある場合にも役立ちます。
## 設定オプション (`config.h`)
さらに、ここにある `config.h` はキーマップフォルダ内の同名のファイルと同じように処理されます。これは `<name>.h` ファイルとは別個に処理されます。
この理由は、`<name>.h` は (`#define TAPPING_TERM 100` などのような)設定を追加する時には追加されず、`config.h` ファイル内の `<name.h>` ファイルを含めるとコンパイルの問題を引き起こすからです。
!>`config.h` は[設定オプション](ja/config_options.md)のために使い、`<name>.h` ファイルはユーザあるいは(レイヤーあるいはキーコードのための enum のような)キーマップ固有の設定のために使うべきです
## Readme (`readme.md`)
作者情報 (あなたの名前、GitHub ユーザ名、eメール)およびオプションで[GPL 互換のライセンス](https://www.gnu.org/licenses/license-list.html#GPLCompatibleLicenses)を含めてください。
以下をテンプレートとして使うことができます:
```
Copyright <year> <name> <email> @<github_username>
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/>.
```
年、名前、eメールおよび GitHub ユーザ名をあなたの情報に置き換えます。
さらに、コードを他の人に共有したい場合、ここはコードを文章化するのに適した場所です。
## 特定のキーマップをサポートする全てのキーボードをビルドする
1つのコマンドで全てのキーマップのビルドを確認したいですか？以下で実行することができます:
make all:<name>
例えば、
make all:jack
これは、[_プルリクエスト_](https://github.com/qmk/qmk_firmware/pulls) を準備する時に全てが正常にコンパイルされることを確認したい場合に最適です。
## 例
簡単な例については、[`/users/_example/`](https://github.com/qmk/qmk_firmware/tree/master/users/drashna) を調べてください。
より複雑な例については、[`/users/drashna/`](https://github.com/qmk/qmk_firmware/tree/master/users/drashna) のユーザスペースを調べてください。
### カスタマイズされた関数 :id=customized-functions
QMK には、[`_quantum`、`_kb` および `_user` バージョン](ja/custom_quantum_functions.md#a-word-on-core-vs-keyboards-vs-keymap)を持つ使用可能な[関数](custom_quantum_functions.md)が山ほどあります。 ほとんどの場合、これらの関数のユーザバージョンを使う必要があります。しかし問題はそれらをユーザスペースで使う場合、キーマップで使うことができるバージョンが無いことです。
しかし、実際にはキーマップバージョンのサポートを追加し、ユーザスペースとキーマップの両方で使うことができます。
例えば、`layer_state_set_user()` 関数を見てみましょう。全てのキーボードで [Tri Layer State](ja/ref_functions.md#olkb-tri-layers) 機能を有効にしながら、`keymap.c` ファイルで Tri Layer 機能を保持することができます。
`<name.c>` ファイル内で、以下を追加する必要があります:
```c
__attribute__ ((weak))
layer_state_t layer_state_set_keymap (layer_state_t state) {
return state;
}
layer_state_t layer_state_set_user (layer_state_t state) {
state = update_tri_layer_state(state, 2, 3, 5);
return layer_state_set_keymap (state);
}
```
`__attribute__ ((weak))` 部分は、コンパイラにこれが `keymap.c` 内のバージョンに置き換えられるプレースホルダ関数であることを伝えます。そうすれば、`keymap.c` に追加する必要はありませんが、追加しても関数が同じ名前を持つため競合することはありません。
ここでの `_keymap` 部分は重要では無く、`_quantum`、`_kb` あるいは `_user` は既に使われているため、それら以外のものである必要があります。`layer_state_set_mine`、`layer_state_set_fn` などを使うことができます。
[`users/drashna`](https://github.com/qmk/qmk_firmware/tree/master/users/drashna) 内の [`template.c`](https://github.com/qmk/qmk_firmware/blob/master/users/drashna/template.c) でこのリストと他の一般的な関数を見つけることができます。
### カスタム機能
ユーザスペース機能は膨大な数のキーボードをサポートすることができるため、特定の機能は有効にしたいが、他のキーボードでは有効にしたくないかもしれません。そして実際に自分のユーザスペースで有効あるいは無効にすることができる「機能」を作成することができます。
例えば、(スペースを節約するために)特定のキーボードでのみたくさんのマクロを利用したい場合、それらを `#ifdef MACROS_ENABLED` して「見えないように」してから、キーボードごとに有効にすることができます。これを行うには、以下を rules.mk に追加します。
```make
ifeq ($(strip $(MACROS_ENABLED)), yes)
OPT_DEFS += -DMACROS_ENABLED
endif
```
`OPT_DEFS` 設定は `MACROS_ENABLED` がキーボード用に定義されるようにし(名前の前に `-D` があることに注意してください)、c/h ファイルで状態をチェックするために `#ifdef MACROS_ENABLED` を使うことができ、それに基づいてそのコードを処理します。
次にキーマップの `rules.mk` に `MACROS_ENABLED = yes` を追加し、ユーザスペースでこの機能とコードを有効にします。
そして `process_record_user` 関数の中で、以下のようなことを行います:
```c
bool process_record_user(uint16_t keycode, keyrecord_t *record) {
switch (keycode) {
#ifdef MACROS_ENABLED
case MACRO1:
if (!record->event.pressed) {
SEND_STRING("This is macro 1!");
}
break;
case MACRO2:
if (!record->event.pressed) {
SEND_STRING("This is macro 2!");
}
break;
#endif
}
return true;
}
```
### 結合マクロ
全てのキーマップについてユーザスペースにマクロやそのほかの関数を統合したい場合は、そうすることができます。これは上記の[カスタマイズ関数](#customized-functions)の例に基づいています。これは異なるキーボード間で共有される大量のマクロを維持し、キーボード固有のマクロも可能です。
最初に、全ての `keymap.c` ファイルを調べ、代わりに `process_record_user` を `process_record_keymap` に置き換えます。この方法では、これらのキーボードでキーボード固有のコードを使用でき、カスタムの "global" キーコードも使うことができます。また、`SAFE_RANGE` を `NEW_SAFE_RANGE` に置き換えて、キーコードが重複しないようにすることもできます。
次に、全ての keymap.c ファイルに `#include <name.h>` を追加します。これにより、各キーマップでそれらを再定義することなく新しいキーコードを使うことができます。
それが完了したら、必要なキーコードの定義を `<name>.h` ファイルに設定します。例えば:
```c
#pragma once
#include "quantum.h"
#include "action.h"
#include "version.h"
// 全てを定義
enum custom_keycodes {
KC_MAKE = SAFE_RANGE,
NEW_SAFE_RANGE // キーマップ固有のコードについては "NEW_SAFE_RANGE" を使用
};
```
ここで、`<name>.c` ファイルを作成し、この内容をそれに追加します:
```c
#include "<name>.h"
__attribute__ ((weak))
bool process_record_keymap(uint16_t keycode, keyrecord_t *record) {
return true;
}
bool process_record_user(uint16_t keycode, keyrecord_t *record) {
switch (keycode) {
case KC_MAKE: // ファームウェアをコンパイルし、キーボードのブートローダに基づく書き込みコマンドを追加します
if (!record->event.pressed) {
uint8_t temp_mod = get_mods();
uint8_t temp_osm = get_oneshot_mods();
clear_mods(); clear_oneshot_mods();
SEND_STRING("make " QMK_KEYBOARD ":" QMK_KEYMAP);
#ifndef FLASH_BOOTLOADER
if ((temp_mod | temp_osm) & MOD_MASK_SHIFT)
#endif
{
SEND_STRING(":flash");
}
if ((temp_mod | temp_osm) & MOD_MASK_CTRL) {
SEND_STRING(" -j8 --output-sync");
}
tap_code(KC_ENT);
set_mods(temp_mod);
}
break;
}
return process_record_keymap(keycode, record);
}
```
(マクロパッドのような) Shift ボタンを持たないキーボードについては、ブートローダオプションを常に含める方法が必要です。これを行うには、以下をユーザスペースフォルダ内の `rules.mk` に追加します:
```make
ifeq ($(strip $(FLASH_BOOTLOADER)), yes)
OPT_DEFS += -DFLASH_BOOTLOADER
endif
```
これは任意のキーマップで使うことができる新しい `KC_MAKE` キーコードを追加します。そして、このキーコードは、`make <keyboard>:<keymap>` を出力するため、頻繁なコンパイルを簡単にします。そして、これは現在のキーボードの情報を出力するため、全てのキーボードとキーマップで動作します。そのため毎回これを入力する必要はありません。
また、Shift を押したままにすると書き込みの対象 (`:flash`) をコマンドに追加します。Control を押したままにすると、複数のファイルを一度に処理することでコンパイル時間を短縮する幾つかのコマンドを追加します。
そして Shift キーが無いキーボード、あるいは常に書き込みを試したいキーボードについては、キーマップの `rules.mk` に `FLASH_BOOTLOADER = yes` を追加することができます。
?> これはブートローダの設定に基づいて正しいユーティリティを使って新しくコンパイルされたファームウェアを自動的に書き込むはずです (あるいはデフォルトで HEX ファイルを生成するだけ)。ただし、これは全てのシステムで動作するわけではないことに注意してください。はっきり言うと、AVRDUDE は WSL では動作しません。そして、これは BootloadHID あるいは mdloader をサポートしません。

35
docs/ja/feature_velocikey.md Normal file
View File

@ -0,0 +1,35 @@
# Velocikey
<!---
original document: 0.8.147:docs/feature_velocikey.md
git diff 0.8.147 HEAD -- docs/feature_velocikey.md | cat
-->
Velocikey は入力の速度を使って(レインボー渦巻効果のような)ライト効果の速度を制御できる機能です。速く入力すればするほどライトが速くなります！
## 使用法
Velocikey を使うためには、2つのステップがあります。最初に、キーボードをコンパイルする時に、`rules.mk` に `VELOCIKEY_ENABLE=yes` を設定する必要があります。例えば:
```
BOOTMAGIC_ENABLE = no
MOUSEKEY_ENABLE = no
STENO_ENABLE = no
EXTRAKEY_ENABLE = yes
VELOCIKEY_ENABLE = yes
```
次に、キーボードの使用中に、VLK_TOG キーコードを使って Velocikey を有効にする必要もあります。これは機能をオンおよびオフにします。
以下の全てのライト効果が、Velocikey を有効にすることで制御されます:
- RGB 明滅動作
- RGB レインボームード
- RGB レインボー渦巻
- RGB スネーク
- RGB ナイト
LED 明滅動作の効果のサポートは計画されていますがまだ利用できません。
Velocikey が有効になっている限り、現在オンになっている RGB ライトの他の全ての速度設定に関係なく、速度が制御されます。
## 設定
Velocikey は現在のところキーボード設定を介したどのような設定もサポートしません。速度の増加あるいは減少率などを調整したい場合は、`velocikey.c` を編集し、そこで値を調整して、好みの速度を実現する必要があります。

24
docs/ja/feature_wpm.md Normal file
View File

@ -0,0 +1,24 @@
# Word Per Minute (WPM) の計算
<!---
original document: 0.9.0:docs/feature_wpm.md
git diff 0.9.0 HEAD -- docs/feature_wpm.md | cat
-->
WPM 機能は、キーストローク間の時間から1分あたりの平均（移動平均）単語数を計算し、様々な用途で利用できるようにします。
`rules.mk` に以下を追加することで WPM システムを有効にします:
WPM_ENABLE = yes
ソフトシリアルを使っている分割キーボードについては、計算された WPM スコアがマスター側とスレーブ側で利用可能です。
## 公開関数
`uint8_t get_current_wpm(void);`
この関数は符号なし整数で現在の WPM を返します。
## WPM 計算のためのカスタマイズ化されたキー
デフォルトでは、WPM スコアは文字、空白、およびいくつかの句読点のみを含みます。WPM の計算に含むとみなす文字セットを変更したい場合は、`wpm_keycode_user(uint16_t keycode)` を実装し、計算に含めたい文字について true を返し、計算しない特定のキーコードに false を返すようにします。

4
docs/ja/flashing.md
View File

@ -1,8 +1,8 @@
# 書き込みの手順とブートローダ情報
<!---
original document: 0.8.62:docs/flashing.md
git diff 0.8.62 HEAD -- docs/flashing.md | cat
original document: 0.9.10:docs/flashing.md
git diff 0.9.10 HEAD -- docs/flashing.md | cat
-->
キーボードが使用するブートローダにはかなり多くの種類があり、ほぼ全てが異なる書き込みの方法を使います。幸いなことに、[QMK Toolbox](https://github.com/qmk/qmk_toolbox/releases) のようなプロジェクトは、あまり深く考える必要無しに様々なタイプと互換性を持つことを目指していますが、この文章では様々なタイプのブートローダとそれらを書き込むために利用可能な方法について説明します。

8
docs/ja/getting_started_github.md
View File

@ -1,15 +1,15 @@
# QMK で Github を使う方法
# QMK で GitHub を使う方法
<!---
original document: 0.8.82:docs/getting_started_github.md
git diff 0.8.82 HEAD -- docs/getting_started_github.md | cat
-->
Github は慣れていない人には少し注意が必要です - このガイドは、QMK におけるフォーク、クローン、プルリクエストのサブミットの各ステップについて説明します。
GitHub は慣れていない人には少し注意が必要です - このガイドは、QMK におけるフォーク、クローン、プルリクエストのサブミットの各ステップについて説明します。
?> このガイドでは、あなたがコマンドラインでの実行にある程度慣れており、システムに git がインストールされていることを前提にしています。
[QMK Github ページ](https://github.com/qmk/qmk_firmware)を開くと、右上に "Fork" というボタンが見えます:
[QMK GitHub ページ](https://github.com/qmk/qmk_firmware)を開くと、右上に "Fork" というボタンが見えます:
![Git でのフォーク](http://i.imgur.com/8Toomz4.jpg)
@ -59,7 +59,7 @@ To https://github.com/whoeveryouare/qmk_firmware.git
+ 20043e64...7da94ac5 master -> master
```
あなたの変更は今では Github 上のフォークにあります - フォーク (`https://github.com/<whoeveryouare>/qmk_firmware`)に戻ると、"New Pull Request" ボタンをクリックすることで新しいプルリクエストを作成することができます:
あなたの変更は今では GitHub 上のフォークにあります - フォーク (`https://github.com/<whoeveryouare>/qmk_firmware`)に戻ると、"New Pull Request" ボタンをクリックすることで新しいプルリクエストを作成することができます:
![New Pull Request](http://i.imgur.com/DxMHpJ8.jpg)

4
docs/ja/getting_started_make_guide.md
View File

@ -1,8 +1,8 @@
# より詳細な `make` 手順
<!---
original document: 5f35203d1:docs/getting_started_make_guide.md
git diff 5f35203d1 HEAD -- docs/getting_started_make_guide.md | cat
original document: 0.9.0:docs/getting_started_make_guide.md
git diff 0.9.0 HEAD -- docs/getting_started_make_guide.md | cat
-->
`make` コマンドの完全な構文は `<keyboard_folder>:<keymap>:<target>` です:

4
docs/ja/getting_started_vagrant.md
View File

@ -1,8 +1,8 @@
# Vagrant クイックスタート
<!---
original document: 7494490d6:docs/getting_started_vagrant.md
git diff 7494490d6 HEAD -- docs/getting_started_vagrant.md | cat
original document: 0.9.10:docs/getting_started_vagrant.md
git diff 0.9.10 HEAD -- docs/getting_started_vagrant.md | cat
-->
このプロジェクトは、プライマリオペレーティングシステムに大きな変更を加えることなくキーボードの新しいファームウェアを非常に簡単に構築することができる `Vagrantfile` を含みます。これは、あなたがプロジェクトをクローンしビルドを実行した時に、ビルドのために Vagrantfile を使っている他のユーザと全く同じ環境を持つことも保証します。これにより、人々はあなたが遭遇した問題の解決をより簡単に行えるようになります。

4
docs/ja/hardware_avr.md
View File

@ -2,8 +2,8 @@
<!---
grep --no-filename "^[ ]*git diff" docs/ja/*.md | sh
original document: c9e3fa6f7:docs/hardware_avr.md
git diff c9e3fa6f7 HEAD -- docs/hardware_avr.md | cat
original document: 0.9.0:docs/hardware_avr.md
git diff 0.9.0 HEAD -- docs/hardware_avr.md | cat
-->
このページでは QMK における AVR マイコンのサポートについて説明します。AVR マイコンには、Atmel 社製の atmega32u4、atmega32u2、at90usb1286 やその他のマイコンを含みます。AVR マイコンは、簡単に動かせるよう設計された8ビットの MCU です。キーボードでよく使用される AVR マイコンには USB 機能や大きなキーボードマトリックスのためのたくさんの GPIO を搭載しています。これらは、現在、キーボードで使われる最も一般的な MCU です。

4
docs/ja/hardware_drivers.md
View File

@ -2,8 +2,8 @@
<!---
grep --no-filename "^[ ]*git diff" docs/ja/*.md | sh
original document: c9e3fa6f7:docs/hardware_drivers.md
git diff c9e3fa6f7 HEAD -- docs/hardware_drivers.md | cat
original document: 0.9.0:docs/hardware_drivers.md
git diff 0.9.0 HEAD -- docs/hardware_drivers.md | cat
-->
QMK はたくさんの異なるハードウェアで使われています。最も一般的な MCU とマトリックス構成をサポートしていますが、キーボードへ他のハードウェアを追加し制御するためのドライバーもいくつか用意されています。例えば、マウスやポインティングデバイス、分割キーボード用の IO エキスパンダ、Bluetooth モジュール、LCD、OLED、TFT 液晶などがあります。

71
docs/ja/hardware_keyboard_guidelines.md
View File

@ -2,8 +2,8 @@
<!---
grep --no-filename "^[ ]*git diff" docs/ja/*.md | sh
original document: c9e3fa6f7:docs/hardware_keyboard_guidelines.md
git diff c9e3fa6f7 HEAD -- docs/hardware_keyboard_guidelines.md | cat
original document: 0.9.0:docs/hardware_keyboard_guidelines.md
git diff 0.9.0 HEAD -- docs/hardware_keyboard_guidelines.md | cat
-->
QMK は開始以来、コミュニティにおけるキーボードの作成や保守に貢献しているあなたのような人たちのおかげで飛躍的に成長しました。私たちが成長するにつれて、うまくやるためのいくつかのパターンを発見しました。他の人たちがあなたの苦労の恩恵を受けやすくするため、それにあわせてもらえるようお願いします。
@ -66,10 +66,77 @@ Clueboard は、サブフォルダをまとめるためとキーボードのリ
全てのプロジェクトには、マトリックスサイズ、製品名、USB VID/PID、説明、その他の設定などが含まれた `config.h` ファイルが必要です。一般に、このファイルを使用して常に機能するキーボードの重要な情報やデフォルトを設定します。
また、`config.h` ファイルはサブフォルダにも置くことができ、その読み込み順は以下の通りです。
* `keyboards/top_folder/config.h`
* `keyboards/top_folder/sub_1/config.h`
* `keyboards/top_folder/sub_1/sub_2/config.h`
* `keyboards/top_folder/sub_1/sub_2/sub_3/config.h`
* `keyboards/top_folder/sub_1/sub_2/sub_3/sub_4/config.h`
* `users/a_user_folder/config.h`
* `keyboards/top_folder/keymaps/a_keymap/config.h`
* `keyboards/top_folder/sub_1/sub_2/sub_3/sub_4/post_config.h`
* `keyboards/top_folder/sub_1/sub_2/sub_3/post_config.h`
* `keyboards/top_folder/sub_1/sub_2/post_config.h`
* `keyboards/top_folder/sub_1/post_config.h`
* `keyboards/top_folder/post_config.h`
`post_config.h` ファイルは、`config.h` ファイルで指定された内容に応じて、追加の後処理を行うために使用することができます。
例えば、キーマップレベルの `config.h` ファイルで `IOS_DEVICE_ENABLE` マクロを以下のように定義すると、`post_config.h` ファイルでより詳細な設定を行うことができます。
* `keyboards/top_folder/keymaps/a_keymap/config.h`
```c
#define IOS_DEVICE_ENABLE
```
* `keyboards/top_folder/post_config.h`
```c
#ifndef IOS_DEVICE_ENABLE
// USB_MAX_POWER_CONSUMPTION value for this keyboard
#define USB_MAX_POWER_CONSUMPTION 400
#else
// fix iPhone and iPad power adapter issue
// iOS device need lessthan 100
#define USB_MAX_POWER_CONSUMPTION 100
#endif
#ifdef RGBLIGHT_ENABLE
#ifndef IOS_DEVICE_ENABLE
#define RGBLIGHT_LIMIT_VAL 200
#define RGBLIGHT_VAL_STEP 17
#else
#define RGBLIGHT_LIMIT_VAL 35
#define RGBLIGHT_VAL_STEP 4
#endif
#ifndef RGBLIGHT_HUE_STEP
#define RGBLIGHT_HUE_STEP 10
#endif
#ifndef RGBLIGHT_SAT_STEP
#define RGBLIGHT_SAT_STEP 17
#endif
#endif
```
?> 上記の例のように `post_config.h` でオプションを定義する場合、キーボードやユーザレベルの `config.h` で同じオプションを定義してはいけません。
### `rules.mk`
このファイルが存在するということは、フォルダがキーボードであり、`make` コマンドで使用できることを意味します。ここでキーボードのビルド環境を構築し、デフォルトの機能を設定します。
`rules.mk` ファイルはサブフォルダにも置くことができ、その読み込み順は以下の通りです。
* `keyboards/top_folder/rules.mk`
* `keyboards/top_folder/sub_1/rules.mk`
* `keyboards/top_folder/sub_1/sub_2/rules.mk`
* `keyboards/top_folder/sub_1/sub_2/sub_3/rules.mk`
* `keyboards/top_folder/sub_1/sub_2/sub_3/sub_4/rules.mk`
* `keyboards/top_folder/keymaps/a_keymap/rules.mk`
* `users/a_user_folder/rules.mk`
* `common_features.mk`
`rules.mk` ファイルに書かれた多くの設定は `common_features.mk` によって解釈され、必要なソースファイルやコンパイラのオプションが設定されます。
?> 詳しくは `build_keyboard.mk` と `common_features.mk` を見てください。
### `<keyboard_name.c>`
ここではキーボードのカスタマイズされたコードを記述します。通常、初期化してキーボードのハードウェアを制御するコードを記述します。キーボードが LED やスピーカー、その他付属ハードウェアのないキーマトリックスのみで構成されている場合は空にできます。

Some files were not shown because too many files have changed in this diff Show More