diff options
Diffstat (limited to 'docs')
86 files changed, 4195 insertions, 1246 deletions
diff --git a/docs/README.md b/docs/README.md index 22ab243cd..9f9ca166b 100644 --- a/docs/README.md +++ b/docs/README.md @@ -15,7 +15,7 @@ QMK (*Quantum Mechanical Keyboard*) is an open source community that maintains Q If you plan on contributing a keymap, keyboard, or features to QMK, the easiest thing to do is [fork the repo through Github](https://github.com/qmk/qmk_firmware#fork-destination-box), and clone your repo locally to make your changes, push them, then open a [Pull Request](https://github.com/qmk/qmk_firmware/pulls) from your fork. -Otherwise, you can either download it directly ([zip](https://github.com/qmk/qmk_firmware/zipball/master), [tar](https://github.com/qmk/qmk_firmware/tarball/master)), or clone it via git (`git@github.com:qmk/qmk_firmware.git`), or https (`https://github.com/qmk/qmk_firmware.git`). +Otherwise, you can clone it directly with `git clone https://github.com/qmk/qmk_firmware`. Do not download the zip or tar files; a git repository is required to download the submodules in order to compile. ## How to Compile diff --git a/docs/_langs.md b/docs/_langs.md index 7a7f127a9..f7b375fb9 100644 --- a/docs/_langs.md +++ b/docs/_langs.md @@ -4,4 +4,6 @@ - [:es: Español](/es/) - [:fr: Français](/fr-fr/) - [:he: עברית](/he-il/) + - [:brazil: Português](/pt-br/) - [:ru: Русский](/ru-ru/) + - [:jp: 日本語](/ja/) diff --git a/docs/_summary.md b/docs/_summary.md index dc6e88f95..f6b03867f 100644 --- a/docs/_summary.md +++ b/docs/_summary.md @@ -3,7 +3,10 @@ * [Building Your First Firmware](newbs_building_firmware.md) * [Flashing Firmware](newbs_flashing.md) * [Testing and Debugging](newbs_testing_debugging.md) - * [Git Best Practices](newbs_best_practices.md) + * [Best Git Practices](newbs_git_best_practices.md) + * [Using Your Fork's Master](newbs_git_using_your_master_branch.md) + * [Resolving Merge Conflicts](newbs_git_resolving_merge_conflicts.md) + * [Resynchronizing a Branch](newbs_git_resynchronize_a_branch.md) * [Learning Resources](newbs_learn_more_resources.md) * [QMK Basics](README.md) @@ -33,6 +36,7 @@ * [Keymap Overview](keymap.md) * [Hardware](hardware.md) + * [Compatible Microcontrollers](compatible_microcontrollers.md) * [AVR Processors](hardware_avr.md) * [Drivers](hardware_drivers.md) @@ -97,6 +101,7 @@ * [Hand Wiring Guide](hand_wire.md) * [ISP Flashing Guide](isp_flashing_guide.md) * [ARM Debugging Guide](arm_debugging.md) + * [ADC Driver](adc_driver.md) * [I2C Driver](i2c_driver.md) * [WS2812 Driver](ws2812_driver.md) * [GPIO Controls](internals_gpio_control.md) @@ -110,7 +115,7 @@ * [Using Eclipse with QMK](other_eclipse.md) * [Using VSCode with QMK](other_vscode.md) * [Support](support.md) - * [How to add translations](translating.md) + * [Translating the QMK Docs](translating.md) * QMK Internals (In Progress) * [Defines](internals_defines.md) diff --git a/docs/adc_driver.md b/docs/adc_driver.md new file mode 100644 index 000000000..26e148add --- /dev/null +++ b/docs/adc_driver.md @@ -0,0 +1,50 @@ +# ADC Driver + +QMK can leverage the Analog-to-Digital Converter (ADC) on supported MCUs to measure voltages on certain pins. This can be useful for implementing things such as battery level indicators for Bluetooth keyboards, or volume controls using a potentiometer, as opposed to a [rotary encoder](feature_encoders.md). + +This driver is currently AVR-only. The values returned are 10-bit integers (0-1023) mapped between 0V and VCC (usually 5V or 3.3V). + +## Usage + +To use this driver, add the following to your `rules.mk`: + +```make +SRC += analog.c +``` + +Then place this include at the top of your code: + +```c +#include "analog.h" +``` + +## Channels + +|Channel|AT90USB64/128|ATmega16/32U4|ATmega32A|ATmega328P| +|-------|-------------|-------------|---------|----------| +|0 |`F0` |`F0` |`A0` |`C0` | +|1 |`F1` |`F1` |`A1` |`C1` | +|2 |`F2` | |`A2` |`C2` | +|3 |`F3` | |`A3` |`C3` | +|4 |`F4` |`F4` |`A4` |`C4` | +|5 |`F5` |`F5` |`A5` |`C5` | +|6 |`F6` |`F6` |`A6` |* | +|7 |`F7` |`F7` |`A7` |* | +|8 | |`D4` | | | +|9 | |`D6` | | | +|10 | |`D7` | | | +|11 | |`B4` | | | +|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> + +## Functions + +|Function |Description | +|----------------------------|-------------------------------------------------------------------------------------------------------------------| +|`analogReference(mode)` |Sets the analog voltage reference source. Must be one of `ADC_REF_EXTERNAL`, `ADC_REF_POWER` or `ADC_REF_INTERNAL`.| +|`analogRead(pin)` |Reads the value from the specified Arduino pin, eg. `4` for ADC6 on the ATmega32U4. | +|`analogReadPin(pin)` |Reads the value from the specified QMK pin, eg. `F6` for ADC6 on the ATmega32U4. | +|`pinToMux(pin)` |Translates a given QMK pin to a mux value. If an unsupported pin is given, returns the mux value for "0V (GND)". | +|`adc_read(mux)` |Reads the value from the ADC according to the specified mux. See your MCU's datasheet for more information. | diff --git a/docs/cli.md b/docs/cli.md index e655b0ee8..1c0952722 100644 --- a/docs/cli.md +++ b/docs/cli.md @@ -95,6 +95,30 @@ qmk compile <configuratorExport.json> qmk compile -kb <keyboard_name> -km <keymap_name> ``` +## `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 <https://docs.qmk.fm/#/flashing> +for more details of the available bootloaders. + +**Usage for Configurator Exports**: + +``` +qmk flash <configuratorExport.json> -bl <bootloader> +``` + +**Usage for Keymaps**: + +``` +qmk flash -kb <keyboard_name> -km <keymap_name> -bl <bootloader> +``` + +**Listing the Bootloaders** + +``` +qmk flash -b +``` + ## `qmk config` This command lets you configure the behavior of QMK. For the full `qmk config` documentation see [CLI Configuration](cli_configuration.md). @@ -135,6 +159,28 @@ Creates a keymap.c from a QMK Configurator export. qmk json-keymap [-o OUTPUT] filename ``` +## `qmk kle2json` + +This command allows you to convert from raw KLE data to QMK Configurator JSON. It accepts either an absolute file path, or a file name in the current directory. By default it will not overwrite `info.json` if it is already present. Use the `-f` or `--force` flag to overwrite. + +**Usage**: + +``` +qmk kle2json [-f] <filename> +``` + +**Examples**: + +``` +$ qmk kle2json kle.txt +☒ File info.json already exists, use -f or --force to overwrite. +``` + +``` +$ qmk kle2json -f kle.txt -f +Ψ Wrote out to info.json +``` + ## `qmk list-keyboards` This command lists all the keyboards currently defined in `qmk_firmware` diff --git a/docs/cli_development.md b/docs/cli_development.md index f5c7ad139..cc8c59d06 100644 --- a/docs/cli_development.md +++ b/docs/cli_development.md @@ -173,3 +173,35 @@ You will only be able to access these arguments using `cli.args`. For example: ``` cli.log.info('Reading from %s and writing to %s', cli.args.filename, cli.args.output) ``` + +# Testing, and Linting, and Formatting (oh my!) + +We use nose2, flake8, and yapf to test, lint, and format code. You can use the `pytest` and `pyformat` subcommands to run these tests: + +### Testing and Linting + + qmk pytest + +### Formatting + + qmk pyformat + +## Formatting Details + +We use [yapf](https://github.com/google/yapf) to automatically format code. Our configuration is in the `[yapf]` section of `setup.cfg`. + +?> Tip- Many editors can use yapf as a plugin to automatically format code as you type. + +## Testing Details + +Our tests can be found in `lib/python/qmk/tests/`. You will find both unit and integration tests in this directory. We hope you will write both unit and integration tests for your code, but if you do not please favor integration tests. + +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 + +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. + +## Linting Details + +We use flake8 to lint our code. Your code should pass flake8 before you open a PR. This will be checked when you run `qmk pytest` and by CI when you submit a PR. diff --git a/docs/coding_conventions_c.md b/docs/coding_conventions_c.md index 08994bfbb..16e28b288 100644 --- a/docs/coding_conventions_c.md +++ b/docs/coding_conventions_c.md @@ -14,7 +14,7 @@ Most of our style is pretty easy to pick up on, but right now it's not entirely * Think of them as a story describing the feature * Use them liberally to explain why particular decisions were made. * Do not write obvious comments - * If you not sure if a comment is obvious, go ahead and include it. + * If you're not sure if a comment is obvious, go ahead and include it. * In general we don't wrap lines, they can be as long as needed. If you do choose to wrap lines please do not wrap any wider than 76 columns. * We use `#pragma once` at the start of header files rather than old-style include guards (`#ifndef THIS_FILE_H`, `#define THIS_FILE_H`, ..., `#endif`) * We accept both forms of preprocessor if's: `#ifdef DEFINED` and `#if defined(DEFINED)` diff --git a/docs/coding_conventions_python.md b/docs/coding_conventions_python.md index 694aa38cf..9dd95e4b7 100644 --- a/docs/coding_conventions_python.md +++ b/docs/coding_conventions_python.md @@ -8,7 +8,7 @@ Most of our style follows PEP8 with some local modifications to make things less * Think of them as a story describing the feature * Use them liberally to explain why particular decisions were made. * Do not write obvious comments - * If you not sure if a comment is obvious, go ahead and include it. + * If you're not sure if a comment is obvious, go ahead and include it. * We require useful docstrings for all functions. * In general we don't wrap lines, they can be as long as needed. If you do choose to wrap lines please do not wrap any wider than 76 columns. * Some of our practices conflict with the wider python community to make our codebase more approachable to non-pythonistas. diff --git a/docs/compatible_microcontrollers.md b/docs/compatible_microcontrollers.md index 6e3f8372c..85dd440d3 100644 --- a/docs/compatible_microcontrollers.md +++ b/docs/compatible_microcontrollers.md @@ -1,25 +1,36 @@ -# Atmel AVR +# Compatible Microcontrollers -QMK should run on any Atmel AVR processor with enough Flash. It has been tested on the following: +QMK runs on any USB-capable AVR or ARM microcontroller with enough flash space - generally 32kB or more, though it will *just* squeeze into 16kB with most features disabled. -* ATmega32U4 ([PJRC Teensy 2.0](http://www.pjrc.com/teensy/)) -* AT90USB1286 ([PJRC Teensy++ 2.0](http://www.pjrc.com/teensy/)) -* AT90USB1287 ([Atmel USBKEY](http://www.atmel.com/tools/AT90USBKEY.aspx)) -* ATmega168P with using [V-USB](http://www.obdev.at/products/vusb/index.html) -* ATmega328P with using [V-USB](http://www.obdev.at/products/vusb/index.html) -* ATmega32U2 -* AT90USB1286, 646, 647 should work -* AT90USB162 testing... +## Atmel AVR -NOTE: To enable full features of firmware you'll need 32KB flash size. +The following use [LUFA](https://www.fourwalledcubicle.com/LUFA.php) as the USB stack: -Please add any tested microcontrollers to this list. +* [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) -# ARM +Certain MCUs which do not have native USB will use [V-USB](https://www.obdev.at/products/vusb/index.html) instead: -You can also use any ARM processor that [ChibiOS](http://www.chibios.org) supports. The following processors have been tested: +* [ATmega32A](https://www.microchip.com/wwwproducts/en/ATmega32A) +* [ATmega328P](https://www.microchip.com/wwwproducts/en/ATmega328P) -* [Kinetis MKL26Z64](http://www.nxp.com/products/microcontrollers-and-processors/arm-processors/kinetis-cortex-m-mcus/l-series-ultra-low-power-m0-plus/kinetis-kl2x-48-mhz-usb-ultra-low-power-microcontrollers-mcus-based-on-arm-cortex-m0-plus-core:KL2x) -* [Kinetis MK20DX128](http://www.nxp.com/assets/documents/data/en/data-sheets/K20P64M50SF0.pdf) -* [Kinetis MK20DX128](http://www.nxp.com/assets/documents/data/en/data-sheets/K20P64M50SF0.pdf) -* [Kinetis MK20DX256](http://www.nxp.com/products/microcontrollers-and-processors/arm-processors/kinetis-cortex-m-mcus/k-series-performance-m4/k2x-usb/kinetis-k20-72-mhz-full-speed-usb-mixed-signal-integration-microcontrollers-mcus-based-on-arm-cortex-m4-core:K20_72) +## ARM + +You can also use any ARM chip with USB that [ChibiOS](http://www.chibios.org) supports. Most have plenty of flash. Known to work are: + +### 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 + +There is limited support for one of Atmel's ATSAM microcontrollers, that being the [ATSAMD51J18A](https://www.microchip.com/wwwproducts/en/ATSAMD51J18A) used by the [Massdrop keyboards](https://github.com/qmk/qmk_firmware/tree/master/keyboards/massdrop). diff --git a/docs/config_options.md b/docs/config_options.md index abd98ec8a..0cf3fb78a 100644 --- a/docs/config_options.md +++ b/docs/config_options.md @@ -196,8 +196,8 @@ If you define these options you will enable the associated feature, which may in * units to step when in/decreasing saturation * `#define RGBLIGHT_VAL_STEP 12` * units to step when in/decreasing value (brightness) -* `#define RGBW_BB_TWI` - * bit-bangs TWI to EZ RGBW LEDs (only required for Ergodox EZ) +* `#define RGBW` + * Enables RGBW LED support ## Mouse Key Options @@ -348,7 +348,8 @@ Use these to enable or disable building certain features. The more you have enab * `NO_USB_STARTUP_CHECK` * Disables usb suspend check after keyboard startup. Usually the keyboard waits for the host to wake it up before any tasks are performed. This is useful for split keyboards as one half will not get a wakeup call but must send commands to the master. * `LINK_TIME_OPTIMIZATION_ENABLE` - = Enables Link Time Optimization (`LTO`) when compiling the keyboard. This makes the process take longer, but can significantly reduce the compiled size (and since the firmware is small, the added time is not noticable). However, this will automatically disable the old Macros and Functions features automatically, as these break when `LTO` is enabled. It does this by automatically defining `NO_ACTION_MACRO` and `NO_ACTION_FUNCTION` + * Enables Link Time Optimization (`LTO`) when compiling the keyboard. This makes the process take longer, but can significantly reduce the compiled size (and since the firmware is small, the added time is not noticeable). However, this will automatically disable the old Macros and Functions features automatically, as these break when `LTO` is enabled. It does this by automatically defining `NO_ACTION_MACRO` and `NO_ACTION_FUNCTION` + * Alternatively, you can use `LTO_ENABLE` instead of `LINK_TIME_OPTIMIZATION_ENABLE`. ## USB Endpoint Limitations diff --git a/docs/contributing.md b/docs/contributing.md index 04dc0da20..7c365b418 100644 --- a/docs/contributing.md +++ b/docs/contributing.md @@ -101,6 +101,18 @@ enum my_keycodes { }; ``` +### Previewing the Documentation + +Before opening a pull request, you can preview your changes if you have set up the development environment by running this command from the `qmk_firmware/` folder: + + ./bin/qmk docs + +or if you only have Python 3 installed: + + python3 -m http.server 8936 + +and navigating to `http://localhost:8936/`. + ## Keymaps Most first-time QMK contributors start with their personal keymaps. We try to keep keymap standards pretty casual (keymaps, after all, reflect the personality of their creators) but we do ask that you follow these guidelines to make it easier for others to discover and learn from your keymap. diff --git a/docs/custom_quantum_functions.md b/docs/custom_quantum_functions.md index 839d49ca0..71a30bc7c 100644 --- a/docs/custom_quantum_functions.md +++ b/docs/custom_quantum_functions.md @@ -90,68 +90,93 @@ keyrecord_t record { # LED Control -QMK provides methods to read the 5 LEDs defined as part of the HID spec: +QMK provides methods to read 5 of the LEDs defined in the HID spec: -* `USB_LED_NUM_LOCK` -* `USB_LED_CAPS_LOCK` -* `USB_LED_SCROLL_LOCK` -* `USB_LED_COMPOSE` -* `USB_LED_KANA` +* Num Lock +* Caps Lock +* Scroll Lock +* Compose +* Kana -These five constants correspond to the positional bits of the host LED state. -There are two ways to get the host LED state: +There are two ways to get the lock LED state: -* by implementing `led_set_user()` -* by calling `host_keyboard_leds()` +* by implementing `bool led_update_kb(led_t led_state)` or `_user(led_t led_state)`; or +* by calling `led_t host_keyboard_led_state()` -## `led_set_user()` +!> `host_keyboard_led_state()` may already reflect a new value before `led_update_user()` is called. -This function will be called when the state of one of those 5 LEDs changes. It receives the LED state as a parameter. -Use the `IS_LED_ON(usb_led, led_name)` and `IS_LED_OFF(usb_led, led_name)` macros to check the LED status. +Two more deprecated functions exist that provide the LED state as a `uint8_t`: -!> `host_keyboard_leds()` may already reflect a new value before `led_set_user()` is called. +* `uint8_t led_set_kb(uint8_t usb_led)` and `_user(uint8_t usb_led)` +* `uint8_t host_keyboard_leds()` -### Example `led_set_user()` Implementation +## `led_update_user()` + +This function will be called when the state of one of those 5 LEDs changes. It receives the LED state as a struct parameter. + +By convention, return `true` from `led_update_user()` to get the `led_update_kb()` hook to run its code, and +return `false` when you would prefer not to run the code in `led_update_kb()`. + +Some examples include: + + - overriding the LEDs to use them for something else like layer indication + - return `false` because you do not want the `_kb()` function to run, as it would override your layer behavior. + - play a sound when an LED turns on or off. + - return `true` because you want the `_kb` function to run, and this is in addition to the default LED behavior. + +?> Because the `led_set_*` functions return `void` instead of `bool`, they do not allow for overriding the keyboard LED control, and thus it's recommended to use `led_update_*` instead. + +### Example `led_update_kb()` Implementation ```c -void led_set_user(uint8_t usb_led) { - if (IS_LED_ON(usb_led, USB_LED_NUM_LOCK)) { - writePinLow(B0); - } else { - writePinHigh(B0); - } - if (IS_LED_ON(usb_led, USB_LED_CAPS_LOCK)) { - writePinLow(B1); - } else { - writePinHigh(B1); - } - if (IS_LED_ON(usb_led, USB_LED_SCROLL_LOCK)) { - writePinLow(B2); - } else { - writePinHigh(B2); +bool led_update_kb(led_t led_state) { + bool res = led_update_user(led_state); + if(res) { + // writePin sets the pin high for 1 and low for 0. + // In this example the pins are inverted, setting + // it low/0 turns it on, and high/1 turns the LED off. + // This behavior depends on whether the LED is between the pin + // and VCC or the pin and GND. + writePin(B0, !led_state.num_lock); + writePin(B1, !led_state.caps_lock); + writePin(B2, !led_state.scroll_lock); + writePin(B3, !led_state.compose); + writePin(B4, !led_state.kana); } - if (IS_LED_ON(usb_led, USB_LED_COMPOSE)) { - writePinLow(B3); - } else { - writePinHigh(B3); - } - if (IS_LED_ON(usb_led, USB_LED_KANA)) { - writePinLow(B4); - } else { - writePinHigh(B4); + return res; +} +``` + +### Example `led_update_user()` Implementation + +This incomplete example would play a sound if Caps Lock is turned on or off. It returns `true`, because you also want the LEDs to maintain their state. + +```c +#ifdef AUDIO_ENABLE + float caps_on[][2] = SONG(CAPS_LOCK_ON_SOUND); + float caps_off[][2] = SONG(CAPS_LOCK_OFF_SOUND); +#endif + +bool led_update_user(led_t led_state) { + #ifdef AUDIO_ENABLE + static uint8_t caps_state = 0; + if (caps_state != led_state.caps_lock) { + led_state.caps_lock ? PLAY_SONG(caps_on) : PLAY_SONG(caps_off); + caps_state = led_state.caps_lock; } + #endif + return true; } ``` -### `led_set_*` Function Documentation +### `led_update_*` Function Documentation -* Keyboard/Revision: `void led_set_kb(uint8_t usb_led)` -* Keymap: `void led_set_user(uint8_t usb_led)` +* Keyboard/Revision: `bool led_update_kb(led_t led_state)` +* Keymap: `bool led_update_user(led_t led_state)` -## `host_keyboard_leds()` +## `host_keyboard_led_state()` -Call this function to get the last received LED state. This is useful for reading the LED state outside `led_set_*`, e.g. in [`matrix_scan_user()`](#matrix-scanning-code). -For convenience, you can use the `IS_HOST_LED_ON(led_name)` and `IS_HOST_LED_OFF(led_name)` macros instead of calling and checking `host_keyboard_leds()` directly. +Call this function to get the last received LED state as a `led_t`. This is useful for reading the LED state outside `led_update_*`, e.g. in [`matrix_scan_user()`](#matrix-scanning-code). ## Setting Physical LED State @@ -369,7 +394,7 @@ void keyboard_post_init_user(void) { // Set default layer, if enabled if (user_config.rgb_layer_change) { rgblight_enable_noeeprom(); - rgblight_sethsv_noeeprom_cyan(); + rgblight_sethsv_noeeprom_cyan(); rgblight_mode_noeeprom(1); } } @@ -417,18 +442,18 @@ bool process_record_user(uint16_t keycode, keyrecord_t *record) { } 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 - if (record->event.pressed) { + if (record->event.pressed) { user_config.rgb_layer_change ^= 1; // Toggles the status eeconfig_update_user(user_config.raw); // Writes the new status to EEPROM - if (user_config.rgb_layer_change) { // if layer state indication is enabled, + if (user_config.rgb_layer_change) { // if layer state indication is enabled, layer_state_set(layer_state); // then immediately update the layer color } } return false; break; case RGB_MODE_FORWARD ... RGB_MODE_GRADIENT: // For any of the RGB codes (see quantum_keycodes.h, L400 for reference) if (record->event.pressed) { //This disables layer indication, as it's assumed that if you're changing this ... you want that disabled - if (user_config.rgb_layer_change) { // only if this is enabled - user_config.rgb_layer_change = false; // disable it, and + if (user_config.rgb_layer_change) { // only if this is enabled + user_config.rgb_layer_change = false; // disable it, and eeconfig_update_user(user_config.raw); // write the setings to EEPROM } } @@ -441,7 +466,7 @@ bool process_record_user(uint16_t keycode, keyrecord_t *record) { And lastly, you want to add the `eeconfig_init_user` function, so that when the EEPROM is reset, you can specify default values, and even custom actions. To force an EEPROM reset, use the `EEP_RST` keycode or [Bootmagic](feature_bootmagic.md) functionallity. For example, if you want to set rgb layer indication by default, and save the default valued. ```c -void eeconfig_init_user(void) { // EEPROM is getting reset! +void eeconfig_init_user(void) { // EEPROM is getting reset! user_config.raw = 0; user_config.rgb_layer_change = true; // We want this enabled by default eeconfig_update_user(user_config.raw); // Write default value to EEPROM now @@ -466,7 +491,7 @@ The `val` is the value of the data that you want to write to EEPROM. And the `e By default, the tapping term is defined globally, and is not configurable by key. For most users, this is perfectly fine. But in come cases, dual function keys would be greatly improved by different timeouts 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 `TAPPING_TERM`. -To enable this functionality, you need to add `#define TAPPING_TERM_PER_KEY` to your `config.h`, first. +To enable this functionality, you need to add `#define TAPPING_TERM_PER_KEY` to your `config.h`, first. ## Example `get_tapping_term` Implementation diff --git a/docs/de/README.md b/docs/de/README.md new file mode 100644 index 000000000..88239d45d --- /dev/null +++ b/docs/de/README.md @@ -0,0 +1,33 @@ +# Quantum Mechanical Keyboard Firmware + +[](https://github.com/qmk/qmk_firmware/tags) +[](https://travis-ci.org/qmk/qmk_firmware) +[](https://discord.gg/Uq7gcHh) +[](https://docs.qmk.fm) +[](https://github.com/qmk/qmk_firmware/pulse/monthly) +[](https://github.com/qmk/qmk_firmware/) + +## Was ist QMK Firmware? + +QMK (*Quantum Mechanical Keyboard*) ist eine Open-Source-Community, welche die QMK-Firmware, die QMK-Toolbox, [qmk.fm](https://qmk.fm) und diese Dokumententation betreut. QMK-Firmware ist eine Weiterentwicklung der [tmk\_keyboard](http://github.com/tmk/tmk_keyboard)-Tastatur-Firmware mit vielen nützlichen Zusatzfunktionen für Atmel AVR-Prozessoren. Ursprünglich wurde sie für Produkte von [OLKB](http://olkb.com), das [ErgoDox EZ](http://www.ergodox-ez.com) und das [Clueboard](http://clueboard.co/) entwickelt. Im Laufe der Zeit wurde sie mit Hilfe von [ChibiOS](http://chibios.org) auch für die ARM-Architektur angepasst. Außerdem ist es inzwischen möglich, auch handverdrahtete Tastaturen und selbst geätzte PCBs mit QMK zu verwenden. + +## 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. + +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`). + + +## Anleitung fürs Kompilieren + +Bevor Du in der Lage bist, die Firmware zu kompilieren, musst Du eine [Entwicklungsumgebung](de/getting_started_build_tools.md) für AVR und/oder ARM aufsetzen. Danach kannst Du mit dem `make` Befehl eine Keymap für deine Tastatur erzeugen. Die Notation dafür ist: + + make planck/rev4:default + +Dies generiert die Revision `rev4` für eine Tastatur vom Type `planck` mit der `default` Tastaturbelegung. Nicht alle Tastaturen haben Revisionen (auch bekannt als Subprojekt oder Unterordner) weswegen dies auch ausgelassen werden kann: + + make preonic:default + +## Möglichkeiten der Anpassung + +QMK hat viele [Features](de/features.md), die es zu entdecken gibt. In der [Dokumentation](https://docs.qmk.fmk) kannst Du Dir einen Überblick verschaffen. Die meisten Features basieren darauf, die [Tastaturbelegung](de/keymap.md) anzupassen und das Verhalten der [Keycodes](de/keycodes.md) zu verändern. diff --git a/docs/de/_summary.md b/docs/de/_summary.md new file mode 100644 index 000000000..f3ce806ba --- /dev/null +++ b/docs/de/_summary.md @@ -0,0 +1,121 @@ +* [Anleitung für Anfänger](de/newbs.md) + * [Erste Schritte](de/newbs_getting_started.md) + * [Die erste Firmware](de/newbs_building_firmware.md) + * [Firmware flashen](de/newbs_flashing.md) + * [Testen und Debuggen](de/newbs_testing_debugging.md) + * [Git Tips und Tricks](de/newbs_best_practices.md) + * [Hilfreiche Ressourcen](de/newbs_learn_more_resources.md) + +* [QMK Basics](de/README.md) + * [QMK Einführung](de/getting_started_introduction.md) + * [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) + * [Nach Hilfe fragen](de/getting_started_getting_help.md) + +* [Breaking Changes](de/breaking_changes.md) + * [2019 Aug 30](de/ChangeLog/20190830.md) + +* [FAQ](de/faq.md) + * [Häufige Fragen](de/faq_general.md) + * [Build/Kompilieren](de/faq_build.md) + * [Debugging/Troubleshooting](de/faq_debug.md) + * [Keymap](de/faq_keymap.md) + * [Treiber Installation mit Zadig](de/driver_installation_zadig.md) + +* Detailierte Guides + * [Build Tools installieren](de/getting_started_build_tools.md) + * [Vagrant Guide](de/getting_started_vagrant.md) + * [Build/Compile Anleitung](de/getting_started_make_guide.md) + * [Firmware flashen](de/flashing.md) + * [Funktionalität anpassen](de/custom_quantum_functions.md) + * [Keymap Überblick](de/keymap.md) + +* [Hardware](de/hardware.md) + * [AVR Prozessoren](de/hardware_avr.md) + * [Treiber](de/hardware_drivers.md) + +* Referenz + * [Tastatur Richtlinien](de/hardware_keyboard_guidelines.md) + * [Konfigurations Optionen](de/config_options.md) + * [Keycodes](de/keycodes.md) + * [Coding Konventionen - C](de/coding_conventions_c.md) + * [Coding Konventionen - Python](de/coding_conventions_python.md) + * [Dokumentations Best Practices](de/documentation_best_practices.md) + * [Dokumentations Templates](de/documentation_templates.md) + * [Glossar](de/reference_glossary.md) + * [Unit Testing](de/unit_testing.md) + * [Nützliche Funktionen](de/ref_functions.md) + * [Configurator Support](de/reference_configurator_support.md) + * [info.json Format](de/reference_info_json.md) + * [Python CLI Development](de/cli_development.md) + +* [Features](de/features.md) + * [Basic Keycodes](de/keycodes_basic.md) + * [US ANSI Shifted Keys](de/keycodes_us_ansi_shifted.md) + * [Quantum Keycodes](de/quantum_keycodes.md) + * [Advanced Keycodes](de/feature_advanced_keycodes.md) + * [Audio](de/feature_audio.md) + * [Auto Shift](de/feature_auto_shift.md) + * [Backlight](de/feature_backlight.md) + * [Bluetooth](de/feature_bluetooth.md) + * [Bootmagic](de/feature_bootmagic.md) + * [Combos](de/feature_combo.md) + * [Command](de/feature_command.md) + * [Debounce API](de/feature_debounce_type.md) + * [DIP Switch](de/feature_dip_switch.md) + * [Dynamic Macros](de/feature_dynamic_macros.md) + * [Encoders](de/feature_encoders.md) + * [Grave Escape](de/feature_grave_esc.md) + * [Haptic Feedback](de/feature_haptic_feedback.md) + * [HD44780 LCD Controller](de/feature_hd44780.md) + * [Key Lock](de/feature_key_lock.md) + * [Layouts](de/feature_layouts.md) + * [Leader Key](de/feature_leader_key.md) + * [LED Matrix](de/feature_led_matrix.md) + * [Macros](de/feature_macros.md) + * [Mouse Keys](de/feature_mouse_keys.md) + * [OLED Driver](de/feature_oled_driver.md) + * [One Shot Keys](de/feature_advanced_keycodes.md#one-shot-keys) + * [Pointing Device](de/feature_pointing_device.md) + * [PS/2 Mouse](de/feature_ps2_mouse.md) + * [RGB Lighting](de/feature_rgblight.md) + * [RGB Matrix](de/feature_rgb_matrix.md) + * [Space Cadet](de/feature_space_cadet.md) + * [Split Keyboard](de/feature_split_keyboard.md) + * [Stenography](de/feature_stenography.md) + * [Swap Hands](de/feature_swap_hands.md) + * [Tap Dance](de/feature_tap_dance.md) + * [Terminal](de/feature_terminal.md) + * [Thermal Printer](de/feature_thermal_printer.md) + * [Unicode](de/feature_unicode.md) + * [Userspace](de/feature_userspace.md) + * [Velocikey](de/feature_velocikey.md) + +* Für Maker und Modder + * [Hand Wiring Guide](de/hand_wire.md) + * [ISP Flashing Guide](de/isp_flashing_guide.md) + * [ARM Debugging Guide](de/arm_debugging.md) + * [I2C Driver](de/i2c_driver.md) + * [GPIO Controls](de/internals_gpio_control.md) + * [Proton C Conversion](de/proton_c_conversion.md) + +* Für ein tieferes Verständnis + * [Wie Tastaturen funktionieren](de/how_keyboards_work.md) + * [QMK verstehen](de/understanding_qmk.md) + +* Andere Themen + * [Eclipse mit QMK](de/other_eclipse.md) + * [VSCode mit QMK](de/other_vscode.md) + * [Support](de/support.md) + * [Übersetzungen](de/translating.md) + +* QMK Internals (In Progress) + * [Defines](de/internals_defines.md) + * [Input Callback Reg](de/internals_input_callback_reg.md) + * [Midi Device](de/internals_midi_device.md) + * [Midi Device Setup Process](de/internals_midi_device_setup_process.md) + * [Midi Util](de/internals_midi_util.md) + * [Send Functions](de/internals_send_functions.md) + * [Sysex Tools](de/internals_sysex_tools.md) diff --git a/docs/de/driver_installation_zadig.md b/docs/de/driver_installation_zadig.md new file mode 100644 index 000000000..bd04e0543 --- /dev/null +++ b/docs/de/driver_installation_zadig.md @@ -0,0 +1,47 @@ +# Bootloader Treiber Installation mit Zadig + +QMK erscheint für den Host als normales HID Eingabegerät und benötigt deshalb keine zusätzlichen Treiber. Der Bootloader, den Du für das Flashen der Firmware benötigst, jedoch meistens schon. + +Hierzu gibt es zwei Ausnahmen: den Caterina Bootloader, meistens auf Pro Micros, sowie den HalfKay Bootloader auf PJRC Teensys. Diese erscheinen als serieller Port und als generisches HID Gerät und benötigen keine Treiber. + +Wir empfehlen deshalb [Zadig](https://zadig.akeo.ie/). Wenn Du die Entwicklungsumgebung mit MSYS2 oder WSL installiert hast, wird dich dass `qmk_install.sh` Skript gefragt haben, ob es die Treiber für dich installieren sollte. + +## Installation + +Versetze deine Tastatur in den Bootloader-Modus, entweder durch Betätigung des physischen `RESET` Schalters - meist auf der Unterseite der Platine - oder durch das Auslösen des Key-Codes `RESET` bzw. `KC_RESET` (sollte in der zur Tastatur gehörigen `keycode.c` zu entnehmen sein). Sollte deine Tastatur weder noch besitzen, versuche es damit die `Escape`-Taste oder `Leertaste + B` zu halten während Du die Tastatur mit dem PC verbindest (Siehe auch [Bootmagic](de/feature_bootmagic.md) für weitere Details). Ein paar Tastaturen benutzen das [Command](de/feature_command.md)-Feature an Stelle von Bootmagic; in diesem Fall kannst du mit den Tastenkombinationen `linkes Shift + rechtes Shift + B` oder `linkes Shift + rechtes Shift + Escape` zu jeder Zeit in den Bootloader wechseln solange die Tastatur verbunden ist. + +Eingie Tastaturen haben u.U. spezielle Anweisungen um in den Bootloader-Modus zu gelangen. Zum Beispiel kann die [Bootmagic-Lite](de/feature_bootmagic.md#bootmagic-lite)-Taste (default: Escape) auf eine andere Taste gemappt sein; oder die magische Kombination (default: linkes Shift+rechtes Shift) verwendet anstatt Shift die STRG-Tasten. Die zur Tastatur gehörige README sollte dir Aufschluss darüber geben wie der Bootloader-Modus ausgelöst werden kann wenn Du unsicher bist. + +Um ein Gerät mit USBaspLoader in den Bootloader-Modus zu versetzen, halte `BOOT` gedrückt während Du den `RESET`-Knopf drückst. +Alternativ, halte `BOOT` gedrückt während Du das USB-Kabel einsteckst. + +Zadig sollte das Bootloader-Gerät automatisch erkennen. Manchmal musst Du zusätzlich noch **Options → List All Devices** auswählen. + + - Tastaturen mit Atmel AVR MCUs sollten als `ATm32U4DFU` (oder ähnlich) angezeigt werden, mit der Vendor ID `03EB`. + - USBasp werden als `USBasp` angezeigt, mit VID/PID `16C0:05DC`. + - Tastaturen AVR controller und dem QMK-DFU Bootloader haben den namen `<Tastatur Name> Bootloader` und die VID `03EB`. + - Die meisten ARM Tastaturen werden als `STM32 BOOTLOADER` angezeigt, mit VID/PID `0483:DF11`. + +!> Sollte Zadig ein oder mehrere Geräte mit `HidUsb`-Treiber anzeigen, dann ist deine Tastatur wahrscheinlich nicht im Bootloader-Modus. Der Pfeil wird orange eingefärbt sein und Du wirst nach einer Bestätigung gefragt um Veränderungen am System vorzunehmen. In diesem Fall **fahre nicht fort**! + +Wenn der Pfeil grün angezeigt wird, wähle den Treiber aus und klicke auf **Treiber installieren**. Der `libusb-win32`-Treiber sollte gewöhnlich für AVR verwendet werden und `WinUSB` für ARM. Sollte es danach noch nicht möglich sein die Tastatur zu flashen, versuche es mit einem anderen Treiber. Für USBaspLoader Geräte, die über die Befehlszeile mit MSYS2 geflasht werden, wird der `libusbk`-Treiber empfohlen. Ansonsten sollte `libusb-win32` funktionieren wenn die QMK Toolbox verwendet wird. + + + +Entferne nun deine Tastatur und verbinde sie erneut um sicherzugehen dass der neue Treiber erfolgreich installiert wurde. Wenn Du QMK Toolbox benutzt, starte die Anwendung zur Sicherheit einmal neu, da Veränderungen am Treiber manchmal nicht richtig erkannt werden. Wenn dies immer noch nicht erfolgreich war hilft es an dieser Stelle manchmal ein Neustart des Computers. + +## Wiederherstellung einer Installation für ein falsches Gerät + +Wenn Du feststellst dass Du anschließend auf deiner Tastatur nicht mehr tippen kannst, ist etwas bei der Installation schief gelaufen. Ein häufiger Fehler ist es dass die Tastatur nicht im Bootloader-Modus war und stattdessen der Treiber für das HID-Gerät ersetzt wurde. Dies kannst Du einfach mit Zadig überprüfen, eine funktionierende Tastatur verwendet als Treiber `HidUsb` auf allen Interfaces . + + + +Öffne den Geräte-Manager und suche nach einem Gerät das wie deine Tastatur aussieht. + + + +Rechtsklick und **Gerät deinstallieren** anklicken. Bitte gehe sicher dass in diesem Schritt auch **Treibersoftware für dieses Gerät löschen** markiert ist. + + + +Klick **Aktion → Suche nach veränderter Hardware**. Nun solltest Du wieder in der Lage sein normal zu tippen. Vergewissere dich mit Hilfe von Zadig dass die Tastatur nun `HidUsb` als Treiber verwendet. Wenn dies der Fall ist sollte wieder alles funktionieren. diff --git a/docs/de/newbs.md b/docs/de/newbs.md new file mode 100644 index 000000000..61139a99e --- /dev/null +++ b/docs/de/newbs.md @@ -0,0 +1,22 @@ +# Anleitung für absolute Beginner +QMK ist eine mächtige Open Source Firmware für mechanische Tastaturen. Mit QMK kannst Du deine Tastatur sowohl sehr einfach als auch sehr umfangreich anpassen. Menschen unterschiedlichen Wissensstandes - vom kompletten Anfänger bis zum erfahrenen Programmierer - haben ihre Tastaturen mit QMK erfolgreich auf ihre persönlichen Bedürfnisse angepasst. Diese Anleitung soll Dir unabhängig von deinen Vorkenntnissen dabei helfen dies ebenfalls zu bewältigen. + +Bist Du unsicher ob deine Tastatur QMK unterstützt? Wenn es eine mechanische Tastatur ist, die Du selbst gebaut hast, stehen deine Chancen gut. Wir unterstützen eine [Vielzahl](https://qmk.fm/keyboards/) selbst gebauter Tastaturen, sodass selbst wenn deine jetzige Tastatur nicht unterstützt wird Du keine Probleme haben solltest eine für deine Anforderungen zu finden. + +## Übersicht + +Diese Anleitung ist in 7 Abschnitte unterteilt: + +* [Die ersten Schritte](newbs_getting_started.md) +* [Die erste Firmware auf der Kommandozeile erzeugen](newbs_building_firmware.md) +* [Die erste Firmware mit der Online GUI erzeugen](newbs_building_firmware_configurator.md) +* [Firmware flashen](newbs_flashing.md) +* [Testen und Debuggen](newbs_testing_debugging.md) +* [Git Leitfaden](newbs_best_practices.md) +* [Weitere hilfreiche Ressourcen für Anfänger](newbs_learn_more_resources.md) + +Diese Anleitung richtet sich an Personen, die vorher noch nie Software kompiliert haben. Die Entscheidungen und Empfehlungen basieren auf dieser Grundannahme. Es gibt unterschiedliche Herangehensweisen für viele der Prozeduren und wir unterstützen die meisten Alternativen. Wenn Du mal nicht weiter weißt oder Dir nicht sicher bist, wie Du an ein Problem herangehen sollst, kannst Du uns gerne [um Hilfe bitten](getting_started_getting_help.md). + +## Weitere Ressourcen + +* [Thomas Baart's QMK Basics Blog](https://thomasbaart.nl/category/mechanical-keyboards/firmware/qmk/qmk-basics/) – Ein äußerst hilfreicher Blog eines Community-Mitglieds, der einige Grundlagen der QMK-Firmware aus der Sicht des Benutzers erklärt (auf Englisch). diff --git a/docs/de/newbs_building_firmware.md b/docs/de/newbs_building_firmware.md new file mode 100644 index 000000000..b6d484024 --- /dev/null +++ b/docs/de/newbs_building_firmware.md @@ -0,0 +1,78 @@ +# Eine eigene Firmware erstellen + +Nachdem Du nun eine funktionierende Entwicklungsumgebung aufgesetzt hast, bist Du nun bereit, deine eigene Firmware zu erstellen. Dieses Sektion des Guides wird zwischen drei Programmen hin- und herwechseln: deinem Dateimanager, deinem Texteditor und der Befehlszeile. Lasse diese drei Fenster geöffnet, bis Du fertig und zufrieden mit deiner Tastatur-Firmware bist. + +Solltest Du die Befehlszeile zwischenzeitlich geschlossen haben, vergiss nicht wieder in das richtige Verzeichnis zu navigieren, benutze dazu den Befehl `cd qmk_firmware`. + +## Navigiere in deinen Keymap Ordner + +Beginne damit, in das `keymaps` Verzeichnis für deine Tastatur zu navigieren. + +Wenn Du macOS oder Windows benutzt, kannst Du einfach in das keymaps Verzeichnis wechseln. + +?> macOS:<br> + open keyboards/<keyboard_folder>/keymaps + +?> Windows:<br> + start .\\keyboards\\<keyboard_folder>\\keymaps + +## Eine Kopie der `default` Tastaturbelegung erstellen + +Wenn Du den `keymaps` Ordner geöffnet hast, solltest Du zuerst eine Kopie des `default` Verzeichnisses erstellen. Wir empfehlen dafür deinen GitHub Benutzernamen zu verweden, aber Du kannst auch jeden anderen Namen verwenden solange er nur aus Kleinbuchstaben, Zahlen und Unterstrichen besteht. + +Um den Prozess zu automatisieren kannst Du dazu auch das Skript `new_keymap.sh` verwenden. + +Navigiere dazu in das `qmk_firmware/util` Verzeichnis und gib folgenden Befehl ein: + +``` +./new_keymap.sh <keyboard path> <username> +``` + +Um zum Beispiel den Benutzernamen John für die Tastaturbelegung eines 1up60hse zu verwenden, würdest Du Folgendes eingeben: + +``` +./new_keymap.sh 1upkeyboards/1up60hse john +``` + +## Öffne `keymap.c` in deinem bevorzugtem Text Editor + +Öffne deine `keymap.c`. In dieser Datei findest Du die Strukturen, die das Verhalten deiner Tastatur bestimmen. Oben in der `keymap.c` befinden sich Definitionen (defines) und Aufzählungen (enums), die die Tastaturbelegung leserlicher machen sollen. Weiter unten wirst Du eine Zeile finden, die wie folgt aussieht: + + const uint16_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] = { + +Diese Zeile markiert den Anfang der Liste der Ebenen (Layers). Darunter befinden sich Zeilen die entweder `LAYOUT` oder `KEYMAP` enthalten, das deutet auf den Start einer Ebene hin. Danach folgt eine Liste von Tasten, die dieser Ebene zugewiesen sind. + +!> Beim Bearbeiten einer Tastaturbelegung solltest Du darauf achten, keine Kommata hinzuzufügen oder zu entfernen. Ansonsten kann dies dazu führen, dass deine Firmware nicht mehr kompiliert und es ist nicht immer einfach festzustellen, wo genau ein Komma zuviel oder zu wenig ist. Die letzte Zeile hat am Ende kein Komma, die Zeilen davor jedoch schon. + +## Personalisiere die Tastaturbelegung nach deinen Wünschen + +Wie Du diesen Schritt abschließt ist vollkommen Dir überlassen. Ändere die eine Sache die Dich stört oder verändere alles von Grund auf. Du kannst Ebenen entfernen die Du nicht brauchst oder Neue hinzufügen, bis zu 32 Stück. Die folgende Dokumentation verrät Dir was Du hier alles definieren kannst: + +* [Keycodes](de/keycodes.md) +* [Features](de/features.md) +* [FAQ](de/faq.md) + +?> Während Du langsam ein Gefühl dafür kriegst wie Keymaps funktionieren, solltest Du darauf achten nicht zuviel auf einmal zu verändern. Größere Änderungen machen es schwieriger, Probleme zu debuggen. + +## Deine Firmware erzeugen + +Wenn Du damit fertig bist, deine Tastaturbelegung anzupassen, musst Du noch die Firmware erzeugen. Öffne dazu wieder die Befehlszeile und führe folgenden Befehl aus: + + make <my_keyboard>:<my_keymap> + +Wenn deine Tastaturbelegung z.B. "xyverz" heißt und Du die Belegung für ein rev5 planck erzeugen möchtest, lautet der Befehl: + + make planck/rev5:xyverz + +Während des Kompiliervorgangs wird viel Text auf dem Bildschirm ausgegeben. Es sollte am Ende mit etwas enden das ungefähr so aussieht: + +``` +Linking: .build/planck_rev5_xyverz.elf [OK] +Creating load file for flashing: .build/planck_rev5_xyverz.hex [OK] +Copying planck_rev5_xyverz.hex to qmk_firmware folder [OK] +Checking file size of planck_rev5_xyverz.hex [OK] + * File size is fine - 18392/28672 +``` + +## Deine Firmware flashen +Bitte fahre mit [Firmware flashen](de/newbs_flashing.md) fort, um zu erfahren, wie Du deine neue Firmware auf deine Tastatur flashen kannst. diff --git a/docs/de/newbs_flashing.md b/docs/de/newbs_flashing.md new file mode 100644 index 000000000..940438669 --- /dev/null +++ b/docs/de/newbs_flashing.md @@ -0,0 +1,369 @@ +# Deine Tastatur flashen + +Nachdem deine Firmware nun fertig ist musst Du Sie noch auf deine Tastatur flashen. + +## Flash-Vorgang mit QMK Toolbox + +Der einfachste Weg deine Tastatur zu flashen ist mit Hilfe der [QMK Toolbox](https://github.com/qmk/qmk_toolbox/releases) + +Leider ist die QMK Toolbox derzeit nur für Windows und macOS verfügbar. Wenn Du Linux benutzt (oder es vorziehst die Firmware mit der Kommandozeile zu flashen) solltest Du die Methode benutzen die [hier](de/newbs_flashing.md#tastatur-mit-der-befehlszeile-flashen) beschrieben wird. + +### Lade die Datei in QMK Toolbox + +Beginne damit die Datei in der QMK Toolbox Anwendung zu laden. Versichere dich dass Du die Firmware-Datei im Finder oder Explorer findest. Deine Tastatur-Firmware sollte entweder vom Typ `.hex` oder `.bin` sein sein. QMK sollte die für deine Tastatur entsprechende Datei automatisch in das Root-Verzeichnis (normalerweise `qmk_firmware`) kopieren. + +?> Wenn Du Windows oder macOS benutzt kannst Du mit folgenden Befehlen ganz einfach das aktuelle Firmware-Verzeichnis im Explorer oder Finder öffnen. + +#### Windows: + +``` start . ``` + +#### macOS: + +``` open . ``` + +Die Firmware-Dateien folgen dabei immer folgendem Schema: + + <meine_Tastatur>_<meine_Tastaturbelegung>.{bin,hex} + +Zum Beispiel würde ein `planck/rev5` mit der `default` Tastaturbelegung folgenden Dateinamen haben: + + planck_rev5_default.hex + +Wenn Du die Firmware-Datei gefunden hast kannst Du sie in das "Local file" ("Lokale Datei") Feld in der QMK Toolbox ziehen, alternativ kannst Du auf "Öffnen" klicken und in das Verzeichnis navigieren indem sich die Firmware-Datei befindet. + +### Die Tastatur in den DFU (Bootloader) Modus versetzen + +Um deine angepasste Firmware auf deine Tastatur zu flashen musst Du diese erst in einen speziellen "flashing"-Modus versetzen. Während die Tastatur in diesem Modus ist kannst Du nicht auf ihr tippen oder sie wie gewohnt als Tastatur benutzen. Es ist wichtig dass der flashing-Prozesses nicht unterbrochen oder die Tastatur ausstöpselst wird, da der Vorgang ansonst wiederholt werden muss. + +Verschiedene Tastaturen verwenden unterschiedliche Methoden um in den Bootloader-Modus zu gelangen. Wenn dein PCB im Moment QMK oder TMK verwendet und Du keine spezifischen Anweisungen erhalten hast probiere die folgenden Methoden in dieser Reihenfolge: + +* Halte beide Shift-Tasten und drücke `Pause` +* Halte beide Shift-Tasten und drücke `B` +* Entferne deine Tastatur vom Computer, drücke gleichzeitig `Leertaste` und `B`, verbinde die Tastatur wieder mit dem Computer und warte eine Sekunde bevor Du die Tasten wieder loslässt. +* Drücke den physischen `RESET`-Knopf auf der Unterseite des PCBs +* Suche auf dem PCB den Pin mit dem Label `RESET`, verbinde diesen mit deinem GND-Pin +* Suche auf dem PCB den Pin mit dem Label `BOOT0`, verbinde diesen mit GND und schließe die Tastatur wieder an den PC an TODO: DIS IS DANGEROUS!! + +Wenn Du damit erfolgreich warst solltest Du in der QMK Toolbox eine Nachricht sehen die ungefähr so aussieht: + +``` +*** Clueboard - Clueboard 66% HotSwap disconnected -- 0xC1ED:0x2390 +*** DFU device connected +``` + +### Tastatur flashen + +Klicke auf den `Flash`-Knopf in der QMK Toolbox. Die Ausgabe wird ungefähr so aussehen: + +``` +*** Clueboard - Clueboard 66% HotSwap disconnected -- 0xC1ED:0x2390 +*** DFU device connected +*** Attempting to flash, please don't remove device +>>> dfu-programmer atmega32u4 erase --force + Erasing flash... Success + Checking memory from 0x0 to 0x6FFF... Empty. +>>> dfu-programmer atmega32u4 flash qmk_firmware/clueboard_66_hotswap_skully.hex + Checking memory from 0x0 to 0x55FF... Empty. + 0% 100% Programming 0x5600 bytes... + [>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>] Success + 0% 100% Reading 0x7000 bytes... + [>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>] Success + Validating... Success + 0x5600 bytes written into 0x7000 bytes memory (76.79%). +>>> dfu-programmer atmega32u4 reset + +*** DFU device disconnected +*** Clueboard - Clueboard 66% HotSwap connected -- 0xC1ED:0x2390 +``` + +## Tastatur mit der Befehlszeile flashen + +Zunächst solltest Du versuchen herauszufinden welchen Bootlader deine Tastatur benutzt. Diese vier Bootloader sind am Weitesten verbreitet: + +| MCU | Bootloader | +| --- | --- | +| Pro-Micro und Klone | CATERINA | +| Teensy | Halfkay | +| OLKB Boards | QMK-DFU | +| sonstige atmega32u4 | DFU | + +Auf der Seite [Flash Anleitung und Bootloader Informationen](de/flashing.md) kannst Du mehr über das Thema erfahren. + +Wenn Du weißt welchen Bootloader deine Tastaur verwendet, kannst Du diese Information bei der Kompilation hinzufügen um den Flash-Vorgang mit dem `make`-Befehl zu automatisieren. +```rules.mk +... +BOOTLOADER = caterina +... +``` + +### DFU + +Wenn Du den DFU-Bootloader verwendest und Du bereit bist deine Firmware zu kompilieren und zu flashen, öffne ein Befehlszeile und führe folgenden Befehl aus: + + make <meine_Tastatur>:<meine_Tastaturbelegung>:dfu + +Wenn deine Tastaturbelegung z.B den Namen "xzverz" trägt und Du ein rev5 planck flashen möchtest sähe der Befehl wie folgt aus: + + make planck/rev5:xyverz:dfu + + +Nachdem der Vorgang abgeschlossen ist sollte die Ausgabe ungefähr so aussehen: + +``` +Linking: .build/planck_rev5_xyverz.elf [OK] +Creating load file for flashing: .build/planck_rev5_xyverz.hex [OK] +Copying planck_rev5_xyverz.hex to qmk_firmware folder [OK] +Checking file size of planck_rev5_xyverz.hex + * File size is fine - 18574/28672 + ``` + +Wenn dieser Punkt erreicht ist wird das Build-Skript alle 5 Sekunden nach einem DFU Bootloader suchen. Dieser Vorgang wird wiederholt bis er erfolgreich ist oder abgebrochen wird. + + dfu-programmer: no device present. + Error: Bootloader not found. Trying again in 5s. + +Wenn diese Nachricht erscheint konnte das Build-Skript den Controller nicht eigenständig in den DFU Modus versetzen (z.B. weil der Modus in rules.mk falsch gesetzt wurde oder ein Problem mit der Hardware besteht), wenn dies eintritt musst Du die oben beschrieben Schritte benutzen um den Controller in den DFU Modus zu versetzen. Danach sollte die Ausgabe ungefähr so aussehen: + +``` +*** Attempting to flash, please don't remove device +>>> dfu-programmer atmega32u4 erase --force + Erasing flash... Success + Checking memory from 0x0 to 0x6FFF... Empty. +>>> dfu-programmer atmega32u4 flash qmk_firmware/clueboard_66_hotswap_skully.hex + Checking memory from 0x0 to 0x55FF... Empty. + 0% 100% Programming 0x5600 bytes... + [>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>] Success + 0% 100% Reading 0x7000 bytes... + [>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>] Success + Validating... Success + 0x5600 bytes written into 0x7000 bytes memory (76.79%). +>>> dfu-programmer atmega32u4 reset +``` + +?> Wenn Du mit diesem Schritt Probleme hast (z.B. `dfu-programmer: no device present`) hilft dir hoffentlich der Abschnitt [Häufig gestellte Fragen (Build/Kompilieren)](de/faq_build.md). + +#### DFU Befehle + +Es gibt verschiedene DFU Befehle um die Firmware auf ein DFU Gerät zu flashen: + +* `:dfu` - Dies ist die default Option. Es wird gecheckt ob ein DFU Gerät verfügbar ist, ist dies der Fall wird die Firmware geflasht. Dieser Check wird alle 5 Sekunden ausgeführt bis ein DFU Gerät erkannt wird. +* `:dfu-ee` - Der Flash-Vorgang benutzt eine `.eep` Datei anstatt einer `.hex` Datei. Dies ist eher unüblich. +* `:dfu-split-left` - Dies flasht die Firmware wie gewohnt (`:dfu`). Allerdings nur die "linke Seite" der EEPROM für geteilte Tastaturen. _Dies ist ideal für auf Elite C basierenden geteilten Tastaturen._ +* `:dfu-split-right` - Dies flasht die Firmware wie gewohnt (`:dfu`). Allerdings nur die "rechte Seite" der EEPROM für geteilte Tastaturen. _Dies ist ideal für auf Elite C basierenden geteilten Tastaturen._ + + +### Caterina +Für Arduinos und andere ProMicro Klone (z.B. SparkFun ProMicro), wenn Du bereit bist zu kompilieren und die Tastatur zu flashen, öffne ein Befehlszeilen-Fenster und führe den Build-Befehl aus: + + make <meine_Tastatur>:<meine_Tastaturbelegung>:avrdude + +Wenn deine Tastaturbelegung zum Beispiel den Namen "xyverz" hat und Du eine Tastaturbelegung für ein "rev2 Lets Split" erzeugen möchtest, lautet der Befehl dafür: + + make lets_split/rev2:xyverz:avrdude + +Nachdem die Kompilation abgeschlossen ist sollte die Ausgabe ungefähr so aussehen: + +``` +Linking: .build/lets_split_rev2_xyverz.elf [OK] +Creating load file for flashing: .build/lets_split_rev2_xyverz.hex [OK] +Checking file size of lets_split_rev2_xyverz.hex [OK] + * File size is fine - 27938/28672 +Detecting USB port, reset your controller now.............. +``` + +Nun wird die Tastatur automatisch zurückgesetzt und das Skript wird die Firmware flashen sobald es den Bootloader erkennt. Die Ausgabe sollte ungefähr so aussehen: + +``` +Detected controller on USB port at /dev/ttyS15 + +Connecting to programmer: . +Found programmer: Id = "CATERIN"; type = S + Software Version = 1.0; No Hardware Version given. +Programmer supports auto addr increment. +Programmer supports buffered memory access with buffersize=128 bytes. + +Programmer supports the following devices: + Device code: 0x44 + +avrdude.exe: AVR device initialized and ready to accept instructions + +Reading | ################################################## | 100% 0.00s + +avrdude.exe: Device signature = 0x1e9587 (probably m32u4) +avrdude.exe: NOTE: "flash" memory has been specified, an erase cycle will be performed + To disable this feature, specify the -D option. +avrdude.exe: erasing chip +avrdude.exe: reading input file "./.build/lets_split_rev2_xyverz.hex" +avrdude.exe: input file ./.build/lets_split_rev2_xyverz.hex auto detected as Intel Hex +avrdude.exe: writing flash (27938 bytes): + +Writing | ################################################## | 100% 2.40s + +avrdude.exe: 27938 bytes of flash written +avrdude.exe: verifying flash memory against ./.build/lets_split_rev2_xyverz.hex: +avrdude.exe: load data flash data from input file ./.build/lets_split_rev2_xyverz.hex: +avrdude.exe: input file ./.build/lets_split_rev2_xyverz.hex auto detected as Intel Hex +avrdude.exe: input file ./.build/lets_split_rev2_xyverz.hex contains 27938 bytes +avrdude.exe: reading on-chip flash data: + +Reading | ################################################## | 100% 0.43s + +avrdude.exe: verifying ... +avrdude.exe: 27938 bytes of flash verified + +avrdude.exe: safemode: Fuses OK (E:CB, H:D8, L:FF) + +avrdude.exe done. Thank you. +``` +Sollten dabei Probleme auftreten (z.B. "Zugriff verweigert" / "Permission denied") muss der Make-Befehl mit privilegierten Berechtigungen ausgeführt werden: + + sudo make <meine_Tastatur>:<meine_Tastaturbelegung>:avrdude + +Zusätzlich ist es möglich mehrere Tastaturen in einem Vorgang zu flashen: + + make <keyboard>:<keymap>:avrdude-loop + +Du kannst den Loop mit STRG + C unterbrechen sobald der Vorgang abgeschlossen ist. Die korrekte Tastenkombination kann abweichen und hängt vom Betriebssystem ab. + + +### HalfKay + +Für Tastaturen mit PJRC Controllern (Teensy's), wenn Du bereit bist zu kompilieren und die Tastatur zu flashen, öffne ein Befehlszeilen-Fenster und führe den Build-Befehl aus: + + make <meine_Tastatur>:<meine_Tastaturbelegung>:teensy + +Wenn deine Tastaturbelegung zum Beispiel den Namen "xyverz" hat und Du eine Tastaturbelegung für ein Ergodox oder Ergodox EZ erzeugen möchtest, lautet der Befehl dafür: + + make ergodox_ez:xyverz:teensy + +Nachdem die Kompilation abgeschlossen ist sollte die Ausgabe ungefähr so aussehen: + +``` +Linking: .build/ergodox_ez_xyverz.elf [OK] +Creating load file for flashing: .build/ergodox_ez_xyverz.hex [OK] +Checking file size of ergodox_ez_xyverz.hex [OK] + * File size is fine - 25584/32256 + Teensy Loader, Command Line, Version 2.1 +Read "./.build/ergodox_ez_xyverz.hex": 25584 bytes, 79.3% usage +Waiting for Teensy device... + (hint: press the reset button) + ``` + +An diesem Punkt solltest Du die Tastatur zurücksetzen um den Flash-Vorgang auszulösen. Wenn dies abgeschlossen ist sollte die Ausgabe ungefähr so aussehen: + + ``` +Found HalfKay Bootloader +Read "./.build/ergodox_ez_xyverz.hex": 28532 bytes, 88.5% usage +Programming............................................................. +................................................... +Booting +``` + +### BootloadHID + +Für auf Bootmapper Client(BMC)/bootloaderHID/ATmega32A basierende Tastaturen, wenn Du bereit bist zu kompilieren und die Tastatur zu flashen, öffne ein Befehlszeilen-Fenster und führe den Build-Befehl aus: + + make <meine_Tastatur>:<meine_Tastaturbelegung>:bootloaderHID + +Wenn deine Tastaturbelegung zum Beispiel den Namen "xyverz" hat und Du eine Tastaturbelegung für ein jj40 erzeugen möchtest, lautet der Befehl dafür: + + make jj40:xyverz:bootloaderHID + +Nachdem die Kompilation abgeschlossen ist sollte die Ausgabe ungefähr so aussehen: + +``` +Linking: .build/jj40_default.elf [OK] +Creating load file for flashing: .build/jj40_default.hex [OK] +Copying jj40_default.hex to qmk_firmware folder [OK] +Checking file size of jj40_default.hex [OK] + * The firmware size is fine - 21920/28672 (6752 bytes free) +``` + +Wenn dieser Punkt erreicht ist wird das Build-Skript alle 5 Sekunden nach einem DFU Bootloader suchen. Dieser Vorgang wird wiederholt bis er erfolgreich ist oder abgebrochen wird. + +``` +Error opening HIDBoot device: The specified device was not found +Trying again in 5s. +``` + +An diesem Punkt solltest Du die Tastatur zurücksetzen um den Flash-Vorgang auszulösen. Wenn dies abgeschlossen ist sollte die Ausgabe ungefähr so aussehen: + +``` +Page size = 128 (0x80) +Device size = 32768 (0x8000); 30720 bytes remaining +Uploading 22016 (0x5600) bytes starting at 0 (0x0) +0x05580 ... 0x05600 +``` + +### STM32 (ARM) + +Für die meisten ARM Tastaturen (inkl. Proton C, Planck Rev 6 und Preonic Rev 3), wenn Du bereit bist zu kompilieren und die Tastatur zu flashen, öffne ein Befehlszeilen-Fenster und führe den Build-Befehl aus: + + make <meine_Tastatur>:<meine_Tastaturbelegung>:dfu-util + +Wenn deine Tastaturbelegung zum Beispiel den Namen "xyverz" hat und Du eine Tastaturbelegung für ein Planck Revision 6 erzeugen möchtest, benutze dafür den folgenden Befehl und reboote die Tastatur in den Bootloader (kurz bevor der Kompiliervorgang abgeschlossen ist): + + make planck/rev6:xyverz:dfu-util + +Nachdem der Kompiliervorgang abgeschlossen ist sollte die Ausgabe ungefähr so aussehen: + +Für auf Bootmapper Client(BMC)/bootloaderHID/ATmega32A basierende Tastaturen, wenn Du bereit bist zu kompilieren und die Tastatur zu flashen, öffne ein Befehlszeilen-Fenster und führe den Build-Befehl aus: + + make <meine_Tastatur>:<meine_Tastaturbelegung>:bootloaderHID + +Wenn deine Tastaturbelegung zum Beispiel den Namen "xyverz" hat und Du eine Tastaturbelegung für ein jj40 erzeugen möchtest, lautet der Befehl dafür: +``` +Linking: .build/planck_rev6_xyverz.elf [OK] +Creating binary load file for flashing: .build/planck_rev6_xyverz.bin [OK] +Creating load file for flashing: .build/planck_rev6_xyverz.hex [OK] + +Size after: + text data bss dec hex filename + 0 41820 0 41820 a35c .build/planck_rev6_xyverz.hex + +Copying planck_rev6_xyverz.bin to qmk_firmware folder [OK] +dfu-util 0.9 + +Copyright 2005-2009 Weston Schmidt, Harald Welte and OpenMoko Inc. +Copyright 2010-2016 Tormod Volden and Stefan Schmidt +This program is Free Software and has ABSOLUTELY NO WARRANTY +Please report bugs to http://sourceforge.net/p/dfu-util/tickets/ + +Invalid DFU suffix signature +A valid DFU suffix will be required in a future dfu-util release!!! +Opening DFU capable USB device... +ID 0483:df11 +Run-time device DFU version 011a +Claiming USB DFU Interface... +Setting Alternate Setting #0 ... +Determining device status: state = dfuERROR, status = 10 +dfuERROR, clearing status +Determining device status: state = dfuIDLE, status = 0 +dfuIDLE, continuing +DFU mode device DFU version 011a +Device returned transfer size 2048 +DfuSe interface name: "Internal Flash " +Downloading to address = 0x08000000, size = 41824 +Download [=========================] 100% 41824 bytes +Download done. +File downloaded successfully +Transitioning to dfuMANIFEST state +``` + +#### STM32 Befehle + +Für Tastaturen mit STM32 Controller sind die DFU Befehle wie folgt: + +* `:dfu-util` - The default command for flashing to STM32 devices. +* `:dfu-util` - Der Standard-Befehl für STM32 Geräte. +* `:dfu-util-wait` - Funktioniert wie der Standard-Befehl, aber mit einem 10 Sekunden Timeout bevor erneut versucht wird die Firmware zu flashen. Mit dem Parameter `TIME_DELAY=20` auf der Befehlszeile kann der Timeout beeinflusst werden. + * z.B.: `make <meine_Tastatur>:<meine_Tastaturbelegung>:dfu-util TIME_DELAY=5` +* `:dfu-util-split-left` - Gleiche Funktionsweise wie `dfu-util`, jedoch wird zusätzlich das EEPROM Setting "linke Seite" für geteilte Tastaturen gesetzt. +* `:dfu-util-split-right` - Gleiche Funktionsweise wie `dfu-util`, jedoch wird zusätzlich das EEPROM Setting "rechte Seite" für geteilte Tastaturen gesetzt. + +## Probier's aus! + +Herzlichen Glückwunsch! Deine individuell angepasst Firmware wurde auf deine Tastatur übertragen! + + Probiere deine neue Tastatur aus und gehe sicher dass alles wie gewünscht funktioniert. Wir haben einen weiteren Artikel zum Thema [Testen und Debuggen](de/newbs_testing_debugging.md) verfasst der sich mit Problembeseitigung beschäftigt um den Beginnger-Guide abzuschließen. diff --git a/docs/de/newbs_getting_started.md b/docs/de/newbs_getting_started.md new file mode 100644 index 000000000..8240f2baf --- /dev/null +++ b/docs/de/newbs_getting_started.md @@ -0,0 +1,101 @@ +# Einleitung +Genau wie in einem Computer befindet sich auch in einer Tastatur ein Prozessor. + +Dieser Prozessor führt Software aus, die registriert wenn Tasten gedrückt bzw. wieder losgelassen werden und leitet die entsprechenden Signale an den Computer weiter. + +QMK übernimmt die Rolle dieser Software und teilt dem Host-Computer den aktuellen Zustand der Tastatur mit. Wenn Du eine Tastaturbelegung definierst, ist dies äquivalent zu einem ausführbarem Programm, das auf deiner Tastatur läuft. + +QMK möchte seine BenutzerInnen in die Lage versetzen, simple Aufgaben möglichst einfach zu gestalten und gleichzeitig komplexe Dinge zu ermöglichen, die mit normalen Tastaturen ohne zusätzliche Software undenkbar wären. Du musst nicht programmieren können, um abgefahrene Tastaturbelegungen zu gestalten - es reicht wenn Du eine Idee hast und ein paar einfache syntaktische Regeln verstehen kannst. + +# Los geht's! +Bevor Du damit loslegen kannst, deine Tastaturbelegung zu erstellen, musst Du ein wenig Software installieren und Dir eine Entwicklungsumgebung aufsetzen. Die gute Nachricht ist, dass das nur einmal erledigt werden muss, egal für wie viele verschiedene Tastaturen Du hinterher Firmware entwickeln willst. + +Wenn Du es vorziehst mit einer grafischen Oberfläche zu entwickeln kannst Du auch dazu gerne direkt mit dem online [QMK Konfigurator](https://config.qmk.fm) loslegen. Siehe auch: [Firmware mit der Online GUI erzeugen](de/newbs_building_firmware_configurator.md) + +## Software herunterladen + +### Text Editor + +Du wirst ein Programm benötigen, mit dem Du **plain text** (= reiner Text) Dateien bearbeiten und speichern kannst. Wenn Du Windows benutzt, reicht dafür schon das normale `Notepad` und für Linux z.B. `gedit` oder `leafpad`. Beide sind sehr rudimentäre Editoren deren Funktionsumfang aber vollkommen ausreicht. Für macOS' standard `TextEdit` muss man ein bisschen vorsichtig sein und darauf achten, beim Speichern explizit unter _Format_ die Option _Reiner Text_ auszuwählen. + +Ansonsten ist es empfehlenswert, einen Editor herunterzuladen der für die Programmierung und das Bearbeiten von Code ausgelegt ist wie z.b [Notepad++](http://notepad-plus-plus.org/), [Sublime Text](https://www.sublimetext.com/) oder [VS Code](https://code.visualstudio.com/). + +?> Immer noch unsicher, welcher Text Editor der Richtige für Dich ist? Laurence Bradford hat eine hervorragende [Einleitung](https://learntocodewith.me/programming/basics/text-editors/) zu dem Thema geschrieben (auf Englisch). + +### QMK Toolbox + +QMK Toolbox ist ein optionales grafisches Programm für Windows und macOS, das es erleichtern soll, deine Tastatur zu programmieren und zu debuggen. Du wirst es höchstwahrscheinlich früher oder später als unverzichtbar ansehen, wenn es darum geht eine Tastatur einfach zu flashen oder zu debuggen, da es ermöglicht, sich debug-Nachrichten direkt anzeigen zu lassen. + +[Hier kannst Du die aktuelle Version herunterladen.](https://github.com/qmk/qmk_toolbox/releases/latest) + +* Für Windows: `qmk_toolbox.exe` (portable) oder `qmk_toolbox_install.exe` (installer) +* Für macOS: `QMK.Toolbox.app.zip` (portable) oder `QMK.Toolbox.pkg` (installer) + +## Die Entwicklungsumgebung aufsetzen + + +Wir haben versucht, die Installation der Entwicklungsumgebung für QMK so einfach wie möglich zu gestalten. Alles, was Du tun musst, ist eine Linux oder Unix Umgebung aufzusetzen, danach macht QMK den Rest. + +?> Wenn Du das erste Mal mit der Linux/Unix Befehlszeile arbeitest, schadet es nicht, sich mit ein paar Grundlagen und Befehlen vertraut zu machen. Diese Ressourcen sollten ausreichen, um sich das Nötigste anzueignen um mit QMK arbeiten zu können:<br> +[Erforderliche Linux Grundlagen](https://www.guru99.com/must-know-linux-commands.html)<br> +[Noch ein paar Linux Befehle](https://www.tjhsst.edu/~dhyatt/superap/unixcmd.html) + +### Windows + +Du wirst MSYS2 (o.Ä.) und Git benötigen. + +* Befolge die Installationsanleitung auf der [MSYS2 Homepage](http://www.msys2.org) +* Schließe alle offenen MSYS2 Fenster und öffne ein neues MSYS2 MinGW 64-bit Terminal +* Installiere Git mit dem Kommando: `pacman -S git` + +### macOS + +Du wirst Homebrew benötigen. Folge dafür den Anweisungen auf der [Homebrew homepage](https://brew.sh). + +Nachdem Homebrew erfolgreich installiert ist, kannst Du mit _QMK aufsetzen_ fortfahren. + +### Linux + +Du benötigst Git, aber es ist ziemlich wahrscheinlich, dass es bereits installiert ist. Sollte dies nicht der Fall sein, kannst Du es mit dem folgenden Aufruf installieren: + +* Debian / Ubuntu / Devuan: `apt-get install git` +* Fedora / Red Hat / CentOS: `yum install git` +* Arch Linux: `pacman -S git` + +?> Docker ist ebenfalls eine Option für alle Plattformen. [Hier](de/getting_started_build_tools.md#docker) kannst Du dazu weitere Informationen finden. + +## QMK aufsetzen +Wenn Du damit fertig bist, deine Linux/Unix Umgebung zu installieren, kannst Du damit fortfahren QMK herunterzuladen. Dafür werden wir mit Git das QMK Repository "klonen". Öffne ein Terminal oder ein MSYS2 MinGW Fenster, dies wirst Du für den Rest der Anleitung benötigen. In diesem Fenster rufst Du nun die beiden folgenden Kommandos auf: + +```shell +git clone --recurse-submodules https://github.com/qmk/qmk_firmware.git +cd qmk_firmware +``` +?> Wenn Du bereits weißt, [wie man GitHub benutzt](de/getting_started_github.md), empfehlen wir, dass Du Dir ein eigenen Fork erstellst. Wenn Du nicht weißt, was das bedeuten soll, kannst Du diesen Ratschlag getrost ignorieren. + +QMK liefert ein Script mit, das helfen soll, Dir alles Weitere abzunehmen. Du kannst es mit dem folgenden Befehl aufrufen: + + util/qmk_install.sh + +## Die Build-Umgebung testen + +Nun sollte hoffentlich alles Nötige für eine funktionierende QMK Build-Umgebung installiert sein und Du solltest in der Lage sein, die QMK-Firmware zu kompilieren. Um dies mit einer `default` Tastaturbelegung zu testen, kannst Du den folgenden Befehl ausprobieren: + + make <keyboard>:default + +Der Befehl um z.B. die Firmware für ein _Clueboard 66%_ zu erzeugen lautet: + + make clueboard/66/rev3:default + +Wenn es fertig ist, sollte der Output ungefähr so ähnlich wie das Folgende aussehen: + +``` +Linking: .build/clueboard_66_rev3_default.elf [OK] +Creating load file for flashing: .build/clueboard_66_rev3_default.hex [OK] +Copying clueboard_66_rev3_default.hex to qmk_firmware folder [OK] +Checking file size of clueboard_66_rev3_default.hex [OK] + * The firmware size is fine - 26356/28672 (2316 bytes free) +``` + +# Eine eigene Tastaturbelegung erstellen +Du bist nun fertig mit dem Setup der Entwicklungsumgebung und solltest somit in der Lage sein, deine eigenen Tastaturbelegungen zu erstellen. Um fortzufahren, folge bitte der nächsten Anleitung unter [Die erste Firmware](de/newbs_building_firmware.md). diff --git a/docs/de/newbs_learn_more_resources.md b/docs/de/newbs_learn_more_resources.md new file mode 100644 index 000000000..59b72152d --- /dev/null +++ b/docs/de/newbs_learn_more_resources.md @@ -0,0 +1,14 @@ +# Lernmaterial + +Diese weiterführenden Ressourcen sind darauf ausgerichtet, Neulingen der QMK Commmunity mehr Informationen und ein besseres Verständnis zu einzelnen Themen zu bieten. + +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 Git im Bezug zu QMK](contributing.md) + +Mehr über die Arbeit mit der Befehlszeile: + +* [Gutes allgemeines Tutorial über die Arbeit mit der Befehlszeile](https://www.codecademy.com/learn/learn-the-command-line) (auf Englisch) diff --git a/docs/de/newbs_testing_debugging.md b/docs/de/newbs_testing_debugging.md new file mode 100644 index 000000000..acc067e10 --- /dev/null +++ b/docs/de/newbs_testing_debugging.md @@ -0,0 +1,100 @@ +# Testen und Debuggen + +Nachdem Du deine Tastatur mit deiner angepassten Firmware geflasht hast, ist es nun an der Zeit sie auszuprobieren. Mit ein bisschen Glück sollte alles ohne Probleme funktionieren, wenn dies nicht der Fall ist, soll dieses Dokument dir dabei helfen, herauszufinden wo das Problem liegt. + +## Testen + +Die Tastatur zu testen ist relativ selbsterklärend. Drücke jede der Tasten um dich zu versichern, dass der gesendete Keyode der ist, den du erwarten würdest. Dafür gibt es sogar ein paar Programme die helfen sollen, dass keine Taste ausgelassen wurde. + +Anmerkung: Diese Programme werden weder von QMK bereitgestellt oder gutgeheißen. + +* [Switch Hitter](https://elitekeyboards.com/switchhitter.php) (Nur für Windows) +* [Keyboard Viewer](https://www.imore.com/how-use-keyboard-viewer-your-mac) (Nur für Mac) +* [Keyboard Tester](http://www.keyboardtester.com) (Web basiert) +* [Keyboard Checker](http://keyboardchecker.com) (Web basiert) + +## Debuggen + +Deine Tastatur wird Debug Informationen liefern wenn Du `CONSOLE_ENABLE = yes` in deiner `rules.mk` gesetzt hast. Die default-Ausgabe ist sehr beschränkt und kann wenn nötig durch die Aktivierung des Debug-Modes erhöht werden. Benutze dafür entweder den `DEBUG` Keycode in deiner Tastaturbelegung, das [Command](de/feature_command.md)-Feature oder füge den folgenden Code zu deiner Tastaturbelegung hinzu. + +```c +void keyboard_post_init_user(void) { + // Customise these values to desired behaviour + debug_enable=true; + debug_matrix=true; + //debug_keyboard=true; + //debug_mouse=true; +} +``` + +### Debuggen mit der QMK Toolbox + +Für kompatible Plattformen kann die [QMK Toolbox](https://github.com/qmk/qmk_toolbox) benutzt werden um Debug-Nachrichten deiner Tastatur anzuzeigen. + +### Debuggen mit hid_listen + +Bevorzugst Du es lieber auf der Befehlszeile zu debuggen? Dafür eignet sich das Programm [hid_listen](https://www.pjrc.com/teensy/hid_listen.html) von PJRC. Binaries sind für Windows, Linux und MacOS verfügbar. + +<!-- FIXME: Describe the debugging messages here. --> + +## Eigene Debug-Nachrichten senden + +Manchmal ist es hilfreich Debug-Nachrichten innerhalb deines eigenen [Custom Codes](de/custom_quantum_functions.md) zu drucken. Das ist ziemlich einfach. Beginne damit `print.h` am Anfang deiner Datei zu inkludieren: + + #include <print.h> + +Danach stehen dir verschiedene Druck-Funktionen zur Verfügung: + +* `print("string")`: Druckt einen simplen String +* `uprintf("%s string", var)`: Druckt einen formatierten String +* `dprint("string")` Druckt einen simplen String, aber nur wenn der Debug-Mode aktiviert ist +* `dprintf("%s string", var)`: Druckt einen formatierten String, aber nur wenn der Debug-Mode aktiviert ist + +## Debug Beispiele + +Anbei findest Du eine Sammlung von hilfreichen Beispielen. Für weitere Informationen Informationen sei an dieser Stelle auf [Debugging/Troubleshooting QMK](de/faq_debug.md) verwiesen. + +### Which matrix position is this keypress? +### Welche Matrix Position hat dieser Tastenanschlag + +Beim Portieren, oder bei der Fehlerdiagnose von PCB Problemen, ist es nützlich sich anzeigen zu lassen ob ein Tastenanschlag richtig erkannt wurde. Um die Protokollierung für diesen Fall zu aktivieren, füge bitte folgenden Code zu deiner Tastaturbelegung `keymap.c` hinzu. + +```c +bool process_record_user(uint16_t keycode, keyrecord_t *record) { + // Wenn 'console' aktiviert ist wird die Matrix-Position und der Status jedes Tastenanschlags ausgegeben +#ifdef CONSOLE_ENABLE + uprintf("KL: kc: %u, col: %u, row: %u, pressed: %u\n", keycode, record->event.key.col, record->event.key.row, record->event.pressed); +#endif + return true; +} +``` + +Beispiel Ausgabe: +```text +Waiting for device:....... +Listening: +KL: kc: 169, col: 0, row: 0, pressed: 1 +KL: kc: 169, col: 0, row: 0, pressed: 0 +KL: kc: 174, col: 1, row: 0, pressed: 1 +KL: kc: 174, col: 1, row: 0, pressed: 0 +KL: kc: 172, col: 2, row: 0, pressed: 1 +KL: kc: 172, col: 2, row: 0, pressed: 0 +``` + +### Wieviel Zeit wurde benötigt um einen Tastenanschlag zu detektieren? + +Wenn Performance-Probleme auftreten ist es hilfreich die Frequenz, mit der die Matrix gescannt wird, zu wissen. Um dies in diesem Fall zu aktiveren füge, den folgenden Code zu deiner Tastaturbelegung in `config.h` hinzu. + +```c +#define DEBUG_MATRIX_SCAN_RATE +``` + +Beispiel Ausgabe +```text + > matrix scan frequency: 315 + > matrix scan frequency: 313 + > matrix scan frequency: 316 + > matrix scan frequency: 316 + > matrix scan frequency: 316 + > matrix scan frequency: 316 +``` diff --git a/docs/documentation_templates.md b/docs/documentation_templates.md index ba3830b64..85d3893b7 100644 --- a/docs/documentation_templates.md +++ b/docs/documentation_templates.md @@ -28,9 +28,9 @@ the Ctrl, Alt, or GUI modifiers are held down. 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) +* 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): @@ -38,5 +38,3 @@ Make example for this keyboard (after setting up your build environment): 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). ``` - -There needs to be two spaces at the end of the `Keyboard Maintainer` and `Hardware Supported` lines for it to render correctly with Markdown. diff --git a/docs/es/README.md b/docs/es/README.md index 73e7a7097..d39b27800 100644 --- a/docs/es/README.md +++ b/docs/es/README.md @@ -19,7 +19,7 @@ De cualquier manera, también puedes descargarlo directamente en formatos ([zip] ## Cómo compilar -Antes de poder compilar, necesitarás [instalar un entorno](getting_started_build_tools.md) para el desarrollo de AVR y/o ARM. Una vez hayas completado este paso, usarás el comando `make` para compilar un teclado y keymap con la siguiente notación: +Antes de poder compilar, necesitarás [instalar un entorno](es/getting_started_build_tools.md) para el desarrollo de AVR y/o ARM. Una vez hayas completado este paso, usarás el comando `make` para compilar un teclado y keymap con la siguiente notación: make planck/rev4:default @@ -29,4 +29,4 @@ Este ejemplo compilaría la revisión `rev4` del teclado `planck` con el keymap ## Cómo personalizar -QMK tiene montones de [características](features.md) para explorar, y una buena cantidad de [documentación de referencia](http://docs.qmk.fm) en la que sumergirse. Se pueden sacar provecho de la mayoría de las características modificando tu [keymap](keymap.md), y cambiando los [keycodes](keycodes.md). +QMK tiene montones de [características](es/features.md) para explorar, y una buena cantidad de [documentación de referencia](http://docs.qmk.fm) en la que sumergirse. Se pueden sacar provecho de la mayoría de las características modificando tu [keymap](es/keymap.md), y cambiando los [keycodes](es/keycodes.md). diff --git a/docs/es/_summary.md b/docs/es/_summary.md index 684d7ab6c..03bf05ba8 100644 --- a/docs/es/_summary.md +++ b/docs/es/_summary.md @@ -1,121 +1,121 @@ -* [Guía completa para novatos](newbs.md) - * [Empezando](newbs_getting_started.md) - * [Construyendo tu primer firmare](newbs_building_firmware.md) - * [Flasheando el firmware](newbs_flashing.md) - * [Testeando y depurando ](newbs_testing_debugging.md) - * [Mejores práticas](newbs_best_practices.md) - * [Recursos de aprendizaje](newbs_learn_more_resources.md) +* [Guía completa para novatos](es/newbs.md) + * [Empezando](es/newbs_getting_started.md) + * [Construyendo tu primer firmare](es/newbs_building_firmware.md) + * [Flasheando el firmware](es/newbs_flashing.md) + * [Testeando y depurando ](es/newbs_testing_debugging.md) + * [Mejores práticas](es/newbs_best_practices.md) + * [Recursos de aprendizaje](es/newbs_learn_more_resources.md) -* [QMK Basics](README.md) - * [Introducción a QMK](getting_started_introduction.md) - * [QMK CLI](cli.md) - * [Configuración de QMK CLI](cli_configuration.md) - * [Contribuyendo a QMK](contributing.md) - * [Cómo usar Github](getting_started_github.md) - * [Obtener ayuda](getting_started_getting_help.md) +* [QMK Basics](es/README.md) + * [Introducción a QMK](es/getting_started_introduction.md) + * [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) + * [Obtener ayuda](es/getting_started_getting_help.md) -* [Cambios incompatibles](breaking_changes.md) - * [30 Ago 2019](ChangeLog/20190830.md) +* [Cambios incompatibles](es/breaking_changes.md) + * [30 Ago 2019](es/ChangeLog/20190830.md) -* [Preguntas frecuentes](faq.md) - * [General](faq_general.md) - * [Construir/Compilar QMK](faq_build.md) - * [Depurando/Encontrando problemas en QMK](faq_debug.md) - * [Keymap](faq_keymap.md) - * [Instalación de drivers con Zadig](driver_installation_zadig.md) +* [Preguntas frecuentes](es/faq.md) + * [General](es/faq_general.md) + * [Construir/Compilar QMK](es/faq_build.md) + * [Depurando/Encontrando problemas en QMK](es/faq_debug.md) + * [Keymap](es/faq_keymap.md) + * [Instalación de drivers con Zadig](es/driver_installation_zadig.md) * Guías detalladas - * [Instalar herramientas construcción](getting_started_build_tools.md) - * [Guía Vagrant](getting_started_vagrant.md) - * [Instrucciones de Construcción/Compilado](getting_started_make_guide.md) - * [Flasheando Firmware](flashing.md) - * [Personalizando funcionalidad](custom_quantum_functions.md) - * [Visión general del Keymap](keymap.md) + * [Instalar herramientas construcción](es/getting_started_build_tools.md) + * [Guía Vagrant](es/getting_started_vagrant.md) + * [Instrucciones de Construcción/Compilado](es/getting_started_make_guide.md) + * [Flasheando Firmware](es/flashing.md) + * [Personalizando funcionalidad](es/custom_quantum_functions.md) + * [Visión general del Keymap](es/keymap.md) -* [Hardware](hardware.md) - * [Procesadores AVR](hardware_avr.md) - * [Drivers](hardware_drivers.md) +* [Hardware](es/hardware.md) + * [Procesadores AVR](es/hardware_avr.md) + * [Drivers](es/hardware_drivers.md) * Referencia - * [Pautas de teclados](hardware_keyboard_guidelines.md) - * [Opciones de configuración](config_options.md) - * [Keycodes](keycodes.md) - * [Convenciones de código - C](coding_conventions_c.md) - * [Convenciones de código - Python](coding_conventions_python.md) - * [Mejores prácticas de documentación](documentation_best_practices.md) - * [Plantillas de documentación](documentation_templates.md) - * [Glosario](reference_glossary.md) - * [Tests unitarios](unit_testing.md) - * [Funciones útiles](ref_functions.md) - * [Sporte configurador](reference_configurator_support.md) - * [Formato info.json](reference_info_json.md) - * [Desarrollo Python CLI](cli_development.md) + * [Pautas de teclados](es/hardware_keyboard_guidelines.md) + * [Opciones de configuración](es/config_options.md) + * [Keycodes](es/keycodes.md) + * [Convenciones de código - C](es/coding_conventions_c.md) + * [Convenciones de código - Python](es/coding_conventions_python.md) + * [Mejores prácticas de documentación](es/documentation_best_practices.md) + * [Plantillas de documentación](es/documentation_templates.md) + * [Glosario](es/reference_glossary.md) + * [Tests unitarios](es/unit_testing.md) + * [Funciones útiles](es/ref_functions.md) + * [Sporte configurador](es/reference_configurator_support.md) + * [Formato info.json](es/reference_info_json.md) + * [Desarrollo Python CLI](es/cli_development.md) -* [Características](features.md) - * [Keycodes Básicos](keycodes_basic.md) - * [Teclas US ANSI Shifted](keycodes_us_ansi_shifted.md) - * [Keycodes Quantum](quantum_keycodes.md) - * [Keycodes Avanzados](feature_advanced_keycodes.md) - * [Audio](feature_audio.md) - * [Auto Shift](feature_auto_shift.md) - * [Retroiluminación](feature_backlight.md) - * [Bluetooth](feature_bluetooth.md) - * [Bootmagic](feature_bootmagic.md) - * [Combos](feature_combo.md) - * [Comando](feature_command.md) - * [API Debounce](feature_debounce_type.md) - * [Switch DIP](feature_dip_switch.md) - * [Macros Dinámicas](feature_dynamic_macros.md) - * [Encoders](feature_encoders.md) - * [Grave Escape](feature_grave_esc.md) - * [Feedback Háptico](feature_haptic_feedback.md) - * [Controlador LCD HD44780](feature_hd44780.md) - * [Key Lock](feature_key_lock.md) - * [Layouts](feature_layouts.md) - * [Tecla Leader](feature_leader_key.md) - * [Matriz LED](feature_led_matrix.md) - * [Macros](feature_macros.md) - * [Teclas del ratón](feature_mouse_keys.md) - * [Driver OLED](feature_oled_driver.md) - * [Teclas One Shot](feature_advanced_keycodes.md#one-shot-keys) - * [Dispositivo de apuntado](feature_pointing_device.md) - * [Ratón PS/2](feature_ps2_mouse.md) - * [Iluminación RGB](feature_rgblight.md) - * [Matriz RGB](feature_rgb_matrix.md) - * [Cadete espacial](feature_space_cadet.md) - * [Teclado dividido](feature_split_keyboard.md) - * [Stenografía](feature_stenography.md) - * [Swap Hands](feature_swap_hands.md) - * [Tap Dance](feature_tap_dance.md) - * [Terminal](feature_terminal.md) - * [Impresora Térmica](feature_thermal_printer.md) - * [Unicode](feature_unicode.md) - * [Userspace](feature_userspace.md) - * [Velocikey](feature_velocikey.md) +* [Características](es/features.md) + * [Keycodes Básicos](es/keycodes_basic.md) + * [Teclas US ANSI Shifted](es/keycodes_us_ansi_shifted.md) + * [Keycodes Quantum](es/quantum_keycodes.md) + * [Keycodes Avanzados](es/feature_advanced_keycodes.md) + * [Audio](es/feature_audio.md) + * [Auto Shift](es/feature_auto_shift.md) + * [Retroiluminación](es/feature_backlight.md) + * [Bluetooth](es/feature_bluetooth.md) + * [Bootmagic](es/feature_bootmagic.md) + * [Combos](es/feature_combo.md) + * [Comando](es/feature_command.md) + * [API Debounce](es/feature_debounce_type.md) + * [Switch DIP](es/feature_dip_switch.md) + * [Macros Dinámicas](es/feature_dynamic_macros.md) + * [Encoders](es/feature_encoders.md) + * [Grave Escape](es/feature_grave_esc.md) + * [Feedback Háptico](es/feature_haptic_feedback.md) + * [Controlador LCD HD44780](es/feature_hd44780.md) + * [Key Lock](es/feature_key_lock.md) + * [Layouts](es/feature_layouts.md) + * [Tecla Leader](es/feature_leader_key.md) + * [Matriz LED](es/feature_led_matrix.md) + * [Macros](es/feature_macros.md) + * [Teclas del ratón](es/feature_mouse_keys.md) + * [Driver OLED](es/feature_oled_driver.md) + * [Teclas One Shot](es/feature_advanced_keycodes.md#one-shot-keys) + * [Dispositivo de apuntado](es/feature_pointing_device.md) + * [Ratón PS/2](es/feature_ps2_mouse.md) + * [Iluminación RGB](es/feature_rgblight.md) + * [Matriz RGB](es/feature_rgb_matrix.md) + * [Cadete espacial](es/feature_space_cadet.md) + * [Teclado dividido](es/feature_split_keyboard.md) + * [Stenografía](es/feature_stenography.md) + * [Swap Hands](es/feature_swap_hands.md) + * [Tap Dance](es/feature_tap_dance.md) + * [Terminal](es/feature_terminal.md) + * [Impresora Térmica](es/feature_thermal_printer.md) + * [Unicode](es/feature_unicode.md) + * [Userspace](es/feature_userspace.md) + * [Velocikey](es/feature_velocikey.md) * Para Makers y Modders - * [Guía de cableado a mano](hand_wire.md) - * [Guía de flasheado de ISP](isp_flashing_guide.md) - * [Guía de depuración de ARM](arm_debugging.md) - * [Driver I2C](i2c_driver.md) - * [Controles GPIO](internals_gpio_control.md) - * [Conversión Proton C](proton_c_conversion.md) + * [Guía de cableado a mano](es/hand_wire.md) + * [Guía de flasheado de ISP](es/isp_flashing_guide.md) + * [Guía de depuración de ARM](es/arm_debugging.md) + * [Driver I2C](es/i2c_driver.md) + * [Controles GPIO](es/internals_gpio_control.md) + * [Conversión Proton C](es/proton_c_conversion.md) * Para entender en profundidad - * [Cómo funcionan los teclados](how_keyboards_work.md) - * [Entendiendo QMK](understanding_qmk.md) + * [Cómo funcionan los teclados](es/how_keyboards_work.md) + * [Entendiendo QMK](es/understanding_qmk.md) * Otros temas - * [Usando Eclipse con QMK](other_eclipse.md) - * [Usando VSCode con QMK](other_vscode.md) - * [Soporte](support.md) - * [Cómo añadir traducciones](translating.md) + * [Usando Eclipse con QMK](es/other_eclipse.md) + * [Usando VSCode con QMK](es/other_vscode.md) + * [Soporte](es/support.md) + * [Cómo añadir traducciones](es/translating.md) * QMK Internals (En progreso) - * [Defines](internals_defines.md) - * [Input Callback Reg](internals_input_callback_reg.md) - * [Dispositivo Midi](internals_midi_device.md) - * [Proceso de configuración de un dispositivo Midi](internals_midi_device_setup_process.md) - * [Utilidad Midi](internals_midi_util.md) - * [Funciones Send](internals_send_functions.md) - * [Herramientas Sysex](internals_sysex_tools.md) + * [Defines](es/internals_defines.md) + * [Input Callback Reg](es/internals_input_callback_reg.md) + * [Dispositivo Midi](es/internals_midi_device.md) + * [Proceso de configuración de un dispositivo Midi](es/internals_midi_device_setup_process.md) + * [Utilidad Midi](es/internals_midi_util.md) + * [Funciones Send](es/internals_send_functions.md) + * [Herramientas Sysex](es/internals_sysex_tools.md) diff --git a/docs/faq_build.md b/docs/faq_build.md index f11cb76aa..618ae40f3 100644 --- a/docs/faq_build.md +++ b/docs/faq_build.md @@ -47,7 +47,7 @@ SUBSYSTEMS=="usb", ATTRS{idVendor}=="feed", MODE:="0666" SUBSYSTEMS=="usb", ATTRS{idVendor}=="1c11", MODE:="0666" ``` -**/etc/udev/rules.d/55-catalina.rules:** +**/etc/udev/rules.d/55-caterina.rules:** ``` # ModemManager should ignore the following devices ATTRS{idVendor}=="2a03", ENV{ID_MM_DEVICE_IGNORE}="1" @@ -69,6 +69,12 @@ SUBSYSTEMS=="usb", ATTRS{idVendor}=="1eaf", ATTRS{idProduct}=="0003", MODE:="066 SUBSYSTEMS=="usb", ATTRS{idVendor}=="0483", ATTRS{idProduct}=="df11", MODE:="0666" ``` +**/etc/udev/rules.d/57-bootloadhid.rules:** +``` +# bootloadHID +SUBSYSTEMS=="usb", ATTRS{idVendor}=="16c0", ATTRS{idProduct}=="05df", MODE:="0666" +``` + ### Serial device is not detected in bootloader mode on Linux Make sure your kernel has appropriate support for your device. If your device uses USB ACM, such as Pro Micro (Atmega32u4), make sure to include `CONFIG_USB_ACM=y`. Other devices may require `USB_SERIAL` and any of its sub options. @@ -81,10 +87,6 @@ Re-running the QMK installation script (`./util/qmk_install.sh` from the `qmk_fi If that doesn't work, then you may need to download and run Zadig. See [Bootloader Driver Installation with Zadig](driver_installation_zadig.md) for more detailed information. -## WINAVR is Obsolete -It is no longer recommended and may cause some problem. -See [TMK Issue #99](https://github.com/tmk/tmk_keyboard/issues/99). - ## USB VID and PID You can use any ID you want with editing `config.h`. Using any presumably unused ID will be no problem in fact except for very low chance of collision with other product. @@ -97,29 +99,6 @@ You can buy a really unique VID:PID here. I don't think you need this for person - http://www.obdev.at/products/vusb/license.html - http://www.mcselec.com/index.php?page=shop.product_details&flypage=shop.flypage&product_id=92&option=com_phpshop&Itemid=1 -## Cortex: `cstddef: No such file or directory` -GCC 4.8 of Ubuntu 14.04 had this problem and had to update to 4.9 with this PPA. -https://launchpad.net/~terry.guo/+archive/ubuntu/gcc-arm-embedded - -https://github.com/tmk/tmk_keyboard/issues/212 -https://github.com/tmk/tmk_keyboard/wiki/mbed-cortex-porting#compile-error-cstddef -https://developer.mbed.org/forum/mbed/topic/5205/ - -## `clock_prescale_set` and `clock_div_1` Not Available -Your toolchain is too old to support the MCU. For example WinAVR 20100110 doesn't support ATMega32u2. - -``` -Compiling C: ../../tmk_core/protocol/lufa/lufa.c -avr-gcc -c -mmcu=atmega32u2 -gdwarf-2 -DF_CPU=16000000UL -DINTERRUPT_CONTROL_ENDPOINT -DBOOTLOADER_SIZE=4096 -DF_USB=16000000UL -DARCH=ARCH_AVR8 -DUSB_DEVICE_ONLY -DUSE_FLASH_DESCRIPTORS -DUSE_STATIC_OPTIONS="(USB_DEVICE_OPT_FULLSPEED | USB_OPT_REG_ENABLED | USB_OPT_AUTO_PLL)" -DFIXED_CONTROL_ENDPOINT_SIZE=8 -DFIXED_NUM_CONFIGURATIONS=1 -DPROTOCOL_LUFA -DEXTRAKEY_ENABLE -DCONSOLE_ENABLE -DCOMMAND_ENABLE -DVERSION=unknown -Os -funsigned-char -funsigned-bitfields -ffunction-sections -fdata-sections -fno-inline-small-functions -fpack-struct -fshort-enums -fno-strict-aliasing -Wall -Wstrict-prototypes -Wa,-adhlns=obj_alps64/protocol/lufa/lufa.lst -I. -I../../tmk_core -I../../tmk_core/protocol/lufa -I../../tmk_core/protocol/lufa/LUFA-git -I../../tmk_core/common -std=gnu99 -include config.h -MMD -MP -MF .dep/obj_alps64_protocol_lufa_lufa.o.d ../../tmk_core/protocol/lufa/lufa.c -o obj_alps64/protocol/lufa/lufa.o -../../tmk_core/protocol/lufa/lufa.c: In function 'setup_mcu': -../../tmk_core/protocol/lufa/lufa.c:575: warning: implicit declaration of function 'clock_prescale_set' -../../tmk_core/protocol/lufa/lufa.c:575: error: 'clock_div_1' undeclared (first use in this function) -../../tmk_core/protocol/lufa/lufa.c:575: error: (Each undeclared identifier is reported only once -../../tmk_core/protocol/lufa/lufa.c:575: error: for each function it appears in.) -make: *** [obj_alps64/protocol/lufa/lufa.o] Error 1 -``` - - ## BOOTLOADER_SIZE for AVR Note that Teensy2.0++ bootloader size is 2048byte. Some Makefiles may have wrong comment. diff --git a/docs/faq_debug.md b/docs/faq_debug.md index 5cc20251d..6c66defbd 100644 --- a/docs/faq_debug.md +++ b/docs/faq_debug.md @@ -27,7 +27,7 @@ You may need privilege to access the device on OS like Linux. Check: - *hid_listen* finds your device. See above. - Enable debug with pressing **Magic**+d. See [Magic Commands](https://github.com/tmk/tmk_keyboard#magic-commands). -- set `debug_enable=true` usually in `matrix_init()` in **matrix.c**. +- set `debug_enable=true`. See [Testing and Debugging](newbs_testing_debugging.md#debugging) - try using 'print' function instead of debug print. See **common/print.h**. - disconnect other devices with console function. See [Issue #97](https://github.com/tmk/tmk_keyboard/issues/97). @@ -112,56 +112,6 @@ In C `1` means one of [int] type which is [16 bit] in case of AVR so you can't s http://deskthority.net/workshop-f7/rebuilding-and-redesigning-a-classic-thinkpad-keyboard-t6181-60.html#p146279 - -## Bootloader Jump Doesn't Work -Properly configure bootloader size in **Makefile**. With wrong section size bootloader won't probably start with **Magic command** and **Boot Magic**. -``` -# Size of Bootloaders in bytes: -# Atmel DFU loader(ATmega32U4) 4096 -# Atmel DFU loader(AT90USB128) 8192 -# LUFA bootloader(ATmega32U4) 4096 -# Arduino Caterina(ATmega32U4) 4096 -# USBaspLoader(ATmega***) 2048 -# Teensy halfKay(ATmega32U4) 512 -# Teensy++ halfKay(AT90USB128) 2048 -OPT_DEFS += -DBOOTLOADER_SIZE=4096 -``` -AVR Boot section size are defined by setting **BOOTSZ** fuse in fact. Consult with your MCU datasheet. -Note that **Word**(2 bytes) size and address are used in datasheet while TMK uses **Byte**. - -AVR Boot section is located at end of Flash memory like the followings. -``` -byte Atmel/LUFA(ATMega32u4) byte Atmel(AT90SUB1286) -0x0000 +---------------+ 0x00000 +---------------+ - | | | | - | | | | - | Application | | Application | - | | | | - = = = = - | | 32KB-4KB | | 128KB-8KB -0x6000 +---------------+ 0x1E000 +---------------+ - | Bootloader | 4KB | Bootloader | 8KB -0x7FFF +---------------+ 0x1FFFF +---------------+ - - -byte Teensy(ATMega32u4) byte Teensy++(AT90SUB1286) -0x0000 +---------------+ 0x00000 +---------------+ - | | | | - | | | | - | Application | | Application | - | | | | - = = = = - | | 32KB-512B | | 128KB-2KB -0x7E00 +---------------+ 0x1FC00 +---------------+ - | Bootloader | 512B | Bootloader | 2KB -0x7FFF +---------------+ 0x1FFFF +---------------+ -``` - -And see this discussion for further reference. -https://github.com/tmk/tmk_keyboard/issues/179 - -If you are using a TeensyUSB, there is a [known bug](https://github.com/qmk/qmk_firmware/issues/164) in which the hardware reset button prevents the RESET key from working. Unplugging the keyboard and plugging it back in should resolve the problem. - ## Special Extra Key Doesn't Work (System, Audio Control Keys) You need to define `EXTRAKEY_ENABLE` in `rules.mk` to use them in QMK. @@ -194,24 +144,6 @@ If you would like to keep JTAG enabled, just add the following to your `config.h #define NO_JTAG_DISABLE ``` -## Adding LED Indicators of Lock Keys -You need your own LED indicators for CapsLock, ScrollLock and NumLock? See this post. - -http://deskthority.net/workshop-f7/tmk-keyboard-firmware-collection-t4478-120.html#p191560 - -## Program Arduino Micro/Leonardo -Push reset button and then run command like this within 8 seconds. - -``` -avrdude -patmega32u4 -cavr109 -b57600 -Uflash:w:adb_usb.hex -P/dev/ttyACM0 -``` - -Device name will vary depending on your system. - -http://arduino.cc/en/Main/ArduinoBoardMicro -https://geekhack.org/index.php?topic=14290.msg1563867#msg1563867 - - ## USB 3 Compatibility I heard some people have a problem with USB 3 port, try USB 2 port. diff --git a/docs/faq_keymap.md b/docs/faq_keymap.md index 84d8548d4..2d00e8bef 100644 --- a/docs/faq_keymap.md +++ b/docs/faq_keymap.md @@ -67,24 +67,8 @@ After enabling this feature use keycodes `KC_LCAP`, `KC_LNUM` and `KC_LSCR` in y Old vintage mechanical keyboards occasionally have lock switches but modern ones don't have. ***You don't need this feature in most case and just use keycodes `KC_CAPS`, `KC_NLCK` and `KC_SLCK`.*** ## Input Special Characters Other Than ASCII like Cédille 'Ç' -NO UNIVERSAL METHOD TO INPUT THOSE WORKS OVER ALL SYSTEMS. You have to define **MACRO** in way specific to your OS or layout. -See this post for example **MACRO** code. - -http://deskthority.net/workshop-f7/tmk-keyboard-firmware-collection-t4478-120.html#p195620 - -On **Windows** you can use `AltGr` key or **Alt code**. -* http://en.wikipedia.org/wiki/AltGr_key -* http://en.wikipedia.org/wiki/Alt_code - -On **Mac** OS defines `Option` key combinations. -* http://en.wikipedia.org/wiki/Option_key#Alternative_keyboard_input - -On **Xorg** you can use `compose` key, instead. -* http://en.wikipedia.org/wiki/Compose_key - -And see this for **Unicode** input. -* http://en.wikipedia.org/wiki/Unicode_input +See the [Unicode](feature_unicode.md) feature. ## `Fn` Key on macOS @@ -130,51 +114,6 @@ https://github.com/tekezo/Karabiner/issues/403 See the [Grave Escape](feature_grave_esc.md) feature. -## Arrow on Right Modifier Keys with Dual-Role -This turns right modifier keys into arrow keys when the keys are tapped while still modifiers when the keys are hold. In TMK the dual-role function is dubbed **TAP**. -``` - -#include "keymap_common.h" - - -/* Arrow keys on right modifier keys with TMK dual role feature - * - * https://github.com/tmk/tmk_core/blob/master/doc/keymap.md#213-modifier-with-tap-keydual-role - * https://en.wikipedia.org/wiki/Modifier_key#Dual-role_keys - */ -const uint8_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] = { - /* 0: qwerty */ - [0] = LAYOUT( \ - ESC, 1, 2, 3, 4, 5, 6, 7, 8, 9, 0, MINS,EQL, NUHS,BSPC, \ - TAB, Q, W, E, R, T, Y, U, I, O, P, LBRC,RBRC,BSLS, \ - LCTL,A, S, D, F, G, H, J, K, L, SCLN,QUOT,ENT, \ - LSFT,NUBS,Z, X, C, V, B, N, M, COMM,DOT, SLSH,FN0, ESC, \ - FN4, LGUI,LALT, SPC, APP, FN2, FN1, FN3), - [1] = LAYOUT( \ - GRV, F1, F2, F3, F4, F5, F6, F7, F8, F9, F10, F11, F12, TRNS,TRNS, \ - TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,\ - TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS, \ - TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,FN5, TRNS, \ - TRNS,TRNS,TRNS, TRNS, TRNS,FN7, FN6, FN8), -}; - -const uint16_t PROGMEM fn_actions[] = { - [0] = ACTION_MODS_TAP_KEY(MOD_RSFT, KC_UP), - [1] = ACTION_MODS_TAP_KEY(MOD_RGUI, KC_DOWN), - [2] = ACTION_MODS_TAP_KEY(MOD_RALT, KC_LEFT), - [3] = ACTION_MODS_TAP_KEY(MOD_RCTL, KC_RIGHT), - [4] = ACTION_LAYER_MOMENTARY(1), - [5] = ACTION_MODS_TAP_KEY(MOD_RSFT, KC_PGUP), - [6] = ACTION_MODS_TAP_KEY(MOD_RGUI, KC_PGDN), - [7] = ACTION_MODS_TAP_KEY(MOD_RALT, KC_HOME), - [8] = ACTION_MODS_TAP_KEY(MOD_RCTL, KC_END), -}; - -``` - -Dual-role key: https://en.wikipedia.org/wiki/Modifier_key#Dual-role_keys - - ## Eject on Mac OSX `KC_EJCT` keycode works on OSX. https://github.com/tmk/tmk_keyboard/issues/250 It seems Windows 10 ignores the code and Linux/Xorg recognizes but has no mapping by default. diff --git a/docs/feature_advanced_keycodes.md b/docs/feature_advanced_keycodes.md index f748ccd70..ec3807f40 100644 --- a/docs/feature_advanced_keycodes.md +++ b/docs/feature_advanced_keycodes.md @@ -15,7 +15,7 @@ This will allow you to use `FN_CAPS` and `ALT_TAB` in your keymap, keeping it mo ## 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`. Modifiers specified as part of a Layer Tap or Mod Tap's keycode will be ignored. If you need to apply modifiers to your tapped keycode, [Tap Dance](https://github.com/qmk/qmk_firmware/blob/master/docs/feature_tap_dance.md#example-5-using-tap-dance-for-advanced-mod-tap-and-layer-tap-keys) can be used to accomplish this. +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`. Modifiers specified as part of a Layer Tap or Mod Tap's keycode will be ignored. 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. Additionally, if at least one right-handed modifier is specified in a Mod Tap or Layer Tap, it will cause all modifiers specified to become right-handed, so it is not possible to mix and match the two. @@ -155,7 +155,7 @@ You can control the behavior of one shot keys by defining these in `config.h`: Sometimes, you want to activate a one-shot key as part of a macro or tap dance routine. -For one shot layers, you need to call `set_oneshot_layer(LAYER, ONESHOT_START)` on key down, and `set_oneshot_layer(ONESHOT_PRESSED)` on key up. If you want to cancel the oneshot, call `reset_oneshot_layer()`. +For one shot layers, you need to call `set_oneshot_layer(LAYER, ONESHOT_START)` on key down, and `clear_oneshot_layer_state(ONESHOT_OTHER_KEY_PRESSED)` on key up. If you want to cancel the oneshot, call `reset_oneshot_layer()`. For one shot mods, you need to call `set_oneshot_mods(MOD)` to set it, or `clear_oneshot_mods()` to cancel it. diff --git a/docs/feature_bootmagic.md b/docs/feature_bootmagic.md index ed00d5129..a19b5e548 100644 --- a/docs/feature_bootmagic.md +++ b/docs/feature_bootmagic.md @@ -56,37 +56,37 @@ Hold down the Bootmagic key (Space by default) and the desired hotkey while plug ## Keycodes -|Keycode |Aliases |Description | -|----------------------------------|---------|------------------------------------------| -|`MAGIC_CAPSLOCK_TO_CONTROL` | |Treat Caps Lock as Left Control | -|`MAGIC_UNCAPSLOCK_TO_CONTROL` | |Stop treating Caps Lock as Left Control | -|`MAGIC_HOST_NKRO` | |Force N-Key Rollover (NKRO) on | -|`MAGIC_UNHOST_NKRO` | |Force NKRO off | -|`MAGIC_TOGGLE_NKRO` | |Turn NKRO on or off | -|`MAGIC_NO_GUI` | |Disable the GUI keys (useful when gaming) | -|`MAGIC_UNNO_GUI` | |Enable the GUI keys | -|`MAGIC_SWAP_ALT_GUI` |`AG_SWAP`|Swap Alt and GUI on both sides (for macOS)| -|`MAGIC_UNSWAP_ALT_GUI` |`AG_NORM`|Unswap Alt and GUI | -|`MAGIC_TOGGLE_ALT_GUI` |`AG_TOGG`|Toggle Alt and GUI swap | -|`MAGIC_SWAP_CTL_GUI` |`CG_SWAP`|Swap Ctrl and GUI on both sides (for macOS)| -|`MAGIC_UNSWAP_CTL_GUI` |`CG_NORM`|Unswap Ctrl and GUI | -|`MAGIC_TOGGLE_CTL_GUI` |`CG_TOGG`|Toggle Ctrl and GUI swap | -|`MAGIC_SWAP_BACKSLASH_BACKSPACE` | |Swap `\` and Backspace | -|`MAGIC_UNSWAP_BACKSLASH_BACKSPACE`| |Unswap `\` and Backspace | -|`MAGIC_SWAP_CONTROL_CAPSLOCK` | |Swap Left Control and Caps Lock | -|`MAGIC_UNSWAP_CONTROL_CAPSLOCK` | |Unswap Left Control and Caps Lock | -|`MAGIC_SWAP_GRAVE_ESC` | |Swap <code>`</code> and Escape | -|`MAGIC_UNSWAP_GRAVE_ESC` | |Unswap <code>`</code> and Escape | -|`MAGIC_SWAP_LALT_LGUI` | |Swap Left Alt and Left GUI | -|`MAGIC_UNSWAP_LALT_LGUI` | |Unswap Left Alt and Left GUI | -|`MAGIC_SWAP_RALT_RGUI` | |Swap Right Alt and Right GUI | -|`MAGIC_UNSWAP_RALT_RGUI` | |Unswap Right Alt and Right GUI | -|`MAGIC_SWAP_LCTL_LGUI` | |Swap Left Control and Left GUI | -|`MAGIC_UNSWAP_LCTL_LGUI` | |Unswap Left Control and Left GUI | -|`MAGIC_SWAP_RCTL_RGUI` | |Swap Right Control and Right GUI | -|`MAGIC_UNSWAP_RCTL_RGUI` | |Unswap Right Control and Right GUI | -|`MAGIC_EE_HANDS_LEFT` | |Set "Left Hand" for EE_HANDS handedness | -|`MAGIC_EE_HANDS_RIGHT` | |Set "Right Hand" for EE_HANDS handedness | +|Key |Aliases |Description | +|----------------------------------|---------|--------------------------------------------------------------------------| +|`MAGIC_SWAP_CONTROL_CAPSLOCK` |`CL_SWAP`|Swap Caps Lock and Left Control | +|`MAGIC_UNSWAP_CONTROL_CAPSLOCK` |`CL_NORM`|Unswap Caps Lock and Left Control | +|`MAGIC_CAPSLOCK_TO_CONTROL` |`CL_CTRL`|Treat Caps Lock as Control | +|`MAGIC_UNCAPSLOCK_TO_CONTROL` |`CL_CAPS`|Stop treating Caps Lock as Control | +|`MAGIC_SWAP_LCTL_LGUI` |`LCG_SWP`|Swap Left Control and GUI | +|`MAGIC_UNSWAP_LCTL_LGUI` |`LCG_NRM`|Unswap Left Control and GUI | +|`MAGIC_SWAP_RCTL_RGUI` |`RCG_SWP`|Swap Right Control and GUI | +|`MAGIC_UNSWAP_RCTL_RGUI` |`RCG_NRM`|Unswap Right Control and GUI | +|`MAGIC_SWAP_CTL_GUI` |`CG_SWAP`|Swap Control and GUI on both sides | +|`MAGIC_UNSWAP_CTL_GUI` |`CG_NORM`|Unswap Control and GUI on both sides | +|`MAGIC_TOGGLE_CTL_GUI` |`CG_TOGG`|Toggle Control and GUI swap on both sides | +|`MAGIC_SWAP_LALT_LGUI` |`LAG_SWP`|Swap Left Alt and GUI | +|`MAGIC_UNSWAP_LALT_LGUI` |`LAG_NRM`|Unswap Left Alt and GUI | +|`MAGIC_SWAP_RALT_RGUI` |`RAG_SWP`|Swap Right Alt and GUI | +|`MAGIC_UNSWAP_RALT_RGUI` |`RAG_NRM`|Unswap Right Alt and GUI | +|`MAGIC_SWAP_ALT_GUI` |`AG_SWAP`|Swap Alt and GUI on both sides | +|`MAGIC_UNSWAP_ALT_GUI` |`AG_NORM`|Unswap Alt and GUI on both sides | +|`MAGIC_TOGGLE_ALT_GUI` |`AG_TOGG`|Toggle Alt and GUI swap on both sides | +|`MAGIC_NO_GUI` |`GUI_OFF`|Disable the GUI keys | +|`MAGIC_UNNO_GUI` |`GUI_ON` |Enable the GUI keys | +|`MAGIC_SWAP_GRAVE_ESC` |`GE_SWAP`|Swap <code>`</code> and Escape | +|`MAGIC_UNSWAP_GRAVE_ESC` |`GE_NORM`|Unswap <code>`</code> and Escape | +|`MAGIC_SWAP_BACKSLASH_BACKSPACE` |`BS_SWAP`|Swap `\` and Backspace | +|`MAGIC_UNSWAP_BACKSLASH_BACKSPACE`|`BS_NORM`|Unswap `\` and Backspace | +|`MAGIC_HOST_NKRO` |`NK_ON` |Enable N-key rollover | +|`MAGIC_UNHOST_NKRO` |`NK_OFF` |Disable N-key rollover | +|`MAGIC_TOGGLE_NKRO` |`NK_TOGG`|Toggle N-key rollover | +|`MAGIC_EE_HANDS_LEFT` |`EH_LEFT`|Set the master half of a split keyboard as the left hand (for `EE_HANDS`) | +|`MAGIC_EE_HANDS_RIGHT` |`EH_RGHT`|Set the master half of a split keyboard as the right hand (for `EE_HANDS`)| ## Configuration diff --git a/docs/feature_debounce_type.md b/docs/feature_debounce_type.md index 38eca3f37..b5e5b61bb 100644 --- a/docs/feature_debounce_type.md +++ b/docs/feature_debounce_type.md @@ -17,14 +17,14 @@ endif | DEBOUNCE_TYPE | Description | What else is needed | | ------------- | --------------------------------------------------- | ----------------------------- | | Not defined | Use the default algorithm, currently sym_g | Nothing | -| custom | Use your own debounce.c | ```SRC += debounce.c``` add your own debounce.c and implement necessary functions | +| custom | Use your own debounce code | ```SRC += debounce.c``` add your own debounce.c and implement necessary functions | | anything_else | Use another algorithm from quantum/debounce/* | Nothing | **Regarding split keyboards**: The debounce code is compatible with split keyboards. # Use your own debouncing code -* Set ```DEBOUNCE_TYPE = custom ```. +* Set ```DEBOUNCE_TYPE = custom```. * Add ```SRC += debounce.c``` * Add your own ```debounce.c```. Look at current implementations in ```quantum/debounce``` for examples. * Debouncing occurs after every raw matrix scan. @@ -33,10 +33,10 @@ The debounce code is compatible with split keyboards. # Changing between included debouncing methods You can either use your own code, by including your own debounce.c, or switch to another included one. Included debounce methods are: -* eager_pr - debouncing per row. On any state change, response is immediate, followed by locking the row ```DEBOUNCE_DELAY``` milliseconds of no further input for that row. +* eager_pr - debouncing per row. On any state change, response is immediate, followed by locking the row ```DEBOUNCE``` milliseconds of no further input for that row. For use in keyboards where refreshing ```NUM_KEYS``` 8-bit counters is computationally expensive / low scan rate, and fingers usually only hit one row at a time. This could be appropriate for the ErgoDox models; the matrix is rotated 90°, and hence its "rows" are really columns, and each finger only hits a single "row" at a time in normal use. -* eager_pk - debouncing per key. On any state change, response is immediate, followed by ```DEBOUNCE_DELAY``` milliseconds of no further input for that key -* sym_g - debouncing per keyboard. On any state change, a global timer is set. When ```DEBOUNCE_DELAY``` milliseconds of no changes has occured, all input changes are pushed. +* eager_pk - debouncing per key. On any state change, response is immediate, followed by ```DEBOUNCE``` milliseconds of no further input for that key +* sym_g - debouncing per keyboard. On any state change, a global timer is set. When ```DEBOUNCE``` milliseconds of no changes has occured, all input changes are pushed. diff --git a/docs/feature_dynamic_macros.md b/docs/feature_dynamic_macros.md index 0d11a2864..b86df6c60 100644 --- a/docs/feature_dynamic_macros.md +++ b/docs/feature_dynamic_macros.md @@ -4,51 +4,45 @@ QMK supports temporary macros created on the fly. We call these Dynamic Macros. You can store one or two macros and they may have a combined total of 128 keypresses. You can increase this size at the cost of RAM. -To enable them, first add a new element to the end of your `keycodes` enum — `DYNAMIC_MACRO_RANGE`: +To enable them, first include `DYNAMIC_MACRO_ENABLE = yes` in your `rules.mk`. Then, add the following keys to your keymap: -```c -enum keycodes { - QWERTY = SAFE_RANGE, - COLEMAK, - DVORAK, - PLOVER, - LOWER, - RAISE, - BACKLIT, - EXT_PLV, - DYNAMIC_MACRO_RANGE, -}; -``` +|Key |Alias |Description | +|------------------|----------|---------------------------------------------------| +|`DYN_REC_START1` |`DM_REC1` |Start recording Macro 1 | +|`DYN_REC_START2` |`DM_REC2` |Start recording Macro 2 | +|`DYN_MACRO_PLAY1` |`DM_PLY1` |Replay Macro 1 | +|`DYN_MACRO_PLAY2` |`DM_PLY2` |Replay Macro 2 | +|`DYN_REC_STOP` |`DM_RSTP` |Finish the macro that is currently being recorded. | -Your `keycodes` enum may have a slightly different name. You must add `DYNAMIC_MACRO_RANGE` as the last element because `dynamic_macros.h` will add some more keycodes after it. +That should be everything necessary. -Below it, include the `dynamic_macro.h` header: +To start recording the macro, press either `DYN_REC_START1` or `DYN_REC_START2`. -```c - #include "dynamic_macro.h"` -``` +To finish the recording, press the `DYN_REC_STOP` layer button. -Add the following keys to your keymap: +To replay the macro, press either `DYN_MACRO_PLAY1` or `DYN_MACRO_PLAY2`. -* `DYN_REC_START1` — start recording the macro 1, -* `DYN_REC_START2` — start recording the macro 2, -* `DYN_MACRO_PLAY1` — replay the macro 1, -* `DYN_MACRO_PLAY2` — replay the macro 2, -* `DYN_REC_STOP` — finish the macro that is currently being recorded. +It is possible to replay a macro as part of a macro. It's ok to replay macro 2 while recording macro 1 and vice versa but never create recursive macros i.e. macro 1 that replays macro 1. If you do so and the keyboard will get unresponsive, unplug the keyboard and plug it again. You can disable this completly by defining `DYNAMIC_MACRO_NO_NESTING` in your `config.h` file. -Add the following code to the very beginning of your `process_record_user()` function: +?> For the details about the internals of the dynamic macros, please read the comments in the `process_dynamic_macro.h` and `process_dynamic_macro.c` files. -```c - if (!process_record_dynamic_macro(keycode, record)) { - return false; - } -``` +## Customization -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 replay the macro, press either `DYN_MACRO_PLAY1` or `DYN_MACRO_PLAY2`. +There are a number of options added that should allow some additional degree of customization -Note that it's possible to replay a macro as part of a macro. It's ok to replay macro 2 while recording macro 1 and vice versa but never create recursive macros i.e. macro 1 that replays macro 1. If you do so and the keyboard will get unresponsive, unplug the keyboard and plug it again. +|Define |Default |Description | +|----------------------------|----------------|-----------------------------------------------------------------------------------------------------------------| +|`DYNAMIC_MACRO_SIZE` |128 |Sets the amount of memory that Dynamic Macros can use. This is a limited resource, dependent on the controller. | +|`DYNAMIC_MACRO_USER_CALL` |*Not defined* |Defining this falls back to using the user `keymap.c` file to trigger the macro behavior. | +|`DYNAMIC_MACRO_NO_NESTING` |*Not Defined* |Defining this disables the ability to call a macro from another macro (nested macros). | -For users of the earlier versions of dynamic macros: It is still possible to finish the macro recording using just the layer modifier used to access the dynamic macro keys, without a dedicated `DYN_REC_STOP` key. If you want this behavior back, use the following snippet instead of the one above: + +If the LEDs start blinking during the recording with each keypress, it means there is no more space for the macro in the macro buffer. To fit the macro in, either make the other macro shorter (they share the same buffer) or increase the buffer size by adding the `DYNAMIC_MACRO_SIZE` define in your `config.h` (default value: 128; please read the comments for it in the header). + + +### DYNAMIC_MACRO_USER_CALL + +For users of the earlier versions of dynamic macros: It is still possible to finish the macro recording using just the layer modifier used to access the dynamic macro keys, without a dedicated `DYN_REC_STOP` key. If you want this behavior back, add `#define DYNAMIC_MACRO_USER_CALL` to your `config.h` and insert the following snippet at the beginning of your `process_record_user()` function: ```c uint16_t macro_kc = (keycode == MO(_DYN) ? DYN_REC_STOP : keycode); @@ -58,6 +52,15 @@ For users of the earlier versions of dynamic macros: It is still possible to fin } ``` -If the LEDs start blinking during the recording with each keypress, it means there is no more space for the macro in the macro buffer. To fit the macro in, either make the other macro shorter (they share the same buffer) or increase the buffer size by setting the `DYNAMIC_MACRO_SIZE` preprocessor macro (default value: 128; please read the comments for it in the header). +### User Hooks + +There are a number of hooks that you can use to add custom functionality and feedback options to Dynamic Macro feature. This allows for some additional degree of customization. + +Note, that direction indicates which macro it is, with `1` being Macro 1, `-1` being Macro 2, and 0 being no macro. + +* `dynamic_macro_record_start_user(void)` - Triggered when you start recording a macro. +* `dynamic_macro_play_user(int8_t direction)` - Triggered when you play back a macro. +* `dynamic_macro_record_key_user(int8_t direction, keyrecord_t *record)` - Triggered on each keypress while recording a macro. +* `dynamic_macro_record_end_user(int8_t direction)` - Triggered when the macro recording is stopped. -For the details about the internals of the dynamic macros, please read the comments in the `dynamic_macro.h` header. +Additionally, you can call `dynamic_macro_led_blink()` to flash the backlights if that feature is enabled. diff --git a/docs/feature_haptic_feedback.md b/docs/feature_haptic_feedback.md index d9e445de8..ff7337a51 100644 --- a/docs/feature_haptic_feedback.md +++ b/docs/feature_haptic_feedback.md @@ -2,7 +2,7 @@ ## Haptic feedback rules.mk options -The following options are currently available for haptic feedback in `rule.mk`: +The following options are currently available for haptic feedback in `rules.mk`: `HAPTIC_ENABLE += DRV2605L` @@ -41,11 +41,15 @@ First you will need a build a circuit to drive the solenoid through a mosfet as [Wiring diagram provided by Adafruit](https://playground.arduino.cc/uploads/Learning/solenoid_driver.pdf) -Select a pin that has PWM for the signal pin -``` -#define SOLENOID_PIN *pin* -``` +| Settings | Default | Description | +|--------------------------|---------------|-------------------------------------------------------| +|`SOLENOID_PIN` | *Not defined* |Configures the pin that the Solenoid is connected to. | +|`SOLENOID_DEFAULT_DWELL` | `12` ms |Configures the default dwell time for the solenoid. | +|`SOLENOID_MIN_DWELL` | `4` ms |Sets the lower limit for the dwell. | +|`SOLENOID_MAX_DWELL` | `100` ms |Sets the upper limit for the dwell. | + +?> Dwell time is how long the "plunger" stays activated. The dwell time changes how the solenoid sounds. Beware that some pins may be powered during bootloader (ie. A13 on the STM32F303 chip) and will result in the solenoid kept in the on state through the whole flashing process. This may overheat and damage the solenoid. If you find that the pin the solenoid is connected to is triggering the solenoid during bootloader/DFU, select another pin. @@ -151,4 +155,4 @@ This will set what sequence HPT_RST will set as the active mode. If not defined, ### DRV2605L Continuous Haptic Mode -This mode sets continuous haptic feedback with the option to increase or decrease strength.
\ No newline at end of file +This mode sets continuous haptic feedback with the option to increase or decrease strength. diff --git a/docs/feature_leader_key.md b/docs/feature_leader_key.md index 82cf78901..22370bf23 100644 --- a/docs/feature_leader_key.md +++ b/docs/feature_leader_key.md @@ -22,10 +22,10 @@ void matrix_scan_user(void) { SEND_STRING("QMK is awesome."); } SEQ_TWO_KEYS(KC_D, KC_D) { - SEND_STRING(SS_LCTRL("a")SS_LCTRL("c")); + SEND_STRING(SS_LCTL("a") SS_LCTL("c")); } SEQ_THREE_KEYS(KC_D, KC_D, KC_S) { - SEND_STRING("https://start.duckduckgo.com"SS_TAP(X_ENTER)); + SEND_STRING("https://start.duckduckgo.com\n"); } SEQ_TWO_KEYS(KC_A, KC_S) { register_code(KC_LGUI); @@ -115,11 +115,11 @@ void matrix_scan_user(void) { SEQ_ONE_KEY(KC_E) { // Anything you can do in a macro. - SEND_STRING(SS_LCTRL(SS_LSFT("t"))); + 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"SS_TAP(KC_ENTER)SS_LCTRL("c")); + SEND_STRING(SS_LGUI("r") "cmd\n" SS_LCTL("c")); did_leader_succeed = true; } leader_end(); diff --git a/docs/feature_macros.md b/docs/feature_macros.md index d81c3c655..c13ae8206 100644 --- a/docs/feature_macros.md +++ b/docs/feature_macros.md @@ -67,14 +67,14 @@ bool process_record_user(uint16_t keycode, keyrecord_t *record) { case QMKURL: if (record->event.pressed) { // when keycode QMKURL is pressed - SEND_STRING("https://qmk.fm/" SS_TAP(X_ENTER)); + SEND_STRING("https://qmk.fm/\n"); } else { // when keycode QMKURL is released } break; case MY_OTHER_MACRO: if (record->event.pressed) { - SEND_STRING(SS_LCTRL("ac")); // selects all and copies + SEND_STRING(SS_LCTL("ac")); // selects all and copies } break; } @@ -109,18 +109,21 @@ Which would send "VE" followed by a `KC_HOME` tap, and "LO" (spelling "LOVE" if There's also a couple of mod shortcuts you can use: -* `SS_LCTRL(string)` -* `SS_LGUI(string)` -* `SS_LALT(string)` +* `SS_LCTL(string)` * `SS_LSFT(string)` -* `SS_RALT(string)` +* `SS_LALT(string)` +* `SS_LGUI(string)`, `SS_LCMD(string)` or `SS_LWIN(string)` +* `SS_RCTL(string)` +* `SS_RSFT(string)` +* `SS_RALT(string)` or `SS_ALGR(string)` +* `SS_RGUI(string)`, `SS_RCMD(string)` or `SS_RWIN(string)` These press the respective modifier, send the supplied string and then release the modifier. They can be used like this: - SEND_STRING(SS_LCTRL("a")); + SEND_STRING(SS_LCTL("a")); -Which would send LCTRL+a (LCTRL down, a, LCTRL up) - notice that they take strings (eg `"k"`), and not the `X_K` keycodes. +Which would send Left Control+`a` (Left Control down, `a`, Left Control up) - notice that they take strings (eg `"k"`), and not the `X_K` keycodes. ### Alternative Keymaps diff --git a/docs/feature_rgb_matrix.md b/docs/feature_rgb_matrix.md index b2850c3cf..5695acc50 100644 --- a/docs/feature_rgb_matrix.md +++ b/docs/feature_rgb_matrix.md @@ -107,7 +107,7 @@ Where `X_Y` is the location of the LED in the matrix defined by [the datasheet]( --- -### WS2812 (AVR only) +### WS2812 There is basic support for addressable RGB matrix lighting with a WS2811/WS2812{a,b,c} addressable LED strand. To enable it, add this to your `rules.mk`: @@ -173,16 +173,20 @@ As mentioned earlier, the center of the keyboard by default is expected to be `{ All RGB keycodes are currently shared with the RGBLIGHT system: -* `RGB_TOG` - toggle -* `RGB_MOD` - cycle through modes -* `RGB_HUI` - increase hue -* `RGB_HUD` - decrease hue -* `RGB_SAI` - increase saturation -* `RGB_SAD` - decrease saturation -* `RGB_VAI` - increase value -* `RGB_VAD` - decrease value -* `RGB_SPI` - increase speed effect (no EEPROM support) -* `RGB_SPD` - decrease speed effect (no EEPROM support) +|Key |Aliases |Description | +|-------------------|----------|--------------------------------------------------------------------------------------| +|`RGB_TOG` | |Toggle RGB lighting on or off | +|`RGB_MODE_FORWARD` |`RGB_MOD` |Cycle through modes, reverse direction when Shift is held | +|`RGB_MODE_REVERSE` |`RGB_RMOD`|Cycle through modes in reverse, forward direction when Shift is held | +|`RGB_HUI` | |Increase hue, decrease hue when Shift is held | +|`RGB_HUD` | |Decrease hue, increase hue when Shift is held | +|`RGB_SAI` | |Increase saturation, decrease saturation when Shift is held | +|`RGB_SAD` | |Decrease saturation, increase saturation when Shift is held | +|`RGB_VAI` | |Increase value (brightness), decrease value when Shift is held | +|`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_*` keycodes will generally work, but are not currently mapped to the correct effects for the RGB Matrix system ## RGB Matrix Effects @@ -282,7 +286,7 @@ You can disable a single effect by defining `DISABLE_[EFFECT_NAME]` in your `con ## Custom RGB Matrix Effects -By setting `RGB_MATRIX_CUSTOM_USER` (and/or `RGB_MATRIX_CUSTOM_KB`) in `rule.mk`, new effects can be defined directly from userspace, without having to edit any QMK core files. +By setting `RGB_MATRIX_CUSTOM_USER` (and/or `RGB_MATRIX_CUSTOM_KB`) in `rules.mk`, new effects can be defined directly from userspace, without having to edit any QMK core files. To declare new effects, create a new `rgb_matrix_user/kb.inc` that looks something like this: diff --git a/docs/feature_rgblight.md b/docs/feature_rgblight.md index be4ddfa72..69a6aaaed 100644 --- a/docs/feature_rgblight.md +++ b/docs/feature_rgblight.md @@ -6,7 +6,7 @@ QMK has the ability to control RGB LEDs attached to your keyboard. This is commo Some keyboards come with RGB LEDs preinstalled. Others must have them installed after the fact. See the [Hardware Modification](#hardware-modification) section for information on adding RGB lighting to your keyboard. -Currently QMK supports the following addressable LEDs on AVR microcontrollers (however, the white LED in RGBW variants is not supported): +Currently QMK supports the following addressable LEDs (however, the white LED in RGBW variants is not supported): * WS2811, WS2812, WS2812B, WS2812C, etc. * SK6812, SK6812MINI, SK6805 @@ -48,12 +48,12 @@ Changing the **Value** sets the overall brightness.<br> |`RGB_TOG` | |Toggle RGB lighting on or off | |`RGB_MODE_FORWARD` |`RGB_MOD` |Cycle through modes, reverse direction when Shift is held | |`RGB_MODE_REVERSE` |`RGB_RMOD`|Cycle through modes in reverse, forward direction when Shift is held| -|`RGB_HUI` | |Increase hue | -|`RGB_HUD` | |Decrease hue | -|`RGB_SAI` | |Increase saturation | -|`RGB_SAD` | |Decrease saturation | -|`RGB_VAI` | |Increase value (brightness) | -|`RGB_VAD` | |Decrease value (brightness) | +|`RGB_HUI` | |Increase hue, decrease hue when Shift is held | +|`RGB_HUD` | |Decrease hue, increase hue when Shift is held | +|`RGB_SAI` | |Increase saturation, decrease saturation when Shift is held | +|`RGB_SAD` | |Decrease saturation, increase saturation when Shift is held | +|`RGB_VAI` | |Increase value (brightness), decrease value when Shift is held | +|`RGB_VAD` | |Decrease value (brightness), increase value 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` |Rainbow animation mode | @@ -363,8 +363,8 @@ Using the `rgblight_set_clipping_range()` function, you can prepare more buffers You can set the Clipping Range by executing the following code. ```c -// some soruce - rgblight_set_clipping_range(3, 4); +// some source +rgblight_set_clipping_range(3, 4); ``` <img src="https://user-images.githubusercontent.com/2170248/55743785-2bd82a00-5a6e-11e9-9d4b-1b4ffaf4932b.JPG" alt="clip direct" width="70%"/> diff --git a/docs/feature_tap_dance.md b/docs/feature_tap_dance.md index 7427a7714..f48f11b1c 100644 --- a/docs/feature_tap_dance.md +++ b/docs/feature_tap_dance.md @@ -333,6 +333,8 @@ And then simply use `TD(X_CTL)` anywhere in your keymap. If you want to implement this in your userspace, then you may want to check out how [DanielGGordon](https://github.com/qmk/qmk_firmware/tree/master/users/gordon) has implemented this in their userspace. +> 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 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`. diff --git a/docs/feature_userspace.md b/docs/feature_userspace.md index e162d423c..a2657c1f6 100644 --- a/docs/feature_userspace.md +++ b/docs/feature_userspace.md @@ -208,15 +208,15 @@ bool process_record_user(uint16_t keycode, keyrecord_t *record) { clear_mods(); clear_oneshot_mods(); SEND_STRING("make " QMK_KEYBOARD ":" QMK_KEYMAP); #ifndef FLASH_BOOTLOADER - if ( (temp_mod | temp_osm) & MOD_MASK_SHIFT ) + 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"); + if ((temp_mod | temp_osm) & MOD_MASK_CTRL) { + SEND_STRING(" -j8 --output-sync"); } - SEND_STRING(SS_TAP(X_ENTER)); + tap_code(KC_ENT); set_mods(temp_mod); } break; diff --git a/docs/flashing_bootloadhid.md b/docs/flashing_bootloadhid.md index c51d8ce4b..731d92772 100644 --- a/docs/flashing_bootloadhid.md +++ b/docs/flashing_bootloadhid.md @@ -13,7 +13,7 @@ General flashing sequence: ## bootloadHID Flashing Target -Using the QMK installation script, detailed [here](newbs_getting_started.md), the required bootloadHID tools should be automatically installed. +?> Using the QMK installation script, detailed [here](newbs_getting_started.md), the required bootloadHID tools should be automatically installed. To flash via the command line, use the target `:bootloadHID` by executing the following command: diff --git a/docs/fr-fr/README.md b/docs/fr-fr/README.md index d3591554b..4527ec4b4 100644 --- a/docs/fr-fr/README.md +++ b/docs/fr-fr/README.md @@ -19,7 +19,7 @@ Sinon, vous pouvez aussi le télécharger directement en ([zip](https://github.c ## Comment le compiler -Avant d'être prêt à compiler vous allez devoir [installer un environnement](getting_started_build_tools.md) pour les développements AVR et/ou ARM. Une fois ceci fait, vous pourrez utiliser la commande `make` pour compiler le clavier et la disposition avec une commande de ce type : +Avant d'être prêt à compiler vous allez devoir [installer un environnement](fr-fr/getting_started_build_tools.md) pour les développements AVR et/ou ARM. Une fois ceci fait, vous pourrez utiliser la commande `make` pour compiler le clavier et la disposition avec une commande de ce type : make planck/rev4:default @@ -29,4 +29,4 @@ Cette commande compilera la révision `rev4` du clavier `planck` avec la disposi ## Comment le personnaliser -QMK a beaucoup de [fonctionnalités](features.md) à explorer, et [une documentation](http://docs.qmk.fm) très abondante que vous pourrez parcourir. La plupart des fonctionnalités vous permettrons de modifier vos [dispositions](keymap.md) (keymaps) et de changer [les codes de caractères](keycodes.md) (keycodes). +QMK a beaucoup de [fonctionnalités](fr-fr/features.md) à explorer, et [une documentation](http://docs.qmk.fm) très abondante que vous pourrez parcourir. La plupart des fonctionnalités vous permettrons de modifier vos [dispositions](fr-fr/keymap.md) (keymaps) et de changer [les codes de caractères](fr-fr/keycodes.md) (keycodes). diff --git a/docs/fr-fr/_summary.md b/docs/fr-fr/_summary.md index eef486176..38e3abe7c 100644 --- a/docs/fr-fr/_summary.md +++ b/docs/fr-fr/_summary.md @@ -29,97 +29,97 @@ **En Anglais** * Guides détaillés - * [Installation des outils de compilation](getting_started_build_tools.md) - * [Guide Vagrant](getting_started_vagrant.md) - * [Commandes de compilations](getting_started_make_guide.md) + * [Installation des outils de compilation](fr-fr/getting_started_build_tools.md) + * [Guide Vagrant](fr-fr/getting_started_vagrant.md) + * [Commandes de compilations](fr-fr/getting_started_make_guide.md) * [Flasher les firmwares](fr-fr/flashing.md) - * [Personnaliser les fonctionnalités](custom_quantum_functions.md) - * [Aperçu des fonctionnalités des dispositions](keymap.md) + * [Personnaliser les fonctionnalités](fr-fr/custom_quantum_functions.md) + * [Aperçu des fonctionnalités des dispositions](fr-fr/keymap.md) -* [Hardware](hardware.md) - * [Processeurs AVR](hardware_avr.md) - * [Pilotes / Drivers](hardware_drivers.md) +* [Hardware](fr-fr/hardware.md) + * [Processeurs AVR](fr-fr/hardware_avr.md) + * [Pilotes / Drivers](fr-fr/hardware_drivers.md) * Réferences - * [Lignes de conduite des claviers](hardware_keyboard_guidelines.md) - * [Options de configurations](config_options.md) - * [Keycodes / Codes des caractères](keycodes.md) - * [Conventions de codage - C](coding_conventions_c.md) - * [Conventions de codage - Python](coding_conventions_python.md) - * [Meilleurs pratiques sur la documentation](documentation_best_practices.md) - * [Modèles de documentation](documentation_templates.md) - * [Glossaire](reference_glossary.md) - * [Tests unitaires](unit_testing.md) - * [Fonctions utiles](ref_functions.md) - * [Support de configuration](reference_configurator_support.md) - * [Format du fichier info.json](reference_info_json.md) - * [Développer la CLI en Python](cli_development.md) + * [Lignes de conduite des claviers](fr-fr/hardware_keyboard_guidelines.md) + * [Options de configurations](fr-fr/config_options.md) + * [Keycodes / Codes des caractères](fr-fr/keycodes.md) + * [Conventions de codage - C](fr-fr/coding_conventions_c.md) + * [Conventions de codage - Python](fr-fr/coding_conventions_python.md) + * [Meilleurs pratiques sur la documentation](fr-fr/documentation_best_practices.md) + * [Modèles de documentation](fr-fr/documentation_templates.md) + * [Glossaire](fr-fr/reference_glossary.md) + * [Tests unitaires](fr-fr/unit_testing.md) + * [Fonctions utiles](fr-fr/ref_functions.md) + * [Support de configuration](fr-fr/reference_configurator_support.md) + * [Format du fichier info.json](fr-fr/reference_info_json.md) + * [Développer la CLI en Python](fr-fr/cli_development.md) -* [Fonctionnalités](features.md) - * [Keycodes basiques](keycodes_basic.md) - * [Touches utilisées avec Shift (US ANSI)](keycodes_us_ansi_shifted.md) - * [Keycodes quantiques](quantum_keycodes.md) - * [Keycodes avancés](feature_advanced_keycodes.md) - * [Fonctionnalités audio](feature_audio.md) - * [Majuscule automatique](feature_auto_shift.md) - * [Rétroéclairage](feature_backlight.md) - * [Bluetooth](feature_bluetooth.md) - * [Bootmagic](feature_bootmagic.md) - * [Combos](feature_combo.md) - * [Commande](feature_command.md) - * [API anti-rebond](feature_debounce_type.md) - * [DIP Switch](feature_dip_switch.md) - * [Macros dynamiques](feature_dynamic_macros.md) - * [Interrupteurs rotatifs](feature_encoders.md) - * [Grave Escape](feature_grave_esc.md) - * [Retour haptique](feature_haptic_feedback.md) - * [Contrôleur LCD HD44780](feature_hd44780.md) - * [Touche à verrou / Lock-key](feature_key_lock.md) - * [Dispositions / layouts](feature_layouts.md) - * [Touche leader](feature_leader_key.md) - * [Matrice LED](feature_led_matrix.md) - * [Macros](feature_macros.md) - * [Boutons de souris](feature_mouse_keys.md) - * [Pilotes / Drivers OLED](feature_oled_driver.md) - * [Touche one-shot](feature_advanced_keycodes.md#one-shot-keys) - * [Périphériques de pointage](feature_pointing_device.md) - * [Souris PS/2](feature_ps2_mouse.md) - * [Éclairage RGB](feature_rgblight.md) - * [Matrice RGB](feature_rgb_matrix.md) - * [Space Cadet](feature_space_cadet.md) - * [Claviers scindés / splittés](feature_split_keyboard.md) - * [Stenographie](feature_stenography.md) - * [Inversion des mains](feature_swap_hands.md) - * [Tap Dance](feature_tap_dance.md) - * [Terminale](feature_terminal.md) - * [Imprimante thermique](feature_thermal_printer.md) - * [Caractères unicodes](feature_unicode.md) - * [Dossier utilisateur](feature_userspace.md) - * [Velocikey](feature_velocikey.md) +* [Fonctionnalités](fr-fr/features.md) + * [Keycodes basiques](fr-fr/keycodes_basic.md) + * [Touches utilisées avec Shift (US ANSI)](fr-fr/keycodes_us_ansi_shifted.md) + * [Keycodes quantiques](fr-fr/quantum_keycodes.md) + * [Keycodes avancés](fr-fr/feature_advanced_keycodes.md) + * [Fonctionnalités audio](fr-fr/feature_audio.md) + * [Majuscule automatique](fr-fr/feature_auto_shift.md) + * [Rétroéclairage](fr-fr/feature_backlight.md) + * [Bluetooth](fr-fr/feature_bluetooth.md) + * [Bootmagic](fr-fr/feature_bootmagic.md) + * [Combos](fr-fr/feature_combo.md) + * [Commande](fr-fr/feature_command.md) + * [API anti-rebond](fr-fr/feature_debounce_type.md) + * [DIP Switch](fr-fr/feature_dip_switch.md) + * [Macros dynamiques](fr-fr/feature_dynamic_macros.md) + * [Interrupteurs rotatifs](fr-fr/feature_encoders.md) + * [Grave Escape](fr-fr/feature_grave_esc.md) + * [Retour haptique](fr-fr/feature_haptic_feedback.md) + * [Contrôleur LCD HD44780](fr-fr/feature_hd44780.md) + * [Touche à verrou / Lock-key](fr-fr/feature_key_lock.md) + * [Dispositions / layouts](fr-fr/feature_layouts.md) + * [Touche leader](fr-fr/feature_leader_key.md) + * [Matrice LED](fr-fr/feature_led_matrix.md) + * [Macros](fr-fr/feature_macros.md) + * [Boutons de souris](fr-fr/feature_mouse_keys.md) + * [Pilotes / Drivers OLED](fr-fr/feature_oled_driver.md) + * [Touche one-shot](fr-fr/feature_advanced_keycodes.md#one-shot-keys) + * [Périphériques de pointage](fr-fr/feature_pointing_device.md) + * [Souris PS/2](fr-fr/feature_ps2_mouse.md) + * [Éclairage RGB](fr-fr/feature_rgblight.md) + * [Matrice RGB](fr-fr/feature_rgb_matrix.md) + * [Space Cadet](fr-fr/feature_space_cadet.md) + * [Claviers scindés / splittés](fr-fr/feature_split_keyboard.md) + * [Stenographie](fr-fr/feature_stenography.md) + * [Inversion des mains](fr-fr/feature_swap_hands.md) + * [Tap Dance](fr-fr/feature_tap_dance.md) + * [Terminale](fr-fr/feature_terminal.md) + * [Imprimante thermique](fr-fr/feature_thermal_printer.md) + * [Caractères unicodes](fr-fr/feature_unicode.md) + * [Dossier utilisateur](fr-fr/feature_userspace.md) + * [Velocikey](fr-fr/feature_velocikey.md) * Pour les makers et les bricoleurs - * [Guide des claviers soudés à la main](hand_wire.md) - * [Guide de flash de l’ISP](isp_flashing_guide.md) - * [Guide du débogage ARM](arm_debugging.md) - * [Drivers i2c](i2c_driver.md) - * [Contrôles des GPIO](internals_gpio_control.md) - * [Conversion en Proton C](proton_c_conversion.md) + * [Guide des claviers soudés à la main](fr-fr/hand_wire.md) + * [Guide de flash de l’ISP](fr-fr/isp_flashing_guide.md) + * [Guide du débogage ARM](fr-fr/arm_debugging.md) + * [Drivers i2c](fr-fr/i2c_driver.md) + * [Contrôles des GPIO](fr-fr/internals_gpio_control.md) + * [Conversion en Proton C](fr-fr/proton_c_conversion.md) * Pour aller plus loin - * [Comment fonctionnent les claviers](how_keyboards_work.md) - * [Comprendre QMK](understanding_qmk.md) + * [Comment fonctionnent les claviers](fr-fr/how_keyboards_work.md) + * [Comprendre QMK](fr-fr/understanding_qmk.md) * Autres sujets - * [Utiliser Eclipse avec QMK](other_eclipse.md) - * [Utiliser VSCode avec QMK](other_vscode.md) - * [Support](support.md) - * [Comment ajouter des traductions](translating.md) + * [Utiliser Eclipse avec QMK](fr-fr/other_eclipse.md) + * [Utiliser VSCode avec QMK](fr-fr/other_vscode.md) + * [Support](fr-fr/support.md) + * [Comment ajouter des traductions](fr-fr/translating.md) * À l’intérieur de QMK (En cours de documentation) - * [Définitions](internals_defines.md) - * [Input Callback Reg](internals_input_callback_reg.md) - * [Appareils Midi](internals_midi_device.md) - * [Installation d’un appareil Midi](internals_midi_device_setup_process.md) - * [Utilitaires Midi](internals_midi_util.md) - * [Fonctions Midi](internals_send_functions.md) - * [Outils Sysex](internals_sysex_tools.md) + * [Définitions](fr-fr/internals_defines.md) + * [Input Callback Reg](fr-fr/internals_input_callback_reg.md) + * [Appareils Midi](fr-fr/internals_midi_device.md) + * [Installation d’un appareil Midi](fr-fr/internals_midi_device_setup_process.md) + * [Utilitaires Midi](fr-fr/internals_midi_util.md) + * [Fonctions Midi](fr-fr/internals_send_functions.md) + * [Outils Sysex](fr-fr/internals_sysex_tools.md) diff --git a/docs/fr-fr/faq_build.md b/docs/fr-fr/faq_build.md index 774bf6880..84d88afcd 100644 --- a/docs/fr-fr/faq_build.md +++ b/docs/fr-fr/faq_build.md @@ -86,10 +86,6 @@ Relancer le script d'installation de QMK (`./util/qmk_install.sh` situé dans r Si vous rencontrez toujours des problèmes, essayez de télécharger et lancer Zadig. Voir [Installation du driver du bootloader avec Zadig](driver_installation_zadig.md) pour plus d'informations. -## WINAVR est obsolète - -Il n'est plus recommandé et peut causer des problèmes. Voir [TMK Issue #99](https://github.com/tmk/tmk_keyboard/issues/99). - ## USB VID et PID Vous pouvez utiliser l'ID de votre choix en modifier `config.h`. Il y a peu de chance de conflit avec d'autres produits. @@ -103,30 +99,6 @@ Vous pouvez acheter un VID:PID unique ici. Je ne pense pas que ce soit nécessai - http://www.obdev.at/products/vusb/license.html - http://www.mcselec.com/index.php?page=shop.product_details&flypage=shop.flypage&product_id=92&option=com_phpshop&Itemid=1 -## Cortex: `cstddef: No such file or directory` - -Ce problème existait avec le GCC 4.8 d'Ubuntu 14.04, la solution a nécessité de mettre à jour vers 4.9 avec ce PPA. -https://launchpad.net/~terry.guo/+archive/ubuntu/gcc-arm-embedded - -https://github.com/tmk/tmk_keyboard/issues/212 -https://github.com/tmk/tmk_keyboard/wiki/mbed-cortex-porting#compile-error-cstddef -https://developer.mbed.org/forum/mbed/topic/5205/ - -## `clock_prescale_set` and `clock_div_1` Not Available - -Votre chaîne d'outils (Toolchain) est trop vieille pour supporter le MCU. Par exemple, WinAVR 20100110 ne supporte pas ATMega32u2. - -``` -Compiling C: ../../tmk_core/protocol/lufa/lufa.c -avr-gcc -c -mmcu=atmega32u2 -gdwarf-2 -DF_CPU=16000000UL -DINTERRUPT_CONTROL_ENDPOINT -DBOOTLOADER_SIZE=4096 -DF_USB=16000000UL -DARCH=ARCH_AVR8 -DUSB_DEVICE_ONLY -DUSE_FLASH_DESCRIPTORS -DUSE_STATIC_OPTIONS="(USB_DEVICE_OPT_FULLSPEED | USB_OPT_REG_ENABLED | USB_OPT_AUTO_PLL)" -DFIXED_CONTROL_ENDPOINT_SIZE=8 -DFIXED_NUM_CONFIGURATIONS=1 -DPROTOCOL_LUFA -DEXTRAKEY_ENABLE -DCONSOLE_ENABLE -DCOMMAND_ENABLE -DVERSION=unknown -Os -funsigned-char -funsigned-bitfields -ffunction-sections -fdata-sections -fno-inline-small-functions -fpack-struct -fshort-enums -fno-strict-aliasing -Wall -Wstrict-prototypes -Wa,-adhlns=obj_alps64/protocol/lufa/lufa.lst -I. -I../../tmk_core -I../../tmk_core/protocol/lufa -I../../tmk_core/protocol/lufa/LUFA-git -I../../tmk_core/common -std=gnu99 -include config.h -MMD -MP -MF .dep/obj_alps64_protocol_lufa_lufa.o.d ../../tmk_core/protocol/lufa/lufa.c -o obj_alps64/protocol/lufa/lufa.o -../../tmk_core/protocol/lufa/lufa.c: In function 'setup_mcu': -../../tmk_core/protocol/lufa/lufa.c:575: warning: implicit declaration of function 'clock_prescale_set' -../../tmk_core/protocol/lufa/lufa.c:575: error: 'clock_div_1' undeclared (first use in this function) -../../tmk_core/protocol/lufa/lufa.c:575: error: (Each undeclared identifier is reported only once -../../tmk_core/protocol/lufa/lufa.c:575: error: for each function it appears in.) -make: *** [obj_alps64/protocol/lufa/lufa.o] Error 1 -``` - ## BOOTLOADER_SIZE pour AVR Notez que la taille du bootloader pour les Teensy2.0++ est de 2048bytes. Quelques Makefiles peuvent contenir une erreur et avoir le mauvais commentaire. diff --git a/docs/fr-fr/faq_debug.md b/docs/fr-fr/faq_debug.md index 7a85fd1f2..754c79921 100644 --- a/docs/fr-fr/faq_debug.md +++ b/docs/fr-fr/faq_debug.md @@ -104,58 +104,6 @@ En C, `1` implique un type [int] qui est [16 bits] pour les AVR, ce qui implique http://deskthority.net/workshop-f7/rebuilding-and-redesigning-a-classic-thinkpad-keyboard-t6181-60.html#p146279 -## Bootloader Jump ne fonctionne pas - -Configurez correctement la taille du bootloader dans le **Makefile**. Une mauvaise taille de section du bootloader empêchera probablement le démarrage avec **Magic command** et **Boot Magic**. - -``` -# Size of Bootloaders in bytes: -# Atmel DFU loader(ATmega32U4) 4096 -# Atmel DFU loader(AT90USB128) 8192 -# LUFA bootloader(ATmega32U4) 4096 -# Arduino Caterina(ATmega32U4) 4096 -# USBaspLoader(ATmega***) 2048 -# Teensy halfKay(ATmega32U4) 512 -# Teensy++ halfKay(AT90USB128) 2048 -OPT_DEFS += -DBOOTLOADER_SIZE=4096 -``` - -La taille de la section de démarrage de AVR est définie par l'option **BOOTSZ** fuse. Vérifiez la fiche technique du MCU. Veuilez noter que les tailles et adresses sont définies en **Word** (2 octets) dans la fiche technique alors que TMK utilise des **Byte**. - -La section de boot AVR se trouve à la fin de la mémoire flash, comme suit. - -``` -byte Atmel/LUFA(ATMega32u4) byte Atmel(AT90SUB1286) -0x0000 +---------------+ 0x00000 +---------------+ - | | | | - | | | | - | Application | | Application | - | | | | - = = = = - | | 32KB-4KB | | 128KB-8KB -0x6000 +---------------+ 0x1E000 +---------------+ - | Bootloader | 4KB | Bootloader | 8KB -0x7FFF +---------------+ 0x1FFFF +---------------+ - - -byte Teensy(ATMega32u4) byte Teensy++(AT90SUB1286) -0x0000 +---------------+ 0x00000 +---------------+ - | | | | - | | | | - | Application | | Application | - | | | | - = = = = - | | 32KB-512B | | 128KB-2KB -0x7E00 +---------------+ 0x1FC00 +---------------+ - | Bootloader | 512B | Bootloader | 2KB -0x7FFF +---------------+ 0x1FFFF +---------------+ -``` - -Référez-vous à cette discussion pour plus de référence. -https://github.com/tmk/tmk_keyboard/issues/179 - -Si vous utilisez un TeensyUSB, il y a un [bug connu](https://github.com/qmk/qmk_firmware/issues/164) qui fait que le bouton reset matériel empêche la touche RESET de fonctionner. Débrancher et rebrancher le clavier devrait résoudre le problème. - ## Les touches spéciales ne fonctionnent pas (Touche Système, Touches de contrôle du son) Vous devez définir `EXTRAKEY_ENABLE` dans le fichier `rules.mk` pour les utiliser dans QMK. @@ -189,25 +137,6 @@ Si vous voulez garder JTAG activé, ajoutez la ligne suivante à votre fichier ` #define NO_JTAG_DISABLE ``` -## Adding LED Indicators of Lock Keys - -Si vous souhaitez votre propre indicateur LED pour CapsLock, ScrollLock et NumLock alors lisez ce post. - -http://deskthority.net/workshop-f7/tmk-keyboard-firmware-collection-t4478-120.html#p191560 - -## Programmer Arduino Micro/Leonardo - -Appuyez sur le bouton reset puis lancez la commande suivante dans les 8 secondes. - -``` -avrdude -patmega32u4 -cavr109 -b57600 -Uflash:w:adb_usb.hex -P/dev/ttyACM0 -``` - -Le nom du périphérique peut varier en fonction de votre système. - -http://arduino.cc/en/Main/ArduinoBoardMicro -https://geekhack.org/index.php?topic=14290.msg1563867#msg1563867 - ## Compatibilité USB 3 Il semble que certaines personnes ont eu des problèmes avec les ports USB 3, essayez un port USB 2. diff --git a/docs/fr-fr/faq_keymap.md b/docs/fr-fr/faq_keymap.md index 8244d4225..2cbbe9308 100644 --- a/docs/fr-fr/faq_keymap.md +++ b/docs/fr-fr/faq_keymap.md @@ -72,24 +72,7 @@ Des vieux claviers mécaniques ont parfois des touches à verrouillage, mais les ## Ajouter des caractères spéciaux autres que ASCII comme la cédille 'Ç' -IL N'EXISTE AUCUNE METHODE UNIVERSELLE POUR LES AJOUTER QUI FONCTIONNE SUR TOUS LES SYSTEMES. Vous devez définir une **MACRO** d'une manière spécifique à votre OS ou layout. - -Voir ce post pour un exemple de code **MACRO**. - -http://deskthority.net/workshop-f7/tmk-keyboard-firmware-collection-t4478-120.html#p195620 - -Sous **Windows** vous pouvez utiliser la touche `AltGr` ou **Alt code**. -* http://en.wikipedia.org/wiki/AltGr_key -* http://en.wikipedia.org/wiki/Alt_code - -Sous **Mac OS** définissez une combinaison de touche `Option`. -* http://en.wikipedia.org/wiki/Option_key#Alternative_keyboard_input - -Sous **Xorg** vous pouvez utiliser une touche `compose` à la place. -* http://en.wikipedia.org/wiki/Compose_key - -Et voir ceci pour une entrée **Unicode**. -* http://en.wikipedia.org/wiki/Unicode_input +Voir la fonctionnalité [Unicode](feature_unicode.md). ## Touche `Fn` sur macOS @@ -144,54 +127,6 @@ Cette fonctionnalité permet d'utiliser une touche à la fois comme touche Écha Voir la fonctionnalité [Grave Escape](feature_grave_esc.md). -## Avoir les touches modificatrices qui ont double usage en flèches directionnelles. - -Ceci transforme les touches "modificateur droit" en touches fléchées lorsque les touches sont seulement "tapées" tout en restant des modificateurs lorsqu'elles sont maintenues. - -Dans TMK la fonction double rôle s'appelle **TAP**. - -```C - -#include "keymap_common.h" - - -/* Arrow keys on right modifier keys with TMK dual role feature - * - * https://github.com/tmk/tmk_core/blob/master/doc/keymap.md#213-modifier-with-tap-keydual-role - * https://en.wikipedia.org/wiki/Modifier_key#Dual-role_keys - */ -const uint8_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] = { - /* 0: qwerty */ - [0] = LAYOUT( \ - ESC, 1, 2, 3, 4, 5, 6, 7, 8, 9, 0, MINS,EQL, NUHS,BSPC, \ - TAB, Q, W, E, R, T, Y, U, I, O, P, LBRC,RBRC,BSLS, \ - LCTL,A, S, D, F, G, H, J, K, L, SCLN,QUOT,ENT, \ - LSFT,NUBS,Z, X, C, V, B, N, M, COMM,DOT, SLSH,FN0, ESC, \ - FN4, LGUI,LALT, SPC, APP, FN2, FN1, FN3), - [1] = LAYOUT( \ - GRV, F1, F2, F3, F4, F5, F6, F7, F8, F9, F10, F11, F12, TRNS,TRNS, \ - TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,\ - TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS, \ - TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,FN5, TRNS, \ - TRNS,TRNS,TRNS, TRNS, TRNS,FN7, FN6, FN8), -}; - -const uint16_t PROGMEM fn_actions[] = { - [0] = ACTION_MODS_TAP_KEY(MOD_RSFT, KC_UP), - [1] = ACTION_MODS_TAP_KEY(MOD_RGUI, KC_DOWN), - [2] = ACTION_MODS_TAP_KEY(MOD_RALT, KC_LEFT), - [3] = ACTION_MODS_TAP_KEY(MOD_RCTL, KC_RIGHT), - [4] = ACTION_LAYER_MOMENTARY(1), - [5] = ACTION_MODS_TAP_KEY(MOD_RSFT, KC_PGUP), - [6] = ACTION_MODS_TAP_KEY(MOD_RGUI, KC_PGDN), - [7] = ACTION_MODS_TAP_KEY(MOD_RALT, KC_HOME), - [8] = ACTION_MODS_TAP_KEY(MOD_RCTL, KC_END), -}; - -``` - -Touches double rôle : https://en.wikipedia.org/wiki/Modifier_key#Dual-role_keys - ## Eject sur Mac OSX Le keycode`KC_EJCT` fonctionne sous OSX. https://github.com/tmk/tmk_keyboard/issues/250 diff --git a/docs/getting_started_build_tools.md b/docs/getting_started_build_tools.md index a55e903a6..2721a9a03 100644 --- a/docs/getting_started_build_tools.md +++ b/docs/getting_started_build_tools.md @@ -112,21 +112,6 @@ The Toolchain setup is done through the Windows Subsystem for Linux, and the pro * The WSL Git is **not** compatible with the Windows Git, so use the Windows Git Bash or a windows Git GUI for all Git operations * You can edit files either inside WSL or normally using Windows, but note that if you edit makefiles or shell scripts, make sure you are using an editor that saves the files with Unix line endings. Otherwise the compilation might not work. -## Windows (Vista and Later) (Deprecated) - -These are the old instructions for Windows Vista and later. We recommend you use [MSYS2 as outlined above](#windows-with-msys2-recommended). - -1. If you have ever installed WinAVR, uninstall it. -2. Install [MHV AVR Tools](https://infernoembedded.com/sites/default/files/project/MHV_AVR_Tools_20131101.exe). Disable smatch, but **be sure to leave the option to add the tools to the PATH checked**. -3. If you are going to flash Infinity based keyboards you will need to install dfu-util, refer to the instructions by [Input Club](https://github.com/kiibohd/controller/wiki/Loading-DFU-Firmware). -4. Install [MinGW](https://sourceforge.net/projects/mingw/files/Installer/mingw-get-setup.exe/download). During installation, uncheck the option to install a graphical user interface. **DO NOT change the default installation folder.** The scripts depend on the default location. -5. Clone this repository. [This link will download it as a zip file, which you'll need to extract.](https://github.com/qmk/qmk_firmware/archive/master.zip) Open the extracted folder in Windows Explorer. -6. Open the `\util` folder. -7. Double-click on the `1-setup-path-win` batch script to run it. You'll need to accept a User Account Control prompt. Press the spacebar to dismiss the success message in the command prompt that pops up. -8. Right-click on the `2-setup-environment-win` batch script, select "Run as administrator", and accept the User Account Control prompt. This part may take a couple of minutes, and you'll need to approve a driver installation, but once it finishes, your environment is complete! - -If you have trouble and want to ask for help, it is useful to generate a *Win_Check_Output.txt* file by running `Win_Check.bat` in the `\util` folder. - ## Docker If this is a bit complex for you, Docker might be the turnkey solution you need. After installing [Docker CE](https://docs.docker.com/install/#supported-platforms), run the following command from the `qmk_firmware` directory to build a keyboard/keymap: diff --git a/docs/getting_started_github.md b/docs/getting_started_github.md index aeb8738b7..629f4ece2 100644 --- a/docs/getting_started_github.md +++ b/docs/getting_started_github.md @@ -19,7 +19,7 @@ And be sure to select "HTTPS", and select the link and copy it: From here, enter `git clone ` into the command line, and then paste your link: ``` -user@computer:~$ git clone https://github.com/whoeveryouare/qmk_firmware.git +user@computer:~$ git clone --recurse-submodules https://github.com/whoeveryouare/qmk_firmware.git Cloning into 'qmk_firmware'... remote: Counting objects: 46625, done. remote: Compressing objects: 100% (2/2), done. diff --git a/docs/getting_started_introduction.md b/docs/getting_started_introduction.md index e183d77ee..6dc51b82b 100644 --- a/docs/getting_started_introduction.md +++ b/docs/getting_started_introduction.md @@ -4,7 +4,7 @@ This page attempts to explain the basic information you need to know to work wit ## Basic QMK Structure -QMK is a fork of [Jun Wako](https://github.com/tmk)'s [tmk_keyboard](https://github.com/tmk/tmk_keyboard) project. The original TMK code, with modifications, can be found in the `tmk` folder. The QMK additions to the project may be found in the `quantum` folder. Keyboard projects may be found in the `handwired` and `keyboard` folders. +QMK is a fork of [Jun Wako](https://github.com/tmk)'s [tmk_keyboard](https://github.com/tmk/tmk_keyboard) project. The original TMK code, with modifications, can be found in the `tmk_core` folder. The QMK additions to the project may be found in the `quantum` folder. Keyboard projects may be found in the `handwired` and `keyboard` folders. ### Userspace Structure diff --git a/docs/getting_started_make_guide.md b/docs/getting_started_make_guide.md index d2596b2e2..bf8d472d0 100644 --- a/docs/getting_started_make_guide.md +++ b/docs/getting_started_make_guide.md @@ -59,7 +59,7 @@ To disable debug messages (*dprint*) and reduce the .hex file size, include `#de To disable print messages (*print*, *xprintf*) and user print messages (*uprint*) and reduce the .hex file size, include `#define NO_PRINT` in your `config.h` file. -To disable print messages (*print*, *xprintf*) and **KEEP** user print messages (*uprint*), include `#define USER_PRINT` in your `config.h` file. +To disable print messages (*print*, *xprintf*) and **KEEP** user print messages (*uprint*), include `#define USER_PRINT` in your `config.h` file (do not also include `#define NO_PRINT` in this case). To see the text, open `hid_listen` and enjoy looking at your printed messages. diff --git a/docs/hardware_drivers.md b/docs/hardware_drivers.md index 321ba2a4b..165187795 100644 --- a/docs/hardware_drivers.md +++ b/docs/hardware_drivers.md @@ -22,7 +22,7 @@ Support for SSD1306 based OLED displays. For more information see the [OLED Driv You can make use of uGFX within QMK to drive character and graphic LCDs, LED arrays, OLED, TFT, and other display technologies. This needs to be better documented, if you are trying to do this and reading the code doesn't help please [open an issue](https://github.com/qmk/qmk_firmware/issues/new) and we can help you through the process. -## WS2812 (AVR Only) +## WS2812 Support for WS2811/WS2812{a,b,c} LED's. For more information see the [RGB Light](feature_rgblight.md) page. diff --git a/docs/he-il/README.md b/docs/he-il/README.md index db0ad43c3..8e0c470b4 100644 --- a/docs/he-il/README.md +++ b/docs/he-il/README.md @@ -20,7 +20,7 @@ QMK (*Quantum Mechanical Keyboard*) היא קהילת קוד פתוח (open sour ## איך לקמפל -לפני שתצליחו לקמפל, תדרשו [להתקין סביבה](getting_started_build_tools.md) עבור פיתוח AVR ו/או ARM. ברגע שהדבר בוצע, תוכלו להריץ פקודת `make` כדי לבנות מקלדת ומיפוי עם התחביר הבא: +לפני שתצליחו לקמפל, תדרשו [להתקין סביבה](he-il/getting_started_build_tools.md) עבור פיתוח AVR ו/או ARM. ברגע שהדבר בוצע, תוכלו להריץ פקודת `make` כדי לבנות מקלדת ומיפוי עם התחביר הבא: make planck/rev4:default @@ -30,5 +30,5 @@ QMK (*Quantum Mechanical Keyboard*) היא קהילת קוד פתוח (open sour ## איך להתאים -לQMK יש המון [יכולות](features.md) שאפשר לנווט בהן, וכמות נכבדת של [תיעוד ודוקומנטציה](http://docs.qmk.fm) בה אפשר לנבור. רוב הפיצ׳רים באים לידי ביטוי על ידי שינוי [מיפוי המקלדת](keymap.md) ושינוי [קודי המקשים](keycodes.md). +לQMK יש המון [יכולות](he-il/features.md) שאפשר לנווט בהן, וכמות נכבדת של [תיעוד ודוקומנטציה](http://docs.qmk.fm) בה אפשר לנבור. רוב הפיצ׳רים באים לידי ביטוי על ידי שינוי [מיפוי המקלדת](he-il/keymap.md) ושינוי [קודי המקשים](he-il/keycodes.md). </div> diff --git a/docs/he-il/_summary.md b/docs/he-il/_summary.md index acc0546d0..804db534a 100644 --- a/docs/he-il/_summary.md +++ b/docs/he-il/_summary.md @@ -1,6 +1,7 @@ <div dir="rtl" markdown="1"> + **בשפה העברית** -* [המדריך המלא למתחילים](newbs.md) +* [המדריך המלא למתחילים](he-il/newbs.md) * [מקורות ללמידה](he-il/newbs_learn_more_resources.md) * [בסיס QMK](he-il/README.md) * [מבוא לQMK](he-il/getting_started_introduction.md) @@ -13,126 +14,126 @@ * [איך לתעד נכון](he-il/documentation_best_practices.md) **בשפה האנגלית** -* [המדריך המלא למתחילים](newbs.md) - * [התחלה](newbs_getting_started.md) - * [בנייה של הקושחה הראשונה שלך](newbs_building_firmware.md) - * [צריבה של הקושחה](newbs_flashing.md) - * [בדיקות ודיבאגינג](newbs_testing_debugging.md) - * [עבודה נכונה ב GIT](newbs_best_practices.md) - * [מקורות ללמידה](newbs_learn_more_resources.md) +* [המדריך המלא למתחילים](he-il/newbs.md) + * [התחלה](he-il/newbs_getting_started.md) + * [בנייה של הקושחה הראשונה שלך](he-il/newbs_building_firmware.md) + * [צריבה של הקושחה](he-il/newbs_flashing.md) + * [בדיקות ודיבאגינג](he-il/newbs_testing_debugging.md) + * [עבודה נכונה ב GIT](he-il/newbs_best_practices.md) + * [מקורות ללמידה](he-il/newbs_learn_more_resources.md) -* [בסיס QMK](README.md) - * [מבוא לQMK](getting_started_introduction.md) - * [QMK CLI](cli.md) - * [QMK CLI Config](cli_configuration.md) - * [תרומה ל QMK](contributing.md) - * [איך להשתמש בGithub](getting_started_github.md) - * [קבלת עזרה](getting_started_getting_help.md) +* [בסיס QMK](he-il/README.md) + * [מבוא לQMK](he-il/getting_started_introduction.md) + * [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) + * [קבלת עזרה](he-il/getting_started_getting_help.md) -* [שינויים משמעותיים](breaking_changes.md) - * [2019 Aug 30](ChangeLog/20190830.md) +* [שינויים משמעותיים](he-il/breaking_changes.md) + * [2019 Aug 30](he-il/ChangeLog/20190830.md) -* [שאלות נפוצות](faq.md) - * [שאלות נפוצות כלליות](faq_general.md) - * [בנייה/קומפילציה של QMK](faq_build.md) - * [דיבאגינג ופתרון תקלות של QMK](faq_debug.md) - * [מיפוי מקשים](faq_keymap.md) - * [התקנת דרייברים עם Zadig](driver_installation_zadig.md) +* [שאלות נפוצות](he-il/faq.md) + * [שאלות נפוצות כלליות](he-il/faq_general.md) + * [בנייה/קומפילציה של QMK](he-il/faq_build.md) + * [דיבאגינג ופתרון תקלות של QMK](he-il/faq_debug.md) + * [מיפוי מקשים](he-il/faq_keymap.md) + * [התקנת דרייברים עם Zadig](he-il/driver_installation_zadig.md) * מדריכים מפורטים - * [התקנת כלי Build](getting_started_build_tools.md) - * [מדריך Vagrant](getting_started_vagrant.md) - * [הוראות בנייה/קומפילציה](getting_started_make_guide.md) - * [צריבת קושחה](flashing.md) - * [התאמה אישית של הפונקציונאליות](custom_quantum_functions.md) - * [מיפוי מקשים](keymap.md) + * [התקנת כלי Build](he-il/getting_started_build_tools.md) + * [מדריך Vagrant](he-il/getting_started_vagrant.md) + * [הוראות בנייה/קומפילציה](he-il/getting_started_make_guide.md) + * [צריבת קושחה](he-il/flashing.md) + * [התאמה אישית של הפונקציונאליות](he-il/custom_quantum_functions.md) + * [מיפוי מקשים](he-il/keymap.md) -* [חומרה](hardware.md) - * [מעבדי AVR](hardware_avr.md) - * [דרייברים](hardware_drivers.md) +* [חומרה](he-il/hardware.md) + * [מעבדי AVR](he-il/hardware_avr.md) + * [דרייברים](he-il/hardware_drivers.md) * התייחסויות - * [מדריך למקלדות](hardware_keyboard_guidelines.md) - * [אפשרויות הגדרות](config_options.md) - * [קודי מקשים](keycodes.md) - * [קונבנציות קוד - C](coding_conventions_c.md) - * [קונבנציות קוד - Python](coding_conventions_python.md) - * [איך לתעד נכון](documentation_best_practices.md) - * [טמפלטים לדוקומנטציה](documentation_templates.md) - * [מילון](reference_glossary.md) - * [בדיקות יחידה](unit_testing.md) - * [פונקציות שימושיות](ref_functions.md) - * [תמיכה בConfigurator](reference_configurator_support.md) - * [פורמט info.json](reference_info_json.md) - * [פיתוח בPython CLI](cli_development.md) + * [מדריך למקלדות](he-il/hardware_keyboard_guidelines.md) + * [אפשרויות הגדרות](he-il/config_options.md) + * [קודי מקשים](he-il/keycodes.md) + * [קונבנציות קוד - C](he-il/coding_conventions_c.md) + * [קונבנציות קוד - Python](he-il/coding_conventions_python.md) + * [איך לתעד נכון](he-il/documentation_best_practices.md) + * [טמפלטים לדוקומנטציה](he-il/documentation_templates.md) + * [מילון](he-il/reference_glossary.md) + * [בדיקות יחידה](he-il/unit_testing.md) + * [פונקציות שימושיות](he-il/ref_functions.md) + * [תמיכה בConfigurator](he-il/reference_configurator_support.md) + * [פורמט info.json](he-il/reference_info_json.md) + * [פיתוח בPython CLI](he-il/cli_development.md) -* [תכונות](features.md) - * [Basic Keycodes](keycodes_basic.md) - * [US ANSI Shifted Keys](keycodes_us_ansi_shifted.md) - * [Quantum Keycodes](quantum_keycodes.md) - * [Advanced Keycodes](feature_advanced_keycodes.md) - * [Audio](feature_audio.md) - * [Auto Shift](feature_auto_shift.md) - * [Backlight](feature_backlight.md) - * [Bluetooth](feature_bluetooth.md) - * [Bootmagic](feature_bootmagic.md) - * [Combos](feature_combo.md) - * [Command](feature_command.md) - * [Debounce API](feature_debounce_type.md) - * [DIP Switch](feature_dip_switch.md) - * [Dynamic Macros](feature_dynamic_macros.md) - * [Encoders](feature_encoders.md) - * [Grave Escape](feature_grave_esc.md) - * [Haptic Feedback](feature_haptic_feedback.md) - * [HD44780 LCD Controller](feature_hd44780.md) - * [Key Lock](feature_key_lock.md) - * [Layouts](feature_layouts.md) - * [Leader Key](feature_leader_key.md) - * [LED Matrix](feature_led_matrix.md) - * [Macros](feature_macros.md) - * [Mouse Keys](feature_mouse_keys.md) - * [OLED Driver](feature_oled_driver.md) - * [One Shot Keys](feature_advanced_keycodes.md#one-shot-keys) - * [Pointing Device](feature_pointing_device.md) - * [PS/2 Mouse](feature_ps2_mouse.md) - * [RGB Lighting](feature_rgblight.md) - * [RGB Matrix](feature_rgb_matrix.md) - * [Space Cadet](feature_space_cadet.md) - * [Split Keyboard](feature_split_keyboard.md) - * [Stenography](feature_stenography.md) - * [Swap Hands](feature_swap_hands.md) - * [Tap Dance](feature_tap_dance.md) - * [Terminal](feature_terminal.md) - * [Thermal Printer](feature_thermal_printer.md) - * [Unicode](feature_unicode.md) - * [Userspace](feature_userspace.md) - * [Velocikey](feature_velocikey.md) +* [תכונות](he-il/features.md) + * [Basic Keycodes](he-il/keycodes_basic.md) + * [US ANSI Shifted Keys](he-il/keycodes_us_ansi_shifted.md) + * [Quantum Keycodes](he-il/quantum_keycodes.md) + * [Advanced Keycodes](he-il/feature_advanced_keycodes.md) + * [Audio](he-il/feature_audio.md) + * [Auto Shift](he-il/feature_auto_shift.md) + * [Backlight](he-il/feature_backlight.md) + * [Bluetooth](he-il/feature_bluetooth.md) + * [Bootmagic](he-il/feature_bootmagic.md) + * [Combos](he-il/feature_combo.md) + * [Command](he-il/feature_command.md) + * [Debounce API](he-il/feature_debounce_type.md) + * [DIP Switch](he-il/feature_dip_switch.md) + * [Dynamic Macros](he-il/feature_dynamic_macros.md) + * [Encoders](he-il/feature_encoders.md) + * [Grave Escape](he-il/feature_grave_esc.md) + * [Haptic Feedback](he-il/feature_haptic_feedback.md) + * [HD44780 LCD Controller](he-il/feature_hd44780.md) + * [Key Lock](he-il/feature_key_lock.md) + * [Layouts](he-il/feature_layouts.md) + * [Leader Key](he-il/feature_leader_key.md) + * [LED Matrix](he-il/feature_led_matrix.md) + * [Macros](he-il/feature_macros.md) + * [Mouse Keys](he-il/feature_mouse_keys.md) + * [OLED Driver](he-il/feature_oled_driver.md) + * [One Shot Keys](he-il/feature_advanced_keycodes.md#one-shot-keys) + * [Pointing Device](he-il/feature_pointing_device.md) + * [PS/2 Mouse](he-il/feature_ps2_mouse.md) + * [RGB Lighting](he-il/feature_rgblight.md) + * [RGB Matrix](he-il/feature_rgb_matrix.md) + * [Space Cadet](he-il/feature_space_cadet.md) + * [Split Keyboard](he-il/feature_split_keyboard.md) + * [Stenography](he-il/feature_stenography.md) + * [Swap Hands](he-il/feature_swap_hands.md) + * [Tap Dance](he-il/feature_tap_dance.md) + * [Terminal](he-il/feature_terminal.md) + * [Thermal Printer](he-il/feature_thermal_printer.md) + * [Unicode](he-il/feature_unicode.md) + * [Userspace](he-il/feature_userspace.md) + * [Velocikey](he-il/feature_velocikey.md) * למייקרים ומודרים - * [מדריך לכתיבה ידנית](hand_wire.md) - * [מדריך לצריבת ISP](isp_flashing_guide.md) - * [מדריך לדיבאגינג ARM](arm_debugging.md) - * [מנהל התקן I2C](i2c_driver.md) - * [בקרת GPIO](internals_gpio_control.md) - * [המרת Proton C](proton_c_conversion.md) + * [מדריך לכתיבה ידנית](he-il/hand_wire.md) + * [מדריך לצריבת ISP](he-il/isp_flashing_guide.md) + * [מדריך לדיבאגינג ARM](he-il/arm_debugging.md) + * [מנהל התקן I2C](he-il/i2c_driver.md) + * [בקרת GPIO](he-il/internals_gpio_control.md) + * [המרת Proton C](he-il/proton_c_conversion.md) * להבנה עמוקה יותר - * [איך עובדות מקלדות](how_keyboards_work.md) - * [להבין את QMK](understanding_qmk.md) + * [איך עובדות מקלדות](he-il/how_keyboards_work.md) + * [להבין את QMK](he-il/understanding_qmk.md) * נושאים נוספים - * [שימוש ב - Eclipse עם QMK](other_eclipse.md) - * [שימוש ב - VSCode עם QMK](other_vscode.md) - * [תמיכה](support.md) - * [כיצד להוסיף תרגום](translating.md) + * [שימוש ב - Eclipse עם QMK](he-il/other_eclipse.md) + * [שימוש ב - VSCode עם QMK](he-il/other_vscode.md) + * [תמיכה](he-il/support.md) + * [כיצד להוסיף תרגום](he-il/translating.md) * QMK מבפנים (בתהליך) - * [Defines](internals_defines.md) - * [Input Callback Reg](internals_input_callback_reg.md) - * [Midi Device](internals_midi_device.md) - * [Midi Device Setup Process](internals_midi_device_setup_process.md) - * [Midi Util](internals_midi_util.md) - * [Send Functions](internals_send_functions.md) - * [Sysex Tools](internals_sysex_tools.md) + * [Defines](he-il/internals_defines.md) + * [Input Callback Reg](he-il/internals_input_callback_reg.md) + * [Midi Device](he-il/internals_midi_device.md) + * [Midi Device Setup Process](he-il/internals_midi_device_setup_process.md) + * [Midi Util](he-il/internals_midi_util.md) + * [Send Functions](he-il/internals_send_functions.md) + * [Sysex Tools](he-il/internals_sysex_tools.md) </div> diff --git a/docs/index.html b/docs/index.html index 0cee19ecd..8d03c6ede 100644 --- a/docs/index.html +++ b/docs/index.html @@ -21,7 +21,7 @@ <div id="app"></div> <script> window.$docsify = { - alias : { + alias: { '/en/(.*)': '/$1', '/en-us/(.*)': '/$1', '/en-gb/(.*)': '/$1', @@ -29,23 +29,47 @@ }, basePath: '/', name: 'QMK Firmware', - nameLink: '/', + nameLink: { + '/de/': '/#/de/', + '/es/': '/#/es/', + '/fr-fr/': '/#/fr-fr/', + '/he-il/': '/#/he-il/', + '/ja/': '/#/ja/', + '/pt-br/': '/#/pt-br/', + '/ru-ru/': '/#/ru-ru/', + '/zh-cn/': '/#/zh-cn/', + '/': '/#/' + }, repo: 'qmk/qmk_firmware', loadSidebar: '_summary.md', loadNavbar: '_langs.md', mergeNavbar: true, auto2top: true, + fallbackLanguages: [ + 'de', + 'es', + 'fr-fr', + 'he-il', + 'ja', + 'pt-br', + 'ru-ru', + 'zh-cn' + ], formatUpdated: '{YYYY}/{MM}/{DD} {HH}:{mm}', search: { paths: 'auto', placeholder: { '/es/': 'Buscar', '/zh-cn/': '搜索', + '/ja/': '検索', + '/pt-br/': 'Busca', '/': 'Search' }, noData: { '/es/': '¡Ningún resultado!', '/zh-cn/': '没有结果!', + '/ja/': '見つかりません!', + '/pt-br/': 'Nenhum resultado!', '/': 'No results!' }, depth: 6 diff --git a/docs/ja/README.md b/docs/ja/README.md new file mode 100644 index 000000000..9b715ec0f --- /dev/null +++ b/docs/ja/README.md @@ -0,0 +1,37 @@ +# Quantum Mechanical Keyboard Firmware + +<!--- + original document: eae21eed7:docs/README.md + git diff eae21eed7 HEAD docs/README.md | cat +--> + +[](https://github.com/qmk/qmk_firmware/tags) +[](https://travis-ci.org/qmk/qmk_firmware) +[](https://discord.gg/Uq7gcHh) +[](https://docs.qmk.fm) +[](https://github.com/qmk/qmk_firmware/pulse/monthly) +[](https://github.com/qmk/qmk_firmware/) + +## QMK ファームウェアとは何か？ + +QMK (*Quantum Mechanical Keyboard*)は QMK ファームウェア、QMK ツールボックス、qmk.fm およびそれらのドキュメントを保守するオープンソースコミュニティです。QMK ファームウェアは[tmk\_keyboard](http://github.com/tmk/tmk_keyboard) を元にしたキーボードファームウェアで、Atmel AVR コントローラ、より具体的には [OLKB 製品](http://olkb.com)、[ErgoDox EZ](http://www.ergodox-ez.com) キーボードおよび [Clueboard 製品](http://clueboard.co/) のための幾つかの便利な機能を持ちます。また、ChibiOS を使って ARM チップに移植されています。これを使ってあなたの作った手配線のキーボードあるいはカスタムキーボード PCB で作ったキーボードを動かすことができます。 + +## 入手方法 + +QMK のキーマップ、キーボード、機能に貢献をする予定がある場合、最も簡単なのは、[Github を介してリポジトリをフォークし](https://github.com/qmk/qmk_firmware#fork-destination-box)、リポジトリをあなたの開発環境にクローンして変更を加え、それらをプッシュし、[プルリクエスト](https://github.com/qmk/qmk_firmware/pulls)を開くことです。 + +それ以外の場合は、`git clone https://github.com/qmk/qmk_firmware` を介して直接クローンすることができます。zip または tar ファイルをダウンロードしないでください。コンパイルするためのサブモジュールをダウンロードするために git リポジトリが必要です。 + +## コンパイル方法 + +コンパイルをする前に、AVR または ARM 開発のための[環境をインストール](ja/getting_started_build_tools.md)する必要があります。それが完了したら、`make` コマンドを使用して、以下の表記でキーボードとキーマップをビルドします。 + + make planck/rev4:default + +これは、`planck` の `rev4` リビジョンを `default` キーマップでビルドします。全てのキーボードにリビジョン(サブプロジェクトまたはフォルダとも呼ばれます)があるわけではありません。その場合は省略されます: + + make preonic:default + +## カスタマイズ方法 + +QMK には、探求すべき多くの[機能](ja/features.md)と、深堀りするための[リファレンス ドキュメント](http://docs.qmk.fm)がたくさんあります。ほとんどの機能は[キーマップ](ja/keymap.md)を変更し、[キーコード](ja/keycodes.md)を変更することで活用されます。 diff --git a/docs/ja/_summary.md b/docs/ja/_summary.md new file mode 100644 index 000000000..22db3a7fe --- /dev/null +++ b/docs/ja/_summary.md @@ -0,0 +1,121 @@ +* [完全な初心者のガイド](ja/newbs.md) + * [はじめに](ja/newbs_getting_started.md) + * [初めてのファームウェアの構築](ja/newbs_building_firmware.md) + * [ファームウェアのフラッシュ](ja/newbs_flashing.md) + * [テストとデバッグ](ja/newbs_testing_debugging.md) + * [Gitのベストプラクティス](ja/newbs_best_practices.md) + * [学習リソース](ja/newbs_learn_more_resources.md) + +* [QMKの基本](ja/README.md) + * [QMKの導入](ja/getting_started_introduction.md) + * [QMK CLI](ja/cli.md) + * [QMK CLI 設定](ja/cli_configuration.md) + * [QMKへの貢献](ja/contributing.md) + * [Githubの使い方](ja/getting_started_github.md) + * [ヘルプ](ja/getting_started_getting_help.md) + +* [破壊的な変更](ja/breaking_changes.md) + * [2019年8月30日](ja/ChangeLog/20190830.md) + +* [FAQ](ja/faq.md) + * [一般的なFAQ](ja/faq_general.md) + * [QMKのビルド/コンパイル](ja/faq_build.md) + * [QMKのデバッグ/トラブルシューティング](ja/faq_debug.md) + * [キーマップ](ja/faq_keymap.md) + * [Zadigを使ったドライバのインストール](ja/driver_installation_zadig.md) + +* 詳細なガイド + * [ビルドツールのインストール](ja/getting_started_build_tools.md) + * [Vagrantのガイド](ja/getting_started_vagrant.md) + * [ビルド/コンパイルの説明](ja/getting_started_make_guide.md) + * [ファームウェアのフラッシュ](ja/flashing.md) + * [機能のカスタマイズ](ja/custom_quantum_functions.md) + * [キーマップの概要](ja/keymap.md) + +* [ハードウェア](ja/hardware.md) + * [AVR プロセッサ](ja/hardware_avr.md) + * [ドライバ](ja/hardware_drivers.md) + +* リファレンス + * [キーボード ガイドライン](ja/hardware_keyboard_guidelines.md) + * [設定オプション](ja/config_options.md) + * [キーコード](ja/keycodes.md) + * [コーディング規約 - C](ja/coding_conventions_c.md) + * [コーディング規約 - Python](ja/coding_conventions_python.md) + * [ドキュメント ベストプラクティス](ja/documentation_best_practices.md) + * [ドキュメント テンプレート](ja/documentation_templates.md) + * [用語](ja/reference_glossary.md) + * [ユニットテスト](ja/unit_testing.md) + * [便利な関数](ja/ref_functions.md) + * [Configurator サポート](ja/reference_configurator_support.md) + * [info.json 形式](ja/reference_info_json.md) + * [Python CLI 開発](ja/cli_development.md) + +* [機能](ja/features.md) + * [基本的なキーコード](ja/keycodes_basic.md) + * [US ANSI シフトキー](ja/keycodes_us_ansi_shifted.md) + * [Quantum キーコード](ja/quantum_keycodes.md) + * [Advanced キーコード](ja/feature_advanced_keycodes.md) + * [オーディオ](ja/feature_audio.md) + * [自動シフト](ja/feature_auto_shift.md) + * [バックライト](ja/feature_backlight.md) + * [ブルートゥース](ja/feature_bluetooth.md) + * [ブートマジック](ja/feature_bootmagic.md) + * [コンボ](ja/feature_combo.md) + * [コマンド](ja/feature_command.md) + * [Debounce API](ja/feature_debounce_type.md) + * [DIP スイッチ](ja/feature_dip_switch.md) + * [動的マクロ](ja/feature_dynamic_macros.md) + * [エンコーダ](ja/feature_encoders.md) + * [グレイブ エスケープ](ja/feature_grave_esc.md) + * [触覚フィードバック](ja/feature_haptic_feedback.md) + * [HD44780 LCD コントローラ](ja/feature_hd44780.md) + * [キーロック](ja/feature_key_lock.md) + * [レイアウト](ja/feature_layouts.md) + * [リーダー キー](ja/feature_leader_key.md) + * [LED マトリクス](ja/feature_led_matrix.md) + * [マクロ](ja/feature_macros.md) + * [マウスキー](ja/feature_mouse_keys.md) + * [OLED ドライバ](ja/feature_oled_driver.md) + * [One Shot Keys](ja/feature_advanced_keycodes.md#one-shot-keys) + * [ポインティング デバイス](ja/feature_pointing_device.md) + * [PS/2 マウス](ja/feature_ps2_mouse.md) + * [RGB ライト](ja/feature_rgblight.md) + * [RGB マトリクス](ja/feature_rgb_matrix.md) + * [Space Cadet](ja/feature_space_cadet.md) + * [分割キーボード](ja/feature_split_keyboard.md) + * [Stenography](ja/feature_stenography.md) + * [Swap Hands](ja/feature_swap_hands.md) + * [タップ ダンス](ja/feature_tap_dance.md) + * [Terminal](ja/feature_terminal.md) + * [感熱式プリンタ](ja/feature_thermal_printer.md) + * [ユニコード](ja/feature_unicode.md) + * [Userspace](ja/feature_userspace.md) + * [Velocikey](ja/feature_velocikey.md) + +* メーカーおよびモッダーのために + * [Hand Wiring Guide](ja/hand_wire.md) + * [ISP Flashing Guide](ja/isp_flashing_guide.md) + * [ARM デバッグ ガイド](ja/arm_debugging.md) + * [I2C ドライバ](ja/i2c_driver.md) + * [GPIO コントロール](ja/internals_gpio_control.md) + * [Proton C 規約](ja/proton_c_conversion.md) + +* より深く知るために + * [キーボードがどのように動作するか](ja/how_keyboards_work.md) + * [QMKの理解](ja/understanding_qmk.md) + +* 他の話題 + * [EclipseでQMKを使用](ja/other_eclipse.md) + * [VSCodeでQMKを使用](ja/other_vscode.md) + * [サポート](ja/support.md) + * [翻訳を追加する方法](ja/translating.md) + +* QMK の内部詳細(作成中) + * [定義](ja/internals_defines.md) + * [Input Callback Reg](ja/internals_input_callback_reg.md) + * [Midi ドライバ](ja/internals_midi_device.md) + * [Midi デバイスのセットアップ手順](ja/internals_midi_device_setup_process.md) + * [Midi ユーティリティ](ja/internals_midi_util.md) + * [Send Functions](ja/internals_send_functions.md) + * [Sysex Tools](ja/internals_sysex_tools.md) diff --git a/docs/ja/arm_debugging.md b/docs/ja/arm_debugging.md new file mode 100644 index 000000000..5b7b89a67 --- /dev/null +++ b/docs/ja/arm_debugging.md @@ -0,0 +1,92 @@ +# Eclipse を使った ARM デバッグ + +<!--- + original document: eae21eed7:docs/arm_debugging.md + git diff eae21eed7 HEAD docs/arm_debugging.md | cat +--> + +このページでは、SWD アダプタとオープンソース/フリーツールを使って ARM MCU をデバッグするためのセットアップ方法について説明します。このガイドでは、GNU MCU Eclipse IDE for C/C++ Developers および OpenOCD を必要な依存関係と一緒にインストールします。 + +このガイドは上級者向けであり、あなたのマシンで、MAKE フローを使って、ARM 互換キーボードをコンパイルできることを前提にしています。 + +## ソフトウェアのインストール + +ここでの主な目的は MCU Eclipse IDE を正しくマシンにインストールすることです。必要な手順は[この](https://gnu-mcu-eclipse.github.io/install/)インストールガイドから派生しています。 + +### xPack マネージャ + +このツールはソフトウェアパッケージマネージャであり、必要な依存関係を取得するために使われます。 + +XPM は Node.js を使って実行されるため、[ここ](https://nodejs.org/en/)から取得してください。インストール後に、ターミナルを開き `npm -v` と入力します。バージョン番号が返ってくるとインストールは成功です。 + +XPM のインストール手順は[ここ](https://www.npmjs.com/package/xpm)で見つけることができ、OS 固有のものです。ターミナルに `xpm --version` と入力すると、ソフトウェアのバージョンが返ってくるはずです。 + +### ARM ツールチェーン + +XPM を使うと、ARM ツールチェーンをとても簡単にインストールできます。`xpm install --global @gnu-mcu-eclipse/arm-none-eabi-gcc` とコマンドを入力します。 + +### Windows ビルドツール + +Windows を使っている場合は、これをインストールする必要があります！ + +`xpm install --global @gnu-mcu-eclipse/windows-build-tools` + +### プログラマ/デバッガドライバ + +プログラマのドライバをインストールします。このチュートリアルはほとんどどこでも入手できる ST-Link v2 を使って作成されました。 +ST-Link を持っている場合は、ドライバは[ここ](https://www.st.com/en/development-tools/stsw-link009.html)で見つけることができます。そうでない場合はツールの製造元にお問い合わせください。 + +### OpenOCD + +この依存関係により、SWD は GDB からアクセスでき、デバッグに不可欠です。`xpm install --global @gnu-mcu-eclipse/openocd` を実行します。 + +### Java + +Java は Eclipse で必要とされるため、[ここ](https://www.oracle.com/technetwork/java/javase/downloads/index.html)からダウンロードしてください。 + +### GNU MCU Eclipse IDE + +最後に IDE をインストールする番です。[ここ](https://github.com/gnu-mcu-eclipse/org.eclipse.epp.packages/releases/)のリリースページから最新バージョンを取得します。 + +## Eclipse の設定 + +ダウンロードした Eclipse IDE を開きます。QMK ディレクトリをインポートするために、File -> Import -> C/C++ -> Existing code as Makefile Project を選択します。Next を選択し、Browse を使用して QMK フォルダを選択します。tool-chain リストから ARM Cross GCC を選択し、Finish を選択します。 + +これで、左側に QMK フォルダが表示されます。右クリックして、Properties を選択します。左側で MCU を展開し、ARM Toolchain Paths を選択します。xPack を押して OK を押します。OpenOCD Path で同じことを繰り返し、Windows の場合は、Build Tool Path でも同じことを繰り返します。Apply and Close を選択します。 + +ここで、必要な MCU パッケージをインストールします。Window -> Open Perspective -> Others -> Packs を選択して、Packs perspective に移動します。Packs タブの横にある黄色のリフレッシュ記号を選択します。これは様々な場所から MCU の定義を要求するため、時間が掛かります。一部のリンクが失敗した場合は、おそらく Ignore を選択できます。 + +これが終了すると、ビルドやデバッグする MCU を見つけることができるはずです。この例では、STM32F3 シリーズの MCU を使います。左側で、STMicroelectronics -> STM32F3 Series を選択します。中央のウィンドウに、pack が表示されます。右クリックし、Install を選択します。それが終了したら、Window -> Open Perspective -> Others -> C/C++ を選択してデフォルトのパースペクティブに戻ることができます。 + +Eclipse に QMK をビルドしようとするデバイスを教える必要があります。QMK フォルダを右クリック -> Properties -> C/C++ Build -> Settings を選択します。Devices タブを選択し、devices の下から MCU の適切な種類を選択します。私の例では、STM32F303CC です。 + +この間に、build コマンドもセットアップしましょう。C/C++ Build を選択し、Behavior タブを選択します。build コマンドのところで、`all` を必要な make コマンドに置き換えます。例えば、rev6 Planck の default キーマップの場合、これは `planck/rev6:default` になります。Apply and Close を選択します。 + +## ビルド + +全て正しくセットアップできていれば、ハンマーボタンを押すとファームウェアがビルドされ、.binファイルが出力されるはずです。 + +## デバッグ + +### デバッガの接続 + +ARM MCU は、クロック信号(SWCLK) とデータ信号(SWDIO) で構成される Single Wire Debug (SWD) プロトコルを使います。MCUを 完全に操作するには、この2本のワイヤとグラウンドを接続するだけで十分です。ここでは、キーボードは USB を介して電力が供給されると想定しています。手動でリセットボタンを使えるため、RESET 信号は必要ありません。より高度なセットアップのために printf と scanf をホストに非同期にパイプする SWO 信号を使用できますが、私たちのセットアップでは無視します。 + +注意: SWCLK と SWDIO ピンがキーボードのマトリックスで使われていないことを確認してください。もし使われている場合は、一時的に他のピンに切り替えることができます。 + +### デバッガの設定 + +QMK フォルダを右クリックし、Debug As -> Debug Configuration を選択します。ここで、GDB OpenOCD Debugging をダブルクリックします。Debugger タブを選択し、MCU に必要な設定を入力します。これを見つけるにはいじったりググったりする必要があるかもしれません。STM32F3 用のデフォルトスクリプトは stm32f3discovery.cfg と呼ばれます。OpenOCD に伝えるには、Config options で `-f board/stm32f3discovery.cfg` と入力します。 + +注意: 私の場合、この設定スクリプトはリセット操作を無効にするために編集が必要です。スクリプトの場所は、通常はパス `openocd/version/.content/scripts/board` の下の実際の実行可能フィールドの中で見つかります。ここで、私は `reset_config srst_only` を `reset_config none` に編集しました。 + +Apply and Close を選択します。 + +### デバッガの実行 + +キーボードをリセットしてください。 + +虫アイコンをクリックし、もし全てうまく行けば debug パースペクティブに移動します。ここでは、main 関数の最初でプログラムカウンタが停止するので、Play ボタンを押します。全てのデバッガのほとんどの機能は ARM MCU で動作しますが、正確な詳細については google があなたのお友達です！ + + +ハッピーデバッギング！ diff --git a/docs/ja/config_options.md b/docs/ja/config_options.md new file mode 100644 index 000000000..d7457798c --- /dev/null +++ b/docs/ja/config_options.md @@ -0,0 +1,376 @@ +# QMK の設定 + +<!--- + original document: eae21eed7:docs/config_options.md + git diff eae21eed7 HEAD docs/config_options.md | cat +--> + +QMK はほぼ無制限に設定可能です。可能なところはいかなるところでも、やりすぎな程、ユーザーがコードサイズを犠牲にしてでも彼らのキーボードをカスタマイズをすることを許しています。ただし、このレベルの柔軟性により設定が困難になります。 + +QMK には主に２種類の設定ファイルがあります- `config.h` と `rules.mk`。これらのファイルは QMK の様々なレベルに存在し、同じ種類の全てのファイルは最終的な設定を構築するために組み合わされます。最低の優先度から最高の優先度までのレベルは以下の通りです: + +* QMK デフォルト +* キーボード +* フォルダ (最大5レべルの深さ) +* キーマップ + +## QMK デフォルト + +QMK での全ての利用可能な設定にはデフォルトがあります。その設定がキーボード、フォルダ、あるいはキーマップレべルで設定されない場合、これが使用される設定です。 + +## キーボード + +このレベルにはキーボード全体に適用される設定オプションが含まれています。一部の設定は、リビジョンあるいはほとんどのキーマップで変更されません。他の設定はこのキーボードのデフォルトに過ぎず、フォルダあるいはキーマップによって上書きされる可能性があります。 + +## フォルダ + +一部のキーボードには、異なるハードウェア構成のためのフォルダとサブフォルダがあります。ほとんどのキーボードは深さ1のフォルダのみですが、QMK は最大深さ5のフォルダの構造をサポートします。各フォルダは、最終的な設定に組み込まれる独自の `config.h` と `rules.mk` ファイルを持つことができます。 + +## キーマップ + +このレベルには特定のキーマップのための全てのオプションが含まれています。以前の定義を上書きしたい場合は、`#undef <variable>` を使って定義を解除し、エラー無しで再定義することができます。 + +# `config.h` ファイル + +これは最初に include されるものの 1 つである C ヘッダファイルで、プロジェクト全体(もし含まれる場合)にわたって持続します。多くの変数をここで設定し、他の場所からアクセスすることができます。`config.h` ファイルでは、以下のもの以外の、他の `config.h` ファイルやその他のファイルの include をしないでください: + + #include "config_common.h" + + +## ハードウェアオプション +* `#define VENDOR_ID 0x1234` + * VID を定義します。ほとんどの DIY プロジェクトにおいて、任意のものを定義できます +* `#define PRODUCT_ID 0x5678` + * PID を定義します。ほとんどの DIY プロジェクトでは、任意のものを定義できます +* `#define DEVICE_VER 0` + * デバイスのバージョンを定義します (多くの場合リビジョンに使われます) +* `#define MANUFACTURER Me` + * 一般的に、誰もしくはどのブランドがボードを作成したか +* `#define PRODUCT Board` + * キーボードの名前 +* `#define DESCRIPTION a keyboard` + * キーボードの簡単な説明 +* `#define MATRIX_ROWS 5` + * キーボードのマトリックスの行の数 +* `#define MATRIX_COLS 15` + * キーボードのマトリックスの列の数 +* `#define MATRIX_ROW_PINS { D0, D5, B5, B6 }` + * 行のピン、上から下へ +* `#define MATRIX_COL_PINS { F1, F0, B0, C7, F4, F5, F6, F7, D4, D6, B4, D7 }` + * 列のピン、左から右へ +* `#define UNUSED_PINS { D1, D2, D3, B1, B2, B3 }` + * 参考として、キーボードで使われていないピン +* `#define MATRIX_HAS_GHOST` + * マトリックスにゴーストがあるか(ありそうにないか)定義します +* `#define DIODE_DIRECTION COL2ROW` + * COL2ROW あるいは ROW2COL - マトリックスがどのように設定されているか。COL2ROW は、スイッチとロウ(行)ラインの間にダイオードが黒い印をロウ(行)ラインに向けて置いてあることを意味します。 +* `#define DIRECT_PINS { { F1, F0, B0, C7 }, { F4, F5, F6, F7 } }` + * ロウ(行)ラインとカラム(列)ラインにマップされているピンを左から右に。各スイッチが個別のピンとグラウンドに接続されているマトリックスを定義します。 +* `#define AUDIO_VOICES` + * (循環させるために)代替音声を有効にします +* `#define C4_AUDIO` + * ピン C4 のオーディオを有効にします +* `#define C5_AUDIO` + * ピン C5 のオーディオを有効にします +* `#define C6_AUDIO` + * ピン C6 のオーディオを有効にします +* `#define B5_AUDIO` + * ピン B5 のオーディオを有効にします (C[4-6]\_AUDIO の1つとともに B[5-7]\_AUDIO の1つが有効にされている場合、疑似ステレオが有効にされます) +* `#define B6_AUDIO` + * ピン B6 のオーディオを有効にします (C[4-6]\_AUDIO の1つとともに B[5-7]\_AUDIO の1つが有効にされている場合、疑似ステレオが有効にされます) +* `#define B7_AUDIO` + * ピン B7 のオーディオを有効にします (C[4-6]\_AUDIO の1つとともに B[5-7]\_AUDIO の1つが有効にされている場合、疑似ステレオが有効にされます) +* `#define BACKLIGHT_PIN B7` + * バックライトのピン +* `#define BACKLIGHT_LEVELS 3` + * バックライトのレベル数 (off を除いて最大15) +* `#define BACKLIGHT_BREATHING` + * バックライトのブレスを有効にします +* `#define BREATHING_PERIOD 6` + * 1つのバックライトの "ブレス" の長さの秒数 +* `#define DEBOUNCE 5` + * ピンの値を読み取る時の遅延 (5がデフォルト) +* `#define LOCKING_SUPPORT_ENABLE` + * メカニカルロックのサポート。キーマップで KC_LCAP、 KC_LNUM そして KC_LSCR を使えるようにします +* `#define LOCKING_RESYNC_ENABLE` + * キーボードの LED の状態をスイッチの状態と一致させ続けようとします +* `#define IS_COMMAND() (get_mods() == MOD_MASK_SHIFT)` + * マジックコマンドの使用を可能にするキーの組み合わせ (デバッグに便利です) +* `#define USB_MAX_POWER_CONSUMPTION 500` + * デバイスの USB 経由の最大電力(mA) を設定します (デフォルト: 500) +* `#define USB_POLLING_INTERVAL_MS 10` + * キーボード、マウス および 共有 (NKRO/メディアキー) インタフェースのための USB ポーリングレートをミリ秒で設定します +* `#define F_SCL 100000L` + * I2C を使用するキーボードのための I2C クロックレート速度を設定します。デフォルトは `400000L` ですが、`split_common` を使っているキーボードは別でデフォルトは `100000L` です。 + +## 無効にできる機能 + +これらのオプションを定義すると、関連する機能が無効になり、コードサイズを節約できます。 + +* `#define NO_DEBUG` + * デバッグを無効にします +* `#define NO_PRINT` + * hid_listen を使った出力やデバッグを無効にします +* `#define NO_ACTION_LAYER` + * レイヤーを無効にします +* `#define NO_ACTION_TAPPING` + * タップダンスと他のタップ機能を無効にします +* `#define NO_ACTION_ONESHOT` + * ワンショットモディファイアを無効にします +* `#define NO_ACTION_MACRO` + * 古い形式のマクロ処理を無効にします: MACRO() & action_get_macro +* `#define NO_ACTION_FUNCTION` + * fn_actions 配列(非推奨)からの action_function() の呼び出しを無効にします + +## 有効にできる機能 + +これらのオプションを定義すると、関連する機能が有効になり、コードサイズが大きくなるかもしれません。 + +* `#define FORCE_NKRO` + * NKRO をデフォルトでオンにする必要があります。これにより EEPROM の設定に関係なく、キーボードの起動時に NKRO が強制的にオンになります。NKRO は引き続きオフにできますが、キーボードを再起動すると再びオンになります。 +* `#define STRICT_LAYER_RELEASE` + * キーリリースがどのレイヤーから来たのかを覚えるのではなく、現在のレイヤースタックを使って強制的に評価されるようにします (高度なケースに使われます) + +## 設定可能な挙動 + +* `#define TAPPING_TERM 200` + * タップがホールドになるまでの時間。500以上に設定された場合、タップ期間中にタップされたキーもホールドになります。(訳注: PERMISSIVE_HOLDも参照) +* `#define TAPPING_TERM_PER_KEY` + * キーごとの `TAPPING_TERM` 設定の処理を有効にします +* `#define RETRO_TAPPING` + * 押下とリリースの間に他のキーによる中断がなければ、TAPPING_TERM の後であってもとにかくタップします + * 詳細は [Retro Tapping](ja/feature_advanced_keycodes.md#retro-tapping) を見てください +* `#define TAPPING_TOGGLE 2` + * トグルを引き起こす前のタップ数 +* `#define PERMISSIVE_HOLD` + * `TAPPING_TERM` にヒットしていなくても、リリースする前に別のキーが押されると、タップとフォールドキーがホールドを引き起こします + * 詳細は [Permissive Hold](ja/feature_advanced_keycodes.md#permissive-hold) を見てください +* `#define IGNORE_MOD_TAP_INTERRUPT` + * 両方のキーに `TAPPING_TERM` を適用することで、ホールド時に他のキーに変換するキーを使ってローリングコンボ (zx) をすることができるようにします + * 詳細は [Mod tap interrupt](ja/feature_advanced_keycodes.md#ignore-mod-tap-interrupt) を見てください +* `#define TAPPING_FORCE_HOLD` + * タップされた直後に、デュアルロールキーを修飾子として使用できるようにします + * [Hold after tap](ja/feature_advanced_keycodes.md#tapping-force-hold)を見てください + * タップトグル機能を無効にします (`TT` あるいは One Shot Tap Toggle) +* `#define LEADER_TIMEOUT 300` + * リーダーキーがタイムアウトするまでの時間 + * タイムアウトする前にシーケンスを終了できない場合は、タイムアウトの設定を増やす必要があるかもしれません。あるいは、`LEADER_PER_KEY_TIMING` オプションを有効にすると良いでしょう。これは各キーがタップされた後でタイムアウトを再設定します。 +* `#define LEADER_PER_KEY_TIMING` + * 全体では無く各キーを押すたびに実行されるリーダーキーコードのタイマーを設定します +* `#define LEADER_KEY_STRICT_KEY_PROCESSING` + * Mod-Tap および Layer-Tap キーコードのためのキーコードフィルタリングを無効にします。例えば、これを有効にすると、`KC_A` を使いたい場合は `MT(MOD_CTL, KC_A)` を指定する必要があります。 +* `#define ONESHOT_TIMEOUT 300` + * ワンショットがタイムアウトするまでの時間 +* `#define ONESHOT_TAP_TOGGLE 2` + * ワンショットトグルが引き起こされるまでのタップ数 +* `#define QMK_KEYS_PER_SCAN 4` + * 走査ごとに1つ以上のキーを送信できるようにします。デフォルトでは、走査ごとに `process_record()` 経由で1つのキーイベントのみが送信されます。これはほとんどのタイピングにほとんど影響しませんが、多くのコードを入力しているか、走査レートが最初から遅い場合、キーイベントの処理に多少の遅延が生じる可能性があります。それぞれのプレスとリリースは別のイベントです。スキャン時間が 1ms 程度のキーボードの場合、とても高速なタイピストでさえ、実際にキーボードから数 ms 以上の遅延を発生させるのに必要な 500 キーストロークを1秒間に生成することはないでしょう。しかし、3～4ms の走査時間でコードを入力している場合はどうでしょうか？おそらくこれが必要です。 +* `#define COMBO_COUNT 2` + * [コンボ](ja/feature_combo.md)機能で使っているコンボの数にこれを設定します。 +* `#define COMBO_TERM 200` + * コンボキーが検出されるまでの時間。定義されていない場合は、デフォルトは `TAPPING_TERM` です。 +* `#define TAP_CODE_DELAY 100` + * 適切な登録に問題がある場合(VUSB ボードで珍しくない)、`register_code` と `unregister_code` の間の遅延を設定します。値はミリ秒です。 +* `#define TAP_HOLD_CAPS_DELAY 80` + * MacOS で特別な処理が行われるため、`KC_CAPSLOCK` を使う時にタップホールドキー (`LT`, `MT`) に遅延を設定します。この値はミリ秒で、定義されていない場合はデフォルトは80msです。macOS については、これを200以上に設定すると良いでしょう。 + +## RGB ライト設定 :id=rgb-light-configuration + +* `#define RGB_DI_PIN D7` + * WS2812 の DI 端子につなぐピン +* `#define RGBLIGHT_ANIMATIONS` + * RGB アニメーションを実行します +* `#define RGBLED_NUM 12` + * LED の数 +* `#define RGBLIGHT_SPLIT` + * 分割キーボードの左半分の RGB LED の出力を右半分の RGB LED の入力につなげるかわりに、それぞれの側で個別にコントローラの出力ピンが直接 RGB LED の入力に繋がっているときは、この定義が必要です。 +* `#define RGBLED_SPLIT { 6, 6 }` + * 分割キーボードの各半分の `RGB_DI_PIN` に直接配線されている接続されているLEDの数 + * 最初の値は左半分の LED の数を示し、2番目の値は右半分です。 + * RGBLED_SPLIT が定義されている場合、RGBLIGHT_SPLIT は暗黙的に定義されます。 +* `#define RGBLIGHT_HUE_STEP 12` + * 色相の増減時のステップ単位 +* `#define RGBLIGHT_SAT_STEP 25` + * 彩度の増減時のステップ単位 +* `#define RGBLIGHT_VAL_STEP 12` + * 値(明度)の増減時のステップ単位 +* `#define RGBW` + * RGBW LED のサポートを有効にします + +## マウスキーオプション + +* `#define MOUSEKEY_INTERVAL 20` +* `#define MOUSEKEY_DELAY 0` +* `#define MOUSEKEY_TIME_TO_MAX 60` +* `#define MOUSEKEY_MAX_SPEED 7` +* `#define MOUSEKEY_WHEEL_DELAY 0` + +## 分割キーボードオプション + +分割キーボード固有のオプション。あなたの rules.mk に 'SPLIT_KEYBOARD = yes' が有ることを確認してください。 + +* `SPLIT_TRANSPORT = custom` + * 標準の分割通信ルーチンをカスタムのものに置き換えることができます。現在、ARM ベースの分割キーボードはこれを使わなければなりません。 + +### 左右の設定 + +一つ覚えておかなければならないことは、USB ポートが接続されている側が常にマスター側であるということです。USB に接続されていない側はスレーブです。 + +分割キーボードの左右を設定するには、幾つかの異なる方法があります (優先度の順にリストされています): + +1. `SPLIT_HAND_PIN` を設定します: 左右を決定するためにピンを読み込みます。ピンが high の場合、それが左側です。low であれば、その半分側が右側であると決定されます。 +2. `EE_HANDS` を設定し、各半分に `eeprom-lefthand.eep`/`eeprom-righthand.eep` を書き込みます + * DFU ブートローダを搭載したボードでは、これらの EEPROM ファイルを書き込むために `:dfu-split-left`/`:dfu-split-right` を使うことができます + * Caterina ブートローダを搭載したボード (標準的な Pro Micros など)では、`:avrdude-split-left`/`:avrdude-split-right` を使ってください + * ARM DFU ブートローダを搭載したボード (Proton C など)では、`:dfu-util-split-left`/`:dfu-util-split-right` を使ってください +3. `MASTER_RIGHT` を設定します: USBポートに差し込まれた側はマスター側で右側であると決定されます(デフォルトの逆) +4. デフォルト: USB ポートに差し込まれている側がマスター側であり、左側であると見なされます。スレーブ側は右側です + +#### 左右を定義します + +* `#define SPLIT_HAND_PIN B7` + * high/low ピンを使って左右を決定します。low = 右手、high = 左手。`B7` を使っているピンに置き換えます。これはオプションで、`SPLIT_HAND_PIN` が未定義のままである場合、EE_HANDS メソッドまたは標準の Let's Splitが使っている MASTER_LEFT / MASTER_RIGHT 定義をまだ使うことができます。 + +* `#define EE_HANDS` (`SPLIT_HAND_PIN` が定義されていない場合のみ動作します) + * `eeprom-lefthand.eep`/`eeprom-righthand.eep` がそれぞれの半分に書き込まれた後で、EEPROM 内に格納されている左右の設定の値を読み込みます。 + +* `#define MASTER_RIGHT` + * マスター側が右側と定義されます。 + +### 他のオプション + +* `#define USE_I2C` + * Serial の代わりに I2C を使う場合 (デフォルトは serial) + +* `#define SOFT_SERIAL_PIN D0` + * serial を使う場合、これを定義します。`D0` あるいは `D1`,`D2`,`D3`,`E6`。 + +* `#define MATRIX_ROW_PINS_RIGHT { <row pins> }` +* `#define MATRIX_COL_PINS_RIGHT { <col pins> }` + * 右半分に左半分と異なるピン配置を指定したい場合は、`MATRIX_ROW_PINS_RIGHT`/`MATRIX_COL_PINS_RIGHT` を定義することができます。現在のところ、`MATRIX_ROW_PINS` のサイズは `MATRIX_ROW_PINS_RIGHT` と同じでなければならず、列の定義も同様です。 + +* `#define DIRECT_PINS_RIGHT { { F1, F0, B0, C7 }, { F4, F5, F6, F7 } }` + * 右半分に左半分と異なる直接ピン配置を指定したい場合は、`DIRECT_PINS_RIGHT` を定義することができます。現在のところ、`DIRECT_PINS` のサイズは `DIRECT_PINS_RIGHT` と同じでなければなりません。 + +* `#define RGBLED_SPLIT { 6, 6 }` + * [RGB ライト設定](#rgb-light-configuration)を見てください。 + +* `#define SELECT_SOFT_SERIAL_SPEED <speed>` (デフォルトの速度は1です) + * serial 通信を使う時のプロトコルの速度を設定します。 + * 速度: + * 0: 約189kbps (実験目的のみ) + * 1: 約 137kbps (デフォルト) + * 2: 約 75kbps + * 3: 約 39kbps + * 4: 約 26kbps + * 5: 約 20kbps + +* `#define SPLIT_USB_DETECT` + * マスタ/スレーブを委任する時に(タイムアウト付きで) USB 接続を検出します + * ARM についてはデフォルトの挙動 + * AVR Teensy については必須 + +* `#define SPLIT_USB_TIMEOUT 2500` + * `SPLIT_USB_DETECT` を使う時のマスタ/スレーブを検出する場合の最大タイムアウト + +# `rules.mk` ファイル + +これは、トップレベルの `Makefile` から include される [make](https://www.gnu.org/software/make/manual/make.html) ファイルです。これは特定の機能を有効または無効にするだけでなく、コンパイルする MCU に関する情報を設定するために使われます。 + +## ビルドオプション + +* `DEFAULT_FOLDER` + * キーボードに1つ以上のサブフォルダがある場合にデフォルトのフォルダを指定するために使われます。 +* `FIRMWARE_FORMAT` + * ビルドの後でルート `qmk_firmware` フォルダにコピーされる形式 (bin, hex) を定義します。 +* `SRC` + * コンパイル・リンクリストにファイルを追加するために使われます。 +* `LAYOUTS` + * このキーボードがサポートする[レイアウト](ja/feature_layouts.md)のリスト + +## AVR MCU オプション +* `MCU = atmega32u4` +* `F_CPU = 16000000` +* `ARCH = AVR8` +* `F_USB = $(F_CPU)` +* `OPT_DEFS += -DINTERRUPT_CONTROL_ENDPOINT` +* `BOOTLOADER = atmel-dfu` と以下のオプション: + * `atmel-dfu` + * `lufa-dfu` + * `qmk-dfu` + * `halfkay` + * `caterina` + * `bootloadHID` + * `USBasp` + +## 機能オプション + +これらを使って特定の機能のビルドを有効または無効にします。有効にすればするほどファームウェアが大きくなり、MCU には大きすぎるファームウェアを構築するリスクがあります。 + +* `BOOTMAGIC_ENABLE` + * 仮想 DIP スイッチ設定 +* `MOUSEKEY_ENABLE` + * マウスキー +* `EXTRAKEY_ENABLE` + * オーディオ制御とシステム制御 +* `CONSOLE_ENABLE` + * デバッグ用コンソール +* `COMMAND_ENABLE` + * デバッグ及び設定用のコマンド +* `COMBO_ENABLE` + * キーコンボ機能 +* `NKRO_ENABLE` + * USB N-キーロールオーバー - これが動作しない場合は、ここを見てください: https://github.com/tmk/tmk_keyboard/wiki/FAQ#nkro-doesnt-work +* `AUDIO_ENABLE` + * オーディオサブシステムを有効にします。 +* `RGBLIGHT_ENABLE` + * キーボードアンダーライト機能を有効にします +* `LEADER_ENABLE` + * リーダーキーコードを有効にします +* `MIDI_ENABLE` + * MIDI 制御 +* `UNICODE_ENABLE` + * Unicode +* `BLUETOOTH_ENABLE` + * Adafruit EZ-Key HID で Bluetooth を有効にするレガシーオプション。BLUETOOTH を見てください +* `BLUETOOTH` + * 現在のオプションは、AdafruitEzKey、AdafruitBLE、RN42 +* `SPLIT_KEYBOARD` + * 分割キーボード (let's split や bakingpy のキーボードのようなデュアル MCU) のサポートを有効にし、quantum/split_common にある全ての必要なファイルをインクルードします +* `CUSTOM_MATRIX` + * 標準マトリックス走査ルーチンを独自のものに置き換えることができます。 +* `DEBOUNCE_TYPE` + * 標準キーデバウンスルーチンを代替または独自のものに置き換えることができます。 +* `WAIT_FOR_USB` + * キーボードが起動する前に、USB 接続が確立されるのをキーボードに待機させます +* `NO_USB_STARTUP_CHECK` + * キーボードの起動後の usb サスペンドチェックを無効にします。通常、キーボードはタスクが実行される前にホストがウェイク アップするのを待ちます。分割キーボードは半分はウェイクアップコールを取得できませんが、マスタにコマンドを送信する必要があるため、役に立ちます。 +* `LINK_TIME_OPTIMIZATION_ENABLE` + * キーボードをコンパイルする時に、Link Time Optimization (`LTO`) を有効にします。これは処理に時間が掛かりますが、コンパイルされたサイズを大幅に減らします (そして、ファームウェアが小さいため、追加の時間は分からないくらいです)。ただし、`LTO` が有効な場合、古いマクロと関数の機能が壊れるため、自動的にこれらの機能を無効にします。これは `NO_ACTION_MACRO` と `NO_ACTION_FUNCTION` を自動的に定義することで行われます。 + * `LINK_TIME_OPTIMIZATION_ENABLE` の代わりに `LTO_ENABLE` を使うことができます。 + +## USB エンドポイントの制限 + +USB 経由でサービスを提供するために、QMK は USB エンドポイントを使う必要があります。 +これらは有限なリソースです: 各マイクロコントローラは特定の数しか持ちません。 +これは一緒に有効にできる機能を制限します。 +利用可能なエンドポイントを超えると、ビルドエラーをひきおこします。 + +以下の機能は個別のエンドポイントを必要とするかもしれません: + +* `MOUSEKEY_ENABLE` +* `EXTRAKEY_ENABLE` +* `CONSOLE_ENABLE` +* `NKRO_ENABLE` +* `MIDI_ENABLE` +* `RAW_ENABLE` +* `VIRTSER_ENABLE` + +エンドポイントの使用率を向上させるために、HID 機能を組み合わせて1つのエンドポイントを使うようにすることができます。 +デフォルトでは、`MOUSEKEY`、`EXTRAKEY` および `NKRO` が単一のエンドポイントに結合されます。 + +基本キーボード機能も、`KEYBOARD_SHARED_EP = yes` を設定することで同じエンドポイントに結合することができます。 +これによりもう1つのエンドポイントが解放されますが、一部の BIOS ではブートキーボードプロトコルの切り替えを実装しないため、キーボードが動作しなくなるかもしれません。 + +マウスの結合も、ブートマウス互換性を破壊します。 +この機能が必要な場合は、`MOUSE_SHARED_EP = no` を設定することで、マウスを結合しないようにすることができます。 diff --git a/docs/ja/newbs.md b/docs/ja/newbs.md new file mode 100644 index 000000000..54189cce4 --- /dev/null +++ b/docs/ja/newbs.md @@ -0,0 +1,41 @@ +# QMK 初心者ガイド + +<!--- + grep --no-filename "^[ ]*git diff" docs/ja/*.md | sh + original document: ed0575fc8:docs/newbs.md + git diff ed0575fc8 HEAD docs/newbs.md | cat +--> + +QMK は、メカニカルキーボード用の強力なオープンソースファームウェアです。 +QMK を使用して、シンプルかつ強力な方法でキーボードをカスタマイズできます。 +完全な初心者からプログラマーに至るまで、あらゆるスキルレベルの人々が QMK を使用してキーボードをカスタマイズしています。 +このガイドは、あなたのスキルにかかわらず、同じことを行う手助けをします。 + +お使いのキーボードで QMK を実行できるかどうか不明ですか？ +もし作成したキーボードがメカニカルキーボードの場合、実行できる可能性が高いです。 +QMK は[多くの趣味のキーボード](http://qmk.fm/keyboards/)をサポートしているため、もし現在のキーボードで QMK を実行できない場合でも、ニーズに合ったキーボードを見つけるのに問題はないはずです。 + +## 概要 + +このガイドには7つの主要なセクションがあります。 + +* [はじめに](ja/newbs_getting_started.md) +* [コマンドラインを使用して初めてのファームウェアを構築する](ja/newbs_building_firmware.md) +* [オンライン GUI を使用して初めてのファームウェアを構築する](ja/newbs_building_firmware_configurator.md) +* [ファームウェアを書きこむ](ja/newbs_flashing.md) +* [テストとデバッグ](ja/newbs_testing_debugging.md) +* [QMK における Git 運用作法](ja/newbs_best_practices.md) +* [さらに学ぶための学習リソース](ja/newbs_learn_more_resources.md) + +このガイドは、これまでソフトウェアをコンパイルしたことがない人を支援することに特化しています。 +その観点から選択と推奨を行います。 +これらの手順の多くには代替方法があり、これらの代替方法のほとんどをサポートしています。 +タスクを達成する方法について疑問がある場合は、[案内を求めることができます](ja/getting_started_getting_help.md)。 + +## 追加のリソース(英語) + +* [Thomas Baart's QMK Basics Blog](https://thomasbaart.nl/category/mechanical-keyboards/firmware/qmk/qmk-basics/) – 新規ユーザ視点から見た QMK ファームウェアの基本的な使用方法をカバーしたユーザ作成のブログ。 + +## 追加のリソース(日本語) + +_日本語のリソース情報を募集中です。_ diff --git a/docs/ja/newbs_best_practices.md b/docs/ja/newbs_best_practices.md new file mode 100644 index 000000000..3c87d53d4 --- /dev/null +++ b/docs/ja/newbs_best_practices.md @@ -0,0 +1,263 @@ +<!-- # Best Practices --> +# QMK における Git 運用作法 + +<!--- + grep --no-filename "^[ ]*git diff" docs/ja/*.md | sh + original document: e75919960:docs/newbs_best_practices.md + git diff e75919960 HEAD docs/newbs_best_practices.md | cat +--> + +<!-- ## Or, "How I Learned to Stop Worrying and Love Git." --> +## または、如何にして私は心配することをやめて Git を愛することを学んだか。 + +<!-- _Almost the same as #7231:25fdbf2a0:newbs_git_best_practices.md L5_ --> +<!-- This document aims to instruct novices in the best ways to have a smooth experience in contributing to QMK. We will walk through the process of contributing to QMK, detailing some ways to make this task easier, and then later we'll break some things in order to teach you how to fix them. --> +この文書は、QMK への貢献をスムーズに行なう最もよい方法を初心者に教えることを目的としています。 +QMK に貢献するプロセスを順を追って説明し、この作業を簡単にするいくつかの方法を詳しく説明します。 +その後、意図的に一部を壊してみせて、それらを修正する方法を教えます。 + +<!-- This document assumes a few things: --> +このドキュメントは以下のことを前提としています: + +<!-- _Same as #7231:25fdbf2a0:newbs_git_best_practices.md L9_ --> +<!-- 1. You have a GitHub account, and have [forked the qmk_firmware repository](getting_started_github.md) to your account. --> +<!-- 2. You've [set up your build environment](newbs_getting_started.md?id=environment-setup). --> +<!-- #7231:da7d49246: 2. You've set up both [your build environment](newbs_getting_started.md?id=set-up-your-environment) and [QMK](newbs_getting_started.md?id=set-up-qmk). --> + +1. あなたは GitHub アカウントがあり、アカウントに [qmk_firmware リポジトリをフォーク](ja/getting_started_github.md) している。 +2. あなたは、[環境構築](ja/newbs_getting_started.md#set-up-your-environment) と [QMK の設定](ja/newbs_getting_started.md#set-up-qmk) を両方とも完了している。 + +<!-- ## Your fork's master: Update Often, Commit Never --> +## あなたのフォークの master ブランチ: 更新は頻繁に、コミットはしないこと + +<!-- _Same as #7231:25fdbf2a0:newbs_git_using_your_master_branch.md L3_ --> +<!-- It is highly recommended for QMK development, regardless of what is being done or where, to keep your `master` branch updated, but ***never*** commit to it. Instead, do all your changes in a development branch and issue pull requests from your branches when you're developing. --> +QMK の開発では、何がどこで行われているかにかかわらず、`master` ブランチを最新の状態に保つことを強くお勧めします、しかし `master` ブランチには***絶対に直接コミットしないでください***。 +代わりに、あなたのすべての変更は開発ブランチで行い、あなたが開発する時にはそのブランチからプルリクエストを発行します。 + +<!-- _Same as #7231:25fdbf2a0:newbs_git_using_your_master_branch.md L5_ --> +<!-- To reduce the chances of merge conflicts — instances where two or more users have edited the same part of a file concurrently — keep your `master` branch relatively up-to-date, and start any new developments by creating a new branch. --> +マージの競合 — これは 2人以上のユーザーがファイルの同じ部分をそれぞれ異なる編集をして統合できなくなった状態 — の可能性を減らすため `master` ブランチをなるべく最新の状態に保ち、新しいブランチを作成して新しい開発を開始します。 + +<!-- ### Updating your master branch --> +### あなたの master ブランチを更新する + +<!-- _Same as #7231:25fdbf2a0:newbs_git_using_your_master_branch.md L9_ --> +<!-- To keep your `master` branch updated, it is recommended to add the QMK Firmware repository ("repo") as a remote repository in git. To do this, open your Git command line interface and enter: --> +`master` ブランチを最新の状態に保つには、git のリモートリポジトリとして QMK ファームウェアのリポジトリ(以降、QMK リポジトリ)を追加することをお勧めします。 +これを行うには、Git コマンドラインインターフェイスを開き、次のように入力します。 + +``` +git remote add upstream https://github.com/qmk/qmk_firmware.git +``` + +<!-- _Same as #7231:25fdbf2a0:newbs_git_using_your_master_branch.md L15_ --> +<!-- To verify that the repository has been added, run `git remote -v`, which should return the following: --> +リポジトリが追加されたことを確認するには、`git remote -v` を実行します。 +次のように表示されます。(訳注: `upstream` は`上流`という意味です。) + +``` +$ git remote -v +origin https://github.com/<your_username>/qmk_firmware.git (fetch) +origin https://github.com/<your_username>/qmk_firmware.git (push) +upstream https://github.com/qmk/qmk_firmware.git (fetch) +upstream https://github.com/qmk/qmk_firmware.git (push) +``` + +<!-- _Same as #7231:25fdbf2a0:newbs_git_using_your_master_branch.md L25_ --> +<!-- Now that this is done, you can check for updates to the repo by running `git fetch upstream`. This retrieves the branches and tags — collectively referred to as "refs" — from the QMK repo, which now has the nickname `upstream`. We can now compare the data on our fork `origin` to that held by QMK. --> +これが完了すると、`git fetch upstream` を実行してリポジトリの更新を確認できます。 +このコマンドは `upstream` というニックネームを持つ QMK リポジトリから、ブランチとタグ — "refs" と総称されます — を取得します。 +これで、あなたのフォーク `origin` のデータを QMK が保持するデータと比較できます。 + +<!-- _Same as #7231:25fdbf2a0:newbs_git_using_your_master_branch.md L27_ --> +<!-- To update your fork's master, run the following, hitting the Enter key after each line: --> +あなたのフォークの `master` を更新するには、次を実行します、各行の後にEnterキーを押してください: + +``` +git checkout master +git fetch upstream +git pull upstream master +git push origin master +``` + +<!-- _Same as #7231:25fdbf2a0:newbs_git_using_your_master_branch.md L36_ --> +<!-- This switches you to your `master` branch, retrieves the refs from the QMK repo, downloads the current QMK `master` branch to your computer, and then uploads it to your fork. --> +これにより、あなたの `master` ブランチに切り替わり、QMK リポジトリから 'refs' を取得し、現在の QMK の `master` ブランチをコンピュータにダウンロードしてから、あなたのフォークにアップロードします。 + +<!-- ### Making Changes --> +### 変更を行なう + +<!-- _Same as #7231:25fdbf2a0:newbs_git_using_your_master_branch.md L40_ --> +<!-- To make changes, create a new branch by entering: --> +変更するには、以下を入力して新しいブランチを作成します: + +``` +git checkout -b dev_branch +git push --set-upstream origin dev_branch +``` + +<!-- _Same as #7231:25fdbf2a0:newbs_git_using_your_master_branch.md L47_ --> +<!-- This creates a new branch named `dev_branch`, checks it out, and then saves the new branch to your fork. The `--set-upstream` argument tells git to use your fork and the `dev_branch` branch every time you use `git push` or `git pull` from this branch. It only needs to be used on the first push; after that, you can safely use `git push` or `git pull`, without the rest of the arguments. --> +これにより、`dev_branch` という名前の新しいブランチが作成され、チェックアウトされ、新しいブランチがあなたのフォークに保存されます。 +`--set-upstream` 引数は、このブランチから `git push` または `git pull` を使用するたびに、あなたのフォークと `dev_branch` ブランチを使用するように git に指示します。 +この引数は最初のプッシュでのみ使用する必要があります。 +その後、残りの引数なしで `git push` または `git pull` を安全に使用できます。 + +<!-- _Same as #7231:25fdbf2a0:newbs_git_using_your_master_branch.md L49_ --> +<!-- With `git push`, you can use `-u` in place of `--set-upstream` — `-u` is an alias for `--set-upstream`. --> +!> `git push` では、`-set-upstream` の代わりに `-u` を使用できます、 `-u` は `--set-upstream` のエイリアスです。 + +<!-- _Same as #7231:25fdbf2a0:newbs_git_using_your_master_branch.md L51_ --> +<!-- You can name your branch nearly anything you want, though it is recommended to name it something related to the changes you are going to make. --> +ブランチにはほぼ任意の名前を付けることができますが、あなたが行なう変更を表す名前を付けることをお勧めします。 + +<!-- _Same as #7231:25fdbf2a0:newbs_git_using_your_master_branch.md L53_ --> +<!-- By default `git checkout -b` will base your new branch on the branch that is checked out. You can base your new branch on an existing branch that is not checked out by adding the name of the existing branch to the command: --> +デフォルトでは、`git checkout -b`は、今チェックアウトされているブランチに基づいて新しいブランチを作成します。 +コマンド末尾に既存のブランチの名前を追加指定することにより、チェックアウトされていない既存のブランチを基にして新しいブランチを作成できます: + +``` +git checkout -b dev_branch master +``` + +<!-- _Same as #7231:25fdbf2a0:newbs_git_using_your_master_branch.md L59_ --> +<!-- Now that you have a development branch, open your text editor and make whatever changes you need to make. It is recommended to make many small commits to your branch; that way, any change that causes issues can be more easily traced and undone if needed. To make your changes, edit and save any files that need to be updated, add them to Git's *staging area*, and then commit them to your branch: --> +これで開発ブランチができたのでテキストエディタを開き必要な変更を加えます。 +ブランチに対して多くの小さなコミットを行うことをお勧めします。 +そうすることで、問題を引き起こす変更をより簡単に特定し必要に応じて元に戻すことができます。 +変更を加えるには、更新が必要なファイルを編集して保存し、Git の *ステージングエリア* に追加してから、ブランチにコミットします: + +``` +git add path/to/updated_file +git commit -m "My commit message." +``` + +<!-- _Same as #7231:25fdbf2a0:newbs_git_using_your_master_branch.md L66_ --> +<!-- `git add` adds files that have been changed to Git's *staging area*, which is Git's "loading zone." This contains the changes that are going to be *committed* by `git commit`, which saves the changes to the repo. Use descriptive commit messages so you can know what was changed at a glance. --> +`git add`は、変更されたファイルを Git の *ステージングエリア* に追加します。 +これは、Git の「ロードゾーン」です。 +これには、`git commit` によって *コミット* される変更が含まれており、リポジトリへの変更が保存されます。 +変更内容が一目でわかるように、説明的なコミットメッセージを使用します。 + +<!-- _Same as #7231:25fdbf2a0:newbs_git_using_your_master_branch.md L68_ --> +<!-- !> If you've changed a lot of files, but all the files are part of the same change, you can use `git add .` to add all the changed files that are in your current directory, rather than having to add each file individually. --> +!> 多くのファイルを変更したが、すべてのファイルが同じ変更の一部である場合、各ファイルを個別に追加するのではなく、 `git add .` を使用して、現在のディレクトリにあるすべての変更されたファイルを追加できます。 + +<!-- ### Publishing Your Changes --> +### 変更を公開する + +<!-- _Same as #7231:25fdbf2a0:newbs_git_using_your_master_branch.md L72_ --> +<!-- The last step is to push your changes to your fork. To do this, enter `git push`. Git now publishes the current state of `dev_branch` to your fork. --> +最後のステップは、変更をフォークにプッシュすることです。これを行うには、`git push`と入力します。 +Git は `dev_branch` の現在の状態をフォークに公開します。 + +<!-- ## Resolving Merge Conflicts --> +## マージの競合の解決 + +<!-- _Same as #7231:25fdbf2a0:newbs_git_resolving_merge_conflicts.md L3_ --> +<!-- Sometimes when your work in a branch takes a long time to complete, changes that have been made by others conflict with changes you have made to your branch when you open a pull request. This is called a *merge conflict*, and is what happens when multiple people edit the same parts of the same files. --> +ブランチでの作業の完了に時間がかかる場合、他の人が行った変更が、プルリクエストを開いたときにブランチに加えた変更と競合することがあります。 +これは *マージの競合* と呼ばれ、複数の人が同じファイルの同じ部分を編集すると発生します。 + +<!-- ### Rebasing Your Changes --> +### 変更のリベース + +<!-- _Same as #7231:25fdbf2a0:newbs_git_resolving_merge_conflicts.md L9_ --> +<!-- A *rebase* is Git's way of taking changes that were applied at one point, reversing them, and then applying the same changes to another point. In the case of a merge conflict, you can rebase your branch to grab the changes that were made between when you created your branch and the present time. --> +*リベース* は、ある時点で適用された変更を取得し、それらを元に戻し、次に同じ変更を別のポイントに適用する Git の方法です。 +マージの競合が発生した場合、ブランチをリベースして、ブランチを作成してから現在までに行われた変更を取得できます。 + +<!-- _Same as #7231:25fdbf2a0:newbs_git_resolving_merge_conflicts.md L11_ --> +<!-- To start, run the following: --> +開始するには、次を実行します: + +``` +git fetch upstream +git rev-list --left-right --count HEAD...upstream/master +``` + +<!-- _Same as #7231:25fdbf2a0:newbs_git_resolving_merge_conflicts.md L18_ --> +<!-- The `git rev-list` command entered here returns the number of commits that differ between the current branch and QMK's master branch. We run `git fetch` first to make sure we have the refs that represent the current state of the upstream repo. The output of the `git rev-list` command entered returns two numbers: --> +ここに入力された `git rev-list` コマンドは、現在のブランチと QMK の master ブランチで異なるコミットの数を返します。 +最初に `git fetch` を実行して、upstream リポジトリの現在の状態を表す refs があることを確認します。 +入力された `git rev-list` コマンドの出力は2つの数値を返します: + +``` +$ git rev-list --left-right --count HEAD...upstream/master +7 35 +``` + +<!-- _Same as #7231:25fdbf2a0:newbs_git_resolving_merge_conflicts.md L25_ --> +<!-- The first number represents the number of commits on the current branch since it was created, and the second number is the number of commits made to `upstream/master` since the current branch was created, and thus, the changes that are not recorded in the current branch. --> +最初の数字は、現在のブランチが作成されてからのコミット数を表し、2番目の数字は、現在のブランチが作成されてから `upstream/master` に対して行われたコミットの数であり、したがって、現在のブランチに記録されていない変更です。 + +<!-- _Same as #7231:25fdbf2a0:newbs_git_resolving_merge_conflicts.md L27_--> +<!-- Now that the current states of both the current branch and the upstream repo are known, we can start a rebase operation: --> +現在のブランチと upstream リポジトリの両方の現在の状態がわかったので、リベース操作を開始できます: + +``` +git rebase upstream/master +``` + +<!-- _Same as #7231:25fdbf2a0:newbs_git_resolving_merge_conflicts.md L33_ --> +<!-- This tells Git to undo the commits on the current branch, and then reapply them against QMK's master branch. --> +これにより、Git は現在のブランチのコミットを取り消してから、QMK の master ブランチに対してコミットを再適用します。 + +``` +$ git rebase upstream/master +First, rewinding head to replay your work on top of it... +Applying: Commit #1 +Using index info to reconstruct a base tree... +M conflicting_file_1.txt +Falling back to patching base and 3-way merge... +Auto-merging conflicting_file_1.txt +CONFLICT (content): Merge conflict in conflicting_file_1.txt +error: Failed to merge in the changes. +hint: Use 'git am --show-current-patch' to see the failed patch +Patch failed at 0001 Commit #1 + +Resolve all conflicts manually, mark them as resolved with +"git add/rm <conflicted_files>", then run "git rebase --continue". +You can instead skip this commit: run "git rebase --skip". +To abort and get back to the state before "git rebase", run "git rebase --abort". +``` + +<!-- _Same as #7231:25fdbf2a0:newbs_git_resolving_merge_conflicts.md L54_ --> +<!-- This tells us that we have a merge conflict, and gives the name of the file with the conflict. Open the conflicting file in your text editor, and somewhere in the file, you'll find something like this: --> +これにより、マージの競合があることがわかり、競合のあるファイルの名前が示されます。 +テキストエディタで競合するファイルを開くと、ファイルのどこかに次のような行があります: + +``` +<<<<<<< HEAD +<p>For help with any issues, email us at support@webhost.us.</p> +======= +<p>Need help? Email support@webhost.us.</p> +>>>>>>> Commit #1 +``` + +<!-- _Same as #7231:25fdbf2a0:newbs_git_resolving_merge_conflicts.md L64_ --> +<!-- The line `<<<<<<< HEAD` marks the beginning of a merge conflict, and the `>>>>>>> Commit #1` line marks the end, with the conflicting sections separated by `=======`. The part on the `HEAD` side is from the QMK master version of the file, and the part marked with the commit message is from the current branch and commit. --> +行 `<<<<<<< HEAD` はマージ競合の始まりを示し、行 `>>>>>>> commit #1` は終了を示し、競合するセクションは `=======` で区切られます。 +`HEAD` 側の部分はファイルの QMK master バージョンからのものであり、コミットメッセージでマークされた部分は現在のブランチとコミットからのものです。 + +<!-- _Same as #7231:25fdbf2a0:newbs_git_resolving_merge_conflicts.md L66_ --> +<!-- Because Git tracks *changes to files* rather than the contents of the files directly, if Git can't find the text that was in the file previous to the commit that was made, it won't know how to edit the file. Re-editing the file will solve the conflict. Make your changes, and then save the file. --> +Git はファイルの内容ではなく *ファイルへの変更* を直接追跡するため、Git がコミットの前にファイル内にあったテキストを見つけられない場合、ファイルの編集方法がわかりません。 +ファイルを再編集して、競合を解決します。 +変更を加えてから、ファイルを保存します。 + +``` +<p>Need help? Email support@webhost.us.</p> +``` + +そしてコマンド実行: + +``` +git add conflicting_file_1.txt +git rebase --continue +``` + +<!-- _Same as #7231:25fdbf2a0:newbs_git_resolving_merge_conflicts.md L79_ --> +<!-- Git logs the changes to the conflicting file, and continues applying the commits from our branch until it reaches the end. --> +Git は、競合するファイルへの変更をログに記録し、ブランチのコミットが最後に達するまで適用し続けます。 diff --git a/docs/ja/newbs_building_firmware.md b/docs/ja/newbs_building_firmware.md new file mode 100644 index 000000000..f9a847f4d --- /dev/null +++ b/docs/ja/newbs_building_firmware.md @@ -0,0 +1,99 @@ +# 初めてのファームウェアを構築する(コマンドライン版) + +<!--- + grep --no-filename "^[ ]*git diff" docs/ja/*.md | sh + original document: ed0575fc8:docs/newbs_building_firmware.md + git diff ed0575fc8 HEAD docs/newbs_building_firmware.md | cat +--> + +ビルド環境をセットアップしたので、カスタムファームウェアのビルドを開始する準備ができました。 +ガイドのこのセクションでは、ファイルマネージャ、テキストエディタ、ターミナルウィンドウの3つのプログラム間を行き来します。 +キーボードファームウェアが完成して満足するまで、この3つすべてを開いたままにします。 + +ガイドの最初の部分を読んだ後でターミナルウィンドウを閉じて再度開いていた場合は、ターミナルが正しいディレクトリにあるように `cd qmk_firmware` を忘れないでください。 + +## キーマップフォルダに移動する + +あなたのキーボードの `keymaps`フォルダに移動することから始めます。 + +macOS または Windows を使用している場合は、キーマップフォルダを簡単に開くために使用できるコマンドがあります。 + +### macOS: + +``` open keyboards/<keyboard_folder>/keymaps ``` + +### Windows: + +``` start .\\keyboards\\<keyboard_folder>\\keymaps ``` + +## `default` キーマップのコピーを作成する + +`keymaps` フォルダを開いたら、`default`フォルダのコピーを作成します。 +フォルダには、あなたの GitHub でのユーザー名と同じ名前を付けることを強くお勧めしますが、小文字、数字、アンダースコアのみが含まれている限り、任意の名前を使用できます。 + +この手順を自動化するために、`new_keymap.sh`スクリプトを実行する方法もあります。 + +`qmk_firmware/util` ディレクトリに移動して、次を入力します。 + +``` +./new_keymap.sh <keyboard path> <username> +``` + +たとえば、John という名前のユーザーが 1up60hse の新しいキーマップを作成しようとするには、次のように入力します。 + +``` +./new_keymap.sh 1upkeyboards/1up60hse john +``` + +## あなたの好みのテキストエディタで `keymap.c` を開く + +`keymap.c`を開きます。 +このファイル内には、キーボードの動作を制御する構造があります。 +`keymap.c`の上部には、キーマップを読みやすくする `define` と `enum` があります。 +さらに下には、次のような行があります。 + + const uint16_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] = { + +この行はレイヤーのリストの開始を表わしています。 +その下には、`LAYOUT` または `KEYMAP` のいずれかを含む行があり、これらの行はレイヤーの開始を表わしています。 +その行の下には、その特定のレイヤーを構成するキーのリストがあります。 + +!> キーマップファイルを編集するときは、カンマを追加したり削除したりしないように注意してください。そうするとファームウェアのコンパイルができなくなり、余分であったり欠落していたりするカンマがどこにあるのかを容易に把握できない場合があります。 + +## 好みに合わせてレイアウトをカスタマイズ + +納得のいくまでこのステップを繰り返します。 +気になる点をひとつづつ変更して試すのもよし、全部作りなおすのもよし。 +あるレイヤー全体が必要ない場合はレイヤーを削除することもでき、必要があれば、合計 32 個までレイヤーを追加することもできます。 +ここで定義できる内容については、次のドキュメントを参照してください。 + +* [キーコード](ja/keycodes.md) +* [機能](ja/features.md) +* [FAQ](ja/faq.md) + +?> キーマップがどのように機能するかを感じながら、各変更を小さくしてください。大きな変更は、発生する問題のデバッグを困難にします。 + +## ファームウェアをビルドする + +キーマップの変更が完了したら、ファームウェアをビルドする必要があります。これを行うには、ターミナルウィンドウに戻り、ビルドコマンドを実行します: + + make <my_keyboard>:<my_keymap> + +たとえば、キーマップの名前が "xyverz" で、rev5 planck のキーマップを作成している場合、次のコマンドを使用します: + + make planck/rev5:xyverz + +これがコンパイルされる間、どのファイルがコンパイルされているかを知らせる多くの出力が画面に表示されます。 +次のような出力で終わるはずです。 + +``` +Linking: .build/planck_rev5_xyverz.elf [OK] +Creating load file for flashing: .build/planck_rev5_xyverz.hex [OK] +Copying planck_rev5_xyverz.hex to qmk_firmware folder [OK] +Checking file size of planck_rev5_xyverz.hex [OK] + * File size is fine - 18392/28672 +``` + +## ファームウェアを書きこむ + +[「ファームウェアを書きこむ」](ja/newbs_flashing.md) に移動して、キーボードに新しいファームウェアを書き込む方法を学習します。 diff --git a/docs/ja/newbs_building_firmware_configurator.md b/docs/ja/newbs_building_firmware_configurator.md new file mode 100644 index 000000000..228269b34 --- /dev/null +++ b/docs/ja/newbs_building_firmware_configurator.md @@ -0,0 +1,113 @@ +# QMK Configurator + +<!--- + grep --no-filename "^[ ]*git diff" docs/ja/*.md | sh + original document: ed0575fc8:docs/newbs_building_firmware_configurator.md + git diff ed0575fc8 HEAD docs/newbs_building_firmware_configurator.md | cat +--> + +[QMK Configurator](https://config.qmk.fm) は、QMKファームウェアの hex ファイルを生成するオンライングラフィカルユーザーインターフェイスです。 + +?> **次の手順を順番に実行してください。** + +[Video Tutorial](https://youtu.be/tx54jkRC9ZY) を見てください。 + +QMK Configurator は Chrome/Firefox で最適に動作します。 + +!> **KLE や kbfirmware などの他のツールのファイルは、QMK Configurator と互換性がありません。それらをロードしたり、インポートしたりしないでください。QMK Configurator は異なるツールです。** + +## キーボードを選ぶ + +ドロップダウンボックスをクリックして、キーマップを作成するキーボードを選択します。 + +?> **キーボードに複数のバージョンがある場合は、正しいバージョンを選択してください。** + +大事なことなのでもう一度言います。 + +!> **正しいバージョンを選択してください!** + +キーボードが QMK を搭載していると宣伝されていてもリストにない場合は、開発者がまだ作業中か、私たちがまだマージするきっかけがなかった可能性があります。 +アクティブな [Pull Request](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 搭載キーボードもあります。 +それも再確認してください。 + +## キーボードのレイアウトを選択する + +作成したいと思うキーマップに最も近いレイアウトを選択します。一部のキーボードには、まだ十分なレイアウトまたは正しいレイアウトが定義されていません。これらは将来サポートされる予定です。 + +## キーマップの名前 + +お好みの名前をキーマップにつけます。 + +?> コンパイル時に問題が発生した場合は、もしかすると QMK ファームウェアリポジトリに既に同じ名前が存在しているのかもしれません、名前を変更してみてください。 + +## キーマップを作る + +キーコード入力は3つの方法で実行できます。 +1. ドラッグ・アンド・ドロップ +2. レイアウト上の空の場所をクリックして、希望するキーコードをクリックします +3. レイアウト上の空の場所をクリックして、キーボードの物理キーを押します + +マウスをキーの上に置くと、そのキーコードの機能の短い説明文が出ます。より詳細な説明については以下を見てください。 + +[Basic Keycode Reference](https://docs.qmk.fm/#/keycodes_basic) +[Advanced Keycode Reference](https://docs.qmk.fm/#/feature_advanced_keycodes) + +キーマップをサポートするレイアウトが見つからない場合、例えばスペースバーが3分割されていたり、バックスペースが2分割されていたり、シフトが2分割されているような場合、それらを全て埋めてください。 + +### 例: + +3分割のスペースバー: 全てスペースバーで埋めます。 + +2分割のバックスペース: 両方ともバックスペースで埋めます。 + +2分割の右シフト: 両方とも右シフトで埋めます。 + +左シフトとISOサポート用に1つずつ: 両方とも左シフトで埋めます。 + +5分割だが4キーのみ: 以前やったことがある人を推測して確認するか尋ねてください。 + +## 後日のためにキーマップを保存する + +キーマップに満足するか、または後で作業したい場合は、`Export Keymap' ボタンを押します。上記で選択した名前に .json が追加されたキーマップが保存されます。 + +後日、`Import Keymap` ボタンを押すことで、この .json ファイルをロードできます。 + +!> **注意:** このファイルは、kbfirmware.com またはその他のツールに使用される .jsonファイルと同じ形式ではありません。これらのツールにこれを使用したり、QMK Configurator でこれらのツールの .json を使用しようとすると、キーボードが **爆発** する可能性があります。 + +## ファームウェアファイルを生成する + +緑色の `Compile` ボタンを押します。 + +コンパイルが完了すると、緑色の `Download Firmware` ボタンを押すことができます。 + +## キーボードに書き込む(フラッシュする) + +[ファームウェアを書きこむ](ja/newbs_flashing.md) を参照してください。 + +## トラブルシューティング + +#### 私の .json ファイルが動きません + +.json ファイルが QMK Configurator で作ったものの場合、おめでとうございます。バグに遭遇しました。 [qmk_configurator](https://github.com/qmk/qmk_configurator/issues) で報告してください。 + +そうでない場合は、... 他の .json ファイルを使用しないようにという、上に書いた注意書きを見逃してませんか？ + +#### レイアウトに余分なスペースがありますか？どうすればいいですか？ + +もしスペースバーが3つに分かれている場合は、全てスペースバーで埋めるのが最善の方法です。バックスペースやシフトについても同じことができます。 + +#### キーコードってなに？ + +以下を見てください。 + +[Basic Keycode Reference](https://docs.qmk.fm/#/keycodes_basic) +[Advanced Keycode Reference](https://docs.qmk.fm/#/feature_advanced_keycodes) + +#### コンパイルできません + +キーマップの他のレイヤーを再確認して、ランダムなキーが存在しないことを確認してください。 + +## 問題とバグ + +私たちは利用者の依頼やバグレポートを常に受け入れています。[qmk_configurator](https://github.com/qmk/qmk_configurator/issues) で報告してください。 diff --git a/docs/ja/newbs_flashing.md b/docs/ja/newbs_flashing.md new file mode 100644 index 000000000..3407b4625 --- /dev/null +++ b/docs/ja/newbs_flashing.md @@ -0,0 +1,400 @@ +# ファームウェアを書きこむ + +<!--- + grep --no-filename "^[ ]*git diff" docs/ja/*.md | sh + original document: ed0575fc8:docs/newbs_flashing.md + git diff ed0575fc8 HEAD docs/newbs_flashing.md | cat +--> + +カスタムファームウェアは出来たので、キーボードに書き込みたくなるでしょう/フラッシュしたくなるでしょう。 + +## QMK Toolbox を使ってキーボードに書き込む + +キーボードに書き込む最も簡単な方法は [QMK Toolbox](https://github.com/qmk/qmk_toolbox/releases) を使うことです。 + +ただし、QMK Toolbox は、現在は Windows と macOS でしか使えません。 +Linuxを使用している場合(および、コマンドラインでファームウェアを書き込みたい場合)は、下の方で概説する[方法](ja/newbs_flashing.md#flash-your-keyboard-from-the-command-line)で行なう必要があります。 + +### QMK Toolbox にファイルをロードする + +まず QMK Toolbox アプリケーションを起動します。 +Finder またはエクスプローラーでファームウェアのファイルを探します。 +ファイル名は `.hex` または `.bin` のどちらかの形式です。 +ビルド時に QMK は、キーボードに適した形式のものを `qmk_firmware` のトップフォルダにコピーしているはずです。 + +Windows か macOS を使用しているときは現在のファームウェアフォルダをエクスプローラーか Finder で簡単に開くためのコマンドがあります。 + +#### Windows + +``` +start . +``` + +#### macOS + +``` +open . +``` + +ファームウェアファイルは常に以下の命名形式に従っています。 + +``` +<keyboard_name>_<keymap_name>.{bin,hex} +``` + +例えば、`plank/rev5` の `default` キーマップのファイル名は以下のようになります。 + +``` +planck_rev5_default.hex +``` + +ファームウェアファイルを見つけたら、QMK Toolbox の "Local file" ボックスにドラッグするか、"Open" をクリックしてファームウェアファイルを指定します。 + +### キーボードを DFU (Bootloader) モードにする + +ファームウェアを書き込むには、キーボードを普段とは違う特別な状態、フラッシュモードにする必要があります。 +このモードでは、キーボードはキーボードとしての機能をはたしません。 +ファームウェアの書き込み中にキーボードのケーブルを抜いたり、書き込みプロセスを中断したりしないことが非常に重要です。 + +キーボードによって、この特別なモードに入る方法は異なります。 +キーボードが現在 QMK または TMK を実行しており、キーボードメーカーから具体的な指示が与えられていない場合は、次を順番に試してください。 + +* 両方のシフトキーを押しながら、`Pause` キーを押す +* 両方のシフトキーを押しながら、`B` キーを押す +* キーボードのケーブルを抜いて、スペースバーとBを同時に押しながら、キーボードを再び接続し、1秒待ってからキーを放す +* 基板(PCB)に付けられている物理的な `RESET` ボタンを押す +* PCB 上の `BOOT0` か `RESET` のラベルの付いたヘッダピンを探し、PCB 接続中にそれらを互いにショートする + +うまくいけば、QMK Toolboxに次のようなメッセージが表示されます。 + +``` +*** Clueboard - Clueboard 66% HotSwap disconnected -- 0xC1ED:0x2390 +*** DFU device connected +``` + +### キーボードへの書き込み + +QMK Toolbox の `Flash` ボタンをクリックします。 +次のような出力が表示されます。 + +``` +*** Clueboard - Clueboard 66% HotSwap disconnected -- 0xC1ED:0x2390 +*** DFU device connected +*** Attempting to flash, please don't remove device +>>> dfu-programmer atmega32u4 erase --force + Erasing flash... Success + Checking memory from 0x0 to 0x6FFF... Empty. +>>> dfu-programmer atmega32u4 flash /Users/skully/qmk_firmware/clueboard_66_hotswap_gen1_skully.hex + Checking memory from 0x0 to 0x55FF... Empty. + 0% 100% Programming 0x5600 bytes... + [>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>] Success + 0% 100% Reading 0x7000 bytes... + [>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>] Success + Validating... Success + 0x5600 bytes written into 0x7000 bytes memory (76.79%). +>>> dfu-programmer atmega32u4 reset + +*** DFU device disconnected +*** Clueboard - Clueboard 66% HotSwap connected -- 0xC1ED:0x2390 +``` + +## コマンドラインでファームウェアを書き込む :id=flash-your-keyboard-from-the-command-line + +これは、以前のものと比較して非常に単純になりました。 +ファームウェアをコンパイルして書き込む準備ができたら、ターミナルウィンドウを開いてビルドコマンドを実行します。 + + make <my_keyboard>:<my_keymap>:flash + +たとえば、キーマップの名前が xyverz で、rev5 planck のキーマップを作成している場合、次のコマンドを使用します。 + + make planck/rev5:xyverz:flash + +これにより、キーボードの構成が確認され、指定されたブートローダに基づいてキーボードへの書き込みが試行されます。 +これはあなたがキーボードが使用するブートローダを知る必要がないことを意味します。 +コマンドをただ実行して、コマンド自身に難しい処理を任せます。 + +ただし、これはキーボードごとに設定されているブートローダに依存します。 +もしこの情報が設定されていない場合、または使用しているキーボードのファームウェアの書き込みにサポートしていないターゲットが設定されている場合、次のエラーが表示されます。 + + WARNING: This board's bootloader is not specified or is not supported by the ":flash" target at this time. + +この場合、あなたは明示的にブートローダを指定する方法を使わなければなりません。 + +ブートローダは主に 5 種類のものが使われています。 +Pro Micro とそのクローンは Caterina を、Teensy は HalfKay を、OLKBの AVR ボードは QMK-DFU を、その他の ATmega32U4 ボードは DFU を、そして多くの ARM ボードは ARM DFU を使います。 + +より詳しいブートローダの情報は、[Flashing Instructions and Bootloader Information](ja/flashing.md) にあります。 + +使用しているブートローダがわかっているならば、ファームウェアをコンパイルするときに、実は `make` コマンドにブートローダを指定するテキストを追加して、書き込みプロセスを自動化できます。 + +### DFU + +DFU ブートローダの場合、ファームウェアをコンパイルして書き込む準備ができたら、ターミナルウィンドウを開いてビルドコマンドを実行します。 + + make <my_keyboard>:<my_keymap>:dfu + +たとえば、キーマップの名前が xyverz で、rev5 planck のキーマップを作成している場合、次のコマンドを使用します。 + + make planck/rev5:xyverz:dfu + +コンパイルが終了すると、以下の出力になるはずです。 + +``` +Linking: .build/planck_rev5_xyverz.elf [OK] +Creating load file for flashing: .build/planck_rev5_xyverz.hex [OK] +Copying planck_rev5_xyverz.hex to qmk_firmware folder [OK] +Checking file size of planck_rev5_xyverz.hex + * File size is fine - 18574/28672 + ``` + +ここまでくると、ビルドスクリプトは5秒ごとに DFU ブートローダを探します。 +デバイスが見つかるか、あなたがキャンセルするまで、以下を繰り返します。 + + dfu-programmer: no device present. + Error: Bootloader not found. Trying again in 5s. + +これを実行したら、コントローラーをリセットする必要があります。 +そして下のような出力が表示されます。 + +``` +*** Attempting to flash, please don't remove device +>>> dfu-programmer atmega32u4 erase --force + Erasing flash... Success + Checking memory from 0x0 to 0x6FFF... Empty. +>>> dfu-programmer atmega32u4 flash /Users/skully/qmk_firmware/clueboard_66_hotswap_gen1_skully.hex + Checking memory from 0x0 to 0x55FF... Empty. + 0% 100% Programming 0x5600 bytes... + [>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>] Success + 0% 100% Reading 0x7000 bytes... + [>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>] Success + Validating... Success + 0x5600 bytes written into 0x7000 bytes memory (76.79%). +>>> dfu-programmer atmega32u4 reset +``` + +?> `dfu-programmer：no device present` など、これに関する問題がある場合は、[よくある質問](ja/faq_build.md) を参照してください。 + +#### DFU コマンド + +ファームウェアを DFU デバイスに書き込むために使用できる DFU コマンドがいくつかあります。 + +* `:dfu` - これが通常のオプションで、DFUデバイスが使用可能になるまで待機したのちファームウェアを書き込みます。5秒ごとに、DFUデバイスが存在するかチェックしています。 +* `:dfu-ee` - 通常の hex ファイルの代わりに `eep` ファイルを書き込みます。これを使用するのはまれです。 +* `:dfu-split-left` - デフォルトオプション (`:dfu`) と同様に、通常のファームウェアが書き込まれます。ただし、分割キーボードの「左側の」 EEPROMファイルも書き込まれます。_これは、Elite C ベースの分割キーボードに最適です。_ +* `:dfu-split-right` - デフォルトオプション (`:dfu`) と同様に、通常のファームウェアが書き込まれます。ただし、分割キーボードの「右側の」EEPROMファイルも書き込まれます。_これは、Elite C ベースの分割キーボードに最適です。_ + + +### Caterina + +Arduino ボードとそれらのクローンの場合(たとえば SparkFun ProMicro)、ファームウェアをコンパイルして書き込む準備ができたら、ターミナルウィンドウを開いてビルドコマンドを実行します。 + + make <my_keyboard>:<my_keymap>:avrdude + +たとえば、キーマップの名前が xyverz で、rev2 Lets Split のキーマップを作成している場合、次のコマンドを使用します。 + + make lets_split/rev2:xyverz:avrdude + +ファームウェアのコンパイルが完了すると、以下のように出力されます。 + +``` +Linking: .build/lets_split_rev2_xyverz.elf [OK] +Creating load file for flashing: .build/lets_split_rev2_xyverz.hex [OK] +Checking file size of lets_split_rev2_xyverz.hex [OK] + * File size is fine - 27938/28672 +Detecting USB port, reset your controller now.............. +``` + +この時点で、キーボードをリセットすると、スクリプトがブートローダを検出し、キーボードに書き込みます。出力は次のようになります。 + +``` +Detected controller on USB port at /dev/ttyS15 + +Connecting to programmer: . +Found programmer: Id = "CATERIN"; type = S + Software Version = 1.0; No Hardware Version given. +Programmer supports auto addr increment. +Programmer supports buffered memory access with buffersize=128 bytes. + +Programmer supports the following devices: + Device code: 0x44 + +avrdude.exe: AVR device initialized and ready to accept instructions + +Reading | ################################################## | 100% 0.00s + +avrdude.exe: Device signature = 0x1e9587 (probably m32u4) +avrdude.exe: NOTE: "flash" memory has been specified, an erase cycle will be performed + To disable this feature, specify the -D option. +avrdude.exe: erasing chip +avrdude.exe: reading input file "./.build/lets_split_rev2_xyverz.hex" +avrdude.exe: input file ./.build/lets_split_rev2_xyverz.hex auto detected as Intel Hex +avrdude.exe: writing flash (27938 bytes): + +Writing | ################################################## | 100% 2.40s + +avrdude.exe: 27938 bytes of flash written +avrdude.exe: verifying flash memory against ./.build/lets_split_rev2_xyverz.hex: +avrdude.exe: load data flash data from input file ./.build/lets_split_rev2_xyverz.hex: +avrdude.exe: input file ./.build/lets_split_rev2_xyverz.hex auto detected as Intel Hex +avrdude.exe: input file ./.build/lets_split_rev2_xyverz.hex contains 27938 bytes +avrdude.exe: reading on-chip flash data: + +Reading | ################################################## | 100% 0.43s + +avrdude.exe: verifying ... +avrdude.exe: 27938 bytes of flash verified + +avrdude.exe: safemode: Fuses OK (E:CB, H:D8, L:FF) + +avrdude.exe done. Thank you. +``` +うまくいかない時は、以下のようにする必要があるかもしれません。 + + sudo make <my_keyboard>:<my_keymap>:avrdude + + +#### Caterina コマンド + +ファームウェアを DFU デバイスに書き込むために使用できる DFU コマンドがいくつかあります。 + +* `:avrdude` - これが通常のオプションで、Caterina デバイスが(新しい COM ポートを検出して)使用可能になるまで待機し、ファームウェアを書き込みます。 +* `:avrdude-loop` - これは `:avrdude` と同じです。ただし書き込みが終了すると再び Caterina デバイスの書き込み待ちに戻ります。これは何台ものデバイスへの書き込みに便利です。_Control+C を押して、手動でこの繰り返しを終了させる必要があります。_ +* `:avrdude-split-left` - デフォルトオプション(`:avrdude`)と同様に通常のファームウェアが書き込まれます。ただし、分割キーボードの「左側の」EEPROMファイルもフラッシュされます。 _これは、Pro Micro ベースの分割キーボードに最適です。_ +* `:avrdude-split-right` - デフォルトオプション(`:avrdude`)と同様に通常のファームウェアが書き込まれます。ただし、分割キーボードの「右側の」EEPROMファイルもフラッシュされます。 _これは、Pro Micro ベースの分割キーボードに最適です。_ + +### HalfKay + +PJRC デバイス(Teensy シリーズ)の場合、ファームウェアをコンパイルして書き込む準備ができたら、ターミナルウィンドウを開いてビルドコマンドを実行します。 + + make <my_keyboard>:<my_keymap>:teensy + +たとえば、キーマップの名前が xyverz で、Ergodox または Ergodox EZ のキーマップを作成している場合、次のコマンドを使用します。 + + make ergodox_ez:xyverz:teensy + +ファームウェアのコンパイルが完了すると、以下のように出力されます。 + +``` +Linking: .build/ergodox_ez_xyverz.elf [OK] +Creating load file for flashing: .build/ergodox_ez_xyverz.hex [OK] +Checking file size of ergodox_ez_xyverz.hex [OK] + * File size is fine - 25584/32256 + Teensy Loader, Command Line, Version 2.1 +Read "./.build/ergodox_ez_xyverz.hex": 25584 bytes, 79.3% usage +Waiting for Teensy device... + (hint: press the reset button) + ``` + +この時点で、キーボードをリセットします。すると、次のような出力が表示されます。 + + ``` + Found HalfKay Bootloader +Read "./.build/ergodox_ez_xyverz.hex": 28532 bytes, 88.5% usage +Programming............................................................................................................................................................................ +................................................... +Booting +``` + +### STM32 (ARM) + +主な ARM ボード (Proton C, Planck Rev 6, Preonic Rev 3 を含む)の場合、ファームウェアをコンパイルして書き込む準備ができたら、ターミナルウィンドウを開いてビルドコマンドを実行します。 + + make <my_keyboard>:<my_keymap>:dfu-util + +たとえば、キーマップの名前が xyverz で、Planck Revision 6 のキーマップを作成している場合、次のコマンドを使用し、(コンパイルが終わる前に)キーボードを再起動してブートローダを起動します: + + make planck/rev6:xyverz:dfu-util + +ファームウェアのコンパイルが完了すると、以下のように出力されます。 + +``` +Linking: .build/planck_rev6_xyverz.elf [OK] +Creating binary load file for flashing: .build/planck_rev6_xyverz.bin [OK] +Creating load file for flashing: .build/planck_rev6_xyverz.hex [OK] + +Size after: + text data bss dec hex filename + 0 41820 0 41820 a35c .build/planck_rev6_xyverz.hex + +Copying planck_rev6_xyverz.bin to qmk_firmware folder [OK] +dfu-util 0.9 + +Copyright 2005-2009 Weston Schmidt, Harald Welte and OpenMoko Inc. +Copyright 2010-2016 Tormod Volden and Stefan Schmidt +This program is Free Software and has ABSOLUTELY NO WARRANTY +Please report bugs to http://sourceforge.net/p/dfu-util/tickets/ + +Invalid DFU suffix signature +A valid DFU suffix will be required in a future dfu-util release!!! +Opening DFU capable USB device... +ID 0483:df11 +Run-time device DFU version 011a +Claiming USB DFU Interface... +Setting Alternate Setting #0 ... +Determining device status: state = dfuERROR, status = 10 +dfuERROR, clearing status +Determining device status: state = dfuIDLE, status = 0 +dfuIDLE, continuing +DFU mode device DFU version 011a +Device returned transfer size 2048 +DfuSe interface name: "Internal Flash " +Downloading to address = 0x08000000, size = 41824 +Download [=========================] 100% 41824 bytes +Download done. +File downloaded successfully +Transitioning to dfuMANIFEST state +``` + +#### STM32 コマンド + +ファームウェアを STM32 デバイスに書き込むために使用できる DFU コマンドがいくつかあります。 + +* `:dfu-util` - STM32 デバイスに書き込むためのデフォルトコマンドで、STM32 ブートローダが見つかるまで待機します。 +* `:dfu-util-split-left` - デフォルトのオプション (`:dfu-util`) と同様に、通常のファームウェアが書き込まれます。 ただし、分割キーボードの「左側の」EEPROM の設定も行われます。 +* `:dfu-util-split-right` - デフォルトのオプション (`:dfu-util`) と同様に、通常のファームウェアが書き込まれます。 ただし、分割キーボードの「右側の」EEPROM の設定も行われます。 +* `:st-link-cli` - dfu-util ではなく、ST-LINK の CLI ユーティリティを介してファームウェアを書き込めます。 + +### BootloadHID + +Bootmapper Client(BMC)/bootloadHID/ATmega32A ベースのキーボードの場合、ファームウェアをコンパイルして書き込む準備ができたら、ターミナルウィンドウを開いてビルドコマンドを実行します。 + + make <my_keyboard>:<my_keymap>:bootloaderHID + +たとえば、キーマップの名前が xyverz で、jj40 のキーマップを作成している場合、次のコマンドを使用します。 + + make jj40:xyverz:bootloaderHID + +ファームウェアのコンパイルが完了すると、以下のように出力されます。 + +``` +Linking: .build/jj40_default.elf [OK] +Creating load file for flashing: .build/jj40_default.hex [OK] +Copying jj40_default.hex to qmk_firmware folder [OK] +Checking file size of jj40_default.hex [OK] + * The firmware size is fine - 21920/28672 (6752 bytes free) +``` + +ここまでくると、ビルドスクリプトは5秒ごとに DFU ブートローダを探します。 +デバイスが見つかるか、あなたがキャンセルするまで、以下を繰り返します。 + +``` +Error opening HIDBoot device: The specified device was not found +Trying again in 5s. +``` + +これを実行したら、コントローラーをリセットする必要があります。 +そして下のような出力が表示されます。 + +``` +Page size = 128 (0x80) +Device size = 32768 (0x8000); 30720 bytes remaining +Uploading 22016 (0x5600) bytes starting at 0 (0x0) +0x05580 ... 0x05600 +``` + +## テストしましょう！ + +おめでとうございます！ カスタムファームウェアがキーボードにプログラムされました！ + +使ってみて、すべてがあなたの望むように動作するかどうか確認してください。 +この初心者ガイドを完全なものにするために [テストとデバッグ](ja/newbs_testing_debugging.md) を書いたので、カスタム機能のトラブルシューティング方法については、こちらをご覧ください。 diff --git a/docs/ja/newbs_getting_started.md b/docs/ja/newbs_getting_started.md new file mode 100644 index 000000000..865ed162a --- /dev/null +++ b/docs/ja/newbs_getting_started.md @@ -0,0 +1,122 @@ +# イントロダクション + +<!--- + grep --no-filename "^[ ]*git diff" docs/ja/*.md | sh + original document: docs/newbs_getting_started.md + git diff 161d469 HEAD docs/newbs_getting_started.md | cat +--> + +キーボードにはプロセッサが入っており、それはコンピュータに入っているものと大して違わないものです。 +このプロセッサでは、キーボードのボタンの押し下げの検出を担当しキーボードのどのボタンが押されている/離されているかのレポートをコンピュータに送信するソフトウェアが動作しています。 +QMK は、そのソフトウェアの役割を果たし、ボタンの押下を検出しその情報をホストコンピュータに渡します。 +カスタムキーマップを作るということは、キーボード上で動くプログラムを作るということなのです。 + +QMK は、簡単なことは簡単に、そして、難しいことを可能なことにすることで、あなたの手にたくさんのパワーをもたらします。 +パワフルなキーマップを作るためにプログラムを作成する方法を知る必要はありません。いくつかのシンプルな文法に従うだけでOKです。 + +# はじめに + +キーマップをビルドする前に、いくつかのソフトウェアをインストールしてビルド環境を構築する必要があります。 +ファームウェアをコンパイルするキーボードの数に関わらず、この作業を一度だけ実行する必要があります。 + +もし、GUI で作業をしたい場合、オンラインで作業できる [QMK Configurator](https://config.qmk.fm) を使ってください。 +使い方は [オンライン GUI を使用して初めてのファームウェアを構築する](ja/newbs_building_firmware_configurator.md) を参照してください。 + +## ソフトウェアのダウンロード + +### テキストエディタ + +GUI を使わない場合、プレーンテキストを編集・保存できるエディタが必要です。 +Windows の場合、メモ帳が使えます。Linux の場合、gedit が使えます。 +どちらもシンプルですが機能的なテキストエディタです。 +macOS では、デフォルトのテキストエディットアプリに注意してください。_フォーマット_ メニューから _標準テキストにする_ を選択しない限り、プレーンテキストとして保存されません。 + +[Sublime Text](https://www.sublimetext.com/) や [VS Code](https://code.visualstudio.com/) のような専用のテキストエディタをダウンロードしてインストールすることもできます。これらのプログラムはコードを編集するために特別に作成されているため、これはプラットフォームに関係なくベストな方法です。 + +?> どのエディタを使えば良いか分からない場合、Laurence Bradford が書いたこの記事 [a great introduction](https://learntocodewith.me/programming/basics/text-editors/) を読んでください。 + +### QMK Toolbox + +QMK Toolbox は、Windows と macOS で使える GUI を備えたプログラムで、カスタムキーボードのプログラミングとデバッグの両方ができます。 +このプログラムは、キーボードに簡単にファームウェアを書き込んだり、出力されるデバッグメッセージを確認する際に、かけがえのないものであることがわかるでしょう。 + +[QMK Toolbox の最新版](https://github.com/qmk/qmk_toolbox/releases/latest) + +* Windows 版: `qmk_toolbox.exe` (portable) または `qmk_toolbox_install.exe` (installer) +* macOS 版: `QMK.Toolbox.app.zip` (portable) または `QMK.Toolbox.pkg` (installer) + +## 環境構築 :id=set-up-your-environment + +私たちは、QMK を可能な限り簡単に構築できるように努力しています。 +Linux か Unix 環境を用意するだけで、QMK に残りをインストールさせることができます。 + +?> もし、Linux か Unix のコマンドを使ったことがない場合、こちらで基本的な概念や各種コマンドを学んでください。これらの教材で QMK を使うのに必要なことを学ぶことができます。 + +[Must Know Linux Commands](https://www.guru99.com/must-know-linux-commands.html)<br> +[Some Basic Unix Commands](https://www.tjhsst.edu/~dhyatt/superap/unixcmd.html) + +### Windows + +MSYS2 と Git のインストールが必要です。 + +* [MSYS2 homepage](http://www.msys2.org) の手順に従って MSYS2 をインストールします。 +* 開いている MSYS2 の全ターミナル画面を閉じて、新しい MSYS2 MinGW 64-bit のターミナル画面を開きます。 +* `pacman -S git` を実行して Git をインストールします。 + +### macOS + +[Homebrew homepage](https://brew.sh) の手順に従って Homebrew をインストールしてください。 + +Homebrew をインストールしたら、以下の _QMK の設定_ に進んでください。そのステップでは、他のパッケージをインストールするスクリプトを実行します。 + +### Linux + +Git のインストールが必要です。既にインストールされている可能性は高いですが、そうでない場合、次のコマンドでインストールできます。 + +* Debian / Ubuntu / Devuan: `apt-get install git` +* Fedora / Red Hat / CentOS: `yum install git` +* Arch: `pacman -S git` + +?> 全てのプラットフォームにおいて、Docker を使うことも可能です。[詳細はこちらをクリックしてください](ja/getting_started_build_tools.md#docker)。 + +## QMK の設定 :id=set-up-qmk + +Linux/Unix 環境が準備できたら QMK のダウンロードの準備は完了です。Git を使用して QMK のリポジトリを「クローン」することで QMK をダウンロードします。ターミナルか MSYS2 MinGW ウィンドウを開いて、このガイドの残りの部分では開いたままにします。そのウィンドウ内で、次の2つのコマンドを実行します。 + +```shell +git clone --recurse-submodules https://github.com/qmk/qmk_firmware.git +cd qmk_firmware +``` + +?> 既に [GitHub の使いかた](ja/getting_started_github.md)を知っているなら、clone ではなく fork を勧めます。この一文の意味が分からない場合、このメッセージは無視してかまいません。 + +QMK には、必要な残りの設定を手助けするスクリプトが含まれています。 +セットアップ作業を完了させるため、次のコマンドを実行します。 + + util/qmk_install.sh + +## ビルド環境の確認 + +これで QMK のビルド環境が用意できましたので、キーボードのファームウェアをビルドできます。 +キーボードのデフォルトキーマップをビルドすることから始めます。次の形式のコマンドでビルドできるはずです。 + + make <keyboard>:default + +例）Clueboard 66% のファームウェアをビルドする + + make clueboard/66/rev3:default + +大量の出力の最後に次のように出力されると完了です。 + +``` +Linking: .build/clueboard_66_rev3_default.elf [OK] +Creating load file for flashing: .build/clueboard_66_rev3_default.hex [OK] +Copying clueboard_66_rev3_default.hex to qmk_firmware folder [OK] +Checking file size of clueboard_66_rev3_default.hex [OK] + * The firmware size is fine - 26356/28672 (2316 bytes free) +``` + +# キーマップの作成 + +これであなた専用のキーマップを作成する準備ができました！ +次は [Building Your First Firmware](ja/newbs_building_firmware.md) で専用のキーマップを作成します。 diff --git a/docs/ja/newbs_learn_more_resources.md b/docs/ja/newbs_learn_more_resources.md new file mode 100644 index 000000000..14feb61b3 --- /dev/null +++ b/docs/ja/newbs_learn_more_resources.md @@ -0,0 +1,32 @@ +# 学習リソース + +<!--- + grep --no-filename "^[ ]*git diff" docs/ja/*.md | sh + original document: ed0575fc8:docs/newbs_learn_more_resources.md + git diff ed0575fc8 HEAD docs/newbs_learn_more_resources.md | cat +--> + +これらのリソースは、QMKコミュニティの新しいメンバーに、初心者向けドキュメントで提供されている情報に対する理解を深めることを目的としています。 + +## Git に関するリース: + +### 英語 + +* [Great General Tutorial](https://www.codecademy.com/learn/learn-git) +* [Git Game To Learn From Examples](https://learngitbranching.js.org/) +* [Git Resources to Learn More About Github](ja/getting_started_github.md) +* [Git Resources Aimed Specifically toward QMK](ja/contributing.md) + +### 日本語 + +_日本語のリソース情報を募集中です。_ + +## コマンドラインに関するリソース: + +### 英語 + +* [Good General Tutorial on Command Line](https://www.codecademy.com/learn/learn-the-command-line) + +### 日本語 + +_日本語のリソース情報を募集中です。_ diff --git a/docs/ja/newbs_testing_debugging.md b/docs/ja/newbs_testing_debugging.md new file mode 100644 index 000000000..9cf5c6520 --- /dev/null +++ b/docs/ja/newbs_testing_debugging.md @@ -0,0 +1,107 @@ +# テストとデバッグ + +<!--- + grep --no-filename "^[ ]*git diff" docs/ja/*.md | sh + original document: ed0575fc8:docs/newbs_testing_debugging.md + git diff ed0575fc8 HEAD docs/newbs_testing_debugging.md | cat +--> + +カスタムファームウェアをキーボードへ書き込んだら、テストする準備が整います。運が良ければ全て問題なく動作しているはずですが、もしそうでなければこのドキュメントがどこが悪いのか調べるのに役立ちます。 + +## テスト + +通常、キーボードをテストするのは非常に簡単です。全てのキーをひとつずつ押して、期待されるキーが送信されていることを確認します。キーを押したことを見逃さないためのプログラムもあります。 + +メモ： これらのプログラムはQMKによって提供・承認されたものではありません。 + +* [QMK Configurator](https://config.qmk.fm/#/test/) (Web Based) +* [Switch Hitter](https://web.archive.org/web/20190413233743/https://elitekeyboards.com/switchhitter.php) (Windows Only) +* [Keyboard Viewer](https://www.imore.com/how-use-keyboard-viewer-your-mac) (Mac Only) +* [Keyboard Tester](http://www.keyboardtester.com) (Web Based) +* [Keyboard Checker](http://keyboardchecker.com) (Web Based) + +## デバッグ + +`rules.mk`へ`CONSOLE_ENABLE = yes`の設定をするとキーボードはデバッグ情報を出力します。デフォルトの出力は非常に限られたものですが、デバッグモードをオンにすることでデバッグ情報の量を増やすことが出来ます。キーマップの`DEBUG`キーコードを使用するか、デバッグモードを有効にする [Command](ja/feature_command.md) 機能を使用するか、以下のコードをキーマップに追加します。 + +```c +void keyboard_post_init_user(void) { + // Customise these values to desired behaviour + debug_enable=true; + debug_matrix=true; + //debug_keyboard=true; + //debug_mouse=true; +} +``` + +### QMK Toolboxを使ったデバッグ + +互換性のある環境では、[QMK Toolbox](https://github.com/qmk/qmk_toolbox)を使うことでキーボードからのデバッグメッセージを表示できます。 + +### hid_listenを使ったデバッグ + +ターミナルベースの方法がお好みですか？PJRCが提供する[hid_listen](https://www.pjrc.com/teensy/hid_listen.html)もデバッグメッセージの表示に使用できます。ビルド済みの実行ファイルはWindows, Linux, MacOS用が用意されています。 + +<!-- FIXME: Describe the debugging messages here. --> + +## 独自のデバッグメッセージを送信する + +[custom code](ja/custom_quantum_functions.md)内からデバッグメッセージを出力すると便利な場合があります。それはとても簡単です。ファイルの先頭に`print.h`のインクルードを追加します: + + #include <print.h> + +そのあとは、いくつかの異なったprint関数を使用することが出来ます。 + +* `print("string")`: シンプルな文字列を出力します +* `uprintf("%s string", var)`: フォーマットされた文字列を出力します +* `dprint("string")` デバッグモードが有効な場合のみ、シンプルな文字列を出力します +* `dprintf("%s string", var)`: デバッグモードが有効な場合のみ、フォーマットされた文字列を出力します + +## デバッグの例 + +以下は現実世界での実際のデバッグ手法の例を集めたものです。追加情報は[Debugging/Troubleshooting QMK](ja/faq_debug.md)を参照してください。 + +### マトリックス上のどの場所でキー押下が起こったか？ + +移植する、PCBの問題を診断する場合、キー入力が正しくスキャンされているかどうかを確認することが役立つ場合があります。この手法でのロギングを有効化するには、`keymap.c`へ以下のコードを追加します。 + +```c +bool process_record_user(uint16_t keycode, keyrecord_t *record) { + // コンソールが有効化されている場合、マトリックス上の位置とキー押下状態を出力します +#ifdef CONSOLE_ENABLE + uprintf("KL: kc: %u, col: %u, row: %u, pressed: %u\n", keycode, record->event.key.col, record->event.key.row, record->event.pressed); +#endif + return true; +} +``` + +出力の例 +```text +Waiting for device:....... +Listening: +KL: kc: 169, col: 0, row: 0, pressed: 1 +KL: kc: 169, col: 0, row: 0, pressed: 0 +KL: kc: 174, col: 1, row: 0, pressed: 1 +KL: kc: 174, col: 1, row: 0, pressed: 0 +KL: kc: 172, col: 2, row: 0, pressed: 1 +KL: kc: 172, col: 2, row: 0, pressed: 0 +``` + +### キースキャンにかかる時間の測定 + +パフォーマンスの問題をテストする場合、スイッチマトリックスをスキャンする頻度を知ることが役立ちます。この手法でのロギングを有効化するには`config.h`へ以下のコードを追加します。 + + +```c +#define DEBUG_MATRIX_SCAN_RATE +``` + +出力例 +```text + > matrix scan frequency: 315 + > matrix scan frequency: 313 + > matrix scan frequency: 316 + > matrix scan frequency: 316 + > matrix scan frequency: 316 + > matrix scan frequency: 316 +``` diff --git a/docs/keycodes.md b/docs/keycodes.md index 7dcff03fd..ae0bfb7af 100644 --- a/docs/keycodes.md +++ b/docs/keycodes.md @@ -257,37 +257,37 @@ This is a reference only. Each group of keys links to the page documenting their ## [Bootmagic](feature_bootmagic.md) -|Key |Aliases |Description | -|----------------------------------|---------|-------------------------------------------| -|`MAGIC_SWAP_CONTROL_CAPSLOCK` | |Swap Caps Lock and Left Control | -|`MAGIC_CAPSLOCK_TO_CONTROL` | |Treat Caps Lock as Control | -|`MAGIC_SWAP_LCTL_LGUI` | |Swap Left Control and GUI | -|`MAGIC_SWAP_RCTL_RGUI` | |Swap Right Control and GUI | -|`MAGIC_SWAP_LALT_LGUI` | |Swap Left Alt and GUI | -|`MAGIC_SWAP_RALT_RGUI` | |Swap Right Alt and GUI | -|`MAGIC_NO_GUI` | |Disable the GUI key | -|`MAGIC_SWAP_GRAVE_ESC` | |Swap <code>`</code> and Escape | -|`MAGIC_SWAP_BACKSLASH_BACKSPACE` | |Swap `\` and Backspace | -|`MAGIC_HOST_NKRO` | |Force NKRO on | -|`MAGIC_SWAP_ALT_GUI` |`AG_SWAP`|Swap Alt and GUI on both sides | -|`MAGIC_SWAP_CTL_GUI` |`CG_SWAP`|Swap Ctrl and GUI on both sides (for macOS)| -|`MAGIC_UNSWAP_CONTROL_CAPSLOCK` | |Unswap Caps Lock and Left Control | -|`MAGIC_UNCAPSLOCK_TO_CONTROL` | |Stop treating Caps Lock as Control | -|`MAGIC_UNSWAP_LCTL_LGUI` | |Unswap Left Control and GUI | -|`MAGIC_UNSWAP_RCTL_RGUI` | |Unswap Right Control and GUI | -|`MAGIC_UNSWAP_LALT_LGUI` | |Unswap Left Alt and GUI | -|`MAGIC_UNSWAP_RALT_RGUI` | |Unswap Right Alt and GUI | -|`MAGIC_UNNO_GUI` | |Enable the GUI key | -|`MAGIC_UNSWAP_GRAVE_ESC` | |Unswap <code>`</code> and Escape | -|`MAGIC_UNSWAP_BACKSLASH_BACKSPACE`| |Unswap `\` and Backspace | -|`MAGIC_UNHOST_NKRO` | |Force NKRO off | -|`MAGIC_UNSWAP_ALT_GUI` |`AG_NORM`|Unswap Alt and GUI on both sides | -|`MAGIC_UNSWAP_CTL_GUI` |`CG_NORM`|Unswap Ctrl and GUI on both sides | -|`MAGIC_TOGGLE_ALT_GUI` |`AG_TOGG`|Toggle Alt and GUI swap on both sides | -|`MAGIC_TOGGLE_CTL_GUI` |`CG_TOGG`|Toggle Ctrl and GUI swap on both sides | -|`MAGIC_TOGGLE_NKRO` | |Turn NKRO on or off | -|`MAGIC_EE_HANDS_LEFT` | |Set "Left Hand" for EE_HANDS handedness | -|`MAGIC_EE_HANDS_RIGHT` | |Set "Right Hand" for EE_HANDS handedness | +|Key |Aliases |Description | +|----------------------------------|---------|--------------------------------------------------------------------------| +|`MAGIC_SWAP_CONTROL_CAPSLOCK` |`CL_SWAP`|Swap Caps Lock and Left Control | +|`MAGIC_UNSWAP_CONTROL_CAPSLOCK` |`CL_NORM`|Unswap Caps Lock and Left Control | +|`MAGIC_CAPSLOCK_TO_CONTROL` |`CL_CTRL`|Treat Caps Lock as Control | +|`MAGIC_UNCAPSLOCK_TO_CONTROL` |`CL_CAPS`|Stop treating Caps Lock as Control | +|`MAGIC_SWAP_LCTL_LGUI` |`LCG_SWP`|Swap Left Control and GUI | +|`MAGIC_UNSWAP_LCTL_LGUI` |`LCG_NRM`|Unswap Left Control and GUI | +|`MAGIC_SWAP_RCTL_RGUI` |`RCG_SWP`|Swap Right Control and GUI | +|`MAGIC_UNSWAP_RCTL_RGUI` |`RCG_NRM`|Unswap Right Control and GUI | +|`MAGIC_SWAP_CTL_GUI` |`CG_SWAP`|Swap Control and GUI on both sides | +|`MAGIC_UNSWAP_CTL_GUI` |`CG_NORM`|Unswap Control and GUI on both sides | +|`MAGIC_TOGGLE_CTL_GUI` |`CG_TOGG`|Toggle Control and GUI swap on both sides | +|`MAGIC_SWAP_LALT_LGUI` |`LAG_SWP`|Swap Left Alt and GUI | +|`MAGIC_UNSWAP_LALT_LGUI` |`LAG_NRM`|Unswap Left Alt and GUI | +|`MAGIC_SWAP_RALT_RGUI` |`RAG_SWP`|Swap Right Alt and GUI | +|`MAGIC_UNSWAP_RALT_RGUI` |`RAG_NRM`|Unswap Right Alt and GUI | +|`MAGIC_SWAP_ALT_GUI` |`AG_SWAP`|Swap Alt and GUI on both sides | +|`MAGIC_UNSWAP_ALT_GUI` |`AG_NORM`|Unswap Alt and GUI on both sides | +|`MAGIC_TOGGLE_ALT_GUI` |`AG_TOGG`|Toggle Alt and GUI swap on both sides | +|`MAGIC_NO_GUI` |`GUI_OFF`|Disable the GUI keys | +|`MAGIC_UNNO_GUI` |`GUI_ON` |Enable the GUI keys | +|`MAGIC_SWAP_GRAVE_ESC` |`GE_SWAP`|Swap <code>`</code> and Escape | +|`MAGIC_UNSWAP_GRAVE_ESC` |`GE_NORM`|Unswap <code>`</code> and Escape | +|`MAGIC_SWAP_BACKSLASH_BACKSPACE` |`BS_SWAP`|Swap `\` and Backspace | +|`MAGIC_UNSWAP_BACKSLASH_BACKSPACE`|`BS_NORM`|Unswap `\` and Backspace | +|`MAGIC_HOST_NKRO` |`NK_ON` |Enable N-key rollover | +|`MAGIC_UNHOST_NKRO` |`NK_OFF` |Disable N-key rollover | +|`MAGIC_TOGGLE_NKRO` |`NK_TOGG`|Toggle N-key rollover | +|`MAGIC_EE_HANDS_LEFT` |`EH_LEFT`|Set the master half of a split keyboard as the left hand (for `EE_HANDS`) | +|`MAGIC_EE_HANDS_RIGHT` |`EH_RGHT`|Set the master half of a split keyboard as the right hand (for `EE_HANDS`)| ## [Bluetooth](feature_bluetooth.md) @@ -297,6 +297,16 @@ This is a reference only. Each group of keys links to the page documenting their |`OUT_USB` |USB only | |`OUT_BT` |Bluetooth only | +## [Dynamic Macros](feature_dynamic_macros.md) + +|Key |Alias |Description | +|-----------------|---------|--------------------------------------------------| +|`DYN_REC_START1` |`DM_REC1`|Start recording Macro 1 | +|`DYN_REC_START2` |`DM_REC2`|Start recording Macro 2 | +|`DYN_MACRO_PLAY1`|`DM_PLY1`|Replay Macro 1 | +|`DYN_MACRO_PLAY2`|`DM_PLY2`|Replay Macro 2 | +|`DYN_REC_STOP` |`DM_RSTP`|Finish the macro that is currently being recorded.| + ## [Layer Switching](feature_advanced_keycodes.md#switching-and-toggling-layers) |Key |Description | @@ -379,12 +389,12 @@ This is a reference only. Each group of keys links to the page documenting their |`RGB_TOG` | |Toggle RGB lighting on or off | |`RGB_MODE_FORWARD` |`RGB_MOD` |Cycle through modes, reverse direction when Shift is held | |`RGB_MODE_REVERSE` |`RGB_RMOD`|Cycle through modes in reverse, forward direction when Shift is held| -|`RGB_HUI` | |Increase hue | -|`RGB_HUD` | |Decrease hue | -|`RGB_SAI` | |Increase saturation | -|`RGB_SAD` | |Decrease saturation | -|`RGB_VAI` | |Increase value (brightness) | -|`RGB_VAD` | |Decrease value (brightness) | +|`RGB_HUI` | |Increase hue, decrease hue when Shift is held | +|`RGB_HUD` | |Decrease hue, increase hue when Shift is held | +|`RGB_SAI` | |Increase saturation, decrease saturation when Shift is held | +|`RGB_SAD` | |Decrease saturation, increase saturation when Shift is held | +|`RGB_VAI` | |Increase value (brightness), decrease value when Shift is held | +|`RGB_VAD` | |Decrease value (brightness), increase value 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` |Rainbow animation mode | @@ -397,19 +407,19 @@ This is a reference only. Each group of keys links to the page documenting their ## [RGB Matrix Lighting](feature_rgb_matrix.md) -|Key |Aliases |Description | -|-------------------|----------|--------------------------------------------------------------------| -|`RGB_TOG` | |Toggle RGB lighting on or off | -|`RGB_MODE_FORWARD` |`RGB_MOD` |Cycle through modes, reverse direction when Shift is held | -|`RGB_MODE_REVERSE` |`RGB_RMOD`|Cycle through modes in reverse, forward direction when Shift is held| -|`RGB_HUI` | |Increase hue | -|`RGB_HUD` | |Decrease hue | -|`RGB_SAI` | |Increase saturation | -|`RGB_SAD` | |Decrease saturation | -|`RGB_VAI` | |Increase value (brightness) | -|`RGB_VAD` | |Decrease value (brightness) | -|`RGB_SPI` | |Increase effect speed (does no support eeprom yet) | -|`RGB_SPD` | |Decrease effect speed (does no support eeprom yet) | +|Key |Aliases |Description | +|-------------------|----------|--------------------------------------------------------------------------------------| +|`RGB_TOG` | |Toggle RGB lighting on or off | +|`RGB_MODE_FORWARD` |`RGB_MOD` |Cycle through modes, reverse direction when Shift is held | +|`RGB_MODE_REVERSE` |`RGB_RMOD`|Cycle through modes in reverse, forward direction when Shift is held | +|`RGB_HUI` | |Increase hue, decrease hue when Shift is held | +|`RGB_HUD` | |Decrease hue, increase hue when Shift is held | +|`RGB_SAI` | |Increase saturation, decrease saturation when Shift is held | +|`RGB_SAD` | |Decrease saturation, increase saturation when Shift is held | +|`RGB_VAI` | |Increase value (brightness), decrease value when Shift is held | +|`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| ## [Thermal Printer](feature_thermal_printer.md) diff --git a/docs/newbs.md b/docs/newbs.md index 904a52945..775bba2ca 100644 --- a/docs/newbs.md +++ b/docs/newbs.md @@ -13,7 +13,7 @@ There are 7 main sections to this guide: * [Building Your First Firmware using the online GUI](newbs_building_firmware_configurator.md) * [Flashing Firmware](newbs_flashing.md) * [Testing and Debugging](newbs_testing_debugging.md) -* [Git Best Practices](newbs_best_practices.md) +* [Best Git Practices](newbs_git_best_practices.md) * [Learn More with these Resources](newbs_learn_more_resources.md) This guide is focused on helping someone who has never compiled software before. It makes choices and recommendations based on that viewpoint. There are alternative methods for many of these procedures, and we support most of those alternatives. If you have any doubt about how to accomplish a task you can [ask us for guidance](getting_started_getting_help.md). diff --git a/docs/newbs_best_practices.md b/docs/newbs_best_practices.md deleted file mode 100644 index 61bcc0c6a..000000000 --- a/docs/newbs_best_practices.md +++ /dev/null @@ -1,163 +0,0 @@ -# Best Practices - -## Or, "How I Learned to Stop Worrying and Love Git." - -This document aims to instruct novices in the best ways to have a smooth experience in contributing to QMK. We will walk through the process of contributing to QMK, detailing some ways to make this task easier, and then later we'll break some things in order to teach you how to fix them. - -This document assumes a few things: - -1. You have a GitHub account, and have [forked the qmk_firmware repository](getting_started_github.md) to your account. -2. You've [set up your build environment](newbs_getting_started.md?id=environment-setup). - - -## Your fork's master: Update Often, Commit Never - -It is highly recommended for QMK development, regardless of what is being done or where, to keep your `master` branch updated, but ***never*** commit to it. Instead, do all your changes in a development branch and issue pull requests from your branches when you're developing. - -To reduce the chances of merge conflicts — instances where two or more users have edited the same part of a file concurrently — keep your `master` branch relatively up-to-date, and start any new developments by creating a new branch. - -### Updating your master branch - -To keep your `master` branch updated, it is recommended to add the QMK Firmware repository ("repo") as a remote repository in git. To do this, open your Git command line interface and enter: - -``` -git remote add upstream https://github.com/qmk/qmk_firmware.git -``` - -To verify that the repository has been added, run `git remote -v`, which should return the following: - -``` -$ git remote -v -origin https://github.com/<your_username>/qmk_firmware.git (fetch) -origin https://github.com/<your_username>/qmk_firmware.git (push) -upstream https://github.com/qmk/qmk_firmware.git (fetch) -upstream https://github.com/qmk/qmk_firmware.git (push) -``` - -Now that this is done, you can check for updates to the repo by running `git fetch upstream`. This retrieves the branches and tags — collectively referred to as "refs" — from the QMK repo, which now has the nickname `upstream`. We can now compare the data on our fork `origin` to that held by QMK. - -To update your fork's master, run the following, hitting the Enter key after each line: - -``` -git checkout master -git fetch upstream -git pull upstream master -git push origin master -``` - -This switches you to your `master` branch, retrieves the refs from the QMK repo, downloads the current QMK `master` branch to your computer, and then uploads it to your fork. - -### Making Changes - -To make changes, create a new branch by entering: - -``` -git checkout -b dev_branch -git push --set-upstream origin dev_branch -``` - -This creates a new branch named `dev_branch`, checks it out, and then saves the new branch to your fork. The `--set-upstream` argument tells git to use your fork and the `dev_branch` branch every time you use `git push` or `git pull` from this branch. It only needs to be used on the first push; after that, you can safely use `git push` or `git pull`, without the rest of the arguments. - -!> With `git push`, you can use `-u` in place of `--set-upstream` — `-u` is an alias for `--set-upstream`. - -You can name your branch nearly anything you want, though it is recommended to name it something related to the changes you are going to make. - -By default `git checkout -b` will base your new branch on the branch that is checked out. You can base your new branch on an existing branch that is not checked out by adding the name of the existing branch to the command: - -``` -git checkout -b dev_branch master -``` - -Now that you have a development branch, open your text editor and make whatever changes you need to make. It is recommended to make many small commits to your branch; that way, any change that causes issues can be more easily traced and undone if needed. To make your changes, edit and save any files that need to be updated, add them to Git's *staging area*, and then commit them to your branch: - -``` -git add path/to/updated_file -git commit -m "My commit message." -``` - -`git add` adds files that have been changed to Git's *staging area*, which is Git's "loading zone." This contains the changes that are going to be *committed* by `git commit`, which saves the changes to the repo. Use descriptive commit messages so you can know what was changed at a glance. - -!> If you've changed a lot of files, but all the files are part of the same change, you can use `git add .` to add all the changed files that are in your current directory, rather than having to add each file individually. - -### Publishing Your Changes - -The last step is to push your changes to your fork. To do this, enter `git push`. Git now publishes the current state of `dev_branch` to your fork. - - -## Resolving Merge Conflicts - -Sometimes when your work in a branch takes a long time to complete, changes that have been made by others conflict with changes you have made to your branch when you open a pull request. This is called a *merge conflict*, and is what happens when multiple people edit the same parts of the same files. - -### Rebasing Your Changes - -A *rebase* is Git's way of taking changes that were applied at one point, reversing them, and then applying the same changes to another point. In the case of a merge conflict, you can rebase your branch to grab the changes that were made between when you created your branch and the present time. - -To start, run the following: - -``` -git fetch upstream -git rev-list --left-right --count HEAD...upstream/master -``` - -The `git rev-list` command entered here returns the number of commits that differ between the current branch and QMK's master branch. We run `git fetch` first to make sure we have the refs that represent the current state of the upstream repo. The output of the `git rev-list` command entered returns two numbers: - -``` -$ git rev-list --left-right --count HEAD...upstream/master -7 35 -``` - -The first number represents the number of commits on the current branch since it was created, and the second number is the number of commits made to `upstream/master` since the current branch was created, and thus, the changes that are not recorded in the current branch. - -Now that the current states of both the current branch and the upstream repo are known, we can start a rebase operation: - -``` -git rebase upstream/master -``` - -This tells Git to undo the commits on the current branch, and then reapply them against QMK's master branch. - -``` -$ git rebase upstream/master -First, rewinding head to replay your work on top of it... -Applying: Commit #1 -Using index info to reconstruct a base tree... -M conflicting_file_1.txt -Falling back to patching base and 3-way merge... -Auto-merging conflicting_file_1.txt -CONFLICT (content): Merge conflict in conflicting_file_1.txt -error: Failed to merge in the changes. -hint: Use 'git am --show-current-patch' to see the failed patch -Patch failed at 0001 Commit #1 - -Resolve all conflicts manually, mark them as resolved with -"git add/rm <conflicted_files>", then run "git rebase --continue". -You can instead skip this commit: run "git rebase --skip". -To abort and get back to the state before "git rebase", run "git rebase --abort". -``` - -This tells us that we have a merge conflict, and gives the name of the file with the conflict. Open the conflicting file in your text editor, and somewhere in the file, you'll find something like this: - -``` -<<<<<<< HEAD -<p>For help with any issues, email us at support@webhost.us.</p> -======= -<p>Need help? Email support@webhost.us.</p> ->>>>>>> Commit #1 -``` - -The line `<<<<<<< HEAD` marks the beginning of a merge conflict, and the `>>>>>>> Commit #1` line marks the end, with the conflicting sections separated by `=======`. The part on the `HEAD` side is from the QMK master version of the file, and the part marked with the commit message is from the current branch and commit. - -Because Git tracks *changes to files* rather than the contents of the files directly, if Git can't find the text that was in the file previous to the commit that was made, it won't know how to edit the file. Re-editing the file will solve the conflict. Make your changes, and then save the file. - -``` -<p>Need help? Email support@webhost.us.</p> -``` - -Now run: - -``` -git add conflicting_file_1.txt -git rebase --continue -``` - -Git logs the changes to the conflicting file, and continues applying the commits from our branch until it reaches the end. diff --git a/docs/newbs_git_best_practices.md b/docs/newbs_git_best_practices.md new file mode 100644 index 000000000..c0cb3a294 --- /dev/null +++ b/docs/newbs_git_best_practices.md @@ -0,0 +1,16 @@ +# Best Git Practices for Working with QMK + +## Or, "How I Learned to Stop Worrying and Love Git." + +This section aims to instruct novices in the best ways to have a smooth experience in contributing to QMK. We will walk through the process of contributing to QMK, detailing some ways to make this task easier, and then later we'll break some things in order to teach you how to fix them. + +This section assumes a few things: + +1. You have a GitHub account, and have [forked the qmk_firmware repository](getting_started_github.md) to your account. +2. You've set up both [your build environment](newbs_getting_started.md#set-up-your-environment) and [QMK](newbs_getting_started.md#set-up-qmk). + +--- + +- Part 1: [Your Fork's Master: Update Often, Commit Never](newbs_git_using_your_master_branch.md) +- Part 2: [Resolving Merge Conflicts](newbs_git_resolving_merge_conflicts.md) +- Part 3: [Resynchronizing an Out-of-Sync Git Branch](newbs_git_resynchronize_a_branch.md) diff --git a/docs/newbs_git_resolving_merge_conflicts.md b/docs/newbs_git_resolving_merge_conflicts.md new file mode 100644 index 000000000..467c13abb --- /dev/null +++ b/docs/newbs_git_resolving_merge_conflicts.md @@ -0,0 +1,79 @@ +# Resolving Merge Conflicts + +Sometimes when your work in a branch takes a long time to complete, changes that have been made by others conflict with changes you have made to your branch when you open a pull request. This is called a *merge conflict*, and is what happens when multiple people edit the same parts of the same files. + +?> This document builds upon the concepts detailed in [Your Fork's Master: Update Often, Commit Never](newbs_git_using_your_master_branch.md). If you are not familiar with that document, please read it first, then return here. + +## Rebasing Your Changes + +A *rebase* is Git's way of taking changes that were applied at one point in the commit history, reversing them, and then applying the same changes at another point. In the case of a merge conflict, you can rebase your branch to grab the changes that were made between when you created your branch and the present time. + +To start, run the following: + +``` +git fetch upstream +git rev-list --left-right --count HEAD...upstream/master +``` + +The `git rev-list` command entered here returns the number of commits that differ between the current branch and QMK's master branch. We run `git fetch` first to make sure we have the refs that represent the current state of the upstream repo. The output of the `git rev-list` command entered returns two numbers: + +``` +$ git rev-list --left-right --count HEAD...upstream/master +7 35 +``` + +The first number represents the number of commits on the current branch since it was created, and the second number is the number of commits made to `upstream/master` since the current branch was created, and thus, the changes that are not recorded in the current branch. + +Now that the current states of both the current branch and the upstream repo are known, we can start a rebase operation: + +``` +git rebase upstream/master +``` + +This tells Git to undo the commits on the current branch, and then reapply them against QMK's master branch. + +``` +$ git rebase upstream/master +First, rewinding head to replay your work on top of it... +Applying: Commit #1 +Using index info to reconstruct a base tree... +M conflicting_file_1.txt +Falling back to patching base and 3-way merge... +Auto-merging conflicting_file_1.txt +CONFLICT (content): Merge conflict in conflicting_file_1.txt +error: Failed to merge in the changes. +hint: Use 'git am --show-current-patch' to see the failed patch +Patch failed at 0001 Commit #1 + +Resolve all conflicts manually, mark them as resolved with +"git add/rm <conflicted_files>", then run "git rebase --continue". +You can instead skip this commit: run "git rebase --skip". +To abort and get back to the state before "git rebase", run "git rebase --abort". +``` + +This tells us that we have a merge conflict, and gives the name of the file with the conflict. Open the conflicting file in your text editor, and somewhere in the file, you'll find something like this: + +``` +<<<<<<< HEAD +<p>For help with any issues, email us at support@webhost.us.</p> +======= +<p>Need help? Email support@webhost.us.</p> +>>>>>>> Commit #1 +``` + +The line `<<<<<<< HEAD` marks the beginning of a merge conflict, and the `>>>>>>> Commit #1` line marks the end, with the conflicting sections separated by `=======`. The part on the `HEAD` side is from the QMK master version of the file, and the part marked with the commit message is from the current branch and commit. + +Because Git tracks *changes to files* rather than the contents of the files directly, if Git can't find the text that was in the file previous to the commit that was made, it won't know how to edit the file. Re-editing the file will solve the conflict. Make your changes, and then save the file. + +``` +<p>Need help? Email support@webhost.us.</p> +``` + +Now run: + +``` +git add conflicting_file_1.txt +git rebase --continue +``` + +Git logs the changes to the conflicting file, and continues applying the commits from our branch until it reaches the end. diff --git a/docs/newbs_git_resynchronize_a_branch.md b/docs/newbs_git_resynchronize_a_branch.md new file mode 100644 index 000000000..2e6b26e09 --- /dev/null +++ b/docs/newbs_git_resynchronize_a_branch.md @@ -0,0 +1,71 @@ +# Resynchronizing an Out-of-Sync Git Branch + +Suppose you have committed to your `master` branch, and now need to update your QMK repository. You could `git pull` QMK's `master` branch into your own, but GitHub will tell you that your commit is a number of commits ahead of `qmk:master`, which can create issues if you want to make a pull request to QMK. + +?> This document builds upon the concepts detailed in [Your Fork's Master: Update Often, Commit Never](newbs_git_using_your_master_branch.md). If you are not familiar with that document, please read it first, then return here. + +## Backing Up the Changes on Your Own Master Branch (Optional) + +No one wants to lose work if it can be helped. If you want to save the changes you've already made to your `master` branch, the simplest way to do so is to simply create a duplicate of your "dirty" `master` branch: + +```sh +git branch old_master master +``` + +Now you have a branch named `old_master` that is a duplicate of your `master` branch. + +## Resynchronizing Your Branch + +Now it's time to resynchronize your `master` branch. For this step, you'll want to have QMK's repository configured as a remote in Git. To check your configured remotes, run `git remote -v`, which should return something similar to: + +```sh +QMKuser ~/qmk_firmware (master) +$ git remote -v +origin https://github.com/<your_username>/qmk_firmware.git (fetch) +origin https://github.com/<your_username>/qmk_firmware.git (push) +upstream https://github.com/qmk/qmk_firmware.git (fetch) +upstream https://github.com/qmk/qmk_firmware.git (push) +``` + +If you only see one fork referenced: + +```sh +QMKuser ~/qmk_firmware (master) +$ git remote -v +origin https://github.com/qmk/qmk_firmware.git (fetch) +origin https://github.com/qmk/qmk_firmware.git (push) +``` + +add a new remote with: + +```sh +git remote add upstream https://github.com/qmk/qmk_firmware.git +``` + +Then, redirect the `origin` remote to your own fork with: + +```sh +git remote set-url origin https://github.com/<your_username>/qmk_firmware.git +``` + +Now that you have both remotes configured, you need to update the references for the upstream repository, which is QMK's, by running: + +```sh +git fetch upstream +``` + +At this point, resynchronize your branch to QMK's by running: + +```sh +git reset --hard upstream/master +``` + +These steps will update the repository on your computer, but your GitHub fork will still be out of sync. To resynchronize your fork on GitHub, you need to push to your fork, instructing Git to override any remote changes that are not reflected in your local repository. To do this, run: + +```sh +git push --force-with-lease +``` + +!> **DO NOT** run `git push --force-with-lease` on a fork to which other users post commits. This will erase their commits. + +Now your GitHub fork, your local files, and QMK's repository are all the same. From here you can make further needed changes ([use a branch!](newbs_git_using_your_master_branch.md#making-changes)) and post them as normal. diff --git a/docs/newbs_git_using_your_master_branch.md b/docs/newbs_git_using_your_master_branch.md new file mode 100644 index 000000000..2032b83b2 --- /dev/null +++ b/docs/newbs_git_using_your_master_branch.md @@ -0,0 +1,74 @@ +# Your Fork's Master: Update Often, Commit Never + +It is highly recommended for QMK development, regardless of what is being done or where, to keep your `master` branch updated, but ***never*** commit to it. Instead, do all your changes in a development branch and issue pull requests from your branches when you're developing. + +To reduce the chances of merge conflicts — instances where two or more users have edited the same part of a file concurrently — keep your `master` branch relatively up-to-date, and start any new developments by creating a new branch. + +## Updating your master branch + +To keep your `master` branch updated, it is recommended to add the QMK Firmware repository ("repo") as a remote repository in git. To do this, open your Git command line interface and enter: + +``` +git remote add upstream https://github.com/qmk/qmk_firmware.git +``` + +?> The name `upstream` is arbitrary, but a common convention; you can give the QMK remote any name that suits you. Git's `remote` command uses the syntax `git remote add <name> <url>`, `<name>` being shorthand for the remote repo. This name can be used with many Git commands, including but not limited to `fetch`, `pull` and `push`, to specify the remote repo on which to act. + +To verify that the repository has been added, run `git remote -v`, which should return the following: + +``` +$ git remote -v +origin https://github.com/<your_username>/qmk_firmware.git (fetch) +origin https://github.com/<your_username>/qmk_firmware.git (push) +upstream https://github.com/qmk/qmk_firmware.git (fetch) +upstream https://github.com/qmk/qmk_firmware.git (push) +``` + +Now that this is done, you can check for updates to the repo by running `git fetch upstream`. This retrieves the branches and tags — collectively referred to as "refs" — from the QMK repo, which now has the nickname `upstream`. We can now compare the data on our fork `origin` to that held by QMK. + +To update your fork's master, run the following, hitting the Enter key after each line: + +``` +git checkout master +git fetch upstream +git pull upstream master +git push origin master +``` + +This switches you to your `master` branch, retrieves the refs from the QMK repo, downloads the current QMK `master` branch to your computer, and then uploads it to your fork. + +## Making Changes + +To make changes, create a new branch by entering: + +``` +git checkout -b dev_branch +git push --set-upstream origin dev_branch +``` + +This creates a new branch named `dev_branch`, checks it out, and then saves the new branch to your fork. The `--set-upstream` argument tells git to use your fork and the `dev_branch` branch every time you use `git push` or `git pull` from this branch. It only needs to be used on the first push; after that, you can safely use `git push` or `git pull`, without the rest of the arguments. + +?> With `git push`, you can use `-u` in place of `--set-upstream` — `-u` is an alias for `--set-upstream`. + +You can name your branch nearly anything you want, though it is recommended to name it something related to the changes you are going to make. + +By default `git checkout -b` will base your new branch on the branch that is currently checked out. You can base your new branch on an existing branch that is not checked out by adding the name of the existing branch to the command: + +``` +git checkout -b dev_branch master +``` + +Now that you have a development branch, open your text editor and make whatever changes you need to make. It is recommended to make many small commits to your branch; that way, any change that causes issues can be more easily traced and undone if needed. To make your changes, edit and save any files that need to be updated, add them to Git's *staging area*, and then commit them to your branch: + +``` +git add path/to/updated_file +git commit -m "My commit message." +``` + +`git add` adds files that have been changed to Git's *staging area*, which is Git's "loading zone." This contains the changes that are going to be *committed* by `git commit`, which saves the changes to the repo. Use descriptive commit messages so you can know what was changed at a glance. + +?> If you've changed multiple files, you can use `git add -- path/to/file1 path/to/file2 ...` to add all your desired files. + +## Publishing Your Changes + +The last step is to push your changes to your fork. To do this, enter `git push`. Git will then publish the current state of `dev_branch` to your fork. diff --git a/docs/proton_c_conversion.md b/docs/proton_c_conversion.md index 8014a35e0..dc0a3f484 100644 --- a/docs/proton_c_conversion.md +++ b/docs/proton_c_conversion.md @@ -29,3 +29,5 @@ These are defaults based on what has been implemented for ARM boards. | [Audio](feature_audio.md) | Enabled | | [RGB Lighting](feature_rgblight.md) | Disabled | | [Backlight](feature_backlight.md) | Forces [task driven PWM](feature_backlight.md#software-pwm-driver) until ARM can provide automatic configuration | +| USB Host (e.g. USB-USB converter) | Not supported (USB host code is AVR specific and is not currently supported on ARM) | +| [Split keyboards](feature_split_keyboard.md) | Not supported yet | diff --git a/docs/pt-br/README.md b/docs/pt-br/README.md new file mode 100644 index 000000000..7cff6ce62 --- /dev/null +++ b/docs/pt-br/README.md @@ -0,0 +1,31 @@ +# Quantum Mechanical Keyboard Firmware + +[](https://github.com/qmk/qmk_firmware/tags) +[](https://travis-ci.org/qmk/qmk_firmware) +[](https://discord.gg/Uq7gcHh) +[](https://docs.qmk.fm) +[](https://github.com/qmk/qmk_firmware/pulse/monthly) +[](https://github.com/qmk/qmk_firmware/) + +## O que é o firmware QMK? +QMK (*Quantum Mechanical Keyboard*) é uma comunidade de código aberto que mantém o QMK Firmware, o QMK Toolbox, qmk.fm e suas documentações. O QMK Firmware é um software embarcado ("firmware") de teclado baseado no [tmk\_keyboard](http://github.com/tmk/tmk_keyboard) com alguns recursos úteis para os controladores Atmel AVR e, mais especificamente, na [linha de produtos OLKB](http://olkb.com), o teclado [ErgoDox EZ](http://www.ergodox-ez.com) e a [linha de produtos Clueboard](http://clueboard.co/). Também foi portado para chips ARM usando o ChibiOS. Você pode usá-lo no seu próprio teclado com fio ou personalizado. + +## Como obter e usar o QMK + +Se você planeja contribuir com um _keymap_ ("mapa de teclas"), teclado ou recursos para o QMK, o jeito mais fácil é [percorrer o repositório através do Github](https://github.com/qmk/qmk_firmware#fork-destination-box) e clonar seu repositório localmente para fazer suas alterações, dê um _push_ nelas e abra uma [_Pull request_](https://github.com/qmk/qmk_firmware/pulls) no seu fork. + +Caso contrário, você pode cloná-lo diretamente com `git clone https://github.com/qmk/qmk_firmware`. Não faça o download dos arquivos zip ou tar; é necessário um repositório git para baixar os submódulos para compilar. + +## Como compilar + +Antes de compilar, você precisará [instalar um ambiente específico](getting_started_build_tools.md) para o desenvolvimento em plataforma AVR e/ou ARM; vez que isto for feito, você usará o comando `make` para criar um teclado e um mapa de teclas com a seguinte notação: + + make planck/rev4:default + +Isso compilaria a revisão `rev4` do teclado ` planck` com o mapa de teclas `default`. Nem todos os teclados têm revisões (também chamadas de _subprojects_ ou _folders_); nesse caso, a revisão pode ser omitida: + + make preonic:default + +## Como personalizar + +O QMK tem muitos [recursos](features.md) para explorar e uma boa quantidade de [documentação de referência](http://docs.qmk.fm) para explorar. A maioria dos recursos é aproveitada modificando seu [keymap](keymap.md) e alterando os [keycodes](keycodes.md). diff --git a/docs/pt-br/_summary.md b/docs/pt-br/_summary.md new file mode 100644 index 000000000..27efd73ab --- /dev/null +++ b/docs/pt-br/_summary.md @@ -0,0 +1,121 @@ +* [Complete Newbs Guide](pt-br/newbs.md) + * [Getting Started](pt-br/newbs_getting_started.md) + * [Building Your First Firmware](pt-br/newbs_building_firmware.md) + * [Flashing Firmware](pt-br/newbs_flashing.md) + * [Testing and Debugging](pt-br/newbs_testing_debugging.md) + * [Git Best Practices](pt-br/newbs_best_practices.md) + * [Learning Resources](pt-br/newbs_learn_more_resources.md) + +* [QMK Basics](pt-br/README.md) + * [QMK Introduction](pt-br/getting_started_introduction.md) + * [QMK CLI](pt-br/cli.md) + * [QMK CLI Config](pt-br/cli_configuration.md) + * [Contributing to QMK](pt-br/contributing.md) + * [How to Use Github](pt-br/getting_started_github.md) + * [Getting Help](pt-br/getting_started_getting_help.md) + +* [Breaking Changes](pt-br/breaking_changes.md) + * [2019 Aug 30](pt-br/ChangeLog/20190830.md) + +* [FAQ](faq.md) + * [General FAQ](pt-br/faq_general.md) + * [Build/Compile QMK](pt-br/faq_build.md) + * [Debugging/Troubleshooting QMK](pt-br/faq_debug.md) + * [Keymap](pt-br/faq_keymap.md) + * [Driver Installation with Zadig](pt-br/driver_installation_zadig.md) + +* Detailed Guides + * [Install Build Tools](pt-br/getting_started_build_tools.md) + * [Vagrant Guide](pt-br/getting_started_vagrant.md) + * [Build/Compile Instructions](pt-br/getting_started_make_guide.md) + * [Flashing Firmware](pt-br/flashing.md) + * [Customizing Functionality](pt-br/custom_quantum_functions.md) + * [Keymap Overview](pt-br/keymap.md) + +* [Hardware](hardware.md) + * [AVR Processors](pt-br/hardware_avr.md) + * [Drivers](pt-br/hardware_drivers.md) + +* Reference + * [Keyboard Guidelines](pt-br/hardware_keyboard_guidelines.md) + * [Config Options](pt-br/config_options.md) + * [Keycodes](pt-br/keycodes.md) + * [Coding Conventions - C](pt-br/coding_conventions_c.md) + * [Coding Conventions - Python](pt-br/coding_conventions_python.md) + * [Documentation Best Practices](pt-br/documentation_best_practices.md) + * [Documentation Templates](pt-br/documentation_templates.md) + * [Glossary](pt-br/reference_glossary.md) + * [Unit Testing](pt-br/unit_testing.md) + * [Useful Functions](pt-br/ref_functions.md) + * [Configurator Support](pt-br/reference_configurator_support.md) + * [info.json Format](pt-br/reference_info_json.md) + * [Python CLI Development](pt-br/cli_development.md) + +* [Features](pt-br/features.md) + * [Basic Keycodes](pt-br/keycodes_basic.md) + * [US ANSI Shifted Keys](pt-br/keycodes_us_ansi_shifted.md) + * [Quantum Keycodes](pt-br/quantum_keycodes.md) + * [Advanced Keycodes](pt-br/feature_advanced_keycodes.md) + * [Audio](pt-br/feature_audio.md) + * [Auto Shift](pt-br/feature_auto_shift.md) + * [Backlight](pt-br/feature_backlight.md) + * [Bluetooth](pt-br/feature_bluetooth.md) + * [Bootmagic](pt-br/feature_bootmagic.md) + * [Combos](pt-br/feature_combo.md) + * [Command](pt-br/feature_command.md) + * [Debounce API](pt-br/feature_debounce_type.md) + * [DIP Switch](pt-br/feature_dip_switch.md) + * [Dynamic Macros](pt-br/feature_dynamic_macros.md) + * [Encoders](pt-br/feature_encoders.md) + * [Grave Escape](pt-br/feature_grave_esc.md) + * [Haptic Feedback](pt-br/feature_haptic_feedback.md) + * [HD44780 LCD Controller](pt-br/feature_hd44780.md) + * [Key Lock](pt-br/feature_key_lock.md) + * [Layouts](pt-br/feature_layouts.md) + * [Leader Key](pt-br/feature_leader_key.md) + * [LED Matrix](pt-br/feature_led_matrix.md) + * [Macros](pt-br/feature_macros.md) + * [Mouse Keys](pt-br/feature_mouse_keys.md) + * [OLED Driver](pt-br/feature_oled_driver.md) + * [One Shot Keys](pt-br/feature_advanced_keycodes.md#one-shot-keys) + * [Pointing Device](pt-br/feature_pointing_device.md) + * [PS/2 Mouse](pt-br/feature_ps2_mouse.md) + * [RGB Lighting](pt-br/feature_rgblight.md) + * [RGB Matrix](pt-br/feature_rgb_matrix.md) + * [Space Cadet](pt-br/feature_space_cadet.md) + * [Split Keyboard](pt-br/feature_split_keyboard.md) + * [Stenography](pt-br/feature_stenography.md) + * [Swap Hands](pt-br/feature_swap_hands.md) + * [Tap Dance](pt-br/feature_tap_dance.md) + * [Terminal](pt-br/feature_terminal.md) + * [Thermal Printer](pt-br/feature_thermal_printer.md) + * [Unicode](pt-br/feature_unicode.md) + * [Userspace](pt-br/feature_userspace.md) + * [Velocikey](pt-br/feature_velocikey.md) + +* For Makers and Modders + * [Hand Wiring Guide](pt-br/hand_wire.md) + * [ISP Flashing Guide](pt-br/isp_flashing_guide.md) + * [ARM Debugging Guide](pt-br/arm_debugging.md) + * [I2C Driver](pt-br/i2c_driver.md) + * [GPIO Controls](pt-br/internals_gpio_control.md) + * [Proton C Conversion](pt-br/proton_c_conversion.md) + +* For a Deeper Understanding + * [How Keyboards Work](pt-br/how_keyboards_work.md) + * [Understanding QMK](pt-br/understanding_qmk.md) + +* Other Topics + * [Using Eclipse with QMK](pt-br/other_eclipse.md) + * [Using VSCode with QMK](pt-br/other_vscode.md) + * [Support](pt-br/support.md) + * [How to add translations](pt-br/translating.md) + +* QMK Internals (In Progress) + * [Defines](pt-br/internals_defines.md) + * [Input Callback Reg](pt-br/internals_input_callback_reg.md) + * [Midi Device](pt-br/internals_midi_device.md) + * [Midi Device Setup Process](pt-br/internals_midi_device_setup_process.md) + * [Midi Util](pt-br/internals_midi_util.md) + * [Send Functions](pt-br/internals_send_functions.md) + * [Sysex Tools](pt-br/internals_sysex_tools.md) diff --git a/docs/ru-ru/_summary.md b/docs/ru-ru/_summary.md new file mode 100644 index 000000000..3269ac86d --- /dev/null +++ b/docs/ru-ru/_summary.md @@ -0,0 +1,123 @@ +* [Complete Newbs Guide](ru-ru/newbs.md) + * [Getting Started](ru-ru/newbs_getting_started.md) + * [Building Your First Firmware](ru-ru/newbs_building_firmware.md) + * [Flashing Firmware](ru-ru/newbs_flashing.md) + * [Testing and Debugging](ru-ru/newbs_testing_debugging.md) + * [Git Best Practices](ru-ru/newbs_best_practices.md) + * [Learning Resources](ru-ru/newbs_learn_more_resources.md) + +* [QMK Basics](ru-ru/README.md) + * [QMK Introduction](ru-ru/getting_started_introduction.md) + * [QMK CLI](ru-ru/cli.md) + * [QMK CLI Config](ru-ru/cli_configuration.md) + * [Contributing to QMK](ru-ru/contributing.md) + * [How to Use Github](ru-ru/getting_started_github.md) + * [Getting Help](ru-ru/getting_started_getting_help.md) + +* [Breaking Changes](ru-ru/breaking_changes.md) + * [2019 Aug 30](ru-ru/ChangeLog/20190830.md) + +* [FAQ](ru-ru/faq.md) + * [General FAQ](ru-ru/faq_general.md) + * [Build/Compile QMK](ru-ru/faq_build.md) + * [Debugging/Troubleshooting QMK](ru-ru/faq_debug.md) + * [Keymap](ru-ru/faq_keymap.md) + * [Driver Installation with Zadig](ru-ru/driver_installation_zadig.md) + +* Detailed Guides + * [Install Build Tools](ru-ru/getting_started_build_tools.md) + * [Vagrant Guide](ru-ru/getting_started_vagrant.md) + * [Build/Compile Instructions](ru-ru/getting_started_make_guide.md) + * [Flashing Firmware](ru-ru/flashing.md) + * [Customizing Functionality](ru-ru/custom_quantum_functions.md) + * [Keymap Overview](ru-ru/keymap.md) + +* [Hardware](ru-ru/hardware.md) + * [Compatible Microcontrollers](ru-ru/compatible_microcontrollers.md) + * [AVR Processors](ru-ru/hardware_avr.md) + * [Drivers](ru-ru/hardware_drivers.md) + +* Reference + * [Keyboard Guidelines](ru-ru/hardware_keyboard_guidelines.md) + * [Config Options](ru-ru/config_options.md) + * [Keycodes](ru-ru/keycodes.md) + * [Coding Conventions - C](ru-ru/coding_conventions_c.md) + * [Coding Conventions - Python](ru-ru/coding_conventions_python.md) + * [Documentation Best Practices](ru-ru/documentation_best_practices.md) + * [Documentation Templates](ru-ru/documentation_templates.md) + * [Glossary](ru-ru/reference_glossary.md) + * [Unit Testing](ru-ru/unit_testing.md) + * [Useful Functions](ru-ru/ref_functions.md) + * [Configurator Support](ru-ru/reference_configurator_support.md) + * [info.json Format](ru-ru/reference_info_json.md) + * [Python CLI Development](ru-ru/cli_development.md) + +* [Features](ru-ru/features.md) + * [Basic Keycodes](ru-ru/keycodes_basic.md) + * [US ANSI Shifted Keys](ru-ru/keycodes_us_ansi_shifted.md) + * [Quantum Keycodes](ru-ru/quantum_keycodes.md) + * [Advanced Keycodes](ru-ru/feature_advanced_keycodes.md) + * [Audio](ru-ru/feature_audio.md) + * [Auto Shift](ru-ru/feature_auto_shift.md) + * [Backlight](ru-ru/feature_backlight.md) + * [Bluetooth](ru-ru/feature_bluetooth.md) + * [Bootmagic](ru-ru/feature_bootmagic.md) + * [Combos](ru-ru/feature_combo.md) + * [Command](ru-ru/feature_command.md) + * [Debounce API](ru-ru/feature_debounce_type.md) + * [DIP Switch](ru-ru/feature_dip_switch.md) + * [Dynamic Macros](ru-ru/feature_dynamic_macros.md) + * [Encoders](ru-ru/feature_encoders.md) + * [Grave Escape](ru-ru/feature_grave_esc.md) + * [Haptic Feedback](ru-ru/feature_haptic_feedback.md) + * [HD44780 LCD Controller](ru-ru/feature_hd44780.md) + * [Key Lock](ru-ru/feature_key_lock.md) + * [Layouts](ru-ru/feature_layouts.md) + * [Leader Key](ru-ru/feature_leader_key.md) + * [LED Matrix](ru-ru/feature_led_matrix.md) + * [Macros](ru-ru/feature_macros.md) + * [Mouse Keys](ru-ru/feature_mouse_keys.md) + * [OLED Driver](ru-ru/feature_oled_driver.md) + * [One Shot Keys](ru-ru/feature_advanced_keycodes.md#one-shot-keys) + * [Pointing Device](ru-ru/feature_pointing_device.md) + * [PS/2 Mouse](ru-ru/feature_ps2_mouse.md) + * [RGB Lighting](ru-ru/feature_rgblight.md) + * [RGB Matrix](ru-ru/feature_rgb_matrix.md) + * [Space Cadet](ru-ru/feature_space_cadet.md) + * [Split Keyboard](ru-ru/feature_split_keyboard.md) + * [Stenography](ru-ru/feature_stenography.md) + * [Swap Hands](ru-ru/feature_swap_hands.md) + * [Tap Dance](ru-ru/feature_tap_dance.md) + * [Terminal](ru-ru/feature_terminal.md) + * [Thermal Printer](ru-ru/feature_thermal_printer.md) + * [Unicode](ru-ru/feature_unicode.md) + * [Userspace](ru-ru/feature_userspace.md) + * [Velocikey](ru-ru/feature_velocikey.md) + +* For Makers and Modders + * [Hand Wiring Guide](ru-ru/hand_wire.md) + * [ISP Flashing Guide](ru-ru/isp_flashing_guide.md) + * [ARM Debugging Guide](ru-ru/arm_debugging.md) + * [I2C Driver](ru-ru/i2c_driver.md) + * [WS2812 Driver](ru-ru/ws2812_driver.md) + * [GPIO Controls](ru-ru/internals_gpio_control.md) + * [Proton C Conversion](ru-ru/proton_c_conversion.md) + +* For a Deeper Understanding + * [How Keyboards Work](ru-ru/how_keyboards_work.md) + * [Understanding QMK](ru-ru/understanding_qmk.md) + +* Other Topics + * [Using Eclipse with QMK](ru-ru/other_eclipse.md) + * [Using VSCode with QMK](ru-ru/other_vscode.md) + * [Support](ru-ru/support.md) + * [Translating the QMK Docs](ru-ru/translating.md) + +* QMK Internals (In Progress) + * [Defines](ru-ru/internals_defines.md) + * [Input Callback Reg](ru-ru/internals_input_callback_reg.md) + * [Midi Device](ru-ru/internals_midi_device.md) + * [Midi Device Setup Process](ru-ru/internals_midi_device_setup_process.md) + * [Midi Util](ru-ru/internals_midi_util.md) + * [Send Functions](ru-ru/internals_send_functions.md) + * [Sysex Tools](ru-ru/internals_sysex_tools.md) diff --git a/docs/ru-ru/becoming_a_qmk_collaborator.md b/docs/ru-ru/becoming_a_qmk_collaborator.md new file mode 100644 index 000000000..653f01ac8 --- /dev/null +++ b/docs/ru-ru/becoming_a_qmk_collaborator.md @@ -0,0 +1,9 @@ +# Стать соавтором QMK + +Соавтор QMK - это производитель или разработчик клавиатуры, который заинтересован в том, чтобы помочь QMK вырасти. Для этого он полностью поддерживает свои клавиатуры, поощряет пользователей и клиентов создавать новый функционал, идеи и раскладки клавиатур. Мы всегда стремимся добавлять больше клавиатур и соавторов, но нам важно, чтобы они соответствовали следующим требованиям: + +* **Иметь печатную плату на продажу.** К сожалению, у собранных вручную клавиатур слишком много вариаций и сложностей. +* **Поддерживать вашу клавиатуру в QMK.** Это может потребовать просто начальной настройки, чтобы ваша клавиатура заработала. Но поддержка также может заключаться в адаптации изменений ядра QMK, которые способны сломать или сделать избыточным любой пользовательский код. +* **Одобрять и производить слияние пулреквестов для вашей клавиатуры.** Мы призываем пользователей делиться своими раскладками клавиатур, чтобы другие могли их видеть и опираться на них при создании своих собственных. + +Если вы чувствуете, что удовлетворяете этим требованиям, напишите нам письмо по адресу hello@qmk.fm с кратким описанием и ссылками на вашу клавиатуру! diff --git a/docs/ru-ru/getting_started_build_tools.md b/docs/ru-ru/getting_started_build_tools.md index f59068533..facdf3563 100644 --- a/docs/ru-ru/getting_started_build_tools.md +++ b/docs/ru-ru/getting_started_build_tools.md @@ -119,21 +119,6 @@ git * WSL Git **не** совместим с Windows Git, поэтому используйте Windows Git Bash или Windows Git GUI для всех операций с Git. * Вы можете изменять файлы как внутри WSL, так и просто через Windows. Но обратите внимание, что если вы изменяете makefiles или сценарии командной строки, вы должны убедиться, что используете текстовый редактор, который сохраняет файлы с переводом строки в стиле Unix (Unix line endings). В противном случае компиляция может не работать. -## Windows (Vista и новее) (устарело) - -Это устаревшие инструкции для Windows Vista и более новых версий. Мы рекомендуем использовать [MSYS2, как сказано выше](#windows-с-msys2-рекомендуется). - -1. Если вы когда-то устанавливали WinAVR, удалите его. -2. Установите [MHV AVR Tools](https://infernoembedded.com/sites/default/files/project/MHV_AVR_Tools_20131101.exe). Отключите smatch, но **оставьте галочку напротив опции добавления инструмента в PATH**. -3. Если вы собираетесь прошивать клавиатуры на базе Infinity, вам нужно установить dfu-util. Обратитесь к инструкциям от [Input Club](https://github.com/kiibohd/controller/wiki/Loading-DFU-Firmware). -4. Установите [MinGW](https://sourceforge.net/projects/mingw/files/Installer/mingw-get-setup.exe/download). Во время установки отключите опцию установки графического пользовательского интерфейса. **НЕ ИЗМЕНЯЙТЕ директорию для установки по умолчанию.** Скрипты зависят от расположения по умолчанию. -5. Выполните клонирование данного репозитория. [Эта ссылка скачает его в виде zip-файла, который вам нужно будет разархивировать.](https://github.com/qmk/qmk_firmware/archive/master.zip) Откройте извлеченную папку в проводнике Windows. -6. Перейдите в папку `\util`. -7. Запустите двойным щелчком пакетный файл сценария `1-setup-path-win`. Вам нужно будет согласиться с уведомлением контроля учетных записей пользователей (User Account Control, UAC). Нажмите пробел, чтобы закрыть появившееся сообщение об успешном выполнении операции в командной строке. -8. Кликните правой кнопкой по пакетному файлу сценария `2-setup-environment-win`, выберите "Запуск от имени администратора" и согласитесь с уведомлением UAC. Это может занять пару минут, и вам потребуется подтвердить установку драйвера. Как только сценарий завершит свою работу, ваше окружение будет готово! - -Если у вас возникли проблемы и вам нужна помощь, будет полезно сгенерировать файл *Win_Check_Output.txt*, запустив `Win_Check.bat` в папке `\util`. - ## Docker Если это немного сложновато для вас, Docker может стать готовым решением, которое вы ищите. После установки [Docker CE](https://docs.docker.com/install/#supported-platforms) выполните следующую команду из директории `qmk_firmware`, чтобы собрать клавиатуру/раскладку: diff --git a/docs/ru-ru/getting_started_getting_help.md b/docs/ru-ru/getting_started_getting_help.md new file mode 100644 index 000000000..75be44310 --- /dev/null +++ b/docs/ru-ru/getting_started_getting_help.md @@ -0,0 +1,15 @@ +# Получение помощи + +Существует много ресурсов для получения помощи по работе с QMK. + +## Чат в реальном времени + +Вы можете найти разработчиков и пользователей QMK на нашем главном [сервере Discord](https://discord.gg/Uq7gcHh). На сервере есть специальные каналы для разговоров о прошивке, Toolbox, оборудовании и конфигураторе. + +## OLKB Сабреддит + +Официальный форум QMK [/r/olkb](https://reddit.com/r/olkb) на [reddit.com](https://reddit.com). + +## GitHub ишью + +Вы можете открыть [ишью на GitHub](https://github.com/qmk/qmk_firmware/issues). Это особенно удобно, когда ваша проблема потребует длительного обсуждения или отладки. diff --git a/docs/ru-ru/getting_started_github.md b/docs/ru-ru/getting_started_github.md new file mode 100644 index 000000000..8a0fd07a2 --- /dev/null +++ b/docs/ru-ru/getting_started_github.md @@ -0,0 +1,58 @@ +# Как использовать GitHub с QMK + +GitHub может показаться несколько сложным для тех, кто никогда с ним не работал. В данном руководстве будет разобран каждый шаг создания форка, клонирования и отправки пулреквеста в QMK. + +?> В этом руководстве предполагается, что вы в какой-то степени знакомы с работой в командной строке, и в вашей системе установлен git. + +Откройте [страницу QMK на GitHub] (https://github.com/qmk/qmk_firmware), и в правом верхнем углу вы увидите кнопку с надписью "Fork": + + + +Если вы состоите в какой-либо организации, вам нужно выбрать учетную запись, к которой будет привязан форк. В большинстве случаев это будет личной аккаунт. Как только ваш форк будет завершен (иногда это занимает немного времени), нажмите кнопку "Clone or Download": + + +И обязательно выберите "HTTPS", затем выделите ссылку и скопируйте ее: + + + +Теперь введите `git clone` в командную строку, а затем вставьте ссылку: + +``` +user@computer:~$ git clone https://github.com/whoeveryouare/qmk_firmware.git +Cloning into 'qmk_firmware'... +remote: Counting objects: 46625, done. +remote: Compressing objects: 100% (2/2), done. +remote: Total 46625 (delta 0), reused 0 (delta 0), pack-reused 46623 +Receiving objects: 100% (46625/46625), 84.47 MiB | 3.14 MiB/s, done. +Resolving deltas: 100% (29362/29362), done. +Checking out files: 100% (2799/2799), done. +``` + +Теперь у вас есть форк QMK на вашем локальном компьютере, и вы можете добавить свою раскладку, скомпилировать ее и прошить ей свою клавиатуру. Как только вы будете довольны своими изменениями, есть возможность добавить, зафиксировать их и сделать коммит в свой форк следующим образом: + +``` +user@computer:~$ git add . +user@computer:~$ git commit -m "adding my keymap" +[master cccb1608] adding my keymap + 1 file changed, 1 insertion(+) + create mode 100644 keyboards/planck/keymaps/mine/keymap.c +user@computer:~$ git push +Counting objects: 1, done. +Delta compression using up to 4 threads. +Compressing objects: 100% (1/1), done. +Writing objects: 100% (1/1), 1.64 KiB | 0 bytes/s, done. +Total 1 (delta 1), reused 0 (delta 0) +remote: Resolving deltas: 100% (1/1), completed with 1 local objects. +To https://github.com/whoeveryouare/qmk_firmware.git + + 20043e64...7da94ac5 master -> master +``` + +Ваши изменения теперь существуют в вашем форке на GitHub - если вернуться туда (`https://github.com/<whoeveryouare>/qmk_firmware`), вы сможете создать "New Pull Request" нажатием на кнопку: + + + +Здесь вы сможете увидеть, какие именно изменения были внесены, - если все выглядит хорошо, вы можете завершить его, нажав "Create Pull Request": + + + +После отправки мы можем расспросить вас о ваших изменениях, попросить внести корректировки и в конечном итоге принять их! Спасибо за ваш вклад в QMK :) diff --git a/docs/ru-ru/getting_started_introduction.md b/docs/ru-ru/getting_started_introduction.md new file mode 100644 index 000000000..142fe4254 --- /dev/null +++ b/docs/ru-ru/getting_started_introduction.md @@ -0,0 +1,58 @@ +# Введение + +Эта страница пытается объяснить основную информацию, которую вы должны знать, чтобы работать с проектом QMK. Предполагается, что вы знакомы с навигацией в оболочке Unix, но не предполагается, что вы знакомы с C или с компиляцией с использованием make. + +## Базовая структура QMK + +QMK - это форк [Джуна Вако (Jun Wako)](https://github.com/tmk) проекта [tmk_keyboard](https://github.com/tmk/tmk_keyboard). Оригинальный код TMK с изменениями можно найти в папке `tmk`. Дополнения QMK к проекту можно найти в папке `quantum`. Проекты клавиатур можно найти в папках `handwired` и `keyboard`. + +### Структура пространства пользователя + +Внутри папки `users` находится каталог для каждого пользователя. Это место для пользователей, куда они могут поместить код, чтобы использовать его с разными клавиатурами. Для получения дополнительной информации обратитесь к документации по [функциям пользовательского пространства](ru-ru/feature_userspace.md). + +### Структура проекта клавиатуры + +Внутри папки `keyboards` есть подпапки `handwired` и есть подкаталоги поставщиков и производителей, для примера, `clueboard` - это каталог для каждого проекта клавиатуры, например, `qmk_firmware/keyboards/clueboard/2x1800`. В нем вы найдете следующую структуру: +* `keymaps/`: Различные раскладки клавиш, которые можно собрать. +* `rules.mk`: Файл, который устанавливает параметры по умолчанию для команды "make". Не редактируйте этот файл напрямую, вместо этого используйте `rules.mk`, относящийся к конкретной раскладке. +* `config.h`: Файл, который устанавливает параметры времени компиляции по умолчанию. Не редактируйте этот файл напрямую, вместо этого используйте `config.h`, относящийся к конкретной раскладке. +* `info.json`: Файл настройки раскладки для QMK Configurator. Посмотрите [Поддержку конфигуратора](ru-ru/reference_configurator_support.md) для дополнительной информации. +* `readme.md`: Краткий обзор клавиатуры. +* `<keyboardName>.h`: В этом файле определяется раскладка клавиатуры по матрице переключателей клавиатуры. +* `<keyboardName>.c`: В этом файле вы можете найти пользовательский код для клавиатуры. + +Для получения дополнительной информации о структуре проекта обратитесь к [Руководству QMK по клавиатуре](ru-ru/hardware_keyboard_guidelines.md). + +### Структура раскладки клавиатуры + +В каждой папке раскладки клавиатуры могут быть найдены следующие файлы. Обязательным является только файл `keymap.c`, и если остальные файлы не найдены, то будут выбраны параметры по умолчанию. + +* `config.h`: настройки вашей раскладки клавиатуры. +* `keymap.c`: весь код вашей раскладки клавиатуры (обязателен). +* `rules.mk`: активированные функции QMK. +* `readme.md`: описание вашей раскладки клавиш, как ее могут использовать другие, и объяснения функций. Пожалуйста, загрузите изображения на сервис, такой как imgur. + +# Файл `config.h` + +Существует 3 возможных местоположения `config.h`: + +* клавиатура (`/keyboards/<keyboard>/config.h`) +* пространство пользователя (`/users/<user>/config.h`) +* раскладка клавиш (`/keyboards/<keyboard>/keymaps/<keymap>/config.h`) + +Система сборки автоматически загружает файлы конфигурации в указанном выше порядке. Если вы хотите переопределить любую настройку, заданную предыдущим `config.h`, вам сначала нужно будет включить некоторый шаблонный код для настроек, которые вы хотите изменить. + +``` +#pragma once +``` + +Затем, чтобы переопределить настройку из предыдущего файла `config.h`, вы должны сделать `#undef` и `#define` для неё снова. + +Код и настройка шаблона вместе выглядят так: +``` +#pragma once + +// Переопределения производятся здесь! +#undef MY_SETTING +#define MY_SETTING 4 +``` diff --git a/docs/translating.md b/docs/translating.md index 6eb268763..436581759 100644 --- a/docs/translating.md +++ b/docs/translating.md @@ -1,29 +1,55 @@ -# How to translate the QMK docs into different languages +# Translating the QMK Docs All files in the root folder (`docs/`) should be in English - all other languages should be in subfolders with the ISO 639-1 language codes, followed by `-` and the country code where relevant. [A list of common ones can be found here](https://www.andiamo.co.uk/resources/iso-language-codes/). If this folder doesn't exist, you may create it. Each of the translated files should have the same name as the English version, so things can fall back successfully. A `_summary.md` file should exist in this folder with a list of links to each file, with a translated name, and link preceded by the language folder: - * [QMK简介](zh-cn/getting_started_introduction.md) +```markdown + * [QMK简介](zh-cn/getting_started_introduction.md) +``` + +All links to other docs pages must also be prefixed with the language folder. If the link is to a specific part of the page (ie. a certain heading), you must use the English ID for the heading, like so: + +```markdown +[建立你的环境](zh-cn/newbs-getting-started.md#set-up-your-environment) + +## 建立你的环境 :id=set-up-your-environment +``` Once you've finished translating a new language, you'll also need to modify the following files: * [`docs/_langs.md`](https://github.com/qmk/qmk_firmware/blob/master/docs/_langs.md) - Each line should contain a country flag in the format `:us:` followed by the name represented in its own language: - - - [:cn: 中文](/zh-cn/) + Each line should contain a country flag as a [GitHub emoji shortcode](https://github.com/ikatyang/emoji-cheat-sheet/blob/master/README.md#country-flag) followed by the name represented in its own language: + + ```markdown + - [:cn: 中文](/zh-cn/) + ``` * [`docs/index.html`](https://github.com/qmk/qmk_firmware/blob/master/docs/index.html) - Both `placeholder` and `noData` objects should have a dictionary entry for the language folder in a string: - - '/zh-cn/': '没有结果!', + Both `placeholder` and `noData` objects should have a dictionary entry for the language folder in a string: + + ```js + '/zh-cn/': '没有结果!', + ``` + + The `nameLink` object, for setting the "QMK Firmware" heading link in the sidebar, must also be added to: + + ```js + '/zh-cn/': '/#/zh-cn/', + ``` -## Previewing the translations + And make sure to add the language folder in the `fallbackLanguages` list, so it will properly fall back to English instead of 404ing: -Before opening a pull request, you can preview your additions if you have Python 3 installed by running this command in the `docs/` folder: + ```js + fallbackLanguages: [ + // ... + 'zh-cn', + // ... + ], + ``` - python -m http.server 9000 +## Previewing the Translations -and navigating to http://localhost:9000/ - you should be able to select your new language from the "Translations" menu at the top-right. +See [Previewing the Documentation](contributing.md#previewing-the-documentation) for how to set up a local instance of the docs - you should be able to select your new language from the "Translations" menu at the top-right. Once you're happy with your work, feel free to open a pull request! diff --git a/docs/ws2812_driver.md b/docs/ws2812_driver.md index 6fa5d324c..67481c458 100644 --- a/docs/ws2812_driver.md +++ b/docs/ws2812_driver.md @@ -1,13 +1,22 @@ # WS2812 Driver This driver powers the [RGB Lighting](feature_rgblight.md) and [RGB Matrix](feature_rgb_matrix.md) features. -Currently QMK supports the following addressable LEDs on AVR microcontrollers (however, the white LED in RGBW variants is not supported): +Currently QMK supports the following addressable LEDs (however, the white LED in RGBW variants is not supported): WS2811, WS2812, WS2812B, WS2812C, etc. SK6812, SK6812MINI, SK6805 These LEDs are called "addressable" because instead of using a wire per color, each LED contains a small microchip that understands a special protocol sent over a single wire. The chip passes on the remaining data to the next LED, allowing them to be chained together. In this way, you can easily control the color of the individual LEDs. +## Supported Driver Types + +| | AVR | ARM | +|----------|--------------------|--------------------| +| bit bang | :heavy_check_mark: | :heavy_check_mark: | +| I2C | :heavy_check_mark: | | +| SPI | | Soon™ | +| PWM | | Soon™ | + ## Driver configuration ### Bitbang @@ -17,7 +26,7 @@ Default driver, the absence of configuration assumes this driver. To configure i WS2812_DRIVER = bitbang ``` -!> ARM does not yet support WS2182. Progress is being made, but we are not quite there, yet. +!> This driver is not hardware accelerated and may not be performant on heavily loaded systems. ### I2C Targeting boards where WS2812 support is offloaded to a 2nd MCU. Currently the driver is limited to AVR given the known consumers are ps2avrGB/BMC. To configure it, add this to your rules.mk: diff --git a/docs/zh-cn/README.md b/docs/zh-cn/README.md index 9eb4ea777..bb7e0130f 100644 --- a/docs/zh-cn/README.md +++ b/docs/zh-cn/README.md @@ -19,7 +19,7 @@ QMK (*Quantum Mechanical Keyboard*) 是一个社区维护的开源软件，包 ## 如何编译 -在你能编译之前, 你需要[部署环境](getting_started_build_tools.md) 用于 AVR or/and ARM 开发。完成后, 你可以使用 `make` 命令来编译一个键盘和布局使用以下命令: +在你能编译之前, 你需要[部署环境](zh-cn/getting_started_build_tools.md) 用于 AVR or/and ARM 开发。完成后, 你可以使用 `make` 命令来编译一个键盘和布局使用以下命令: make planck/rev4:default @@ -29,4 +29,4 @@ QMK (*Quantum Mechanical Keyboard*) 是一个社区维护的开源软件，包 ## 如何定制 -QMK 有许多 [特性](features.md)来探索，也有很多 [参考文档](http://docs.qmk.fm) 供您发掘。你可以通过修改 [布局](keymap.md)和[键码](keycodes.md)来利用许多特性。 +QMK 有许多 [特性](zh-cn/features.md)来探索，也有很多 [参考文档](http://docs.qmk.fm) 供您发掘。你可以通过修改 [布局](zh-cn/keymap.md)和[键码](zh-cn/keycodes.md)来利用许多特性。 diff --git a/docs/zh-cn/faq_build.md b/docs/zh-cn/faq_build.md index 8fb449db3..0d9047bc5 100644 --- a/docs/zh-cn/faq_build.md +++ b/docs/zh-cn/faq_build.md @@ -56,11 +56,6 @@ SUBSYSTEMS=="usb", ATTRS{idVendor}=="1c11", MODE:="0666" ?> 事实上没有一个驱动的最佳选择，有些选项就是和某些系统相辅相成。但libUSB和WinUSB似乎也算是这里的最佳选择了。 如果bootloader在设备列表中没有显示，你可能要使能 "List all devices"选项在选项菜单中`Options`，然后找到有问题的bootloader设备。(译者注：在win10中可能为 查看-显示隐藏的设备) - -## WINAVR已淘汰 -不再推荐使用WINAVR，使用可能会导致问题 -详情请见[TMK Issue #99](https://github.com/tmk/tmk_keyboard/issues/99). - ## USB VID 和 PID 你可以在编辑`config.h`时使用任何你想用的ID值。实际上，使用任何可能未使用的ID都没有问题，除了有极低的与其他产品发生冲突的可能性。 @@ -73,29 +68,6 @@ https://github.com/tmk/tmk_keyboard/issues/150 - http://www.obdev.at/products/vusb/license.html - http://www.mcselec.com/index.php?page=shop.product_details&flypage=shop.flypage&product_id=92&option=com_phpshop&Itemid=1 -## Cortex: `cstddef: No such file or directory` -在Ubuntu 14.04上的GCC 4.8 会出现这种问题需要用这个PPA升级到4.9。 -https://launchpad.net/~terry.guo/+archive/ubuntu/gcc-arm-embedded - -https://github.com/tmk/tmk_keyboard/issues/212 -https://github.com/tmk/tmk_keyboard/wiki/mbed-cortex-porting#compile-error-cstddef -https://developer.mbed.org/forum/mbed/topic/5205/ - -## `clock_prescale_set` and `clock_div_1` Not Available -你的工具链太旧了不支持MCU。比如WinAVR 20100110就不支持ATMega32u2. - -``` -Compiling C: ../../tmk_core/protocol/lufa/lufa.c -avr-gcc -c -mmcu=atmega32u2 -gdwarf-2 -DF_CPU=16000000UL -DINTERRUPT_CONTROL_ENDPOINT -DBOOTLOADER_SIZE=4096 -DF_USB=16000000UL -DARCH=ARCH_AVR8 -DUSB_DEVICE_ONLY -DUSE_FLASH_DESCRIPTORS -DUSE_STATIC_OPTIONS="(USB_DEVICE_OPT_FULLSPEED | USB_OPT_REG_ENABLED | USB_OPT_AUTO_PLL)" -DFIXED_CONTROL_ENDPOINT_SIZE=8 -DFIXED_NUM_CONFIGURATIONS=1 -DPROTOCOL_LUFA -DEXTRAKEY_ENABLE -DCONSOLE_ENABLE -DCOMMAND_ENABLE -DVERSION=unknown -Os -funsigned-char -funsigned-bitfields -ffunction-sections -fdata-sections -fno-inline-small-functions -fpack-struct -fshort-enums -fno-strict-aliasing -Wall -Wstrict-prototypes -Wa,-adhlns=obj_alps64/protocol/lufa/lufa.lst -I. -I../../tmk_core -I../../tmk_core/protocol/lufa -I../../tmk_core/protocol/lufa/LUFA-git -I../../tmk_core/common -std=gnu99 -include config.h -MMD -MP -MF .dep/obj_alps64_protocol_lufa_lufa.o.d ../../tmk_core/protocol/lufa/lufa.c -o obj_alps64/protocol/lufa/lufa.o -../../tmk_core/protocol/lufa/lufa.c: In function 'setup_mcu': -../../tmk_core/protocol/lufa/lufa.c:575: warning: implicit declaration of function 'clock_prescale_set' -../../tmk_core/protocol/lufa/lufa.c:575: error: 'clock_div_1' undeclared (first use in this function) -../../tmk_core/protocol/lufa/lufa.c:575: error: (Each undeclared identifier is reported only once -../../tmk_core/protocol/lufa/lufa.c:575: error: for each function it appears in.) -make: *** [obj_alps64/protocol/lufa/lufa.o] Error 1 -``` - - ## AVR的BOOTLOADER_SIZE 注意Teensy2.0++ bootloader的大小是2048字节。有些Makefile注释错了。 diff --git a/docs/zh-cn/faq_debug.md b/docs/zh-cn/faq_debug.md index a3cc7c510..7eff7f265 100644 --- a/docs/zh-cn/faq_debug.md +++ b/docs/zh-cn/faq_debug.md @@ -101,56 +101,6 @@ https://github.com/tmk/tmk_keyboard#boot-magic-configuration---virtual-dip-switc http://deskthority.net/workshop-f7/rebuilding-and-redesigning-a-classic-thinkpad-keyboard-t6181-60.html#p146279 - -## Bootloader跳转不好用 -在**Makefile**中正确配置**Makefile**大小。如果分区大小不正确，引导加载程序可能无法从**Magic command**和**Boot Magic**加载。 -``` -# bootloader字节数： -# Atmel DFU loader(ATmega32U4) 4096 -# Atmel DFU loader(AT90USB128) 8192 -# LUFA bootloader(ATmega32U4) 4096 -# Arduino Caterina(ATmega32U4) 4096 -# USBaspLoader(ATmega***) 2048 -# Teensy halfKay(ATmega32U4) 512 -# Teensy++ halfKay(AT90USB128) 2048 -OPT_DEFS += -DBOOTLOADER_SIZE=4096 -``` -AVR引导大小是通过**BOOTSZ**熔丝位来设置的。查阅你单片机的datasheet。 -记住，datasheet用的是**Word**(2字节)表示大小和地址，TMK用的是**Byte**。 - -AVR引导部分位于闪存的末尾，如下所示（Application是应用区，Bootloader是引导区）。 -``` -byte Atmel/LUFA(ATMega32u4) byte Atmel(AT90SUB1286) -0x0000 +---------------+ 0x00000 +---------------+ - | | | | - | | | | - | Application | | Application | - | | | | - = = = = - | | 32KB-4KB | | 128KB-8KB -0x6000 +---------------+ 0x1E000 +---------------+ - | Bootloader | 4KB | Bootloader | 8KB -0x7FFF +---------------+ 0x1FFFF +---------------+ - - -byte Teensy(ATMega32u4) byte Teensy++(AT90SUB1286) -0x0000 +---------------+ 0x00000 +---------------+ - | | | | - | | | | - | Application | | Application | - | | | | - = = = = - | | 32KB-512B | | 128KB-2KB -0x7E00 +---------------+ 0x1FC00 +---------------+ - | Bootloader | 512B | Bootloader | 2KB -0x7FFF +---------------+ 0x1FFFF +---------------+ -``` - -详情请见下方issue。 -https://github.com/tmk/tmk_keyboard/issues/179 - -如果你使用TeensyUSB, 有一个[已知bug](https://github.com/qmk/qmk_firmware/issues/164)硬件重置按钮阻止软件定义重置键工作。重新插拔键盘就好了。 - ## 特殊额外键不起作用(系统，音频控制键) 你要在`rules.mk`定义`EXTRAKEY_ENABLE`在QMK中使用它们。 @@ -173,24 +123,6 @@ EXTRAKEY_ENABLE = yes # 音频控制和系统控制 Arduino Leonardo和micro使用**ATMega32U4**，该芯片TMK可用，但Arduino的bootloader会导致问题。 -## 为锁定键添加指示灯 -你要自制CapsLock, ScrollLock 和 NumLock指示灯？见下文。 - -http://deskthority.net/workshop-f7/tmk-keyboard-firmware-collection-t4478-120.html#p191560 - -## 为Arduino Micro/Leonardo编程 -按下重置键然后在8秒内运行下方这样的命令。 - -``` -avrdude -patmega32u4 -cavr109 -b57600 -Uflash:w:adb_usb.hex -P/dev/ttyACM0 -``` - -设备名称因系统而异。 - -http://arduino.cc/en/Main/ArduinoBoardMicro -https://geekhack.org/index.php?topic=14290.msg1563867#msg1563867 - - ## USB 3 兼容性 据传说有些人用USB3接口会有问题，用USB2的试试。 diff --git a/docs/zh-cn/faq_keymap.md b/docs/zh-cn/faq_keymap.md index ee8e3c06b..7fb434b4c 100644 --- a/docs/zh-cn/faq_keymap.md +++ b/docs/zh-cn/faq_keymap.md @@ -66,24 +66,8 @@ https://github.com/tmk/tmk_keyboard/issues/67 远古机械键盘偶尔会有自锁机械开关，现在几乎没有了。***大多数情况下你不需要使用该功能，且要使用`KC_CAPS`, `KC_NLCK`和`KC_SLCK`这三个键码。*** ## 输入ASCII之外的特殊字符比如Cédille 'Ç' -没有在所有系统中输入这个的通用方法。你要定义针对你的特定操作系统或布局的**宏**。 -比如看这个**宏**代码的文章。 - -http://deskthority.net/workshop-f7/tmk-keyboard-firmware-collection-t4478-120.html#p195620 -<!--翻译问题：下方维基百科链接应全部替换为中文链接，暂未找到全部--> -在**Windows**上，可以用`AltGr`键或**Alt码**。 -* http://en.wikipedia.org/wiki/AltGr_key -* https://zh.wikipedia.org/wiki/Alt%E7%A0%81 - -在**Mac OS**定义`Option`键组合。 -* https://zh.wikipedia.org/wiki/Option%E9%94%AE#%E6%9B%BF%E4%BB%A3%E9%94%AE%E7%9B%98%E8%BE%93%E5%85%A5 - -在**Xorg**可以改用`compose`键。 -* http://en.wikipedia.org/wiki/Compose_key - -下方链接查看**Unicode**输入。 -* http://en.wikipedia.org/wiki/Unicode_input +请见[Unicode](feature_unicode.md)功能。 ## macOS上的`Fn` @@ -136,51 +120,6 @@ https://github.com/tekezo/Karabiner/issues/403 请见[Grave Escape](feature_grave_esc.md)功能。 -## 右侧双角色修改键(诸如Shift、Alt等有修改其他键作用的键)变箭头键 -右侧修改键单击时会变为箭头键，长按就还是修改键。在TMK中双角色键称之为**TAP**. -``` - -#include "keymap_common.h" - - -/* 用TMK双角色键功能实现右侧修改键改箭头键 - * - * https://github.com/tmk/tmk_core/blob/master/doc/keymap.md#213-modifier-with-tap-keydual-role - * https://en.wikipedia.org/wiki/Modifier_key#Dual-role_keys - */ -const uint8_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] = { - /* 0: qwerty */ - [0] = LAYOUT( \ - ESC, 1, 2, 3, 4, 5, 6, 7, 8, 9, 0, MINS,EQL, NUHS,BSPC, \ - TAB, Q, W, E, R, T, Y, U, I, O, P, LBRC,RBRC,BSLS, \ - LCTL,A, S, D, F, G, H, J, K, L, SCLN,QUOT,ENT, \ - LSFT,NUBS,Z, X, C, V, B, N, M, COMM,DOT, SLSH,FN0, ESC, \ - FN4, LGUI,LALT, SPC, APP, FN2, FN1, FN3), - [1] = LAYOUT( \ - GRV, F1, F2, F3, F4, F5, F6, F7, F8, F9, F10, F11, F12, TRNS,TRNS, \ - TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,\ - TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS, \ - TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,FN5, TRNS, \ - TRNS,TRNS,TRNS, TRNS, TRNS,FN7, FN6, FN8), -}; - -const uint16_t PROGMEM fn_actions[] = { - [0] = ACTION_MODS_TAP_KEY(MOD_RSFT, KC_UP), - [1] = ACTION_MODS_TAP_KEY(MOD_RGUI, KC_DOWN), - [2] = ACTION_MODS_TAP_KEY(MOD_RALT, KC_LEFT), - [3] = ACTION_MODS_TAP_KEY(MOD_RCTL, KC_RIGHT), - [4] = ACTION_LAYER_MOMENTARY(1), - [5] = ACTION_MODS_TAP_KEY(MOD_RSFT, KC_PGUP), - [6] = ACTION_MODS_TAP_KEY(MOD_RGUI, KC_PGDN), - [7] = ACTION_MODS_TAP_KEY(MOD_RALT, KC_HOME), - [8] = ACTION_MODS_TAP_KEY(MOD_RCTL, KC_END), -}; - -``` - -双角色键说明: https://en.wikipedia.org/wiki/Modifier_key#Dual-role_keys - - ## Mac OSX的弹出键 `KC_EJCT` 键码在OSX可以使用 https://github.com/tmk/tmk_keyboard/issues/250 似乎Windows10会忽略该键码，Linux/Xorg可以识别该键码但默认不映射。 |