From 6ef97172889ccd5db376b2a9f8825489e24fdac4 Mon Sep 17 00:00:00 2001 From: Nick Brassel Date: Thu, 30 May 2024 12:00:41 +1000 Subject: [PATCH] Vitepress conversion of docs. (#23795) --- .github/workflows/docs.yml | 53 +- Doxyfile | 70 +- builddefs/docsgen/.gitignore | 5 + builddefs/docsgen/.vitepress/config.mts | 51 ++ .../docsgen/.vitepress/theme/QMKLayout.vue | 18 + builddefs/docsgen/.vitepress/theme/custom.css | 19 + builddefs/docsgen/.vitepress/theme/index.ts | 13 + builddefs/docsgen/build-docs.sh | 6 + builddefs/docsgen/package.json | 14 + builddefs/docsgen/start-docs.sh | 5 + builddefs/docsgen/yarn.lock | 797 ++++++++++++++++ docs/.nojekyll | 0 docs/CNAME | 1 - docs/ChangeLog/20190830.md | 4 +- docs/ChangeLog/20200229.md | 2 +- docs/ChangeLog/20200829.md | 18 +- docs/ChangeLog/20201128.md | 16 +- docs/ChangeLog/20210529.md | 32 +- docs/ChangeLog/20210828.md | 30 +- docs/ChangeLog/20211127.md | 40 +- docs/ChangeLog/20220226.md | 14 +- docs/ChangeLog/20220528.md | 34 +- docs/ChangeLog/20220827.md | 32 +- docs/ChangeLog/20221126.md | 40 +- docs/ChangeLog/20230226.md | 20 +- docs/ChangeLog/20230528.md | 32 +- docs/ChangeLog/20230827.md | 22 +- docs/ChangeLog/20231126.md | 34 +- docs/ChangeLog/20240225.md | 26 +- docs/ChangeLog/20240526.md | 28 +- docs/__capabilities.md | 47 +- docs/_langs.md | 4 - docs/_sidebar.json | 309 +++++++ docs/_summary.md | 204 ----- docs/adc_driver.md | 2 +- docs/apa102_driver.md | 16 +- docs/api_docs.md | 10 +- docs/api_overview.md | 6 +- docs/audio_driver.md | 24 +- docs/breaking_changes.md | 12 +- docs/breaking_changes_history.md | 38 +- docs/cli.md | 12 +- docs/cli_commands.md | 33 +- docs/cli_development.md | 4 +- docs/coding_conventions_python.md | 2 +- docs/compatible_microcontrollers.md | 2 +- docs/config_options.md | 38 +- docs/configurator_default_keymaps.md | 18 +- docs/configurator_step_by_step.md | 34 +- docs/configurator_troubleshooting.md | 4 +- docs/contributing.md | 18 +- docs/custom_quantum_functions.md | 36 +- docs/data_driven_config.md | 4 +- docs/documentation_best_practices.md | 18 +- docs/documentation_templates.md | 4 +- docs/driver_installation_zadig.md | 16 +- docs/easy_maker.md | 2 +- docs/eeprom_driver.md | 50 +- docs/faq_build.md | 8 +- docs/faq_debug.md | 12 +- docs/faq_general.md | 10 +- docs/faq_keymap.md | 12 +- docs/faq_misc.md | 2 +- docs/feature_advanced_keycodes.md | 38 +- docs/feature_audio.md | 10 +- docs/feature_auto_shift.md | 32 +- docs/feature_autocorrect.md | 44 +- docs/feature_backlight.md | 74 +- docs/feature_bluetooth.md | 2 +- docs/feature_bootmagic.md | 16 +- docs/feature_caps_word.md | 20 +- docs/feature_combo.md | 8 +- docs/feature_command.md | 2 +- docs/feature_converters.md | 38 +- docs/feature_debounce_type.md | 12 +- docs/feature_digitizer.md | 24 +- docs/feature_dip_switch.md | 6 +- docs/feature_dynamic_macros.md | 4 +- docs/feature_eeprom.md | 2 +- docs/feature_encoders.md | 22 +- docs/feature_haptic_feedback.md | 4 +- docs/feature_hd44780.md | 84 +- docs/feature_joystick.md | 48 +- docs/feature_key_lock.md | 4 +- docs/feature_key_overrides.md | 44 +- docs/feature_layers.md | 36 +- docs/feature_leader_key.md | 76 +- docs/feature_led_indicators.md | 12 +- docs/feature_led_matrix.md | 50 +- docs/feature_macros.md | 20 +- docs/feature_midi.md | 8 +- docs/feature_mouse_keys.md | 2 +- docs/feature_oled_driver.md | 22 +- docs/feature_os_detection.md | 6 +- docs/feature_pointing_device.md | 32 +- docs/feature_programmable_button.md | 46 +- docs/feature_ps2_mouse.md | 36 +- docs/feature_rawhid.md | 26 +- docs/feature_repeat_key.md | 10 +- docs/feature_rgb_matrix.md | 118 ++- docs/feature_rgblight.md | 32 +- docs/feature_secure.md | 6 +- docs/feature_send_string.md | 70 +- docs/feature_sequencer.md | 4 +- docs/feature_space_cadet.md | 2 +- docs/feature_split_keyboard.md | 52 +- docs/feature_stenography.md | 44 +- docs/feature_swap_hands.md | 4 +- docs/feature_tap_dance.md | 34 +- docs/feature_tri_layer.md | 10 +- docs/feature_unicode.md | 132 +-- docs/feature_userspace.md | 20 +- docs/flash_driver.md | 8 +- docs/flashing.md | 6 +- docs/flashing_bootloadhid.md | 4 +- docs/getting_started_docker.md | 4 +- docs/getting_started_github.md | 4 +- docs/getting_started_introduction.md | 6 +- docs/getting_started_make_guide.md | 16 +- docs/gpio_control.md | 8 +- docs/hand_wire.md | 8 +- docs/hardware_drivers.md | 10 +- docs/hardware_keyboard_guidelines.md | 26 +- docs/how_a_matrix_works.md | 2 +- docs/how_keyboards_work.md | 2 +- docs/i2c_driver.md | 62 +- docs/index.html | 147 --- docs/{README.md => index.md} | 15 +- docs/internals/defines.md | 78 -- docs/internals/input_callback_reg.md | 169 ---- docs/internals/midi_device.md | 143 --- docs/internals/midi_device_setup_process.md | 31 - docs/internals/midi_util.md | 54 -- docs/internals/send_functions.md | 241 ----- docs/internals/sysex_tools.md | 61 -- docs/isp_flashing_guide.md | 34 +- docs/ja/README.md | 47 - docs/ja/_summary.md | 180 ---- docs/ja/adc_driver.md | 155 ---- docs/ja/api_development_environment.md | 8 - docs/ja/api_development_overview.md | 49 - docs/ja/api_docs.md | 73 -- docs/ja/api_overview.md | 20 - docs/ja/arm_debugging.md | 92 -- docs/ja/breaking_changes.md | 120 --- docs/ja/breaking_changes_instructions.md | 51 -- docs/ja/cli.md | 43 - docs/ja/cli_commands.md | 296 ------ docs/ja/cli_configuration.md | 126 --- docs/ja/cli_development.md | 223 ----- docs/ja/coding_conventions_c.md | 63 -- docs/ja/coding_conventions_python.md | 331 ------- docs/ja/compatible_microcontrollers.md | 54 -- docs/ja/config_options.md | 410 --------- docs/ja/configurator_step_by_step.md | 67 -- docs/ja/configurator_troubleshooting.md | 32 - docs/ja/contributing.md | 173 ---- docs/ja/custom_matrix.md | 114 --- docs/ja/custom_quantum_functions.md | 403 -------- docs/ja/data_driven_config.md | 123 --- docs/ja/documentation_best_practices.md | 69 -- docs/ja/documentation_templates.md | 45 - docs/ja/driver_installation_zadig.md | 53 -- docs/ja/faq_build.md | 73 -- docs/ja/faq_debug.md | 131 --- docs/ja/faq_general.md | 58 -- docs/ja/faq_keymap.md | 160 ---- docs/ja/faq_misc.md | 103 --- docs/ja/feature_advanced_keycodes.md | 185 ---- docs/ja/feature_audio.md | 322 ------- docs/ja/feature_auto_shift.md | 135 --- docs/ja/feature_backlight.md | 225 ----- docs/ja/feature_bluetooth.md | 49 - docs/ja/feature_bootmagic.md | 182 ---- docs/ja/feature_combo.md | 108 --- docs/ja/feature_command.md | 56 -- docs/ja/feature_debounce_type.md | 128 --- docs/ja/feature_dip_switch.md | 115 --- docs/ja/feature_dynamic_macros.md | 72 -- docs/ja/feature_encoders.md | 85 -- docs/ja/feature_grave_esc.md | 37 - docs/ja/feature_haptic_feedback.md | 173 ---- docs/ja/feature_hd44780.md | 62 -- docs/ja/feature_key_lock.md | 27 - docs/ja/feature_layers.md | 97 -- docs/ja/feature_layouts.md | 114 --- docs/ja/feature_leader_key.md | 164 ---- docs/ja/feature_led_indicators.md | 119 --- docs/ja/feature_led_matrix.md | 96 -- docs/ja/feature_macros.md | 303 ------ docs/ja/feature_mouse_keys.md | 147 --- docs/ja/feature_pointing_device.md | 58 -- docs/ja/feature_ps2_mouse.md | 288 ------ docs/ja/feature_rawhid.md | 74 -- docs/ja/feature_split_keyboard.md | 251 ----- docs/ja/feature_stenography.md | 135 --- docs/ja/feature_swap_hands.md | 36 - docs/ja/feature_tap_dance.md | 530 ----------- docs/ja/feature_thermal_printer.md | 15 - docs/ja/feature_unicode.md | 266 ------ docs/ja/feature_userspace.md | 260 ------ docs/ja/feature_wpm.md | 24 - docs/ja/flashing.md | 247 ----- docs/ja/flashing_bootloadhid.md | 75 -- docs/ja/getting_started_docker.md | 60 -- docs/ja/getting_started_github.md | 69 -- docs/ja/getting_started_introduction.md | 65 -- docs/ja/getting_started_make_guide.md | 161 ---- docs/ja/gpio_control.md | 47 - docs/ja/hardware_avr.md | 190 ---- docs/ja/hardware_drivers.md | 41 - docs/ja/hardware_keyboard_guidelines.md | 239 ----- docs/ja/how_a_matrix_works.md | 104 --- docs/ja/how_keyboards_work.md | 74 -- docs/ja/i2c_driver.md | 134 --- docs/ja/isp_flashing_guide.md | 294 ------ docs/ja/ja_doc_status.sh | 34 - docs/ja/keycodes.md | 574 ------------ docs/ja/keycodes_basic.md | 261 ------ docs/ja/keycodes_us_ansi_shifted.md | 41 - docs/ja/keymap.md | 189 ---- docs/ja/mod_tap.md | 71 -- docs/ja/newbs.md | 40 - docs/ja/newbs_building_firmware.md | 81 -- .../newbs_building_firmware_configurator.md | 20 - docs/ja/newbs_flashing.md | 133 --- docs/ja/newbs_getting_started.md | 210 ----- docs/ja/newbs_git_best_practices.md | 24 - .../ja/newbs_git_resolving_merge_conflicts.md | 94 -- docs/ja/newbs_git_resynchronize_a_branch.md | 88 -- docs/ja/newbs_git_using_your_master_branch.md | 101 -- docs/ja/newbs_learn_more_resources.md | 63 -- docs/ja/newbs_testing_debugging.md | 15 - docs/ja/one_shot_keys.md | 110 --- docs/ja/other_eclipse.md | 89 -- docs/ja/other_vscode.md | 119 --- docs/ja/pr_checklist.md | 145 --- docs/ja/proton_c_conversion.md | 98 -- docs/ja/quantum_keycodes.md | 20 - docs/ja/ref_functions.md | 124 --- docs/ja/reference_configurator_support.md | 200 ---- docs/ja/reference_glossary.md | 173 ---- docs/ja/reference_info_json.md | 68 -- docs/ja/reference_keymap_extras.md | 89 -- docs/ja/serial_driver.md | 75 -- docs/ja/support.md | 22 - docs/ja/syllabus.md | 76 -- docs/ja/tap_hold.md | 167 ---- docs/ja/translating.md | 60 -- docs/ja/understanding_qmk.md | 190 ---- docs/keycodes.md | 124 +-- docs/keycodes_basic.md | 4 +- docs/keycodes_magic.md | 2 +- docs/keymap.md | 12 +- docs/mod_tap.md | 8 +- docs/newbs.md | 16 +- docs/newbs_building_firmware.md | 24 +- docs/newbs_building_firmware_configurator.md | 8 +- docs/newbs_building_firmware_workflow.md | 48 +- docs/newbs_external_userspace.md | 24 +- docs/newbs_flashing.md | 20 +- docs/newbs_getting_started.md | 114 ++- docs/newbs_git_best_practices.md | 10 +- docs/newbs_git_resolving_merge_conflicts.md | 4 +- docs/newbs_git_resynchronize_a_branch.md | 10 +- docs/newbs_git_using_your_master_branch.md | 14 +- docs/newbs_testing_debugging.md | 6 +- docs/one_shot_keys.md | 6 +- docs/other_eclipse.md | 2 +- docs/other_vscode.md | 10 +- docs/platformdev_chibios_earlyinit.md | 8 +- docs/platformdev_rp2040.md | 42 +- docs/platformdev_selecting_arm_mcu.md | 10 +- docs/porting_your_keyboard_to_qmk.md | 26 +- docs/pr_checklist.md | 28 +- docs/public/badge-community-dark.svg | 1 + docs/public/badge-community-light.svg | 1 + docs/qmk.css | 862 ------------------ docs/qmk_custom_dark.css | 45 - docs/qmk_custom_light.css | 58 -- docs/quantum_keycodes.md | 6 +- docs/quantum_painter.md | 215 +++-- docs/quantum_painter_lvgl.md | 27 +- docs/quantum_painter_qff.md | 22 +- docs/quantum_painter_qgf.md | 18 +- docs/quantum_painter_rle.md | 4 +- docs/redirects.json | 52 -- docs/ref_functions.md | 16 +- docs/reference_configurator_support.md | 16 +- docs/reference_glossary.md | 20 +- docs/reference_info_json.md | 108 +-- docs/serial_driver.md | 22 +- docs/spi_driver.md | 44 +- docs/squeezing_avr.md | 2 +- docs/support_deprecation_policy.md | 8 +- docs/sw.js | 83 -- docs/syllabus.md | 82 +- docs/tap_hold.md | 32 +- docs/translating.md | 55 -- docs/uart_driver.md | 34 +- docs/understanding_qmk.md | 6 +- docs/unit_testing.md | 4 +- docs/ws2812_driver.md | 50 +- docs/zh-cn/README.md | 42 - docs/zh-cn/_summary.md | 191 ---- docs/zh-cn/api_docs.md | 73 -- docs/zh-cn/api_overview.md | 20 - docs/zh-cn/cli.md | 43 - docs/zh-cn/cli_commands.md | 503 ---------- docs/zh-cn/cli_configuration.md | 126 --- docs/zh-cn/cli_tab_complete.md | 32 - docs/zh-cn/configurator_architecture.md | 66 -- docs/zh-cn/configurator_default_keymaps.md | 198 ---- docs/zh-cn/configurator_step_by_step.md | 63 -- docs/zh-cn/configurator_troubleshooting.md | 31 - docs/zh-cn/contributing.md | 175 ---- docs/zh-cn/custom_quantum_functions.md | 476 ---------- docs/zh-cn/driver_installation_zadig.md | 102 --- docs/zh-cn/easy_maker.md | 37 - docs/zh-cn/faq_build.md | 73 -- docs/zh-cn/faq_debug.md | 136 --- docs/zh-cn/faq_general.md | 58 -- docs/zh-cn/faq_keymap.md | 157 ---- docs/zh-cn/faq_misc.md | 108 --- docs/zh-cn/feature_grave_esc.md | 39 - docs/zh-cn/feature_space_cadet.md | 70 -- docs/zh-cn/flashing.md | 329 ------- docs/zh-cn/flashing_bootloadhid.md | 75 -- docs/zh-cn/getting_started_docker.md | 59 -- docs/zh-cn/getting_started_github.md | 69 -- docs/zh-cn/getting_started_introduction.md | 59 -- docs/zh-cn/hand_wire.md | 255 ------ docs/zh-cn/keymap.md | 211 ----- docs/zh-cn/mod_tap.md | 141 --- docs/zh-cn/newbs.md | 29 - docs/zh-cn/newbs_building_firmware.md | 68 -- .../newbs_building_firmware_configurator.md | 18 - docs/zh-cn/newbs_flashing.md | 124 --- docs/zh-cn/newbs_getting_started.md | 208 ----- docs/zh-cn/newbs_git_best_practices.md | 23 - .../newbs_git_resolving_merge_conflicts.md | 86 -- .../zh-cn/newbs_git_resynchronize_a_branch.md | 76 -- .../newbs_git_using_your_master_branch.md | 79 -- docs/zh-cn/newbs_learn_more_resources.md | 35 - docs/zh-cn/newbs_testing_debugging.md | 14 - docs/zh-cn/other_eclipse.md | 90 -- docs/zh-cn/other_vscode.md | 120 --- docs/zh-cn/reference_configurator_support.md | 200 ---- docs/zh-cn/reference_glossary.md | 198 ---- docs/zh-cn/support.md | 22 - docs/zh-cn/syllabus.md | 77 -- docs/zh-cn/translating.md | 60 -- docs/zh-cn/zh_cn_doc_status.sh | 35 - lib/python/qmk/cli/docs.py | 41 +- lib/python/qmk/cli/generate/docs.py | 42 +- lib/python/qmk/cli/new/keyboard.py | 2 +- lib/python/qmk/docs.py | 61 ++ 357 files changed, 3611 insertions(+), 24208 deletions(-) create mode 100644 builddefs/docsgen/.gitignore create mode 100644 builddefs/docsgen/.vitepress/config.mts create mode 100644 builddefs/docsgen/.vitepress/theme/QMKLayout.vue create mode 100644 builddefs/docsgen/.vitepress/theme/custom.css create mode 100644 builddefs/docsgen/.vitepress/theme/index.ts create mode 100755 builddefs/docsgen/build-docs.sh create mode 100644 builddefs/docsgen/package.json create mode 100755 builddefs/docsgen/start-docs.sh create mode 100644 builddefs/docsgen/yarn.lock delete mode 100644 docs/.nojekyll delete mode 100644 docs/CNAME delete mode 100644 docs/_langs.md create mode 100644 docs/_sidebar.json delete mode 100644 docs/_summary.md delete mode 100644 docs/index.html rename docs/{README.md => index.md} (76%) delete mode 100644 docs/internals/defines.md delete mode 100644 docs/internals/input_callback_reg.md delete mode 100644 docs/internals/midi_device.md delete mode 100644 docs/internals/midi_device_setup_process.md delete mode 100644 docs/internals/midi_util.md delete mode 100644 docs/internals/send_functions.md delete mode 100644 docs/internals/sysex_tools.md delete mode 100644 docs/ja/README.md delete mode 100644 docs/ja/_summary.md delete mode 100644 docs/ja/adc_driver.md delete mode 100644 docs/ja/api_development_environment.md delete mode 100644 docs/ja/api_development_overview.md delete mode 100644 docs/ja/api_docs.md delete mode 100644 docs/ja/api_overview.md delete mode 100644 docs/ja/arm_debugging.md delete mode 100644 docs/ja/breaking_changes.md delete mode 100644 docs/ja/breaking_changes_instructions.md delete mode 100644 docs/ja/cli.md delete mode 100644 docs/ja/cli_commands.md delete mode 100644 docs/ja/cli_configuration.md delete mode 100644 docs/ja/cli_development.md delete mode 100644 docs/ja/coding_conventions_c.md delete mode 100644 docs/ja/coding_conventions_python.md delete mode 100644 docs/ja/compatible_microcontrollers.md delete mode 100644 docs/ja/config_options.md delete mode 100644 docs/ja/configurator_step_by_step.md delete mode 100644 docs/ja/configurator_troubleshooting.md delete mode 100644 docs/ja/contributing.md delete mode 100644 docs/ja/custom_matrix.md delete mode 100644 docs/ja/custom_quantum_functions.md delete mode 100644 docs/ja/data_driven_config.md delete mode 100644 docs/ja/documentation_best_practices.md delete mode 100644 docs/ja/documentation_templates.md delete mode 100644 docs/ja/driver_installation_zadig.md delete mode 100644 docs/ja/faq_build.md delete mode 100644 docs/ja/faq_debug.md delete mode 100644 docs/ja/faq_general.md delete mode 100644 docs/ja/faq_keymap.md delete mode 100644 docs/ja/faq_misc.md delete mode 100644 docs/ja/feature_advanced_keycodes.md delete mode 100644 docs/ja/feature_audio.md delete mode 100644 docs/ja/feature_auto_shift.md delete mode 100644 docs/ja/feature_backlight.md delete mode 100644 docs/ja/feature_bluetooth.md delete mode 100644 docs/ja/feature_bootmagic.md delete mode 100644 docs/ja/feature_combo.md delete mode 100644 docs/ja/feature_command.md delete mode 100644 docs/ja/feature_debounce_type.md delete mode 100644 docs/ja/feature_dip_switch.md delete mode 100644 docs/ja/feature_dynamic_macros.md delete mode 100644 docs/ja/feature_encoders.md delete mode 100644 docs/ja/feature_grave_esc.md delete mode 100644 docs/ja/feature_haptic_feedback.md delete mode 100644 docs/ja/feature_hd44780.md delete mode 100644 docs/ja/feature_key_lock.md delete mode 100644 docs/ja/feature_layers.md delete mode 100644 docs/ja/feature_layouts.md delete mode 100644 docs/ja/feature_leader_key.md delete mode 100644 docs/ja/feature_led_indicators.md delete mode 100644 docs/ja/feature_led_matrix.md delete mode 100644 docs/ja/feature_macros.md delete mode 100644 docs/ja/feature_mouse_keys.md delete mode 100644 docs/ja/feature_pointing_device.md delete mode 100644 docs/ja/feature_ps2_mouse.md delete mode 100644 docs/ja/feature_rawhid.md delete mode 100644 docs/ja/feature_split_keyboard.md delete mode 100644 docs/ja/feature_stenography.md delete mode 100644 docs/ja/feature_swap_hands.md delete mode 100644 docs/ja/feature_tap_dance.md delete mode 100644 docs/ja/feature_thermal_printer.md delete mode 100644 docs/ja/feature_unicode.md delete mode 100644 docs/ja/feature_userspace.md delete mode 100644 docs/ja/feature_wpm.md delete mode 100644 docs/ja/flashing.md delete mode 100644 docs/ja/flashing_bootloadhid.md delete mode 100644 docs/ja/getting_started_docker.md delete mode 100644 docs/ja/getting_started_github.md delete mode 100644 docs/ja/getting_started_introduction.md delete mode 100644 docs/ja/getting_started_make_guide.md delete mode 100644 docs/ja/gpio_control.md delete mode 100644 docs/ja/hardware_avr.md delete mode 100644 docs/ja/hardware_drivers.md delete mode 100644 docs/ja/hardware_keyboard_guidelines.md delete mode 100644 docs/ja/how_a_matrix_works.md delete mode 100644 docs/ja/how_keyboards_work.md delete mode 100644 docs/ja/i2c_driver.md delete mode 100644 docs/ja/isp_flashing_guide.md delete mode 100644 docs/ja/ja_doc_status.sh delete mode 100644 docs/ja/keycodes.md delete mode 100644 docs/ja/keycodes_basic.md delete mode 100644 docs/ja/keycodes_us_ansi_shifted.md delete mode 100644 docs/ja/keymap.md delete mode 100644 docs/ja/mod_tap.md delete mode 100644 docs/ja/newbs.md delete mode 100644 docs/ja/newbs_building_firmware.md delete mode 100644 docs/ja/newbs_building_firmware_configurator.md delete mode 100644 docs/ja/newbs_flashing.md delete mode 100644 docs/ja/newbs_getting_started.md delete mode 100644 docs/ja/newbs_git_best_practices.md delete mode 100644 docs/ja/newbs_git_resolving_merge_conflicts.md delete mode 100644 docs/ja/newbs_git_resynchronize_a_branch.md delete mode 100644 docs/ja/newbs_git_using_your_master_branch.md delete mode 100644 docs/ja/newbs_learn_more_resources.md delete mode 100644 docs/ja/newbs_testing_debugging.md delete mode 100644 docs/ja/one_shot_keys.md delete mode 100644 docs/ja/other_eclipse.md delete mode 100644 docs/ja/other_vscode.md delete mode 100644 docs/ja/pr_checklist.md delete mode 100644 docs/ja/proton_c_conversion.md delete mode 100644 docs/ja/quantum_keycodes.md delete mode 100644 docs/ja/ref_functions.md delete mode 100644 docs/ja/reference_configurator_support.md delete mode 100644 docs/ja/reference_glossary.md delete mode 100644 docs/ja/reference_info_json.md delete mode 100644 docs/ja/reference_keymap_extras.md delete mode 100644 docs/ja/serial_driver.md delete mode 100644 docs/ja/support.md delete mode 100644 docs/ja/syllabus.md delete mode 100644 docs/ja/tap_hold.md delete mode 100644 docs/ja/translating.md delete mode 100644 docs/ja/understanding_qmk.md create mode 100644 docs/public/badge-community-dark.svg create mode 100644 docs/public/badge-community-light.svg delete mode 100644 docs/qmk.css delete mode 100644 docs/qmk_custom_dark.css delete mode 100644 docs/qmk_custom_light.css delete mode 100644 docs/redirects.json delete mode 100644 docs/sw.js delete mode 100644 docs/translating.md delete mode 100644 docs/zh-cn/README.md delete mode 100644 docs/zh-cn/_summary.md delete mode 100644 docs/zh-cn/api_docs.md delete mode 100644 docs/zh-cn/api_overview.md delete mode 100644 docs/zh-cn/cli.md delete mode 100644 docs/zh-cn/cli_commands.md delete mode 100644 docs/zh-cn/cli_configuration.md delete mode 100644 docs/zh-cn/cli_tab_complete.md delete mode 100644 docs/zh-cn/configurator_architecture.md delete mode 100644 docs/zh-cn/configurator_default_keymaps.md delete mode 100644 docs/zh-cn/configurator_step_by_step.md delete mode 100644 docs/zh-cn/configurator_troubleshooting.md delete mode 100644 docs/zh-cn/contributing.md delete mode 100644 docs/zh-cn/custom_quantum_functions.md delete mode 100644 docs/zh-cn/driver_installation_zadig.md delete mode 100644 docs/zh-cn/easy_maker.md delete mode 100644 docs/zh-cn/faq_build.md delete mode 100644 docs/zh-cn/faq_debug.md delete mode 100644 docs/zh-cn/faq_general.md delete mode 100644 docs/zh-cn/faq_keymap.md delete mode 100644 docs/zh-cn/faq_misc.md delete mode 100644 docs/zh-cn/feature_grave_esc.md delete mode 100644 docs/zh-cn/feature_space_cadet.md delete mode 100644 docs/zh-cn/flashing.md delete mode 100644 docs/zh-cn/flashing_bootloadhid.md delete mode 100644 docs/zh-cn/getting_started_docker.md delete mode 100644 docs/zh-cn/getting_started_github.md delete mode 100644 docs/zh-cn/getting_started_introduction.md delete mode 100644 docs/zh-cn/hand_wire.md delete mode 100644 docs/zh-cn/keymap.md delete mode 100644 docs/zh-cn/mod_tap.md delete mode 100644 docs/zh-cn/newbs.md delete mode 100644 docs/zh-cn/newbs_building_firmware.md delete mode 100644 docs/zh-cn/newbs_building_firmware_configurator.md delete mode 100644 docs/zh-cn/newbs_flashing.md delete mode 100644 docs/zh-cn/newbs_getting_started.md delete mode 100644 docs/zh-cn/newbs_git_best_practices.md delete mode 100644 docs/zh-cn/newbs_git_resolving_merge_conflicts.md delete mode 100644 docs/zh-cn/newbs_git_resynchronize_a_branch.md delete mode 100644 docs/zh-cn/newbs_git_using_your_master_branch.md delete mode 100644 docs/zh-cn/newbs_learn_more_resources.md delete mode 100644 docs/zh-cn/newbs_testing_debugging.md delete mode 100644 docs/zh-cn/other_eclipse.md delete mode 100644 docs/zh-cn/other_vscode.md delete mode 100644 docs/zh-cn/reference_configurator_support.md delete mode 100644 docs/zh-cn/reference_glossary.md delete mode 100644 docs/zh-cn/support.md delete mode 100644 docs/zh-cn/syllabus.md delete mode 100644 docs/zh-cn/translating.md delete mode 100644 docs/zh-cn/zh_cn_doc_status.sh create mode 100644 lib/python/qmk/docs.py diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index a00e6616a6..25311019c6 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -7,20 +7,26 @@ on: push: branches: - master + - vitepress paths: + - 'builddefs/docsgen/**' - 'tmk_core/**' - 'quantum/**' - 'platforms/**' - 'docs/**' - '.github/workflows/docs.yml' +defaults: + run: + shell: bash + jobs: generate: runs-on: ubuntu-latest container: ghcr.io/qmk/qmk_cli # protect against those who develop with their fork on master - if: github.repository == 'qmk/qmk_firmware' + if: github.repository == 'qmk/qmk_firmware' || (github.repository == 'tzarc/qmk_firmware' && github.ref == 'refs/heads/vitepress') steps: - uses: actions/checkout@v4 @@ -29,18 +35,51 @@ jobs: - name: Install dependencies run: | - apt-get update && apt-get install -y rsync nodejs npm doxygen + apt-get update && apt-get install -y rsync doxygen curl + # install nvm + touch $HOME/.bashrc + curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash + + - name: Install node + run: | + source $HOME/.bashrc + nvm install 20 + nvm use 20 + corepack enable npm install -g moxygen - name: Build docs run: | + source $HOME/.bashrc + nvm use 20 qmk --verbose generate-docs + touch '.build/docs/.nojekyll' + + - name: Set CNAME + if: github.repository == 'qmk/qmk_firmware' + run: | + # Override target CNAME + echo 'docs.qmk.fm' > .build/docs/CNAME + + - name: Override CNAME + if: github.repository == 'tzarc/qmk_firmware' + run: | + # Temporarily override target CNAME during development + echo 'vitepress.qmk.fm' > .build/docs/CNAME - name: Deploy + if: github.repository == 'qmk/qmk_firmware' uses: JamesIves/github-pages-deploy-action@v4.6.1 with: - GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} - BASE_BRANCH: master - BRANCH: gh-pages - FOLDER: .build/docs - GIT_CONFIG_EMAIL: hello@qmk.fm + token: ${{ secrets.GITHUB_TOKEN }} + branch: gh-pages + folder: .build/docs + git-config-name: QMK Bot + git-config-email: hello@qmk.fm + + - name: Deploy + if: github.repository == 'tzarc/qmk_firmware' + uses: JamesIves/github-pages-deploy-action@v4.6.1 + with: + branch: gh-pages + folder: .build/docs diff --git a/Doxyfile b/Doxyfile index 4b0ea3f086..42f2e70c0e 100644 --- a/Doxyfile +++ b/Doxyfile @@ -21,7 +21,7 @@ DOXYFILE_ENCODING = UTF-8 PROJECT_NAME = "QMK Firmware" PROJECT_NUMBER = https://github.com/qmk/qmk_firmware PROJECT_BRIEF = "Keyboard controller firmware for Atmel AVR and ARM USB families" -OUTPUT_DIRECTORY = .build/doxygen +OUTPUT_DIRECTORY = .build/docs/static/doxygen ALLOW_UNICODE_NAMES = NO OUTPUT_LANGUAGE = English BRIEF_MEMBER_DESC = YES @@ -40,8 +40,8 @@ ABBREVIATE_BRIEF = "The $name class" \ ALWAYS_DETAILED_SEC = NO INLINE_INHERITED_MEMB = NO FULL_PATH_NAMES = YES -STRIP_FROM_PATH = -STRIP_FROM_INC_PATH = +STRIP_FROM_PATH = +STRIP_FROM_INC_PATH = SHORT_NAMES = NO JAVADOC_AUTOBRIEF = NO QT_AUTOBRIEF = NO @@ -49,13 +49,13 @@ MULTILINE_CPP_IS_BRIEF = NO INHERIT_DOCS = YES SEPARATE_MEMBER_PAGES = NO TAB_SIZE = 4 -ALIASES = -TCL_SUBST = +ALIASES = +TCL_SUBST = OPTIMIZE_OUTPUT_FOR_C = YES OPTIMIZE_OUTPUT_JAVA = NO OPTIMIZE_FOR_FORTRAN = NO OPTIMIZE_OUTPUT_VHDL = NO -EXTENSION_MAPPING = +EXTENSION_MAPPING = MARKDOWN_SUPPORT = YES TOC_INCLUDE_HEADINGS = 2 AUTOLINK_SUPPORT = YES @@ -104,14 +104,14 @@ GENERATE_TODOLIST = YES GENERATE_TESTLIST = YES GENERATE_BUGLIST = YES GENERATE_DEPRECATEDLIST= YES -ENABLED_SECTIONS = +ENABLED_SECTIONS = MAX_INITIALIZER_LINES = 30 SHOW_USED_FILES = YES SHOW_FILES = YES SHOW_NAMESPACES = YES -FILE_VERSION_FILTER = -LAYOUT_FILE = -CITE_BIB_FILES = +FILE_VERSION_FILTER = +LAYOUT_FILE = +CITE_BIB_FILES = #--------------------------------------------------------------------------- # Configuration options related to warning and progress messages @@ -124,7 +124,7 @@ WARN_IF_DOC_ERROR = YES WARN_NO_PARAMDOC = NO WARN_AS_ERROR = NO WARN_FORMAT = "$file:$line: $text" -WARN_LOGFILE = +WARN_LOGFILE = #--------------------------------------------------------------------------- # Configuration options related to the input files @@ -143,19 +143,19 @@ FILE_PATTERNS = *.c \ *.hpp \ *.h++ RECURSIVE = YES -EXCLUDE = +EXCLUDE = EXCLUDE_SYMLINKS = NO EXCLUDE_PATTERNS = */protocol/arm_atsam/* -EXCLUDE_SYMBOLS = -EXAMPLE_PATH = +EXCLUDE_SYMBOLS = +EXAMPLE_PATH = EXAMPLE_PATTERNS = * EXAMPLE_RECURSIVE = NO -IMAGE_PATH = -INPUT_FILTER = -FILTER_PATTERNS = +IMAGE_PATH = +INPUT_FILTER = +FILTER_PATTERNS = FILTER_SOURCE_FILES = NO -FILTER_SOURCE_PATTERNS = -USE_MDFILE_AS_MAINPAGE = +FILTER_SOURCE_PATTERNS = +USE_MDFILE_AS_MAINPAGE = #--------------------------------------------------------------------------- # Configuration options related to source browsing @@ -177,7 +177,7 @@ VERBATIM_HEADERS = YES ALPHABETICAL_INDEX = YES COLS_IN_ALPHA_INDEX = 5 -IGNORE_PREFIX = +IGNORE_PREFIX = #--------------------------------------------------------------------------- # Configuration options related to disabled outputs @@ -207,18 +207,18 @@ ENABLE_PREPROCESSING = YES MACRO_EXPANSION = NO EXPAND_ONLY_PREDEF = NO SEARCH_INCLUDES = YES -INCLUDE_PATH = -INCLUDE_FILE_PATTERNS = +INCLUDE_PATH = +INCLUDE_FILE_PATTERNS = PREDEFINED = __DOXYGEN__ PROGMEM -EXPAND_AS_DEFINED = +EXPAND_AS_DEFINED = SKIP_FUNCTION_MACROS = YES #--------------------------------------------------------------------------- # Configuration options related to external references #--------------------------------------------------------------------------- -TAGFILES = -GENERATE_TAGFILE = +TAGFILES = +GENERATE_TAGFILE = ALLEXTERNALS = NO EXTERNAL_GROUPS = YES EXTERNAL_PAGES = YES @@ -229,14 +229,14 @@ PERL_PATH = /usr/bin/perl #--------------------------------------------------------------------------- CLASS_DIAGRAMS = YES -MSCGEN_PATH = -DIA_PATH = +MSCGEN_PATH = +DIA_PATH = HIDE_UNDOC_RELATIONS = YES HAVE_DOT = NO DOT_NUM_THREADS = 0 DOT_FONTNAME = Helvetica DOT_FONTSIZE = 10 -DOT_FONTPATH = +DOT_FONTPATH = CLASS_GRAPH = YES COLLABORATION_GRAPH = YES GROUP_GRAPHS = YES @@ -251,13 +251,13 @@ GRAPHICAL_HIERARCHY = YES DIRECTORY_GRAPH = YES DOT_IMAGE_FORMAT = png INTERACTIVE_SVG = NO -DOT_PATH = -DOTFILE_DIRS = -MSCFILE_DIRS = -DIAFILE_DIRS = -PLANTUML_JAR_PATH = -PLANTUML_CFG_FILE = -PLANTUML_INCLUDE_PATH = +DOT_PATH = +DOTFILE_DIRS = +MSCFILE_DIRS = +DIAFILE_DIRS = +PLANTUML_JAR_PATH = +PLANTUML_CFG_FILE = +PLANTUML_INCLUDE_PATH = DOT_GRAPH_MAX_NODES = 50 MAX_DOT_GRAPH_DEPTH = 0 DOT_TRANSPARENT = NO diff --git a/builddefs/docsgen/.gitignore b/builddefs/docsgen/.gitignore new file mode 100644 index 0000000000..e71427cba3 --- /dev/null +++ b/builddefs/docsgen/.gitignore @@ -0,0 +1,5 @@ +node_modules +.vitepress/cache +.vitepress/.temp +.vitepress/dist +docs diff --git a/builddefs/docsgen/.vitepress/config.mts b/builddefs/docsgen/.vitepress/config.mts new file mode 100644 index 0000000000..f2111eeb7c --- /dev/null +++ b/builddefs/docsgen/.vitepress/config.mts @@ -0,0 +1,51 @@ +import { defineConfig } from "vitepress"; +import { tabsMarkdownPlugin } from "vitepress-plugin-tabs"; +import sidebar from "../../../docs/_sidebar.json"; + +// https://vitepress.dev/reference/site-config +export default defineConfig(({ mode }) => { + const prod = mode === "production"; + return { + title: "QMK Firmware", + description: "Documentation for QMK Firmware", + + srcDir: prod ? "docs" : "../../docs", + outDir: "../../.build/docs", + cleanUrls: true, + + markdown: { + config(md) { + md.use(tabsMarkdownPlugin); + }, + }, + + vite: { + resolve: { + preserveSymlinks: true, + }, + }, + + themeConfig: { + // https://vitepress.dev/reference/default-theme-config + logo: { + light: "/badge-community-light.svg", + dark: "/badge-community-dark.svg", + }, + siteTitle: false, + + nav: [{ text: "Home", link: "./" }], + + search: { + provider: "local", + }, + + sidebar: sidebar, + + socialLinks: [ + { icon: { svg: '' }, link: "https://reddit.com/r/olkb" }, + { icon: "discord", link: "https://discord.gg/qmk" }, + { icon: "github", link: "https://github.com/qmk/qmk_firmware" }, + ], + } + }; +}); diff --git a/builddefs/docsgen/.vitepress/theme/QMKLayout.vue b/builddefs/docsgen/.vitepress/theme/QMKLayout.vue new file mode 100644 index 0000000000..30d0780d7c --- /dev/null +++ b/builddefs/docsgen/.vitepress/theme/QMKLayout.vue @@ -0,0 +1,18 @@ + + + diff --git a/builddefs/docsgen/.vitepress/theme/custom.css b/builddefs/docsgen/.vitepress/theme/custom.css new file mode 100644 index 0000000000..646d215c1f --- /dev/null +++ b/builddefs/docsgen/.vitepress/theme/custom.css @@ -0,0 +1,19 @@ +/* Override as vitepress doesn't put them with borders */ +kbd { + border: 1px solid var(--vp-c-text-1); + border-radius: 0.6em; + margin: 0.2em; + padding: 0.2em; +} + +:root { + --vp-nav-logo-height: 100%; +} + +.logo { + padding-bottom: 0.2em; +} + +.VPNavBarTitle.has-sidebar .title { + border-bottom: 0; +} diff --git a/builddefs/docsgen/.vitepress/theme/index.ts b/builddefs/docsgen/.vitepress/theme/index.ts new file mode 100644 index 0000000000..3c820ec5ab --- /dev/null +++ b/builddefs/docsgen/.vitepress/theme/index.ts @@ -0,0 +1,13 @@ +import type { Theme } from 'vitepress' +import DefaultTheme from 'vitepress/theme' +import { enhanceAppWithTabs } from 'vitepress-plugin-tabs/client' +import QMKLayout from './QMKLayout.vue' +import './custom.css' + +export default { + extends: DefaultTheme, + Layout: QMKLayout, + enhanceApp({ app }) { + enhanceAppWithTabs(app) + } +} satisfies Theme diff --git a/builddefs/docsgen/build-docs.sh b/builddefs/docsgen/build-docs.sh new file mode 100755 index 0000000000..2ea884752f --- /dev/null +++ b/builddefs/docsgen/build-docs.sh @@ -0,0 +1,6 @@ +#!/usr/bin/env bash + +cd "$(dirname "$(realpath "${BASH_SOURCE[0]}")")" +yarn install +[[ -e docs ]] || ln -sf ../../docs docs +DEBUG='vitepress:*,vite:*' yarn run docs:build diff --git a/builddefs/docsgen/package.json b/builddefs/docsgen/package.json new file mode 100644 index 0000000000..435e7481f1 --- /dev/null +++ b/builddefs/docsgen/package.json @@ -0,0 +1,14 @@ +{ + "license": "GPL-2.0-or-later", + "devDependencies": { + "vite": "^5.2.10", + "vitepress": "^1.1.0", + "vitepress-plugin-tabs": "^0.5.0", + "vue": "^3.4.24" + }, + "scripts": { + "docs:dev": "vitepress dev --host 0.0.0.0", + "docs:build": "vitepress build", + "docs:preview": "vitepress preview --host 0.0.0.0" + } +} diff --git a/builddefs/docsgen/start-docs.sh b/builddefs/docsgen/start-docs.sh new file mode 100755 index 0000000000..e6e044c6a1 --- /dev/null +++ b/builddefs/docsgen/start-docs.sh @@ -0,0 +1,5 @@ +#!/usr/bin/env bash + +cd "$(dirname "$(realpath "${BASH_SOURCE[0]}")")" +yarn install +DEBUG='vitepress:*,vite:*' yarn run docs:dev diff --git a/builddefs/docsgen/yarn.lock b/builddefs/docsgen/yarn.lock new file mode 100644 index 0000000000..b40c1298d0 --- /dev/null +++ b/builddefs/docsgen/yarn.lock @@ -0,0 +1,797 @@ +# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT THIS FILE DIRECTLY. +# yarn lockfile v1 + + +"@algolia/autocomplete-core@1.9.3": + version "1.9.3" + resolved "https://registry.yarnpkg.com/@algolia/autocomplete-core/-/autocomplete-core-1.9.3.tgz#1d56482a768c33aae0868c8533049e02e8961be7" + integrity sha512-009HdfugtGCdC4JdXUbVJClA0q0zh24yyePn+KUGk3rP7j8FEe/m5Yo/z65gn6nP/cM39PxpzqKrL7A6fP6PPw== + dependencies: + "@algolia/autocomplete-plugin-algolia-insights" "1.9.3" + "@algolia/autocomplete-shared" "1.9.3" + +"@algolia/autocomplete-plugin-algolia-insights@1.9.3": + version "1.9.3" + resolved "https://registry.yarnpkg.com/@algolia/autocomplete-plugin-algolia-insights/-/autocomplete-plugin-algolia-insights-1.9.3.tgz#9b7f8641052c8ead6d66c1623d444cbe19dde587" + integrity sha512-a/yTUkcO/Vyy+JffmAnTWbr4/90cLzw+CC3bRbhnULr/EM0fGNvM13oQQ14f2moLMcVDyAx/leczLlAOovhSZg== + dependencies: + "@algolia/autocomplete-shared" "1.9.3" + +"@algolia/autocomplete-preset-algolia@1.9.3": + version "1.9.3" + resolved "https://registry.yarnpkg.com/@algolia/autocomplete-preset-algolia/-/autocomplete-preset-algolia-1.9.3.tgz#64cca4a4304cfcad2cf730e83067e0c1b2f485da" + integrity sha512-d4qlt6YmrLMYy95n5TB52wtNDr6EgAIPH81dvvvW8UmuWRgxEtY0NJiPwl/h95JtG2vmRM804M0DSwMCNZlzRA== + dependencies: + "@algolia/autocomplete-shared" "1.9.3" + +"@algolia/autocomplete-shared@1.9.3": + version "1.9.3" + resolved "https://registry.yarnpkg.com/@algolia/autocomplete-shared/-/autocomplete-shared-1.9.3.tgz#2e22e830d36f0a9cf2c0ccd3c7f6d59435b77dfa" + integrity sha512-Wnm9E4Ye6Rl6sTTqjoymD+l8DjSTHsHboVRYrKgEt8Q7UHm9nYbqhN/i0fhUYA3OAEH7WA8x3jfpnmJm3rKvaQ== + +"@algolia/cache-browser-local-storage@4.23.3": + version "4.23.3" + resolved "https://registry.yarnpkg.com/@algolia/cache-browser-local-storage/-/cache-browser-local-storage-4.23.3.tgz#0cc26b96085e1115dac5fcb9d826651ba57faabc" + integrity sha512-vRHXYCpPlTDE7i6UOy2xE03zHF2C8MEFjPN2v7fRbqVpcOvAUQK81x3Kc21xyb5aSIpYCjWCZbYZuz8Glyzyyg== + dependencies: + "@algolia/cache-common" "4.23.3" + +"@algolia/cache-common@4.23.3": + version "4.23.3" + resolved "https://registry.yarnpkg.com/@algolia/cache-common/-/cache-common-4.23.3.tgz#3bec79092d512a96c9bfbdeec7cff4ad36367166" + integrity sha512-h9XcNI6lxYStaw32pHpB1TMm0RuxphF+Ik4o7tcQiodEdpKK+wKufY6QXtba7t3k8eseirEMVB83uFFF3Nu54A== + +"@algolia/cache-in-memory@4.23.3": + version "4.23.3" + resolved "https://registry.yarnpkg.com/@algolia/cache-in-memory/-/cache-in-memory-4.23.3.tgz#3945f87cd21ffa2bec23890c85305b6b11192423" + integrity sha512-yvpbuUXg/+0rbcagxNT7un0eo3czx2Uf0y4eiR4z4SD7SiptwYTpbuS0IHxcLHG3lq22ukx1T6Kjtk/rT+mqNg== + dependencies: + "@algolia/cache-common" "4.23.3" + +"@algolia/client-account@4.23.3": + version "4.23.3" + resolved "https://registry.yarnpkg.com/@algolia/client-account/-/client-account-4.23.3.tgz#8751bbf636e6741c95e7c778488dee3ee430ac6f" + integrity sha512-hpa6S5d7iQmretHHF40QGq6hz0anWEHGlULcTIT9tbUssWUriN9AUXIFQ8Ei4w9azD0hc1rUok9/DeQQobhQMA== + dependencies: + "@algolia/client-common" "4.23.3" + "@algolia/client-search" "4.23.3" + "@algolia/transporter" "4.23.3" + +"@algolia/client-analytics@4.23.3": + version "4.23.3" + resolved "https://registry.yarnpkg.com/@algolia/client-analytics/-/client-analytics-4.23.3.tgz#f88710885278fe6fb6964384af59004a5a6f161d" + integrity sha512-LBsEARGS9cj8VkTAVEZphjxTjMVCci+zIIiRhpFun9jGDUlS1XmhCW7CTrnaWeIuCQS/2iPyRqSy1nXPjcBLRA== + dependencies: + "@algolia/client-common" "4.23.3" + "@algolia/client-search" "4.23.3" + "@algolia/requester-common" "4.23.3" + "@algolia/transporter" "4.23.3" + +"@algolia/client-common@4.23.3": + version "4.23.3" + resolved "https://registry.yarnpkg.com/@algolia/client-common/-/client-common-4.23.3.tgz#891116aa0db75055a7ecc107649f7f0965774704" + integrity sha512-l6EiPxdAlg8CYhroqS5ybfIczsGUIAC47slLPOMDeKSVXYG1n0qGiz4RjAHLw2aD0xzh2EXZ7aRguPfz7UKDKw== + dependencies: + "@algolia/requester-common" "4.23.3" + "@algolia/transporter" "4.23.3" + +"@algolia/client-personalization@4.23.3": + version "4.23.3" + resolved "https://registry.yarnpkg.com/@algolia/client-personalization/-/client-personalization-4.23.3.tgz#35fa8e5699b0295fbc400a8eb211dc711e5909db" + integrity sha512-3E3yF3Ocr1tB/xOZiuC3doHQBQ2zu2MPTYZ0d4lpfWads2WTKG7ZzmGnsHmm63RflvDeLK/UVx7j2b3QuwKQ2g== + dependencies: + "@algolia/client-common" "4.23.3" + "@algolia/requester-common" "4.23.3" + "@algolia/transporter" "4.23.3" + +"@algolia/client-search@4.23.3": + version "4.23.3" + resolved "https://registry.yarnpkg.com/@algolia/client-search/-/client-search-4.23.3.tgz#a3486e6af13a231ec4ab43a915a1f318787b937f" + integrity sha512-P4VAKFHqU0wx9O+q29Q8YVuaowaZ5EM77rxfmGnkHUJggh28useXQdopokgwMeYw2XUht49WX5RcTQ40rZIabw== + dependencies: + "@algolia/client-common" "4.23.3" + "@algolia/requester-common" "4.23.3" + "@algolia/transporter" "4.23.3" + +"@algolia/logger-common@4.23.3": + version "4.23.3" + resolved "https://registry.yarnpkg.com/@algolia/logger-common/-/logger-common-4.23.3.tgz#35c6d833cbf41e853a4f36ba37c6e5864920bfe9" + integrity sha512-y9kBtmJwiZ9ZZ+1Ek66P0M68mHQzKRxkW5kAAXYN/rdzgDN0d2COsViEFufxJ0pb45K4FRcfC7+33YB4BLrZ+g== + +"@algolia/logger-console@4.23.3": + version "4.23.3" + resolved "https://registry.yarnpkg.com/@algolia/logger-console/-/logger-console-4.23.3.tgz#30f916781826c4db5f51fcd9a8a264a06e136985" + integrity sha512-8xoiseoWDKuCVnWP8jHthgaeobDLolh00KJAdMe9XPrWPuf1by732jSpgy2BlsLTaT9m32pHI8CRfrOqQzHv3A== + dependencies: + "@algolia/logger-common" "4.23.3" + +"@algolia/recommend@4.23.3": + version "4.23.3" + resolved "https://registry.yarnpkg.com/@algolia/recommend/-/recommend-4.23.3.tgz#53d4f194d22d9c72dc05f3f7514c5878f87c5890" + integrity sha512-9fK4nXZF0bFkdcLBRDexsnGzVmu4TSYZqxdpgBW2tEyfuSSY54D4qSRkLmNkrrz4YFvdh2GM1gA8vSsnZPR73w== + dependencies: + "@algolia/cache-browser-local-storage" "4.23.3" + "@algolia/cache-common" "4.23.3" + "@algolia/cache-in-memory" "4.23.3" + "@algolia/client-common" "4.23.3" + "@algolia/client-search" "4.23.3" + "@algolia/logger-common" "4.23.3" + "@algolia/logger-console" "4.23.3" + "@algolia/requester-browser-xhr" "4.23.3" + "@algolia/requester-common" "4.23.3" + "@algolia/requester-node-http" "4.23.3" + "@algolia/transporter" "4.23.3" + +"@algolia/requester-browser-xhr@4.23.3": + version "4.23.3" + resolved "https://registry.yarnpkg.com/@algolia/requester-browser-xhr/-/requester-browser-xhr-4.23.3.tgz#9e47e76f60d540acc8b27b4ebc7a80d1b41938b9" + integrity sha512-jDWGIQ96BhXbmONAQsasIpTYWslyjkiGu0Quydjlowe+ciqySpiDUrJHERIRfELE5+wFc7hc1Q5hqjGoV7yghw== + dependencies: + "@algolia/requester-common" "4.23.3" + +"@algolia/requester-common@4.23.3": + version "4.23.3" + resolved "https://registry.yarnpkg.com/@algolia/requester-common/-/requester-common-4.23.3.tgz#7dbae896e41adfaaf1d1fa5f317f83a99afb04b3" + integrity sha512-xloIdr/bedtYEGcXCiF2muajyvRhwop4cMZo+K2qzNht0CMzlRkm8YsDdj5IaBhshqfgmBb3rTg4sL4/PpvLYw== + +"@algolia/requester-node-http@4.23.3": + version "4.23.3" + resolved "https://registry.yarnpkg.com/@algolia/requester-node-http/-/requester-node-http-4.23.3.tgz#c9f94a5cb96a15f48cea338ab6ef16bbd0ff989f" + integrity sha512-zgu++8Uj03IWDEJM3fuNl34s746JnZOWn1Uz5taV1dFyJhVM/kTNw9Ik7YJWiUNHJQXcaD8IXD1eCb0nq/aByA== + dependencies: + "@algolia/requester-common" "4.23.3" + +"@algolia/transporter@4.23.3": + version "4.23.3" + resolved "https://registry.yarnpkg.com/@algolia/transporter/-/transporter-4.23.3.tgz#545b045b67db3850ddf0bbecbc6c84ff1f3398b7" + integrity sha512-Wjl5gttqnf/gQKJA+dafnD0Y6Yw97yvfY8R9h0dQltX1GXTgNs1zWgvtWW0tHl1EgMdhAyw189uWiZMnL3QebQ== + dependencies: + "@algolia/cache-common" "4.23.3" + "@algolia/logger-common" "4.23.3" + "@algolia/requester-common" "4.23.3" + +"@babel/parser@^7.24.4": + version "7.24.4" + resolved "https://registry.yarnpkg.com/@babel/parser/-/parser-7.24.4.tgz#234487a110d89ad5a3ed4a8a566c36b9453e8c88" + integrity sha512-zTvEBcghmeBma9QIGunWevvBAp4/Qu9Bdq+2k0Ot4fVMD6v3dsC9WOcRSKk7tRRyBM/53yKMJko9xOatGQAwSg== + +"@docsearch/css@3.6.0", "@docsearch/css@^3.6.0": + version "3.6.0" + resolved "https://registry.yarnpkg.com/@docsearch/css/-/css-3.6.0.tgz#0e9f56f704b3a34d044d15fd9962ebc1536ba4fb" + integrity sha512-+sbxb71sWre+PwDK7X2T8+bhS6clcVMLwBPznX45Qu6opJcgRjAp7gYSDzVFp187J+feSj5dNBN1mJoi6ckkUQ== + +"@docsearch/js@^3.6.0": + version "3.6.0" + resolved "https://registry.yarnpkg.com/@docsearch/js/-/js-3.6.0.tgz#f9e46943449b9092d874944f7a80bcc071004cfb" + integrity sha512-QujhqINEElrkIfKwyyyTfbsfMAYCkylInLYMRqHy7PHc8xTBQCow73tlo/Kc7oIwBrCLf0P3YhjlOeV4v8hevQ== + dependencies: + "@docsearch/react" "3.6.0" + preact "^10.0.0" + +"@docsearch/react@3.6.0": + version "3.6.0" + resolved "https://registry.yarnpkg.com/@docsearch/react/-/react-3.6.0.tgz#b4f25228ecb7fc473741aefac592121e86dd2958" + integrity sha512-HUFut4ztcVNmqy9gp/wxNbC7pTOHhgVVkHVGCACTuLhUKUhKAF9KYHJtMiLUJxEqiFLQiuri1fWF8zqwM/cu1w== + dependencies: + "@algolia/autocomplete-core" "1.9.3" + "@algolia/autocomplete-preset-algolia" "1.9.3" + "@docsearch/css" "3.6.0" + algoliasearch "^4.19.1" + +"@esbuild/aix-ppc64@0.20.2": + version "0.20.2" + resolved "https://registry.yarnpkg.com/@esbuild/aix-ppc64/-/aix-ppc64-0.20.2.tgz#a70f4ac11c6a1dfc18b8bbb13284155d933b9537" + integrity sha512-D+EBOJHXdNZcLJRBkhENNG8Wji2kgc9AZ9KiPr1JuZjsNtyHzrsfLRrY0tk2H2aoFu6RANO1y1iPPUCDYWkb5g== + +"@esbuild/android-arm64@0.20.2": + version "0.20.2" + resolved "https://registry.yarnpkg.com/@esbuild/android-arm64/-/android-arm64-0.20.2.tgz#db1c9202a5bc92ea04c7b6840f1bbe09ebf9e6b9" + integrity sha512-mRzjLacRtl/tWU0SvD8lUEwb61yP9cqQo6noDZP/O8VkwafSYwZ4yWy24kan8jE/IMERpYncRt2dw438LP3Xmg== + +"@esbuild/android-arm@0.20.2": + version "0.20.2" + resolved "https://registry.yarnpkg.com/@esbuild/android-arm/-/android-arm-0.20.2.tgz#3b488c49aee9d491c2c8f98a909b785870d6e995" + integrity sha512-t98Ra6pw2VaDhqNWO2Oph2LXbz/EJcnLmKLGBJwEwXX/JAN83Fym1rU8l0JUWK6HkIbWONCSSatf4sf2NBRx/w== + +"@esbuild/android-x64@0.20.2": + version "0.20.2" + resolved "https://registry.yarnpkg.com/@esbuild/android-x64/-/android-x64-0.20.2.tgz#3b1628029e5576249d2b2d766696e50768449f98" + integrity sha512-btzExgV+/lMGDDa194CcUQm53ncxzeBrWJcncOBxuC6ndBkKxnHdFJn86mCIgTELsooUmwUm9FkhSp5HYu00Rg== + +"@esbuild/darwin-arm64@0.20.2": + version "0.20.2" + resolved "https://registry.yarnpkg.com/@esbuild/darwin-arm64/-/darwin-arm64-0.20.2.tgz#6e8517a045ddd86ae30c6608c8475ebc0c4000bb" + integrity sha512-4J6IRT+10J3aJH3l1yzEg9y3wkTDgDk7TSDFX+wKFiWjqWp/iCfLIYzGyasx9l0SAFPT1HwSCR+0w/h1ES/MjA== + +"@esbuild/darwin-x64@0.20.2": + version "0.20.2" + resolved "https://registry.yarnpkg.com/@esbuild/darwin-x64/-/darwin-x64-0.20.2.tgz#90ed098e1f9dd8a9381695b207e1cff45540a0d0" + integrity sha512-tBcXp9KNphnNH0dfhv8KYkZhjc+H3XBkF5DKtswJblV7KlT9EI2+jeA8DgBjp908WEuYll6pF+UStUCfEpdysA== + +"@esbuild/freebsd-arm64@0.20.2": + version "0.20.2" + resolved "https://registry.yarnpkg.com/@esbuild/freebsd-arm64/-/freebsd-arm64-0.20.2.tgz#d71502d1ee89a1130327e890364666c760a2a911" + integrity sha512-d3qI41G4SuLiCGCFGUrKsSeTXyWG6yem1KcGZVS+3FYlYhtNoNgYrWcvkOoaqMhwXSMrZRl69ArHsGJ9mYdbbw== + +"@esbuild/freebsd-x64@0.20.2": + version "0.20.2" + resolved "https://registry.yarnpkg.com/@esbuild/freebsd-x64/-/freebsd-x64-0.20.2.tgz#aa5ea58d9c1dd9af688b8b6f63ef0d3d60cea53c" + integrity sha512-d+DipyvHRuqEeM5zDivKV1KuXn9WeRX6vqSqIDgwIfPQtwMP4jaDsQsDncjTDDsExT4lR/91OLjRo8bmC1e+Cw== + +"@esbuild/linux-arm64@0.20.2": + version "0.20.2" + resolved "https://registry.yarnpkg.com/@esbuild/linux-arm64/-/linux-arm64-0.20.2.tgz#055b63725df678379b0f6db9d0fa85463755b2e5" + integrity sha512-9pb6rBjGvTFNira2FLIWqDk/uaf42sSyLE8j1rnUpuzsODBq7FvpwHYZxQ/It/8b+QOS1RYfqgGFNLRI+qlq2A== + +"@esbuild/linux-arm@0.20.2": + version "0.20.2" + resolved "https://registry.yarnpkg.com/@esbuild/linux-arm/-/linux-arm-0.20.2.tgz#76b3b98cb1f87936fbc37f073efabad49dcd889c" + integrity sha512-VhLPeR8HTMPccbuWWcEUD1Az68TqaTYyj6nfE4QByZIQEQVWBB8vup8PpR7y1QHL3CpcF6xd5WVBU/+SBEvGTg== + +"@esbuild/linux-ia32@0.20.2": + version "0.20.2" + resolved "https://registry.yarnpkg.com/@esbuild/linux-ia32/-/linux-ia32-0.20.2.tgz#c0e5e787c285264e5dfc7a79f04b8b4eefdad7fa" + integrity sha512-o10utieEkNPFDZFQm9CoP7Tvb33UutoJqg3qKf1PWVeeJhJw0Q347PxMvBgVVFgouYLGIhFYG0UGdBumROyiig== + +"@esbuild/linux-loong64@0.20.2": + version "0.20.2" + resolved "https://registry.yarnpkg.com/@esbuild/linux-loong64/-/linux-loong64-0.20.2.tgz#a6184e62bd7cdc63e0c0448b83801001653219c5" + integrity sha512-PR7sp6R/UC4CFVomVINKJ80pMFlfDfMQMYynX7t1tNTeivQ6XdX5r2XovMmha/VjR1YN/HgHWsVcTRIMkymrgQ== + +"@esbuild/linux-mips64el@0.20.2": + version "0.20.2" + resolved "https://registry.yarnpkg.com/@esbuild/linux-mips64el/-/linux-mips64el-0.20.2.tgz#d08e39ce86f45ef8fc88549d29c62b8acf5649aa" + integrity sha512-4BlTqeutE/KnOiTG5Y6Sb/Hw6hsBOZapOVF6njAESHInhlQAghVVZL1ZpIctBOoTFbQyGW+LsVYZ8lSSB3wkjA== + +"@esbuild/linux-ppc64@0.20.2": + version "0.20.2" + resolved "https://registry.yarnpkg.com/@esbuild/linux-ppc64/-/linux-ppc64-0.20.2.tgz#8d252f0b7756ffd6d1cbde5ea67ff8fd20437f20" + integrity sha512-rD3KsaDprDcfajSKdn25ooz5J5/fWBylaaXkuotBDGnMnDP1Uv5DLAN/45qfnf3JDYyJv/ytGHQaziHUdyzaAg== + +"@esbuild/linux-riscv64@0.20.2": + version "0.20.2" + resolved "https://registry.yarnpkg.com/@esbuild/linux-riscv64/-/linux-riscv64-0.20.2.tgz#19f6dcdb14409dae607f66ca1181dd4e9db81300" + integrity sha512-snwmBKacKmwTMmhLlz/3aH1Q9T8v45bKYGE3j26TsaOVtjIag4wLfWSiZykXzXuE1kbCE+zJRmwp+ZbIHinnVg== + +"@esbuild/linux-s390x@0.20.2": + version "0.20.2" + resolved "https://registry.yarnpkg.com/@esbuild/linux-s390x/-/linux-s390x-0.20.2.tgz#3c830c90f1a5d7dd1473d5595ea4ebb920988685" + integrity sha512-wcWISOobRWNm3cezm5HOZcYz1sKoHLd8VL1dl309DiixxVFoFe/o8HnwuIwn6sXre88Nwj+VwZUvJf4AFxkyrQ== + +"@esbuild/linux-x64@0.20.2": + version "0.20.2" + resolved "https://registry.yarnpkg.com/@esbuild/linux-x64/-/linux-x64-0.20.2.tgz#86eca35203afc0d9de0694c64ec0ab0a378f6fff" + integrity sha512-1MdwI6OOTsfQfek8sLwgyjOXAu+wKhLEoaOLTjbijk6E2WONYpH9ZU2mNtR+lZ2B4uwr+usqGuVfFT9tMtGvGw== + +"@esbuild/netbsd-x64@0.20.2": + version "0.20.2" + resolved "https://registry.yarnpkg.com/@esbuild/netbsd-x64/-/netbsd-x64-0.20.2.tgz#e771c8eb0e0f6e1877ffd4220036b98aed5915e6" + integrity sha512-K8/DhBxcVQkzYc43yJXDSyjlFeHQJBiowJ0uVL6Tor3jGQfSGHNNJcWxNbOI8v5k82prYqzPuwkzHt3J1T1iZQ== + +"@esbuild/openbsd-x64@0.20.2": + version "0.20.2" + resolved "https://registry.yarnpkg.com/@esbuild/openbsd-x64/-/openbsd-x64-0.20.2.tgz#9a795ae4b4e37e674f0f4d716f3e226dd7c39baf" + integrity sha512-eMpKlV0SThJmmJgiVyN9jTPJ2VBPquf6Kt/nAoo6DgHAoN57K15ZghiHaMvqjCye/uU4X5u3YSMgVBI1h3vKrQ== + +"@esbuild/sunos-x64@0.20.2": + version "0.20.2" + resolved "https://registry.yarnpkg.com/@esbuild/sunos-x64/-/sunos-x64-0.20.2.tgz#7df23b61a497b8ac189def6e25a95673caedb03f" + integrity sha512-2UyFtRC6cXLyejf/YEld4Hajo7UHILetzE1vsRcGL3earZEW77JxrFjH4Ez2qaTiEfMgAXxfAZCm1fvM/G/o8w== + +"@esbuild/win32-arm64@0.20.2": + version "0.20.2" + resolved "https://registry.yarnpkg.com/@esbuild/win32-arm64/-/win32-arm64-0.20.2.tgz#f1ae5abf9ca052ae11c1bc806fb4c0f519bacf90" + integrity sha512-GRibxoawM9ZCnDxnP3usoUDO9vUkpAxIIZ6GQI+IlVmr5kP3zUq+l17xELTHMWTWzjxa2guPNyrpq1GWmPvcGQ== + +"@esbuild/win32-ia32@0.20.2": + version "0.20.2" + resolved "https://registry.yarnpkg.com/@esbuild/win32-ia32/-/win32-ia32-0.20.2.tgz#241fe62c34d8e8461cd708277813e1d0ba55ce23" + integrity sha512-HfLOfn9YWmkSKRQqovpnITazdtquEW8/SoHW7pWpuEeguaZI4QnCRW6b+oZTztdBnZOS2hqJ6im/D5cPzBTTlQ== + +"@esbuild/win32-x64@0.20.2": + version "0.20.2" + resolved "https://registry.yarnpkg.com/@esbuild/win32-x64/-/win32-x64-0.20.2.tgz#9c907b21e30a52db959ba4f80bb01a0cc403d5cc" + integrity sha512-N49X4lJX27+l9jbLKSqZ6bKNjzQvHaT8IIFUy+YIqmXQdjYCToGWwOItDrfby14c78aDd5NHQl29xingXfCdLQ== + +"@jridgewell/sourcemap-codec@^1.4.15": + version "1.4.15" + resolved "https://registry.yarnpkg.com/@jridgewell/sourcemap-codec/-/sourcemap-codec-1.4.15.tgz#d7c6e6755c78567a951e04ab52ef0fd26de59f32" + integrity sha512-eF2rxCRulEKXHTRiDrDy6erMYWqNw4LPdQ8UQA4huuxaQsVeRPFl2oM8oDGxMFhJUWZf9McpLtJasDDZb/Bpeg== + +"@rollup/rollup-android-arm-eabi@4.16.4": + version "4.16.4" + resolved "https://registry.yarnpkg.com/@rollup/rollup-android-arm-eabi/-/rollup-android-arm-eabi-4.16.4.tgz#5e8930291f1e5ead7fb1171d53ba5c87718de062" + integrity sha512-GkhjAaQ8oUTOKE4g4gsZ0u8K/IHU1+2WQSgS1TwTcYvL+sjbaQjNHFXbOJ6kgqGHIO1DfUhI/Sphi9GkRT9K+Q== + +"@rollup/rollup-android-arm64@4.16.4": + version "4.16.4" + resolved "https://registry.yarnpkg.com/@rollup/rollup-android-arm64/-/rollup-android-arm64-4.16.4.tgz#ffb84f1359c04ec8a022a97110e18a5600f5f638" + integrity sha512-Bvm6D+NPbGMQOcxvS1zUl8H7DWlywSXsphAeOnVeiZLQ+0J6Is8T7SrjGTH29KtYkiY9vld8ZnpV3G2EPbom+w== + +"@rollup/rollup-darwin-arm64@4.16.4": + version "4.16.4" + resolved "https://registry.yarnpkg.com/@rollup/rollup-darwin-arm64/-/rollup-darwin-arm64-4.16.4.tgz#b2fcee8d4806a0b1b9185ac038cc428ddedce9f4" + integrity sha512-i5d64MlnYBO9EkCOGe5vPR/EeDwjnKOGGdd7zKFhU5y8haKhQZTN2DgVtpODDMxUr4t2K90wTUJg7ilgND6bXw== + +"@rollup/rollup-darwin-x64@4.16.4": + version "4.16.4" + resolved "https://registry.yarnpkg.com/@rollup/rollup-darwin-x64/-/rollup-darwin-x64-4.16.4.tgz#fcb25ccbaa3dd33a6490e9d1c64bab2e0e16b932" + integrity sha512-WZupV1+CdUYehaZqjaFTClJI72fjJEgTXdf4NbW69I9XyvdmztUExBtcI2yIIU6hJtYvtwS6pkTkHJz+k08mAQ== + +"@rollup/rollup-linux-arm-gnueabihf@4.16.4": + version "4.16.4" + resolved "https://registry.yarnpkg.com/@rollup/rollup-linux-arm-gnueabihf/-/rollup-linux-arm-gnueabihf-4.16.4.tgz#40d46bdfe667e5eca31bf40047460e326d2e26bb" + integrity sha512-ADm/xt86JUnmAfA9mBqFcRp//RVRt1ohGOYF6yL+IFCYqOBNwy5lbEK05xTsEoJq+/tJzg8ICUtS82WinJRuIw== + +"@rollup/rollup-linux-arm-musleabihf@4.16.4": + version "4.16.4" + resolved "https://registry.yarnpkg.com/@rollup/rollup-linux-arm-musleabihf/-/rollup-linux-arm-musleabihf-4.16.4.tgz#7741df2448c11c56588b50835dbfe91b1a10b375" + integrity sha512-tJfJaXPiFAG+Jn3cutp7mCs1ePltuAgRqdDZrzb1aeE3TktWWJ+g7xK9SNlaSUFw6IU4QgOxAY4rA+wZUT5Wfg== + +"@rollup/rollup-linux-arm64-gnu@4.16.4": + version "4.16.4" + resolved "https://registry.yarnpkg.com/@rollup/rollup-linux-arm64-gnu/-/rollup-linux-arm64-gnu-4.16.4.tgz#0a23b02d2933e4c4872ad18d879890b6a4a295df" + integrity sha512-7dy1BzQkgYlUTapDTvK997cgi0Orh5Iu7JlZVBy1MBURk7/HSbHkzRnXZa19ozy+wwD8/SlpJnOOckuNZtJR9w== + +"@rollup/rollup-linux-arm64-musl@4.16.4": + version "4.16.4" + resolved "https://registry.yarnpkg.com/@rollup/rollup-linux-arm64-musl/-/rollup-linux-arm64-musl-4.16.4.tgz#e37ef259358aa886cc07d782220a4fb83c1e6970" + integrity sha512-zsFwdUw5XLD1gQe0aoU2HVceI6NEW7q7m05wA46eUAyrkeNYExObfRFQcvA6zw8lfRc5BHtan3tBpo+kqEOxmg== + +"@rollup/rollup-linux-powerpc64le-gnu@4.16.4": + version "4.16.4" + resolved "https://registry.yarnpkg.com/@rollup/rollup-linux-powerpc64le-gnu/-/rollup-linux-powerpc64le-gnu-4.16.4.tgz#8c69218b6de05ee2ba211664a2d2ac1e54e43f94" + integrity sha512-p8C3NnxXooRdNrdv6dBmRTddEapfESEUflpICDNKXpHvTjRRq1J82CbU5G3XfebIZyI3B0s074JHMWD36qOW6w== + +"@rollup/rollup-linux-riscv64-gnu@4.16.4": + version "4.16.4" + resolved "https://registry.yarnpkg.com/@rollup/rollup-linux-riscv64-gnu/-/rollup-linux-riscv64-gnu-4.16.4.tgz#d32727dab8f538d9a4a7c03bcf58c436aecd0139" + integrity sha512-Lh/8ckoar4s4Id2foY7jNgitTOUQczwMWNYi+Mjt0eQ9LKhr6sK477REqQkmy8YHY3Ca3A2JJVdXnfb3Rrwkng== + +"@rollup/rollup-linux-s390x-gnu@4.16.4": + version "4.16.4" + resolved "https://registry.yarnpkg.com/@rollup/rollup-linux-s390x-gnu/-/rollup-linux-s390x-gnu-4.16.4.tgz#d46097246a187d99fc9451fe8393b7155b47c5ec" + integrity sha512-1xwwn9ZCQYuqGmulGsTZoKrrn0z2fAur2ujE60QgyDpHmBbXbxLaQiEvzJWDrscRq43c8DnuHx3QorhMTZgisQ== + +"@rollup/rollup-linux-x64-gnu@4.16.4": + version "4.16.4" + resolved "https://registry.yarnpkg.com/@rollup/rollup-linux-x64-gnu/-/rollup-linux-x64-gnu-4.16.4.tgz#6356c5a03a4afb1c3057490fc51b4764e109dbc7" + integrity sha512-LuOGGKAJ7dfRtxVnO1i3qWc6N9sh0Em/8aZ3CezixSTM+E9Oq3OvTsvC4sm6wWjzpsIlOCnZjdluINKESflJLA== + +"@rollup/rollup-linux-x64-musl@4.16.4": + version "4.16.4" + resolved "https://registry.yarnpkg.com/@rollup/rollup-linux-x64-musl/-/rollup-linux-x64-musl-4.16.4.tgz#03a5831a9c0d05877b94653b5ddd3020d3c6fb06" + integrity sha512-ch86i7KkJKkLybDP2AtySFTRi5fM3KXp0PnHocHuJMdZwu7BuyIKi35BE9guMlmTpwwBTB3ljHj9IQXnTCD0vA== + +"@rollup/rollup-win32-arm64-msvc@4.16.4": + version "4.16.4" + resolved "https://registry.yarnpkg.com/@rollup/rollup-win32-arm64-msvc/-/rollup-win32-arm64-msvc-4.16.4.tgz#6cc0db57750376b9303bdb6f5482af8974fcae35" + integrity sha512-Ma4PwyLfOWZWayfEsNQzTDBVW8PZ6TUUN1uFTBQbF2Chv/+sjenE86lpiEwj2FiviSmSZ4Ap4MaAfl1ciF4aSA== + +"@rollup/rollup-win32-ia32-msvc@4.16.4": + version "4.16.4" + resolved "https://registry.yarnpkg.com/@rollup/rollup-win32-ia32-msvc/-/rollup-win32-ia32-msvc-4.16.4.tgz#aea0b7e492bd9ed46971cb80bc34f1eb14e07789" + integrity sha512-9m/ZDrQsdo/c06uOlP3W9G2ENRVzgzbSXmXHT4hwVaDQhYcRpi9bgBT0FTG9OhESxwK0WjQxYOSfv40cU+T69w== + +"@rollup/rollup-win32-x64-msvc@4.16.4": + version "4.16.4" + resolved "https://registry.yarnpkg.com/@rollup/rollup-win32-x64-msvc/-/rollup-win32-x64-msvc-4.16.4.tgz#c09ad9a132ccb5a67c4f211d909323ab1294f95f" + integrity sha512-YunpoOAyGLDseanENHmbFvQSfVL5BxW3k7hhy0eN4rb3gS/ct75dVD0EXOWIqFT/nE8XYW6LP6vz6ctKRi0k9A== + +"@shikijs/core@1.3.0", "@shikijs/core@^1.3.0": + version "1.3.0" + resolved "https://registry.yarnpkg.com/@shikijs/core/-/core-1.3.0.tgz#5b93b51ddb8def1e3a1543107f9b5b0540f716f6" + integrity sha512-7fedsBfuILDTBmrYZNFI8B6ATTxhQAasUHllHmjvSZPnoq4bULWoTpHwmuQvZ8Aq03/tAa2IGo6RXqWtHdWaCA== + +"@shikijs/transformers@^1.3.0": + version "1.3.0" + resolved "https://registry.yarnpkg.com/@shikijs/transformers/-/transformers-1.3.0.tgz#b03c5733ef61e25e4f53666bf11889f8876f34e9" + integrity sha512-3mlpg2I9CjhjE96dEWQOGeCWoPcyTov3s4aAsHmgvnTHa8MBknEnCQy8/xivJPSpD+olqOqIEoHnLfbNJK29AA== + dependencies: + shiki "1.3.0" + +"@types/estree@1.0.5": + version "1.0.5" + resolved "https://registry.yarnpkg.com/@types/estree/-/estree-1.0.5.tgz#a6ce3e556e00fd9895dd872dd172ad0d4bd687f4" + integrity sha512-/kYRxGDLWzHOB7q+wtSUQlFrtcdUccpfy+X+9iMBpHK8QLLhx2wIPYuS5DYtR9Wa/YlZAbIovy7qVdB1Aq6Lyw== + +"@types/linkify-it@*": + version "3.0.5" + resolved "https://registry.yarnpkg.com/@types/linkify-it/-/linkify-it-3.0.5.tgz#1e78a3ac2428e6d7e6c05c1665c242023a4601d8" + integrity sha512-yg6E+u0/+Zjva+buc3EIb+29XEg4wltq7cSmd4Uc2EE/1nUVmxyzpX6gUXD0V8jIrG0r7YeOGVIbYRkxeooCtw== + +"@types/markdown-it@^14.0.1": + version "14.0.1" + resolved "https://registry.yarnpkg.com/@types/markdown-it/-/markdown-it-14.0.1.tgz#3d3fdf9dba83b69edececc070d39ec72b84270a7" + integrity sha512-6WfOG3jXR78DW8L5cTYCVVGAsIFZskRHCDo5tbqa+qtKVt4oDRVH7hyIWu1SpDQJlmIoEivNQZ5h+AGAOrgOtQ== + dependencies: + "@types/linkify-it" "*" + "@types/mdurl" "*" + +"@types/mdurl@*": + version "1.0.5" + resolved "https://registry.yarnpkg.com/@types/mdurl/-/mdurl-1.0.5.tgz#3e0d2db570e9fb6ccb2dc8fde0be1d79ac810d39" + integrity sha512-6L6VymKTzYSrEf4Nev4Xa1LCHKrlTlYCBMTlQKFuddo1CvQcE52I0mwfOJayueUC7MJuXOeHTcIU683lzd0cUA== + +"@types/web-bluetooth@^0.0.20": + version "0.0.20" + resolved "https://registry.yarnpkg.com/@types/web-bluetooth/-/web-bluetooth-0.0.20.tgz#f066abfcd1cbe66267cdbbf0de010d8a41b41597" + integrity sha512-g9gZnnXVq7gM7v3tJCWV/qw7w+KeOlSHAhgF9RytFyifW6AF61hdT2ucrYhPq9hLs5JIryeupHV3qGk95dH9ow== + +"@vitejs/plugin-vue@^5.0.4": + version "5.0.4" + resolved "https://registry.yarnpkg.com/@vitejs/plugin-vue/-/plugin-vue-5.0.4.tgz#508d6a0f2440f86945835d903fcc0d95d1bb8a37" + integrity sha512-WS3hevEszI6CEVEx28F8RjTX97k3KsrcY6kvTg7+Whm5y3oYvcqzVeGCU3hxSAn4uY2CLCkeokkGKpoctccilQ== + +"@vue/compiler-core@3.4.24": + version "3.4.24" + resolved "https://registry.yarnpkg.com/@vue/compiler-core/-/compiler-core-3.4.24.tgz#6b4a5ffddcd874a692f2acfa68981201bcd7096b" + integrity sha512-vbW/tgbwJYj62N/Ww99x0zhFTkZDTcGh3uwJEuadZ/nF9/xuFMC4693P9r+3sxGXISABpDKvffY5ApH9pmdd1A== + dependencies: + "@babel/parser" "^7.24.4" + "@vue/shared" "3.4.24" + entities "^4.5.0" + estree-walker "^2.0.2" + source-map-js "^1.2.0" + +"@vue/compiler-dom@3.4.24": + version "3.4.24" + resolved "https://registry.yarnpkg.com/@vue/compiler-dom/-/compiler-dom-3.4.24.tgz#b7335a49f095b6d35e48b6f7be8da513c1fa52b8" + integrity sha512-4XgABML/4cNndVsQndG6BbGN7+EoisDwi3oXNovqL/4jdNhwvP8/rfRMTb6FxkxIxUUtg6AI1/qZvwfSjxJiWA== + dependencies: + "@vue/compiler-core" "3.4.24" + "@vue/shared" "3.4.24" + +"@vue/compiler-sfc@3.4.24": + version "3.4.24" + resolved "https://registry.yarnpkg.com/@vue/compiler-sfc/-/compiler-sfc-3.4.24.tgz#2872e353147ce2a145169a33ddd4d68dc95c3a18" + integrity sha512-nRAlJUK02FTWfA2nuvNBAqsDZuERGFgxZ8sGH62XgFSvMxO2URblzulExsmj4gFZ8e+VAyDooU9oAoXfEDNxTA== + dependencies: + "@babel/parser" "^7.24.4" + "@vue/compiler-core" "3.4.24" + "@vue/compiler-dom" "3.4.24" + "@vue/compiler-ssr" "3.4.24" + "@vue/shared" "3.4.24" + estree-walker "^2.0.2" + magic-string "^0.30.10" + postcss "^8.4.38" + source-map-js "^1.2.0" + +"@vue/compiler-ssr@3.4.24": + version "3.4.24" + resolved "https://registry.yarnpkg.com/@vue/compiler-ssr/-/compiler-ssr-3.4.24.tgz#0d11fe54dabd17cbd6393a16bf7f785da1cfab46" + integrity sha512-ZsAtr4fhaUFnVcDqwW3bYCSDwq+9Gk69q2r/7dAHDrOMw41kylaMgOP4zRnn6GIEJkQznKgrMOGPMFnLB52RbQ== + dependencies: + "@vue/compiler-dom" "3.4.24" + "@vue/shared" "3.4.24" + +"@vue/devtools-api@^7.0.27": + version "7.1.2" + resolved "https://registry.yarnpkg.com/@vue/devtools-api/-/devtools-api-7.1.2.tgz#8808b0f008842b756bf1e9c30788837abb62ab3a" + integrity sha512-AKd49cN3BdRgttmX5Aw8op7sx6jmaPwaILcDjaa05UKc1yIHDYST7P8yGZs6zd2pKFETAQz40gmyG7+b57slsQ== + dependencies: + "@vue/devtools-kit" "^7.1.2" + +"@vue/devtools-kit@^7.1.2": + version "7.1.2" + resolved "https://registry.yarnpkg.com/@vue/devtools-kit/-/devtools-kit-7.1.2.tgz#dfb7306edf895dadc556dd5f0c516809c2f94826" + integrity sha512-UTrcUSOhlI9eXqbPMHUWwA6NQiiPT3onzXsVk2JHGR8ZFFSkzsWTTpHyVA1woG8zvgu2HNV/wigW2k87p858zw== + dependencies: + "@vue/devtools-shared" "^7.1.2" + hookable "^5.5.3" + mitt "^3.0.1" + perfect-debounce "^1.0.0" + speakingurl "^14.0.1" + +"@vue/devtools-shared@^7.1.2": + version "7.1.2" + resolved "https://registry.yarnpkg.com/@vue/devtools-shared/-/devtools-shared-7.1.2.tgz#7b1c1de10bab4756f271c377370a62833b4ee94b" + integrity sha512-r9cUf93VMhKSsxF2/cBbf6Lm1nRBx+r1pRuji5CiAf3JIPYPOjeEqJ13OuwP1fauYh1tyBFcCxt3eJPvHT59gg== + dependencies: + rfdc "^1.3.1" + +"@vue/reactivity@3.4.24": + version "3.4.24" + resolved "https://registry.yarnpkg.com/@vue/reactivity/-/reactivity-3.4.24.tgz#150584316ca2acc4ed19a24f9f29863c3a17a7b2" + integrity sha512-nup3fSYg4i4LtNvu9slF/HF/0dkMQYfepUdORBcMSsankzRPzE7ypAFurpwyRBfU1i7Dn1kcwpYsE1wETSh91g== + dependencies: + "@vue/shared" "3.4.24" + +"@vue/runtime-core@3.4.24": + version "3.4.24" + resolved "https://registry.yarnpkg.com/@vue/runtime-core/-/runtime-core-3.4.24.tgz#066c544dc59a07a96c12874a57b750c239124874" + integrity sha512-c7iMfj6cJMeAG3s5yOn9Rc5D9e2/wIuaozmGf/ICGCY3KV5H7mbTVdvEkd4ZshTq7RUZqj2k7LMJWVx+EBiY1g== + dependencies: + "@vue/reactivity" "3.4.24" + "@vue/shared" "3.4.24" + +"@vue/runtime-dom@3.4.24": + version "3.4.24" + resolved "https://registry.yarnpkg.com/@vue/runtime-dom/-/runtime-dom-3.4.24.tgz#4f8e7acbe1e8ffa7c55af1366e4438729ebe9b20" + integrity sha512-uXKzuh/Emfad2Y7Qm0ABsLZZV6H3mAJ5ZVqmAOlrNQRf+T5mxpPGZBfec1hkP41t6h6FwF6RSGCs/gd8WbuySQ== + dependencies: + "@vue/runtime-core" "3.4.24" + "@vue/shared" "3.4.24" + csstype "^3.1.3" + +"@vue/server-renderer@3.4.24": + version "3.4.24" + resolved "https://registry.yarnpkg.com/@vue/server-renderer/-/server-renderer-3.4.24.tgz#80dd546f8d6a9f5c4f8b68083fe9cc2d62299332" + integrity sha512-H+DLK4sQF6sRgzKyofmlEVBIV/9KrQU6HIV7nt6yIwSGGKvSwlV8pqJlebUKLpbXaNHugdSfAbP6YmXF69lxow== + dependencies: + "@vue/compiler-ssr" "3.4.24" + "@vue/shared" "3.4.24" + +"@vue/shared@3.4.24": + version "3.4.24" + resolved "https://registry.yarnpkg.com/@vue/shared/-/shared-3.4.24.tgz#278ac71f492b392b9b17fe8fc7d324db1a8842db" + integrity sha512-BW4tajrJBM9AGAknnyEw5tO2xTmnqgup0VTnDAMcxYmqOX0RG0b9aSUGAbEKolD91tdwpA6oCwbltoJoNzpItw== + +"@vueuse/core@10.9.0", "@vueuse/core@^10.9.0": + version "10.9.0" + resolved "https://registry.yarnpkg.com/@vueuse/core/-/core-10.9.0.tgz#7d779a95cf0189de176fee63cee4ba44b3c85d64" + integrity sha512-/1vjTol8SXnx6xewDEKfS0Ra//ncg4Hb0DaZiwKf7drgfMsKFExQ+FnnENcN6efPen+1kIzhLQoGSy0eDUVOMg== + dependencies: + "@types/web-bluetooth" "^0.0.20" + "@vueuse/metadata" "10.9.0" + "@vueuse/shared" "10.9.0" + vue-demi ">=0.14.7" + +"@vueuse/integrations@^10.9.0": + version "10.9.0" + resolved "https://registry.yarnpkg.com/@vueuse/integrations/-/integrations-10.9.0.tgz#2b1a9556215ad3c1f96d39cbfbef102cf6e0ec05" + integrity sha512-acK+A01AYdWSvL4BZmCoJAcyHJ6EqhmkQEXbQLwev1MY7NBnS+hcEMx/BzVoR9zKI+UqEPMD9u6PsyAuiTRT4Q== + dependencies: + "@vueuse/core" "10.9.0" + "@vueuse/shared" "10.9.0" + vue-demi ">=0.14.7" + +"@vueuse/metadata@10.9.0": + version "10.9.0" + resolved "https://registry.yarnpkg.com/@vueuse/metadata/-/metadata-10.9.0.tgz#769a1a9db65daac15cf98084cbf7819ed3758620" + integrity sha512-iddNbg3yZM0X7qFY2sAotomgdHK7YJ6sKUvQqbvwnf7TmaVPxS4EJydcNsVejNdS8iWCtDk+fYXr7E32nyTnGA== + +"@vueuse/shared@10.9.0": + version "10.9.0" + resolved "https://registry.yarnpkg.com/@vueuse/shared/-/shared-10.9.0.tgz#13af2a348de15d07b7be2fd0c7fc9853a69d8fe0" + integrity sha512-Uud2IWncmAfJvRaFYzv5OHDli+FbOzxiVEQdLCKQKLyhz94PIyFC3CHcH7EDMwIn8NPtD06+PNbC/PiO0LGLtw== + dependencies: + vue-demi ">=0.14.7" + +algoliasearch@^4.19.1: + version "4.23.3" + resolved "https://registry.yarnpkg.com/algoliasearch/-/algoliasearch-4.23.3.tgz#e09011d0a3b0651444916a3e6bbcba064ec44b60" + integrity sha512-Le/3YgNvjW9zxIQMRhUHuhiUjAlKY/zsdZpfq4dlLqg6mEm0nL6yk+7f2hDOtLpxsgE4jSzDmvHL7nXdBp5feg== + dependencies: + "@algolia/cache-browser-local-storage" "4.23.3" + "@algolia/cache-common" "4.23.3" + "@algolia/cache-in-memory" "4.23.3" + "@algolia/client-account" "4.23.3" + "@algolia/client-analytics" "4.23.3" + "@algolia/client-common" "4.23.3" + "@algolia/client-personalization" "4.23.3" + "@algolia/client-search" "4.23.3" + "@algolia/logger-common" "4.23.3" + "@algolia/logger-console" "4.23.3" + "@algolia/recommend" "4.23.3" + "@algolia/requester-browser-xhr" "4.23.3" + "@algolia/requester-common" "4.23.3" + "@algolia/requester-node-http" "4.23.3" + "@algolia/transporter" "4.23.3" + +csstype@^3.1.3: + version "3.1.3" + resolved "https://registry.yarnpkg.com/csstype/-/csstype-3.1.3.tgz#d80ff294d114fb0e6ac500fbf85b60137d7eff81" + integrity sha512-M1uQkMl8rQK/szD0LNhtqxIPLpimGm8sOBwU7lLnCpSbTyY3yeU1Vc7l4KT5zT4s/yOxHH5O7tIuuLOCnLADRw== + +entities@^4.5.0: + version "4.5.0" + resolved "https://registry.yarnpkg.com/entities/-/entities-4.5.0.tgz#5d268ea5e7113ec74c4d033b79ea5a35a488fb48" + integrity sha512-V0hjH4dGPh9Ao5p0MoRY6BVqtwCjhz6vI5LT8AJ55H+4g9/4vbHx1I54fS0XuclLhDHArPQCiMjDxjaL8fPxhw== + +esbuild@^0.20.1: + version "0.20.2" + resolved "https://registry.yarnpkg.com/esbuild/-/esbuild-0.20.2.tgz#9d6b2386561766ee6b5a55196c6d766d28c87ea1" + integrity sha512-WdOOppmUNU+IbZ0PaDiTst80zjnrOkyJNHoKupIcVyU8Lvla3Ugx94VzkQ32Ijqd7UhHJy75gNWDMUekcrSJ6g== + optionalDependencies: + "@esbuild/aix-ppc64" "0.20.2" + "@esbuild/android-arm" "0.20.2" + "@esbuild/android-arm64" "0.20.2" + "@esbuild/android-x64" "0.20.2" + "@esbuild/darwin-arm64" "0.20.2" + "@esbuild/darwin-x64" "0.20.2" + "@esbuild/freebsd-arm64" "0.20.2" + "@esbuild/freebsd-x64" "0.20.2" + "@esbuild/linux-arm" "0.20.2" + "@esbuild/linux-arm64" "0.20.2" + "@esbuild/linux-ia32" "0.20.2" + "@esbuild/linux-loong64" "0.20.2" + "@esbuild/linux-mips64el" "0.20.2" + "@esbuild/linux-ppc64" "0.20.2" + "@esbuild/linux-riscv64" "0.20.2" + "@esbuild/linux-s390x" "0.20.2" + "@esbuild/linux-x64" "0.20.2" + "@esbuild/netbsd-x64" "0.20.2" + "@esbuild/openbsd-x64" "0.20.2" + "@esbuild/sunos-x64" "0.20.2" + "@esbuild/win32-arm64" "0.20.2" + "@esbuild/win32-ia32" "0.20.2" + "@esbuild/win32-x64" "0.20.2" + +estree-walker@^2.0.2: + version "2.0.2" + resolved "https://registry.yarnpkg.com/estree-walker/-/estree-walker-2.0.2.tgz#52f010178c2a4c117a7757cfe942adb7d2da4cac" + integrity sha512-Rfkk/Mp/DL7JVje3u18FxFujQlTNR2q6QfMSMB7AvCBx91NGj/ba3kCfza0f6dVDbw7YlRf/nDrn7pQrCCyQ/w== + +focus-trap@^7.5.4: + version "7.5.4" + resolved "https://registry.yarnpkg.com/focus-trap/-/focus-trap-7.5.4.tgz#6c4e342fe1dae6add9c2aa332a6e7a0bbd495ba2" + integrity sha512-N7kHdlgsO/v+iD/dMoJKtsSqs5Dz/dXZVebRgJw23LDk+jMi/974zyiOYDziY2JPp8xivq9BmUGwIJMiuSBi7w== + dependencies: + tabbable "^6.2.0" + +fsevents@~2.3.2, fsevents@~2.3.3: + version "2.3.3" + resolved "https://registry.yarnpkg.com/fsevents/-/fsevents-2.3.3.tgz#cac6407785d03675a2a5e1a5305c697b347d90d6" + integrity sha512-5xoDfX+fL7faATnagmWPpbFtwh/R77WmMMqqHGS65C3vvB0YHrgF+B1YmZ3441tMj5n63k0212XNoJwzlhffQw== + +hookable@^5.5.3: + version "5.5.3" + resolved "https://registry.yarnpkg.com/hookable/-/hookable-5.5.3.tgz#6cfc358984a1ef991e2518cb9ed4a778bbd3215d" + integrity sha512-Yc+BQe8SvoXH1643Qez1zqLRmbA5rCL+sSmk6TVos0LWVfNIB7PGncdlId77WzLGSIB5KaWgTaNTs2lNVEI6VQ== + +magic-string@^0.30.10: + version "0.30.10" + resolved "https://registry.yarnpkg.com/magic-string/-/magic-string-0.30.10.tgz#123d9c41a0cb5640c892b041d4cfb3bd0aa4b39e" + integrity sha512-iIRwTIf0QKV3UAnYK4PU8uiEc4SRh5jX0mwpIwETPpHdhVM4f53RSwS/vXvN1JhGX+Cs7B8qIq3d6AH49O5fAQ== + dependencies: + "@jridgewell/sourcemap-codec" "^1.4.15" + +mark.js@8.11.1: + version "8.11.1" + resolved "https://registry.yarnpkg.com/mark.js/-/mark.js-8.11.1.tgz#180f1f9ebef8b0e638e4166ad52db879beb2ffc5" + integrity sha512-1I+1qpDt4idfgLQG+BNWmrqku+7/2bi5nLf4YwF8y8zXvmfiTBY3PV3ZibfrjBueCByROpuBjLLFCajqkgYoLQ== + +minisearch@^6.3.0: + version "6.3.0" + resolved "https://registry.yarnpkg.com/minisearch/-/minisearch-6.3.0.tgz#985a2f1ca3c73c2d65af94f0616bfe57164b0b6b" + integrity sha512-ihFnidEeU8iXzcVHy74dhkxh/dn8Dc08ERl0xwoMMGqp4+LvRSCgicb+zGqWthVokQKvCSxITlh3P08OzdTYCQ== + +mitt@^3.0.1: + version "3.0.1" + resolved "https://registry.yarnpkg.com/mitt/-/mitt-3.0.1.tgz#ea36cf0cc30403601ae074c8f77b7092cdab36d1" + integrity sha512-vKivATfr97l2/QBCYAkXYDbrIWPM2IIKEl7YPhjCvKlG3kE2gm+uBo6nEXK3M5/Ffh/FLpKExzOQ3JJoJGFKBw== + +nanoid@^3.3.7: + version "3.3.7" + resolved "https://registry.yarnpkg.com/nanoid/-/nanoid-3.3.7.tgz#d0c301a691bc8d54efa0a2226ccf3fe2fd656bd8" + integrity sha512-eSRppjcPIatRIMC1U6UngP8XFcz8MQWGQdt1MTBQ7NaAmvXDfvNxbvWV3x2y6CdEUciCSsDHDQZbhYaB8QEo2g== + +perfect-debounce@^1.0.0: + version "1.0.0" + resolved "https://registry.yarnpkg.com/perfect-debounce/-/perfect-debounce-1.0.0.tgz#9c2e8bc30b169cc984a58b7d5b28049839591d2a" + integrity sha512-xCy9V055GLEqoFaHoC1SoLIaLmWctgCUaBaWxDZ7/Zx4CTyX7cJQLJOok/orfjZAh9kEYpjJa4d0KcJmCbctZA== + +picocolors@^1.0.0: + version "1.0.0" + resolved "https://registry.yarnpkg.com/picocolors/-/picocolors-1.0.0.tgz#cb5bdc74ff3f51892236eaf79d68bc44564ab81c" + integrity sha512-1fygroTLlHu66zi26VoTDv8yRgm0Fccecssto+MhsZ0D/DGW2sm8E8AjW7NU5VVTRt5GxbeZ5qBuJr+HyLYkjQ== + +postcss@^8.4.38: + version "8.4.38" + resolved "https://registry.yarnpkg.com/postcss/-/postcss-8.4.38.tgz#b387d533baf2054288e337066d81c6bee9db9e0e" + integrity sha512-Wglpdk03BSfXkHoQa3b/oulrotAkwrlLDRSOb9D0bN86FdRyE9lppSp33aHNPgBa0JKCoB+drFLZkQoRRYae5A== + dependencies: + nanoid "^3.3.7" + picocolors "^1.0.0" + source-map-js "^1.2.0" + +preact@^10.0.0: + version "10.20.2" + resolved "https://registry.yarnpkg.com/preact/-/preact-10.20.2.tgz#0b343299a8c020562311cc25db93b3d832ec5e71" + integrity sha512-S1d1ernz3KQ+Y2awUxKakpfOg2CEmJmwOP+6igPx6dgr6pgDvenqYviyokWso2rhHvGtTlWWnJDa7RaPbQerTg== + +rfdc@^1.3.1: + version "1.3.1" + resolved "https://registry.yarnpkg.com/rfdc/-/rfdc-1.3.1.tgz#2b6d4df52dffe8bb346992a10ea9451f24373a8f" + integrity sha512-r5a3l5HzYlIC68TpmYKlxWjmOP6wiPJ1vWv2HeLhNsRZMrCkxeqxiHlQ21oXmQ4F3SiryXBHhAD7JZqvOJjFmg== + +rollup@^4.13.0: + version "4.16.4" + resolved "https://registry.yarnpkg.com/rollup/-/rollup-4.16.4.tgz#fe328eb41293f20c9593a095ec23bdc4b5d93317" + integrity sha512-kuaTJSUbz+Wsb2ATGvEknkI12XV40vIiHmLuFlejoo7HtDok/O5eDDD0UpCVY5bBX5U5RYo8wWP83H7ZsqVEnA== + dependencies: + "@types/estree" "1.0.5" + optionalDependencies: + "@rollup/rollup-android-arm-eabi" "4.16.4" + "@rollup/rollup-android-arm64" "4.16.4" + "@rollup/rollup-darwin-arm64" "4.16.4" + "@rollup/rollup-darwin-x64" "4.16.4" + "@rollup/rollup-linux-arm-gnueabihf" "4.16.4" + "@rollup/rollup-linux-arm-musleabihf" "4.16.4" + "@rollup/rollup-linux-arm64-gnu" "4.16.4" + "@rollup/rollup-linux-arm64-musl" "4.16.4" + "@rollup/rollup-linux-powerpc64le-gnu" "4.16.4" + "@rollup/rollup-linux-riscv64-gnu" "4.16.4" + "@rollup/rollup-linux-s390x-gnu" "4.16.4" + "@rollup/rollup-linux-x64-gnu" "4.16.4" + "@rollup/rollup-linux-x64-musl" "4.16.4" + "@rollup/rollup-win32-arm64-msvc" "4.16.4" + "@rollup/rollup-win32-ia32-msvc" "4.16.4" + "@rollup/rollup-win32-x64-msvc" "4.16.4" + fsevents "~2.3.2" + +shiki@1.3.0, shiki@^1.3.0: + version "1.3.0" + resolved "https://registry.yarnpkg.com/shiki/-/shiki-1.3.0.tgz#3eda35cb49f6f0a98525e9da48fc072e6c655a3f" + integrity sha512-9aNdQy/etMXctnPzsje1h1XIGm9YfRcSksKOGqZWXA/qP9G18/8fpz5Bjpma8bOgz3tqIpjERAd6/lLjFyzoww== + dependencies: + "@shikijs/core" "1.3.0" + +source-map-js@^1.2.0: + version "1.2.0" + resolved "https://registry.yarnpkg.com/source-map-js/-/source-map-js-1.2.0.tgz#16b809c162517b5b8c3e7dcd315a2a5c2612b2af" + integrity sha512-itJW8lvSA0TXEphiRoawsCksnlf8SyvmFzIhltqAHluXd88pkCd+cXJVHTDwdCr0IzwptSm035IHQktUu1QUMg== + +speakingurl@^14.0.1: + version "14.0.1" + resolved "https://registry.yarnpkg.com/speakingurl/-/speakingurl-14.0.1.tgz#f37ec8ddc4ab98e9600c1c9ec324a8c48d772a53" + integrity sha512-1POYv7uv2gXoyGFpBCmpDVSNV74IfsWlDW216UPjbWufNf+bSU6GdbDsxdcxtfwb4xlI3yxzOTKClUosxARYrQ== + +tabbable@^6.2.0: + version "6.2.0" + resolved "https://registry.yarnpkg.com/tabbable/-/tabbable-6.2.0.tgz#732fb62bc0175cfcec257330be187dcfba1f3b97" + integrity sha512-Cat63mxsVJlzYvN51JmVXIgNoUokrIaT2zLclCXjRd8boZ0004U4KCs/sToJ75C6sdlByWxpYnb5Boif1VSFew== + +vite@^5.2.10, vite@^5.2.9: + version "5.2.10" + resolved "https://registry.yarnpkg.com/vite/-/vite-5.2.10.tgz#2ac927c91e99d51b376a5c73c0e4b059705f5bd7" + integrity sha512-PAzgUZbP7msvQvqdSD+ErD5qGnSFiGOoWmV5yAKUEI0kdhjbH6nMWVyZQC/hSc4aXwc0oJ9aEdIiF9Oje0JFCw== + dependencies: + esbuild "^0.20.1" + postcss "^8.4.38" + rollup "^4.13.0" + optionalDependencies: + fsevents "~2.3.3" + +vitepress-plugin-tabs@^0.5.0: + version "0.5.0" + resolved "https://registry.yarnpkg.com/vitepress-plugin-tabs/-/vitepress-plugin-tabs-0.5.0.tgz#2b193a72ed36b9fcd63e3907d3044fe7b6cf3e4e" + integrity sha512-SIhFWwGsUkTByfc2b279ray/E0Jt8vDTsM1LiHxmCOBAEMmvzIBZSuYYT1DpdDTiS3SuJieBheJkYnwCq/yD9A== + +vitepress@^1.1.0: + version "1.1.3" + resolved "https://registry.yarnpkg.com/vitepress/-/vitepress-1.1.3.tgz#ded22392f5274680aaba8bb81dd4fb1c4741c02e" + integrity sha512-hGrIYN0w9IHWs0NQSnlMjKV/v/HLfD+Ywv5QdvCSkiT32mpNOOwUrZjnqZv/JL/WBPpUc94eghTUvmipxw0xrA== + dependencies: + "@docsearch/css" "^3.6.0" + "@docsearch/js" "^3.6.0" + "@shikijs/core" "^1.3.0" + "@shikijs/transformers" "^1.3.0" + "@types/markdown-it" "^14.0.1" + "@vitejs/plugin-vue" "^5.0.4" + "@vue/devtools-api" "^7.0.27" + "@vueuse/core" "^10.9.0" + "@vueuse/integrations" "^10.9.0" + focus-trap "^7.5.4" + mark.js "8.11.1" + minisearch "^6.3.0" + shiki "^1.3.0" + vite "^5.2.9" + vue "^3.4.23" + +vue-demi@>=0.14.7: + version "0.14.7" + resolved "https://registry.yarnpkg.com/vue-demi/-/vue-demi-0.14.7.tgz#8317536b3ef74c5b09f268f7782e70194567d8f2" + integrity sha512-EOG8KXDQNwkJILkx/gPcoL/7vH+hORoBaKgGe+6W7VFMvCYJfmF2dGbvgDroVnI8LU7/kTu8mbjRZGBU1z9NTA== + +vue@^3.4.23, vue@^3.4.24: + version "3.4.24" + resolved "https://registry.yarnpkg.com/vue/-/vue-3.4.24.tgz#f269549939a6c092480f018aa0bd886ba64f4c6f" + integrity sha512-NPdx7dLGyHmKHGRRU5bMRYVE+rechR+KDU5R2tSTNG36PuMwbfAJ+amEvOAw7BPfZp5sQulNELSLm5YUkau+Sg== + dependencies: + "@vue/compiler-dom" "3.4.24" + "@vue/compiler-sfc" "3.4.24" + "@vue/runtime-dom" "3.4.24" + "@vue/server-renderer" "3.4.24" + "@vue/shared" "3.4.24" diff --git a/docs/.nojekyll b/docs/.nojekyll deleted file mode 100644 index e69de29bb2..0000000000 diff --git a/docs/CNAME b/docs/CNAME deleted file mode 100644 index e089843e0b..0000000000 --- a/docs/CNAME +++ /dev/null @@ -1 +0,0 @@ -docs.qmk.fm \ No newline at end of file diff --git a/docs/ChangeLog/20190830.md b/docs/ChangeLog/20190830.md index 298ec958c5..d6895216e9 100644 --- a/docs/ChangeLog/20190830.md +++ b/docs/ChangeLog/20190830.md @@ -20,7 +20,7 @@ This document marks the inaugural Breaking Change merge. A list of changes follo * `fn_actions` is deprecated, and its functionality has been superseded by direct keycodes and `process_record_user()` * The end result of removing this obsolete feature should result in a decent reduction in firmware size and code complexity -* All keymaps affected are recommended to switch away from `fn_actions` in favour of the [custom keycode](https://docs.qmk.fm/#/custom_quantum_functions) and [macro](https://docs.qmk.fm/#/feature_macros) features +* All keymaps affected are recommended to switch away from `fn_actions` in favour of the [custom keycode](../custom_quantum_functions) and [macro](../feature_macros) features ## Update Atreus to current code conventions @@ -43,7 +43,7 @@ This document marks the inaugural Breaking Change merge. A list of changes follo * `fn_actions` is deprecated, and its functionality has been superseded by direct keycodes and `process_record_user()` * All keymaps using these actions have had the relevant `KC_FN*` keys replaced with the equivalent `BL_*` keys -* If you currently use `KC_FN*` you will need to replace `fn_actions` with the [custom keycode](https://docs.qmk.fm/#/custom_quantum_functions) and [macro](https://docs.qmk.fm/#/feature_macros) features +* If you currently use `KC_FN*` you will need to replace `fn_actions` with the [custom keycode](../custom_quantum_functions) and [macro](../feature_macros) features ## Remove `KC_DELT` alias in favor of `KC_DEL` diff --git a/docs/ChangeLog/20200229.md b/docs/ChangeLog/20200229.md index 398fe01c0d..02bca3e371 100644 --- a/docs/ChangeLog/20200229.md +++ b/docs/ChangeLog/20200229.md @@ -51,7 +51,7 @@ Four times a year QMK runs a process for merging Breaking Changes. A Breaking Ch * `fn_actions` is deprecated, and its functionality has been superseded by direct keycodes and `process_record_user()` * The end result of removing this obsolete feature should result in a decent reduction in firmware size and code complexity -* All keymaps affected are recommended to switch away from `fn_actions` in favour of the [custom keycode](https://docs.qmk.fm/#/custom_quantum_functions) and [macro](https://docs.qmk.fm/#/feature_macros) features +* All keymaps affected are recommended to switch away from `fn_actions` in favour of the [custom keycode](../custom_quantum_functions) and [macro](../feature_macros) features ## Moving backlight keycode handling to `process_keycode/` diff --git a/docs/ChangeLog/20200829.md b/docs/ChangeLog/20200829.md index c6abed5b30..66957211f8 100644 --- a/docs/ChangeLog/20200829.md +++ b/docs/ChangeLog/20200829.md @@ -3,9 +3,9 @@ Four times a year QMK runs a process for merging Breaking Changes. A Breaking Change is any change which modifies how QMK behaves in a way that is incompatible or potentially dangerous. We limit these changes to 4 times per year so that users can have confidence that updating their QMK tree will not break their keymaps. -## Changes Requiring User Action :id=changes-requiring-user-action +## Changes Requiring User Action {#changes-requiring-user-action} -### Relocated Keyboards :id=relocated-keyboards +### Relocated Keyboards {#relocated-keyboards} #### The Key Company project consolidation ([#9547](https://github.com/qmk/qmk_firmware/pull/9547)) #### relocating boards by flehrad to flehrad/ folder ([#9635](https://github.com/qmk/qmk_firmware/pull/9635)) @@ -24,7 +24,7 @@ handwired/numbrero | flehrad/numbrero snagpad | flehrad/snagpad handwired/tradestation | flehrad/tradestation -### Updated Keyboard Codebases :id=keyboard-updates +### Updated Keyboard Codebases {#keyboard-updates} #### Keebio RGB wiring update ([#7754](https://github.com/qmk/qmk_firmware/pull/7754)) @@ -46,7 +46,7 @@ This change affects: * Quefrency rev1 * Viterbi, revs. 1 and 2 -### Changes to Core Functionality :id=core-updates +### Changes to Core Functionality {#core-updates} * Bigger Combo index ([#9318](https://github.com/qmk/qmk_firmware/pull/9318)) @@ -58,14 +58,14 @@ Any fork that uses `process_combo_event` needs to update the function's first ar * New function: `void process_combo_event(uint16_t combo_index, bool pressed)` -## Core Changes :id=core-changes +## Core Changes {#core-changes} -### Fixes :id=core-fixes +### Fixes {#core-fixes} * Mousekeys: scrolling acceleration is no longer coupled to mouse movement acceleration ([#9174](https://github.com/qmk/qmk_firmware/pull/9174)) * Keymap Extras: correctly assign Question Mark in Czech layout ([#9987](https://github.com/qmk/qmk_firmware/pull/9987)) -### Additions and Enhancements :id=core-additions +### Additions and Enhancements {#core-additions} * allow for WS2812 PWM to work on DMAMUX-capable devices ([#9471](https://github.com/qmk/qmk_firmware/pull/9471)) * Newer STM32 MCUs have a DMAMUX peripheral, which allows mapping of DMAs to different DMA streams, rather than hard-defining the target streams in silicon. @@ -109,7 +109,7 @@ Any fork that uses `process_combo_event` needs to update the function's first ar * The K-Type has been refactored to use QMK's native matrix scanning routine, and now has partial support for the RGB Matrix feature. * Joysticks can now be used without defining analog pins ([#10169](https://github.com/qmk/qmk_firmware/pull/10169)) -### Clean-ups and Optimizations :id=core-optimizations +### Clean-ups and Optimizations {#core-optimizations} * iWRAP protocol removed ([#9284](https://github.com/qmk/qmk_firmware/pull/9284)) * work begun for consolidation of ChibiOS platform files ([#8327](https://github.com/qmk/qmk_firmware/pull/8327) and [#9315](https://github.com/qmk/qmk_firmware/pull/9315)) @@ -140,7 +140,7 @@ Any fork that uses `process_combo_event` needs to update the function's first ar * remove support for Adafruit EZ Key Bluetooth controller ([#10103](https://github.com/qmk/qmk_firmware/pull/10103)) -## QMK Infrastructure and Internals :id=qmk-internals +## QMK Infrastructure and Internals {#qmk-internals} * Attempt to fix CI for non-master branches. ([#9308](https://github.com/qmk/qmk_firmware/pull/9308)) * Actually fetch the branch we're attempting to compare against. diff --git a/docs/ChangeLog/20201128.md b/docs/ChangeLog/20201128.md index 4441320295..d005d3b56b 100644 --- a/docs/ChangeLog/20201128.md +++ b/docs/ChangeLog/20201128.md @@ -3,9 +3,9 @@ Four times a year QMK runs a process for merging Breaking Changes. A Breaking Change is any change which modifies how QMK behaves in a way that is incompatible or potentially dangerous. We limit these changes to 4 times per year so that users can have confidence that updating their QMK tree will not break their keymaps. -## Changes Requiring User Action :id=changes-requiring-user-action +## Changes Requiring User Action {#changes-requiring-user-action} -### Relocated Keyboards :id=relocated-keyboards +### Relocated Keyboards {#relocated-keyboards} #### Reduce Helix keyboard build variation ([#8669](https://github.com/qmk/qmk_firmware/pull/8669)) @@ -88,21 +88,21 @@ The Valor and Dawn60 keyboards by Xelus22 both now require their revisions to be | xelus/valor | xelus/valor/rev1 | -### Updated Keyboard Codebases :id=keyboard-updates +### Updated Keyboard Codebases {#keyboard-updates} #### AEboards EXT65 Refactor ([#10820](https://github.com/qmk/qmk_firmware/pull/10820)) The EXT65 codebase has been reworked so keymaps can be used with either revision. -## Core Changes :id=core-changes +## Core Changes {#core-changes} -### Fixes :id=core-fixes +### Fixes {#core-fixes} * Reconnect the USB if users wake up a computer from the keyboard to restore the USB state ([#10088](https://github.com/qmk/qmk_firmware/pull/10088)) * Fix cursor position bug in oled_write_raw functions ([#10800](https://github.com/qmk/qmk_firmware/pull/10800)) -### Additions and Enhancements :id=core-additions +### Additions and Enhancements {#core-additions} * Allow MATRIX_ROWS to be greater than 32 ([#10183](https://github.com/qmk/qmk_firmware/pull/10183)) * Add support for soft serial to ATmega32U2 ([#10204](https://github.com/qmk/qmk_firmware/pull/10204)) @@ -119,7 +119,7 @@ The EXT65 codebase has been reworked so keymaps can be used with either revision * Add AT90USB support for serial.c ([#10706](https://github.com/qmk/qmk_firmware/pull/10706)) * Auto shift: support repeats and early registration (#9826) -### Clean-ups and Optimizations :id=core-optimizations +### Clean-ups and Optimizations {#core-optimizations} * Haptic and solenoid cleanup ([#9700](https://github.com/qmk/qmk_firmware/pull/9700)) * XD75 cleanup ([#10524](https://github.com/qmk/qmk_firmware/pull/10524)) @@ -129,7 +129,7 @@ The EXT65 codebase has been reworked so keymaps can be used with either revision * Remove references to HD44780 ([#10735](https://github.com/qmk/qmk_firmware/pull/10735)) -## QMK Infrastructure and Internals :id=qmk-internals +## QMK Infrastructure and Internals {#qmk-internals} * Add ability to build a subset of all keyboards based on platform. ([#10420](https://github.com/qmk/qmk_firmware/pull/10420)) * Initialise EEPROM drivers at startup, instead of upon first execution ([#10438](https://github.com/qmk/qmk_firmware/pull/10438)) diff --git a/docs/ChangeLog/20210529.md b/docs/ChangeLog/20210529.md index 2feeed6437..69923b0c5a 100644 --- a/docs/ChangeLog/20210529.md +++ b/docs/ChangeLog/20210529.md @@ -1,30 +1,30 @@ # QMK Breaking Changes - 2021 May 29 Changelog -## Notable Changes :id=notable-changes +## Notable Changes {#notable-changes} -### RGB Matrix support for split common ([#11055](https://github.com/qmk/qmk_firmware/pull/11055)) :id=rgb-matrix-split-common +### RGB Matrix support for split common ([#11055](https://github.com/qmk/qmk_firmware/pull/11055)) {#rgb-matrix-split-common} Split boards can now use RGB Matrix without defining a custom matrix. -### Teensy 3.6 support ([#12258](https://github.com/qmk/qmk_firmware/pull/12258)) :id=teensy-3-6-support +### Teensy 3.6 support ([#12258](https://github.com/qmk/qmk_firmware/pull/12258)) {#teensy-3-6-support} Added support for MK66F18 (Teensy 3.6) microcontroller. -### New command: qmk console ([#12828](https://github.com/qmk/qmk_firmware/pull/12828)) :id=new-command-qmk-console +### New command: qmk console ([#12828](https://github.com/qmk/qmk_firmware/pull/12828)) {#new-command-qmk-console} A new `qmk console` command has been added for attaching to your keyboard's console. It operates similiarly to QMK Toolbox by allowing you to connect to one or more keyboard consoles to display debugging messages. -### Improved command: qmk config :id=improve-command-qmk-config +### Improved command: qmk config {#improve-command-qmk-config} We've updated the `qmk config` command to show only the configuration items you have actually set. You can now display (almost) all of the available configuration options, along with their default values, using `qmk config -a`. -### LED Matrix Improvements ([#12509](https://github.com/qmk/qmk_firmware/pull/12509), [#12580](https://github.com/qmk/qmk_firmware/pull/12580), [#12588](https://github.com/qmk/qmk_firmware/pull/12588), [#12633](https://github.com/qmk/qmk_firmware/pull/12633), [#12651](https://github.com/qmk/qmk_firmware/pull/12651), [#12685](https://github.com/qmk/qmk_firmware/pull/12685)) :id=led-matrix-improvements +### LED Matrix Improvements ([#12509](https://github.com/qmk/qmk_firmware/pull/12509), [#12580](https://github.com/qmk/qmk_firmware/pull/12580), [#12588](https://github.com/qmk/qmk_firmware/pull/12588), [#12633](https://github.com/qmk/qmk_firmware/pull/12633), [#12651](https://github.com/qmk/qmk_firmware/pull/12651), [#12685](https://github.com/qmk/qmk_firmware/pull/12685)) {#led-matrix-improvements} LED Matrix has been improved with effects, CIE1931 curves, and a task system. -## Changes Requiring User Action :id=changes-requiring-user-action +## Changes Requiring User Action {#changes-requiring-user-action} -### Updated Keyboard Codebases :id=updated-keyboard-codebases +### Updated Keyboard Codebases {#updated-keyboard-codebases} * Durgod keyboard refactor in preparation for adding additional durgod keyboards ([#11978](https://github.com/qmk/qmk_firmware/pull/11978)) * Updated Function96 with V2 files and removed chconf.h and halconf.h ([#12613](https://github.com/qmk/qmk_firmware/pull/12613)) @@ -52,7 +52,7 @@ The codebase for the [Durgod K320](https://github.com/qmk/qmk_firmware/tree/0.13 Additionally, the `crkbd/rev1/legacy` keyboard has been removed. -### Bootmagic Deprecation and Refactor ([#12172](https://github.com/qmk/qmk_firmware/pull/12172)) :id=bootmagic-deprecation-and-refactor +### Bootmagic Deprecation and Refactor ([#12172](https://github.com/qmk/qmk_firmware/pull/12172)) {#bootmagic-deprecation-and-refactor} QMK has decided to deprecate the full Bootmagic feature and leave Bootmagic Lite as the only remaining option. @@ -68,11 +68,11 @@ This is the current planned roadmap for the behavior of `BOOTMAGIC_ENABLE`: - From 2021 Aug 28, `BOOTMAGIC_ENABLE` must be either `yes`, `lite`, or `no` – setting `BOOTMAGIC_ENABLE = full` will cause compilation to fail. - From 2021 Nov 27, `BOOTMAGIC_ENABLE` must be either `yes` or `no` – setting `BOOTMAGIC_ENABLE = lite` will cause compilation to fail. -### Removal of LAYOUT_kc ([#12160](https://github.com/qmk/qmk_firmware/pull/12160)) :id=removal-of-layout-kc +### Removal of LAYOUT_kc ([#12160](https://github.com/qmk/qmk_firmware/pull/12160)) {#removal-of-layout-kc} We've removed support for `LAYOUT_kc` macros, if your keymap uses one you will need to update it use a regular `LAYOUT` macro. -### Encoder callbacks are now boolean ([#12805](https://github.com/qmk/qmk_firmware/pull/12805), [#12985](https://github.com/qmk/qmk_firmware/pull/12985)) :id=encoder-callback-boolean +### Encoder callbacks are now boolean ([#12805](https://github.com/qmk/qmk_firmware/pull/12805), [#12985](https://github.com/qmk/qmk_firmware/pull/12985)) {#encoder-callback-boolean} To allow for keyboards to override (or not) keymap level code the `encoder_update_kb` function has been changed from `void` to `bool`. You will need to update your function definition to reflect this and ensure that you return a `true` or `false` value. @@ -127,9 +127,9 @@ bool encoder_update_user(uint8_t index, bool clockwise) { } ``` -## Core Changes :id=core-changes +## Core Changes {#core-changes} -### Fixes :id=core-fixes +### Fixes {#core-fixes} * Fix connection issue in split keyboards when slave and OLED display are connected via I2C (fixes #9335) ([#11487](https://github.com/qmk/qmk_firmware/pull/11487)) * Terrazzo: Fix wrong LED Matrix function names ([#12561](https://github.com/qmk/qmk_firmware/pull/12561)) @@ -147,7 +147,7 @@ bool encoder_update_user(uint8_t index, bool clockwise) { * [Keyboard] Fix Terrazzo build failure ([#12977](https://github.com/qmk/qmk_firmware/pull/12977)) * Do not hard set config in CPTC files ([#11864](https://github.com/qmk/qmk_firmware/pull/11864)) -### Additions and Enhancements :id=core-additions +### Additions and Enhancements {#core-additions} * ARM - Refactor SLEEP_LED to support more platforms ([#8403](https://github.com/qmk/qmk_firmware/pull/8403)) * Add ability to toggle One Shot functionality ([#4198](https://github.com/qmk/qmk_firmware/pull/4198)) @@ -193,7 +193,7 @@ bool encoder_update_user(uint8_t index, bool clockwise) { * Backlight: add defines for default level and breathing state ([#12560](https://github.com/qmk/qmk_firmware/pull/12560), [#13024](https://github.com/qmk/qmk_firmware/pull/13024)) * Add dire message about LUFA mass storage bootloader ([#13014](https://github.com/qmk/qmk_firmware/pull/13014)) -### Clean-ups and Optimizations :id=core-optimizations +### Clean-ups and Optimizations {#core-optimizations} * Overhaul bootmagic logic to have single entrypoint ([#8532](https://github.com/qmk/qmk_firmware/pull/8532)) * Refactor of USB code within split_common ([#11890](https://github.com/qmk/qmk_firmware/pull/11890)) @@ -218,7 +218,7 @@ bool encoder_update_user(uint8_t index, bool clockwise) { * Deprecate `send_unicode_hex_string()` ([#12602](https://github.com/qmk/qmk_firmware/pull/12602)) * [Keyboard] Remove redundant legacy and common headers for crkbd ([#13023](https://github.com/qmk/qmk_firmware/pull/13023)) -### QMK Infrastructure and Internals :id=qmk-internals +### QMK Infrastructure and Internals {#qmk-internals} * trivial change to trigger api update ([`b15288fb87`](https://github.com/qmk/qmk_firmware/commit/b15288fb87)) * fix some references to bin/qmk that slipped in ([#12832](https://github.com/qmk/qmk_firmware/pull/12832)) diff --git a/docs/ChangeLog/20210828.md b/docs/ChangeLog/20210828.md index f96283e6ad..f84169cc94 100644 --- a/docs/ChangeLog/20210828.md +++ b/docs/ChangeLog/20210828.md @@ -1,28 +1,28 @@ # QMK Breaking Changes - 2021 August 28 Changelog -## Notable Features :id=notable-features +## Notable Features {#notable-features} -### Combo processing improvements ([#8591](https://github.com/qmk/qmk_firmware/pull/8591)) :id=combo-processing-improvements +### Combo processing improvements ([#8591](https://github.com/qmk/qmk_firmware/pull/8591)) {#combo-processing-improvements} Combo processing has been reordered with respect to keypress handling, allowing for much better compatibility with mod taps. It is also now possible to define combos that have keys overlapping with other combos, triggering only one. For example, a combo of `A`, `B` can coexist with a longer combo of `A`, `B`, `C` -- previous functionality would trigger both combos if all three keys were pressed. -### Key Overrides ([#11422](https://github.com/qmk/qmk_firmware/pull/11422)) :id=key-overrides +### Key Overrides ([#11422](https://github.com/qmk/qmk_firmware/pull/11422)) {#key-overrides} -QMK now has a new feature: [key overrides](https://docs.qmk.fm/#/feature_key_overrides). This feature allows for overriding the output of key combinations involving modifiers. As an example, pressing Shift+2 normally results in an @ on US-ANSI keyboard layouts -- the new key overrides allow for adding similar functionality, but for any modifier + key press. +QMK now has a new feature: [key overrides](../feature_key_overrides). This feature allows for overriding the output of key combinations involving modifiers. As an example, pressing Shift+2 normally results in an @ on US-ANSI keyboard layouts -- the new key overrides allow for adding similar functionality, but for any modifier + key press. To illustrate, it's now possible to use the key overrides feature to translate Shift + Backspace into Delete -- an often-requested example of where this functionality comes in handy. -There's far more to describe that what lives in this changelog, so head over to the [key overrides documentation](https://docs.qmk.fm/#/feature_key_overrides) for more examples and info. +There's far more to describe that what lives in this changelog, so head over to the [key overrides documentation](../feature_key_overrides) for more examples and info. ### Digitizer support ([#12851](https://github.com/qmk/qmk_firmware/pull/12851)) QMK gained the ability to pretend to be a digitizer device -- much like a tablet device. A mouse uses delta-coordinates -- move up, move right -- but a digitizer works with absolute coordinates -- top left, bottom right. -## Changes Requiring User Action :id=changes-requiring-user-action +## Changes Requiring User Action {#changes-requiring-user-action} -### Updated Keyboard Codebases :id=updated-keyboard-codebases +### Updated Keyboard Codebases {#updated-keyboard-codebases} The following keyboards have had their source moved within QMK: @@ -69,7 +69,7 @@ xd84pro | xiudi/xd84pro xd87 | xiudi/xd87 xd96 | xiudi/xd96 -### Bootmagic Full Removal ([#13846](https://github.com/qmk/qmk_firmware/pull/13846)) :id=bootmagic-full-removal +### Bootmagic Full Removal ([#13846](https://github.com/qmk/qmk_firmware/pull/13846)) {#bootmagic-full-removal} As noted during last breaking changes cycle, QMK has decided to deprecate the full Bootmagic feature and leave Bootmagic Lite as the only remaining option. @@ -85,7 +85,7 @@ This is the current roadmap for the behavior of `BOOTMAGIC_ENABLE`: - (now) From 2021 Aug 28, `BOOTMAGIC_ENABLE` must be either `yes`, `lite`, or `no` – setting `BOOTMAGIC_ENABLE = full` will cause compilation to fail. - (next) From 2021 Nov 27, `BOOTMAGIC_ENABLE` must be either `yes` or `no` – setting `BOOTMAGIC_ENABLE = lite` will cause compilation to fail. -### DIP switch callbacks are now boolean ([#13399](https://github.com/qmk/qmk_firmware/pull/13399)) :id=dip-switch-boolean +### DIP switch callbacks are now boolean ([#13399](https://github.com/qmk/qmk_firmware/pull/13399)) {#dip-switch-boolean} To match the encoder change last breaking changes cycle, DIP switch callbacks now return `bool`, too. @@ -149,9 +149,9 @@ bool dip_switch_update_mask_user(uint32_t state) { } ``` -## Notable core changes :id=notable-core +## Notable core changes {#notable-core} -### Split transport improvements :id=split-transport-improvements +### Split transport improvements {#split-transport-improvements} Split keyboards gained a significant amount of improvements during this breaking changes cycle, specifically: @@ -160,9 +160,11 @@ Split keyboards gained a significant amount of improvements during this breaking * Make solo half of split keyboards (more) usable. ([#13523](https://github.com/qmk/qmk_firmware/pull/13523)) -- allows the slave to be disconnected, enabling one-handed use. * Switch split_common to CRC subsystem ([#13418](https://github.com/qmk/qmk_firmware/pull/13418)) -!> If you're updating your split keyboard, you will need to flash both sides of the split with the your firmware. +::: warning +If you're updating your split keyboard, you will need to flash both sides of the split with the your firmware. +::: -### Teensy 4.x support ([#13056](https://github.com/qmk/qmk_firmware/pull/13056), [#13076](https://github.com/qmk/qmk_firmware/pull/13076), [#13077](https://github.com/qmk/qmk_firmware/pull/13077)) :id=teensy-4-x-support +### Teensy 4.x support ([#13056](https://github.com/qmk/qmk_firmware/pull/13056), [#13076](https://github.com/qmk/qmk_firmware/pull/13076), [#13077](https://github.com/qmk/qmk_firmware/pull/13077)) {#teensy-4-x-support} Updated ChibiOS and ChibiOS-Contrib, which brought in support for Teensy 4.x dev boards, running NXP i.MX1062. @@ -243,7 +245,7 @@ We've added dozens of new keys to `info.json` so that you can configure more tha * `usb.force_nkro`, `usb.max_power`, `usb.no_startup_check`, `usb.polling_interval`, `usb.shared_endpoint.keyboard`, `usb.shared_endpoint.mouse`, `usb.suspend_wakeup_delay`, `usb.wait_for` * `qmk.keys_per_scan`, `qmk.tap_keycode_delay`, `qmk.tap_capslock_delay` -### Codebase restructure and cleanup :id=codebase-restructure +### Codebase restructure and cleanup {#codebase-restructure} QMK was originally based on TMK, and has grown in size considerably since its first inception. To keep moving things forward, restructure of some of the core areas of the code is needed to support new concepts and new hardware, and progress is happening along those lines: diff --git a/docs/ChangeLog/20211127.md b/docs/ChangeLog/20211127.md index 0780ab6a44..d810be505a 100644 --- a/docs/ChangeLog/20211127.md +++ b/docs/ChangeLog/20211127.md @@ -1,6 +1,6 @@ # QMK Breaking Changes - 2021 November 27 Changelog -## 2000 keyboards! :id=qmk-2000th-keyboard +## 2000 keyboards! {#qmk-2000th-keyboard} QMK had it's 2000th keyboard submitted during this breaking changes cycle.... and it only _just_ made the cut-off! @@ -11,9 +11,9 @@ QMK had it's 2000th keyboard submitted during this breaking changes cycle.... an From the whole QMK team, a major thankyou to the community for embracing QMK as your preferred keyboard firmware! -## Notable Features :id=notable-features +## Notable Features {#notable-features} -### Expanded Pointing Device support ([#14343](https://github.com/qmk/qmk_firmware/pull/14343)) :id=expanded-pointing-device +### Expanded Pointing Device support ([#14343](https://github.com/qmk/qmk_firmware/pull/14343)) {#expanded-pointing-device} Pointing device support has been reworked and reimplemented to allow for easier integration of new peripherals. @@ -31,9 +31,9 @@ QMK now has core-supplied support for the following pointing device peripherals: | `POINTING_DEVICE_DRIVER = pimoroni_trackball` | Pimoroni Trackball | | `POINTING_DEVICE_DRIVER = pmw3360` | PMW 3360 | -See the new documentation for the [Pointing Device](../feature_pointing_device.md) feature for more information on specific configuration for each driver. +See the new documentation for the [Pointing Device](../feature_pointing_device) feature for more information on specific configuration for each driver. -### Dynamic Tapping Term ([#11036](https://github.com/qmk/qmk_firmware/pull/11036)) :id=dynamic-tapping-term +### Dynamic Tapping Term ([#11036](https://github.com/qmk/qmk_firmware/pull/11036)) {#dynamic-tapping-term} For people who are starting out with tapping keys, or for people who think tapping keys don't "feel right", it's sometimes quite difficult to determine what duration of tapping term to use to make things seem natural. @@ -47,9 +47,9 @@ If you're in this stage of discovery, you can now add `DYNAMIC_TAPPING_TERM_ENAB Coupled with the use of `qmk console` or QMK Toolbox to show console output from your keyboard, you can tweak the tapping term dynamically in order to narrow down what "feels right" to you. Once you're happy, drop in the resulting number into your keymap's `config.h` and you're good to go! -### Macros in JSON keymaps ([#14374](https://github.com/qmk/qmk_firmware/pull/14374)) :id=macros-in-keymap-json +### Macros in JSON keymaps ([#14374](https://github.com/qmk/qmk_firmware/pull/14374)) {#macros-in-keymap-json} -You can now define up to 32 macros in your `keymap.json` file, as used by [QMK Configurator](newbs_building_firmware_configurator.md), and `qmk compile`. You can define these macros in a list under the `macros` keyword, like this: +You can now define up to 32 macros in your `keymap.json` file, as used by [QMK Configurator](../newbs_building_firmware_configurator), and `qmk compile`. You can define these macros in a list under the `macros` keyword, like this: ```json { @@ -83,9 +83,9 @@ You can now define up to 32 macros in your `keymap.json` file, as used by [QMK C In due course, [QMK Configurator](https://config.qmk.fm/) will pick up support for defining these in its UI, but for now the json is the only way to define macros. -## Changes Requiring User Action :id=changes-requiring-user-action +## Changes Requiring User Action {#changes-requiring-user-action} -### Updated Keyboard Codebases :id=updated-keyboard-codebases +### Updated Keyboard Codebases {#updated-keyboard-codebases} The following keyboards have had their source moved within QMK: @@ -104,21 +104,21 @@ The following keyboards have had their source moved within QMK: | signum/3_0/elitec | signum/3_0 | | tgr/jane | tgr/jane/v2 | -### Squeezing space out of AVR ([#15243](https://github.com/qmk/qmk_firmware/pull/15243)) :id=squeezing-space-from-avr +### Squeezing space out of AVR ([#15243](https://github.com/qmk/qmk_firmware/pull/15243)) {#squeezing-space-from-avr} The AVR platform has been problematic for some time, in the sense that it is severely resource-constrained -- this makes life difficult for anyone attempting to add new functionality such as display panels to their keymap code. The illustrious Drashna has contributed some newer documentation on how to attempt to free up some space on AVR-based keyboards that are in short supply. Of course, there are much fewer constraints with ARM chips... ;) -### Require explicit enabling of RGB Matrix modes ([#15018](https://github.com/qmk/qmk_firmware/pull/15018)) :id=explicit-rgb-modes +### Require explicit enabling of RGB Matrix modes ([#15018](https://github.com/qmk/qmk_firmware/pull/15018)) {#explicit-rgb-modes} Related to the previous section -- RGB Matrix modes have now been made to be opt-in, rather than opt-out. As these animations are now opt-in, you may find that your keyboard no longer has all the RGB modes you're expecting -- you may need to configure and recompile your firmware and enable your animations of choice... with any luck they'll still fit in the space available. Most keyboards keep their original functionality, but over time the QMK maintainers have found that removal of animations ends up being the quickest way to free up space... and some keyboards have had animations such as reactive effects disabled by default in order to still fit within the flash space available. -The full list of configurables to turn specific animations back on can be found at on the [RGB Matrix documentation](feature_rgb_matrix.md#rgb-matrix-effects) page. +The full list of configurables to turn specific animations back on can be found at on the [RGB Matrix documentation](../feature_rgb_matrix#rgb-matrix-effects) page. -### OLED task refactoring ([#14864](https://github.com/qmk/qmk_firmware/pull/14864)) :id=oled-task-refactor +### OLED task refactoring ([#14864](https://github.com/qmk/qmk_firmware/pull/14864)) {#oled-task-refactor} OLED display code was traditionally difficult to override in keymaps as they did not follow the standard pattern of `bool *_kb()` deferring to `bool *_user()` functions, allowing signalling to the higher level that processing had already been done. @@ -152,7 +152,7 @@ bool oled_task_kb(void) { } ``` -### Bootmagic Full Removal ([#15002](https://github.com/qmk/qmk_firmware/pull/15002)) :id=bootmagic-full-removal +### Bootmagic Full Removal ([#15002](https://github.com/qmk/qmk_firmware/pull/15002)) {#bootmagic-full-removal} As noted during previous breaking changes cycles, QMK decided to deprecate the full Bootmagic feature and leave Bootmagic Lite as the only remaining option. @@ -170,13 +170,13 @@ This is the historical timeline for the behavior of `BOOTMAGIC_ENABLE`: - (done) From 2021 Aug 28, `BOOTMAGIC_ENABLE` must be either `yes`, `lite`, or `no` – setting `BOOTMAGIC_ENABLE = full` will cause compilation to fail. - (now) From 2021 Nov 27, `BOOTMAGIC_ENABLE` must be either `yes` or `no` – setting `BOOTMAGIC_ENABLE = lite` will cause compilation to fail. -### Remove QWIIC_DRIVERS ([#14174](https://github.com/qmk/qmk_firmware/pull/14174)) :id=remove-qwiic +### Remove QWIIC_DRIVERS ([#14174](https://github.com/qmk/qmk_firmware/pull/14174)) {#remove-qwiic} Due to minimal QWIIC adoption and other options for similar functionality, the QWIIC drivers were removed from QMK. Existing OLED usages have been migrated across to the normal QMK OLED driver instead. -## Notable core changes :id=notable-core +## Notable core changes {#notable-core} -### New MCU Support :id=new-mcu-support +### New MCU Support {#new-mcu-support} QMK firmware picked up support for a handful of new MCU families, potentially making it a bit easier to source components. @@ -187,7 +187,7 @@ QMK firmware is now no longer limited to AVR and ARM - it also picked up support * Westberrytech pr ([#14422](https://github.com/qmk/qmk_firmware/pull/14422)) * Initial pass of F405 support ([#14584](https://github.com/qmk/qmk_firmware/pull/14584)) -### EEPROM Changes :id=eeprom-changes +### EEPROM Changes {#eeprom-changes} There were a few EEPROM-related changes that landed during this breaking changes cycle, most prominently the long-awaited ability for the Drop boards to gain persistent storage. Any users of the Drop CTRL or Drop ALT should update QMK Toolbox as well -- coupled with a QMK firmware update settings should now be saved. @@ -197,7 +197,7 @@ There were a few EEPROM-related changes that landed during this breaking changes * Further tidy up of STM32 eeprom emulation ([#14591](https://github.com/qmk/qmk_firmware/pull/14591)) * Enable eeprom with F401xE ld ([#14752](https://github.com/qmk/qmk_firmware/pull/14752)) -### Compilation Database :id=compile-commands +### Compilation Database {#compile-commands} A clang-compatible compilation database generator has been added as an option in order to help development environments such as Visual Studio Code. @@ -208,7 +208,7 @@ Do note that switching keyboards will require re-generation of this file. * New CLI subcommand to create clang-compatible compilation database (`compile_commands.json`) ([#14370](https://github.com/qmk/qmk_firmware/pull/14370)) * compiledb: query include paths from gcc directly. ([#14462](https://github.com/qmk/qmk_firmware/pull/14462)) -### Codebase restructure and cleanup :id=codebase-restructure +### Codebase restructure and cleanup {#codebase-restructure} QMK continues on its restructuring journey, in order to make it easier to integrate newer features and add support for new hardware. This quarter's batch of changes include: diff --git a/docs/ChangeLog/20220226.md b/docs/ChangeLog/20220226.md index a469612fe8..f0cbbc0603 100644 --- a/docs/ChangeLog/20220226.md +++ b/docs/ChangeLog/20220226.md @@ -1,6 +1,6 @@ # QMK Breaking Changes - 2022 February 26 Changelog -## Notable Features :id=notable-features +## Notable Features {#notable-features} ### Default USB Polling rate now 1kHz ([#15352](https://github.com/qmk/qmk_firmware/pull/15352)) @@ -12,13 +12,13 @@ Something something *Lets go gamers!* Pointing devices can now be shared across a split keyboard with support for a single pointing device or a pointing device on each side. -See the [Pointing Device](feature_pointing_device.md) documentation for further configuration options. +See the [Pointing Device](../feature_pointing_device) documentation for further configuration options. -## Changes Requiring User Action :id=changes-requiring-user-action +## Changes Requiring User Action {#changes-requiring-user-action} ### Legacy macro and action_function system removed ([#16025](https://github.com/qmk/qmk_firmware/pull/16025)) -The long time deprecated `MACRO()` and `action_get_macro` methods have been removed. Where possible, existing usages have been migrated over to core [Macros](feature_macros.md). +The long time deprecated `MACRO()` and `action_get_macro` methods have been removed. Where possible, existing usages have been migrated over to core [Macros](../feature_macros). ### Create a build error if no bootloader is specified ([#16181](https://github.com/qmk/qmk_firmware/pull/16181)) @@ -31,7 +31,7 @@ Bootloader configuration is no longer assumed. Keyboards must now set either: In preparation of future bluetooth work, the `AdafruitBLE` integration has been renamed to allow potential for any other Adafruit BLE products. -### Updated Keyboard Codebases :id=updated-keyboard-codebases +### Updated Keyboard Codebases {#updated-keyboard-codebases} The following keyboards have had their source moved within QMK: @@ -241,9 +241,9 @@ The following keyboards have had their source moved within QMK: | zinc/rev1 | 25keys/zinc/rev1 | | zinc/reva | 25keys/zinc/reva | -## Notable core changes :id=notable-core +## Notable core changes {#notable-core} -### New MCU Support :id=new-mcu-support +### New MCU Support {#new-mcu-support} Building on previous cycles, QMK firmware picked up support for a couple extra MCU variants: diff --git a/docs/ChangeLog/20220528.md b/docs/ChangeLog/20220528.md index 1265c81206..31347c9c00 100644 --- a/docs/ChangeLog/20220528.md +++ b/docs/ChangeLog/20220528.md @@ -1,16 +1,16 @@ # QMK Breaking Changes - 2022 May 28 Changelog -## Notable Features :id=notable-features +## Notable Features {#notable-features} -### Caps Word ([#16588](https://github.com/qmk/qmk_firmware/pull/16588)) :id=caps-word +### Caps Word ([#16588](https://github.com/qmk/qmk_firmware/pull/16588)) {#caps-word} This is a new feature that allows for capslock-like functionality that turns itself off at the end of the word. For instance, if you wish to type "QMK" without holding shift the entire time, you can either tap both left and right shift, or double-tap shift, to turn on _Caps Word_ -- then type `qmk` (lowercase) without holding shift. Once you hit any key other than `a`--`z`, `0`--`9`, `-`, `_`, delete, or backspace, this will go back to normal typing! -There are other activation mechanisms as well as configurable options like timeout and the like -- see the [Caps Word documentation](feature_caps_word.md) for more information. +There are other activation mechanisms as well as configurable options like timeout and the like -- see the [Caps Word documentation](../feature_caps_word) for more information. -### Quantum Painter ([#10174](https://github.com/qmk/qmk_firmware/pull/10174)) :id=quantum-painter +### Quantum Painter ([#10174](https://github.com/qmk/qmk_firmware/pull/10174)) {#quantum-painter} QMK has had support for small OLED displays for some time now, but hasn't really gained too much ability to draw to panels other than the SSD1306 or SH1106 panels. @@ -18,27 +18,31 @@ Quantum Painter is a new drawing subsystem available to suitable ARM and RISC-V The QMK CLI has new commands added to be able to generate images and fonts for Quantum Painter to digest -- it's even capable of converting animated gifs for display on screen. -See the [Quantum Painter documentation](quantum_painter.md) for more information on how to set up the displays as well as how to convert images and fonts. +See the [Quantum Painter documentation](../quantum_painter) for more information on how to set up the displays as well as how to convert images and fonts. -!> Quantum Painter is not supported on AVR due to complexity and size constraints. Boards based on AVR such as ProMicro or Elite-C builds will not be able to leverage Quantum Painter. +::: warning +Quantum Painter is not supported on AVR due to complexity and size constraints. Boards based on AVR such as ProMicro or Elite-C builds will not be able to leverage Quantum Painter. +::: -### Encoder Mapping ([#13286](https://github.com/qmk/qmk_firmware/pull/13286)) :id=encoder-mapping +### Encoder Mapping ([#13286](https://github.com/qmk/qmk_firmware/pull/13286)) {#encoder-mapping} -One of the long-standing complaints with Encoders is that there has been no easy way to configure them in user keymaps. [#13286](https://github.com/qmk/qmk_firmware/pull/13286) added support for [Encoder Mapping](feature_encoders.md#encoder-map), which allows users to define encoder functionality in a similar way to their normal keymap. +One of the long-standing complaints with Encoders is that there has been no easy way to configure them in user keymaps. [#13286](https://github.com/qmk/qmk_firmware/pull/13286) added support for [Encoder Mapping](../feature_encoders#encoder-map), which allows users to define encoder functionality in a similar way to their normal keymap. -!> This is not yet supported by QMK Configurator. It is also unlikely to ever be supported by VIA. +::: warning +This is not yet supported by QMK Configurator. It is also unlikely to ever be supported by VIA. +::: -## Changes Requiring User Action :id=changes-requiring-user-action +## Changes Requiring User Action {#changes-requiring-user-action} -### `RESET` => `QK_BOOT` ([#17037](https://github.com/qmk/qmk_firmware/pull/17037)) :id=reset-2-qk_boot +### `RESET` => `QK_BOOT` ([#17037](https://github.com/qmk/qmk_firmware/pull/17037)) {#reset-2-qk_boot} QMK is always in the process of picking up support for new hardware platforms. One of the side-effects for future integrations has shown that QMK's usage of `RESET` as a keycode is causing naming collisions. As a result, [#17037](https://github.com/qmk/qmk_firmware/pull/17037) changed usages of `RESET` to the new keycode `QK_BOOT` in the majority of default-like keymaps. At this stage the old keycode is still usable but will likely be removed in the next breaking changes cycle. Users with keymaps containing `RESET` should also move to `QK_BOOT`. -### Sendstring keycode overhaul ([#16941](https://github.com/qmk/qmk_firmware/pull/16941)) :id=sendstring-keycodes +### Sendstring keycode overhaul ([#16941](https://github.com/qmk/qmk_firmware/pull/16941)) {#sendstring-keycodes} Some keycodes used with `SEND_STRING` and its relatives have been deprecated and may have their old keycode usages removed at a later date. The list of [deprecated keycodes](https://github.com/qmk/qmk_firmware/blob/ebd402788346aa6e88bde1486b2a835684d40d39/quantum/send_string_keycodes.h#L456-L505) should be consulted to determine if you're using one of the older names (the first identifier after `#define`) -- you should swap to the newer variant (the second identifier on the same line). -### Pillow Installation ([#17133](https://github.com/qmk/qmk_firmware/pull/17133)) :id=pillow-install +### Pillow Installation ([#17133](https://github.com/qmk/qmk_firmware/pull/17133)) {#pillow-install} The merge of Quantum Painter added some new dependencies in the QMK CLI, most notably _Pillow_, which requires some installation in order for the CLI to function. If you've got an existing installation, you'll need to run some commands in order to get things working: @@ -62,7 +66,7 @@ On Linux or WSL: python3 -m pip install --user --upgrade qmk ``` -### Updated Keyboard Codebases :id=updated-keyboard-codebases +### Updated Keyboard Codebases {#updated-keyboard-codebases} The following keyboards have had their source moved within QMK: @@ -97,7 +101,7 @@ The following keyboards have had their source moved within QMK: --- -## Full changelist :id=full-changelist +## Full changelist {#full-changelist} Core: * Quantum Painter ([#10174](https://github.com/qmk/qmk_firmware/pull/10174)) diff --git a/docs/ChangeLog/20220827.md b/docs/ChangeLog/20220827.md index b672b57cb8..d58db91272 100644 --- a/docs/ChangeLog/20220827.md +++ b/docs/ChangeLog/20220827.md @@ -1,28 +1,28 @@ # QMK Breaking Changes - 2022 August 27 Changelog -## Notable Features :id=notable-features +## Notable Features {#notable-features} -### Add Raspberry Pi RP2040 support ([#14877](https://github.com/qmk/qmk_firmware/pull/14877), [#17514](https://github.com/qmk/qmk_firmware/pull/17514), [#17516](https://github.com/qmk/qmk_firmware/pull/17516), [#17519](https://github.com/qmk/qmk_firmware/pull/17519), [#17612](https://github.com/qmk/qmk_firmware/pull/17612), [#17512](https://github.com/qmk/qmk_firmware/pull/17512), [#17557](https://github.com/qmk/qmk_firmware/pull/17557), [#17817](https://github.com/qmk/qmk_firmware/pull/17817), [#17839](https://github.com/qmk/qmk_firmware/pull/17839), [#18100](https://github.com/qmk/qmk_firmware/pull/18100)) :id=rp2040-support +### Add Raspberry Pi RP2040 support ([#14877](https://github.com/qmk/qmk_firmware/pull/14877), [#17514](https://github.com/qmk/qmk_firmware/pull/17514), [#17516](https://github.com/qmk/qmk_firmware/pull/17516), [#17519](https://github.com/qmk/qmk_firmware/pull/17519), [#17612](https://github.com/qmk/qmk_firmware/pull/17612), [#17512](https://github.com/qmk/qmk_firmware/pull/17512), [#17557](https://github.com/qmk/qmk_firmware/pull/17557), [#17817](https://github.com/qmk/qmk_firmware/pull/17817), [#17839](https://github.com/qmk/qmk_firmware/pull/17839), [#18100](https://github.com/qmk/qmk_firmware/pull/18100)) {#rp2040-support} QMK _finally_ picked up support for RP2040-based boards, such as the Raspberry Pi Pico, the Sparkfun Pro Micro RP2040, and the Adafruit KB2040. One of QMK's newest collaborators, _@KarlK90_, effectively did `/micdrop` with RP2040, with a massive set of changes to both QMK and the repository QMK uses for the base platform support, ChibiOS[-Contrib]. There has been a flurry of development this breaking changes cycle related to RP2040 from a large number of contributors -- so much so that almost all standard QMK hardware subsystems are supported. -Check the [RP2040 platform development page](platformdev_rp2040.md) for all supported peripherals and other hardware implementation details. +Check the [RP2040 platform development page](../platformdev_rp2040) for all supported peripherals and other hardware implementation details. -### Allow `qmk flash` to use prebuilt firmware binaries ([#16584](https://github.com/qmk/qmk_firmware/pull/16584)) :id=cli-flash-binaries +### Allow `qmk flash` to use prebuilt firmware binaries ([#16584](https://github.com/qmk/qmk_firmware/pull/16584)) {#cli-flash-binaries} A long-requested capability of the QMK CLI has been the ability to flash binaries directly, without needing to build a firmware. QMK provides prebuilt `develop`-based default firmwares on our [CI page](https://qmk.tzarc.io/) -- normally people would need [QMK Toolbox](https://github.com/qmk/qmk_toolbox/releases/latest) to flash them. This new functionality written by _@Erovia_ allows `qmk flash` to be provided the prebuilt file instead, simplifying the workflow for people who haven't got Toolbox available. -## Changes Requiring User Action :id=changes-requiring-user-action +## Changes Requiring User Action {#changes-requiring-user-action} ### Default layers dropped from 32 to 16 ([#15286](https://github.com/qmk/qmk_firmware/pull/15286)) QMK allows for controlling the maximum number of layers it supports through `LAYER_STATE_(8|16|32)BIT`. Each definition allows for the same number of maximum layers -- `LAYER_STATE_8BIT` => 8 layers. There is also a corresponding firmware size decrease that goes along with smaller numbers -- given the vast majority of users don't use more than 16 layers the default has been swapped to 16. AVR users who were not previously specifying their max layer count may see some space freed up as a result. -### `RESET` => `QK_BOOT` ([#17940](https://github.com/qmk/qmk_firmware/pull/17940)) :id=reset-2-qk_boot +### `RESET` => `QK_BOOT` ([#17940](https://github.com/qmk/qmk_firmware/pull/17940)) {#reset-2-qk_boot} Following the last breaking changes cycle, QMK has been migrating usages of `RESET` to `QK_BOOT` due to naming collisions with our upstream board support packages. [#17940](https://github.com/qmk/qmk_firmware/pull/17940) converts user keymaps across to use the new keycode name. `RESET` should also move to `QK_BOOT`. -### Updated Keyboard Codebases :id=updated-keyboard-codebases +### Updated Keyboard Codebases {#updated-keyboard-codebases} The following keyboards have had their source moved within QMK: @@ -33,7 +33,7 @@ The following keyboards have had their source moved within QMK: | idobao/id80/v1/ansi | idobao/id80/v2/ansi | | idobao/id80/v1/iso | idobao/id80/v2/iso | -### Data-driven USB IDs Refactoring ([#18152](https://github.com/qmk/qmk_firmware/pull/18152)) :id=usb-ids-Refactoring +### Data-driven USB IDs Refactoring ([#18152](https://github.com/qmk/qmk_firmware/pull/18152)) {#usb-ids-Refactoring} QMK has decided to deprecate the specification of USB IDs inside `config.h` in favour of `info.json`, eventually leaving data-driven as the only method to specify USB information. @@ -67,25 +67,25 @@ Replaced by `info.json`: - From 2022 Aug 27, specifying USB information in `config.h` will produce warnings during build but will still function as previously. - From 2022 Nov 26, specifying USB information in `config.h` will cause compilation to fail. -## Notable core changes :id=notable-core +## Notable core changes {#notable-core} -### Board converters ([#17514](https://github.com/qmk/qmk_firmware/pull/17514), [#17603](https://github.com/qmk/qmk_firmware/pull/17603), [#17711](https://github.com/qmk/qmk_firmware/pull/17711), [#17827](https://github.com/qmk/qmk_firmware/pull/17827), [#17593](https://github.com/qmk/qmk_firmware/pull/17593), [#17652](https://github.com/qmk/qmk_firmware/pull/17652), [#17595](https://github.com/qmk/qmk_firmware/pull/17595)) :id=board-converters +### Board converters ([#17514](https://github.com/qmk/qmk_firmware/pull/17514), [#17603](https://github.com/qmk/qmk_firmware/pull/17603), [#17711](https://github.com/qmk/qmk_firmware/pull/17711), [#17827](https://github.com/qmk/qmk_firmware/pull/17827), [#17593](https://github.com/qmk/qmk_firmware/pull/17593), [#17652](https://github.com/qmk/qmk_firmware/pull/17652), [#17595](https://github.com/qmk/qmk_firmware/pull/17595)) {#board-converters} -Historically QMK had a `CONVERT_TO_PROTON_C` directive for `rules.mk` to allow people to replace an AVR-based Pro Micro with a QMK Proton C. Global parts shortages have prompted people to create their own pin-compatible boards -- QMK has made this conversion generic and now allows for drop-in replacements for a lot more boards. see the [Converters Feature](feature_converters.md) documentation for the full list of supported replacement boards -- in this breaking changes cycle we've gone from 1 to 7. +Historically QMK had a `CONVERT_TO_PROTON_C` directive for `rules.mk` to allow people to replace an AVR-based Pro Micro with a QMK Proton C. Global parts shortages have prompted people to create their own pin-compatible boards -- QMK has made this conversion generic and now allows for drop-in replacements for a lot more boards. see the [Converters Feature](../feature_converters) documentation for the full list of supported replacement boards -- in this breaking changes cycle we've gone from 1 to 7. -### Add cli command to import keyboard|keymap|kbfirmware ([#16668](https://github.com/qmk/qmk_firmware/pull/16668)) :id=cli-import +### Add cli command to import keyboard|keymap|kbfirmware ([#16668](https://github.com/qmk/qmk_firmware/pull/16668)) {#cli-import} To help with importing keyboards and keymaps from other sources, _@zvecr_ added [#16668](https://github.com/qmk/qmk_firmware/pull/16668) which adds a new set of commands to the CLI to automatically import keyboards (`qmk import-keyboard -h`), keymaps (`qmk import-keymap -h`), and kbfirmware definitions (`qmk import-kbfirmware -h`) into QMK. The now-EOL kbfirmware allowed people who aren't set up with QMK the ability to create keyboard firmwares without requiring a full installation of QMK. Unfortunately, it targets a 7-year-old version of QMK -- adding frustration for users who want the newest features, as well as for QMK maintainers who have to spend time explaining why QMK can't just accept a drive-by code drop from kbfirmware. With any luck, this new command helps both camps! -### Generic wear-leveling for EEPROM emulation ([#16996](https://github.com/qmk/qmk_firmware/pull/16996), [#17376](https://github.com/qmk/qmk_firmware/pull/17376), [#18102](https://github.com/qmk/qmk_firmware/pull/18102)) :id=wear-leveling +### Generic wear-leveling for EEPROM emulation ([#16996](https://github.com/qmk/qmk_firmware/pull/16996), [#17376](https://github.com/qmk/qmk_firmware/pull/17376), [#18102](https://github.com/qmk/qmk_firmware/pull/18102)) {#wear-leveling} QMK has had the ability to write to internal MCU flash in order to emulate EEPROM for some time now, but it was only limited to a small number of MCUs. The base HAL used by QMK for a large number of ARM devices provides a "proper" embedded MCU flash driver, so _@tzarc_ decoupled the wear-leveling algorithm from the old flash writing code, improved it, wrote some tests, and enabled its use for a much larger number of other devices... including RP2040's XIP flash, and external SPI NOR Flash. -See the [EEPROM Driver](eeprom_driver.md) documentation for more information. +See the [EEPROM Driver](../eeprom_driver) documentation for more information. -### Pointing Device Improvements ([#16371](https://github.com/qmk/qmk_firmware/pull/16371), [#17111](https://github.com/qmk/qmk_firmware/pull/17111), [#17176](https://github.com/qmk/qmk_firmware/pull/17176), [#17482](https://github.com/qmk/qmk_firmware/pull/17482), [#17776](https://github.com/qmk/qmk_firmware/pull/17776), [#17613](https://github.com/qmk/qmk_firmware/pull/17613)) :id=pointing-device-improvements +### Pointing Device Improvements ([#16371](https://github.com/qmk/qmk_firmware/pull/16371), [#17111](https://github.com/qmk/qmk_firmware/pull/17111), [#17176](https://github.com/qmk/qmk_firmware/pull/17176), [#17482](https://github.com/qmk/qmk_firmware/pull/17482), [#17776](https://github.com/qmk/qmk_firmware/pull/17776), [#17613](https://github.com/qmk/qmk_firmware/pull/17613)) {#pointing-device-improvements} Ever since Pointing Device Driver support and Split Pointing Device support were added by _@drashna_ and _@daskygit_, there has been increased interest in the development of the pointing device subsystem and its associated code. @@ -102,7 +102,7 @@ Other related changes: --- -## Full changelist :id=full-changelist +## Full changelist {#full-changelist} Core: * Tentative Teensy 3.5 support ([#14420](https://github.com/qmk/qmk_firmware/pull/14420)) diff --git a/docs/ChangeLog/20221126.md b/docs/ChangeLog/20221126.md index 82aa4a499e..25cf1d592d 100644 --- a/docs/ChangeLog/20221126.md +++ b/docs/ChangeLog/20221126.md @@ -1,14 +1,14 @@ # QMK Breaking Changes - 2022 November 26 Changelog -## Notable Features :id=notable-features +## Notable Features {#notable-features} -### Autocorrect ([#15699](https://github.com/qmk/qmk_firmware/pull/15699)) :id=autocorrect +### Autocorrect ([#15699](https://github.com/qmk/qmk_firmware/pull/15699)) {#autocorrect} -_@getreuer_ in their infinite wisdom decided that autocorrect was a feature needed by QMK. As is customary, _@drashna_ adapted it to core and got it into a state that everyone else can use it. See [Feature: Autocorrect](feature_autocorrect.md) for more ifnormation (grin). +_@getreuer_ in their infinite wisdom decided that autocorrect was a feature needed by QMK. As is customary, _@drashna_ adapted it to core and got it into a state that everyone else can use it. See [Feature: Autocorrect](../feature_autocorrect) for more ifnormation (grin). -## Changes Requiring User Action :id=changes-requiring-user-action +## Changes Requiring User Action {#changes-requiring-user-action} -### Updated Keyboard Codebases :id=updated-keyboard-codebases +### Updated Keyboard Codebases {#updated-keyboard-codebases} The following keyboards have had their source moved within QMK: @@ -23,17 +23,19 @@ The following keyboards have had their source moved within QMK: | handwired/hillside/52 | hillside/52 | | maple_computing/christmas_tree/V2017 | maple_computing/christmas_tree/v2017 | -### Keycodes refactoring :id=keycodes-overhaul-user-action +### Keycodes refactoring {#keycodes-overhaul-user-action} -QMK's keycodes got a very significant overhaul this breaking changes cycle, with the bulk of the work done by _@zvecr_ and _@fauxpark_ -- renaming, reordering, removing has been their focus in this area. In an attempt to standardise interoperation with host applications, keycode values now have strong versioning so that any connected application has confidence that the keys it thinks exist on the board actually match up with what's compiled in. These strongly-versioned keycode definitions are now published online and will not change, so tools that remap keycodes have a reference to work with. In future versions of QMK, any new or changed keycodes will result in a new version specification. See [API docs](api_docs.md#qmk-constants) for more information on the published versions if you're writing a tool to manage keycodes. +QMK's keycodes got a very significant overhaul this breaking changes cycle, with the bulk of the work done by _@zvecr_ and _@fauxpark_ -- renaming, reordering, removing has been their focus in this area. In an attempt to standardise interoperation with host applications, keycode values now have strong versioning so that any connected application has confidence that the keys it thinks exist on the board actually match up with what's compiled in. These strongly-versioned keycode definitions are now published online and will not change, so tools that remap keycodes have a reference to work with. In future versions of QMK, any new or changed keycodes will result in a new version specification. See [API docs](../api_docs#qmk-constants) for more information on the published versions if you're writing a tool to manage keycodes. In most cases user keymaps in the repository have already been updated to reflect the new naming scheme. In some cases user keymaps outside the repository may strike a missing keycode with the old name -- it's highly likely that the name had already been deprecated for some time, and should have been updated previously. See below for the full list of changesets. -!> Keycode aliases have been put in place in most cases to cater for "old names" being mapped to "new names" -- the documentation already reflects all the new naming of keys. +::: warning +Keycode aliases have been put in place in most cases to cater for "old names" being mapped to "new names" -- the documentation already reflects all the new naming of keys. +::: -### Configuration Item Refactoring :id=config-refactoring +### Configuration Item Refactoring {#config-refactoring} A number of configuration items have been renamed for consistency. @@ -66,7 +68,7 @@ Joystick configuration: | JOYSTICK_AXES_COUNT | JOYSTICK_AXIS_COUNT | | JOYSTICK_AXES_RESOLUTION | JOYSTICK_AXIS_RESOLUTION | -### Data-driven USB IDs Refactoring ([#18152](https://github.com/qmk/qmk_firmware/pull/18152)) :id=usb-ids-Refactoring +### Data-driven USB IDs Refactoring ([#18152](https://github.com/qmk/qmk_firmware/pull/18152)) {#usb-ids-Refactoring} QMK has decided to deprecate the specification of USB IDs inside `config.h` in favour of `info.json`, leaving data-driven as the only method to specify USB information. As per the deprecation schedule put forward last breaking changes cycle, USB information must be specified in `info.json` instead. @@ -92,7 +94,7 @@ Replaced by `info.json`: } ``` -### LED Indicator callback refactoring ([#14864](https://github.com/qmk/qmk_firmware/pull/18450)) :id=led-callback-refactor +### LED Indicator callback refactoring ([#14864](https://github.com/qmk/qmk_firmware/pull/18450)) {#led-callback-refactor} _RGB Matrix_ and _LED Matrix_ Indicator display code was traditionally difficult to override in keymaps as they did not follow the standard pattern of `bool *_kb()` deferring to `bool *_user()` functions, allowing signalling to the higher level that processing had already been done. @@ -128,15 +130,15 @@ bool rgb_matrix_indicators_kb(void) { The equivalent transformations should be done for LED Matrix boards. -### Unicode mode refactoring :id=unicode-mode-renaming +### Unicode mode refactoring {#unicode-mode-renaming} -Unicode modes were renamed in order to prevent collision with equivalent keycodes. The available values for `UNICODE_SELECTED_MODES` changed -- see [Feature: Unicode](feature_unicode.md#setting-the-input-mode) for the new list of values and how to configure them. +Unicode modes were renamed in order to prevent collision with equivalent keycodes. The available values for `UNICODE_SELECTED_MODES` changed -- see [Feature: Unicode](../feature_unicode#setting-the-input-mode) for the new list of values and how to configure them. -## Notable core changes :id=notable-core +## Notable core changes {#notable-core} This breaking changes cycle, a lot of the core changes are related to cleanup and refactoring -- commonly called "tech debt". -### Keycodes refactoring :id=keycodes-overhaul-core-changes +### Keycodes refactoring {#keycodes-overhaul-core-changes} We aren't going to list each and every change -- they're far too numerous -- instead, we'll just list the related PRs in order to convey just how wide-reaching these changes were: @@ -181,7 +183,7 @@ We aren't going to list each and every change -- they're far too numerous -- ins * Remove legacy sendstring keycodes ([#18749](https://github.com/qmk/qmk_firmware/pull/18749)) * Reworked backlight keycodes. ([#18961](https://github.com/qmk/qmk_firmware/pull/18961)) -### Board Converters :id=board-converters +### Board Converters {#board-converters} There was additional work in the space of board converters -- historically QMK allowed for "converting" a Pro Micro build to a QMK Proton-C build. The last few versions of QMK have added support for replacement boards much like the Proton-C, and this quarter was no exception: @@ -191,9 +193,9 @@ There was additional work in the space of board converters -- historically QMK a * Add Elite-Pi converter ([#18236](https://github.com/qmk/qmk_firmware/pull/18236)) * Allow QK_MAKE to work with converters ([#18637](https://github.com/qmk/qmk_firmware/pull/18637)) -See [Feature: Converters](feature_converters.md) for the full list of board conversions available. +See [Feature: Converters](../feature_converters) for the full list of board conversions available. -### Pointing and Digitizer device updates :id=pointing-and-digitizer +### Pointing and Digitizer device updates {#pointing-and-digitizer} Both pointing devices and digitizer got a host of updates this cycle. Inertia, automatic mouse layers, fixes for preventing sleep... you even get more buttons with digitizers! @@ -207,7 +209,7 @@ Both pointing devices and digitizer got a host of updates this cycle. Inertia, a * Invert pointing device motion pin for cirque touchpads ([#18404](https://github.com/qmk/qmk_firmware/pull/18404)) * Refactor more host code (programmable button & digitizer) ([#18565](https://github.com/qmk/qmk_firmware/pull/18565)) -## Full changelist :id=full-changelist +## Full changelist {#full-changelist} Core: * quantum: led: split out led_update_ports() for customization of led behaviour ([#14452](https://github.com/qmk/qmk_firmware/pull/14452)) diff --git a/docs/ChangeLog/20230226.md b/docs/ChangeLog/20230226.md index df5095ac7b..ee56068604 100644 --- a/docs/ChangeLog/20230226.md +++ b/docs/ChangeLog/20230226.md @@ -1,8 +1,8 @@ # QMK Breaking Changes - 2023 February 26 Changelog -## Changes Requiring User Action :id=changes-requiring-user-action +## Changes Requiring User Action {#changes-requiring-user-action} -### `IGNORE_MOD_TAP_INTERRUPT` behaviour changes ([#15741](https://github.com/qmk/qmk_firmware/pull/15741)) :id=i-m-t-i +### `IGNORE_MOD_TAP_INTERRUPT` behaviour changes ([#15741](https://github.com/qmk/qmk_firmware/pull/15741)) {#i-m-t-i} `IGNORE_MOD_TAP_INTERRUPT_PER_KEY` has been removed and `IGNORE_MOD_TAP_INTERRUPT` deprecated as a stepping stone towards making `IGNORE_MOD_TAP_INTERRUPT` the new default behavior for mod-taps in the future. @@ -46,9 +46,9 @@ bool get_hold_on_other_key_press(uint16_t keycode, keyrecord_t *record) { } ``` -For more information, you are invited to read the sections on [IGNORE_MOD_TAP_INTERRUPT](tap_hold.md#ignore-mod-tap-interrupt) and [HOLD_ON_OTHER_KEY_PRESS](tap_hold.md#hold-on-other-key-press) in the page on [Tap-Hold configuration options](tap_hold.md). +For more information, you are invited to read the sections on [IGNORE_MOD_TAP_INTERRUPT](../tap_hold#ignore-mod-tap-interrupt) and [HOLD_ON_OTHER_KEY_PRESS](../tap_hold#hold-on-other-key-press) in the page on [Tap-Hold configuration options](../tap_hold). -### `TAPPING_FORCE_HOLD` => `QUICK_TAP_TERM` ([#17007](https://github.com/qmk/qmk_firmware/pull/17007)) :id=quick-tap-term +### `TAPPING_FORCE_HOLD` => `QUICK_TAP_TERM` ([#17007](https://github.com/qmk/qmk_firmware/pull/17007)) {#quick-tap-term} `TAPPING_FORCE_HOLD` feature is now replaced by `QUICK_TAP_TERM`. Instead of turning off auto-repeat completely, user will have the option to configure a `QUICK_TAP_TERM` in milliseconds. When the user holds a tap-hold key after tapping it within `QUICK_TAP_TERM`, QMK will send the tap keycode to the host, enabling auto-repeat. @@ -80,9 +80,9 @@ uint16_t get_quick_tap_term(uint16_t keycode, keyrecord_t *record) { } ``` -For more details, please read the updated documentation section on [Quick Tap Term](tap_hold.md#quick-tap-term). +For more details, please read the updated documentation section on [Quick Tap Term](../tap_hold#quick-tap-term). -### Leader Key Rework :id=leader-key-rework ([#19632](https://github.com/qmk/qmk_firmware/pull/19632)) +### Leader Key Rework {#leader-key-rework ([#19632](https://github.com/qmk/qmk_firmware/pull/19632))} The Leader Key feature API has been significantly improved, along with some bugfixes and added tests. @@ -106,9 +106,9 @@ void leader_end_user(void) { } ``` -For more information please see the [Leader Key documentation](feature_leader_key.md). +For more information please see the [Leader Key documentation](../feature_leader_key). -### Updated Keyboard Codebases :id=updated-keyboard-codebases +### Updated Keyboard Codebases {#updated-keyboard-codebases} The following keyboards have had their source moved within QMK: @@ -130,7 +130,7 @@ The following keyboards have had their source moved within QMK: | the_uni | stenothe_uni | | xelus/xs60 | xelus/xs60/soldered | -## Notable core changes :id=notable-core +## Notable core changes {#notable-core} As per last breaking changes cycle, there has been _a lot_ of emphasis on behind-the-scenes changes, mainly around consolidation of core subsystems and constant values, as well as addressing tech debt. Whilst not outwardly visible, this cleanup and refactoring should start paying dividends as it simplifies future development and maintenance. @@ -142,7 +142,7 @@ A handful of examples: * Many more configuration options have moved into `info.json`, such as backlight, encoders * Additional unit tests to ensure keycode behaviours don't accidentally change -## Full changelist :id=full-changelist +## Full changelist {#full-changelist} Core: * Remove IGNORE_MOD_TAP_INTERRUPT_PER_KEY in favour of HOLD_ON_OTHER_KEY_PRESS_PER_KEY ([#15741](https://github.com/qmk/qmk_firmware/pull/15741)) diff --git a/docs/ChangeLog/20230528.md b/docs/ChangeLog/20230528.md index b4044d3109..40ab3a420c 100644 --- a/docs/ChangeLog/20230528.md +++ b/docs/ChangeLog/20230528.md @@ -1,6 +1,6 @@ # QMK Breaking Changes - 2023 May 28 Changelog -## Notable Changes :id=notable-changes +## Notable Changes {#notable-changes} As per last breaking changes cycle, there has been _a lot_ of emphasis on behind-the-scenes changes, mainly around migration of configurables into `info.json` files, cleanup of `info.json` files, additional layout definitions for keyboards, adding support for general community layouts to keyboards, as well as addressing technical debt. @@ -20,11 +20,11 @@ Of note for keyboard designers: * `encoder_map[][NUM_ENCODERS][2]` => `encoder_map[][NUM_ENCODERS][NUM_DIRECTIONS]` * Users assumed the `2` referred to the number of encoders, rather than the number of directions (which is always 2) -### Repeat last key ([#19700](https://github.com/qmk/qmk_firmware/pull/19700)) :id=repeat-last-key +### Repeat last key ([#19700](https://github.com/qmk/qmk_firmware/pull/19700)) {#repeat-last-key} A new pair of keys has been added to QMK -- namely `QK_REPEAT_KEY` and `QK_ALT_REPEAT_KEY` (shortened: `QK_REP`/`QK_AREP`). These allow you to repeat the last key pressed, or in the case of the alternate key, press the "opposite" of the last key. For example, if you press `KC_LEFT`, pressing `QK_REPEAT_KEY` afterwards repeats `KC_LEFT`, but pressing `QK_ALT_REPEAT_KEY` instead sends `KC_RIGHT`. -The full list of default alternate keys is available on the [Repeat Key](feature_repeat_key.md) documentation. +The full list of default alternate keys is available on the [Repeat Key](../feature_repeat_key) documentation. To enable these keys, in your keymap's `rules.mk`, add: @@ -34,27 +34,27 @@ REPEAT_KEY_ENABLE = yes ...and add them to your keymap. -### User callback for pre process record ([#20584](https://github.com/qmk/qmk_firmware/pull/20584)) :id=user-callback-for-pre-process-record +### User callback for pre process record ([#20584](https://github.com/qmk/qmk_firmware/pull/20584)) {#user-callback-for-pre-process-record} Two new boolean callback functions, `pre_process_record_kb` and `pre_process_record_user`, have been added. They are called at the beginning of `process_record`, right before `process_combo`. -Similar to existing `*_kb` and `*_user` callback functions, returning `false` will halt further processing of key events. The `pre_process_record_user` function will allow user space opportunity to handle or capture an input before it undergoes quantum processing. For example, while action tapping is still resolving the tap or hold output of a mod-tap key, `pre_process_record_user` can capture the next key record of an input event that follows. That key record can be used to influence the [decision of the mod-tap](https://docs.qmk.fm/#/tap_hold) key that is currently undergoing quantum processing. +Similar to existing `*_kb` and `*_user` callback functions, returning `false` will halt further processing of key events. The `pre_process_record_user` function will allow user space opportunity to handle or capture an input before it undergoes quantum processing. For example, while action tapping is still resolving the tap or hold output of a mod-tap key, `pre_process_record_user` can capture the next key record of an input event that follows. That key record can be used to influence the [decision of the mod-tap](../tap_hold) key that is currently undergoing quantum processing. -### Consolidate modelm ([#14996](https://github.com/qmk/qmk_firmware/pull/14996) :id=consolidate-modelm +### Consolidate modelm ([#14996](https://github.com/qmk/qmk_firmware/pull/14996) {#consolidate-modelm} Several build targets for the IBM Model M were cluttered in different folders. The maintainers of several Model M replacement controller projects agreed to consolidate them under one common folder. -The list of all moved keyboard locations is listed [below](20230528.md#updated-keyboard-codebases). +The list of all moved keyboard locations is listed [below](20230528#updated-keyboard-codebases). -## Changes Requiring User Action :id=changes-requiring-user-action +## Changes Requiring User Action {#changes-requiring-user-action} -### `IGNORE_MOD_TAP_INTERRUPT` behaviour changes ([#20211](https://github.com/qmk/qmk_firmware/pull/20211)) :id=i-m-t-i +### `IGNORE_MOD_TAP_INTERRUPT` behaviour changes ([#20211](https://github.com/qmk/qmk_firmware/pull/20211)) {#i-m-t-i} Following up from the last breaking changes cycle, `IGNORE_MOD_TAP_INTERRUPT` has been removed and if present in keymap code, will now fail to build. The previous functionality for `IGNORE_MOD_TAP_INTERRUPT` is now default, and should you wish to revert to the old behaviour, you can use `HOLD_ON_OTHER_KEY_PRESS` instead. -For more information, you are invited to read the section on [HOLD_ON_OTHER_KEY_PRESS](tap_hold.md#hold-on-other-key-press) in the page on [Tap-Hold configuration options](tap_hold.md). +For more information, you are invited to read the section on [HOLD_ON_OTHER_KEY_PRESS](../tap_hold#hold-on-other-key-press) in the page on [Tap-Hold configuration options](../tap_hold). -### Updated Keyboard Codebases :id=updated-keyboard-codebases +### Updated Keyboard Codebases {#updated-keyboard-codebases} | Old Keyboard Name | New Keyboard Name | |---------------------------------|-------------------------------------| @@ -77,9 +77,9 @@ For more information, you are invited to read the section on [HOLD_ON_OTHER_KEY_ | tronguylabs/m122_3270/teensy | ibm/model_m_122/m122_3270/teensy | | yugo_m/model_m_101 | ibm/model_m/yugo_m | -## Notable core changes :id=notable-core +## Notable core changes {#notable-core} -### Encoder functionality fallback ([#20320](https://github.com/qmk/qmk_firmware/pull/20320)) :id=encoder-functionality-fallback +### Encoder functionality fallback ([#20320](https://github.com/qmk/qmk_firmware/pull/20320)) {#encoder-functionality-fallback} For keyboards who have not yet been migrated to encoder map, a default set of encoder functionality is now enabled, gracefully degrading functionality depending on which flags are enabled by the keyboard: @@ -89,13 +89,13 @@ For keyboards who have not yet been migrated to encoder map, a default set of en Additionally, this ensures that builds on QMK Configurator produce some sort of usable encoder mapping. -### OLED Driver Improvements ([#20331](https://github.com/qmk/qmk_firmware/pull/20331)) :id=oled-driver-improvements +### OLED Driver Improvements ([#20331](https://github.com/qmk/qmk_firmware/pull/20331)) {#oled-driver-improvements} The "classic" OLED driver picked up support for additional sizes of OLED displays, support for the SH1107 controller, and SPI-based OLED support. -Other configurable items are available and can be found on the [OLED Driver page](https://docs.qmk.fm/#/feature_oled_driver). +Other configurable items are available and can be found on the [OLED Driver page](../feature_oled_driver). -## Full changelist :id=full-changelist +## Full changelist {#full-changelist} Core: * Refactor `keyevent_t` for 1ms timing resolution ([#15847](https://github.com/qmk/qmk_firmware/pull/15847)) diff --git a/docs/ChangeLog/20230827.md b/docs/ChangeLog/20230827.md index 12093d889f..aecbcb0d8f 100644 --- a/docs/ChangeLog/20230827.md +++ b/docs/ChangeLog/20230827.md @@ -1,14 +1,14 @@ # QMK Breaking Changes - 2023 Aug 27 Changelog -## Notable Changes :id=notable-changes +## Notable Changes {#notable-changes} As per last few breaking changes cycles, there have been _a lot_ of behind-the-scenes changes, mainly around migration of configurables into `info.json` files, cleanup of `info.json` files, additional layout definitions for keyboards, adding support for general community layouts to keyboards, as well as addressing technical debt. -One thing to note for this release -- `qmk/qmk_firmware` is no longer accepting PRs for keymaps other than for manufacturer-supported keymaps. User keymap workflow has been documented [here](https://docs.qmk.fm/#/newbs) for several years. This change is to progressively reduce the maintenance burden on the project, and to allow us to focus on the core features of QMK. +One thing to note for this release -- `qmk/qmk_firmware` is no longer accepting PRs for keymaps other than for manufacturer-supported keymaps. User keymap workflow has been documented [here](../newbs) for several years. This change is to progressively reduce the maintenance burden on the project, and to allow us to focus on the core features of QMK. Existing user keymaps and userspace areas will likely be relocated/removed in the future -- non-building keymaps and userspace will be first targets, likely during the new breaking changes cycle. We will provide more information on Discord regarding this initiative as it becomes available. -### RGB Matrix optimizations ([#21134](https://github.com/qmk/qmk_firmware/pull/21134), [#21135](https://github.com/qmk/qmk_firmware/pull/21135)) :id=rgb-matrix-optimizations +### RGB Matrix optimizations ([#21134](https://github.com/qmk/qmk_firmware/pull/21134), [#21135](https://github.com/qmk/qmk_firmware/pull/21135)) {#rgb-matrix-optimizations} Most RGB Matrix implementations now check whether or not RGB LED data has changed and skip transmission if it hasn't. This was measured to improve scan frequency in cases of static or infrequently-changing colors. @@ -18,9 +18,9 @@ Some audio code relating to "notes" used `double` datatypes, which are implement AVR sees minimal (if any) benefit -- `double` was interpreted as `float` on AVR anyway. -## Changes Requiring User Action :id=changes-requiring-user-action +## Changes Requiring User Action {#changes-requiring-user-action} -### Updated Keyboard Codebases :id=updated-keyboard-codebases +### Updated Keyboard Codebases {#updated-keyboard-codebases} | Old Keyboard Name | New Keyboard Name | |---------------------------------------|-------------------------------------| @@ -40,11 +40,11 @@ AVR sees minimal (if any) benefit -- `double` was interpreted as `float` on AVR | modelh | ibm/model_m/modelh | | vinta | coarse/vinta | -### Remove encoder in-matrix workaround code ([#20389](https://github.com/qmk/qmk_firmware/pull/20389)) :id=remove-encoder-in-matrix-workaround-code +### Remove encoder in-matrix workaround code ([#20389](https://github.com/qmk/qmk_firmware/pull/20389)) {#remove-encoder-in-matrix-workaround-code} -Some keyboards "hacked" encoder support into spare slots in the key matrix in order to interoperate with VIA. This workaround is no longer necessary, and the code has been removed. If you have a keyboard that uses this workaround, you will need to update your keymap to use the new [Encoder Map](feature_encoders.md#encoder-map) API instead. +Some keyboards "hacked" encoder support into spare slots in the key matrix in order to interoperate with VIA. This workaround is no longer necessary, and the code has been removed. If you have a keyboard that uses this workaround, you will need to update your keymap to use the new [Encoder Map](../feature_encoders#encoder-map) API instead. -### Unicodemap keycodes rename ([#21092](https://github.com/qmk/qmk_firmware/pull/21092)) :id=unicodemap-keycodes-rename +### Unicodemap keycodes rename ([#21092](https://github.com/qmk/qmk_firmware/pull/21092)) {#unicodemap-keycodes-rename} The Unicodemap keycodes have been renamed: @@ -53,11 +53,11 @@ The Unicodemap keycodes have been renamed: | `X(i)` | `UM(i)` | | `XP(i,j)` | `UP(i,j)` | -### Remove old OLED API code ([#21651](https://github.com/qmk/qmk_firmware/pull/21651)) :id=remove-old-oled-api-code +### Remove old OLED API code ([#21651](https://github.com/qmk/qmk_firmware/pull/21651)) {#remove-old-oled-api-code} Old OLED code using `ssd1306.c` `ssd1306.h`, and `SSD1306OLED` and other similar files have been consolidated to use the standard OLED driver. External user keymaps will need to be updated to use the standard OLED driver accordingly. -### Driver naming consolidation ([#21551](https://github.com/qmk/qmk_firmware/pull/21551), [#21558](https://github.com/qmk/qmk_firmware/pull/21558), [#21580](https://github.com/qmk/qmk_firmware/pull/21580), [#21594](https://github.com/qmk/qmk_firmware/pull/21594), [#21624](https://github.com/qmk/qmk_firmware/pull/21624), [#21710](https://github.com/qmk/qmk_firmware/pull/21710)) :id=driver-naming-consolidation +### Driver naming consolidation ([#21551](https://github.com/qmk/qmk_firmware/pull/21551), [#21558](https://github.com/qmk/qmk_firmware/pull/21558), [#21580](https://github.com/qmk/qmk_firmware/pull/21580), [#21594](https://github.com/qmk/qmk_firmware/pull/21594), [#21624](https://github.com/qmk/qmk_firmware/pull/21624), [#21710](https://github.com/qmk/qmk_firmware/pull/21710)) {#driver-naming-consolidation} In most circumstances this won't affect users -- only keyboard designers with currently-unmerged boards. The only users affected are people who have modified existing keyboards in order to add/modify haptics, lighting, or bluetooth -- and only if the base keyboard did not configure them already. Driver naming has been modified to be lowercase. @@ -116,7 +116,7 @@ Bluetooth (`BLUETOOTH_DRIVER` / `bluetooth.driver`): | `BluefruitLE` | `bluefruit_le` | | `RN42` | `rn42` | -## Full changelist :id=full-changelist +## Full changelist {#full-changelist} Core: * On-each-release tap dance function ([#20255](https://github.com/qmk/qmk_firmware/pull/20255)) diff --git a/docs/ChangeLog/20231126.md b/docs/ChangeLog/20231126.md index 61cff520c8..8a43bb0016 100644 --- a/docs/ChangeLog/20231126.md +++ b/docs/ChangeLog/20231126.md @@ -1,14 +1,14 @@ # QMK Breaking Changes - 2023 November 26 Changelog -## Notable Features :id=notable-features +## Notable Features {#notable-features} As per last few breaking changes cycles, there have been _a lot_ of behind-the-scenes changes, mainly around consolidation of config into `info.json` files, cleanup of `info.json` files, cleaning up driver naming, as well as addressing technical debt. -As a followup to last cycle's [notable changes](20230827.md#notable-changes), as `qmk/qmk_firmware` is no longer accepting PRs for keymaps we're pleased to announce that storing and building keymaps externally from the normal QMK Firmware repository is now possible. This is done through the new [External Userspace](newbs_external_userspace.md) feature, more details below! +As a followup to last cycle's [notable changes](20230827#notable-changes), as `qmk/qmk_firmware` is no longer accepting PRs for keymaps we're pleased to announce that storing and building keymaps externally from the normal QMK Firmware repository is now possible. This is done through the new [External Userspace](../newbs_external_userspace) feature, more details below! -## Changes Requiring User Action :id=changes-requiring-user-action +## Changes Requiring User Action {#changes-requiring-user-action} -### Updated Keyboard Codebases :id=updated-keyboard-codebases +### Updated Keyboard Codebases {#updated-keyboard-codebases} | Old Keyboard Name | New Keyboard Name | |---------------------------------------|-------------------------------| @@ -29,29 +29,31 @@ As a followup to last cycle's [notable changes](20230827.md#notable-changes), as | studiokestra/line_tkl | studiokestra/line_friends_tkl | | ymdk/melody96 | ymdk/melody96/soldered | -## Notable core changes :id=notable-core +## Notable core changes {#notable-core} ### External Userspace ([#22222](https://github.com/qmk/qmk_firmware/pull/22222)) As mentioned above, the new External Userspace feature allows for keymaps to be stored and built externally from the main QMK Firmware repository. This allows for keymaps to be stored separately -- usually in their own repository -- and for users to be able to maintain and build their keymaps without needing to fork the main QMK Firmware repository. -See the [External Userspace documentation](newbs_external_userspace.md) for more details. +See the [External Userspace documentation](../newbs_external_userspace) for more details. A significant portion of user keymaps have already been removed from `qmk/qmk_firmware` and more will follow in coming weeks. You can still recover your keymap from the tag [user-keymaps-still-present](https://github.com/qmk/qmk_firmware/tree/user-keymaps-still-present) if required -- a perfect time to migrate to the new External Userspace! -!> This feature is still in beta, and we're looking for feedback on it. Please try it out and let us know what you think -- a new `#help-userspace` channel has been set up on Discord. +::: warning +This feature is still in beta, and we're looking for feedback on it. Please try it out and let us know what you think -- a new `#help-userspace` channel has been set up on Discord. +::: -### Improve and Cleanup Shutdown callbacks ([#21060](https://github.com/qmk/qmk_firmware/pull/20160)) :id=improve-and-cleanup-shutdown-callbacks +### Improve and Cleanup Shutdown callbacks ([#21060](https://github.com/qmk/qmk_firmware/pull/20160)) {#improve-and-cleanup-shutdown-callbacks} Shutdown callbacks at the keyboard level were never present, preventing safe shutdown sequencing for peripherals such as OLEDs, RGB LEDs, and other devices. This PR adds a new `shutdown_kb` function, as well as amending `shutdown_user`, allowing for safe shutdown of peripherals at both keyboard and keymap level. -See the [Keyboard Shutdown/Reboot Code](custom_quantum_functions.md#keyboard-shutdown-reboot-code) documentation for more details. +See the [Keyboard Shutdown/Reboot Code](../custom_quantum_functions#keyboard-shutdown-reboot-code) documentation for more details. -### OLED Force Flush ([#20953](https://github.com/qmk/qmk_firmware/pull/20953)) :id=oled-force-flush +### OLED Force Flush ([#20953](https://github.com/qmk/qmk_firmware/pull/20953)) {#oled-force-flush} Along with the new `shutdown_kb` function, a new API `oled_render_dirty(bool)` function has been added. This allows OLED contents to be written deterministically when supplied with `true` -- that is, the OLED will be updated immediately, rather than waiting for the next OLED update cycle. This allows for OLEDs to show things such as "BOOTLOADER MODE" and the like if resetting to bootloader from QMK. -### Switch statement helpers for keycode ranges ([#20059](https://github.com/qmk/qmk_firmware/pull/20059)) :id=switch-statement-helpers-for-keycode-ranges +### Switch statement helpers for keycode ranges ([#20059](https://github.com/qmk/qmk_firmware/pull/20059)) {#switch-statement-helpers-for-keycode-ranges} Predefined ranges usable within switch statements have been added for groups of similar keycodes, where people who wish to handle entire blocks at once can do so. This allows keymaps to be immune to changes in keycode values, and also allows for more efficient code generation. @@ -98,17 +100,17 @@ Becomes: /* do stuff with basic and modifier keycodes */ ``` -### Quantum Painter OLED support ([#19997](https://github.com/qmk/qmk_firmware/pull/19997)) :id=quantum-painter-oled-support +### Quantum Painter OLED support ([#19997](https://github.com/qmk/qmk_firmware/pull/19997)) {#quantum-painter-oled-support} Quantum Painter has picked up support for SH1106 displays -- commonly seen as 128x64 OLEDs. Support for both I2C and SPI displays is available. -If you're already using OLED through `OLED_DRIVER_ENABLE = yes` or equivalent in `info.json` and wish to use Quantum Painter instead, you'll need to disable the old OLED system, instead enabling Quantum Painter as well as enabling the appropriate SH1106 driver. See the [Quantum Painter driver documentation](quantum_painter.md#quantum-painter-drivers) for more details. The old OLED driver is still available, and keymaps do not require migrating to Quantum Painter if you don't want to do so. +If you're already using OLED through `OLED_DRIVER_ENABLE = yes` or equivalent in `info.json` and wish to use Quantum Painter instead, you'll need to disable the old OLED system, instead enabling Quantum Painter as well as enabling the appropriate SH1106 driver. See the [Quantum Painter driver documentation](../quantum_painter#quantum-painter-drivers) for more details. The old OLED driver is still available, and keymaps do not require migrating to Quantum Painter if you don't want to do so. ### RGB/LED lighting driver naming and cleanup ([#21890](https://github.com/qmk/qmk_firmware/pull/21890), [#21891](https://github.com/qmk/qmk_firmware/pull/21891), [#21892](https://github.com/qmk/qmk_firmware/pull/21892), [#21903](https://github.com/qmk/qmk_firmware/pull/21903), [#21904](https://github.com/qmk/qmk_firmware/pull/21904), [#21905](https://github.com/qmk/qmk_firmware/pull/21905), [#21918](https://github.com/qmk/qmk_firmware/pull/21918), [#21929](https://github.com/qmk/qmk_firmware/pull/21929), [#21938](https://github.com/qmk/qmk_firmware/pull/21938), [#22004](https://github.com/qmk/qmk_firmware/pull/22004), [#22008](https://github.com/qmk/qmk_firmware/pull/22008), [#22009](https://github.com/qmk/qmk_firmware/pull/22009), [#22071](https://github.com/qmk/qmk_firmware/pull/22071), [#22090](https://github.com/qmk/qmk_firmware/pull/22090), [#22099](https://github.com/qmk/qmk_firmware/pull/22099), [#22126](https://github.com/qmk/qmk_firmware/pull/22126), [#22133](https://github.com/qmk/qmk_firmware/pull/22133), [#22163](https://github.com/qmk/qmk_firmware/pull/22163), [#22200](https://github.com/qmk/qmk_firmware/pull/22200), [#22308](https://github.com/qmk/qmk_firmware/pull/22308), [#22309](https://github.com/qmk/qmk_firmware/pull/22309), [#22311](https://github.com/qmk/qmk_firmware/pull/22311), [#22325](https://github.com/qmk/qmk_firmware/pull/22325), [#22365](https://github.com/qmk/qmk_firmware/pull/22365), [#22379](https://github.com/qmk/qmk_firmware/pull/22379), [#22380](https://github.com/qmk/qmk_firmware/pull/22380), [#22381](https://github.com/qmk/qmk_firmware/pull/22381), [#22383](https://github.com/qmk/qmk_firmware/pull/22383), [#22436](https://github.com/qmk/qmk_firmware/pull/22436)) As you can probably tell by the list of PRs just above, there has been a lot of cleanup and consolidation this cycle when it comes to RGB/LED lighting drivers. The number of changes is too large to list here, but the general theme has been focusing on consistency of naming, both of drivers themselves and their respective implementation and configuration. Most changes only affect keyboard designers -- if you find that your in-development keyboard is no longer building due to naming of defines changing, your best bet is to refer to another board already in the repository which has had the changes applied. -### Peripheral subsystem enabling ([#22253](https://github.com/qmk/qmk_firmware/pull/22253), [#22448](https://github.com/qmk/qmk_firmware/pull/22448), [#22106](https://github.com/qmk/qmk_firmware/pull/22106)) :id=peripheral-subsystem-enabling +### Peripheral subsystem enabling ([#22253](https://github.com/qmk/qmk_firmware/pull/22253), [#22448](https://github.com/qmk/qmk_firmware/pull/22448), [#22106](https://github.com/qmk/qmk_firmware/pull/22106)) {#peripheral-subsystem-enabling} When enabling peripherals such as I2C, SPI, or Analog/ADC, some required manual inclusion of source files in order to provide driver support, and in some cases, when multiple drivers were using the same underlying peripheral, files were being added to the build multiple times. @@ -125,11 +127,11 @@ For a concrete example, users or keyboard designers who previously added `SRC += | `UART_DRIVER_REQUIRED = yes` | `SRC += uart.c` | | `WS2812_DRIVER_REQUIRED = yes` | `SRC += ws2812.c` | -### NKRO on V-USB boards ([#22398](https://github.com/qmk/qmk_firmware/pull/22398)) :id=vusb-nkro +### NKRO on V-USB boards ([#22398](https://github.com/qmk/qmk_firmware/pull/22398)) {#vusb-nkro} NKRO is now available for ATmega32A and 328P-based keyboards (including PS2AVRGB/Bootmapper boards), thanks to some internal refactoring and cleanup. To enable it, the process is the same as always - add `NKRO_ENABLE = yes` to your `rules.mk`, then assign and press the `NK_TOGG` keycode to switch modes. -## Full changelist :id=full-changelist +## Full changelist {#full-changelist} Core: * Compilation warning if both `keymap.json` and `keymap.c` exist ([#19939](https://github.com/qmk/qmk_firmware/pull/19939)) diff --git a/docs/ChangeLog/20240225.md b/docs/ChangeLog/20240225.md index 779b778490..f4103c594e 100644 --- a/docs/ChangeLog/20240225.md +++ b/docs/ChangeLog/20240225.md @@ -1,6 +1,6 @@ # QMK Breaking Changes - 2024 February 25 Changelog -## Notable Features :id=notable-features +## Notable Features {#notable-features} _0.24.0_ is mainly a maintenance release of QMK Firmware -- as per last few breaking changes cycles, there have been a lot of behind-the-scenes changes, mainly: @@ -10,17 +10,17 @@ _0.24.0_ is mainly a maintenance release of QMK Firmware -- as per last few brea * keyboard relocations * addressing technical debt -## Changes Requiring User Action :id=changes-requiring-user-action +## Changes Requiring User Action {#changes-requiring-user-action} ### Windows Driver Changes ([QMK Toolbox 0.3.0 Release](https://github.com/qmk/qmk_toolbox/releases/tag/0.3.0)) Flashing keyboards that target `atmel-dfu` or `qmk-dfu` on Windows using `qmk flash` or QMK Toolbox have traditionally used _libusb_ for access to the DFU USB device. Since QMK Toolbox 0.3.0, this has changed to WinUSB. -If you update QMK Toolbox or update QMK MSYS, you may find that flashing Atmel DFU keyboards no longer functions as intended. If you strike such issues when flashing new firmware, you will need to replace the _libusb_ driver with _WinUSB_ using Zadig. You can follow the [Recovering from Installation to Wrong Device](driver_installation_zadig.md#recovering-from-installation-to-wrong-device) instructions to replace the driver associated with the Atmel DFU bootloader, skipping the section about removal as Zadig will safely replace the driver instead. Please ensure your keyboard is in bootloader mode and has _libusb_ as the existing driver before attempting to use Zadig to replace the driver. If instead you see _HidUsb_ you're not in bootloader mode and should not continue with driver replacement. +If you update QMK Toolbox or update QMK MSYS, you may find that flashing Atmel DFU keyboards no longer functions as intended. If you strike such issues when flashing new firmware, you will need to replace the _libusb_ driver with _WinUSB_ using Zadig. You can follow the [Recovering from Installation to Wrong Device](../driver_installation_zadig#recovering-from-installation-to-wrong-device) instructions to replace the driver associated with the Atmel DFU bootloader, skipping the section about removal as Zadig will safely replace the driver instead. Please ensure your keyboard is in bootloader mode and has _libusb_ as the existing driver before attempting to use Zadig to replace the driver. If instead you see _HidUsb_ you're not in bootloader mode and should not continue with driver replacement. -### Updated Keyboard Codebases :id=updated-keyboard-codebases +### Updated Keyboard Codebases {#updated-keyboard-codebases} -One note with updated keyboard names -- historical keyboard names are still considered valid when using [External Userspace](newbs_external_userspace.md) for builds. If you're already using External Userspace, you do not need to move your keymap inside your repository. +One note with updated keyboard names -- historical keyboard names are still considered valid when using [External Userspace](../newbs_external_userspace) for builds. If you're already using External Userspace, you do not need to move your keymap inside your repository. | Old Keyboard Name | New Keyboard Name | |-------------------------|---------------------------------| @@ -77,9 +77,9 @@ One note with updated keyboard names -- historical keyboard names are still cons | z12 | zigotica/z12 | | z34 | zigotica/z34 | -## Notable core changes :id=notable-core +## Notable core changes {#notable-core} -### Renaming Arduino-style GPIO pin functions ([#23085](https://github.com/qmk/qmk_firmware/pull/23085), [#23093](https://github.com/qmk/qmk_firmware/pull/23093)) :id=gpio-rename +### Renaming Arduino-style GPIO pin functions ([#23085](https://github.com/qmk/qmk_firmware/pull/23085), [#23093](https://github.com/qmk/qmk_firmware/pull/23093)) {#gpio-rename} QMK has long used Arduino-style GPIO naming conventions. This has been confusing for users, as over time they've had new variations added, as well as users mistakenly thinking that QMK supports the rest of the Arduino ecosystem. @@ -110,17 +110,17 @@ Much like the GPIO refactoring, I2C APIs were also updated to conform to QMK nam | `i2c_writeReg()` | `i2c_write_register()` | | `i2c_writeReg16()` | `i2c_write_register16()` | -### Renaming _Bootmagic Lite_ => _Bootmagic_ ([#22970](https://github.com/qmk/qmk_firmware/pull/22970), [#22979](https://github.com/qmk/qmk_firmware/pull/22979)) :id=bootmagic-rename +### Renaming _Bootmagic Lite_ => _Bootmagic_ ([#22970](https://github.com/qmk/qmk_firmware/pull/22970), [#22979](https://github.com/qmk/qmk_firmware/pull/22979)) {#bootmagic-rename} Bootmagic "Lite" had no real meaning once the historical Bootmagic "Full" was deprecated and removed. Any references to _Bootmagic Lite_ should now just refer to _Bootmagic_. We hope we got the majority of the code and the documentation, so if you find any more, let us know! -### Threshold for automatic mouse layer activation ([#21398](https://github.com/qmk/qmk_firmware/pull/21398)) :id=auto-mouse-layer +### Threshold for automatic mouse layer activation ([#21398](https://github.com/qmk/qmk_firmware/pull/21398)) {#auto-mouse-layer} In some cases, accidental automatic activation of the mouse layer made it difficult to continue typing, such as when brushing across a trackball. `AUTO_MOUSE_THRESHOLD` is now a configurable option in `config.h` which allows for specifying what the movement threshold is before automatically activating the mouse layer. -### DIP Switch Mapping ([#22543](https://github.com/qmk/qmk_firmware/pull/22543)) :id=dip-switch-map +### DIP Switch Mapping ([#22543](https://github.com/qmk/qmk_firmware/pull/22543)) {#dip-switch-map} -Much like Encoder Mapping, DIP Switch Mapping allows for specifying a table of actions to execute when a DIP switch state changes. See the [DIP Switch Documentation](feature_dip_switch.md#dip-switch-map) for more information. +Much like Encoder Mapping, DIP Switch Mapping allows for specifying a table of actions to execute when a DIP switch state changes. See the [DIP Switch Documentation](../feature_dip_switch#dip-switch-map) for more information. ```c #if defined(DIP_SWITCH_MAP_ENABLE) @@ -131,7 +131,7 @@ const uint16_t PROGMEM dip_switch_map[NUM_DIP_SWITCHES][NUM_DIP_STATES] = { #endif ``` -### Quantum Painter updates ([#18521](https://github.com/qmk/qmk_firmware/pull/18521), [#20645](https://github.com/qmk/qmk_firmware/pull/20645), [#22358](https://github.com/qmk/qmk_firmware/pull/22358)) :id=qp-updates +### Quantum Painter updates ([#18521](https://github.com/qmk/qmk_firmware/pull/18521), [#20645](https://github.com/qmk/qmk_firmware/pull/20645), [#22358](https://github.com/qmk/qmk_firmware/pull/22358)) {#qp-updates} Quantum Painter picked up support for the following: @@ -141,7 +141,7 @@ Quantum Painter picked up support for the following: Quantum Painter now supports the majority of common OLED panels supported by the basic OLED driver, so if you're using an ARM-based board you may find Quantum Painter a much more feature-rich API in comparison. -## Full changelist :id=full-changelist +## Full changelist {#full-changelist} Core: * [Driver] ILI9486 on Quantum Painter ([#18521](https://github.com/qmk/qmk_firmware/pull/18521)) diff --git a/docs/ChangeLog/20240526.md b/docs/ChangeLog/20240526.md index 4cf185234c..b5e5b3b693 100644 --- a/docs/ChangeLog/20240526.md +++ b/docs/ChangeLog/20240526.md @@ -1,14 +1,14 @@ # QMK Breaking Changes - 2024 May 26 Changelog -## Notable Features :id=notable-features +## Notable Features {#notable-features} May 2024 brings about another heavy maintenance release of QMK. Of the 209 PRs created this breaking changes cycle against the `develop` branch, 174 behind-the-scenes PRs (83%!) were aimed at converting, consolidating, and cleaning up keyboards and their configuration data. Not the most glamorous work, but it means QMK is in a much more manageable spot than what it was 3 months prior. The work steadily continues! -## Changes Requiring User Action :id=changes-requiring-user-action +## Changes Requiring User Action {#changes-requiring-user-action} -### Updated Keyboard Codebases :id=updated-keyboard-codebases +### Updated Keyboard Codebases {#updated-keyboard-codebases} -One note with updated keyboard names -- historical keyboard names are still considered valid when using [External Userspace](newbs_external_userspace.md) for builds. If you're already using External Userspace, you do not need to move your keymap inside your repository. +One note with updated keyboard names -- historical keyboard names are still considered valid when using [External Userspace](../newbs_external_userspace) for builds. If you're already using External Userspace, you do not need to move your keymap inside your repository. | Old Keyboard Name | New Keyboard Name | |------------------------------|-----------------------------------| @@ -40,7 +40,7 @@ A bunch of legacy keycodes have been removed -- check [the affected keycodes](ht The latest of these were officially deprecated within QMK in the August 2023 breaking changes -- the new keycodes are the way forward. -### P3D Spacey Layout Updates ([#23329](https://github.com/qmk/qmk_firmware/pull/23329)) :id=spacey-layout-updates +### P3D Spacey Layout Updates ([#23329](https://github.com/qmk/qmk_firmware/pull/23329)) {#spacey-layout-updates} This PR removed the `LAYOUT` macro that was configured for the Spacey. If you have a keymap for this keyboard, you will need to update your @@ -54,7 +54,7 @@ keymap using the following steps: 4. Move the keycode for the Right Arrow to the end of the Shift row, after the Down Arrow key. -### MechKeys ACR60 Layout Updates ([#23309](https://github.com/qmk/qmk_firmware/pull/23309)) :id=acr60-layout-updates +### MechKeys ACR60 Layout Updates ([#23309](https://github.com/qmk/qmk_firmware/pull/23309)) {#acr60-layout-updates} This PR removed and changed some of the layouts that were configured for the ACR60. If you use one of the following layouts, you will need to update your keymap: @@ -63,17 +63,17 @@ This PR removed and changed some of the layouts that were configured for the ACR - [`LAYOUT_directional`](#layout-directional) - [`LAYOUT_mitchsplit`](#layout-mitchsplit) -#### `LAYOUT_hhkb` :id=acr60-layout-hhkb +#### `LAYOUT_hhkb` {#acr60-layout-hhkb} 1. Change your layout macro to `LAYOUT_60_hhkb`. 1. Remove any keycodes for the key between Left Shift and QWERTY Z. -#### `LAYOUT_true_hhkb` :id=acr60-layout-true-hhkb +#### `LAYOUT_true_hhkb` {#acr60-layout-true-hhkb} 1. Change your layout macro to `LAYOUT_60_true_hhkb`. 1. Remove any keycodes for the key between Left Shift and QWERTY Z. -#### `LAYOUT_directional` :id=acr60-layout-directional +#### `LAYOUT_directional` {#acr60-layout-directional} 1. Change your layout macro to `LAYOUT_60_ansi_arrow_split_bs`. 1. Remove any keycodes for the key between Left Shift and QWERTY Z. @@ -81,16 +81,16 @@ This PR removed and changed some of the layouts that were configured for the ACR If you need split spacebars, you may implement `LAYOUT_60_ansi_arrow_split_space_split_bs` and change your layout to it, removing the keycode between Left Shift and QWERTY Z. -#### `LAYOUT_mitchsplit` :id=acr60-layout-mitchsplit +#### `LAYOUT_mitchsplit` {#acr60-layout-mitchsplit} 1. Use `LAYOUT_60_ansi_split_space_split_rshift`. -## Notable core changes :id=notable-core +## Notable core changes {#notable-core} -### Introduction of `keyboard.json` ([22891](https://github.com/qmk/qmk_firmware/pull/22891)) :id=keyboard-json +### Introduction of `keyboard.json` ([22891](https://github.com/qmk/qmk_firmware/pull/22891)) {#keyboard-json} One longer term goal of QMK is increased maintainability. -As part of the continued push towards [Data Driven Configuration](data_driven_config.md), the build system has been updated to simplify the existing codebase, and power future workflows. +As part of the continued push towards [Data Driven Configuration](../data_driven_config), the build system has been updated to simplify the existing codebase, and power future workflows. The `keyboard.json` configuration file allows the support of a single data file for keyboard level config. @@ -109,7 +109,7 @@ Essentially, changes were made in the internals of how QMK interacts with USB fo Compliance checks were run against QMK firmwares for the most popular ARM microcontrollers, as well as suspend/resume tests. As far as we can tell, a whole host of hard-to-reproduce issues are mitigated by this change. -## Full changelist :id=full-changelist +## Full changelist {#full-changelist} Core: * Refactor vusb to protocol use pre/post task ([#14944](https://github.com/qmk/qmk_firmware/pull/14944)) diff --git a/docs/__capabilities.md b/docs/__capabilities.md index 71183ed760..e28b928970 100644 --- a/docs/__capabilities.md +++ b/docs/__capabilities.md @@ -6,8 +6,6 @@ This page lays out the capabilities used by the QMK Firmware documentation, in o Unrelated to styling, high-level tech. -* I18n -- translations to other languages: [_langs.md](_langs.md) -* Sidebar -- listing of pages by category: [_summary.md](_summary.md) * Title anchors -- `:id=some-anchor-name`, used for direct linking to sections * Links to anchors: * Style 1: [early initialization](platformdev_chibios_earlyinit.md?id=board-init) @@ -40,7 +38,10 @@ Unrelated to styling, high-level tech. ![QMK Color Wheel with HSV Values](https://i.imgur.com/vkYVo66.jpg) -HSV Color Wheel +![QMK Light](./public/badge-community-light.svg) +![QMK Dark](./public/badge-community-dark.svg) + +HSV Color Wheel ### Lists @@ -126,6 +127,26 @@ Command+` !> Notification, damnit! +::: info +This is an info box. +::: + +::: tip +This is a tip. +::: + +::: warning +This is a warning. +::: + +::: danger +This is a dangerous warning. +::: + +::: details +This is a details block. +::: + ### Keyboard keys , @@ -242,6 +263,20 @@ Content three +::::tabs +=== tab a +a content 2 +=== tab b +b content 2 +=== tab c +:::tabs +== nested tab a +nested a content 2 +== nested tab b +nested b content 2 +::: +:::: + ## Details sections Expandable: @@ -254,8 +289,10 @@ Expandable: This is some inner content. - [1]: https://en.wikipedia.org/wiki/Eclipse_(software) - ## Embed [example embed](__capabilities_inc.md ':include') + + + + [1]: https://en.wikipedia.org/wiki/Eclipse_(software) diff --git a/docs/_langs.md b/docs/_langs.md deleted file mode 100644 index 8b08c34513..0000000000 --- a/docs/_langs.md +++ /dev/null @@ -1,4 +0,0 @@ -- Translations - - [:uk: English](/) - - [:cn: 简体中文](/zh-cn/) - - [:jp: 日本語](/ja/) diff --git a/docs/_sidebar.json b/docs/_sidebar.json new file mode 100644 index 0000000000..f1b7c156e6 --- /dev/null +++ b/docs/_sidebar.json @@ -0,0 +1,309 @@ +[ + { + "text": "Tutorial", + "items": [ + { "text": "Introduction", "link": "/newbs" }, + { "text": "Setup", "link": "/newbs_getting_started" }, + { "text": "Building Your First Firmware", "link": "/newbs_building_firmware" }, + { "text": "Flashing Firmware", "link": "/newbs_flashing" }, + { "text": "Getting Help/Support", "link": "/support" }, + { "text": "External Userspace", "link": "/newbs_external_userspace" }, + { "text": "Other Resources", "link": "/newbs_learn_more_resources" }, + { "text": "Syllabus", "link": "/syllabus" } + ] + }, + { + "text": "FAQs", + "items": [ + { "text": "General FAQ", "link": "/faq_general" }, + { "text": "Build/Compile QMK", "link": "/faq_build" }, + { "text": "Troubleshooting QMK", "link": "/faq_misc" }, + { "text": "Debugging QMK", "link": "/faq_debug" }, + { "text": "Keymap FAQ", "link": "/faq_keymap" }, + { "text": "Squeezing Space from AVR", "link": "/squeezing_avr" }, + { "text": "Glossary", "link": "/reference_glossary" } + ] + }, + { + "text": "Configurator", + "items": [ + { "text": "Overview", "link": "/newbs_building_firmware_configurator" }, + { "text": "Step by Step", "link": "/configurator_step_by_step" }, + { "text": "Troubleshooting", "link": "/configurator_troubleshooting" }, + { "text": "Architecture", "link": "/configurator_architecture" }, + { + "text": "QMK API", + "items": [ + { "text": "Overview", "link": "/api_overview" }, + { "text": "API Documentation", "link": "/api_docs" }, + { "text": "Keyboard Support", "link": "/reference_configurator_support" }, + { "text": "Adding Default Keymaps", "link": "/configurator_default_keymaps" } + ] + } + ] + }, + { + "text": "CLI", + "items": [ + { "text": "Overview", "link": "/cli" }, + { "text": "Configuration", "link": "/cli_configuration" }, + { "text": "Commands", "link": "/cli_commands" }, + { "text": "Tab Completion", "link": "/cli_tab_complete" } + ] + }, + { + "text": "Using QMK", + "items": [ + { + "text": "Guides", + "items": [ + { "text": "Customizing Functionality", "link": "/custom_quantum_functions" }, + { "text": "Driver Installation with Zadig", "link": "/driver_installation_zadig" }, + { "text": "Keymap Overview", "link": "/keymap" }, + { + "text": "Development Environments", + "items": [{ "text": "Docker Guide", "link": "/getting_started_docker" }] + }, + { + "text": "Flashing", + "items": [ + { "text": "Flashing", "link": "/flashing" }, + { "text": "Flashing ATmega32A (ps2avrgb)", "link": "/flashing_bootloadhid" } + ] + }, + { + "text": "IDEs", + "items": [ + { "text": "Using Eclipse with QMK", "link": "/other_eclipse" }, + { "text": "Using VSCode with QMK", "link": "/other_vscode" } + ] + }, + { + "text": "Git Best Practices", + "items": [ + { "text": "Introduction", "link": "/newbs_git_best_practices" }, + { "text": "Your Fork", "link": "/newbs_git_using_your_master_branch" }, + { "text": "Merge Conflicts", "link": "/newbs_git_resolving_merge_conflicts" }, + { "text": "Fixing Your Branch", "link": "/newbs_git_resynchronize_a_branch" } + ] + } + ] + }, + { + "text": "Simple Keycodes", + "items": [ + { "text": "Full List", "link": "/keycodes" }, + { "text": "Basic Keycodes", "link": "/keycodes_basic" }, + { "text": "Language-Specific Keycodes", "link": "/reference_keymap_extras" }, + { "text": "Modifier Keys", "link": "/feature_advanced_keycodes" }, + { "text": "Quantum Keycodes", "link": "/quantum_keycodes" }, + { "text": "Magic Keycodes", "link": "/keycodes_magic" } + ] + }, + { + "text": "Advanced Keycodes", + "items": [ + { "text": "Command", "link": "/feature_command" }, + { "text": "Dynamic Macros", "link": "/feature_dynamic_macros" }, + { "text": "Grave Escape", "link": "/feature_grave_esc" }, + { "text": "Leader Key", "link": "/feature_leader_key" }, + { "text": "Mod-Tap", "link": "/mod_tap" }, + { "text": "Macros", "link": "/feature_macros" }, + { "text": "Mouse Keys", "link": "/feature_mouse_keys" }, + { "text": "Programmable Button", "link": "/feature_programmable_button" }, + { "text": "Repeat Key", "link": "/feature_repeat_key" }, + { "text": "Space Cadet Shift", "link": "/feature_space_cadet" }, + { "text": "US ANSI Shifted Keys", "link": "/keycodes_us_ansi_shifted" } + ] + }, + { + "text": "Software Features", + "items": [ + { "text": "Auto Shift", "link": "/feature_auto_shift" }, + { "text": "Autocorrect", "link": "/feature_autocorrect" }, + { "text": "Caps Word", "link": "/feature_caps_word" }, + { "text": "Combos", "link": "/feature_combo" }, + { "text": "Debounce API", "link": "/feature_debounce_type" }, + { "text": "Digitizer", "link": "/feature_digitizer" }, + { "text": "EEPROM", "link": "/feature_eeprom" }, + { "text": "Key Lock", "link": "/feature_key_lock" }, + { "text": "Key Overrides", "link": "/feature_key_overrides" }, + { "text": "Layers", "link": "/feature_layers" }, + { "text": "One Shot Keys", "link": "/one_shot_keys" }, + { "text": "OS Detection", "link": "/feature_os_detection" }, + { "text": "Raw HID", "link": "/feature_rawhid" }, + { "text": "Secure", "link": "/feature_secure" }, + { "text": "Send String", "link": "/feature_send_string" }, + { "text": "Sequencer", "link": "/feature_sequencer" }, + { "text": "Swap Hands", "link": "/feature_swap_hands" }, + { "text": "Tap Dance", "link": "/feature_tap_dance" }, + { "text": "Tap-Hold Configuration", "link": "/tap_hold" }, + { "text": "Tri Layer", "link": "/feature_tri_layer" }, + { "text": "Unicode", "link": "/feature_unicode" }, + { "text": "Userspace", "link": "/feature_userspace" }, + { "text": "WPM Calculation", "link": "/feature_wpm" } + ] + }, + { + "text": "Hardware Features", + "items": [ + { + "text": "Displays", + "items": [ + { + "text": "Quantum Painter", + "link": "quantum_painter", + "items": [ + { "text": "Quantum Painter LVGL Integration", "link": "/quantum_painter_lvgl" } + ] + }, + { "text": "HD44780 LCD Driver", "link": "/feature_hd44780" }, + { "text": "ST7565 LCD Driver", "link": "/feature_st7565" }, + { "text": "OLED Driver", "link": "/feature_oled_driver" } + ] + }, + { + "text": "Lighting", + "items": [ + { "text": "Backlight", "link": "/feature_backlight" }, + { "text": "LED Matrix", "link": "/feature_led_matrix" }, + { "text": "RGB Lighting", "link": "/feature_rgblight" }, + { "text": "RGB Matrix", "link": "/feature_rgb_matrix" } + ] + }, + { "text": "Audio", "link": "/feature_audio" }, + { "text": "Bluetooth", "link": "/feature_bluetooth" }, + { "text": "Bootmagic Lite", "link": "/feature_bootmagic" }, + { "text": "Converters", "link": "/feature_converters" }, + { "text": "Custom Matrix", "link": "/custom_matrix" }, + { "text": "DIP Switch", "link": "/feature_dip_switch" }, + { "text": "Encoders", "link": "/feature_encoders" }, + { "text": "Haptic Feedback", "link": "/feature_haptic_feedback" }, + { "text": "Joystick", "link": "/feature_joystick" }, + { "text": "LED Indicators", "link": "/feature_led_indicators" }, + { "text": "MIDI", "link": "/feature_midi" }, + { "text": "Pointing Device", "link": "/feature_pointing_device" }, + { "text": "PS/2 Mouse", "link": "/feature_ps2_mouse" }, + { "text": "Split Keyboard", "link": "/feature_split_keyboard" }, + { "text": "Stenography", "link": "/feature_stenography" } + ] + }, + { + "text": "Keyboard Building", + "items": [ + { "text": "Easy Maker for One Offs", "link": "/easy_maker" }, + { "text": "Porting Keyboards", "link": "/porting_your_keyboard_to_qmk" }, + { "text": "Hand Wiring Guide", "link": "/hand_wire" }, + { "text": "ISP Flashing Guide", "link": "/isp_flashing_guide" } + ] + } + ] + }, + { + "text": "Developing QMK", + "items": [ + { "text": "PR Checklist", "link": "/pr_checklist" }, + { + "text": "Breaking Changes", + "items": [ + { "text": "Overview", "link": "/breaking_changes" }, + { "text": "My Pull Request Was Flagged", "link": "/breaking_changes_instructions" }, + { + "text": "Most Recent ChangeLog", + "link": "/ChangeLog/20240526" + }, + { "text": "Past Breaking Changes", "link": "/breaking_changes_history" } + ] + }, + + { + "text": "C Development", + "items": [ + { "text": "ARM Debugging Guide", "link": "/arm_debugging" }, + { "text": "Coding Conventions", "link": "/coding_conventions_c" }, + { "text": "Compatible Microcontrollers", "link": "/compatible_microcontrollers" }, + { + "text": "Drivers", + "link": "hardware_drivers", + "items": [ + { "text": "ADC Driver", "link": "/adc_driver" }, + { "text": "APA102 Driver", "link": "/apa102_driver" }, + { "text": "Audio Driver", "link": "/audio_driver" }, + { "text": "I2C Driver", "link": "/i2c_driver" }, + { "text": "SPI Driver", "link": "/spi_driver" }, + { "text": "WS2812 Driver", "link": "/ws2812_driver" }, + { "text": "EEPROM Driver", "link": "/eeprom_driver" }, + { "text": "Flash Driver", "link": "/flash_driver" }, + { "text": "'serial' Driver", "link": "/serial_driver" }, + { "text": "UART Driver", "link": "/uart_driver" } + ] + }, + { "text": "GPIO Controls", "link": "/gpio_control" }, + { "text": "Keyboard Guidelines", "link": "/hardware_keyboard_guidelines" } + ] + }, + + { + "text": "Python Development", + "items": [ + { "text": "Coding Conventions", "link": "/coding_conventions_python" }, + { "text": "QMK CLI Development", "link": "/cli_development" } + ] + }, + + { + "text": "Configurator Development", + "items": [ + { + "text": "QMK API", + "items": [ + { "text": "Development Environment", "link": "/api_development_environment" }, + { "text": "Architecture Overview", "link": "/api_development_overview" } + ] + } + ] + }, + + { + "text": "Hardware Platform Development", + "items": [ + { + "text": "Arm/ChibiOS", + "items": [ + { "text": "Selecting an MCU", "link": "/platformdev_selecting_arm_mcu" }, + { "text": "Early initialization", "link": "/platformdev_chibios_earlyinit" }, + { "text": "Raspberry Pi RP2040", "link": "/platformdev_rp2040" }, + { "text": "Proton C", "link": "/platformdev_proton_c" }, + { "text": "WeAct Blackpill F4x1", "link": "/platformdev_blackpill_f4x1" } + ] + } + ] + }, + + { + "text": "QMK Reference", + "items": [ + { "text": "Contributing to QMK", "link": "/contributing" }, + { "text": "Config Options", "link": "/config_options" }, + { "text": "Data Driven Configuration", "link": "/data_driven_config" }, + { "text": "Make Documentation", "link": "/getting_started_make_guide" }, + { "text": "Documentation Best Practices", "link": "/documentation_best_practices" }, + { "text": "Documentation Templates", "link": "/documentation_templates" }, + { "text": "Community Layouts", "link": "/feature_layouts" }, + { "text": "Unit Testing", "link": "/unit_testing" }, + { "text": "Useful Functions", "link": "/ref_functions" }, + { "text": "info.json Format", "link": "/reference_info_json" } + ] + }, + + { + "text": "For a Deeper Understanding", + "items": [ + { "text": "How Keyboards Work", "link": "/how_keyboards_work" }, + { "text": "How a Matrix Works", "link": "/how_a_matrix_works" }, + { "text": "Understanding QMK", "link": "/understanding_qmk" } + ] + } + ] + } +] diff --git a/docs/_summary.md b/docs/_summary.md deleted file mode 100644 index adf48cec85..0000000000 --- a/docs/_summary.md +++ /dev/null @@ -1,204 +0,0 @@ -* Tutorial - * [Introduction](newbs.md) - * [Setup](newbs_getting_started.md) - * [Building Your First Firmware](newbs_building_firmware.md) - * [Flashing Firmware](newbs_flashing.md) - * [Getting Help/Support](support.md) - * [External Userspace](newbs_external_userspace.md) - * [Other Resources](newbs_learn_more_resources.md) - * [Syllabus](syllabus.md) - -* FAQs - * [General FAQ](faq_general.md) - * [Build/Compile QMK](faq_build.md) - * [Troubleshooting QMK](faq_misc.md) - * [Debugging QMK](faq_debug.md) - * [Keymap FAQ](faq_keymap.md) - * [Squeezing Space from AVR](squeezing_avr.md) - * [Glossary](reference_glossary.md) - -* Configurator - * [Overview](newbs_building_firmware_configurator.md) - * [Step by Step](configurator_step_by_step.md) - * [Troubleshooting](configurator_troubleshooting.md) - * [Architecture](configurator_architecture.md) - * QMK API - * [Overview](api_overview.md) - * [API Documentation](api_docs.md) - * [Keyboard Support](reference_configurator_support.md) - * [Adding Default Keymaps](configurator_default_keymaps.md) - -* CLI - * [Overview](cli.md) - * [Configuration](cli_configuration.md) - * [Commands](cli_commands.md) - * [Tab Completion](cli_tab_complete.md) - -* Using QMK - * Guides - * [Customizing Functionality](custom_quantum_functions.md) - * [Driver Installation with Zadig](driver_installation_zadig.md) - * [Keymap Overview](keymap.md) - * Development Environments - * [Docker Guide](getting_started_docker.md) - * Flashing - * [Flashing](flashing.md) - * [Flashing ATmega32A (ps2avrgb)](flashing_bootloadhid.md) - * IDEs - * [Using Eclipse with QMK](other_eclipse.md) - * [Using VSCode with QMK](other_vscode.md) - * Git Best Practices - * [Introduction](newbs_git_best_practices.md) - * [Your Fork](newbs_git_using_your_master_branch.md) - * [Merge Conflicts](newbs_git_resolving_merge_conflicts.md) - * [Fixing Your Branch](newbs_git_resynchronize_a_branch.md) - - * Simple Keycodes - * [Full List](keycodes.md) - * [Basic Keycodes](keycodes_basic.md) - * [Language-Specific Keycodes](reference_keymap_extras.md) - * [Modifier Keys](feature_advanced_keycodes.md) - * [Quantum Keycodes](quantum_keycodes.md) - * [Magic Keycodes](keycodes_magic.md) - - * Advanced Keycodes - * [Command](feature_command.md) - * [Dynamic Macros](feature_dynamic_macros.md) - * [Grave Escape](feature_grave_esc.md) - * [Leader Key](feature_leader_key.md) - * [Mod-Tap](mod_tap.md) - * [Macros](feature_macros.md) - * [Mouse Keys](feature_mouse_keys.md) - * [Programmable Button](feature_programmable_button.md) - * [Repeat Key](feature_repeat_key.md) - * [Space Cadet Shift](feature_space_cadet.md) - * [US ANSI Shifted Keys](keycodes_us_ansi_shifted.md) - - * Software Features - * [Auto Shift](feature_auto_shift.md) - * [Autocorrect](feature_autocorrect.md) - * [Caps Word](feature_caps_word.md) - * [Combos](feature_combo.md) - * [Debounce API](feature_debounce_type.md) - * [Digitizer](feature_digitizer.md) - * [EEPROM](feature_eeprom.md) - * [Key Lock](feature_key_lock.md) - * [Key Overrides](feature_key_overrides.md) - * [Layers](feature_layers.md) - * [One Shot Keys](one_shot_keys.md) - * [OS Detection](feature_os_detection.md) - * [Raw HID](feature_rawhid.md) - * [Secure](feature_secure.md) - * [Send String](feature_send_string.md) - * [Sequencer](feature_sequencer.md) - * [Swap Hands](feature_swap_hands.md) - * [Tap Dance](feature_tap_dance.md) - * [Tap-Hold Configuration](tap_hold.md) - * [Tri Layer](feature_tri_layer.md) - * [Unicode](feature_unicode.md) - * [Userspace](feature_userspace.md) - * [WPM Calculation](feature_wpm.md) - - * Hardware Features - * Displays - * [Quantum Painter](quantum_painter.md) - * [Quantum Painter LVGL Integration](quantum_painter_lvgl.md) - * [HD44780 LCD Driver](feature_hd44780.md) - * [ST7565 LCD Driver](feature_st7565.md) - * [OLED Driver](feature_oled_driver.md) - * Lighting - * [Backlight](feature_backlight.md) - * [LED Matrix](feature_led_matrix.md) - * [RGB Lighting](feature_rgblight.md) - * [RGB Matrix](feature_rgb_matrix.md) - * [Audio](feature_audio.md) - * [Bluetooth](feature_bluetooth.md) - * [Bootmagic Lite](feature_bootmagic.md) - * [Converters](feature_converters.md) - * [Custom Matrix](custom_matrix.md) - * [DIP Switch](feature_dip_switch.md) - * [Encoders](feature_encoders.md) - * [Haptic Feedback](feature_haptic_feedback.md) - * [Joystick](feature_joystick.md) - * [LED Indicators](feature_led_indicators.md) - * [MIDI](feature_midi.md) - * [Pointing Device](feature_pointing_device.md) - * [PS/2 Mouse](feature_ps2_mouse.md) - * [Split Keyboard](feature_split_keyboard.md) - * [Stenography](feature_stenography.md) - - * Keyboard Building - * [Easy Maker for One Offs](easy_maker.md) - * [Porting Keyboards](porting_your_keyboard_to_qmk.md) - * [Hand Wiring Guide](hand_wire.md) - * [ISP Flashing Guide](isp_flashing_guide.md) - -* Developing QMK - * [PR Checklist](pr_checklist.md) - * Breaking Changes - * [Overview](breaking_changes.md) - * [My Pull Request Was Flagged](breaking_changes_instructions.md) - * [Most Recent ChangeLog](ChangeLog/20240526.md "QMK v0.25.0 - 2024 May 26") - * [Past Breaking Changes](breaking_changes_history.md) - - * C Development - * [ARM Debugging Guide](arm_debugging.md) - * [Coding Conventions](coding_conventions_c.md) - * [Compatible Microcontrollers](compatible_microcontrollers.md) - * [Drivers](hardware_drivers.md) - * [ADC Driver](adc_driver.md) - * [APA102 Driver](apa102_driver.md) - * [Audio Driver](audio_driver.md) - * [I2C Driver](i2c_driver.md) - * [SPI Driver](spi_driver.md) - * [WS2812 Driver](ws2812_driver.md) - * [EEPROM Driver](eeprom_driver.md) - * [Flash Driver](flash_driver.md) - * ['serial' Driver](serial_driver.md) - * [UART Driver](uart_driver.md) - * [GPIO Controls](gpio_control.md) - * [Keyboard Guidelines](hardware_keyboard_guidelines.md) - - * Python Development - * [Coding Conventions](coding_conventions_python.md) - * [QMK CLI Development](cli_development.md) - - * Configurator Development - * QMK API - * [Development Environment](api_development_environment.md) - * [Architecture Overview](api_development_overview.md) - - * Hardware Platform Development - * Arm/ChibiOS - * [Selecting an MCU](platformdev_selecting_arm_mcu.md) - * [Early initialization](platformdev_chibios_earlyinit.md) - * [Raspberry Pi RP2040](platformdev_rp2040.md) - * [Proton C](platformdev_proton_c.md) - * [WeAct Blackpill F4x1](platformdev_blackpill_f4x1.md) - - * QMK Reference - * [Contributing to QMK](contributing.md) - * [Translating the QMK Docs](translating.md) - * [Config Options](config_options.md) - * [Data Driven Configuration](data_driven_config.md) - * [Make Documentation](getting_started_make_guide.md) - * [Documentation Best Practices](documentation_best_practices.md) - * [Documentation Templates](documentation_templates.md) - * [Community Layouts](feature_layouts.md) - * [Unit Testing](unit_testing.md) - * [Useful Functions](ref_functions.md) - * [info.json Format](reference_info_json.md) - - * For a Deeper Understanding - * [How Keyboards Work](how_keyboards_work.md) - * [How a Matrix Works](how_a_matrix_works.md) - * [Understanding QMK](understanding_qmk.md) - - * QMK Internals (In Progress) - * [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) diff --git a/docs/adc_driver.md b/docs/adc_driver.md index dd928e1e7f..a1ab5a5251 100644 --- a/docs/adc_driver.md +++ b/docs/adc_driver.md @@ -1,6 +1,6 @@ # 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). +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). This driver currently supports both AVR and a limited selection of ARM devices. The values returned are 10-bit integers (0-1023) mapped between 0V and VCC (usually 5V or 3.3V for AVR, 3.3V only for ARM), however on ARM there is more flexibility in control of operation through `#define`s if you need more precision. diff --git a/docs/apa102_driver.md b/docs/apa102_driver.md index 1da2de6ca3..0f905e3f18 100644 --- a/docs/apa102_driver.md +++ b/docs/apa102_driver.md @@ -1,10 +1,10 @@ -# APA102 Driver :id=apa102-driver +# APA102 Driver {#apa102-driver} -This driver provides support for APA102 addressable RGB LEDs. They are similar to the [WS2812](ws2812_driver.md) LEDs, but have increased data and refresh rates. +This driver provides support for APA102 addressable RGB LEDs. They are similar to the [WS2812](ws2812_driver) LEDs, but have increased data and refresh rates. -## Usage :id=usage +## Usage {#usage} -In most cases, the APA102 driver code is automatically included if you are using either the [RGBLight](feature_rgblight.md) or [RGB Matrix](feature_rgb_matrix.md) feature with the `apa102` driver set, and you would use those APIs instead. +In most cases, the APA102 driver code is automatically included if you are using either the [RGBLight](feature_rgblight) or [RGB Matrix](feature_rgb_matrix) feature with the `apa102` driver set, and you would use those APIs instead. However, if you need to use the driver standalone, add the following to your `rules.mk`: @@ -14,7 +14,7 @@ APA102_DRIVER_REQUIRED = yes You can then call the APA102 API by including `apa102.h` in your code. -## Basic Configuration :id=basic-configuration +## Basic Configuration {#basic-configuration} Add the following to your `config.h`: @@ -24,13 +24,13 @@ Add the following to your `config.h`: |`APA102_CI_PIN` |*Not defined*|The GPIO pin connected to the CI pin of the first LED in the chain| |`APA102_DEFAULT_BRIGHTNESS`|`31` |The default global brightness level of the LEDs, from 0 to 31 | -## API :id=api +## API {#api} ### `void apa102_setleds(rgb_led_t *start_led, uint16_t num_leds)` Send RGB data to the APA102 LED chain. -#### Arguments :id=api-apa102-setleds-arguments +#### Arguments {#api-apa102-setleds-arguments} - `rgb_led_t *start_led` A pointer to the LED array. @@ -43,7 +43,7 @@ Send RGB data to the APA102 LED chain. Set the global brightness. -#### Arguments :id=api-apa102-set-brightness-arguments +#### Arguments {#api-apa102-set-brightness-arguments} - `uint8_t brightness` The brightness level to set, from 0 to 31. diff --git a/docs/api_docs.md b/docs/api_docs.md index 3324bc545b..f4ba19c42a 100644 --- a/docs/api_docs.md +++ b/docs/api_docs.md @@ -67,7 +67,7 @@ Once your compile job has finished you'll check the `result` key. The value of t * `firmware_source_url`: A list of URLs for the full firmware source code * `output`: The stdout and stderr for this compile job. Errors will be found here. -## Constants :id=qmk-constants +## Constants {#qmk-constants} If you're writing a tool that leverages constants used within QMK, the API is used to publish "locked-in" versions of those constants in order to ensure that any third-party tooling has a canonical set of information to work with. @@ -81,9 +81,13 @@ $ curl https://keyboards.develop.qmk.fm/v1/constants_metadata.json # For `develo {"last_updated": "2022-11-26 12:00:00 GMT", "constants": {"keycodes": ["0.0.1", "0.0.2"]}} ``` -!> Versions exported by the `master` endpoint are locked-in. Any extra versions that exist on the `develop` endpoint which don't exist in `master` are subject to change. +::: warning +Versions exported by the `master` endpoint are locked-in. Any extra versions that exist on the `develop` endpoint which don't exist in `master` are subject to change. +::: -?> Only keycodes are currently published, but over time all other "externally visible" IDs are expected to appear on these endpoints. +::: tip +Only keycodes are currently published, but over time all other "externally visible" IDs are expected to appear on these endpoints. +::: To retrieve the constants associated with a subsystem, the endpoint format is as follows: ``` diff --git a/docs/api_overview.md b/docs/api_overview.md index f851a48a4a..c8ec42e947 100644 --- a/docs/api_overview.md +++ b/docs/api_overview.md @@ -4,12 +4,12 @@ The QMK API provides an asynchronous API that Web and GUI tools can use to compi ## App Developers -If you are an app developer interested in using this API in your application you should head over to [Using The API](api_docs.md). +If you are an app developer interested in using this API in your application you should head over to [Using The API](api_docs). ## Keyboard Maintainers -If you would like to enhance your keyboard's support in the QMK Compiler API head over to the [Keyboard Support](reference_configurator_support.md) section. +If you would like to enhance your keyboard's support in the QMK Compiler API head over to the [Keyboard Support](reference_configurator_support) section. ## Backend Developers -If you are interested in working on the API itself you should start by setting up a [Development Environment](api_development_environment.md), then check out [Hacking On The API](api_development_overview.md). +If you are interested in working on the API itself you should start by setting up a [Development Environment](api_development_environment), then check out [Hacking On The API](api_development_overview). diff --git a/docs/audio_driver.md b/docs/audio_driver.md index 03c0a824df..4a71b4f411 100644 --- a/docs/audio_driver.md +++ b/docs/audio_driver.md @@ -1,11 +1,11 @@ -# Audio Driver :id=audio-driver +# Audio Driver {#audio-driver} -The [Audio feature](feature_audio.md) breaks the hardware specifics out into separate, exchangeable driver units, with a common interface to the audio-"core" - which itself handles playing songs and notes while tracking their progress in an internal state, initializing/starting/stopping the driver as needed. +The [Audio feature](feature_audio) breaks the hardware specifics out into separate, exchangeable driver units, with a common interface to the audio-"core" - which itself handles playing songs and notes while tracking their progress in an internal state, initializing/starting/stopping the driver as needed. Not all MCUs support every available driver, either the platform-support is not there (yet?) or the MCU simply does not have the required hardware peripheral. -## AVR :id=avr +## AVR {#avr} Boards built around an Atmega32U4 can use two sets of PWM capable pins, each driving a separate speaker. The possible configurations are: @@ -23,7 +23,7 @@ AUDIO_DRIVER = pwm_hardware ``` -## ARM :id=arm +## ARM {#arm} For Arm based boards, QMK depends on ChibiOS - hence any MCU supported by the later is likely usable, as long as certain hardware peripherals are available. @@ -50,7 +50,7 @@ piezo speakers are marked with :one: for the first/primary and :two: for the sec -### DAC basic :id=dac-basic +### DAC basic {#dac-basic} The default driver for ARM boards, in absence of an overriding configuration. This driver needs one Timer per enabled/used DAC channel, to trigger conversion; and a third timer to trigger state updates with the audio-core. @@ -79,7 +79,9 @@ Additionally, in the board config, you'll want to make changes to enable the DAC #define STM32_GPT_USE_TIM8 TRUE ``` -?> Note: DAC1 (A4) uses TIM6, DAC2 (A5) uses TIM7, and the audio state timer uses TIM8 (configurable). +::: tip +Note: DAC1 (A4) uses TIM6, DAC2 (A5) uses TIM7, and the audio state timer uses TIM8 (configurable). +::: You can also change the timer used for the overall audio state by defining the driver. For instance: @@ -87,7 +89,7 @@ You can also change the timer used for the overall audio state by defining the d #define AUDIO_STATE_TIMER GPTD9 ``` -### DAC additive :id=dac-additive +### DAC additive {#dac-additive} only needs one timer (GPTD6, Tim6) to trigger the DAC unit to do a conversion; the audio state updates are in turn triggered during the DAC callback. @@ -131,7 +133,7 @@ There are a number of predefined quality settings that you can use, with "sane m | `AUDIO_DAC_QUALITY_VERY_HIGH` | `88200U` | `1` | `256U` | | `AUDIO_DAC_QUALITY_SANE_MINIMUM` | `16384U` | `8` | `64U` | -#### Notes on buffer size :id=buffer-size +#### Notes on buffer size {#buffer-size} By default, the buffer size attempts to keep to these constraints: @@ -162,7 +164,7 @@ You can lower the buffer size if you need a bit more space in your firmware, or ``` -### PWM hardware :id=pwm-hardware +### PWM hardware {#pwm-hardware} This driver uses the ChibiOS-PWM system to produce a square-wave on specific output pins that are connected to the PWM hardware. The hardware directly toggles the pin via its alternate function. See your MCU's data-sheet for which pin can be driven by what timer - looking for TIMx_CHy and the corresponding alternate function. @@ -205,7 +207,7 @@ You can also use the Complementary output (`TIMx_CHyN`) for PWM on supported con #define AUDIO_PWM_COMPLEMENTARY_OUTPUT ``` -### PWM software :id=pwm-software +### PWM software {#pwm-software} This driver uses the PWM callbacks from PWMD1 with TIM1_CH1 to toggle the selected AUDIO_PIN in software. During the same callback, with AUDIO_PIN_ALT_AS_NEGATIVE set, the AUDIO_PIN_ALT is toggled inversely to AUDIO_PIN. This is useful for setups that drive a piezo from two pins (instead of one and Gnd). @@ -217,7 +219,7 @@ You can also change the timer used for software PWM by defining the driver. For ``` -### Testing Notes :id=testing-notes +### Testing Notes {#testing-notes} While not an exhaustive list, the following table provides the scenarios that have been partially validated: diff --git a/docs/breaking_changes.md b/docs/breaking_changes.md index 1c0b1bafce..d72a8d4761 100644 --- a/docs/breaking_changes.md +++ b/docs/breaking_changes.md @@ -10,10 +10,10 @@ Practically, this means QMK merges the `develop` branch into the `master` branch ## What has been included in past Breaking Changes? -* [2024 May 26](ChangeLog/20240526.md) -* [2024 Feb 25](ChangeLog/20240225.md) -* [2023 Nov 26](ChangeLog/20231126.md) -* [Older Breaking Changes](breaking_changes_history.md) +* [2024 May 26](ChangeLog/20240526) +* [2024 Feb 25](ChangeLog/20240225) +* [2023 Nov 26](ChangeLog/20231126) +* [Older Breaking Changes](breaking_changes_history) ## When is the next Breaking Change? @@ -71,7 +71,7 @@ This section documents various processes we use when running the Breaking Change ### 1 Week Before Merge * `develop` is now closed to PR merges, only critical bugfixes may be included -* Announce that master will be closed from <2 Days Before> to -- message `@Breaking Changes Updates` on `#qmk_firmware` in Discord: +* Announce that master will be closed from `<2 Days Before>` to `` -- message `@Breaking Changes Updates` on `#qmk_firmware` in Discord: * `@Breaking Changes Updates -- Hey folks, last day for functional PRs to be merged into qmk_firmware for this breaking changes cycle is today. After that, we're handling bugfixes only.` ### 2 Days Before Merge @@ -136,7 +136,7 @@ This happens immediately after the previous `develop` branch is merged to `maste * Announce that both `master` and `develop` are now unlocked -- message `@Breaking Changes Updates` on `#qmk_firmware` in Discord: * `@Breaking Changes Updates -- Hey folks, develop has now been merged into master -- newest batch of changes are now available for everyone to use!` -* (Optional) [update ChibiOS + ChibiOS-Contrib on `develop`](chibios_upgrade_instructions.md) +* (Optional) [update ChibiOS + ChibiOS-Contrib on `develop`](chibios_upgrade_instructions) ### Set up Discord events for the next cycle diff --git a/docs/breaking_changes_history.md b/docs/breaking_changes_history.md index 6f0f25be0e..8c01e35e68 100644 --- a/docs/breaking_changes_history.md +++ b/docs/breaking_changes_history.md @@ -2,22 +2,22 @@ This page links to all previous changelogs from the QMK Breaking Changes process. -* [2024 May 26](ChangeLog/20240526.md) - version 0.25.0 -* [2024 Feb 25](ChangeLog/20240225.md) - version 0.24.0 -* [2023 Nov 26](ChangeLog/20231126.md) - version 0.23.0 -* [2023 Aug 27](ChangeLog/20230827.md) - version 0.22.0 -* [2023 May 28](ChangeLog/20230528.md) - version 0.21.0 -* [2023 Feb 26](ChangeLog/20230226.md) - version 0.20.0 -* [2022 Nov 26](ChangeLog/20221126.md) - version 0.19.0 -* [2022 Aug 27](ChangeLog/20220827.md) - version 0.18.0 -* [2022 May 28](ChangeLog/20220528.md) - version 0.17.0 -* [2022 Feb 26](ChangeLog/20220226.md) - version 0.16.0 -* [2021 Nov 27](ChangeLog/20211127.md) - version 0.15.0 -* [2021 Aug 28](ChangeLog/20210828.md) - version 0.14.0 -* [2021 May 29](ChangeLog/20210529.md) - version 0.13.0 -* [2021 Feb 27](ChangeLog/20210227.md) - version 0.12.0 -* [2020 Nov 28](ChangeLog/20201128.md) - version 0.11.0 -* [2020 Aug 29](ChangeLog/20200829.md) - version 0.10.0 -* [2020 May 30](ChangeLog/20200530.md) - version 0.9.0 -* [2020 Feb 29](ChangeLog/20200229.md) - version 0.8.0 -* [2019 Aug 30](ChangeLog/20190830.md) - version 0.7.0 +* [2024 May 26](ChangeLog/20240526) - version 0.25.0 +* [2024 Feb 25](ChangeLog/20240225) - version 0.24.0 +* [2023 Nov 26](ChangeLog/20231126) - version 0.23.0 +* [2023 Aug 27](ChangeLog/20230827) - version 0.22.0 +* [2023 May 28](ChangeLog/20230528) - version 0.21.0 +* [2023 Feb 26](ChangeLog/20230226) - version 0.20.0 +* [2022 Nov 26](ChangeLog/20221126) - version 0.19.0 +* [2022 Aug 27](ChangeLog/20220827) - version 0.18.0 +* [2022 May 28](ChangeLog/20220528) - version 0.17.0 +* [2022 Feb 26](ChangeLog/20220226) - version 0.16.0 +* [2021 Nov 27](ChangeLog/20211127) - version 0.15.0 +* [2021 Aug 28](ChangeLog/20210828) - version 0.14.0 +* [2021 May 29](ChangeLog/20210529) - version 0.13.0 +* [2021 Feb 27](ChangeLog/20210227) - version 0.12.0 +* [2020 Nov 28](ChangeLog/20201128) - version 0.11.0 +* [2020 Aug 29](ChangeLog/20200829) - version 0.10.0 +* [2020 May 30](ChangeLog/20200530) - version 0.9.0 +* [2020 Feb 29](ChangeLog/20200229) - version 0.8.0 +* [2019 Aug 30](ChangeLog/20190830) - version 0.7.0 diff --git a/docs/cli.md b/docs/cli.md index 0fa068dc7b..7d4c10cedd 100644 --- a/docs/cli.md +++ b/docs/cli.md @@ -1,14 +1,14 @@ -# QMK CLI :id=qmk-cli +# QMK CLI {#qmk-cli} -## Overview :id=overview +## Overview {#overview} The QMK CLI (command line interface) makes building and working with QMK keyboards easier. We have provided a number of commands to simplify and streamline tasks such as obtaining and compiling the QMK firmware, creating keymaps, and more. -### Requirements :id=requirements +### Requirements {#requirements} QMK requires Python 3.7 or greater. We try to keep the number of requirements small but you will also need to install the packages listed in [`requirements.txt`](https://github.com/qmk/qmk_firmware/blob/master/requirements.txt). These are installed automatically when you install the QMK CLI. -### Install Using Homebrew (macOS, some Linux) :id=install-using-homebrew +### Install Using Homebrew (macOS, some Linux) {#install-using-homebrew} If you have installed [Homebrew](https://brew.sh) you can tap and install QMK: @@ -18,7 +18,7 @@ export QMK_HOME='~/qmk_firmware' # Optional, set the location for `qmk_firmware` qmk setup # This will clone `qmk/qmk_firmware` and optionally set up your build environment ``` -### Install Using pip :id=install-using-easy_install-or-pip +### Install Using pip {#install-using-easy_install-or-pip} If your system is not listed above you can install QMK manually. First ensure that you have Python 3.7 (or later) installed and have installed pip. Then install QMK with this command: @@ -28,7 +28,7 @@ export QMK_HOME='~/qmk_firmware' # Optional, set the location for `qmk_firmware` qmk setup # This will clone `qmk/qmk_firmware` and optionally set up your build environment ``` -### Packaging For Other Operating Systems :id=packaging-for-other-operating-systems +### Packaging For Other Operating Systems {#packaging-for-other-operating-systems} We are looking for people to create and maintain a `qmk` package for more operating systems. If you would like to create a package for your OS please follow these guidelines: diff --git a/docs/cli_commands.md b/docs/cli_commands.md index e97af79d33..6f82d9c9de 100644 --- a/docs/cli_commands.md +++ b/docs/cli_commands.md @@ -86,7 +86,7 @@ qmk compile -j 0 -kb ## `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 `. Visit the [Flashing Firmware](flashing.md) guide for more details of the available bootloaders. +This command is similar to `qmk compile`, but can also target a bootloader. The bootloader is optional, and is set to `:flash` by default. To specify a different bootloader, use `-bl `. Visit the [Flashing Firmware](flashing) guide for more details of the available bootloaders. This command is directory aware. It will automatically fill in KEYBOARD and/or KEYMAP if you are in a keyboard or keymap directory. @@ -127,7 +127,7 @@ 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). +This command lets you configure the behavior of QMK. For the full `qmk config` documentation see [CLI Configuration](cli_configuration). **Usage**: @@ -703,30 +703,39 @@ Now open your dev environment and live a squiggly-free life. ## `qmk docs` -This command starts a local HTTP server which you can use for browsing or improving the docs. Default port is 8936. -Use the `-b`/`--browser` flag to automatically open the local webserver in your default browser. +This command starts a local HTTP server which you can use for browsing or improving the docs. Default port is 5173. -This command runs `docsify serve` if `docsify-cli` is installed (which provides live reload), otherwise Python's builtin HTTP server module will be used. +This command requires `node` and `yarn` to be installed as prerequisites, and provides live reload capability whilst editing. **Usage**: ``` -qmk docs [-b] [-p PORT] +usage: qmk docs [-h] + +options: + -h, --help show this help message and exit ``` ## `qmk generate-docs` -This command allows you to generate QMK documentation locally. It can be uses for general browsing or improving the docs. External tools such as [serve](https://www.npmjs.com/package/serve) can be used to browse the generated files. +This command allows you to generate QMK documentation locally. It can be uses for general browsing or improving the docs. +Use the `-s`/`--serve` flag to also serve the static site once built. Default port is 4173. + +This command requires `node` and `yarn` to be installed as prerequisites, and requires the operating system to support symlinks. **Usage**: ``` -qmk generate-docs +usage: qmk generate-docs [-h] [-s] + +options: + -h, --help show this help message and exit + -s, --serve Serves the generated docs once built. ``` ## `qmk generate-rgb-breathe-table` -This command generates a lookup table (LUT) header file for the [RGB Lighting](feature_rgblight.md) feature's breathing animation. Place this file in your keyboard or keymap directory as `rgblight_breathe_table.h` to override the default LUT in `quantum/rgblight/`. +This command generates a lookup table (LUT) header file for the [RGB Lighting](feature_rgblight) feature's breathing animation. Place this file in your keyboard or keymap directory as `rgblight_breathe_table.h` to override the default LUT in `quantum/rgblight/`. **Usage**: @@ -793,15 +802,15 @@ Run single test: ## `qmk painter-convert-graphics` -This command converts images to a format usable by QMK, i.e. the QGF File Format. See the [Quantum Painter](quantum_painter.md?id=quantum-painter-cli) documentation for more information on this command. +This command converts images to a format usable by QMK, i.e. the QGF File Format. See the [Quantum Painter](quantum_painter#quantum-painter-cli) documentation for more information on this command. ## `qmk painter-make-font-image` -This command converts a TTF font to an intermediate format for editing, before converting to the QFF File Format. See the [Quantum Painter](quantum_painter.md?id=quantum-painter-cli) documentation for more information on this command. +This command converts a TTF font to an intermediate format for editing, before converting to the QFF File Format. See the [Quantum Painter](quantum_painter#quantum-painter-cli) documentation for more information on this command. ## `qmk painter-convert-font-image` -This command converts an intermediate font image to the QFF File Format. See the [Quantum Painter](quantum_painter.md?id=quantum-painter-cli) documentation for more information on this command. +This command converts an intermediate font image to the QFF File Format. See the [Quantum Painter](quantum_painter#quantum-painter-cli) documentation for more information on this command. ## `qmk test-c` diff --git a/docs/cli_development.md b/docs/cli_development.md index 8d4ee62535..e94884de2e 100644 --- a/docs/cli_development.md +++ b/docs/cli_development.md @@ -202,7 +202,9 @@ We use nose2, flake8, and yapf to test, lint, and format code. You can use the ` 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. +::: tip +Tip- Many editors can use yapf as a plugin to automatically format code as you type. +::: ## Testing Details diff --git a/docs/coding_conventions_python.md b/docs/coding_conventions_python.md index 1ed27ee46a..502ee9102e 100644 --- a/docs/coding_conventions_python.md +++ b/docs/coding_conventions_python.md @@ -15,7 +15,7 @@ Most of our style follows PEP8 with some local modifications to make things less # YAPF -You can use [yapf](https://github.com/google/yapf) to style your code. We provide a config in [setup.cfg](setup.cfg). +You can use [yapf](https://github.com/google/yapf) to style your code. We provide a config in [setup.cfg](https://github.com/qmk/qmk_firmware/blob/master/setup.cfg). # Imports diff --git a/docs/compatible_microcontrollers.md b/docs/compatible_microcontrollers.md index 197033f78b..785aee30d5 100644 --- a/docs/compatible_microcontrollers.md +++ b/docs/compatible_microcontrollers.md @@ -73,7 +73,7 @@ You can also use any ARM chip with USB that [ChibiOS](https://www.chibios.org) s * [RP2040](https://www.raspberrypi.com/documentation/microcontrollers/rp2040.html) -For a detailed overview about the RP2040 support by QMK see the [dedicated RP2040 page](platformdev_rp2040.md). +For a detailed overview about the RP2040 support by QMK see the [dedicated RP2040 page](platformdev_rp2040). ## Atmel ATSAM diff --git a/docs/config_options.md b/docs/config_options.md index 046429a587..236649a0ea 100644 --- a/docs/config_options.md +++ b/docs/config_options.md @@ -6,11 +6,13 @@ There are three main types of configuration files in QMK: * `config.h`, which contains various preprocessor directives (`#define`, `#ifdef`) * `rules.mk`, which contains additional variables -* `info.json`, which is utilized for [data-driven configuration](https://docs.qmk.fm/#/data_driven_config) +* `info.json`, which is utilized for [data-driven configuration](data_driven_config) This page will only discuss the first two types, `config.h` and `rules.mk`. -?> While not all settings have data-driven equivalents yet, keyboard makers are encouraged to utilize the `info.json` file to set the metadata for their boards when possible. See the [`info.json` Format](https://docs.qmk.fm/#/reference_info_json) page for more details. +::: tip +While not all settings have data-driven equivalents yet, keyboard makers are encouraged to utilize the `info.json` file to set the metadata for their boards when possible. See the [`info.json` Format](reference_info_json) page for more details. +::: These files exist at various levels in QMK and all files of the same type are combined to build the final configuration. The levels, from lowest priority to highest priority, are: @@ -56,10 +58,10 @@ This is a C header file that is one of the first things included, and will persi * the number of columns in your keyboard's matrix * `#define MATRIX_ROW_PINS { D0, D5, B5, B6 }` * pins of the rows, from top to bottom - * may be omitted by the keyboard designer if matrix reads are handled in an alternate manner. See [low-level matrix overrides](custom_quantum_functions.md?id=low-level-matrix-overrides) for more information. + * may be omitted by the keyboard designer if matrix reads are handled in an alternate manner. See [low-level matrix overrides](custom_quantum_functions#low-level-matrix-overrides) for more information. * `#define MATRIX_COL_PINS { F1, F0, B0, C7, F4, F5, F6, F7, D4, D6, B4, D7 }` * pins of the columns, from left to right - * may be omitted by the keyboard designer if matrix reads are handled in an alternate manner. See [low-level matrix overrides](custom_quantum_functions.md?id=low-level-matrix-overrides) for more information. + * may be omitted by the keyboard designer if matrix reads are handled in an alternate manner. See [low-level matrix overrides](custom_quantum_functions#low-level-matrix-overrides) for more information. * `#define MATRIX_IO_DELAY 30` * the delay in microseconds when between changing matrix pin state and reading values * `#define MATRIX_HAS_GHOST` @@ -151,26 +153,26 @@ If you define these options you will enable the associated feature, which may in * enables handling for per key `TAPPING_TERM` settings * `#define RETRO_TAPPING` * tap anyway, even after `TAPPING_TERM`, if there was no other key interruption between press and release - * See [Retro Tapping](tap_hold.md#retro-tapping) for details + * See [Retro Tapping](tap_hold#retro-tapping) for details * `#define RETRO_TAPPING_PER_KEY` * enables handling for per key `RETRO_TAPPING` settings * `#define TAPPING_TOGGLE 2` * how many taps before triggering the toggle * `#define PERMISSIVE_HOLD` * makes tap and hold keys trigger the hold if another key is pressed before releasing, even if it hasn't hit the `TAPPING_TERM` - * See [Permissive Hold](tap_hold.md#permissive-hold) for details + * See [Permissive Hold](tap_hold#permissive-hold) for details * `#define PERMISSIVE_HOLD_PER_KEY` * enabled handling for per key `PERMISSIVE_HOLD` settings * `#define QUICK_TAP_TERM 100` * tap-then-hold timing to use a dual role key to repeat keycode - * See [Quick Tap Term](tap_hold.md#quick-tap-term) + * See [Quick Tap Term](tap_hold#quick-tap-term) * Changes the timing of Tap Toggle functionality (`TT` or the One Shot Tap Toggle) * Defaults to `TAPPING_TERM` if not defined * `#define QUICK_TAP_TERM_PER_KEY` * enables handling for per key `QUICK_TAP_TERM` settings * `#define HOLD_ON_OTHER_KEY_PRESS` * selects the hold action of a dual-role key as soon as the tap of the dual-role key is interrupted by the press of another key. - * See "[hold on other key press](tap_hold.md#hold-on-other-key-press)" for details + * See "[hold on other key press](tap_hold#hold-on-other-key-press)" for details * `#define HOLD_ON_OTHER_KEY_PRESS_PER_KEY` * enables handling for per key `HOLD_ON_OTHER_KEY_PRESS` settings * `#define LEADER_TIMEOUT 300` @@ -205,7 +207,7 @@ If you define these options you will enable the associated feature, which may in * `#define TAP_HOLD_CAPS_DELAY 80` * Sets the delay for Tap Hold keys (`LT`, `MT`) when using `KC_CAPS_LOCK` keycode, as this has some special handling on MacOS. The value is in milliseconds, and defaults to 80 ms if not defined. For macOS, you may want to set this to 200 or higher. * `#define KEY_OVERRIDE_REPEAT_DELAY 500` - * Sets the key repeat interval for [key overrides](feature_key_overrides.md). + * Sets the key repeat interval for [key overrides](feature_key_overrides). * `#define LEGACY_MAGIC_HANDLING` * Enables magic configuration handling for advanced keycodes (such as Mod Tap and Layer Tap) @@ -215,14 +217,14 @@ If you define these options you will enable the associated feature, which may in * `#define WS2812_DI_PIN D7` * pin the DI on the WS2812 is hooked-up to * `#define RGBLIGHT_LAYERS` - * Lets you define [lighting layers](feature_rgblight.md?id=lighting-layers) that can be toggled on or off. Great for showing the current keyboard layer or caps lock state. + * Lets you define [lighting layers](feature_rgblight#lighting-layers) that can be toggled on or off. Great for showing the current keyboard layer or caps lock state. * `#define RGBLIGHT_MAX_LAYERS` - * Defaults to 8. Can be expanded up to 32 if more [lighting layers](feature_rgblight.md?id=lighting-layers) are needed. + * Defaults to 8. Can be expanded up to 32 if more [lighting layers](feature_rgblight#lighting-layers) are needed. * Note: Increasing the maximum will increase the firmware size and slow sync on split keyboards. * `#define RGBLIGHT_LAYER_BLINK` - * Adds ability to [blink](feature_rgblight.md?id=lighting-layer-blink) a lighting layer for a specified number of milliseconds (e.g. to acknowledge an action). + * Adds ability to [blink](feature_rgblight#lighting-layer-blink) a lighting layer for a specified number of milliseconds (e.g. to acknowledge an action). * `#define RGBLIGHT_LAYERS_OVERRIDE_RGB_OFF` - * If defined, then [lighting layers](feature_rgblight?id=overriding-rgb-lighting-onoff-status) will be shown even if RGB Light is off. + * If defined, then [lighting layers](feature_rgblight#overriding-rgb-lighting-onoff-status) will be shown even if RGB Light is off. * `#define RGBLIGHT_LED_COUNT 12` * number of LEDs * `#define RGBLIGHT_SPLIT` @@ -294,7 +296,7 @@ There are a few different ways to set handedness for split keyboards (listed in * `#define MATRIX_ROW_PINS_RIGHT { }` * `#define MATRIX_COL_PINS_RIGHT { }` * If you want to specify a different pinout for the right half than the left half, you can define `MATRIX_ROW_PINS_RIGHT`/`MATRIX_COL_PINS_RIGHT`. Currently, the size of `MATRIX_ROW_PINS` must be the same as `MATRIX_ROW_PINS_RIGHT` and likewise for the definition of columns. - * may be omitted by the keyboard designer if matrix reads are handled in an alternate manner. See [low-level matrix overrides](custom_quantum_functions.md?id=low-level-matrix-overrides) for more information. + * may be omitted by the keyboard designer if matrix reads are handled in an alternate manner. See [low-level matrix overrides](custom_quantum_functions#low-level-matrix-overrides) for more information. * `#define DIRECT_PINS_RIGHT { { F1, F0, B0, C7 }, { F4, F5, F6, F7 } }` * If you want to specify a different direct pinout for the right half than the left half, you can define `DIRECT_PINS_RIGHT`. Currently, the size of `DIRECT_PINS` must be the same as `DIRECT_PINS_RIGHT`. @@ -356,7 +358,7 @@ There are a few different ways to set handedness for split keyboards (listed in * `#define SPLIT_TRANSACTION_IDS_KB .....` * `#define SPLIT_TRANSACTION_IDS_USER .....` - * Allows for custom data sync with the slave when using the QMK-provided split transport. See [custom data sync between sides](feature_split_keyboard.md#custom-data-sync) for more information. + * Allows for custom data sync with the slave when using the QMK-provided split transport. See [custom data sync between sides](feature_split_keyboard#custom-data-sync) for more information. # The `rules.mk` File @@ -385,7 +387,7 @@ This is a [make](https://www.gnu.org/software/make/manual/make.html) file that i ... a.o c.o ... lib_b.a lib_d.a ... ``` * `LAYOUTS` - * A list of [layouts](feature_layouts.md) this keyboard supports. + * A list of [layouts](feature_layouts) this keyboard supports. * `LTO_ENABLE` * Enables Link Time Optimization (LTO) when compiling the keyboard. This makes the process take longer, but it can significantly reduce the compiled size (and since the firmware is small, the added time is not noticeable). @@ -404,7 +406,7 @@ This is a [make](https://www.gnu.org/software/make/manual/make.html) file that i * `bootloadhid` * `usbasploader` -## Feature Options :id=feature-options +## Feature Options {#feature-options} Use these to enable or disable building certain features. The more you have enabled the bigger your firmware will be, and you run the risk of building a firmware too large for your MCU. @@ -451,7 +453,7 @@ 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. * `DEFERRED_EXEC_ENABLE` - * Enables deferred executor support -- timed delays before callbacks are invoked. See [deferred execution](custom_quantum_functions.md#deferred-execution) for more information. + * Enables deferred executor support -- timed delays before callbacks are invoked. See [deferred execution](custom_quantum_functions#deferred-execution) for more information. * `DYNAMIC_TAPPING_TERM_ENABLE` * Allows to configure the global tapping term on the fly. diff --git a/docs/configurator_default_keymaps.md b/docs/configurator_default_keymaps.md index 4d3c1b8f47..40304dc57b 100644 --- a/docs/configurator_default_keymaps.md +++ b/docs/configurator_default_keymaps.md @@ -1,9 +1,9 @@ -# Adding Default Keymaps to QMK Configurator :id=adding-default-keymaps +# Adding Default Keymaps to QMK Configurator {#adding-default-keymaps} This page covers how to add a default keymap for a keyboard to QMK Configurator. -## Technical Information :id=technical-information +## Technical Information {#technical-information} QMK Configurator uses JSON as its native file format for keymaps. As much as possible, these should be kept such that they behave the same as running `make :default` from `qmk_firmware`. @@ -27,7 +27,7 @@ f14629ed1cd7c7ec9089604d64f29a99981558e8 Remove/migrate action_get_macro()s from In this example, `f14629ed1cd7c7ec9089604d64f29a99981558e8` is the value that should be used for `commit`. -## Example :id=example +## Example {#example} If one wished to add a default keymap for the H87a by Hineybush, one would run the `git log` command above against the H87a's default keymap in `qmk_firmware`: @@ -96,9 +96,9 @@ The default keymap uses the `LAYOUT_all` macro, so that will be the value of the The white space in the `layers` arrays have no effect on the functionality of the keymap, but are used to make these files easier for humans to read. -## Caveats :id=caveats +## Caveats {#caveats} -### Layers can only be referenced by number :id=layer-references +### Layers can only be referenced by number {#layer-references} A common QMK convention is to name layers using a series of `#define`s, or an `enum` statement: @@ -112,11 +112,11 @@ enum layer_names { This works in C, but for Configurator, you *must* use the layer's numeric index – `MO(_FN)` would need to be `MO(2)` in the above example. -### No support for custom code of any kind :id=custom-code +### No support for custom code of any kind {#custom-code} Features that require adding functions to the keymap.c file, such as Tap Dance or Unicode, can not be compiled in Configurator **at all**. Even setting `TAP_DANCE_ENABLE = yes` in the `qmk_firmware` repository at the keyboard level will prevent Configurator from compiling **any** firmware for that keyboard. This is limited both by the API and the current spec of our JSON keymap format. -### Limited Support for Custom keycodes :id=custom-keycodes +### Limited Support for Custom keycodes {#custom-keycodes} There is a way to support custom keycodes: if the logic for a custom keycode is implemented at the keyboard level instead of the keymap level in qmk_firmware, that keycode *can* be used in Configurator and it *will* compile and work. Instead of using the following in your `keymap.c`: @@ -186,6 +186,6 @@ bool process_record_kb(uint16_t keycode, keyrecord_t *record) { Note the call to `process_record_user()` at the end. -## Additional Reading :id=additional-reading +## Additional Reading {#additional-reading} -For QMK Configurator to support your keyboard, your keyboard must be present in the `master` branch of the `qmk_firmware` repository. For instructions on this, please see [Supporting Your Keyboard in QMK Configurator](reference_configurator_support.md). +For QMK Configurator to support your keyboard, your keyboard must be present in the `master` branch of the `qmk_firmware` repository. For instructions on this, please see [Supporting Your Keyboard in QMK Configurator](reference_configurator_support). diff --git a/docs/configurator_step_by_step.md b/docs/configurator_step_by_step.md index c3cc2bfcdb..4da9ea04a2 100644 --- a/docs/configurator_step_by_step.md +++ b/docs/configurator_step_by_step.md @@ -6,11 +6,15 @@ This page describes the steps for building your firmware in QMK Configurator. Click the drop down box and select the keyboard you want to create a keymap for. -?> If your keyboard has several versions, make sure you select the correct one. +::: tip +If your keyboard has several versions, make sure you select the correct one. +::: I'll say that again because it's important: -!> **MAKE SURE YOU SELECT THE RIGHT VERSION!** +::: warning +**MAKE SURE YOU SELECT THE RIGHT VERSION!** +::: If your keyboard has been advertised to be powered by QMK but is not in the list, chances are a developer hasn't gotten to it yet or we haven't had a chance to merge it in yet. File an issue at [qmk_firmware](https://github.com/qmk/qmk_firmware/issues) requesting to support that particular keyboard, if there is no active [Pull Request](https://github.com/qmk/qmk_firmware/pulls?q=is%3Aopen+is%3Apr+label%3Akeyboard) for it. There are also QMK powered keyboards that are in their manufacturer's own GitHub accounts. Double check for that as well. @@ -18,13 +22,17 @@ If your keyboard has been advertised to be powered by QMK but is not in the list Choose the layout that best represents the keymap you want to create. Some keyboards do not have enough layouts or correct layouts defined yet. They will be supported in the future. -!> Sometimes there isn't a layout that supports your exact build. In that case select `LAYOUT_all`. +::: warning +Sometimes there isn't a layout that supports your exact build. In that case select `LAYOUT_all`. +::: ## Step 3: Name Your Keymap Call this keymap what you want. -?> If you are running into issues when compiling, it may be worth changing this name, as it may already exist in the QMK Firmware repo. +::: tip +If you are running into issues when compiling, it may be worth changing this name, as it may already exist in the QMK Firmware repo. +::: ## Step 4: Define Your Keymap @@ -34,18 +42,24 @@ Keycode Entry is accomplished in one of 3 ways: 2. Clicking on an empty spot on the layout, then clicking the keycode you desire 3. Clicking on an empty spot on the layout, then pressing the physical key on your keyboard -?> Hover your mouse over a key and a short blurb will tell you what that keycode does. For a more verbose description please see: +::: tip +Hover your mouse over a key and a short blurb will tell you what that keycode does. For a more verbose description please see: +::: -* [Basic Keycode Reference](keycodes_basic.md) -* [Advanced Keycode Reference](feature_advanced_keycodes.md) +* [Basic Keycode Reference](keycodes_basic) +* [Advanced Keycode Reference](feature_advanced_keycodes) -!> If your selected layout doesn't match your physical build leave the unused keys blank. If you're not sure which key is in use, for example you have a one backspace key but `LAYOUT_all` has 2 keys, put the same keycode in both locations. +::: warning +If your selected layout doesn't match your physical build leave the unused keys blank. If you're not sure which key is in use, for example you have a one backspace key but `LAYOUT_all` has 2 keys, put the same keycode in both locations. +::: ## Step 5: Save Your Keymap for Future Changes When you're satisfied with your keymap or just want to work on it later, press the `Download this QMK Keymap JSON File` button. It will save your keymap to your computer. You can then load this .json file in the future by pressing the `Upload a QMK Keymap JSON File` button. -!> **CAUTION:** This is not the same type of .json file used for kbfirmware.com or any other tool. If you try to use this for those tools, or the .json from those tools with QMK Configurator, you will encounter problems. +::: warning +**CAUTION:** This is not the same type of .json file used for kbfirmware.com or any other tool. If you try to use this for those tools, or the .json from those tools with QMK Configurator, you will encounter problems. +::: ## Step 6: Compile Your Firmware File @@ -55,4 +69,4 @@ When the compilation is done, you will be able to press the green `Download Firm ## Next steps: Flashing Your Keyboard -Please refer to [Flashing Firmware](newbs_flashing.md). +Please refer to [Flashing Firmware](newbs_flashing). diff --git a/docs/configurator_troubleshooting.md b/docs/configurator_troubleshooting.md index 80b9713b64..634b05c206 100644 --- a/docs/configurator_troubleshooting.md +++ b/docs/configurator_troubleshooting.md @@ -14,8 +14,8 @@ If you're referring to having three spots for space bar, the best course of acti Please see: -* [Basic Keycode Reference](keycodes_basic.md) -* [Advanced Keycode Reference](feature_advanced_keycodes.md) +* [Basic Keycode Reference](keycodes_basic) +* [Advanced Keycode Reference](feature_advanced_keycodes) ## It won't compile diff --git a/docs/contributing.md b/docs/contributing.md index 8d993e3389..14025c2c50 100644 --- a/docs/contributing.md +++ b/docs/contributing.md @@ -56,8 +56,8 @@ Never made an open source contribution before? Wondering how contributions work Most of our style is pretty easy to pick up on. If you are familiar with either C or Python you should not have too much trouble with our local styles. -* [Coding Conventions - C](coding_conventions_c.md) -* [Coding Conventions - Python](coding_conventions_python.md) +* [Coding Conventions - C](coding_conventions_c) +* [Coding Conventions - Python](coding_conventions_python) # General Guidelines @@ -101,17 +101,13 @@ enum my_keycodes { }; ``` -### Previewing the Documentation :id=previewing-the-documentation +### Previewing the Documentation {#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: qmk docs -or if you only have Python 3 installed: - - python3 -m http.server 8936 --directory docs - -and navigating to `http://localhost:8936/`. +and navigating to `http://localhost:5173/`. ## Keyboards @@ -119,7 +115,7 @@ Keyboards are the raison d'être for QMK. Some keyboards are community maintaine We also ask that you follow these guidelines: -* Write a `readme.md` using [the template](documentation_templates.md). +* Write a `readme.md` using [the template](documentation_templates). * Include a `default` keymap that provides a clean slate for users to start with when creating their own keymaps. * Do not lump core features in with new keyboards. Submit the feature first and then submit a separate PR for the keyboard. * Name `.c`/`.h` file after the immediate parent folder, eg `/keyboards///.[ch]` @@ -128,7 +124,7 @@ We also ask that you follow these guidelines: ## Quantum/TMK Core -Before you put a lot of work into building your new feature you should make sure you are implementing it in the best way. You can get a basic understanding of QMK by reading [Understanding QMK](understanding_qmk.md), which will take you on a tour of the QMK program flow. From here you should talk to us to get a sense of the best way to implement your idea. There are two main ways to do this: +Before you put a lot of work into building your new feature you should make sure you are implementing it in the best way. You can get a basic understanding of QMK by reading [Understanding QMK](understanding_qmk), which will take you on a tour of the QMK program flow. From here you should talk to us to get a sense of the best way to implement your idea. There are two main ways to do this: * [Chat on Discord](https://discord.gg/Uq7gcHh) * [Open an Issue](https://github.com/qmk/qmk_firmware/issues/new) @@ -146,7 +142,7 @@ We also ask that you follow these guidelines: * Keep the number of commits reasonable or we will squash your PR * Do not lump keyboards or keymaps in with core changes. Submit your core changes first. -* Write [Unit Tests](unit_testing.md) for your feature +* Write [Unit Tests](unit_testing) for your feature * Follow the style of the file you are editing. If the style is unclear or there are mixed styles you should conform to the [coding conventions](#coding-conventions) above. ## Refactoring diff --git a/docs/custom_quantum_functions.md b/docs/custom_quantum_functions.md index bc3b28bbba..ac21f0e039 100644 --- a/docs/custom_quantum_functions.md +++ b/docs/custom_quantum_functions.md @@ -2,9 +2,9 @@ For a lot of people a custom keyboard is about more than sending button presses to your computer. You want to be able to do things that are more complex than simple button presses and macros. QMK has hooks that allow you to inject code, override functionality, and otherwise customize how your keyboard behaves in different situations. -This page does not assume any special knowledge about QMK, but reading [Understanding QMK](understanding_qmk.md) will help you understand what is going on at a more fundamental level. +This page does not assume any special knowledge about QMK, but reading [Understanding QMK](understanding_qmk) will help you understand what is going on at a more fundamental level. -## A Word on Core vs Keyboards vs Keymap :id=a-word-on-core-vs-keyboards-vs-keymap +## A Word on Core vs Keyboards vs Keymap {#a-word-on-core-vs-keyboards-vs-keymap} We have structured QMK as a hierarchy: @@ -34,7 +34,7 @@ enum my_keycodes { }; ``` -## Programming the Behavior of Any Keycode :id=programming-the-behavior-of-any-keycode +## Programming the Behavior of Any Keycode {#programming-the-behavior-of-any-keycode} When you want to override the behavior of an existing key, or define the behavior for a new key, you should use the `process_record_kb()` and `process_record_user()` functions. These are called by QMK during key processing before the actual key event is handled. If these functions return `true` QMK will process the keycodes as usual. That can be handy for extending the functionality of a key rather than replacing it. If these functions return `false` QMK will skip the normal key handling, and it will be up to you to send any key up or down events that are required. @@ -98,7 +98,9 @@ These are the three main initialization functions, listed in the order that they * `matrix_init_*` - Happens midway through the firmware's startup process. Hardware is initialized, but features may not be yet. * `keyboard_post_init_*` - Happens at the end of the firmware's startup process. This is where you'd want to put "customization" code, for the most part. -!> For most people, the `keyboard_post_init_user` function is what you want to call. For instance, this is where you want to set up things for RGB Underglow. +::: warning +For most people, the `keyboard_post_init_user` function is what you want to call. For instance, this is where you want to set up things for RGB Underglow. +::: ## Keyboard Pre Initialization code @@ -144,7 +146,7 @@ This is useful for setting up stuff that you may need elsewhere, but isn't hardw * Keyboard/Revision: `void matrix_init_kb(void)` * Keymap: `void matrix_init_user(void)` -### Low-level Matrix Overrides Function Documentation :id=low-level-matrix-overrides +### Low-level Matrix Overrides Function Documentation {#low-level-matrix-overrides} * GPIO pin initialisation: `void matrix_init_pins(void)` * This needs to perform the low-level initialisation of all row and column pins. By default this will initialise the input/output state of each of the GPIO pins listed in `MATRIX_ROW_PINS` and `MATRIX_COL_PINS`, based on whether or not the keyboard is set up for `ROW2COL`, `COL2ROW`, or `DIRECT_PINS`. Should the keyboard designer override this function, no initialisation of pin state will occur within QMK itself, instead deferring to the keyboard's override. @@ -204,7 +206,7 @@ Similar to `matrix_scan_*`, these are called as often as the MCU can handle. To ### Example `void housekeeping_task_user(void)` implementation -This example will show you how to use `void housekeeping_task_user(void)` to turn off [RGB Light](feature_rgblight.md). For RGB Matrix, the [builtin](https://docs.qmk.fm/#/feature_rgb_matrix?id=additional-configh-options) `RGB_MATRIX_TIMEOUT` should be used. +This example will show you how to use `void housekeeping_task_user(void)` to turn off [RGB Light](feature_rgblight). For RGB Matrix, the [builtin](feature_rgb_matrix#additional-configh-options) `RGB_MATRIX_TIMEOUT` should be used. First, add the following lines to your keymap's `config.h`: @@ -284,7 +286,7 @@ void suspend_wakeup_init_user(void) { * Keymap: `void suspend_power_down_kb(void)` and `void suspend_wakeup_init_user(void)` -# Keyboard Shutdown/Reboot Code :id=keyboard-shutdown-reboot-code +# Keyboard Shutdown/Reboot Code {#keyboard-shutdown-reboot-code} This function gets called whenever the firmware is reset, whether it's a soft reset or reset to the bootloader. This is the spot to use for any sort of cleanup, as this happens right before the actual reset. And it can be useful for turning off different systems (such as RGB, onboard screens, etc). @@ -296,7 +298,9 @@ If `jump_to_bootloader` is set to `true`, this indicates that the board will be As there is a keyboard and user level function, returning `false` for the user function will disable the keyboard level function, allowing for customization. -?> Bootmagic does not trigger `shutdown_*()` as it happens before most of the initialization process. +::: tip +Bootmagic does not trigger `shutdown_*()` as it happens before most of the initialization process. +::: ### Example `shutdown_kb()` Implementation @@ -342,7 +346,7 @@ bool shutdown_user(bool jump_to_bootloader) { * Keyboard/Revision: `bool shutdown_kb(bool jump_to_bootloader)` * Keymap: `bool shutdown_user(bool jump_to_bootloader)` -# Deferred Execution :id=deferred-execution +# Deferred Execution {#deferred-execution} QMK has the ability to execute a callback after a specified period of time, rather than having to manually manage timers. To enable this functionality, set `DEFERRED_EXEC_ENABLE = yes` in rules.mk. @@ -364,7 +368,9 @@ The second argument `cb_arg` is the same argument passed into `defer_exec()` bel The return value is the number of milliseconds to use if the function should be repeated -- if the callback returns `0` then it's automatically unregistered. In the example above, a hypothetical `my_deferred_functionality()` is invoked to determine if the callback needs to be repeated -- if it does, it reschedules for a `500` millisecond delay, otherwise it informs the deferred execution background task that it's done, by returning `0`. -?> Note that the returned delay will be applied to the intended trigger time, not the time of callback invocation. This allows for generally consistent timing even in the face of occasional late execution. +::: tip +Note that the returned delay will be applied to the intended trigger time, not the time of callback invocation. This allows for generally consistent timing even in the face of occasional late execution. +::: ## Deferred executor registration @@ -408,14 +414,14 @@ If registrations fail, then you can increase this value in your keyboard or keym #define MAX_DEFERRED_EXECUTORS 16 ``` -# Advanced topics :id=advanced-topics +# Advanced topics {#advanced-topics} This page used to encompass a large set of features. We have moved many sections that used to be part of this page to their own pages. Everything below this point is simply a redirect so that people following old links on the web find what they're looking for. -## Layer Change Code :id=layer-change-code +## Layer Change Code {#layer-change-code} -[Layer change code](feature_layers.md#layer-change-code) +[Layer change code](feature_layers#layer-change-code) -## Persistent Configuration (EEPROM) :id=persistent-configuration-eeprom +## Persistent Configuration (EEPROM) {#persistent-configuration-eeprom} -[Persistent Configuration (EEPROM)](feature_eeprom.md) +[Persistent Configuration (EEPROM)](feature_eeprom) diff --git a/docs/data_driven_config.md b/docs/data_driven_config.md index b288f9901a..2c1a56e004 100644 --- a/docs/data_driven_config.md +++ b/docs/data_driven_config.md @@ -4,7 +4,7 @@ This page describes how QMK's data driven JSON configuration system works. It is ## History -Historically QMK has been configured through a combination of two mechanisms- `rules.mk` and `config.h`. While this worked well when QMK was only a handful of keyboards we've grown to encompass nearly 1500 supported keyboards. That extrapolates out to 6000 configuration files under `keyboards/` alone! The freeform nature of these files and the unique patterns people have used to avoid duplication have made ongoing maintenance a challenge, and a large number of our keyboards follow patterns that are outdated and sometimes harder to understand. +Historically QMK has been configured through a combination of two mechanisms- `rules.mk` and `config.h`. While this worked well when QMK was only a handful of keyboards we've grown to encompass nearly 4000 supported keyboards. That extrapolates out to 6000 configuration files under `keyboards/` alone! The freeform nature of these files and the unique patterns people have used to avoid duplication have made ongoing maintenance a challenge, and a large number of our keyboards follow patterns that are outdated and sometimes harder to understand. We have also been working on bringing the power of QMK to people who aren't comformable with a CLI, and other projects such as VIA are working to make using QMK as easy as installing a program. These tools need information about how a keyboard is laid out or what pins and features are available so that users can take full advantage of QMK. We introduced `info.json` as a first step towards this. The QMK API is an effort to combine these 3 sources of information- `config.h`, `rules.mk`, and `info.json`- into a single source of truth that end-user tools can use. @@ -75,7 +75,7 @@ Whenever QMK generates a complete `info.json` it extracts information from `conf If you are not sure how to edit this file or are not comfortable with Python [open an issue](https://github.com/qmk/qmk_firmware/issues/new?assignees=&labels=cli%2C+python&template=other_issues.md&title=) or [join #cli on Discord](https://discord.gg/heQPAgy) and someone can help you with this part. -### Add code to generate it :id=add-code-to-generate-it +### Add code to generate it {#add-code-to-generate-it} The final piece of the puzzle is providing your new option to the build system. This is done by generating two files: diff --git a/docs/documentation_best_practices.md b/docs/documentation_best_practices.md index c193fed6b8..d41ec28f19 100644 --- a/docs/documentation_best_practices.md +++ b/docs/documentation_best_practices.md @@ -25,22 +25,30 @@ You can have styled hint blocks drawn around text to draw attention to it. ### Important ``` -!> This is important +::: warning +This is important +::: ``` Renders as: -!> This is important +::: warning +This is important +::: ### General Tips ``` -?> This is a helpful tip. +::: tip +This is a helpful tip. +::: ``` Renders as: -?> This is a helpful tip. +::: tip +This is a helpful tip. +::: # Documenting Features @@ -61,4 +69,4 @@ This page describes my cool feature. You can use my cool feature to make coffee |KC_SUGAR||Order Sugar| ``` -Place your documentation into `docs/feature_.md`, and add that file to the appropriate place in `docs/_summary.md`. If you have added any keycodes be sure to add them to `docs/keycodes.md` with a link back to your feature page. +Place your documentation into `docs/feature_.md`, and add that file to the appropriate place in `docs/_sidebar.json`. If you have added any keycodes be sure to add them to `docs/keycodes.md` with a link back to your feature page. diff --git a/docs/documentation_templates.md b/docs/documentation_templates.md index 0ad4303416..b60a00d673 100644 --- a/docs/documentation_templates.md +++ b/docs/documentation_templates.md @@ -2,7 +2,7 @@ This page documents the templates you should use when submitting new Keymaps and Keyboards to QMK. -## Keymap `readme.md` Template :id=keyboard-readmemd-template +## Keymap `readme.md` Template {#keyboard-readmemd-template} Most keymaps have an image depicting the layout. You can use [Keyboard Layout Editor](http://keyboard-layout-editor.com) to create an image. Upload it to [Imgur](https://imgur.com) or another hosting service, please do not include images in your Pull Request. @@ -40,7 +40,7 @@ Flashing example for this keyboard: make planck/rev4:default:flash -See the [build environment setup](https://docs.qmk.fm/#/getting_started_build_tools) and the [make instructions](https://docs.qmk.fm/#/getting_started_make_guide) for more information. Brand new to QMK? Start with our [Complete Newbs Guide](https://docs.qmk.fm/#/newbs). +See the [build environment setup](getting_started_build_tools) and the [make instructions](getting_started_make_guide) for more information. Brand new to QMK? Start with our [Complete Newbs Guide](newbs). ## Bootloader diff --git a/docs/driver_installation_zadig.md b/docs/driver_installation_zadig.md index 0440d6a4aa..69113863f8 100644 --- a/docs/driver_installation_zadig.md +++ b/docs/driver_installation_zadig.md @@ -8,15 +8,17 @@ We recommend the use of the [Zadig](https://zadig.akeo.ie/) utility. If you have ## Installation -Put your keyboard into bootloader mode, either by hitting the `QK_BOOT` keycode (which may be on a different layer), or by pressing the reset switch that's usually located on the underside of the board. If your keyboard has neither, try holding Escape or Space+`B` as you plug it in (see the [Bootmagic Lite](feature_bootmagic.md) docs for more details). Some boards use [Command](feature_command.md) instead of Bootmagic; in this case, you can enter bootloader mode by hitting Left Shift+Right Shift+`B` or Left Shift+Right Shift+Escape at any point while the keyboard is plugged in. -Some keyboards may have specific instructions for entering the bootloader. For example, the [Bootmagic Lite](feature_bootmagic.md) key (default: Escape) might be on a different key, e.g. Left Control; or the magic combination for Command (default: Left Shift+Right Shift) might require you to hold something else, e.g. Left Control+Right Control. Refer to the board's README file if you are unsure. +Put your keyboard into bootloader mode, either by hitting the `QK_BOOT` keycode (which may be on a different layer), or by pressing the reset switch that's usually located on the underside of the board. If your keyboard has neither, try holding Escape or Space+`B` as you plug it in (see the [Bootmagic Lite](feature_bootmagic) docs for more details). Some boards use [Command](feature_command) instead of Bootmagic; in this case, you can enter bootloader mode by hitting Left Shift+Right Shift+`B` or Left Shift+Right Shift+Escape at any point while the keyboard is plugged in. +Some keyboards may have specific instructions for entering the bootloader. For example, the [Bootmagic Lite](feature_bootmagic) key (default: Escape) might be on a different key, e.g. Left Control; or the magic combination for Command (default: Left Shift+Right Shift) might require you to hold something else, e.g. Left Control+Right Control. Refer to the board's README file if you are unsure. To put a device in bootloader mode with USBaspLoader, tap the `RESET` button while holding down the `BOOT` button. Alternatively, hold `BOOT` while inserting the USB cable. Zadig should automatically detect the bootloader device, but you may sometimes need to check **Options → List All Devices** and select the device from the dropdown instead. -!> If Zadig lists one or more devices with the `HidUsb` driver, your keyboard is probably not in bootloader mode. The arrow will be colored orange and you will be asked to confirm modifying a system driver. **Do not** proceed if this is the case! +::: warning +If Zadig lists one or more devices with the `HidUsb` driver, your keyboard is probably not in bootloader mode. The arrow will be colored orange and you will be asked to confirm modifying a system driver. **Do not** proceed if this is the case! +::: If the arrow appears green, select the driver, and click **Install Driver**. See the [list of known bootloaders](#list-of-known-bootloaders) for the correct driver to install. @@ -40,7 +42,9 @@ Right-click each entry and hit **Uninstall device**. Make sure to tick **Delete Click **Action → Scan for hardware changes**. At this point, you should be able to type again. Double check in Zadig that the keyboard device(s) are using the `HidUsb` driver. If so, you're all done, and your board should be functional again! Otherwise, repeat this process until Zadig reports the correct driver. -?> A full reboot of your computer may sometimes be necessary at this point, to get Windows to pick up the new driver. +::: tip +A full reboot of your computer may sometimes be necessary at this point, to get Windows to pick up the new driver. +::: ## Uninstallation @@ -60,7 +64,9 @@ Run `pnputil /delete-driver oemXX.inf /uninstall`. This will delete the driver a As with the previous section, this process may need to be repeated multiple times, as multiple drivers can be applicable to the same device. -!> **WARNING:** Be *extremely careful* when doing this! You could potentially uninstall the driver for some other critical device. If you are unsure, double check the output of `/enum-drivers`, and omit the `/uninstall` flag when running `/delete-driver`. +::: warning +**WARNING:** Be *extremely careful* when doing this! You could potentially uninstall the driver for some other critical device. If you are unsure, double check the output of `/enum-drivers`, and omit the `/uninstall` flag when running `/delete-driver`. +::: ## List of Known Bootloaders diff --git a/docs/easy_maker.md b/docs/easy_maker.md index 6af6473815..6a2f00686f 100644 --- a/docs/easy_maker.md +++ b/docs/easy_maker.md @@ -5,7 +5,7 @@ Have you ever needed an easy way to program a controller, such as a Proton C or There are different styles of Easy Maker available depending on your needs: * [Direct Pin](https://config.qmk.fm/#/?filter=ez_maker/direct) - Connect a single switch to a single pin -* Direct Pin + Backlight (Coming Soon) - Like Direct Pin but dedicates a single pin to [Backlight](feature_backlight.md) control +* Direct Pin + Backlight (Coming Soon) - Like Direct Pin but dedicates a single pin to [Backlight](feature_backlight) control * Direct Pin + Numlock (Coming Soon) - Like Direct Pin but dedicates a single pin to the Numlock LED * Direct Pin + Capslock (Coming Soon) - Like Direct Pin but dedicates a single pin to the Capslock LED * Direct Pin + Encoder (Coming Soon) - Like Direct Pin but uses 2 pins to add a single rotary encoder diff --git a/docs/eeprom_driver.md b/docs/eeprom_driver.md index c77d18c68d..6d13377ed8 100644 --- a/docs/eeprom_driver.md +++ b/docs/eeprom_driver.md @@ -1,4 +1,4 @@ -# EEPROM Driver Configuration :id=eeprom-driver-configuration +# EEPROM Driver Configuration {#eeprom-driver-configuration} The EEPROM driver can be swapped out depending on the needs of the keyboard, or whether extra hardware is present. @@ -12,17 +12,19 @@ Driver | Description `EEPROM_DRIVER = transient` | Fake EEPROM driver -- supports reading/writing to RAM, and will be discarded when power is lost. `EEPROM_DRIVER = wear_leveling` | Frontend driver for the wear_leveling system, allowing for EEPROM emulation on top of flash -- both in-MCU and external SPI NOR flash. -## Vendor Driver Configuration :id=vendor-eeprom-driver-configuration +## Vendor Driver Configuration {#vendor-eeprom-driver-configuration} -#### STM32 L0/L1 Configuration :id=stm32l0l1-eeprom-driver-configuration +#### STM32 L0/L1 Configuration {#stm32l0l1-eeprom-driver-configuration} -!> Resetting EEPROM using an STM32L0/L1 device takes up to 1 second for every 1kB of internal EEPROM used. +::: warning +Resetting EEPROM using an STM32L0/L1 device takes up to 1 second for every 1kB of internal EEPROM used. +::: `config.h` override | Description | Default Value ------------------------------------|--------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------- `#define STM32_ONBOARD_EEPROM_SIZE` | The size of the EEPROM to use, in bytes. Erase times can be high, so it's configurable here, if not using the default value. | Minimum required to cover base _eeconfig_ data, or `1024` if VIA is enabled. -## I2C Driver Configuration :id=i2c-eeprom-driver-configuration +## I2C Driver Configuration {#i2c-eeprom-driver-configuration} Currently QMK supports 24xx-series chips over I2C. As such, requires a working i2c_master driver configuration. You can override the driver configuration via your config.h: @@ -52,9 +54,11 @@ RM24C512C EEPROM | `#define EEPROM_I2C_RM24C512C` | MB85RC256V FRAM | `#define EEPROM_I2C_MB85RC256V` | -?> If you find that the EEPROM is not cooperating, ensure you've correctly shifted up your EEPROM address by 1. For example, the datasheet might state the address as `0b01010000` -- the correct value of `EXTERNAL_EEPROM_I2C_BASE_ADDRESS` needs to be `0b10100000`. +::: tip +If you find that the EEPROM is not cooperating, ensure you've correctly shifted up your EEPROM address by 1. For example, the datasheet might state the address as `0b01010000` -- the correct value of `EXTERNAL_EEPROM_I2C_BASE_ADDRESS` needs to be `0b10100000`. +::: -## SPI Driver Configuration :id=spi-eeprom-driver-configuration +## SPI Driver Configuration {#spi-eeprom-driver-configuration} Currently QMK supports 25xx-series chips over SPI. As such, requires a working spi_master driver configuration. You can override the driver configuration via your config.h: @@ -74,9 +78,11 @@ Module | Equivalent `#define` | Source -----------------|---------------------------------|------------------------------------------ MB85RS64V FRAM | `define EEPROM_SPI_MB85RS64V` | -!> There's no way to determine if there is an SPI EEPROM actually responding. Generally, this will result in reads of nothing but zero. +::: warning +There's no way to determine if there is an SPI EEPROM actually responding. Generally, this will result in reads of nothing but zero. +::: -## Transient Driver configuration :id=transient-eeprom-driver-configuration +## Transient Driver configuration {#transient-eeprom-driver-configuration} The only configurable item for the transient EEPROM driver is its size: @@ -86,13 +92,13 @@ The only configurable item for the transient EEPROM driver is its size: Default values and extended descriptions can be found in `drivers/eeprom/eeprom_transient.h`. -## Wear-leveling Driver Configuration :id=wear_leveling-eeprom-driver-configuration +## Wear-leveling Driver Configuration {#wear_leveling-eeprom-driver-configuration} The wear-leveling driver uses an algorithm to minimise the number of erase cycles on the underlying MCU flash memory. There is no specific configuration for this driver, but the wear-leveling system used by this driver may need configuration. See the [wear-leveling configuration](#wear_leveling-configuration) section for more information. -# Wear-leveling Configuration :id=wear_leveling-configuration +# Wear-leveling Configuration {#wear_leveling-configuration} The wear-leveling driver has a few possible _backing stores_ that may be used by adding to your keyboard's `rules.mk` file: @@ -103,9 +109,11 @@ Driver | Description `WEAR_LEVELING_DRIVER = rp2040_flash` | This driver is used to write to the same storage the RP2040 executes code from. `WEAR_LEVELING_DRIVER = legacy` | This driver is the "legacy" emulated EEPROM provided in historical revisions of QMK. Currently used for STM32F0xx and STM32F4x1, but slated for deprecation and removal once `embedded_flash` support for those MCU families is complete. -!> All wear-leveling drivers require an amount of RAM equivalent to the selected logical EEPROM size. Increasing the size to 32kB of EEPROM requires 32kB of RAM, which a significant number of MCUs simply do not have. +::: warning +All wear-leveling drivers require an amount of RAM equivalent to the selected logical EEPROM size. Increasing the size to 32kB of EEPROM requires 32kB of RAM, which a significant number of MCUs simply do not have. +::: -## Wear-leveling Embedded Flash Driver Configuration :id=wear_leveling-efl-driver-configuration +## Wear-leveling Embedded Flash Driver Configuration {#wear_leveling-efl-driver-configuration} This driver performs writes to the embedded flash storage embedded in the MCU. In most circumstances, the last few of sectors of flash are used in order to minimise the likelihood of collision with program code. @@ -119,11 +127,13 @@ Configurable options in your keyboard's `config.h`: `#define WEAR_LEVELING_BACKING_SIZE` | `2048` | Number of bytes used by the wear-leveling algorithm for its underlying storage, and needs to be a multiple of the logical size. `#define BACKING_STORE_WRITE_SIZE` | _automatic_ | The byte width of the underlying write used on the MCU, and is usually automatically determined from the selected MCU family. If an error occurs in the auto-detection, you'll need to consult the MCU's datasheet and determine this value, specifying it directly. -!> If your MCU does not boot after swapping to the EFL wear-leveling driver, it's likely that the flash size is incorrectly detected, usually as an MCU with larger flash and may require overriding. +::: warning +If your MCU does not boot after swapping to the EFL wear-leveling driver, it's likely that the flash size is incorrectly detected, usually as an MCU with larger flash and may require overriding. +::: -## Wear-leveling SPI Flash Driver Configuration :id=wear_leveling-flash_spi-driver-configuration +## Wear-leveling SPI Flash Driver Configuration {#wear_leveling-flash_spi-driver-configuration} -This driver performs writes to an external SPI NOR Flash peripheral. It also requires a working configuration for the SPI NOR Flash peripheral -- see the [flash driver](flash_driver.md) documentation for more information. +This driver performs writes to an external SPI NOR Flash peripheral. It also requires a working configuration for the SPI NOR Flash peripheral -- see the [flash driver](flash_driver) documentation for more information. Configurable options in your keyboard's `config.h`: @@ -135,9 +145,11 @@ Configurable options in your keyboard's `config.h`: `#define WEAR_LEVELING_BACKING_SIZE` | `(block_count*block_size)` | Number of bytes used by the wear-leveling algorithm for its underlying storage, and needs to be a multiple of the logical size. `#define BACKING_STORE_WRITE_SIZE` | `8` | The write width used whenever a write is performed on the external flash peripheral. -!> There is currently a limit of 64kB for the EEPROM subsystem within QMK, so using a larger flash is not going to be beneficial as the logical size cannot be increased beyond 65536. The backing size may be increased to a larger value, but erase timing may suffer as a result. +::: warning +There is currently a limit of 64kB for the EEPROM subsystem within QMK, so using a larger flash is not going to be beneficial as the logical size cannot be increased beyond 65536. The backing size may be increased to a larger value, but erase timing may suffer as a result. +::: -## Wear-leveling RP2040 Driver Configuration :id=wear_leveling-rp2040-driver-configuration +## Wear-leveling RP2040 Driver Configuration {#wear_leveling-rp2040-driver-configuration} This driver performs writes to the same underlying storage that the RP2040 executes its code. @@ -151,7 +163,7 @@ Configurable options in your keyboard's `config.h`: `#define WEAR_LEVELING_BACKING_SIZE` | `8192` | Number of bytes used by the wear-leveling algorithm for its underlying storage, and needs to be a multiple of the logical size as well as the sector size. `#define BACKING_STORE_WRITE_SIZE` | `2` | The write width used whenever a write is performed on the external flash peripheral. -## Wear-leveling Legacy EEPROM Emulation Driver Configuration :id=wear_leveling-legacy-driver-configuration +## Wear-leveling Legacy EEPROM Emulation Driver Configuration {#wear_leveling-legacy-driver-configuration} This driver performs writes to the embedded flash storage embedded in the MCU much like the normal Embedded Flash Driver, and is only for use with STM32F0xx and STM32F4x1 devices. This flash implementation is still currently provided as the EFL driver is currently non-functional for the previously mentioned families. diff --git a/docs/faq_build.md b/docs/faq_build.md index b86f2177a0..7fafff1066 100644 --- a/docs/faq_build.md +++ b/docs/faq_build.md @@ -1,6 +1,6 @@ # Frequently Asked Build Questions -This page covers questions about building QMK. If you haven't yet done so, you should read the [Build Environment Setup](getting_started_build_tools.md) and [Make Instructions](getting_started_make_guide.md) guides. +This page covers questions about building QMK. If you haven't yet done so, you should read the [Build Environment Setup](newbs_getting_started) and [Make Instructions](getting_started_make_guide) guides. ## Can't Program on Linux You will need proper permissions to operate a device. For Linux users, see the instructions regarding `udev` rules, below. If you have issues with `udev`, a work-around is to use the `sudo` command. If you are not familiar with this command, check its manual with `man sudo` or [see this webpage](https://linux.die.net/man/8/sudo). @@ -17,7 +17,7 @@ or just: Note that running `make` with `sudo` is generally ***not*** a good idea, and you should use one of the former methods, if possible. -### Linux `udev` Rules :id=linux-udev-rules +### Linux `udev` Rules {#linux-udev-rules} On Linux, you'll need proper privileges to communicate with the bootloader device. You can either use `sudo` when flashing firmware (not recommended), or place [this file](https://github.com/qmk/qmk_firmware/tree/master/util/udev/50-qmk.rules) into `/etc/udev/rules.d/`. @@ -46,7 +46,7 @@ Issues encountered when flashing keyboards on Windows are most often due to havi Re-running the QMK installation script (`./util/qmk_install.sh` from the `qmk_firmware` directory in MSYS2 or WSL) or reinstalling the QMK Toolbox may fix the issue. Alternatively, you can download and run the [`qmk_driver_installer`](https://github.com/qmk/qmk_driver_installer) package manually. -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. +If that doesn't work, then you may need to download and run Zadig. See [Bootloader Driver Installation with Zadig](driver_installation_zadig) for more detailed information. ## 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. @@ -66,4 +66,4 @@ Due to how EEPROM works on ARM based chips, saved settings may no longer be vali [Planck rev6 reset EEPROM](https://cdn.discordapp.com/attachments/473506116718952450/539284620861243409/planck_rev6_default.bin) can be used to force an eeprom reset. After flashing this image, flash your normal firmware again which should restore your keyboard to _normal_ working order. [Preonic rev3 reset EEPROM](https://cdn.discordapp.com/attachments/473506116718952450/537849497313738762/preonic_rev3_default.bin) -If bootmagic is enabled in any form, you should be able to do this too (see [Bootmagic docs](feature_bootmagic.md) and keyboard info for specifics on how to do this). +If bootmagic is enabled in any form, you should be able to do this too (see [Bootmagic docs](feature_bootmagic) and keyboard info for specifics on how to do this). diff --git a/docs/faq_debug.md b/docs/faq_debug.md index cad98bc331..e22bc5d9ce 100644 --- a/docs/faq_debug.md +++ b/docs/faq_debug.md @@ -2,9 +2,9 @@ This page details various common questions people have about troubleshooting their keyboards. -## Debugging :id=debugging +## Debugging {#debugging} -Your keyboard will output debug information if you have `CONSOLE_ENABLE = yes` in your `rules.mk`. By default the output is very limited, but you can turn on debug mode to increase the amount of debug output. Use the `DB_TOGG` keycode in your keymap, use the [Command](feature_command.md) feature to enable debug mode, or add the following code to your keymap. +Your keyboard will output debug information if you have `CONSOLE_ENABLE = yes` in your `rules.mk`. By default the output is very limited, but you can turn on debug mode to increase the amount of debug output. Use the `DB_TOGG` keycode in your keymap, use the [Command](feature_command) feature to enable debug mode, or add the following code to your keymap. ```c void keyboard_post_init_user(void) { @@ -26,15 +26,15 @@ For compatible platforms, [QMK Toolbox](https://github.com/qmk/qmk_toolbox) can ### Debugging with QMK CLI -Prefer a terminal based solution? The [QMK CLI console command](cli_commands.md#qmk-console) can be used to display debug messages from your keyboard. +Prefer a terminal based solution? The [QMK CLI console command](cli_commands#qmk-console) can be used to display debug messages from your keyboard. ### Debugging With hid_listen Something stand-alone? [hid_listen](https://www.pjrc.com/teensy/hid_listen.html), provided by PJRC, can also be used to display debug messages. Prebuilt binaries for Windows,Linux,and MacOS are available. -## Sending Your Own Debug Messages :id=debug-api +## Sending Your Own Debug Messages {#debug-api} -Sometimes it's useful to print debug messages from within your [custom code](custom_quantum_functions.md). Doing so is pretty simple. Start by including `print.h` at the top of your file: +Sometimes it's useful to print debug messages from within your [custom code](custom_quantum_functions). Doing so is pretty simple. Start by including `print.h` at the top of your file: ```c #include "print.h" @@ -49,7 +49,7 @@ After that you can use a few different print functions: ## Debug Examples -Below is a collection of real world debugging examples. For additional information, refer to [Debugging/Troubleshooting QMK](faq_debug.md). +Below is a collection of real world debugging examples. For additional information, refer to [Debugging/Troubleshooting QMK](faq_debug). ### Which matrix position is this keypress? diff --git a/docs/faq_general.md b/docs/faq_general.md index 56b150da29..69ef4efa17 100644 --- a/docs/faq_general.md +++ b/docs/faq_general.md @@ -6,13 +6,13 @@ ## I don't know where to start! -If this is the case, then you should start with our [Newbs Guide](newbs.md). There is a lot of great info there, and that should cover everything you need to get started. +If this is the case, then you should start with our [Newbs Guide](newbs). There is a lot of great info there, and that should cover everything you need to get started. If that's an issue, hop onto the [QMK Configurator](https://config.qmk.fm), as that will handle a majority of what you need there. ## How can I flash the firmware I built? -First, head to the [Compiling/Flashing FAQ Page](faq_build.md). There is a good deal of info there, and you'll find a bunch of solutions to common issues there. +First, head to the [Compiling/Flashing FAQ Page](faq_build). There is a good deal of info there, and you'll find a bunch of solutions to common issues there. ## What if I have an issue that isn't covered here? @@ -26,9 +26,9 @@ Then please open an [issue](https://github.com/qmk/qmk_firmware/issues/new), and ## But `git` and `GitHub` are intimidating! -Don't worry, we have some pretty nice [Guidelines](newbs_git_best_practices.md) on how to start using `git` and GitHub to make things easier to develop. +Don't worry, we have some pretty nice [Guidelines](newbs_git_best_practices) on how to start using `git` and GitHub to make things easier to develop. -Additionally, you can find additional `git` and GitHub related links [here](newbs_learn_more_resources.md). +Additionally, you can find additional `git` and GitHub related links [here](newbs_learn_more_resources). ## I have a Keyboard that I want to add support for @@ -46,7 +46,7 @@ If you have any questions about this, open an issue or head to [Discord](https:/ TMK was originally designed and implemented by [Jun Wako](https://github.com/tmk). QMK started as [Jack Humbert](https://github.com/jackhumbert)'s fork of TMK for the Planck. After a while Jack's fork had diverged quite a bit from TMK, and in 2015 Jack decided to rename his fork to QMK. -From a technical standpoint QMK builds upon TMK by adding several new features. Most notably QMK has expanded the number of available keycodes and uses these to implement advanced features like `S()`, `LCTL()`, and `MO()`. You can see a complete list of these keycodes in [Keycodes](keycodes.md). +From a technical standpoint QMK builds upon TMK by adding several new features. Most notably QMK has expanded the number of available keycodes and uses these to implement advanced features like `S()`, `LCTL()`, and `MO()`. You can see a complete list of these keycodes in [Keycodes](keycodes). From a project and community management standpoint TMK maintains all the officially supported keyboards by himself, with a bit of community support. Separate community maintained forks exist or can be created for other keyboards. Only a few keymaps are provided by default, so users typically don't share keymaps with each other. QMK encourages sharing of both keyboards and keymaps through a centrally managed repository, accepting all pull requests that follow the quality standards. These are mostly community maintained, but the QMK team also helps when necessary. diff --git a/docs/faq_keymap.md b/docs/faq_keymap.md index 8641281835..0070b6d1de 100644 --- a/docs/faq_keymap.md +++ b/docs/faq_keymap.md @@ -1,10 +1,10 @@ # Keymap FAQ -This page covers questions people often have about keymaps. If you haven't you should read [Keymap Overview](keymap.md) first. +This page covers questions people often have about keymaps. If you haven't you should read [Keymap Overview](keymap) first. ## What Keycodes Can I Use? -See [Keycodes](keycodes.md) for an index of keycodes available to you. These link to more extensive documentation when available. +See [Keycodes](keycodes) for an index of keycodes available to you. These link to more extensive documentation when available. Keycodes are actually defined in [quantum/keycode.h](https://github.com/qmk/qmk_firmware/blob/master/quantum/keycode.h). @@ -44,8 +44,8 @@ QMK has a couple of features which allow you to change the behavior of your keyb Refer to the EEPROM clearing methods above, which should return those keys to normal operation. If that doesn't work, look here: -* [Magic Keycodes](keycodes_magic.md) -* [Command](feature_command.md) +* [Magic Keycodes](keycodes_magic) +* [Command](feature_command) ## The Menu Key Isn't Working @@ -86,7 +86,7 @@ Old vintage mechanical keyboards occasionally have lock switches but modern ones ## Input Special Characters Other Than ASCII like Cédille 'Ç' -See the [Unicode](feature_unicode.md) feature. +See the [Unicode](feature_unicode) feature. ## `Fn` Key on macOS @@ -130,7 +130,7 @@ https://github.com/tekezo/Karabiner/issues/403 ## Esc and ` on a Single Key -See the [Grave Escape](feature_grave_esc.md) feature. +See the [Grave Escape](feature_grave_esc) feature. ## Eject on Mac OSX diff --git a/docs/faq_misc.md b/docs/faq_misc.md index 287ca7711d..133dbcf612 100644 --- a/docs/faq_misc.md +++ b/docs/faq_misc.md @@ -1,6 +1,6 @@ # Miscellaneous FAQ -## How do I test my keyboard? :id=testing +## How do I test my keyboard? {#testing} Testing your keyboard is usually pretty straightforward. Press every single key and make sure it sends the keys you expect. You can use [QMK Configurator](https://config.qmk.fm/#/test/)'s test mode to check your keyboard, even if it doesn't run QMK. diff --git a/docs/feature_advanced_keycodes.md b/docs/feature_advanced_keycodes.md index 171243301d..50dc0bb281 100644 --- a/docs/feature_advanced_keycodes.md +++ b/docs/feature_advanced_keycodes.md @@ -1,4 +1,4 @@ -# Modifier Keys :id=modifier-keys +# Modifier Keys {#modifier-keys} These allow you to combine a modifier with a keycode. When pressed, the keydown event for the modifier, then `kc` will be sent. On release, the keyup event for `kc`, then the modifier will be sent. @@ -26,7 +26,7 @@ These allow you to combine a modifier with a keycode. When pressed, the keydown You can also chain them, for example `LCTL(LALT(KC_DEL))` or `C(A(KC_DEL))` makes a key that sends Control+Alt+Delete with a single keypress. -# Checking Modifier State :id=checking-modifier-state +# Checking Modifier State {#checking-modifier-state} The current modifier state can mainly be accessed with two functions: `get_mods()` for normal modifiers and modtaps and `get_oneshot_mods()` for one-shot modifiers (unless they're held, in which case they act like normal modifier keys). @@ -35,7 +35,7 @@ The presence of one or more specific modifiers in the current modifier state can Thus, to give an example, `01000010` would be the internal representation of LShift+RAlt. For more information on bitwise operators in C, click [here](https://en.wikipedia.org/wiki/Bitwise_operations_in_C) to open the Wikipedia page on the topic. -In practice, this means that you can check whether a given modifier is active with `get_mods() & MOD_BIT(KC_)` (see the [list of modifier keycodes](keycodes_basic.md#modifiers)) or with `get_mods() & MOD_MASK_` if the difference between left and right hand modifiers is not important and you want to match both. Same thing can be done for one-shot modifiers if you replace `get_mods()` with `get_oneshot_mods()`. +In practice, this means that you can check whether a given modifier is active with `get_mods() & MOD_BIT(KC_)` (see the [list of modifier keycodes](keycodes_basic#modifiers)) or with `get_mods() & MOD_MASK_` if the difference between left and right hand modifiers is not important and you want to match both. Same thing can be done for one-shot modifiers if you replace `get_mods()` with `get_oneshot_mods()`. To check that *only* a specific set of mods is active at a time, use a simple equality operator: `get_mods() == `. @@ -77,11 +77,11 @@ Similarly, in addition to `get_oneshot_mods()`, there also exists these function * `set_oneshot_mods(mods)`: Overwrite current one-shot modifier state with `mods` * `clear_oneshot_mods()`: Reset the one-shot modifier state by disabling all one-shot modifiers -## Examples :id=examples +## Examples {#examples} -The following examples use [advanced macro functions](feature_macros.md#advanced-macro-functions) which you can read more about in the [documentation page on macros](feature_macros.md). +The following examples use [advanced macro functions](feature_macros#advanced-macro-functions) which you can read more about in the [documentation page on macros](feature_macros). -### Alt + Escape for Alt + Tab :id=alt-escape-for-alt-tab +### Alt + Escape for Alt + Tab {#alt-escape-for-alt-tab} Simple example where chording Left Alt with `KC_ESC` makes it behave like `KC_TAB` for alt-tabbing between applications. This example strictly checks if only Left Alt is active, meaning you can't do Alt+Shift+Esc to switch between applications in reverse order. Also keep in mind that this removes the ability to trigger the actual Alt+Escape keyboard shortcut, though it keeps the ability to do AltGr+Escape. @@ -110,7 +110,7 @@ bool process_record_user(uint16_t keycode, keyrecord_t *record) { }; ``` -### Shift + Backspace for Delete :id=shift-backspace-for-delete +### Shift + Backspace for Delete {#shift-backspace-for-delete} Advanced example where the original behaviour of shift is cancelled when chorded with `KC_BSPC` and is instead fully replaced by `KC_DEL`. Two main variables are created to make this work well: `mod_state` and `delkey_registered`. The first one stores the modifier state and is used to restore it after registering `KC_DEL`. The second variable is a boolean variable (true or false) which keeps track of the status of `KC_DEL` to manage the release of the whole Backspace/Delete key correctly. @@ -160,28 +160,28 @@ bool process_record_user(uint16_t keycode, keyrecord_t *record) { return true; }; ``` -Alternatively, this can be done with [Key Overrides](feature_key_overrides?id=simple-example). +Alternatively, this can be done with [Key Overrides](feature_key_overrides#simple-example). -# Advanced topics :id=advanced-topics +# Advanced topics {#advanced-topics} This page used to encompass a large set of features. We have moved many sections that used to be part of this page to their own pages. Everything below this point is simply a redirect so that people following old links on the web find what they're looking for. -## Layers :id=switching-and-toggling-layers +## Layers {#switching-and-toggling-layers} -* [Layers](feature_layers.md) +* [Layers](feature_layers) -## Mod-Tap :id=mod-tap +## Mod-Tap {#mod-tap} -* [Mod-Tap](mod_tap.md) +* [Mod-Tap](mod_tap) -## One Shot Keys :id=one-shot-keys +## One Shot Keys {#one-shot-keys} -* [One Shot Keys](one_shot_keys.md) +* [One Shot Keys](one_shot_keys) -## Tap-Hold Configuration Options :id=tap-hold-configuration-options +## Tap-Hold Configuration Options {#tap-hold-configuration-options} -* [Tap-Hold Configuration Options](tap_hold.md) +* [Tap-Hold Configuration Options](tap_hold) -## Key Overrides :id=key-overrides +## Key Overrides {#key-overrides} -* [Key Overrides](feature_key_overrides.md) +* [Key Overrides](feature_key_overrides) diff --git a/docs/feature_audio.md b/docs/feature_audio.md index 05f32e9840..c83d6e3d93 100644 --- a/docs/feature_audio.md +++ b/docs/feature_audio.md @@ -27,7 +27,7 @@ per speaker is - for example with a piezo buzzer - the black lead to Ground, and ## ARM based boards -for more technical details, see the notes on [Audio driver](audio_driver.md). +for more technical details, see the notes on [Audio driver](audio_driver). ### DAC (basic) @@ -131,7 +131,7 @@ You can override the default songs by doing something like this in your `config. ```c #ifdef AUDIO_ENABLE -# define STARTUP_SONG SONG(STARTUP_SOUND) +# define STARTUP_SONG SONG(STARTUP_SOUND) #endif ``` @@ -167,7 +167,9 @@ The available keycodes for audio are: |`QK_AUDIO_OFF` |`AU_OFF` |Turns off Audio Feature | |`QK_AUDIO_TOGGLE` |`AU_TOGG`|Toggles Audio state | -!> These keycodes turn all of the audio functionality on and off. Turning it off means that audio feedback, audio clicky, music mode, etc. are disabled, completely. +::: warning +These keycodes turn all of the audio functionality on and off. Turning it off means that audio feedback, audio clicky, music mode, etc. are disabled, completely. +::: ## Audio Config @@ -346,7 +348,7 @@ You can configure the default, min and max frequencies, the stepping and built i ## MIDI Functionality -See [MIDI](feature_midi.md) +See [MIDI](feature_midi) ## Audio Keycodes diff --git a/docs/feature_auto_shift.md b/docs/feature_auto_shift.md index 74be33cdd4..3dbaec555e 100644 --- a/docs/feature_auto_shift.md +++ b/docs/feature_auto_shift.md @@ -100,7 +100,9 @@ occasion. This is simply due to habit and holding some keys a little longer than others. Once you find this value, work on tapping your problem keys a little quicker than normal and you will be set. -?> Auto Shift has three special keys that can help you get this value right very quick. See "Auto Shift Setup" for more details! +::: tip +Auto Shift has three special keys that can help you get this value right very quick. See "Auto Shift Setup" for more details! +::: For more granular control of this feature, you can add the following to your `config.h`: @@ -179,23 +181,23 @@ For more granular control, there is `get_auto_shifted_key`. The default function ```c bool get_auto_shifted_key(uint16_t keycode, keyrecord_t *record) { switch (keycode) { -# ifndef NO_AUTO_SHIFT_ALPHA +# ifndef NO_AUTO_SHIFT_ALPHA case AUTO_SHIFT_ALPHA: -# endif -# ifndef NO_AUTO_SHIFT_NUMERIC +# endif +# ifndef NO_AUTO_SHIFT_NUMERIC case AUTO_SHIFT_NUMERIC: -# endif -# ifndef NO_AUTO_SHIFT_SPECIAL -# ifndef NO_AUTO_SHIFT_TAB +# endif +# ifndef NO_AUTO_SHIFT_SPECIAL +# ifndef NO_AUTO_SHIFT_TAB case KC_TAB: # endif -# ifndef NO_AUTO_SHIFT_SYMBOLS +# ifndef NO_AUTO_SHIFT_SYMBOLS case AUTO_SHIFT_SYMBOLS: # endif -# endif -# ifdef AUTO_SHIFT_ENTER +# endif +# ifdef AUTO_SHIFT_ENTER case KC_ENT: -# endif +# endif return true; } return get_custom_auto_shifted_key(keycode, record); @@ -290,7 +292,7 @@ Holding and releasing a Tap Hold key without pressing another key will ordinaril result in only the hold. With `retro shift` enabled this action will instead produce a shifted version of the tap keycode on release. -It does not require [Retro Tapping](tap_hold.md#retro-tapping) to be enabled, and +It does not require [Retro Tapping](tap_hold#retro-tapping) to be enabled, and if both are enabled the state of `retro tapping` will only apply if the tap keycode is not matched by Auto Shift. `RETRO_TAPPING_PER_KEY` and its corresponding function, however, are checked before `retro shift` is applied. @@ -314,10 +316,10 @@ Without a value set, holds of any length without an interrupting key will produc This value (if set) must be greater than one's `TAPPING_TERM`, as the key press must be designated as a 'hold' by `process_tapping` before we send the modifier. -[Per-key tapping terms](tap_hold.md#tapping-term) can be used as a workaround. +[Per-key tapping terms](tap_hold#tapping-term) can be used as a workaround. There is no such limitation in regards to `AUTO_SHIFT_TIMEOUT` for normal keys. -**Note:** Tap Holds must be added to Auto Shift, see [here.](feature_auto_shift.md#auto-shift-per-key) +**Note:** Tap Holds must be added to Auto Shift, see [here.](feature_auto_shift#auto-shift-per-key) `IS_RETRO` may be helpful if one wants all Tap Holds retro shifted. ### Retro Shift and Tap Hold Configurations @@ -326,7 +328,7 @@ Tap Hold Configurations work a little differently when using Retro Shift. Referencing `TAPPING_TERM` makes little sense, as holding longer would result in shifting one of the keys. -`RETRO_SHIFT` enables [`PERMISSIVE_HOLD`-like behaviour](tap_hold.md#permissive-hold) (even if not explicitly enabled) on all mod-taps for which `RETRO_SHIFT` applies. +`RETRO_SHIFT` enables [`PERMISSIVE_HOLD`-like behaviour](tap_hold#permissive-hold) (even if not explicitly enabled) on all mod-taps for which `RETRO_SHIFT` applies. ## Using Auto Shift Setup diff --git a/docs/feature_autocorrect.md b/docs/feature_autocorrect.md index 3a0a49095c..1ad582207a 100644 --- a/docs/feature_autocorrect.md +++ b/docs/feature_autocorrect.md @@ -2,7 +2,7 @@ There are a lot of words that are prone to being typed incorrectly, due to habit, sequence or just user error. This feature leverages your firmware to automatically correct these errors, to help reduce typos. -## How does it work? :id=how-does-it-work +## How does it work? {#how-does-it-work} The feature maintains a small buffer of recent key presses. On each key press, it checks whether the buffer ends in a recognized typo, and if so, automatically sends keystrokes to correct it. @@ -12,7 +12,7 @@ The tricky part is how to efficiently check the buffer for typos. We don’t wan Since we search whether the buffer ends in a typo, we store the trie writing in reverse. The trie is queried starting from the last letter, then second to last letter, and so on, until either a letter doesn’t match or we reach a leaf, meaning a typo was found. -## How do I enable Autocorrection :id=how-do-i-enable-autocorrection +## How do I enable Autocorrection {#how-do-i-enable-autocorrection} In your `rules.mk`, add this: @@ -24,7 +24,7 @@ Additionally, you will need a library for autocorrection. A small sample librar By default, autocorrect is disabled. To enable it, you need to use the `AC_TOGG` keycode to enable it. The status is stored in persistent memory, so you shouldn't need to enabled it again. -## Customizing autocorrect library :id=customizing-autocorrect-library +## Customizing autocorrect library {#customizing-autocorrect-library} To provide a custom library, you need to create a text file with the corrections. For instance: @@ -66,7 +66,7 @@ static const uint8_t autocorrect_data[DICTIONARY_SIZE] PROGMEM = {85, 7, 0, 23, 0}; ``` -### Avoiding false triggers :id=avoiding-false-triggers +### Avoiding false triggers {#avoiding-false-triggers} By default, typos are searched within words, to find typos within longer identifiers like maxFitlerOuput. While this is useful, a consequence is that autocorrection will falsely trigger when a typo happens to be a substring of a correctly-spelled word. For instance, if we had thier -> their as an entry, it would falsely trigger on (correct, though relatively uncommon) words like “wealthier” and “filthier.” @@ -82,7 +82,9 @@ The solution is to set a word break : before and/or after the typo to constrain The `qmk generate-autocorrect-data` commands can make an effort to check for entries that would false trigger as substrings of correct words. It searches each typo against a dictionary of 25K English words from the english_words Python package, provided it’s installed. (run `python3 -m pip install english_words` to install it.) -?> Unfortunately, this is limited to just english words, at this point. +::: tip +Unfortunately, this is limited to just english words, at this point. +::: ## Overriding Autocorrect @@ -96,7 +98,7 @@ This works because the autocorrection implementation doesn’t understand hotkey Additionally, you can use the `AC_TOGG` keycode to toggle the on/off status for Autocorrect. -### Keycodes :id=keycodes +### Keycodes {#keycodes} |Keycode |Aliases |Description | |-----------------------|---------|----------------------------------------------| @@ -110,7 +112,9 @@ Additionally, you can use the `AC_TOGG` keycode to toggle the on/off status for Callback function `bool process_autocorrect_user(uint16_t *keycode, keyrecord_t *record, uint8_t *typo_buffer_size, uint8_t *mods)` is available to customise incoming keycodes and handle exceptions. You can use this function to sanitise input before they are passed onto the autocorrect engine -?> Sanitisation of input is required because autocorrect will only match 8-bit [basic keycodes](keycodes_basic.md) for typos. If valid modifier keys or 16-bit keycodes that are part of a user's word input (such as Shift + A) is passed through, they will fail typo letter detection. For example a [Mod-Tap](mod_tap.md) key such as `LCTL_T(KC_A)` is 16-bit and should be masked for the 8-bit `KC_A`. +::: tip +Sanitisation of input is required because autocorrect will only match 8-bit [basic keycodes](keycodes_basic) for typos. If valid modifier keys or 16-bit keycodes that are part of a user's word input (such as Shift + A) is passed through, they will fail typo letter detection. For example a [Mod-Tap](mod_tap) key such as `LCTL_T(KC_A)` is 16-bit and should be masked for the 8-bit `KC_A`. +::: The default user callback function is found inside `quantum/process_keycode/process_autocorrect.c`. It covers most use-cases for QMK special functions and quantum keycodes, including [overriding autocorrect](#overriding-autocorrect) with a modifier other than shift. The `process_autocorrect_user` function is `weak` defined to allow user's copy inside `keymap.c` (or code files) to overwrite it. @@ -145,11 +149,11 @@ bool process_autocorrect_user(uint16_t *keycode, keyrecord_t *record, uint8_t *t // Exclude tap-hold keys when they are held down // and mask for base keycode when they are tapped. case QK_LAYER_TAP ... QK_LAYER_TAP_MAX: -# ifdef NO_ACTION_LAYER +# ifdef NO_ACTION_LAYER // Exclude Layer Tap, if layers are disabled // but action tapping is still enabled. return false; -# endif +# endif case QK_MOD_TAP ... QK_MOD_TAP_MAX: // Exclude hold if mods other than Shift is not active if (!record->tap.count) { @@ -194,13 +198,17 @@ bool process_autocorrect_user(uint16_t *keycode, keyrecord_t *record, uint8_t *t } ``` -?> In this callback function, `return false` will skip processing of that keycode for autocorrect. Adding `*typo_buffer_size = 0` will also reset the autocorrect buffer at the same time, cancelling any current letters already stored in the buffer. +::: tip +In this callback function, `return false` will skip processing of that keycode for autocorrect. Adding `*typo_buffer_size = 0` will also reset the autocorrect buffer at the same time, cancelling any current letters already stored in the buffer. +::: ### Apply Autocorrect Additionally, `apply_autocorrect(uint8_t backspaces, const char *str, char *typo, char *correct)` allows for users to add additional handling to the autocorrection, or replace the functionality entirely. This passes on the number of backspaces needed to replace the words, as well as the replacement string (partial word, not the full word), and the typo and corrected strings (complete words). -?> Due to the way code works (no notion of words, just a stream of letters), the `typo` and `correct` strings are a best bet and could be "wrong". For example you may get `wordtpyo` & `wordtypo` instead of the expected `tpyo` & `typo`. +::: tip +Due to the way code works (no notion of words, just a stream of letters), the `typo` and `correct` strings are a best bet and could be "wrong". For example you may get `wordtpyo` & `wordtypo` instead of the expected `tpyo` & `typo`. +::: #### Apply Autocorrect Example @@ -223,9 +231,13 @@ bool apply_autocorrect(uint8_t backspaces, const char *str, char *typo, char *co } ``` -?> In this callback function, `return false` will stop the normal processing of autocorrect, which requires manually handling of removing the "bad" characters and typing the new characters. +::: tip +In this callback function, `return false` will stop the normal processing of autocorrect, which requires manually handling of removing the "bad" characters and typing the new characters. +::: -!> ***IMPORTANT***: `str` is a pointer to `PROGMEM` data for the autocorrection. If you return false, and want to send the string, this needs to use `send_string_P` and not `send_string` nor `SEND_STRING`. +::: warning +***IMPORTANT***: `str` is a pointer to `PROGMEM` data for the autocorrection. If you return false, and want to send the string, this needs to use `send_string_P` and not `send_string` nor `SEND_STRING`. +::: You can also use `apply_autocorrect` to detect and display the event but allow internal code to execute the autocorrection with `return true`: @@ -253,13 +265,13 @@ Additional user callback functions to manipulate Autocorrect: | `autocorrect_is_enabled()` | Returns true if Autocorrect is currently on. | -## Appendix: Trie binary data format :id=appendix +## Appendix: Trie binary data format {#appendix} This section details how the trie is serialized to byte data in autocorrect_data. You don’t need to care about this to use this autocorrection implementation. But it is documented for the record in case anyone is interested in modifying the implementation, or just curious how it works. What I did here is fairly arbitrary, but it is simple to decode and gets the job done. -### Encoding :id=encoding +### Encoding {#encoding} All autocorrection data is stored in a single flat array autocorrect_data. Each trie node is associated with a byte offset into this array, where data for that node is encoded, beginning with root at offset 0. There are three kinds of nodes. The highest two bits of the first byte of the node indicate what kind: @@ -299,7 +311,7 @@ If we were to encode this chain using the same format used for branching nodes, +-------+-------+-------+-------+-------+-------+ ``` -### Decoding :id=decoding +### Decoding {#decoding} This format is by design decodable with fairly simple logic. A 16-bit variable state represents our current position in the trie, initialized with 0 to start at the root node. Then, for each keycode, test the highest two bits in the byte at state to identify the kind of node. diff --git a/docs/feature_backlight.md b/docs/feature_backlight.md index 69391fcefe..545d7be949 100644 --- a/docs/feature_backlight.md +++ b/docs/feature_backlight.md @@ -1,10 +1,10 @@ -# Backlighting :id=backlighting +# Backlighting {#backlighting} -Many keyboards support backlit keys by way of individual LEDs placed through or underneath the keyswitches. This feature is distinct from both the [RGB Underglow](feature_rgblight.md) and [RGB Matrix](feature_rgb_matrix.md) features as it usually allows for only a single colour per switch, though you can obviously install multiple different single coloured LEDs on a keyboard. +Many keyboards support backlit keys by way of individual LEDs placed through or underneath the keyswitches. This feature is distinct from both the [RGB Underglow](feature_rgblight) and [RGB Matrix](feature_rgb_matrix) features as it usually allows for only a single colour per switch, though you can obviously install multiple different single coloured LEDs on a keyboard. QMK is able to control the brightness of these LEDs by switching them on and off rapidly in a certain ratio, a technique known as *Pulse Width Modulation*, or PWM. By altering the duty cycle of the PWM signal, it creates the illusion of dimming. -## Usage :id=usage +## Usage {#usage} Most keyboards have backlighting enabled by default if they support it, but if it is not working for you (or you have added support), check that your `rules.mk` includes the following: @@ -12,7 +12,7 @@ Most keyboards have backlighting enabled by default if they support it, but if i BACKLIGHT_ENABLE = yes ``` -## Keycodes :id=keycodes +## Keycodes {#keycodes} |Key |Aliases |Description | |-------------------------------|---------|-----------------------------------| @@ -24,7 +24,7 @@ BACKLIGHT_ENABLE = yes |`QK_BACKLIGHT_DOWN` |`BL_DOWN`|Decrease the backlight level | |`QK_BACKLIGHT_TOGGLE_BREATHING`|`BL_BRTG`|Toggle backlight breathing | -## Basic Configuration :id=basic-configuration +## Basic Configuration {#basic-configuration} Add the following to your `config.h`: @@ -43,7 +43,7 @@ Add the following to your `config.h`: Unless you are designing your own keyboard, you generally should not need to change the `BACKLIGHT_PIN` or `BACKLIGHT_ON_STATE`. -### "On" State :id=on-state +### "On" State {#on-state} Most backlight circuits are driven by an N-channel MOSFET or NPN transistor. This means that to turn the transistor *on* and light the LEDs, you must drive the backlight pin, connected to the gate or base, *high*. Sometimes, however, a P-channel MOSFET, or a PNP transistor is used. In this case, when the transistor is on, the pin is driven *low* instead. @@ -54,7 +54,7 @@ To configure the "on" state of the backlight circuit, add the following to your #define BACKLIGHT_ON_STATE 0 ``` -### Multiple Backlight Pins :id=multiple-backlight-pins +### Multiple Backlight Pins {#multiple-backlight-pins} Most keyboards have only one backlight pin which controls all backlight LEDs (especially if the backlight is connected to a hardware PWM pin). The `timer` and `software` drivers allow you to define multiple backlight pins, which will be turned on and off at the same time during the PWM duty cycle. @@ -67,11 +67,11 @@ To configure multiple backlight pins, add something like this to your `config.h` #define BACKLIGHT_PINS { F5, B2 } ``` -## Driver Configuration :id=driver-configuration +## Driver Configuration {#driver-configuration} Backlight driver selection is configured in `rules.mk`. Valid drivers are `pwm` (default), `timer`, `software`, or `custom`. See below for information on individual drivers. -### PWM Driver :id=pwm-driver +### PWM Driver {#pwm-driver} This is the default backlight driver, which leverages the hardware PWM output capability of the microcontroller. @@ -79,7 +79,7 @@ This is the default backlight driver, which leverages the hardware PWM output ca BACKLIGHT_DRIVER = pwm ``` -### Timer Driver :id=timer-driver +### Timer Driver {#timer-driver} This driver is similar to the PWM driver, but instead of directly configuring the pin to output a PWM signal, an interrupt handler is attached to the timer to turn the pin on and off as appropriate. @@ -87,7 +87,7 @@ This driver is similar to the PWM driver, but instead of directly configuring th BACKLIGHT_DRIVER = timer ``` -### Software Driver :id=software-driver +### Software Driver {#software-driver} In this mode, PWM is "emulated" while running other keyboard tasks. It offers maximum hardware compatibility without extra platform configuration. However, breathing is not supported, and the backlight can flicker when the keyboard is busy. @@ -95,7 +95,7 @@ In this mode, PWM is "emulated" while running other keyboard tasks. It offers ma BACKLIGHT_DRIVER = software ``` -### Custom Driver :id=custom-driver +### Custom Driver {#custom-driver} If none of the above drivers apply to your board (for example, you are using a separate IC to control the backlight), you can implement a custom backlight driver using a simple API. @@ -120,9 +120,9 @@ void backlight_task(void) { } ``` -## AVR Configuration :id=avr-configuration +## AVR Configuration {#avr-configuration} -### PWM Driver :id=avr-pwm-driver +### PWM Driver {#avr-pwm-driver} The following table describes the supported pins for the PWM driver. Only cells marked with a timer number are capable of hardware PWM output; any others must use the `timer` driver. @@ -139,7 +139,7 @@ The following table describes the supported pins for the PWM driver. Only cells |`D4` | | | | |Timer 1 | | |`D5` | | | | |Timer 1 | | -### Timer Driver :id=avr-timer-driver +### Timer Driver {#avr-timer-driver} Any GPIO pin can be used with this driver. The following table describes the supported timers: @@ -153,11 +153,11 @@ The following `#define`s apply only to the `timer` driver: |-----------------------|-------|----------------| |`BACKLIGHT_PWM_TIMER` |`1` |The timer to use| -Note that the choice of timer may conflict with the [Audio](feature_audio.md) feature. +Note that the choice of timer may conflict with the [Audio](feature_audio) feature. -## ChibiOS/ARM Configuration :id=arm-configuration +## ChibiOS/ARM Configuration {#arm-configuration} -### PWM Driver :id=arm-pwm-driver +### PWM Driver {#arm-pwm-driver} Depending on the ChibiOS board configuration, you may need to enable PWM at the keyboard level. For STM32, this would look like: @@ -183,7 +183,7 @@ The following `#define`s apply only to the `pwm` driver: Refer to the ST datasheet for your particular MCU to determine these values. For example, these defaults are set up for pin `B8` on a Proton-C (STM32F303) using `TIM4_CH3` on AF2. Unless you are designing your own keyboard, you generally should not need to change them. -### Timer Driver :id=arm-timer-driver +### Timer Driver {#arm-timer-driver} Depending on the ChibiOS board configuration, you may need to enable general-purpose timers at the keyboard level. For STM32, this would look like: @@ -213,97 +213,97 @@ The values of these resistors are not critical - see [this Electronics StackExch ![Backlight example circuit](https://i.imgur.com/BmAvoUC.png) -## API :id=api +## API {#api} -### `void backlight_toggle(void)` :id=api-backlight-toggle +### `void backlight_toggle(void)` {#api-backlight-toggle} Toggle the backlight on or off. --- -### `void backlight_enable(void)` :id=api-backlight-enable +### `void backlight_enable(void)` {#api-backlight-enable} Turn the backlight on. --- -### `void backlight_disable(void)` :id=api-backlight-disable +### `void backlight_disable(void)` {#api-backlight-disable} Turn the backlight off. --- -### `void backlight_step(void)` :id=api-backlight-step +### `void backlight_step(void)` {#api-backlight-step} Cycle through backlight levels. --- -### `void backlight_increase(void)` :id=api-backlight-increase +### `void backlight_increase(void)` {#api-backlight-increase} Increase the backlight level. --- -### `void backlight_decrease(void)` :id=api-backlight-decrease +### `void backlight_decrease(void)` {#api-backlight-decrease} Decrease the backlight level. --- -### `void backlight_level(uint8_t level)` :id=api-backlight-level +### `void backlight_level(uint8_t level)` {#api-backlight-level} Set the backlight level. -#### Arguments :id=api-backlight-level-arguments +#### Arguments {#api-backlight-level-arguments} - `uint8_t level` The level to set, from 0 to `BACKLIGHT_LEVELS`. --- -### `uint8_t get_backlight_level(void)` :id=api-get-backlight-level +### `uint8_t get_backlight_level(void)` {#api-get-backlight-level} Get the current backlight level. -#### Return Value :id=api-get-backlight-level-return +#### Return Value {#api-get-backlight-level-return} The current backlight level, from 0 to `BACKLIGHT_LEVELS`. --- -### `bool is_backlight_enabled(void)` :id=api-is-backlight-enabled +### `bool is_backlight_enabled(void)` {#api-is-backlight-enabled} Get the current backlight state. -#### Return Value :id=api-is-backlight-enabled-return +#### Return Value {#api-is-backlight-enabled-return} `true` if the backlight is enabled. --- -### `void backlight_toggle_breathing(void)` :id=api-backlight-toggle-breathing +### `void backlight_toggle_breathing(void)` {#api-backlight-toggle-breathing} Toggle backlight breathing on or off. --- -### `void backlight_enable_breathing(void)` :id=api-backlight-enable-breathing +### `void backlight_enable_breathing(void)` {#api-backlight-enable-breathing} Turn backlight breathing on. --- -### `void backlight_disable_breathing(void)` :id=api-backlight-disable-breathing +### `void backlight_disable_breathing(void)` {#api-backlight-disable-breathing} Turn backlight breathing off. --- -### `bool is_backlight_breathing(void)` :id=api-is-backlight-breathing +### `bool is_backlight_breathing(void)` {#api-is-backlight-breathing} Get the current backlight breathing state. -#### Return Value :id=api-is-backlight-breathing-return +#### Return Value {#api-is-backlight-breathing-return} `true` if backlight breathing is enabled. diff --git a/docs/feature_bluetooth.md b/docs/feature_bluetooth.md index 5fac06fba7..7562a75447 100644 --- a/docs/feature_bluetooth.md +++ b/docs/feature_bluetooth.md @@ -26,7 +26,7 @@ A Bluefruit UART friend can be converted to an SPI friend, however this [require ## Bluetooth Rules.mk Options -The currently supported Bluetooth chipsets do not support [N-Key Rollover (NKRO)](reference_glossary.md#n-key-rollover-nkro), so `rules.mk` must contain `NKRO_ENABLE = no`. +The currently supported Bluetooth chipsets do not support [N-Key Rollover (NKRO)](reference_glossary#n-key-rollover-nkro), so `rules.mk` must contain `NKRO_ENABLE = no`. Add the following to your `rules.mk`: diff --git a/docs/feature_bootmagic.md b/docs/feature_bootmagic.md index 564760be92..df0344ee8e 100644 --- a/docs/feature_bootmagic.md +++ b/docs/feature_bootmagic.md @@ -1,4 +1,4 @@ -# Bootmagic :id=bootmagic +# Bootmagic {#bootmagic} The Bootmagic feature that only handles jumping into the bootloader. This is great for boards that don't have a physical reset button, giving you a way to jump into the bootloader @@ -19,11 +19,13 @@ By default, these are set to 0 and 0, which is usually the "ESC" key on a majori And to trigger the bootloader, you hold this key down when plugging the keyboard in. Just the single key. -!> Using Bootmagic will **always reset** the EEPROM, so you will lose any settings that have been saved. +::: warning +Using Bootmagic will **always reset** the EEPROM, so you will lose any settings that have been saved. +::: ## Split Keyboards -When [handedness](feature_split_keyboard.md#setting-handedness) is predetermined via options like `SPLIT_HAND_PIN` or `EE_HANDS`, you might need to configure a different key between halves. To identify the correct key for the right half, examine the split key matrix defined in the `.h` file, e.g.: +When [handedness](feature_split_keyboard#setting-handedness) is predetermined via options like `SPLIT_HAND_PIN` or `EE_HANDS`, you might need to configure a different key between halves. To identify the correct key for the right half, examine the split key matrix defined in the `.h` file, e.g.: ```c #define LAYOUT_split_3x5_2( \ @@ -51,7 +53,9 @@ If you pick the top right key for the right half, it is `R05` on the top layout. #define BOOTMAGIC_COLUMN_RIGHT 4 ``` -?> These values are not set by default. +::: tip +These values are not set by default. +::: ## Advanced Bootmagic @@ -76,6 +80,6 @@ You can define additional logic here. For instance, resetting the EEPROM or requ ## Addenda -To manipulate settings that were formerly configured through the now-deprecated full Bootmagic feature, see [Magic Keycodes](keycodes_magic.md). +To manipulate settings that were formerly configured through the now-deprecated full Bootmagic feature, see [Magic Keycodes](keycodes_magic). -The Command feature, formerly known as Magic, also allows you to control different aspects of your keyboard. While it shares some functionality with Magic Keycodes, it also allows you to do things that Magic Keycodes cannot, such as printing version information to the console. For more information, see [Command](feature_command.md). +The Command feature, formerly known as Magic, also allows you to control different aspects of your keyboard. While it shares some functionality with Magic Keycodes, it also allows you to do things that Magic Keycodes cannot, such as printing version information to the console. For more information, see [Command](feature_command). diff --git a/docs/feature_caps_word.md b/docs/feature_caps_word.md index 7f726b059d..666edecb6e 100644 --- a/docs/feature_caps_word.md +++ b/docs/feature_caps_word.md @@ -32,7 +32,7 @@ a modern alternative to Caps Lock: shift](#configure-which-keys-are-word-breaking). -## How do I enable Caps Word :id=how-do-i-enable-caps-word +## How do I enable Caps Word {#how-do-i-enable-caps-word} In your `rules.mk`, add: @@ -62,16 +62,16 @@ Next, use one the following methods to activate Caps Word: * **Custom activation**: You can activate Caps Word from code by calling `caps_word_on()`. This may be used to activate Caps Word through [a - combo](feature_combo.md) or [tap dance](feature_tap_dance.md) or any means + combo](feature_combo) or [tap dance](feature_tap_dance) or any means you like. -### Troubleshooting: Command :id=troubleshooting-command +### Troubleshooting: Command {#troubleshooting-command} When using `BOTH_SHIFTS_TURNS_ON_CAPS_WORD`, you might see a compile message **"BOTH_SHIFTS_TURNS_ON_CAPS_WORD and Command should not be enabled at the same time, since both use the Left Shift + Right Shift key combination."** -Many keyboards enable the [Command feature](feature_command.md), which by +Many keyboards enable the [Command feature](feature_command), which by default is also activated using the Left Shift + Right Shift key combination. To fix this conflict, please disable Command by adding in rules.mk: @@ -88,9 +88,9 @@ by defining `IS_COMMAND()` in config.h: ``` -## Customizing Caps Word :id=customizing-caps-word +## Customizing Caps Word {#customizing-caps-word} -### Invert on shift :id=invert-on-shift +### Invert on shift {#invert-on-shift} By default, Caps Word turns off when Shift keys are pressed, considering them as word-breaking. Alternatively with the `CAPS_WORD_INVERT_ON_SHIFT` option, @@ -110,7 +110,7 @@ keys, and one-shot Shift keys. Note that while Caps Word is on, one-shot Shift keys behave like regular Shift keys, and have effect only while they are held. -### Idle timeout :id=idle-timeout +### Idle timeout {#idle-timeout} Caps Word turns off automatically if no keys are pressed for `CAPS_WORD_IDLE_TIMEOUT` milliseconds. The default is 5000 (5 seconds). @@ -124,7 +124,7 @@ Setting `CAPS_WORD_IDLE_TIMEOUT` to 0 configures Caps Word to never time out. Caps Word then remains active indefinitely until a word breaking key is pressed. -### Functions :id=functions +### Functions {#functions} Functions to manipulate Caps Word: @@ -136,7 +136,7 @@ Functions to manipulate Caps Word: | `is_caps_word_on()` | Returns true if Caps Word is currently on. | -### Configure which keys are "word breaking" :id=configure-which-keys-are-word-breaking +### Configure which keys are "word breaking" {#configure-which-keys-are-word-breaking} You can define the `caps_word_press_user(uint16_t keycode)` callback to configure which keys should be shifted and which keys are considered "word @@ -171,7 +171,7 @@ bool caps_word_press_user(uint16_t keycode) { ``` -### Representing Caps Word state :id=representing-caps-word-state +### Representing Caps Word state {#representing-caps-word-state} Define `caps_word_set_user(bool active)` to get callbacks when Caps Word turns on or off. This is useful to represent the current Caps Word state, e.g. by diff --git a/docs/feature_combo.md b/docs/feature_combo.md index 496e97bd3c..b49a444804 100644 --- a/docs/feature_combo.md +++ b/docs/feature_combo.md @@ -18,7 +18,7 @@ combo_t key_combos[] = { This will send "Escape" if you hit the A and B keys, and Ctrl+Z when you hit the C and D keys. ## Advanced Keycodes Support -Advanced keycodes, such as [Mod-Tap](mod_tap.md) and [Tap Dance](feature_tap_dance.md) are also supported together with combos. If you use these advanced keycodes in your keymap, you will need to place the full keycode in the combo definition, e.g.: +Advanced keycodes, such as [Mod-Tap](mod_tap) and [Tap Dance](feature_tap_dance) are also supported together with combos. If you use these advanced keycodes in your keymap, you will need to place the full keycode in the combo definition, e.g.: ```c const uint16_t PROGMEM test_combo1[] = {LSFT_T(KC_A), LT(1, KC_B), COMBO_END}; @@ -99,7 +99,7 @@ void process_combo_event(uint16_t combo_index, bool pressed) { This will send "john.doe@example.com" if you chord E and M together, and clear the current line with Backspace and Left-Shift. You could change this to do stuff like play sounds or change settings. -It is worth noting that `COMBO_ACTION`s are not needed anymore. As of [PR#8591](https://github.com/qmk/qmk_firmware/pull/8591/), it is possible to run your own custom keycodes from combos. Just define the custom keycode, program its functionality in `process_record_user`, and define a combo with `COMBO(, )`. See the first example in [Macros](feature_macros.md). +It is worth noting that `COMBO_ACTION`s are not needed anymore. As of [PR#8591](https://github.com/qmk/qmk_firmware/pull/8591/), it is possible to run your own custom keycodes from combos. Just define the custom keycode, program its functionality in `process_record_user`, and define a combo with `COMBO(, )`. See the first example in [Macros](feature_macros). ## Keycodes You can enable, disable and toggle the Combo feature on the fly. This is useful if you need to disable them temporarily, such as for a game. The following keycodes are available for use in your `keymap.c` @@ -373,7 +373,9 @@ In addition to the keycodes, there are a few functions that you can use to set t Having 3 places to update when adding new combos or altering old ones does become cumbersome when you have a lot of combos. We can alleviate this with some magic! ... If you consider C macros magic. First, you need to add `VPATH += keyboards/gboards` to your `rules.mk`. Next, include the file `g/keymap_combo.h` in your `keymap.c`. -!> This functionality uses the same `process_combo_event` function as `COMBO_ACTION` macros do, so you cannot use the function yourself in your keymap. Instead, you have to define the `case`s of the `switch` statement by themselves within `inject.h`, which `g/keymap_combo.h` will then include into the function. +::: warning +This functionality uses the same `process_combo_event` function as `COMBO_ACTION` macros do, so you cannot use the function yourself in your keymap. Instead, you have to define the `case`s of the `switch` statement by themselves within `inject.h`, which `g/keymap_combo.h` will then include into the function. +::: Then, write your combos in `combos.def` file in the following manner: diff --git a/docs/feature_command.md b/docs/feature_command.md index 8300066131..4aba9cfb63 100644 --- a/docs/feature_command.md +++ b/docs/feature_command.md @@ -1,6 +1,6 @@ # Command -Command, formerly known as Magic, is a way to change your keyboard's behavior without having to flash or unplug it to use [Bootmagic Lite](feature_bootmagic.md). There is a lot of overlap between this functionality and the [Magic Keycodes](keycodes_magic.md). Wherever possible we encourage you to use that feature instead of Command. +Command, formerly known as Magic, is a way to change your keyboard's behavior without having to flash or unplug it to use [Bootmagic Lite](feature_bootmagic). There is a lot of overlap between this functionality and the [Magic Keycodes](keycodes_magic). Wherever possible we encourage you to use that feature instead of Command. On some keyboards Command is disabled by default. If this is the case, it must be explicitly enabled in your `rules.mk`: diff --git a/docs/feature_converters.md b/docs/feature_converters.md index 62c214e246..9b2d027a66 100644 --- a/docs/feature_converters.md +++ b/docs/feature_converters.md @@ -38,7 +38,9 @@ qmk flash -c -kb keebio/bdn9/rev1 -km default -e CONVERT_TO=proton_c You can also add the same `CONVERT_TO=` to your keymap's `rules.mk`, which will accomplish the same thing. -?> If you get errors about `PORTB/DDRB`, etc not being defined, you'll need to convert the keyboard's code to use the [GPIO Controls](gpio_control.md) that will work for both ARM and AVR. This shouldn't affect the AVR builds at all. +::: tip +If you get errors about `PORTB/DDRB`, etc not being defined, you'll need to convert the keyboard's code to use the [GPIO Controls](gpio_control) that will work for both ARM and AVR. This shouldn't affect the AVR builds at all. +::: ### Conditional Configuration @@ -104,7 +106,7 @@ Converter summary: | `imera` | `-e CONVERT_TO=imera` | `CONVERT_TO=imera` | `#ifdef CONVERT_TO_IMERA` | | `michi` | `-e CONVERT_TO=michi` | `CONVERT_TO=michi` | `#ifdef CONVERT_TO_MICHI` | -### Proton C :id=proton_c +### Proton C {#proton_c} The Proton C only has one on-board LED (C13), and by default, the TXLED (D5) is mapped to it. If you want the RXLED (B0) mapped to it instead, add this line to your `config.h`: @@ -116,28 +118,28 @@ The following defaults are based on what has been implemented for STM32 boards. | Feature | Notes | |----------------------------------------------|------------------------------------------------------------------------------------------------------------------| -| [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 | +| [Audio](feature_audio) | Enabled | +| [RGB Lighting](feature_rgblight) | Disabled | +| [Backlight](feature_backlight) | Forces [task driven PWM](feature_backlight#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) | Partial - heavily dependent on enabled features | +| [Split keyboards](feature_split_keyboard) | Partial - heavily dependent on enabled features | -### Adafruit KB2040 :id=kb2040 +### Adafruit KB2040 {#kb2040} -The following defaults are based on what has been implemented for [RP2040](platformdev_rp2040.md) boards. +The following defaults are based on what has been implemented for [RP2040](platformdev_rp2040) boards. | Feature | Notes | |----------------------------------------------|------------------------------------------------------------------------------------------------------------------| -| [RGB Lighting](feature_rgblight.md) | Enabled via `PIO` vendor driver | -| [Backlight](feature_backlight.md) | Forces [task driven PWM](feature_backlight.md#software-pwm-driver) until ARM can provide automatic configuration | +| [RGB Lighting](feature_rgblight) | Enabled via `PIO` vendor driver | +| [Backlight](feature_backlight) | Forces [task driven PWM](feature_backlight#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) | Partial via `PIO` vendor driver - heavily dependent on enabled features | +| [Split keyboards](feature_split_keyboard) | Partial via `PIO` vendor driver - heavily dependent on enabled features | -### SparkFun Pro Micro - RP2040, Blok, Bit-C PRO and Michi :id=promicro_rp2040 +### SparkFun Pro Micro - RP2040, Blok, Bit-C PRO and Michi {#promicro_rp2040 } Feature set is identical to [Adafruit KB2040](#kb2040). -### STeMCell :id=stemcell +### STeMCell {#stemcell} Feature set currently identical to [Proton C](#proton_c). There are two versions of STeMCell available, with different pinouts: @@ -154,7 +156,7 @@ STeMCell has support to swap UART and I2C pins to enable single-wire uart commun | D1 | -e STMC_IS=yes| | D0 | Not needed | -### Bonsai C4 :id=bonsai_c4 +### Bonsai C4 {#bonsai_c4} The Bonsai C4 only has one on-board LED (B2), and by default, both the Pro Micro TXLED (D5) and RXLED (B0) are mapped to it. If you want only one of them mapped, you can undefine one and redefine it to another pin by adding these line to your `config.h`: @@ -164,9 +166,9 @@ The Bonsai C4 only has one on-board LED (B2), and by default, both the Pro Micro #define B0 PAL_LINE(GPIOA, 9) ``` -### RP2040 Community Edition - Elite-Pi, Helios, and Liatris :id=rp2040_ce +### RP2040 Community Edition - Elite-Pi, Helios, and Liatris {#rp2040_ce} -Feature set is identical to [Adafruit KB2040](#kb2040). VBUS detection is enabled by default for superior split keyboard support. For more information, refer to the [Community Edition pinout](platformdev_rp2040.md#rp2040_ce) docs. +Feature set is identical to [Adafruit KB2040](#kb2040). VBUS detection is enabled by default for superior split keyboard support. For more information, refer to the [Community Edition pinout](platformdev_rp2040#rp2040_ce) docs. ## Elite-C @@ -190,10 +192,10 @@ Converter summary: | `helios` | `-e CONVERT_TO=helios` | `CONVERT_TO=helios` | `#ifdef CONVERT_TO_HELIOS` | | `liatris` | `-e CONVERT_TO=liatris` | `CONVERT_TO=liatris` | `#ifdef CONVERT_TO_LIATRIS` | -### STeMCell :id=stemcell_elite +### STeMCell {#stemcell}_elite Identical to [Pro Micro - STeMCell](#stemcell) with support for the additional bottom row of pins. -### RP2040 Community Edition :id=rp2040_ce_elite +### RP2040 Community Edition {#rp2040_ce_elite} Identical to [Pro Micro - RP2040 Community Edition](#rp2040_ce) with support for the additional bottom row of pins. diff --git a/docs/feature_debounce_type.md b/docs/feature_debounce_type.md index 807b902a6c..eb29b4ef26 100644 --- a/docs/feature_debounce_type.md +++ b/docs/feature_debounce_type.md @@ -99,7 +99,9 @@ Default debounce time is 5 milliseconds and it can be changed with the following ``` #define DEBOUNCE 10 ``` -?> Setting `DEBOUNCE` to `0` will disable this feature. +::: tip +Setting `DEBOUNCE` to `0` will disable this feature. +::: ### Debounce Method @@ -118,9 +120,13 @@ Name of algorithm is one of: | `sym_eager_pk` | Debouncing per key. On any state change, response is immediate, followed by `DEBOUNCE` milliseconds of no further input for that key. | | `asym_eager_defer_pk` | Debouncing per key. On a key-down state change, response is immediate, followed by `DEBOUNCE` milliseconds of no further input for that key. On a key-up state change, a per-key timer is set. When `DEBOUNCE` milliseconds of no changes have occurred on that key, the key-up status change is pushed. | -?> `sym_defer_g` is the default if `DEBOUNCE_TYPE` is undefined. +::: tip +`sym_defer_g` is the default if `DEBOUNCE_TYPE` is undefined. +::: -?> `sym_eager_pr` is suitable for use in keyboards where refreshing `NUM_KEYS` 8-bit counters is computationally expensive or has low scan rate while fingers usually hit one row at a time. This could be appropriate for the ErgoDox models where the matrix is rotated 90°. Hence its "rows" are really columns and each finger only hits a single "row" at a time with normal usage. +::: tip +`sym_eager_pr` is suitable for use in keyboards where refreshing `NUM_KEYS` 8-bit counters is computationally expensive or has low scan rate while fingers usually hit one row at a time. This could be appropriate for the ErgoDox models where the matrix is rotated 90°. Hence its "rows" are really columns and each finger only hits a single "row" at a time with normal usage. +::: ### Implementing your own debouncing code diff --git a/docs/feature_digitizer.md b/docs/feature_digitizer.md index 2e9e37cd5f..905ad9cbd0 100644 --- a/docs/feature_digitizer.md +++ b/docs/feature_digitizer.md @@ -1,10 +1,10 @@ -# Digitizer :id=digitizer +# Digitizer {#digitizer} -Digitizers allow the mouse cursor to be placed at absolute coordinates, unlike the [Pointing Device](feature_pointing_device.md) feature which applies relative displacements. +Digitizers allow the mouse cursor to be placed at absolute coordinates, unlike the [Pointing Device](feature_pointing_device) feature which applies relative displacements. This feature implements a stylus device with a tip switch and barrel switch (generally equivalent to the primary and secondary mouse buttons respectively). Tip pressure is not currently implemented. -## Usage :id=usage +## Usage {#usage} Add the following to your `rules.mk`: @@ -12,13 +12,15 @@ Add the following to your `rules.mk`: DIGITIZER_ENABLE = yes ``` -## Positioning :id=positioning +## Positioning {#positioning} The X and Y coordinates are normalized, meaning their value must be set between 0 and 1. For the X component, the value `0` is the leftmost position, whereas the value `1` is the rightmost position. Similarly for the Y component, `0` is at the top and `1` at the bottom. -?> Since there is no display attached, the OS will likely map these coordinates to the virtual desktop. This may be important to know if you have multiple monitors. +::: tip +Since there is no display attached, the OS will likely map these coordinates to the virtual desktop. This may be important to know if you have multiple monitors. +::: -## Examples :id=examples +## Examples {#examples} This example simply places the cursor in the middle of the screen: @@ -40,13 +42,13 @@ digitizer_flush(); `digitizer_state` is a struct of type `digitizer_t`. -## API :id=api +## API {#api} -### `struct digitizer_t` :id=api-digitizer-t +### `struct digitizer_t` {#api-digitizer-t} Contains the state of the digitizer. -#### Members :id=api-digitizer-t-members +#### Members {#api-digitizer-t-members} - `bool in_range` Indicates to the host that the contact is within range (ie. close to or in contact with the digitizer surface). @@ -63,7 +65,7 @@ Contains the state of the digitizer. --- -### `void digitizer_flush(void)` :id=api-digitizer-flush +### `void digitizer_flush(void)` {#api-digitizer-flush} Send the digitizer report to the host if it is marked as dirty. @@ -109,7 +111,7 @@ Deassert the barrel switch, and flush the report. Set the absolute X and Y position of the digitizer contact, and flush the report. -#### Arguments :id=api-digitizer-set-position-arguments +#### Arguments {#api-digitizer-set-position-arguments} - `float x` The X value of the contact position, from 0 to 1. diff --git a/docs/feature_dip_switch.md b/docs/feature_dip_switch.md index 0e31f5acae..738331bef0 100644 --- a/docs/feature_dip_switch.md +++ b/docs/feature_dip_switch.md @@ -20,7 +20,7 @@ or #define DIP_SWITCH_MATRIX_GRID { {0,6}, {1,6}, {2,6} } // List of row and col pairs ``` -## DIP Switch map :id=dip-switch-map +## DIP Switch map {#dip-switch-map} DIP Switch mapping may be added to your `keymap.c`, which replicates the normal keyswitch functionality, but with dip switches. Add this to your keymap's `rules.mk`: @@ -39,7 +39,9 @@ const uint16_t PROGMEM dip_switch_map[NUM_DIP_SWITCHES][NUM_DIP_STATES] = { #endif ``` -?> This should only be enabled at the keymap level. +::: tip +This should only be enabled at the keymap level. +::: ## Callbacks diff --git a/docs/feature_dynamic_macros.md b/docs/feature_dynamic_macros.md index 8ab1bad61c..a642ced43e 100644 --- a/docs/feature_dynamic_macros.md +++ b/docs/feature_dynamic_macros.md @@ -24,7 +24,9 @@ To replay the macro, press either `DM_PLY1` or `DM_PLY2`. 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 completely by defining `DYNAMIC_MACRO_NO_NESTING` in your `config.h` file. -?> 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. +::: tip +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. +::: ## Customization diff --git a/docs/feature_eeprom.md b/docs/feature_eeprom.md index 088f4f36ff..63026d3c10 100644 --- a/docs/feature_eeprom.md +++ b/docs/feature_eeprom.md @@ -109,7 +109,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 `EE_CLR` keycode or [Bootmagic Lite](feature_bootmagic.md) functionallity. For example, if you want to set rgb layer indication by default, and save the default valued. +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 `EE_CLR` keycode or [Bootmagic Lite](feature_bootmagic) 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! diff --git a/docs/feature_encoders.md b/docs/feature_encoders.md index 4eeb388e57..3d1cac79af 100644 --- a/docs/feature_encoders.md +++ b/docs/feature_encoders.md @@ -67,9 +67,11 @@ Additionally, if one side does not have an encoder, you can specify `{}` for the #define ENCODER_RESOLUTIONS_RIGHT { 4 } ``` -!> Keep in mind that whenver you change the encoder resolution, you will need to reflash the half that has the encoder affected by the change. +::: warning +Keep in mind that whenver you change the encoder resolution, you will need to reflash the half that has the encoder affected by the change. +::: -## Encoder map :id=encoder-map +## Encoder map {#encoder-map} Encoder mapping may be added to your `keymap.c`, which replicates the normal keyswitch layer handling functionality, but with encoders. Add this to your keymap's `rules.mk`: @@ -90,7 +92,9 @@ const uint16_t PROGMEM encoder_map[][NUM_ENCODERS][NUM_DIRECTIONS] = { #endif ``` -?> This should only be enabled at the keymap level. +::: tip +This should only be enabled at the keymap level. +::: Using encoder mapping pumps events through the normal QMK keycode processing pipeline, resulting in a _keydown/keyup_ combination pushed through `process_record_xxxxx()`. To configure the amount of time between the encoder "keyup" and "keydown", you can add the following to your `config.h`: @@ -98,11 +102,15 @@ Using encoder mapping pumps events through the normal QMK keycode processing pip #define ENCODER_MAP_KEY_DELAY 10 ``` -?> By default, the encoder map delay matches the value of `TAP_CODE_DELAY`. +::: tip +By default, the encoder map delay matches the value of `TAP_CODE_DELAY`. +::: ## Callbacks -?> [**Default Behaviour**](https://github.com/qmk/qmk_firmware/blob/master/quantum/encoder.c#L79-#L98): all encoders installed will function as volume up (`KC_VOLU`) on clockwise rotation and volume down (`KC_VOLD`) on counter-clockwise rotation. If you do not wish to override this, no further configuration is necessary. +::: tip +[**Default Behaviour**](https://github.com/qmk/qmk_firmware/blob/master/quantum/encoder.c#L79-): all encoders installed will function as volume up (`KC_VOLU`) on clockwise rotation and volume down (`KC_VOLD`) on counter-clockwise rotation. If you do not wish to override this, no further configuration is necessary. +::: If you would like the alter the default behaviour, and are not using `ENCODER_MAP_ENABLE = yes`, the callback functions can be inserted into your `.c`: @@ -149,7 +157,9 @@ bool encoder_update_user(uint8_t index, bool clockwise) { } ``` -!> If you return `true` in the keymap level `_user` function, it will allow the keyboard/core level encoder code to run on top of your own. Returning `false` will override the keyboard level function, if setup correctly. This is generally the safest option to avoid confusion. +::: warning +If you return `true` in the keymap level `_user` function, it will allow the keyboard/core level encoder code to run on top of your own. Returning `false` will override the keyboard level function, if setup correctly. This is generally the safest option to avoid confusion. +::: ## Hardware diff --git a/docs/feature_haptic_feedback.md b/docs/feature_haptic_feedback.md index 68145edd6c..16370327cb 100644 --- a/docs/feature_haptic_feedback.md +++ b/docs/feature_haptic_feedback.md @@ -192,11 +192,11 @@ The Haptic Exclusion is implemented as `__attribute__((weak)) bool get_haptic_en With the entry of `#define NO_HAPTIC_MOD` in config.h, the following keys will not trigger feedback: * Usual modifier keys such as Control/Shift/Alt/Gui (For example `KC_LCTL`) -* `MO()` momentary keys. See also [Layers](feature_layers.md). +* `MO()` momentary keys. See also [Layers](feature_layers). * `LM()` momentary keys with mod active. * `LT()` layer tap keys, when held to activate a layer. However when tapped, and the key is quickly released, and sends a keycode, haptic feedback is still triggered. * `TT()` layer tap toggle keys, when held to activate a layer. However when tapped `TAPPING_TOGGLE` times to permanently toggle the layer, on the last tap haptic feedback is still triggered. -* `MT()` mod tap keys, when held to keep a usual modifier key pressed. However when tapped, and the key is quickly released, and sends a keycode, haptic feedback is still triggered. See also [Mod-Tap](mod_tap.md). +* `MT()` mod tap keys, when held to keep a usual modifier key pressed. However when tapped, and the key is quickly released, and sends a keycode, haptic feedback is still triggered. See also [Mod-Tap](mod_tap). ### NO_HAPTIC_ALPHA With the entry of `#define NO_HAPTIC_ALPHA` in config.h, none of the alpha keys (A ... Z) will trigger a feedback. diff --git a/docs/feature_hd44780.md b/docs/feature_hd44780.md index dcbd656bbe..6b4209333b 100644 --- a/docs/feature_hd44780.md +++ b/docs/feature_hd44780.md @@ -1,6 +1,6 @@ -# HD44780 LCD Driver :id=hd44780-lcd-driver +# HD44780 LCD Driver {#hd44780-lcd-driver} -## Supported Hardware :id=supported-hardware +## Supported Hardware {#supported-hardware} LCD modules using [HD44780U](https://www.sparkfun.com/datasheets/LCD/HD44780.pdf) IC or equivalent, communicating in 4-bit mode. @@ -11,7 +11,7 @@ LCD modules using [HD44780U](https://www.sparkfun.com/datasheets/LCD/HD44780.pdf To run these modules at 3.3V, an additional MAX660 voltage converter IC must be soldered on, along with two 10µF capacitors. See [this page](https://www.codrey.com/electronic-circuits/hack-your-16x2-lcd/) for more details. -## Usage :id=usage +## Usage {#usage} Add the following to your `rules.mk`: @@ -19,7 +19,7 @@ Add the following to your `rules.mk`: HD44780_ENABLE = yes ``` -## Basic Configuration :id=basic-configuration +## Basic Configuration {#basic-configuration} Add the following to your `config.h`: @@ -33,9 +33,9 @@ Add the following to your `config.h`: |`HD44780_DISPLAY_LINES`|`2` |The number of visible lines on the display | |`HD44780_WRAP_LINES` |*Not defined* |If defined, input characters will wrap to the next line | -## Examples :id=examples +## Examples {#examples} -### Hello World :id=example-hello-world +### Hello World {#example-hello-world} Add the following to your `keymap.c`: @@ -46,7 +46,7 @@ void keyboard_post_init_user(void) { } ``` -### Custom Character Definition :id=example-custom-character +### Custom Character Definition {#example-custom-character} Up to eight custom characters can be defined. This data is stored in the Character Generator RAM (CGRAM), and is not persistent across power cycles. @@ -77,15 +77,15 @@ void keyboard_post_init_user(void) { } ``` -## API :id=api +## API {#api} -### `void hd44780_init(bool cursor, bool blink)` :id=api-hd44780-init +### `void hd44780_init(bool cursor, bool blink)` {#api-hd44780-init} Initialize the display. This function should be called only once, before any of the other functions can be called. -#### Arguments :id=api-hd44780-init-arguments +#### Arguments {#api-hd44780-init-arguments} - `bool cursor` Whether to show the cursor. @@ -94,7 +94,7 @@ This function should be called only once, before any of the other functions can --- -### `void hd44780_clear(void)` :id=api-hd44780-clear +### `void hd44780_clear(void)` {#api-hd44780-clear} Clear the display. @@ -102,7 +102,7 @@ This function is called on init. --- -### `void hd44780_home(void)` :id=api-hd44780-home +### `void hd44780_home(void)` {#api-hd44780-home} Move the cursor to the home position. @@ -110,13 +110,13 @@ This function is called on init. --- -### `void hd44780_on(bool cursor, bool blink)` :id=api-hd44780-on +### `void hd44780_on(bool cursor, bool blink)` {#api-hd44780-on} Turn the display on, and/or set the cursor properties. This function is called on init. -#### Arguments :id=api-hd44780-on-arguments +#### Arguments {#api-hd44780-on-arguments} - `bool cursor` Whether to show the cursor. @@ -125,17 +125,17 @@ This function is called on init. --- -### `void hd44780_off(void)` :id=api-hd44780-off +### `void hd44780_off(void)` {#api-hd44780-off} Turn the display off. --- -### `void hd44780_set_cursor(uint8_t col, uint8_t line)` :id=api-hd44780-set-cursor +### `void hd44780_set_cursor(uint8_t col, uint8_t line)` {#api-hd44780-set-cursor} Move the cursor to the specified position on the display. -#### Arguments :id=api-hd44780-set-cursor-arguments +#### Arguments {#api-hd44780-set-cursor-arguments} - `uint8_t col` The column number to move to, from 0 to 15 on 16x2 displays. @@ -144,48 +144,48 @@ Move the cursor to the specified position on the display. --- -### `void hd44780_putc(char c)` :id=api-hd44780-putc +### `void hd44780_putc(char c)` {#api-hd44780-putc} Print a character to the display. The newline character `\n` will move the cursor to the start of the next line. The exact character shown may depend on the ROM code of your particular display - refer to the datasheet for the full character set. -#### Arguments :id=api-hd44780-putc-arguments +#### Arguments {#api-hd44780-putc-arguments} - `char c` The character to print. --- -### `void hd44780_puts(const char *s)` :id=api-hd44780-puts +### `void hd44780_puts(const char *s)` {#api-hd44780-puts} Print a string of characters to the display. -#### Arguments :id=api-hd44780-puts-arguments +#### Arguments {#api-hd44780-puts-arguments} - `const char *s` The string to print. --- -### `void hd44780_puts_P(const char *s)` :id=api-hd44780-puts-p +### `void hd44780_puts_P(const char *s)` {#api-hd44780-puts-p} Print a string of characters from PROGMEM to the display. On ARM devices, this function is simply an alias of `hd44780_puts()`. -#### Arguments :id=api-hd44780-puts-p-arguments +#### Arguments {#api-hd44780-puts-p-arguments} - `const char *s` The PROGMEM string to print (ie. `PSTR("Hello")`). --- -### `void hd44780_define_char(uint8_t index, uint8_t *data)` :id=api-hd44780-define-char +### `void hd44780_define_char(uint8_t index, uint8_t *data)` {#api-hd44780-define-char} Define a custom character. -#### Arguments :id=api-hd44780-define-char-arguments +#### Arguments {#api-hd44780-define-char-arguments} - `uint8_t index` The index of the custom character to define, from 0 to 7. @@ -194,13 +194,13 @@ Define a custom character. --- -### `void hd44780_define_char_P(uint8_t index, const uint8_t *data)` :id=api-hd44780-define-char-p +### `void hd44780_define_char_P(uint8_t index, const uint8_t *data)` {#api-hd44780-define-char-p} Define a custom character from PROGMEM. On ARM devices, this function is simply an alias of `hd44780_define_char()`. -#### Arguments :id=api-hd44780-define-char-p-arguments +#### Arguments {#api-hd44780-define-char-p-arguments} - `uint8_t index` The index of the custom character to define, from 0 to 7. @@ -209,21 +209,21 @@ On ARM devices, this function is simply an alias of `hd44780_define_char()`. --- -### `bool hd44780_busy(void)` :id=api-hd44780-busy +### `bool hd44780_busy(void)` {#api-hd44780-busy} Indicates whether the display is currently processing, and cannot accept instructions. -#### Return Value :id=api-hd44780-busy-arguments +#### Return Value {#api-hd44780-busy-arguments} `true` if the display is busy. --- -### `void hd44780_write(uint8_t data, bool isData)` :id=api-hd44780-write +### `void hd44780_write(uint8_t data, bool isData)` {#api-hd44780-write} Write a byte to the display. -#### Arguments :id=api-hd44780-write-arguments +#### Arguments {#api-hd44780-write-arguments} - `uint8_t data` The byte to send to the display. @@ -232,67 +232,67 @@ Write a byte to the display. --- -### `uint8_t hd44780_read(bool isData)` :id=api-hd44780-read +### `uint8_t hd44780_read(bool isData)` {#api-hd44780-read} Read a byte from the display. -#### Arguments :id=api-hd44780-read-arguments +#### Arguments {#api-hd44780-read-arguments} - `bool isData` Whether to read the current cursor position, or the character at the cursor. -#### Return Value :id=api-hd44780-read-return +#### Return Value {#api-hd44780-read-return} If `isData` is `true`, the returned byte will be the character at the current DDRAM address. Otherwise, it will be the current DDRAM address and the busy flag. --- -### `void hd44780_command(uint8_t command)` :id=api-hd44780-command +### `void hd44780_command(uint8_t command)` {#api-hd44780-command} Send a command to the display. Refer to the datasheet and `hd44780.h` for the valid commands and defines. This function waits for the display to clear the busy flag before sending the command. -#### Arguments :id=api-hd44780-command-arguments +#### Arguments {#api-hd44780-command-arguments} - `uint8_t command` The command to send. --- -### `void hd44780_data(uint8_t data)` :id=api-hd44780-data +### `void hd44780_data(uint8_t data)` {#api-hd44780-data} Send a byte of data to the display. This function waits for the display to clear the busy flag before sending the data. -#### Arguments :id=api-hd44780-data-arguments +#### Arguments {#api-hd44780-data-arguments} - `uint8_t data` The byte of data to send. --- -### `void hd44780_set_cgram_address(uint8_t address)` :id=api-hd44780-set-cgram-address +### `void hd44780_set_cgram_address(uint8_t address)` {#api-hd44780-set-cgram-address} Set the CGRAM address. This function is used when defining custom characters. -#### Arguments :id=api-hd44780-set-cgram-address-arguments +#### Arguments {#api-hd44780-set-cgram-address-arguments} - `uint8_t address` The CGRAM address to move to, from `0x00` to `0x3F`. --- -### `void hd44780_set_ddram_address(uint8_t address)` :id=api-hd44780-set-ddram-address +### `void hd44780_set_ddram_address(uint8_t address)` {#api-hd44780-set-ddram-address} Set the DDRAM address. This function is used when printing characters to the display, and setting the cursor. -#### Arguments :id=api-hd44780-set-ddram-address-arguments +#### Arguments {#api-hd44780-set-ddram-address-arguments} - `uint8_t address` The DDRAM address to move to, from `0x00` to `0x7F`. diff --git a/docs/feature_joystick.md b/docs/feature_joystick.md index 0e4529b2eb..75bffa605a 100644 --- a/docs/feature_joystick.md +++ b/docs/feature_joystick.md @@ -1,10 +1,10 @@ -# Joystick :id=joystick +# Joystick {#joystick} -This feature provides game controller input as a joystick device supporting up to 6 axes and 32 buttons. Axes can be read either from an [ADC-capable input pin](adc_driver.md), or can be virtual, so that its value is provided by your code. +This feature provides game controller input as a joystick device supporting up to 6 axes and 32 buttons. Axes can be read either from an [ADC-capable input pin](adc_driver), or can be virtual, so that its value is provided by your code. An analog device such as a [potentiometer](https://en.wikipedia.org/wiki/Potentiometer) found on an analog joystick's axes is based on a voltage divider, where adjusting the movable wiper controls the output voltage which can then be read by the microcontroller's ADC. -## Usage :id=usage +## Usage {#usage} Add the following to your `rules.mk`: @@ -18,7 +18,7 @@ By default the joystick driver is `analog`, but you can change this with: JOYSTICK_DRIVER = digital ``` -## Configuration :id=configuration +## Configuration {#configuration} By default, two axes and eight buttons are defined, with a reported resolution of 8 bits (-127 to +127). This can be changed in your `config.h`: @@ -31,9 +31,11 @@ By default, two axes and eight buttons are defined, with a reported resolution o #define JOYSTICK_AXIS_RESOLUTION 10 ``` -?> You must define at least one button or axis. Also note that the maximum ADC resolution of the supported AVR MCUs is 10-bit, and 12-bit for most STM32 MCUs. +::: tip +You must define at least one button or axis. Also note that the maximum ADC resolution of the supported AVR MCUs is 10-bit, and 12-bit for most STM32 MCUs. +::: -### Axes :id=axes +### Axes {#axes} When defining axes for your joystick, you must provide a definition array typically in your `keymap.c`. @@ -55,7 +57,7 @@ Axes can be configured using one of the following macros: The `low` and `high` values can be swapped to effectively invert the axis. -#### Virtual Axes :id=virtual-axes +#### Virtual Axes {#virtual-axes} The following example adjusts two virtual axes (X and Y) based on keypad presses, with `KC_P0` as a precision modifier: @@ -96,7 +98,7 @@ bool process_record_user(uint16_t keycode, keyrecord_t *record) { } ``` -## Keycodes :id=keycodes +## Keycodes {#keycodes} |Key |Aliases|Description| |-----------------------|-------|-----------| @@ -133,13 +135,13 @@ bool process_record_user(uint16_t keycode, keyrecord_t *record) { |`QK_JOYSTICK_BUTTON_30`|`JS_30`|Button 30 | |`QK_JOYSTICK_BUTTON_31`|`JS_31`|Button 31 | -## API :id=api +## API {#api} -### `struct joystick_t` :id=api-joystick-t +### `struct joystick_t` {#api-joystick-t} Contains the state of the joystick. -#### Members :id=api-joystick-t-members +#### Members {#api-joystick-t-members} - `uint8_t buttons[]` A bit-packed array containing the joystick button states. The size is calculated as `(JOYSTICK_BUTTON_COUNT - 1) / 8 + 1`. @@ -150,11 +152,11 @@ Contains the state of the joystick. --- -### `struct joystick_config_t` :id=api-joystick-config-t +### `struct joystick_config_t` {#api-joystick-config-t} Describes a single axis. -#### Members :id=api-joystick-config-t-members +#### Members {#api-joystick-config-t-members} - `pin_t input_pin` The pin to read the analog value from, or `JS_VIRTUAL_AXIS`. @@ -167,52 +169,52 @@ Describes a single axis. --- -### `void joystick_flush(void)` :id=api-joystick-flush +### `void joystick_flush(void)` {#api-joystick-flush} Send the joystick report to the host, if it has been marked as dirty. --- -### `void register_joystick_button(uint8_t button)` :id=api-register-joystick-button +### `void register_joystick_button(uint8_t button)` {#api-register-joystick-button} Set the state of a button, and flush the report. -#### Arguments :id=api-register-joystick-button-arguments +#### Arguments {#api-register-joystick-button-arguments} - `uint8_t button` The index of the button to press, from 0 to 31. --- -### `void unregister_joystick_button(uint8_t button)` :id=api-unregister-joystick-button +### `void unregister_joystick_button(uint8_t button)` {#api-unregister-joystick-button} Reset the state of a button, and flush the report. -#### Arguments :id=api-unregister-joystick-button-arguments +#### Arguments {#api-unregister-joystick-button-arguments} - `uint8_t button` The index of the button to release, from 0 to 31. --- -### `int16_t joystick_read_axis(uint8_t axis)` :id=api-joystick-read-axis +### `int16_t joystick_read_axis(uint8_t axis)` {#api-joystick-read-axis} Sample and process the analog value of the given axis. -#### Arguments :id=api-joystick-read-axis-arguments +#### Arguments {#api-joystick-read-axis-arguments} - `uint8_t axis` The axis to read. -#### Return Value :id=api-joystick-read-axis-return +#### Return Value {#api-joystick-read-axis-return} A signed 16-bit integer, where 0 is the resting or mid point. -### `void joystick_set_axis(uint8_t axis, int16_t value)` :id=api-joystick-set-axis +### `void joystick_set_axis(uint8_t axis, int16_t value)` {#api-joystick-set-axis} Set the value of the given axis. -#### Arguments :id=api-joystick-set-axis-arguments +#### Arguments {#api-joystick-set-axis-arguments} - `uint8_t axis` The axis to set the value of. diff --git a/docs/feature_key_lock.md b/docs/feature_key_lock.md index 1acee524da..1a0a2dfb60 100644 --- a/docs/feature_key_lock.md +++ b/docs/feature_key_lock.md @@ -16,8 +16,8 @@ First, enable Key Lock by setting `KEY_LOCK_ENABLE = yes` in your `rules.mk`. Th ## Caveats -Key Lock is only able to hold standard action keys and [One Shot modifier](one_shot_keys.md) keys (for example, if you have your Shift defined as `OSM(MOD_LSFT)`). -This does not include any of the QMK special functions (except One Shot modifiers), or shifted versions of keys such as `KC_LPRN`. If it's in the [Basic Keycodes](keycodes_basic.md) list, it can be held. +Key Lock is only able to hold standard action keys and [One Shot modifier](one_shot_keys) keys (for example, if you have your Shift defined as `OSM(MOD_LSFT)`). +This does not include any of the QMK special functions (except One Shot modifiers), or shifted versions of keys such as `KC_LPRN`. If it's in the [Basic Keycodes](keycodes_basic) list, it can be held. Switching layers will not cancel the Key Lock. The Key Lock can be cancelled by calling the `cancel_key_lock()` function. diff --git a/docs/feature_key_overrides.md b/docs/feature_key_overrides.md index 59eced95c3..b9fbd35966 100644 --- a/docs/feature_key_overrides.md +++ b/docs/feature_key_overrides.md @@ -1,4 +1,4 @@ -# Key Overrides :id=key-overrides +# Key Overrides {#key-overrides} Key overrides allow you to override modifier-key combinations to send a different modifier-key combination or perform completely custom actions. Don't want `shift` + `1` to type `!` on your computer? Use a key override to make your keyboard type something different when you press `shift` + `1`. The general behavior is like this: If `modifiers w` + `key x` are pressed, replace these keys with `modifiers y` + `key z` in the keyboard report. @@ -10,13 +10,13 @@ You can use key overrides in a similar way to momentary layer/fn keys to activat - Create custom shortcuts or change existing ones: E.g. Send `ctrl`+`shift`+`z` when `ctrl`+`y` is pressed. - Run custom code when `ctrl` + `alt` + `esc` is pressed. -## Setup :id=setup +## Setup {#setup} To enable this feature, you need to add `KEY_OVERRIDE_ENABLE = yes` to your `rules.mk`. Then, in your `keymap.c` file, you'll need to define the array `key_overrides`, which defines all key overrides to be used. Each override is a value of type `key_override_t`. The array `key_overrides` is `NULL`-terminated and contains pointers to `key_override_t` values (`const key_override_t **`). -## Creating Key Overrides :id=creating-key-overrides +## Creating Key Overrides {#creating-key-overrides} The `key_override_t` struct has many options that allow you to precisely tune your overrides. The full reference is shown below. Instead of manually creating a `key_override_t` value, it is recommended to use these dedicated initializers: @@ -34,7 +34,7 @@ Additionally takes a bitmask `options` that specifies additional options. See `k For more customization possibilities, you may directly create a `key_override_t`, which allows you to customize even more behavior. Read further below for details and examples. -## Simple Example :id=simple-example +## Simple Example {#simple-example} This shows how the mentioned example of sending `delete` when `shift` + `backspace` are pressed is realized: @@ -48,9 +48,9 @@ const key_override_t **key_overrides = (const key_override_t *[]){ }; ``` -## Intermediate Difficulty Examples :id=intermediate-difficulty-examples +## Intermediate Difficulty Examples {#intermediate-difficulty-examples} -### Media Controls & Screen Brightness :id=media-controls-amp-screen-brightness +### Media Controls & Screen Brightness {#media-controls-amp-screen-brightness} In this example a single key is configured to control media, volume and screen brightness by using key overrides. @@ -102,8 +102,8 @@ const key_override_t **key_overrides = (const key_override_t *[]){ }; ``` -### Flexible macOS-friendly Grave Escape :id=flexible-macos-friendly-grave-escape -The [Grave Escape feature](feature_grave_esc.md) is limited in its configurability and has [bugs when used on macOS](feature_grave_esc.md#caveats). Key overrides can be used to achieve a similar functionality as Grave Escape, but with more customization and without bugs on macOS. +### Flexible macOS-friendly Grave Escape {#flexible-macos-friendly-grave-escape} +The [Grave Escape feature](feature_grave_esc) is limited in its configurability and has [bugs when used on macOS](feature_grave_esc#caveats). Key overrides can be used to achieve a similar functionality as Grave Escape, but with more customization and without bugs on macOS. ```c // Shift + esc = ~ @@ -121,8 +121,8 @@ const key_override_t **key_overrides = (const key_override_t *[]){ In addition to not encountering unexpected bugs on macOS, you can also change the behavior as you wish. Instead setting `GUI` + `ESC` = `` ` `` you may change it to an arbitrary other modifier, for example `Ctrl` + `ESC` = `` ` ``. -## Advanced Examples :id=advanced-examples -### Modifiers as Layer Keys :id=modifiers-as-layer-keys +## Advanced Examples {#advanced-examples} +### Modifiers as Layer Keys {#modifiers-as-layer-keys} Do you really need a dedicated key to toggle your fn layer? With key overrides, perhaps not. This example shows how you can configure to use `rGUI` + `rAlt` (right GUI and right alt) to access a momentary layer like an fn layer. With this you completely eliminate the need to use a dedicated layer key. Of course the choice of modifier keys can be changed as needed, `rGUI` + `rAlt` is just an example here. @@ -150,7 +150,7 @@ const key_override_t fn_override = {.trigger_mods = MOD_BIT(KC_RGUI) | .enabled = NULL}; ``` -## Keycodes :id=keycodes +## Keycodes {#keycodes} |Keycode |Aliases |Description | |------------------------|---------|----------------------| @@ -158,7 +158,7 @@ const key_override_t fn_override = {.trigger_mods = MOD_BIT(KC_RGUI) | |`QK_KEY_OVERRIDE_ON` |`KO_ON` |Turn on key overrides | |`QK_KEY_OVERRIDE_OFF` |`KO_OFF` |Turn off key overrides| -## Reference for `key_override_t` :id=reference-for-key_override_t +## Reference for `key_override_t` {#reference-for-key_override_t} Advanced users may need more customization than what is offered by the simple `ko_make` initializers. For this, directly create a `key_override_t` value and set all members. Below is a reference for all members of `key_override_t`. @@ -175,7 +175,7 @@ Advanced users may need more customization than what is offered by the simple `k | `void *context` | A context that will be passed to the custom action function. | | `bool *enabled` | If this points to false this override will not be used. Set to NULL to always have this override enabled. | -## Reference for `ko_option_t` :id=reference-for-ko_option_t +## Reference for `ko_option_t` {#reference-for-ko_option_t} Bitfield with various options controlling the behavior of a key override. @@ -189,11 +189,11 @@ Bitfield with various options controlling the behavior of a key override. | `ko_option_no_reregister_trigger` | If set, the trigger key will never be registered again after the override is deactivated. | | `ko_options_default` | The default options used by the `ko_make_xxx` functions | -## For Advanced Users: Inner Workings :id=for-advanced-users-inner-workings +## For Advanced Users: Inner Workings {#for-advanced-users-inner-workings} This section explains how a key override works in detail, explaining where each member of `key_override_t` comes into play. Understanding this is essential to be able to take full advantage of all the options offered by key overrides. -#### Activation :id=activation +#### Activation {#activation} When the necessary keys are pressed (`trigger_mods` + `trigger`), the override is 'activated' and the replacement key is registered in the keyboard report (`replacement`), while the `trigger` key is removed from the keyboard report. The trigger modifiers may also be removed from the keyboard report upon activation of an override (`suppressed_mods`). The override will not activate if any of the `negative_modifiers` are pressed. @@ -207,11 +207,11 @@ Use the `option` member to customize which of these events are allowed to activa In any case, a key override can only activate if the `trigger` key is the _last_ non-modifier key that was pressed down. This emulates the behavior of how standard OSes (macOS, Windows, Linux) handle normal key input (to understand: Hold down `a`, then also hold down `b`, then hold down `shift`; `B` will be typed but not `A`). -#### Deactivation :id=deactivation +#### Deactivation {#deactivation} An override is 'deactivated' when one of the trigger keys (`trigger_mods`, `trigger`) is lifted, another non-modifier key is pressed down, or one of the `negative_modifiers` is pressed down. When an override deactivates, the `replacement` key is removed from the keyboard report, while the `suppressed_mods` that are still held down are re-added to the keyboard report. By default, the `trigger` key is re-added to the keyboard report if it is still held down and no other non-modifier key has been pressed since. This again emulates the behavior of how standard OSes handle normal key input (To understand: hold down `a`, then also hold down `b`, then also `shift`, then release `b`; `A` will not be typed even though you are holding the `a` and `shift` keys). Use the `option` field `ko_option_no_reregister_trigger` to prevent re-registering the trigger key in all cases. -#### Key Repeat Delay :id=key-repeat-delay +#### Key Repeat Delay {#key-repeat-delay} A third way in which standard OS-handling of modifier-key input is emulated in key overrides is with a ['key repeat delay'](https://www.dummies.com/computers/pcs/set-your-keyboards-repeat-delay-and-repeat-rate/). To explain what this is, let's look at how normal keyboard input is handled by mainstream OSes again: If you hold down `a`, followed by `shift`, you will see the letter `a` is first typed, then for a short moment nothing is typed and then repeating `A`s are typed. Take note that, although shift is pressed down just after `a` is pressed, it takes a moment until `A` is typed. This is caused by the aforementioned key repeat delay, and it is a feature that prevents unwanted repeated characters from being typed. @@ -222,11 +222,11 @@ This applies equally to releasing a modifier: When you hold `shift`, then press The duration of the key repeat delay is controlled with the `KEY_OVERRIDE_REPEAT_DELAY` macro. Define this value in your `config.h` file to change it. It is 500ms by default. -## Difference to Combos :id=difference-to-combos +## Difference to Combos {#difference-to-combos} -Note that key overrides are very different from [combos](https://docs.qmk.fm/#/feature_combo). Combos require that you press down several keys almost _at the same time_ and can work with any combination of non-modifier keys. Key overrides work like keyboard shortcuts (e.g. `ctrl` + `z`): They take combinations of _multiple_ modifiers and _one_ non-modifier key to then perform some custom action. Key overrides are implemented with much care to behave just like normal keyboard shortcuts would in regards to the order of pressed keys, timing, and interaction with other pressed keys. There are a number of optional settings that can be used to really fine-tune the behavior of each key override as well. Using key overrides also does not delay key input for regular key presses, which inherently happens in combos and may be undesirable. +Note that key overrides are very different from [combos](feature_combo). Combos require that you press down several keys almost _at the same time_ and can work with any combination of non-modifier keys. Key overrides work like keyboard shortcuts (e.g. `ctrl` + `z`): They take combinations of _multiple_ modifiers and _one_ non-modifier key to then perform some custom action. Key overrides are implemented with much care to behave just like normal keyboard shortcuts would in regards to the order of pressed keys, timing, and interaction with other pressed keys. There are a number of optional settings that can be used to really fine-tune the behavior of each key override as well. Using key overrides also does not delay key input for regular key presses, which inherently happens in combos and may be undesirable. -## Solution to the problem of flashing modifiers :id=neutralize-flashing-modifiers +## Solution to the problem of flashing modifiers {#neutralize-flashing-modifiers} If the programs you use bind an action to taps of modifier keys (e.g. tapping left GUI to bring up the applications menu or tapping left Alt to focus the menu bar), you may find that using key overrides with suppressed mods falsely triggers those actions. To counteract this, you can define a `DUMMY_MOD_NEUTRALIZER_KEYCODE` in `config.h` that will get sent in between the register and unregister events of a suppressed modifier. That way, the programs on your computer will no longer interpret the mod suppression induced by key overrides as a lone tap of a modifier key and will thus not falsely trigger the undesired action. @@ -251,4 +251,6 @@ Examples: #define MODS_TO_NEUTRALIZE { MOD_BIT(KC_LEFT_ALT), MOD_BIT(KC_LEFT_GUI), MOD_BIT(KC_RIGHT_GUI), MOD_BIT(KC_LEFT_CTRL)|MOD_BIT(KC_LEFT_SHIFT) } ``` -!> Do not use `MOD_xxx` constants like `MOD_LSFT` or `MOD_RALT`, since they're 5-bit packed bit-arrays while `MODS_TO_NEUTRALIZE` expects a list of 8-bit packed bit-arrays. Use `MOD_BIT()` or `MOD_MASK_xxx` instead. +::: warning +Do not use `MOD_xxx` constants like `MOD_LSFT` or `MOD_RALT`, since they're 5-bit packed bit-arrays while `MODS_TO_NEUTRALIZE` expects a list of 8-bit packed bit-arrays. Use `MOD_BIT()` or `MOD_MASK_xxx` instead. +::: diff --git a/docs/feature_layers.md b/docs/feature_layers.md index e57642071f..77b6ef9531 100644 --- a/docs/feature_layers.md +++ b/docs/feature_layers.md @@ -1,25 +1,25 @@ -# Layers :id=layers +# Layers {#layers} One of the most powerful and well used features of QMK Firmware is the ability to use layers. For most people, this amounts to a function key that allows for different keys, much like what you would see on a laptop or tablet keyboard. -For a detailed explanation of how the layer stack works, checkout [Keymap Overview](keymap.md#keymap-and-layers). +For a detailed explanation of how the layer stack works, checkout [Keymap Overview](keymap#keymap-and-layers). -## Switching and Toggling Layers :id=switching-and-toggling-layers +## Switching and Toggling Layers {#switching-and-toggling-layers} These functions allow you to activate layers in various ways. Note that layers are not generally independent layouts -- multiple layers can be activated at once, and it's typical for layers to use `KC_TRNS` to allow keypresses to pass through to lower layers. When using momentary layer switching with MO(), LM(), TT(), or LT(), make sure to leave the key on the above layers transparent or it may not work as intended. -* `DF(layer)` - switches the default layer. The default layer is the always-active base layer that other layers stack on top of. See below for more about the default layer. This might be used to switch from QWERTY to Dvorak layout. (Note that this is a temporary switch that only persists until the keyboard loses power. To modify the default layer in a persistent way requires deeper customization, such as calling the `set_single_persistent_default_layer` function inside of [process_record_user](custom_quantum_functions.md#programming-the-behavior-of-any-keycode).) +* `DF(layer)` - switches the default layer. The default layer is the always-active base layer that other layers stack on top of. See below for more about the default layer. This might be used to switch from QWERTY to Dvorak layout. (Note that this is a temporary switch that only persists until the keyboard loses power. To modify the default layer in a persistent way requires deeper customization, such as calling the `set_single_persistent_default_layer` function inside of [process_record_user](custom_quantum_functions#programming-the-behavior-of-any-keycode).) * `MO(layer)` - momentarily activates *layer*. As soon as you let go of the key, the layer is deactivated. * `LM(layer, mod)` - Momentarily activates *layer* (like `MO`), but with modifier(s) *mod* active. Only supports layers 0-15. The modifiers this keycode accept are prefixed with `MOD_`, not `KC_`. These modifiers can be combined using bitwise OR, e.g. `LM(_RAISE, MOD_LCTL | MOD_LALT)`. * `LT(layer, kc)` - momentarily activates *layer* when held, and sends *kc* when tapped. Only supports layers 0-15. -* `OSL(layer)` - momentarily activates *layer* until the next key is pressed. See [One Shot Keys](one_shot_keys.md) for details and additional functionality. +* `OSL(layer)` - momentarily activates *layer* until the next key is pressed. See [One Shot Keys](one_shot_keys) for details and additional functionality. * `TG(layer)` - toggles *layer*, activating it if it's inactive and vice versa * `TO(layer)` - activates *layer* and de-activates all other layers (except your default layer). This function is special, because instead of just adding/removing one layer to your active layer stack, it will completely replace your current active layers, uniquely allowing you to replace higher layers with a lower one. This is activated on keydown (as soon as the key is pressed). * `TT(layer)` - Layer Tap-Toggle. If you hold the key down, *layer* is activated, and then is de-activated when you let go (like `MO`). If you repeatedly tap it, the layer will be toggled on or off (like `TG`). It needs 5 taps by default, but you can change this by defining `TAPPING_TOGGLE` -- for example, `#define TAPPING_TOGGLE 2` to toggle on just two taps. -### Caveats :id=caveats +### Caveats {#caveats} -Currently, the `layer` argument of `LT()` is limited to layers 0-15, and the `kc` argument to the [Basic Keycode set](keycodes_basic.md), meaning you can't use keycodes like `LCTL()`, `KC_TILD`, or anything greater than `0xFF`. This is because QMK uses 16-bit keycodes, of which 4 bits are used for the function identifier and 4 bits for the layer, leaving only 8 bits for the keycode. +Currently, the `layer` argument of `LT()` is limited to layers 0-15, and the `kc` argument to the [Basic Keycode set](keycodes_basic), meaning you can't use keycodes like `LCTL()`, `KC_TILD`, or anything greater than `0xFF`. This is because QMK uses 16-bit keycodes, of which 4 bits are used for the function identifier and 4 bits for the layer, leaving only 8 bits for the keycode. For a similar reason, the `layer` argument of `LM()` is also limited to layers 0-15 and the `mod` argument must fit within 5 bits. As a consequence, although left and right modifiers are supported by `LM()`, it is impossible to mix and match left and right modifiers. Specifying at least one right-hand modifier in a combination such as `MOD_RALT|MOD_LSFT` will convert *all* the listed modifiers to their right-hand counterpart. So, using the aforementionned mod-mask will actually send Right Alt+Right Shift. Make sure to use the `MOD_xxx` constants over alternative ways of specifying modifiers when defining your layer-mod key. @@ -27,13 +27,13 @@ For a similar reason, the `layer` argument of `LM()` is also limited to layers 0 |:---------------:|:----------------------:|:------------------------:|:----------------:| | ❌ | ❌ | ❌ | ✅ | -Expanding this would be complicated, at best. Moving to a 32-bit keycode would solve a lot of this, but would double the amount of space that the keymap matrix uses. And it could potentially cause issues, too. If you need to apply modifiers to your tapped keycode, [Tap Dance](feature_tap_dance.md#example-5-using-tap-dance-for-advanced-mod-tap-and-layer-tap-keys) can be used to accomplish this. +Expanding this would be complicated, at best. Moving to a 32-bit keycode would solve a lot of this, but would double the amount of space that the keymap matrix uses. And it could potentially cause issues, too. If you need to apply modifiers to your tapped keycode, [Tap Dance](feature_tap_dance#example-5-using-tap-dance-for-advanced-mod-tap-and-layer-tap-keys) can be used to accomplish this. -## Working with Layers :id=working-with-layers +## Working with Layers {#working-with-layers} Care must be taken when switching layers, it's possible to lock yourself into a layer with no way to deactivate that layer (without unplugging your keyboard.) We've created some guidelines to help users avoid the most common problems. -### Beginners :id=beginners +### Beginners {#beginners} If you are just getting started with QMK you will want to keep everything simple. Follow these guidelines when setting up your layers: @@ -41,11 +41,11 @@ If you are just getting started with QMK you will want to keep everything simple * Arrange your layers in a "tree" layout, with layer 0 as the root. Do not try to enter the same layer from more than one other layer. * In a layer's keymap, only reference higher-numbered layers. Because layers are processed from the highest-numbered (topmost) active layer down, modifying the state of lower layers can be tricky and error-prone. -### Intermediate Users :id=intermediate-users +### Intermediate Users {#intermediate-users} Sometimes you need more than one base layer. For example, if you want to switch between QWERTY and Dvorak, switch between layouts for different countries, or switch your layout for different videogames. Your base layers should always be the lowest numbered layers. When you have multiple base layers you should always treat them as mutually exclusive. When one base layer is on the others are off. -### Advanced Users :id=advanced-users +### Advanced Users {#advanced-users} Once you have a good feel for how layers work and what you can do, you can get more creative. The rules listed in the beginner section will help you be successful by avoiding some of the tricker details but they can be constraining, especially for ultra-compact keyboard users. Understanding how layers work will allow you to use them in more advanced ways. @@ -53,7 +53,7 @@ Layers stack on top of each other in numerical order. When determining what a ke Sometimes, you might want to switch between layers in a macro or as part of a tap dance routine. `layer_on` activates a layer, and `layer_off` deactivates it. More layer-related functions can be found in [action_layer.h](https://github.com/qmk/qmk_firmware/blob/master/quantum/action_layer.h). -## Functions :id=functions +## Functions {#functions} There are a number of functions (and variables) related to how you can use or manipulate the layers. @@ -87,7 +87,9 @@ In addition to the functions that you can call, there are a number of callback f | `default_layer_state_set_kb(layer_state_t state)` | Callback for default layer functions, for keyboard. Called on keyboard initialization. | | `default_layer_state_set_user(layer_state_t state)` | Callback for default layer functions, for users. Called on keyboard initialization. | -?> For additional details on how you can use these callbacks, check out the [Layer Change Code](custom_quantum_functions.md#layer-change-code) document. +::: tip +For additional details on how you can use these callbacks, check out the [Layer Change Code](custom_quantum_functions#layer-change-code) document. +::: It is also possible to check the state of a particular layer using the following functions and macros. @@ -96,13 +98,13 @@ It is also possible to check the state of a particular layer using the following | `layer_state_is(layer)` | Checks if the specified `layer` is enabled globally. | `IS_LAYER_ON(layer)`, `IS_LAYER_OFF(layer)` | | `layer_state_cmp(state, layer)` | Checks `state` to see if the specified `layer` is enabled. Intended for use in layer callbacks. | `IS_LAYER_ON_STATE(state, layer)`, `IS_LAYER_OFF_STATE(state, layer)` | -## Layer Change Code :id=layer-change-code +## Layer Change Code {#layer-change-code} This runs code every time that the layers get changed. This can be useful for layer indication, or custom layer handling. ### Example `layer_state_set_*` Implementation -This example shows how to set the [RGB Underglow](feature_rgblight.md) lights based on the layer, using the Planck as an example. +This example shows how to set the [RGB Underglow](feature_rgblight) lights based on the layer, using the Planck as an example. ```c layer_state_t layer_state_set_user(layer_state_t state) { @@ -185,4 +187,4 @@ Outside of `layer_state_set_*` functions, you can use the `IS_LAYER_ON(layer)` a * Keymap: `layer_state_t layer_state_set_user(layer_state_t state)` -The `state` is the bitmask of the active layers, as explained in the [Keymap Overview](keymap.md#keymap-layer-status) +The `state` is the bitmask of the active layers, as explained in the [Keymap Overview](keymap#keymap-layer-status) diff --git a/docs/feature_leader_key.md b/docs/feature_leader_key.md index 72a6818dd1..641c2d7ae5 100644 --- a/docs/feature_leader_key.md +++ b/docs/feature_leader_key.md @@ -1,8 +1,8 @@ -# The Leader Key: A New Kind of Modifier :id=the-leader-key +# The Leader Key: A New Kind of Modifier {#the-leader-key} -If you're a Vim user, you probably know what a Leader key is. In contrast to [Combos](feature_combo.md), the Leader key allows you to hit a *sequence* of up to five keys instead, which triggers some custom functionality once complete. +If you're a Vim user, you probably know what a Leader key is. In contrast to [Combos](feature_combo), the Leader key allows you to hit a *sequence* of up to five keys instead, which triggers some custom functionality once complete. -## Usage :id=usage +## Usage {#usage} Add the following to your `rules.mk`: @@ -12,7 +12,7 @@ LEADER_ENABLE = yes Then add the `QK_LEAD` keycode to your keymap. -## Callbacks :id=callbacks +## Callbacks {#callbacks} These callbacks are invoked when the leader sequence begins and ends. In the latter you can implement your custom functionality based on the contents of the sequence buffer. @@ -38,9 +38,9 @@ void leader_end_user(void) { } ``` -## Basic Configuration :id=basic-configuration +## Basic Configuration {#basic-configuration} -### Timeout :id=timeout +### Timeout {#timeout} This is the amount of time you have to complete a sequence once the leader key has been pressed. The default value is 300 milliseconds, but you can change this by adding the following to your `config.h`: @@ -48,7 +48,7 @@ This is the amount of time you have to complete a sequence once the leader key h #define LEADER_TIMEOUT 350 ``` -### Per-Key Timeout :id=per-key-timeout +### Per-Key Timeout {#per-key-timeout} Rather than relying on an incredibly high timeout for long leader key strings or those of us without 200 wpm typing skills, you can enable per-key timing to ensure that each key pressed provides you with more time to finish the sequence. This is incredibly helpful with leader key emulation of tap dance (such as multiple taps of the same key like C, C, C). @@ -72,7 +72,7 @@ if (leader_sequence_three_keys(KC_C, KC_C, KC_C)) { } ``` -### Disabling Initial Timeout :id=disabling-initial-timeout +### Disabling Initial Timeout {#disabling-initial-timeout} Sometimes your leader key may be too far away from the rest of the keys in the sequence. Imagine that your leader key is one of your outer top right keys - you may need to reposition your hand just to reach your leader key. This can make typing the entire sequence on time hard difficult if you are able to type most of the sequence fast. For example, if your sequence is `Leader + asd`, typing `asd` fast is very easy once you have your hands in your home row, but starting the sequence in time after moving your hand out of the home row to reach the leader key and back is not. @@ -84,9 +84,9 @@ To remove the stress this situation produces to your hands, you can disable the Now, after you hit the leader key, you will have an infinite amount of time to start the rest of the sequence, allowing you to properly position your hands to type the rest of the sequence comfortably. This way you can configure a very short `LEADER_TIMEOUT`, but still have plenty of time to position your hands. -### Strict Key Processing :id=strict-key-processing +### Strict Key Processing {#strict-key-processing} -By default, only the "tap keycode" portions of [Mod-Taps](mod_tap.md) and [Layer Taps](feature_layers.md#switching-and-toggling-layers) are added to the sequence buffer. This means if you press eg. `LT(3, KC_A)` as part of a sequence, `KC_A` will be added to the buffer, rather than the entire `LT(3, KC_A)` keycode. +By default, only the "tap keycode" portions of [Mod-Taps](mod_tap) and [Layer Taps](feature_layers#switching-and-toggling-layers) are added to the sequence buffer. This means if you press eg. `LT(3, KC_A)` as part of a sequence, `KC_A` will be added to the buffer, rather than the entire `LT(3, KC_A)` keycode. This gives a more expected behaviour for most users, however you may want to change this. @@ -96,7 +96,7 @@ To enable this, add the following to your `config.h`: #define LEADER_KEY_STRICT_KEY_PROCESSING ``` -## Example :id=example +## Example {#example} This example will play the Mario "One Up" sound when you hit `QK_LEAD` to start the leader sequence. When the sequence ends, it will play "All Star" if it completes successfully or "Rick Roll" you if it fails (in other words, no sequence matched). @@ -134,62 +134,62 @@ void leader_end_user(void) { } ``` -## Keycodes :id=keycodes +## Keycodes {#keycodes} |Key |Aliases |Description | |-----------------------|---------|-------------------------| |`QK_LEADER` |`QK_LEAD`|Begin the leader sequence| -## API :id=api +## API {#api} -### `void leader_start_user(void)` :id=api-leader-start-user +### `void leader_start_user(void)` {#api-leader-start-user} User callback, invoked when the leader sequence begins. --- -### `void leader_end_user(void)` :id=api-leader-end-user +### `void leader_end_user(void)` {#api-leader-end-user} User callback, invoked when the leader sequence ends. --- -### `void leader_start(void)` :id=api-leader-start +### `void leader_start(void)` {#api-leader-start} Begin the leader sequence, resetting the buffer and timer. --- -### `void leader_end(void)` :id=api-leader-end +### `void leader_end(void)` {#api-leader-end} End the leader sequence. --- -### `bool leader_sequence_active(void)` :id=api-leader-sequence-active +### `bool leader_sequence_active(void)` {#api-leader-sequence-active} Whether the leader sequence is active. --- -### `bool leader_sequence_add(uint16_t keycode)` :id=api-leader-sequence-add +### `bool leader_sequence_add(uint16_t keycode)` {#api-leader-sequence-add} Add the given keycode to the sequence buffer. If `LEADER_NO_TIMEOUT` is defined, the timer is reset if the buffer is empty. -#### Arguments :id=api-leader-sequence-add-arguments +#### Arguments {#api-leader-sequence-add-arguments} - `uint16_t keycode` The keycode to add. -#### Return Value :id=api-leader-sequence-add-return +#### Return Value {#api-leader-sequence-add-return} `true` if the keycode was added, `false` if the buffer is full. --- -### `bool leader_sequence_timed_out(void)` :id=api-leader-sequence-timed-out +### `bool leader_sequence_timed_out(void)` {#api-leader-sequence-timed-out} Whether the leader sequence has reached the timeout. @@ -197,49 +197,49 @@ If `LEADER_NO_TIMEOUT` is defined, the buffer must also contain at least one key --- -### `bool leader_reset_timer(void)` :id=api-leader-reset-timer +### `bool leader_reset_timer(void)` {#api-leader-reset-timer} Reset the leader sequence timer. --- -### `bool leader_sequence_one_key(uint16_t kc)` :id=api-leader-sequence-one-key +### `bool leader_sequence_one_key(uint16_t kc)` {#api-leader-sequence-one-key} Check the sequence buffer for the given keycode. -#### Arguments :id=api-leader-sequence-one-key-arguments +#### Arguments {#api-leader-sequence-one-key-arguments} - `uint16_t kc` The keycode to check. -#### Return Value :id=api-leader-sequence-one-key-return +#### Return Value {#api-leader-sequence-one-key-return} `true` if the sequence buffer matches. --- -### `bool leader_sequence_two_keys(uint16_t kc1, uint16_t kc2)` :id=api-leader-sequence-two-keys +### `bool leader_sequence_two_keys(uint16_t kc1, uint16_t kc2)` {#api-leader-sequence-two-keys} Check the sequence buffer for the given keycodes. -#### Arguments :id=api-leader-sequence-two-keys-arguments +#### Arguments {#api-leader-sequence-two-keys-arguments} - `uint16_t kc1` The first keycode to check. - `uint16_t kc2` The second keycode to check. -#### Return Value :id=api-leader-sequence-two-keys-return +#### Return Value {#api-leader-sequence-two-keys-return} `true` if the sequence buffer matches. --- -### `bool leader_sequence_three_keys(uint16_t kc1, uint16_t kc2, uint16_t kc3)` :id=api-leader-sequence-three-keys +### `bool leader_sequence_three_keys(uint16_t kc1, uint16_t kc2, uint16_t kc3)` {#api-leader-sequence-three-keys} Check the sequence buffer for the given keycodes. -#### Arguments :id=api-leader-sequence-three-keys-arguments +#### Arguments {#api-leader-sequence-three-keys-arguments} - `uint16_t kc1` The first keycode to check. @@ -248,17 +248,17 @@ Check the sequence buffer for the given keycodes. - `uint16_t kc3` The third keycode to check. -#### Return Value :id=api-leader-sequence-three-keys-return +#### Return Value {#api-leader-sequence-three-keys-return} `true` if the sequence buffer matches. --- -### `bool leader_sequence_four_keys(uint16_t kc1, uint16_t kc2, uint16_t kc3, uint16_t kc4)` :id=api-leader-sequence-four-keys +### `bool leader_sequence_four_keys(uint16_t kc1, uint16_t kc2, uint16_t kc3, uint16_t kc4)` {#api-leader-sequence-four-keys} Check the sequence buffer for the given keycodes. -#### Arguments :id=api-leader-sequence-four-keys-arguments +#### Arguments {#api-leader-sequence-four-keys-arguments} - `uint16_t kc1` The first keycode to check. @@ -269,17 +269,17 @@ Check the sequence buffer for the given keycodes. - `uint16_t kc4` The fourth keycode to check. -#### Return Value :id=api-leader-sequence-four-keys-return +#### Return Value {#api-leader-sequence-four-keys-return} `true` if the sequence buffer matches. --- -### `bool leader_sequence_five_keys(uint16_t kc1, uint16_t kc2, uint16_t kc3, uint16_t kc4, uint16_t kc5)` :id=api-leader-sequence-five-keys +### `bool leader_sequence_five_keys(uint16_t kc1, uint16_t kc2, uint16_t kc3, uint16_t kc4, uint16_t kc5)` {#api-leader-sequence-five-keys} Check the sequence buffer for the given keycodes. -#### Arguments :id=api-leader-sequence-five-keys-arguments +#### Arguments {#api-leader-sequence-five-keys-arguments} - `uint16_t kc1` The first keycode to check. @@ -292,6 +292,6 @@ Check the sequence buffer for the given keycodes. - `uint16_t kc5` The fifth keycode to check. -#### Return Value :id=api-leader-sequence-five-keys-return +#### Return Value {#api-leader-sequence-five-keys-return} `true` if the sequence buffer matches. diff --git a/docs/feature_led_indicators.md b/docs/feature_led_indicators.md index b35a174490..e28c222e76 100644 --- a/docs/feature_led_indicators.md +++ b/docs/feature_led_indicators.md @@ -1,6 +1,8 @@ # LED Indicators -?> LED indicators on split keyboards will require state information synced to the slave half (e.g. `#define SPLIT_LED_STATE_ENABLE`). See [data sync options](feature_split_keyboard.md#data-sync-options) for more details. +::: tip +LED indicators on split keyboards will require state information synced to the slave half (e.g. `#define SPLIT_LED_STATE_ENABLE`). See [data sync options](feature_split_keyboard#data-sync-options) for more details. +::: QMK provides methods to read 5 of the LEDs defined in the HID spec: @@ -15,7 +17,9 @@ There are three ways to get the lock LED state: * Implement `led_update_*` function * Call `led_t host_keyboard_led_state()` -!> The `host_keyboard_led_state()` may reflect an updated state before `led_update_user()` is called. +::: warning +The `host_keyboard_led_state()` may reflect an updated state before `led_update_user()` is called. +::: Two deprecated functions that provide the LED state as `uint8_t`: @@ -46,7 +50,9 @@ When the configuration options do not provide enough flexibility, the following Both receives LED state as a struct parameter. Returning `true` in `led_update_user()` will allow the keyboard level code in `led_update_kb()` to run as well. Returning `false` will override the keyboard level code, depending on how the keyboard level function is set up. -?> This boolean return type of `led_update_user` allows for overriding keyboard LED controls, and is thus recommended over the void `led_set_user` function. +::: tip +This boolean return type of `led_update_user` allows for overriding keyboard LED controls, and is thus recommended over the void `led_set_user` function. +::: ### Example of keyboard LED update implementation diff --git a/docs/feature_led_matrix.md b/docs/feature_led_matrix.md index 83357ab14e..78afb36d2c 100644 --- a/docs/feature_led_matrix.md +++ b/docs/feature_led_matrix.md @@ -1,12 +1,12 @@ -# LED Matrix Lighting :id=led-matrix-lighting +# LED Matrix Lighting {#led-matrix-lighting} This feature allows you to use LED matrices driven by external drivers. It hooks into the backlight system so you can use the same keycodes as backlighting to control it. -If you want to use RGB LED's you should use the [RGB Matrix Subsystem](feature_rgb_matrix.md) instead. +If you want to use RGB LED's you should use the [RGB Matrix Subsystem](feature_rgb_matrix) instead. -## Driver configuration :id=driver-configuration +## Driver configuration {#driver-configuration} --- -### IS31FL3731 :id=is31fl3731 +### IS31FL3731 {#is31fl3731} There is basic support for addressable LED matrix lighting with the I2C IS31FL3731 LED controller. To enable it, add this to your `rules.mk`: @@ -47,7 +47,9 @@ Here is an example using 2 drivers. #define LED_MATRIX_LED_COUNT (LED_DRIVER_1_LED_TOTAL + LED_DRIVER_2_LED_TOTAL) ``` -!> Note the parentheses, this is so when `LED_MATRIX_LED_COUNT` is used in code and expanded, the values are added together before any additional math is applied to them. As an example, `rand() % (LED_DRIVER_1_LED_TOTAL + LED_DRIVER_2_LED_TOTAL)` will give very different results than `rand() % LED_DRIVER_1_LED_TOTAL + LED_DRIVER_2_LED_TOTAL`. +::: warning +Note the parentheses, this is so when `LED_MATRIX_LED_COUNT` is used in code and expanded, the values are added together before any additional math is applied to them. As an example, `rand() % (LED_DRIVER_1_LED_TOTAL + LED_DRIVER_2_LED_TOTAL)` will give very different results than `rand() % LED_DRIVER_1_LED_TOTAL + LED_DRIVER_2_LED_TOTAL`. +::: For split keyboards using `LED_MATRIX_SPLIT` with an LED driver, you can either have the same driver address or different driver addresses. If using different addresses, use `IS31FL3731_I2C_ADDRESS_1` for one and `IS31FL3731_I2C_ADDRESS_2` for the other one. Then, in `g_is31fl3731_leds`, fill out the correct driver index (0 or 1). If using one address, use `IS31FL3731_I2C_ADDRESS_1` for both, and use index 0 for `g_is31fl3731_leds`. @@ -68,7 +70,7 @@ const is31fl3731_led_t PROGMEM g_is31fl3731_leds[IS31FL3731_LED_COUNT] = { Where `Cx_y` is the location of the LED in the matrix defined by [the datasheet](https://www.issi.com/WW/pdf/31FL3731.pdf) and the header file `drivers/led/issi/is31fl3731-mono.h`. The `driver` is the index of the driver you defined in your `config.h` (`0`, `1`, `2`, or `3` ). --- -### IS31FLCOMMON :id=is31flcommon +### IS31FLCOMMON {#is31flcommon} There is basic support for addressable LED matrix lighting with a selection of I2C ISSI Lumissil LED controllers through a shared common driver. To enable it, add this to your `rules.mk`: @@ -130,7 +132,9 @@ Here is an example using 2 drivers. #define DRIVER_2_LED_TOTAL 42 #define LED_MATRIX_LED_COUNT (DRIVER_1_LED_TOTAL + DRIVER_2_LED_TOTAL) ``` -!> Note the parentheses, this is so when `LED_MATRIX_LED_COUNT` is used in code and expanded, the values are added together before any additional math is applied to them. As an example, `rand() % (DRIVER_1_LED_TOTAL + DRIVER_2_LED_TOTAL)` will give very different results than `rand() % DRIVER_1_LED_TOTAL + DRIVER_2_LED_TOTAL`. +::: warning +Note the parentheses, this is so when `LED_MATRIX_LED_COUNT` is used in code and expanded, the values are added together before any additional math is applied to them. As an example, `rand() % (DRIVER_1_LED_TOTAL + DRIVER_2_LED_TOTAL)` will give very different results than `rand() % DRIVER_1_LED_TOTAL + DRIVER_2_LED_TOTAL`. +::: Currently only 4 drivers are supported, but it would be trivial to support for more. Note that using a combination of different drivers is not supported. All drivers must be of the same model. @@ -170,7 +174,7 @@ Where LED Index is the position of the LED in the `g_is31_leds` array. The `scal --- -## Common Configuration :id=common-configuration +## Common Configuration {#common-configuration} From this point forward the configuration is the same for all the drivers. The `led_config_t` struct provides a key electrical matrix to led index lookup table, what the physical position of each LED is on the board, and what type of key or usage the LED if the LED represents. Here is a brief example: @@ -203,7 +207,7 @@ As mentioned earlier, the center of the keyboard by default is expected to be `{ `// LED Index to Flag` is a bitmask, whether or not a certain LEDs is of a certain type. It is recommended that LEDs are set to only 1 type. -## Flags :id=flags +## Flags {#flags} |Define |Value |Description | |----------------------------|------|-------------------------------------------------| @@ -215,7 +219,7 @@ As mentioned earlier, the center of the keyboard by default is expected to be `{ |`LED_FLAG_KEYLIGHT` |`0x04`|If the LED is for key backlight | |`LED_FLAG_INDICATOR` |`0x08`|If the LED is for keyboard state indication | -## Keycodes :id=keycodes +## Keycodes {#keycodes} |Key |Aliases |Description | |-------------------------------|---------|-----------------------------------| @@ -229,7 +233,7 @@ As mentioned earlier, the center of the keyboard by default is expected to be `{ |`QK_LED_MATRIX_SPEED_UP` |`LM_SPDU`|Increase the animation speed | |`QK_LED_MATRIX_SPEED_DOWN` |`LM_SPDD`|Decrease the animation speed | -## LED Matrix Effects :id=led-matrix-effects +## LED Matrix Effects {#led-matrix-effects} These are the effects that are currently available: @@ -290,9 +294,11 @@ You can enable a single effect by defining `ENABLE_[EFFECT_NAME]` in your `confi |`#define ENABLE_LED_MATRIX_SOLID_SPLASH` |Enables `LED_MATRIX_SOLID_SPLASH` | |`#define ENABLE_LED_MATRIX_SOLID_MULTISPLASH` |Enables `LED_MATRIX_SOLID_MULTISPLASH` | -?> These modes introduce additional logic that can increase firmware size. +::: tip +These modes introduce additional logic that can increase firmware size. +::: -## Custom LED Matrix Effects :id=custom-led-matrix-effects +## Custom LED Matrix Effects {#custom-led-matrix-effects} By setting `LED_MATRIX_CUSTOM_USER` (and/or `LED_MATRIX_CUSTOM_KB`) in `rules.mk`, new effects can be defined directly from userspace, without having to edit any QMK core files. @@ -353,7 +359,7 @@ static bool my_cool_effect2(effect_params_t* params) { For inspiration and examples, check out the built-in effects under `quantum/led_matrix/animations/`. -## Additional `config.h` Options :id=additional-configh-options +## Additional `config.h` Options {#additional-configh-options} ```c #define LED_MATRIX_KEYRELEASES // reactive effects respond to keyreleases (instead of keypresses) @@ -371,17 +377,17 @@ For inspiration and examples, check out the built-in effects under `quantum/led_ // If reactive effects are enabled, you also will want to enable SPLIT_TRANSPORT_MIRROR ``` -## EEPROM storage :id=eeprom-storage +## EEPROM storage {#eeprom-storage} The EEPROM for it is currently shared with the RGB Matrix system (it's generally assumed only one feature would be used at a time). -### Direct Operation :id=direct-operation +### Direct Operation {#direct-operation} |Function |Description | |--------------------------------------------|-------------| |`led_matrix_set_value_all(v)` |Set all of the LEDs to the given value, where `v` is between 0 and 255 (not written to EEPROM) | |`led_matrix_set_value(index, v)` |Set a single LED to the given value, where `v` is between 0 and 255, and `index` is between 0 and `LED_MATRIX_LED_COUNT` (not written to EEPROM) | -### Disable/Enable Effects :id=disable-enable-effects +### Disable/Enable Effects {#disable-enable-effects} |Function |Description | |--------------------------------------------|-------------| |`led_matrix_toggle()` |Toggle effect range LEDs between on and off | @@ -391,7 +397,7 @@ The EEPROM for it is currently shared with the RGB Matrix system (it's generally |`led_matrix_disable()` |Turn effect range LEDs off, based on their previous state | |`led_matrix_disable_noeeprom()` |Turn effect range LEDs off, based on their previous state (not written to EEPROM) | -### Change Effect Mode :id=change-effect-mode +### Change Effect Mode {#change-effect-mode} |Function |Description | |--------------------------------------------|-------------| |`led_matrix_mode(mode)` |Set the mode, if LED animations are enabled | @@ -407,7 +413,7 @@ The EEPROM for it is currently shared with the RGB Matrix system (it's generally |`led_matrix_set_speed(speed)` |Set the speed of the animations to the given value where `speed` is between 0 and 255 | |`led_matrix_set_speed_noeeprom(speed)` |Set the speed of the animations to the given value where `speed` is between 0 and 255 (not written to EEPROM) | -### Change Value :id=change-value +### Change Value {#change-value} |Function |Description | |--------------------------------------------|-------------| |`led_matrix_increase_val()` |Increase the value for effect range LEDs. This wraps around at maximum value | @@ -415,7 +421,7 @@ The EEPROM for it is currently shared with the RGB Matrix system (it's generally |`led_matrix_decrease_val()` |Decrease the value for effect range LEDs. This wraps around at minimum value | |`led_matrix_decrease_val_noeeprom()` |Decrease the value for effect range LEDs. This wraps around at minimum value (not written to EEPROM) | -### Query Current Status :id=query-current-status +### Query Current Status {#query-current-status} |Function |Description | |---------------------------------|---------------------------| |`led_matrix_is_enabled()` |Gets current on/off status | @@ -424,9 +430,9 @@ The EEPROM for it is currently shared with the RGB Matrix system (it's generally |`led_matrix_get_speed()` |Gets current speed | |`led_matrix_get_suspend_state()` |Gets current suspend state | -## Callbacks :id=callbacks +## Callbacks {#callbacks} -### Indicators :id=indicators +### Indicators {#indicators} If you want to set custom indicators, such as an LED for Caps Lock, or layer indication, then you can use the `led_matrix_indicators_kb` function on the keyboard level source file, or `led_matrix_indicators_user` function in the user `keymap.c`. ```c diff --git a/docs/feature_macros.md b/docs/feature_macros.md index f0533f14fe..c3162dba80 100644 --- a/docs/feature_macros.md +++ b/docs/feature_macros.md @@ -2,11 +2,13 @@ Macros allow you to send multiple keystrokes when pressing just one key. QMK has a number of ways to define and use macros. These can do anything you want: type common phrases for you, copypasta, repetitive game movements, or even help you code. -!> **Security Note**: While it is possible to use macros to send passwords, credit card numbers, and other sensitive information it is a supremely bad idea to do so. Anyone who gets a hold of your keyboard will be able to access that information by opening a text editor. +::: warning +**Security Note**: While it is possible to use macros to send passwords, credit card numbers, and other sensitive information it is a supremely bad idea to do so. Anyone who gets a hold of your keyboard will be able to access that information by opening a text editor. +::: ## Using Macros In JSON Keymaps -You can define up to 32 macros in a `keymap.json` file, as used by [Configurator](newbs_building_firmware_configurator.md), and `qmk compile`. You can define these macros in a list under the `macros` keyword, like this: +You can define up to 32 macros in a `keymap.json` file, as used by [Configurator](newbs_building_firmware_configurator), and `qmk compile`. You can define these macros in a list under the `macros` keyword, like this: ```json { @@ -84,7 +86,7 @@ All objects have one required key: `action`. This tells QMK what the object does Only basic keycodes (prefixed by `KC_`) are supported. Do not include the `KC_` prefix when listing keycodes. * `beep` - * Play a bell if the keyboard has [audio enabled](feature_audio.md). + * Play a bell if the keyboard has [audio enabled](feature_audio). * Example: `{"action": "beep"}` * `delay` * Pause macro playback. Duration is specified in milliseconds (ms). @@ -106,7 +108,7 @@ Only basic keycodes (prefixed by `KC_`) are supported. Do not include the `KC_` ### `SEND_STRING()` & `process_record_user` -See also: [Send String](feature_send_string.md) +See also: [Send String](feature_send_string) Sometimes you want a key to type out words or phrases. For the most common situations, we've provided `SEND_STRING()`, which will type out a string (i.e. a sequence of characters) for you. All ASCII characters that are easily translatable to a keycode are supported (e.g. `qmk 123\n\t`). @@ -146,7 +148,7 @@ If yes, we send the string `"QMK is the best thing ever!"` to the computer via t We return `true` to indicate to the caller that the key press we just processed should continue to be processed as normal (as we didn't replace or alter the functionality). Finally, we define the keymap so that the first button activates our macro and the second button is just an escape button. -?>It is recommended to use the SAFE_RANGE macro as per [Customizing Functionality](custom_quantum_functions.md). +?>It is recommended to use the SAFE_RANGE macro as per [Customizing Functionality](custom_quantum_functions). You might want to add more than one macro. You can do that by adding another keycode and adding another case to the switch statement, like so: @@ -195,7 +197,9 @@ const uint16_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] = { }; ``` -?> An enumerated list of custom keycodes (`enum custom_keycodes`) must be declared before `keymaps[]` array, `process_record_user()` and any other function that use the list for the compiler to recognise it. +::: tip +An enumerated list of custom keycodes (`enum custom_keycodes`) must be declared before `keymaps[]` array, `process_record_user()` and any other function that use the list for the compiler to recognise it. +::: #### Advanced Macros @@ -315,7 +319,9 @@ SEND_STRING(".."SS_TAP(X_END)); There are some functions you may find useful in macro-writing. Keep in mind that while you can write some fairly advanced code within a macro, if your functionality gets too complex you may want to define a custom keycode instead. Macros are meant to be simple. -?> You can also use the functions described in [Useful function](ref_functions.md) and [Checking modifier state](feature_advanced_keycodes#checking-modifier-state) for additional functionality. For example, `reset_keyboard()` allows you to reset the keyboard as part of a macro and `get_mods() & MOD_MASK_SHIFT` lets you check for the existence of active shift modifiers. +::: tip +You can also use the functions described in [Useful function](ref_functions) and [Checking modifier state](feature_advanced_keycodes#checking-modifier-state) for additional functionality. For example, `reset_keyboard()` allows you to reset the keyboard as part of a macro and `get_mods() & MOD_MASK_SHIFT` lets you check for the existence of active shift modifiers. +::: #### `record->event.pressed` diff --git a/docs/feature_midi.md b/docs/feature_midi.md index 59ee0114c8..89c6af0508 100644 --- a/docs/feature_midi.md +++ b/docs/feature_midi.md @@ -34,7 +34,7 @@ To enable advanced MIDI, add the following to your `config.h`: If you're aiming to emulate the features of something like a Launchpad or other MIDI controller you'll need to access the internal MIDI device directly. -Because there are so many possible CC messages, not all of them are implemented as keycodes. Additionally, you might need to provide more than just two values that you would get from a keycode (pressed and released) - for example, the analog values from a fader or a potentiometer. So, you will need to implement [custom keycodes](feature_macros.md) if you want to use them in your keymap directly using `process_record_user()`. +Because there are so many possible CC messages, not all of them are implemented as keycodes. Additionally, you might need to provide more than just two values that you would get from a keycode (pressed and released) - for example, the analog values from a fader or a potentiometer. So, you will need to implement [custom keycodes](feature_macros) if you want to use them in your keymap directly using `process_record_user()`. For reference of all the possible control code numbers see [MIDI Specification](#midi-specification) @@ -258,7 +258,7 @@ For the above, the `MI_C` keycode will produce a C3 (note number 48), and so on. diff --git a/docs/feature_mouse_keys.md b/docs/feature_mouse_keys.md index 42448325c9..240f6bf9be 100644 --- a/docs/feature_mouse_keys.md +++ b/docs/feature_mouse_keys.md @@ -205,4 +205,4 @@ Tips: ## Use with PS/2 Mouse and Pointing Device -Mouse keys button state is shared with [PS/2 mouse](feature_ps2_mouse.md) and [pointing device](feature_pointing_device.md) so mouse keys button presses can be used for clicks and drags. +Mouse keys button state is shared with [PS/2 mouse](feature_ps2_mouse) and [pointing device](feature_pointing_device) so mouse keys button presses can be used for clicks and drags. diff --git a/docs/feature_oled_driver.md b/docs/feature_oled_driver.md index 5a583fd40e..cb7a2f13f3 100644 --- a/docs/feature_oled_driver.md +++ b/docs/feature_oled_driver.md @@ -102,7 +102,9 @@ bool oled_task_user(void) { } ``` -?> The default font file is located at `drivers/oled/glcdfont.c` and its location can be overwritten with the `OLED_FONT_H` configuration option. Font file content can be edited with external tools such as [Helix Font Editor](https://helixfonteditor.netlify.app/) and [Logo Editor](https://joric.github.io/qle/). +::: tip +The default font file is located at `drivers/oled/glcdfont.c` and its location can be overwritten with the `OLED_FONT_H` configuration option. Font file content can be edited with external tools such as [Helix Font Editor](https://helixfonteditor.netlify.app/) and [Logo Editor](https://joric.github.io/qle/). +::: ## Buffer Read Example For some purposes, you may need to read the current state of the OLED display @@ -243,7 +245,9 @@ These configuration options should be placed in `config.h`. Example: |`OLED_DISPLAY_128X128`|*Not defined* |Changes the display defines for use with 128x128 displays. | |`OLED_DISPLAY_CUSTOM` |*Not defined* |Changes the display defines for use with custom displays.
Requires user to implement the below defines. | -!> 64x128 and 128x128 displays default to the SH1107 IC type, as these heights are not supported by the other IC types. +::: warning +64x128 and 128x128 displays default to the SH1107 IC type, as these heights are not supported by the other IC types. +::: |Define |Default |Description | | --------------------|---------------|----------------------------------------------------------------------------------------------------------------------------------------| @@ -391,9 +395,9 @@ void oled_write_ln_P(const char *data, bool invert); // Writes a PROGMEM string to the buffer at current cursor position void oled_write_raw_P(const char *data, uint16_t size); #else -# define oled_write_P(data, invert) oled_write(data, invert) -# define oled_write_ln_P(data, invert) oled_write_ln(data, invert) -# define oled_write_raw_P(data, size) oled_write_raw(data, size) +# define oled_write_P(data, invert) oled_write(data, invert) +# define oled_write_ln_P(data, invert) oled_write_ln(data, invert) +# define oled_write_raw_P(data, size) oled_write_raw(data, size) #endif // defined(__AVR__) // Can be used to manually turn on the screen if it is off @@ -462,9 +466,13 @@ uint8_t oled_max_chars(void); uint8_t oled_max_lines(void); ``` -!> Scrolling is unsupported on the SH1106 and SH1107. +::: warning +Scrolling is unsupported on the SH1106 and SH1107. +::: -!> Scrolling does not work properly on the SSD1306 if the display width is smaller than 128. +::: warning +Scrolling does not work properly on the SSD1306 if the display width is smaller than 128. +::: ## SSD1306.h Driver Conversion Guide diff --git a/docs/feature_os_detection.md b/docs/feature_os_detection.md index a50ee7ccc2..d0556d2549 100644 --- a/docs/feature_os_detection.md +++ b/docs/feature_os_detection.md @@ -29,10 +29,12 @@ enum { } os_variant_t; ``` -?> Note that it takes some time after firmware is booted to detect the OS. +::: tip +Note that it takes some time after firmware is booted to detect the OS. +::: This time is quite short, probably hundreds of milliseconds, but this data may be not ready in keyboard and layout setup functions which run very early during firmware startup. -## Callbacks :id=callbacks +## Callbacks {#callbacks} If you want to perform custom actions when the OS is detected, then you can use the `process_detected_host_os_kb` function on the keyboard level source file, or `process_detected_host_os_user` function in the user `keymap.c`. diff --git a/docs/feature_pointing_device.md b/docs/feature_pointing_device.md index f55b308286..933202a009 100644 --- a/docs/feature_pointing_device.md +++ b/docs/feature_pointing_device.md @@ -1,4 +1,4 @@ -# Pointing Device :id=pointing-device +# Pointing Device {#pointing-device} Pointing Device is a generic name for a feature intended to be generic: moving the system pointer around. There are certainly other options for it - like mousekeys - but this aims to be easily modifiable and hardware driven. You can implement custom keys to control functionality, or you can gather information from other peripherals and insert it directly here - let QMK handle the processing for you. @@ -112,7 +112,9 @@ Specific device profiles are provided which set the required values for dimensio | `AZOTEQ_IQS5XX_TPS43` | (Pick One) Sets resolution/mm to TPS43 specifications. | | `AZOTEQ_IQS5XX_TPS65` | (Pick One) Sets resolution/mm to TPS65 specifications. | -?> If using one of the above defines you can skip to gesture settings. +::: tip +If using one of the above defines you can skip to gesture settings. +::: | Setting | Description | Default | | -------------------------------- | ---------------------------------------------------------- | ------------- | @@ -383,7 +385,9 @@ uint16_t pointing_device_driver_get_cpi(void) { return 0; } void pointing_device_driver_set_cpi(uint16_t cpi) {} ``` -!> Ideally, new sensor hardware should be added to `drivers/sensors/` and `quantum/pointing_device_drivers.c`, but there may be cases where it's very specific to the hardware. So these functions are provided, just in case. +::: warning +Ideally, new sensor hardware should be added to `drivers/sensors/` and `quantum/pointing_device_drivers.c`, but there may be cases where it's very specific to the hardware. So these functions are provided, just in case. +::: ## Common Configuration @@ -404,15 +408,19 @@ void pointing_device_driver_set_cpi(uint16_t cpi) {} | `POINTING_DEVICE_SDIO_PIN` | (Optional) Provides a default SDIO pin, useful for supporting multiple sensor configs. | _not defined_ | | `POINTING_DEVICE_SCLK_PIN` | (Optional) Provides a default SCLK pin, useful for supporting multiple sensor configs. | _not defined_ | -!> When using `SPLIT_POINTING_ENABLE` the `POINTING_DEVICE_MOTION_PIN` functionality is not supported and `POINTING_DEVICE_TASK_THROTTLE_MS` will default to `1`. Increasing this value will increase transport performance at the cost of possible mouse responsiveness. +::: warning +When using `SPLIT_POINTING_ENABLE` the `POINTING_DEVICE_MOTION_PIN` functionality is not supported and `POINTING_DEVICE_TASK_THROTTLE_MS` will default to `1`. Increasing this value will increase transport performance at the cost of possible mouse responsiveness. +::: The `POINTING_DEVICE_CS_PIN`, `POINTING_DEVICE_SDIO_PIN`, and `POINTING_DEVICE_SCLK_PIN` provide a convenient way to define a single pin that can be used for an interchangeable sensor config. This allows you to have a single config, without defining each device. Each sensor allows for this to be overridden with their own defines. -!> Any pointing device with a lift/contact status can integrate inertial cursor feature into its driver, controlled by `POINTING_DEVICE_GESTURES_CURSOR_GLIDE_ENABLE`. e.g. PMW3360 can use Lift_Stat from Motion register. Note that `POINTING_DEVICE_MOTION_PIN` cannot be used with this feature; continuous polling of `get_report()` is needed to generate glide reports. +::: warning +Any pointing device with a lift/contact status can integrate inertial cursor feature into its driver, controlled by `POINTING_DEVICE_GESTURES_CURSOR_GLIDE_ENABLE`. e.g. PMW3360 can use Lift_Stat from Motion register. Note that `POINTING_DEVICE_MOTION_PIN` cannot be used with this feature; continuous polling of `get_report()` is needed to generate glide reports. +::: ## Split Keyboard Configuration -The following configuration options are only available when using `SPLIT_POINTING_ENABLE` see [data sync options](feature_split_keyboard.md?id=data-sync-options). The rotation and invert `*_RIGHT` options are only used with `POINTING_DEVICE_COMBINED`. If using `POINTING_DEVICE_LEFT` or `POINTING_DEVICE_RIGHT` use the common configuration above to configure your pointing device. +The following configuration options are only available when using `SPLIT_POINTING_ENABLE` see [data sync options](feature_split_keyboard#data-sync-options). The rotation and invert `*_RIGHT` options are only used with `POINTING_DEVICE_COMBINED`. If using `POINTING_DEVICE_LEFT` or `POINTING_DEVICE_RIGHT` use the common configuration above to configure your pointing device. | Setting | Description | Default | | ------------------------------------ | ----------------------------------------------------------------------------------------------------- | ------------- | @@ -425,7 +433,9 @@ The following configuration options are only available when using `SPLIT_POINTIN | `POINTING_DEVICE_INVERT_X_RIGHT` | (Optional) Inverts the X axis report. | _not defined_ | | `POINTING_DEVICE_INVERT_Y_RIGHT` | (Optional) Inverts the Y axis report. | _not defined_ | -!> If there is a `_RIGHT` configuration option or callback, the [common configuration](feature_pointing_device.md?id=common-configuration) option will work for the left. For correct left/right detection you should setup a [handedness option](feature_split_keyboard?id=setting-handedness), `EE_HANDS` is usually a good option for an existing board that doesn't do handedness by hardware. +::: warning +If there is a `_RIGHT` configuration option or callback, the [common configuration](feature_pointing_device#common-configuration) option will work for the left. For correct left/right detection you should setup a [handedness option](feature_split_keyboard#setting-handedness), `EE_HANDS` is usually a good option for an existing board that doesn't do handedness by hardware. +::: ## Callbacks and Functions @@ -448,7 +458,7 @@ The following configuration options are only available when using `SPLIT_POINTIN ## Split Keyboard Callbacks and Functions -The combined functions below are only available when using `SPLIT_POINTING_ENABLE` and `POINTING_DEVICE_COMBINED`. The 2 callbacks `pointing_device_task_combined_*` replace the single sided equivalents above. See the [combined pointing devices example](feature_pointing_device.md?id=combined-pointing-devices) +The combined functions below are only available when using `SPLIT_POINTING_ENABLE` and `POINTING_DEVICE_COMBINED`. The 2 callbacks `pointing_device_task_combined_*` replace the single sided equivalents above. See the [combined pointing devices example](feature_pointing_device#combined-pointing-devices) | Function | Description | | --------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ | @@ -673,11 +683,13 @@ If you are having issues with pointing device drivers debug messages can be enab #define POINTING_DEVICE_DEBUG ``` -?> The messages will be printed out to the `CONSOLE` output. For additional information, refer to [Debugging/Troubleshooting QMK](faq_debug.md). +::: tip +The messages will be printed out to the `CONSOLE` output. For additional information, refer to [Debugging/Troubleshooting QMK](faq_debug). +::: --- -# Automatic Mouse Layer :id=pointing-device-auto-mouse +# Automatic Mouse Layer {#pointing-device-auto-mouse} When using a pointing device combined with a keyboard the mouse buttons are often kept on a separate layer from the default keyboard layer, which requires pressing or holding a key to change layers before using the mouse. To make this easier and more efficient an additional pointing device feature may be enabled that will automatically activate a target layer as soon as the pointing device is active _(in motion, mouse button pressed etc.)_ and deactivate the target layer after a set time. diff --git a/docs/feature_programmable_button.md b/docs/feature_programmable_button.md index 091464e19c..1fdf44c29e 100644 --- a/docs/feature_programmable_button.md +++ b/docs/feature_programmable_button.md @@ -1,12 +1,14 @@ -# Programmable Button :id=programmable-button +# Programmable Button {#programmable-button} Programmable Buttons are keys that have no predefined meaning. This means they can be processed on the host side by custom software without the operating system trying to interpret them. The keycodes are emitted according to the HID Telephony Device page (`0x0B`), Programmable Button usage (`0x09`). On Linux (> 5.14) they are handled automatically and translated to `KEY_MACRO#` keycodes (up to `KEY_MACRO30`). -?> Currently there is no known support in Windows or macOS. It may be possible to write a custom HID driver to receive these usages, but this is out of the scope of the QMK documentation. +::: tip +Currently there is no known support in Windows or macOS. It may be possible to write a custom HID driver to receive these usages, but this is out of the scope of the QMK documentation. +::: -## Usage :id=usage +## Usage {#usage} Add the following to your `rules.mk`: @@ -14,7 +16,7 @@ Add the following to your `rules.mk`: PROGRAMMABLE_BUTTON_ENABLE = yes ``` -## Keycodes :id=keycodes +## Keycodes {#keycodes} |Key |Aliases|Description | |---------------------------|-------|----------------------| @@ -51,94 +53,94 @@ PROGRAMMABLE_BUTTON_ENABLE = yes |`QK_PROGRAMMABLE_BUTTON_31`|`PB_31`|Programmable button 31| |`QK_PROGRAMMABLE_BUTTON_32`|`PB_32`|Programmable button 32| -## API :id=api +## API {#api} -### `void programmable_button_clear(void)` :id=api-programmable-button-clear +### `void programmable_button_clear(void)` {#api-programmable-button-clear} Clear the programmable button report. --- -### `void programmable_button_add(uint8_t index)` :id=api-programmable-button-add +### `void programmable_button_add(uint8_t index)` {#api-programmable-button-add} Set the state of a button. -#### Arguments :id=api-programmable-button-add-arguments +#### Arguments {#api-programmable-button-add-arguments} - `uint8_t index` The index of the button to press, from 0 to 31. --- -### `void programmable_button_remove(uint8_t index)` :id=api-programmable-button-remove +### `void programmable_button_remove(uint8_t index)` {#api-programmable-button-remove} Reset the state of a button. -#### Arguments :id=api-programmable-button-remove-arguments +#### Arguments {#api-programmable-button-remove-arguments} - `uint8_t index` The index of the button to release, from 0 to 31. --- -### `void programmable_button_register(uint8_t index)` :id=api-programmable-button-register +### `void programmable_button_register(uint8_t index)` {#api-programmable-button-register} Set the state of a button, and flush the report. -#### Arguments :id=api-programmable-button-register-arguments +#### Arguments {#api-programmable-button-register-arguments} - `uint8_t index` The index of the button to press, from 0 to 31. --- -### `void programmable_button_unregister(uint8_t index)` :id=api-programmable-button-unregister +### `void programmable_button_unregister(uint8_t index)` {#api-programmable-button-unregister} Reset the state of a button, and flush the report. -#### Arguments :id=api-programmable-button-unregister-arguments +#### Arguments {#api-programmable-button-unregister-arguments} - `uint8_t index` The index of the button to release, from 0 to 31. --- -### `bool programmable_button_is_on(uint8_t index)` :id=api-programmable-button-is-on +### `bool programmable_button_is_on(uint8_t index)` {#api-programmable-button-is-on} Get the state of a button. -#### Arguments :id=api-programmable-button-is-on-arguments +#### Arguments {#api-programmable-button-is-on-arguments} - `uint8_t index` The index of the button to check, from 0 to 31. -#### Return Value :id=api-programmable-button-is-on-return +#### Return Value {#api-programmable-button-is-on-return} `true` if the button is pressed. --- -### `void programmable_button_flush(void)` :id=api-programmable-button-flush +### `void programmable_button_flush(void)` {#api-programmable-button-flush} Send the programmable button report to the host. --- -### `uint32_t programmable_button_get_report(void)` :id=api-programmable-button-get-report +### `uint32_t programmable_button_get_report(void)` {#api-programmable-button-get-report} Get the programmable button report. -#### Return Value :id=api-programmable-button-get-report-return +#### Return Value {#api-programmable-button-get-report-return} The bitmask of programmable button states. --- -### `void programmable_button_set_report(uint32_t report)` :id=api-programmable-button-set-report +### `void programmable_button_set_report(uint32_t report)` {#api-programmable-button-set-report} Set the programmable button report. -#### Arguments :id=api-programmable-button-set-report-arguments +#### Arguments {#api-programmable-button-set-report-arguments} - `uint32_t report` A bitmask of programmable button states. diff --git a/docs/feature_ps2_mouse.md b/docs/feature_ps2_mouse.md index 766fd6fe78..90f4cca827 100644 --- a/docs/feature_ps2_mouse.md +++ b/docs/feature_ps2_mouse.md @@ -1,4 +1,4 @@ -# PS/2 Mouse Support :id=ps2-mouse-support +# PS/2 Mouse Support {#ps2-mouse-support} Its possible to hook up a PS/2 mouse (for example touchpads or trackpoints) to your keyboard as a composite device. @@ -6,7 +6,7 @@ To hook up a Trackpoint, you need to obtain a Trackpoint module (i.e. harvest fr There are three available modes for hooking up PS/2 devices: USART (best), interrupts (better) or busywait (not recommended). -## The Circuitry between Trackpoint and Controller :id=the-circuitry-between-trackpoint-and-controller +## The Circuitry between Trackpoint and Controller {#the-circuitry-between-trackpoint-and-controller} To get the things working, a 4.7K drag is needed between the two lines DATA and CLK and the line 5+. @@ -24,7 +24,7 @@ MODULE 5+ --------+--+--------- PWR CONTROLLER ``` -## Busywait Version :id=busywait-version +## Busywait Version {#busywait-version} Note: This is not recommended, you may encounter jerky movement or unsent inputs. Please use interrupt or USART version if possible. @@ -40,12 +40,12 @@ In your keyboard config.h: ```c #ifdef PS2_DRIVER_BUSYWAIT -# define PS2_CLOCK_PIN D1 -# define PS2_DATA_PIN D2 +# define PS2_CLOCK_PIN D1 +# define PS2_DATA_PIN D2 #endif ``` -### Interrupt Version (AVR/ATMega32u4) :id=interrupt-version-avr +### Interrupt Version (AVR/ATMega32u4) {#interrupt-version-avr} The following example uses D2 for clock and D5 for data. You can use any INT or PCINT pin for clock, and any pin for data. @@ -78,7 +78,7 @@ In your keyboard config.h: #endif ``` -### Interrupt Version (ARM chibios) :id=interrupt-version-chibios +### Interrupt Version (ARM chibios) {#interrupt-version-chibios} Pretty much any two pins can be used for the (software) interrupt variant on ARM cores. The example below uses A8 for clock, and A9 for data. @@ -103,7 +103,7 @@ And in the chibios specifig halconf.h: ``` -### USART Version :id=usart-version +### USART Version {#usart-version} To use USART on the ATMega32u4, you have to use PD5 for clock and PD2 for data. If one of those are unavailable, you need to use interrupt version. @@ -155,7 +155,7 @@ In your keyboard config.h: #endif ``` -### RP2040 PIO Version :id=rp2040-pio-version +### RP2040 PIO Version {#rp2040-pio-version} The `PIO` subsystem is a Raspberry Pi RP2040 specific implementation, using the integrated PIO peripheral and is therefore only available on this MCU. @@ -178,9 +178,9 @@ Example info.json content: } ``` -## Additional Settings :id=additional-settings +## Additional Settings {#additional-settings} -### PS/2 Mouse Features :id=ps2-mouse-features +### PS/2 Mouse Features {#ps2-mouse-features} These enable settings supported by the PS/2 mouse protocol. @@ -221,7 +221,7 @@ void ps2_mouse_set_resolution(ps2_mouse_resolution_t resolution); void ps2_mouse_set_sample_rate(ps2_mouse_sample_rate_t sample_rate); ``` -### Fine Control :id=fine-control +### Fine Control {#fine-control} Use the following defines to change the sensitivity and speed of the mouse. Note: you can also use `ps2_mouse_set_resolution` for the same effect (not supported on most touchpads). @@ -232,7 +232,7 @@ Note: you can also use `ps2_mouse_set_resolution` for the same effect (not suppo #define PS2_MOUSE_V_MULTIPLIER 1 ``` -### Scroll Button :id=scroll-button +### Scroll Button {#scroll-button} If you're using a trackpoint, you will likely want to be able to use it for scrolling. It's possible to enable a "scroll button/s" that when pressed will cause the mouse to scroll instead of moving. @@ -279,7 +279,7 @@ Fine control over the scrolling is supported with the following defines: #define PS2_MOUSE_SCROLL_DIVISOR_V 2 ``` -### Invert Mouse buttons :id=invert-buttons +### Invert Mouse buttons {#invert-buttons} To invert the left & right buttons you can put: @@ -289,7 +289,7 @@ To invert the left & right buttons you can put: into config.h. -### Invert Mouse and Scroll Axes :id=invert-mouse-and-scroll-axes +### Invert Mouse and Scroll Axes {#invert-mouse-and-scroll-axes} To invert the X and Y axes you can put: @@ -309,7 +309,7 @@ To reverse the scroll axes you can put: into config.h. -### Rotate Mouse Axes :id=rotate-mouse-axes +### Rotate Mouse Axes {#rotate-mouse-axes} Transform the output of the device with a clockwise rotation of 90, 180, or 270 degrees. @@ -328,7 +328,7 @@ be North-facing, compensate as follows: #define PS2_MOUSE_ROTATE 90 /* Compensate for West-facing device orientation. */ ``` -### Debug Settings :id=debug-settings +### Debug Settings {#debug-settings} To debug the mouse, add `debug_mouse = true` or enable via bootmagic. @@ -338,7 +338,7 @@ To debug the mouse, add `debug_mouse = true` or enable via bootmagic. #define PS2_MOUSE_DEBUG_RAW ``` -### Movement Hook :id=movement-hook +### Movement Hook {#movement-hook} Process mouse movement in the keymap before it is sent to the host. Example uses include filtering noise, adding acceleration, and automatically activating diff --git a/docs/feature_rawhid.md b/docs/feature_rawhid.md index 64cb42fdfe..c3ecfbe099 100644 --- a/docs/feature_rawhid.md +++ b/docs/feature_rawhid.md @@ -1,10 +1,10 @@ -# Raw HID :id=raw-hid +# Raw HID {#raw-hid} The Raw HID feature allows for bidirectional communication between QMK and the host computer over an HID interface. This has many potential use cases, such as switching keymaps on the fly or sending useful metrics like CPU/RAM usage. In order to communicate with the keyboard using this feature, you will need to write a program that runs on the host. As such, some basic programming skills are required - more if you intend to implement complex behaviour. -## Usage :id=usage +## Usage {#usage} Add the following to your `rules.mk`: @@ -12,7 +12,7 @@ Add the following to your `rules.mk`: RAW_ENABLE = yes ``` -## Basic Configuration :id=basic-configuration +## Basic Configuration {#basic-configuration} By default, the HID Usage Page and Usage ID for the Raw HID interface are `0xFF60` and `0x61`. However, they can be changed if necessary by adding the following to your `config.h`: @@ -21,7 +21,7 @@ By default, the HID Usage Page and Usage ID for the Raw HID interface are `0xFF6 |`RAW_USAGE_PAGE`|`0xFF60`|The usage page of the Raw HID interface| |`RAW_USAGE_ID` |`0x61` |The usage ID of the Raw HID interface | -## Sending Data to the Keyboard :id=sending-data-to-the-keyboard +## Sending Data to the Keyboard {#sending-data-to-the-keyboard} To send data to the keyboard, you must first find a library for communicating with HID devices in the programming language of your choice. Here are some examples: @@ -46,15 +46,17 @@ void raw_hid_receive(uint8_t *data, uint8_t length) { } ``` -!> Because the HID specification does not support variable length reports, all reports in both directions must be exactly `RAW_EPSIZE` (currently 32) bytes long, regardless of actual payload length. However, variable length payloads can potentially be implemented on top of this by creating your own data structure that may span multiple reports. +::: warning +Because the HID specification does not support variable length reports, all reports in both directions must be exactly `RAW_EPSIZE` (currently 32) bytes long, regardless of actual payload length. However, variable length payloads can potentially be implemented on top of this by creating your own data structure that may span multiple reports. +::: -## Receiving Data from the Keyboard :id=receiving-data-from-the-keyboard +## Receiving Data from the Keyboard {#receiving-data-from-the-keyboard} If you need the keyboard to send data back to the host, simply call the `raw_hid_send()` function. It requires two arguments - a pointer to a 32-byte buffer containing the data you wish to send, and the length (which should always be `RAW_EPSIZE`). The received report can then be handled in whichever way your HID library provides. -## Simple Example :id=simple-example +## Simple Example {#simple-example} The following example reads the first byte of the received report from the host, and if it is an ASCII "A", responds with "B". `memset()` is used to fill the response buffer (which could still contain the previous response) with null bytes. @@ -129,13 +131,13 @@ if __name__ == '__main__': ]) ``` -## API :id=api +## API {#api} -### `void raw_hid_receive(uint8_t *data, uint8_t length)` :id=api-raw-hid-receive +### `void raw_hid_receive(uint8_t *data, uint8_t length)` {#api-raw-hid-receive} Callback, invoked when a raw HID report has been received from the host. -#### Arguments :id=api-raw-hid-receive-arguments +#### Arguments {#api-raw-hid-receive-arguments} - `uint8_t *data` A pointer to the received data. Always 32 bytes in length. @@ -144,11 +146,11 @@ Callback, invoked when a raw HID report has been received from the host. --- -### `void raw_hid_send(uint8_t *data, uint8_t length)` :id=api-raw-hid-send +### `void raw_hid_send(uint8_t *data, uint8_t length)` {#api-raw-hid-send} Send an HID report. -#### Arguments :id=api-raw-hid-send-arguments +#### Arguments {#api-raw-hid-send-arguments} - `uint8_t *data` A pointer to the data to send. Must always be 32 bytes in length. diff --git a/docs/feature_repeat_key.md b/docs/feature_repeat_key.md index 6fa8a724ef..c353ec5b59 100644 --- a/docs/feature_repeat_key.md +++ b/docs/feature_repeat_key.md @@ -172,7 +172,7 @@ uint16_t get_alt_repeat_key_keycode_user(uint16_t keycode, uint8_t mods) { #### Typing shortcuts A useful possibility is having Alternate Repeat press [a -macro](feature_macros.md). This way macros can be used without having to +macro](feature_macros). This way macros can be used without having to dedicate keys to them. The following defines a couple shortcuts. * Typing K, Alt Repeat produces "`keyboard`," with the @@ -280,8 +280,10 @@ bool remember_last_key_user(uint16_t keycode, keyrecord_t* record, } ``` -?> See [Layer Functions](feature_layers.md#functions) and [Checking Modifier -State](feature_advanced_keycodes.md#checking-modifier-state) for further +::: tip +See [Layer Functions](feature_layers#functions) and [Checking Modifier +::: +State](feature_advanced_keycodes#checking-modifier-state) for further details. @@ -386,7 +388,7 @@ By leveraging `get_last_keycode()` in macros, it is possible to define additional, distinct "Alternate Repeat"-like keys. The following defines two keys `ALTREP2` and `ALTREP3` and implements ten shortcuts with them for common English 5-gram letter patterns, taking inspiration from -[Stenotype](feature_stenography.md): +[Stenotype](feature_stenography): | Typing | Produces | Typing | Produces | diff --git a/docs/feature_rgb_matrix.md b/docs/feature_rgb_matrix.md index d05d768ceb..b9c01dcbf5 100644 --- a/docs/feature_rgb_matrix.md +++ b/docs/feature_rgb_matrix.md @@ -1,12 +1,12 @@ -# RGB Matrix Lighting :id=rgb-matrix-lighting +# RGB Matrix Lighting {#rgb-matrix-lighting} This feature allows you to use RGB LED matrices driven by external drivers. It hooks into the RGBLIGHT system so you can use the same keycodes as RGBLIGHT to control it. -If you want to use single color LED's you should use the [LED Matrix Subsystem](feature_led_matrix.md) instead. +If you want to use single color LED's you should use the [LED Matrix Subsystem](feature_led_matrix) instead. -## Driver configuration :id=driver-configuration +## Driver configuration {#driver-configuration} --- -### IS31FL3731 :id=is31fl3731 +### IS31FL3731 {#is31fl3731} There is basic support for addressable RGB matrix lighting with the I2C IS31FL3731 RGB controller. To enable it, add this to your `rules.mk`: @@ -48,7 +48,9 @@ Here is an example using 2 drivers. #define RGB_MATRIX_LED_COUNT (DRIVER_1_LED_TOTAL + DRIVER_2_LED_TOTAL) ``` -!> Note the parentheses, this is so when `RGB_MATRIX_LED_COUNT` is used in code and expanded, the values are added together before any additional math is applied to them. As an example, `rand() % (DRIVER_1_LED_TOTAL + DRIVER_2_LED_TOTAL)` will give very different results than `rand() % DRIVER_1_LED_TOTAL + DRIVER_2_LED_TOTAL`. +::: warning +Note the parentheses, this is so when `RGB_MATRIX_LED_COUNT` is used in code and expanded, the values are added together before any additional math is applied to them. As an example, `rand() % (DRIVER_1_LED_TOTAL + DRIVER_2_LED_TOTAL)` will give very different results than `rand() % DRIVER_1_LED_TOTAL + DRIVER_2_LED_TOTAL`. +::: For split keyboards using `RGB_MATRIX_SPLIT` with an LED driver, you can either have the same driver address or different driver addresses. If using different addresses, use `IS31FL3731_I2C_ADDRESS_1` for one and `IS31FL3731_I2C_ADDRESS_2` for the other one. Then, in `g_is31fl3731_leds`, fill out the correct driver index (0 or 1). If using one address, use `IS31FL3731_I2C_ADDRESS_1` for both, and use index 0 for `g_is31fl3731_leds`. @@ -70,7 +72,7 @@ const is31fl3731_led_t PROGMEM g_is31fl3731_leds[IS31FL3731_LED_COUNT] = { Where `Cx_y` is the location of the LED in the matrix defined by [the datasheet](https://www.issi.com/WW/pdf/31FL3731.pdf) and the header file `drivers/led/issi/is31fl3731.h`. The `driver` is the index of the driver you defined in your `config.h` (`0`, `1`, `2`, or `3`). --- -### IS31FL3733 :id=is31fl3733 +### IS31FL3733 {#is31fl3733} There is basic support for addressable RGB matrix lighting with the I2C IS31FL3733 RGB controller. To enable it, add this to your `rules.mk`: @@ -132,7 +134,9 @@ Here is an example using 2 drivers. #define RGB_MATRIX_LED_COUNT (DRIVER_1_LED_TOTAL + DRIVER_2_LED_TOTAL) ``` -!> Note the parentheses, this is so when `RGB_MATRIX_LED_COUNT` is used in code and expanded, the values are added together before any additional math is applied to them. As an example, `rand() % (DRIVER_1_LED_TOTAL + DRIVER_2_LED_TOTAL)` will give very different results than `rand() % DRIVER_1_LED_TOTAL + DRIVER_2_LED_TOTAL`. +::: warning +Note the parentheses, this is so when `RGB_MATRIX_LED_COUNT` is used in code and expanded, the values are added together before any additional math is applied to them. As an example, `rand() % (DRIVER_1_LED_TOTAL + DRIVER_2_LED_TOTAL)` will give very different results than `rand() % DRIVER_1_LED_TOTAL + DRIVER_2_LED_TOTAL`. +::: Currently only 4 drivers are supported, but it would be trivial to support all 8 combinations. @@ -154,7 +158,7 @@ const is31fl3733_led_t PROGMEM g_is31fl3733_leds[IS31FL3733_LED_COUNT] = { Where `SWx_CSy` is the location of the LED in the matrix defined by [the datasheet](https://www.issi.com/WW/pdf/31FL3733.pdf) and the header file `drivers/led/issi/is31fl3733.h`. The `driver` is the index of the driver you defined in your `config.h` (`0`, `1`, `2`, or `3` for now). --- -### IS31FL3736 :id=is31fl3736 +### IS31FL3736 {#is31fl3736} There is basic support for addressable RGB matrix lighting with the I2C IS31FL3736 RGB controller. To enable it, add this to your `rules.mk`: @@ -213,7 +217,9 @@ Here is an example using 2 drivers. #define DRIVER_2_LED_TOTAL 32 #define RGB_MATRIX_LED_COUNT (DRIVER_1_LED_TOTAL + DRIVER_2_LED_TOTAL) ``` -!> Note the parentheses, this is so when `RGB_MATRIX_LED_COUNT` is used in code and expanded, the values are added together before any additional math is applied to them. As an example, `rand() % (DRIVER_1_LED_TOTAL + DRIVER_2_LED_TOTAL)` will give very different results than `rand() % DRIVER_1_LED_TOTAL + DRIVER_2_LED_TOTAL`. +::: warning +Note the parentheses, this is so when `RGB_MATRIX_LED_COUNT` is used in code and expanded, the values are added together before any additional math is applied to them. As an example, `rand() % (DRIVER_1_LED_TOTAL + DRIVER_2_LED_TOTAL)` will give very different results than `rand() % DRIVER_1_LED_TOTAL + DRIVER_2_LED_TOTAL`. +::: Define these arrays listing all the LEDs in your `.c`: @@ -229,7 +235,7 @@ const is31fl3736_led_t PROGMEM g_is31fl3736_leds[IS31FL3736_LED_COUNT] = { .... } ``` -### IS31FL3737 :id=is31fl3737 +### IS31FL3737 {#is31fl3737} There is basic support for addressable RGB matrix lighting with the I2C IS31FL3737 RGB controller. To enable it, add this to your `rules.mk`: @@ -287,7 +293,9 @@ Here is an example using 2 drivers. #define DRIVER_2_LED_TOTAL 36 #define RGB_MATRIX_LED_COUNT (DRIVER_1_LED_TOTAL + DRIVER_2_LED_TOTAL) ``` -!> Note the parentheses, this is so when `RGB_MATRIX_LED_COUNT` is used in code and expanded, the values are added together before any additional math is applied to them. As an example, `rand() % (DRIVER_1_LED_TOTAL + DRIVER_2_LED_TOTAL)` will give very different results than `rand() % DRIVER_1_LED_TOTAL + DRIVER_2_LED_TOTAL`. +::: warning +Note the parentheses, this is so when `RGB_MATRIX_LED_COUNT` is used in code and expanded, the values are added together before any additional math is applied to them. As an example, `rand() % (DRIVER_1_LED_TOTAL + DRIVER_2_LED_TOTAL)` will give very different results than `rand() % DRIVER_1_LED_TOTAL + DRIVER_2_LED_TOTAL`. +::: Define these arrays listing all the LEDs in your `.c`: @@ -307,7 +315,7 @@ const is31fl3737_led_t PROGMEM g_is31fl3737_leds[IS31FL3737_LED_COUNT] = { Where `SWx_CSy` is the location of the LED in the matrix defined by [the datasheet](https://www.issi.com/WW/pdf/31FL3737.pdf) and the header file `drivers/led/issi/is31fl3737.h`. The `driver` is the index of the driver you defined in your `config.h` (Only `0`, `1`, `2`, or `3` for now). --- -### IS31FLCOMMON :id=is31flcommon +### IS31FLCOMMON {#is31flcommon} There is basic support for addressable RGB matrix lighting with a selection of I2C ISSI Lumissil RGB controllers through a shared common driver. To enable it, add this to your `rules.mk`: @@ -372,7 +380,9 @@ Here is an example using 2 drivers. #define RGB_MATRIX_LED_COUNT (DRIVER_1_LED_TOTAL + DRIVER_2_LED_TOTAL) ``` -!> Note the parentheses, this is so when `RGB_MATRIX_LED_COUNT` is used in code and expanded, the values are added together before any additional math is applied to them. As an example, `rand() % (DRIVER_1_LED_TOTAL + DRIVER_2_LED_TOTAL)` will give very different results than `rand() % DRIVER_1_LED_TOTAL + DRIVER_2_LED_TOTAL`. +::: warning +Note the parentheses, this is so when `RGB_MATRIX_LED_COUNT` is used in code and expanded, the values are added together before any additional math is applied to them. As an example, `rand() % (DRIVER_1_LED_TOTAL + DRIVER_2_LED_TOTAL)` will give very different results than `rand() % DRIVER_1_LED_TOTAL + DRIVER_2_LED_TOTAL`. +::: Currently only 4 drivers are supported, but it would be trivial to support for more. Note that using a combination of different drivers is not supported. All drivers must be of the same model. @@ -415,7 +425,7 @@ Where LED Index is the position of the LED in the `g_is31_leds` array. The `scal --- -### WS2812 :id=ws2812 +### WS2812 {#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`: @@ -433,11 +443,13 @@ Configure the hardware via your `config.h`: #define RGB_MATRIX_LED_COUNT 70 ``` -?> There are additional configuration options for ARM controllers that offer increased performance over the default bitbang driver. Please see [WS2812 Driver](ws2812_driver.md) for more information. +::: tip +There are additional configuration options for ARM controllers that offer increased performance over the default bitbang driver. Please see [WS2812 Driver](ws2812_driver) for more information. +::: --- -### APA102 :id=apa102 +### APA102 {#apa102} There is basic support for APA102 based addressable LED strands. To enable it, add this to your `rules.mk`: @@ -458,7 +470,7 @@ Configure the hardware via your `config.h`: ``` --- -### AW20216S :id=aw20216s +### AW20216S {#aw20216s} There is basic support for addressable RGB matrix lighting with the SPI AW20216S RGB controller. To enable it, add this to your `rules.mk`: ```make @@ -496,7 +508,9 @@ Here is an example using 2 drivers. #define RGB_MATRIX_LED_COUNT (DRIVER_1_LED_TOTAL + DRIVER_2_LED_TOTAL) ``` -!> Note the parentheses, this is so when `RGB_MATRIX_LED_COUNT` is used in code and expanded, the values are added together before any additional math is applied to them. As an example, `rand() % (DRIVER_1_LED_TOTAL + DRIVER_2_LED_TOTAL)` will give very different results than `rand() % DRIVER_1_LED_TOTAL + DRIVER_2_LED_TOTAL`. +::: warning +Note the parentheses, this is so when `RGB_MATRIX_LED_COUNT` is used in code and expanded, the values are added together before any additional math is applied to them. As an example, `rand() % (DRIVER_1_LED_TOTAL + DRIVER_2_LED_TOTAL)` will give very different results than `rand() % DRIVER_1_LED_TOTAL + DRIVER_2_LED_TOTAL`. +::: Define these arrays listing all the LEDs in your `.c`: @@ -527,7 +541,7 @@ const aw20216s_led_t PROGMEM g_aw20216s_leds[AW20216S_LED_COUNT] = { --- -## Common Configuration :id=common-configuration +## Common Configuration {#common-configuration} From this point forward the configuration is the same for all the drivers. The `led_config_t` struct provides a key electrical matrix to led index lookup table, what the physical position of each LED is on the board, and what type of key or usage the LED if the LED represents. Here is a brief example: @@ -560,7 +574,7 @@ As mentioned earlier, the center of the keyboard by default is expected to be `{ `// LED Index to Flag` is a bitmask, whether or not a certain LEDs is of a certain type. It is recommended that LEDs are set to only 1 type. -## Flags :id=flags +## Flags {#flags} |Define |Value |Description | |----------------------------|------|-------------------------------------------------| @@ -573,7 +587,7 @@ As mentioned earlier, the center of the keyboard by default is expected to be `{ |`LED_FLAG_KEYLIGHT` |`0x04`|If the LED is for key backlight | |`LED_FLAG_INDICATOR` |`0x08`|If the LED is for keyboard state indication | -## Keycodes :id=keycodes +## Keycodes {#keycodes} All RGB keycodes are currently shared with the RGBLIGHT system: @@ -599,12 +613,16 @@ All RGB keycodes are currently shared with the RGBLIGHT system: `RGB_MODE_PLAIN`, `RGB_MODE_BREATHE`, `RGB_MODE_RAINBOW`, and `RGB_MODE_SWIRL` are the only ones that are mapped properly. The rest don't have a direct equivalent, and are not mapped. -?> `RGB_*` keycodes cannot be used with functions like `tap_code16(RGB_HUD)` as they're not USB HID keycodes. If you wish to replicate similar behaviour in custom code within your firmware (e.g. inside `encoder_update_user()` or `process_record_user()`), the equivalent [RGB functions](#functions) should be used instead. +::: tip +`RGB_*` keycodes cannot be used with functions like `tap_code16(RGB_HUD)` as they're not USB HID keycodes. If you wish to replicate similar behaviour in custom code within your firmware (e.g. inside `encoder_update_user()` or `process_record_user()`), the equivalent [RGB functions](#functions) should be used instead. +::: -!> By default, if you have both the [RGB Light](feature_rgblight.md) and the RGB Matrix feature enabled, these keycodes will work for both features, at the same time. You can disable the keycode functionality by defining the `*_DISABLE_KEYCODES` option for the specific feature. +::: warning +By default, if you have both the [RGB Light](feature_rgblight) and the RGB Matrix feature enabled, these keycodes will work for both features, at the same time. You can disable the keycode functionality by defining the `*_DISABLE_KEYCODES` option for the specific feature. +::: -## RGB Matrix Effects :id=rgb-matrix-effects +## RGB Matrix Effects {#rgb-matrix-effects} All effects have been configured to support current configuration values (Hue, Saturation, Value, & Speed) unless otherwise noted below. These are the effects that are currently available: @@ -709,7 +727,9 @@ You can enable a single effect by defining `ENABLE_[EFFECT_NAME]` in your `confi |`#define ENABLE_RGB_MATRIX_TYPING_HEATMAP` |Enables `RGB_MATRIX_TYPING_HEATMAP` | |`#define ENABLE_RGB_MATRIX_DIGITAL_RAIN` |Enables `RGB_MATRIX_DIGITAL_RAIN` | -?> These modes introduce additional logic that can increase firmware size. +::: tip +These modes introduce additional logic that can increase firmware size. +::: |Reactive Defines |Description | |------------------------------------------------------|----------------------------------------------| @@ -726,10 +746,12 @@ You can enable a single effect by defining `ENABLE_[EFFECT_NAME]` in your `confi |`#define ENABLE_RGB_MATRIX_SOLID_SPLASH` |Enables `RGB_MATRIX_SOLID_SPLASH` | |`#define ENABLE_RGB_MATRIX_SOLID_MULTISPLASH` |Enables `RGB_MATRIX_SOLID_MULTISPLASH` | -?> These modes introduce additional logic that can increase firmware size. +::: tip +These modes introduce additional logic that can increase firmware size. +::: -### RGB Matrix Effect Typing Heatmap :id=rgb-matrix-effect-typing-heatmap +### RGB Matrix Effect Typing Heatmap {#rgb-matrix-effect-typing-heatmap} This effect will color the RGB matrix according to a heatmap of recently pressed keys. Whenever a key is pressed its "temperature" increases as well as that of its neighboring keys. The temperature of each key is then decreased automatically every 25 milliseconds by default. @@ -767,7 +789,7 @@ the number of keystrokes needed to fully heat up the key. #define RGB_MATRIX_TYPING_HEATMAP_INCREASE_STEP 32 ``` -### RGB Matrix Effect Solid Reactive :id=rgb-matrix-effect-solid-reactive +### RGB Matrix Effect Solid Reactive {#rgb-matrix-effect-solid-reactive} Solid reactive effects will pulse RGB light on key presses with user configurable hues. To enable gradient mode that will automatically change reactive color, add the following define: @@ -777,11 +799,13 @@ Solid reactive effects will pulse RGB light on key presses with user configurabl Gradient mode will loop through the color wheel hues over time and its duration can be controlled with the effect speed keycodes (`RGB_SPI`/`RGB_SPD`). -## Custom RGB Matrix Effects :id=custom-rgb-matrix-effects +## Custom RGB Matrix Effects {#custom-rgb-matrix-effects} By setting `RGB_MATRIX_CUSTOM_USER = yes` in `rules.mk`, new effects can be defined directly from your keymap or userspace, without having to edit any QMK core files. To declare new effects, create a `rgb_matrix_user.inc` file in the user keymap directory or userspace folder. -?> Hardware maintainers who want to limit custom effects to a specific keyboard can create a `rgb_matrix_kb.inc` file in the root of the keyboard directory, and add `RGB_MATRIX_CUSTOM_KB = yes` to the keyboard level `rules.mk`. +::: tip +Hardware maintainers who want to limit custom effects to a specific keyboard can create a `rgb_matrix_kb.inc` file in the root of the keyboard directory, and add `RGB_MATRIX_CUSTOM_KB = yes` to the keyboard level `rules.mk`. +::: To use custom effects in your code, simply prepend `RGB_MATRIX_CUSTOM_` to the effect name specified in `RGB_MATRIX_EFFECT()`. For example, an effect declared as `RGB_MATRIX_EFFECT(my_cool_effect)` would be referenced with: @@ -835,7 +859,7 @@ static bool my_cool_effect2(effect_params_t* params) { For inspiration and examples, check out the built-in effects under `quantum/rgb_matrix/animations/`. -## Colors :id=colors +## Colors {#colors} These are shorthands to popular colors. The `RGB` ones can be passed to the `setrgb` functions, while the `HSV` ones to the `sethsv` functions. @@ -864,7 +888,7 @@ These are shorthands to popular colors. The `RGB` ones can be passed to the `set These are defined in [`color.h`](https://github.com/qmk/qmk_firmware/blob/master/quantum/color.h). Feel free to add to this list! -## Additional `config.h` Options :id=additional-configh-options +## Additional `config.h` Options {#additional-configh-options} ```c #define RGB_MATRIX_KEYRELEASES // reactive effects respond to keyreleases (instead of keypresses) @@ -886,19 +910,19 @@ These are defined in [`color.h`](https://github.com/qmk/qmk_firmware/blob/master #define RGB_TRIGGER_ON_KEYDOWN // Triggers RGB keypress events on key down. This makes RGB control feel more responsive. This may cause RGB to not function properly on some boards ``` -## EEPROM storage :id=eeprom-storage +## EEPROM storage {#eeprom-storage} The EEPROM for it is currently shared with the LED Matrix system (it's generally assumed only one feature would be used at a time). -## Functions :id=functions +## Functions {#functions} -### Direct Operation :id=direct-operation +### Direct Operation {#direct-operation} |Function |Description | |--------------------------------------------|-------------| |`rgb_matrix_set_color_all(r, g, b)` |Set all of the LEDs to the given RGB value, where `r`/`g`/`b` are between 0 and 255 (not written to EEPROM) | |`rgb_matrix_set_color(index, r, g, b)` |Set a single LED to the given RGB value, where `r`/`g`/`b` are between 0 and 255, and `index` is between 0 and `RGB_MATRIX_LED_COUNT` (not written to EEPROM) | -### Disable/Enable Effects :id=disable-enable-effects +### Disable/Enable Effects {#disable-enable-effects} |Function |Description | |--------------------------------------------|-------------| |`rgb_matrix_toggle()` |Toggle effect range LEDs between on and off | @@ -908,7 +932,7 @@ The EEPROM for it is currently shared with the LED Matrix system (it's generally |`rgb_matrix_disable()` |Turn effect range LEDs off, based on their previous state | |`rgb_matrix_disable_noeeprom()` |Turn effect range LEDs off, based on their previous state (not written to EEPROM) | -### Change Effect Mode :id=change-effect-mode +### Change Effect Mode {#change-effect-mode} |Function |Description | |--------------------------------------------|-------------| |`rgb_matrix_mode(mode)` |Set the mode, if RGB animations are enabled | @@ -925,7 +949,7 @@ The EEPROM for it is currently shared with the LED Matrix system (it's generally |`rgb_matrix_set_speed_noeeprom(speed)` |Set the speed of the animations to the given value where `speed` is between 0 and 255 (not written to EEPROM) | |`rgb_matrix_reload_from_eeprom()` |Reload the effect configuration (enabled, mode and color) from EEPROM | -### Change Color :id=change-color +### Change Color {#change-color} |Function |Description | |--------------------------------------------|-------------| |`rgb_matrix_increase_hue()` |Increase the hue for effect range LEDs. This wraps around at maximum hue | @@ -943,7 +967,7 @@ The EEPROM for it is currently shared with the LED Matrix system (it's generally |`rgb_matrix_sethsv(h, s, v)` |Set LEDs to the given HSV value where `h`/`s`/`v` are between 0 and 255 | |`rgb_matrix_sethsv_noeeprom(h, s, v)` |Set LEDs to the given HSV value where `h`/`s`/`v` are between 0 and 255 (not written to EEPROM) | -### Query Current Status :id=query-current-status +### Query Current Status {#query-current-status} |Function |Description | |---------------------------------|---------------------------| |`rgb_matrix_is_enabled()` |Gets current on/off status | @@ -955,9 +979,9 @@ The EEPROM for it is currently shared with the LED Matrix system (it's generally |`rgb_matrix_get_speed()` |Gets current speed | |`rgb_matrix_get_suspend_state()` |Gets current suspend state | -## Callbacks :id=callbacks +## Callbacks {#callbacks} -### Indicators :id=indicators +### Indicators {#indicators} If you want to set custom indicators, such as an LED for Caps Lock, or layer indication, then you can use the `rgb_matrix_indicators_kb` function on the keyboard level source file, or `rgb_matrix_indicators_user` function in the user `keymap.c`. ```c @@ -979,7 +1003,7 @@ bool rgb_matrix_indicators_advanced_user(uint8_t led_min, uint8_t led_max) { } ``` -### Indicator Examples :id=indicator-examples +### Indicator Examples {#indicator-examples} Caps Lock indicator on alphanumeric flagged keys: ```c @@ -1035,9 +1059,11 @@ bool rgb_matrix_indicators_advanced_user(uint8_t led_min, uint8_t led_max) { } ``` -?> Split keyboards will require layer state data syncing with `#define SPLIT_LAYER_STATE_ENABLE`. See [Data Sync Options](feature_split_keyboard?id=data-sync-options) for more details. +::: tip +Split keyboards will require layer state data syncing with `#define SPLIT_LAYER_STATE_ENABLE`. See [Data Sync Options](feature_split_keyboard#data-sync-options) for more details. +::: -#### Examples :id=indicator-examples +#### Examples {#indicator-examples-2} This example sets the modifiers to be a specific color based on the layer state. You can use a switch case here, instead, if you would like. This uses HSV and then converts to RGB, because this allows the brightness to be limited (important when using the WS2812 driver). @@ -1078,7 +1104,9 @@ bool rgb_matrix_indicators_advanced_user(uint8_t led_min, uint8_t led_max) { } ``` -?> RGB indicators on split keyboards will require state information synced to the slave half (e.g. `#define SPLIT_LAYER_STATE_ENABLE`). See [data sync options](feature_split_keyboard.md#data-sync-options) for more details. +::: tip +RGB indicators on split keyboards will require state information synced to the slave half (e.g. `#define SPLIT_LAYER_STATE_ENABLE`). See [data sync options](feature_split_keyboard#data-sync-options) for more details. +::: #### Indicators without RGB Matrix Effect diff --git a/docs/feature_rgblight.md b/docs/feature_rgblight.md index ae37ceca92..bd973ef009 100644 --- a/docs/feature_rgblight.md +++ b/docs/feature_rgblight.md @@ -22,7 +22,9 @@ On keyboards with onboard RGB LEDs, it is usually enabled by default. If it is n RGBLIGHT_ENABLE = yes ``` -?> There are additional configuration options for ARM controllers that offer increased performance over the default WS2812 bitbang driver. Please see [WS2812 Driver](ws2812_driver.md) for more information. +::: tip +There are additional configuration options for ARM controllers that offer increased performance over the default WS2812 bitbang driver. Please see [WS2812 Driver](ws2812_driver) for more information. +::: For APA102 LEDs, add the following to your `rules.mk`: @@ -47,7 +49,7 @@ Then you should be able to use the keycodes below to change the RGB lighting to QMK uses [Hue, Saturation, and Value](https://en.wikipedia.org/wiki/HSL_and_HSV) to select colors rather than RGB. The color wheel below demonstrates how this works. -HSV Color Wheel +HSV Color Wheel Changing the **Hue** cycles around the circle.
Changing the **Saturation** moves between the inner and outer sections of the wheel, affecting the intensity of the color.
@@ -79,10 +81,14 @@ Changing the **Value** sets the overall brightness.
|`RGB_MODE_RGBTEST` |`RGB_M_T` |Red, Green, Blue test animation mode | |`RGB_MODE_TWINKLE` |`RGB_M_TW`|Twinkle animation mode | -?> `RGB_*` keycodes cannot be used with functions like `tap_code16(RGB_HUI)` as they're not USB HID keycodes. If you wish to replicate similar behaviour in custom code within your firmware (e.g. inside `encoder_update_user()` or `process_record_user()`), the equivalent [RGB functions](#functions) should be used instead. +::: tip +`RGB_*` keycodes cannot be used with functions like `tap_code16(RGB_HUI)` as they're not USB HID keycodes. If you wish to replicate similar behaviour in custom code within your firmware (e.g. inside `encoder_update_user()` or `process_record_user()`), the equivalent [RGB functions](#functions) should be used instead. +::: -!> By default, if you have both the RGB Light and the [RGB Matrix](feature_rgb_matrix.md) feature enabled, these keycodes will work for both features, at the same time. You can disable the keycode functionality by defining the `*_DISABLE_KEYCODES` option for the specific feature. +::: warning +By default, if you have both the RGB Light and the [RGB Matrix](feature_rgb_matrix) feature enabled, these keycodes will work for both features, at the same time. You can disable the keycode functionality by defining the `*_DISABLE_KEYCODES` option for the specific feature. +::: ## Configuration @@ -146,7 +152,9 @@ Use these defines to add or remove animations from the firmware. When you are ru |`RGBLIGHT_EFFECT_STATIC_GRADIENT` |*Not defined*|Enable static gradient mode. | |`RGBLIGHT_EFFECT_TWINKLE` |*Not defined*|Enable twinkle animation mode. | -!> `RGBLIGHT_ANIMATIONS` is being deprecated and animation modes should be explicitly defined. +::: warning +`RGBLIGHT_ANIMATIONS` is being deprecated and animation modes should be explicitly defined. +::: ### Effect and Animation Settings @@ -209,12 +217,14 @@ const uint8_t RGBLED_GRADIENT_RANGES[] PROGMEM = {255, 170, 127, 85, 64}; ## Lighting Layers -?> **Note:** Lighting Layers is an RGB Light feature, it will not work for RGB Matrix. See [RGB Matrix Indicators](feature_rgb_matrix.md#indicators) for details on how to do so. +::: tip +**Note:** Lighting Layers is an RGB Light feature, it will not work for RGB Matrix. See [RGB Matrix Indicators](feature_rgb_matrix#indicators) for details on how to do so. +::: By including `#define RGBLIGHT_LAYERS` in your `config.h` file you can enable lighting layers. These make it easy to use your underglow LEDs as status indicators to show which keyboard layer is currently active, or the state of caps lock, all without disrupting any animations. [Here's a video](https://youtu.be/uLGE1epbmdY) showing an example of what you can do. -### Defining Lighting Layers :id=defining-lighting-layers +### Defining Lighting Layers {#defining-lighting-layers} By default, 8 layers are possible. This can be expanded to as many as 32 by overriding the definition of `RGBLIGHT_MAX_LAYERS` in `config.h` (e.g. `#define RGBLIGHT_MAX_LAYERS 32`). Please note, if you use a split keyboard, you will need to flash both sides of the split after changing this. Also, increasing the maximum will increase the firmware size, and will slow sync on split keyboards. @@ -259,7 +269,7 @@ void keyboard_post_init_user(void) { ``` Note: For split keyboards with two controllers, both sides need to be flashed when updating the contents of rgblight_layers. -### Enabling and disabling lighting layers :id=enabling-lighting-layers +### Enabling and disabling lighting layers {#enabling-lighting-layers} Everything above just configured the definition of each lighting layer. We can now enable and disable the lighting layers whenever the state of the keyboard changes: @@ -282,7 +292,7 @@ layer_state_t layer_state_set_user(layer_state_t state) { } ``` -### Lighting layer blink :id=lighting-layer-blink +### Lighting layer blink {#lighting-layer-blink} By including `#define RGBLIGHT_LAYER_BLINK` in your `config.h` file you can turn a lighting layer on for a specified duration. Once the specified number of milliseconds has elapsed @@ -342,7 +352,9 @@ rgblight_unblink_layer(3); rgblight_blink_layer(2, 500); ``` -!> Lighting layers on split keyboards will require layer state synced to the slave half (e.g. `#define SPLIT_LAYER_STATE_ENABLE`). See [data sync options](feature_split_keyboard.md#data-sync-options) for more details. +::: warning +Lighting layers on split keyboards will require layer state synced to the slave half (e.g. `#define SPLIT_LAYER_STATE_ENABLE`). See [data sync options](feature_split_keyboard#data-sync-options) for more details. +::: ### Overriding RGB Lighting on/off status diff --git a/docs/feature_secure.md b/docs/feature_secure.md index eaa2b601ae..5ca9eed65f 100644 --- a/docs/feature_secure.md +++ b/docs/feature_secure.md @@ -2,7 +2,9 @@ The secure feature aims to prevent unwanted interaction without user intervention. -?> Secure does **not** currently implement encryption/decryption/etc and should not be a replacement where a strong hardware/software based solution is required. +::: tip +Secure does **not** currently implement encryption/decryption/etc and should not be a replacement where a strong hardware/software based solution is required. +::: ### Unlock sequence @@ -14,7 +16,7 @@ To unlock, the user must perform a set of actions. This can optionally be config ### Automatic Locking Once unlocked, the keyboard will revert back to a locked state after the configured timeout. -The timeout can be refreshed by using the `secure_activity_event` function, for example from one of the various [hooks](custom_quantum_functions.md). +The timeout can be refreshed by using the `secure_activity_event` function, for example from one of the various [hooks](custom_quantum_functions). ## Usage diff --git a/docs/feature_send_string.md b/docs/feature_send_string.md index 7d3f3ba32a..97e4ccc809 100644 --- a/docs/feature_send_string.md +++ b/docs/feature_send_string.md @@ -1,12 +1,14 @@ -# Send String :id=send-string +# Send String {#send-string} The Send String API is part of QMK's macro system. It allows for sequences of keystrokes to be sent automatically. The full ASCII character set is supported, along with all of the keycodes in the Basic Keycode range (as these are the only ones that will actually be sent to the host). -?> Unicode characters are **not** supported with this API -- see the [Unicode](feature_unicode.md) feature instead. +::: tip +Unicode characters are **not** supported with this API -- see the [Unicode](feature_unicode) feature instead. +::: -## Usage :id=usage +## Usage {#usage} Send String is enabled by default, so there is usually no need for any special setup. However, if it is disabled, add the following to your `rules.mk`: @@ -14,18 +16,18 @@ Send String is enabled by default, so there is usually no need for any special s SEND_STRING_ENABLE = yes ``` -## Basic Configuration :id=basic-configuration +## Basic Configuration {#basic-configuration} Add the following to your `config.h`: |Define |Default |Description | |-----------------|----------------|------------------------------------------------------------------------------------------------------------| -|`SENDSTRING_BELL`|*Not defined* |If the [Audio](feature_audio.md) feature is enabled, the `\a` character (ASCII `BEL`) will beep the speaker.| +|`SENDSTRING_BELL`|*Not defined* |If the [Audio](feature_audio) feature is enabled, the `\a` character (ASCII `BEL`) will beep the speaker.| |`BELL_SOUND` |`TERMINAL_SOUND`|The song to play when the `\a` character is encountered. By default, this is an eighth note of C5. | -## Keycodes :id=keycodes +## Keycodes {#keycodes} -The Send String functions accept C string literals, but specific keycodes can be injected with the below macros. All of the keycodes in the [Basic Keycode range](keycodes_basic.md) are supported (as these are the only ones that will actually be sent to the host), but with an `X_` prefix instead of `KC_`. +The Send String functions accept C string literals, but specific keycodes can be injected with the below macros. All of the keycodes in the [Basic Keycode range](keycodes_basic) are supported (as these are the only ones that will actually be sent to the host), but with an `X_` prefix instead of `KC_`. |Macro |Description | |--------------|-------------------------------------------------------------------| @@ -44,13 +46,13 @@ The following characters are also mapped to their respective keycodes for conven |`\t` |`\x1B`|`TAB`|`KC_TAB` | | |`\x7F`|`DEL`|`KC_DELETE` | -### Language Support :id=language-support +### Language Support {#language-support} -By default, Send String assumes your OS keyboard layout is set to US ANSI. If you are using a different keyboard layout, you can [override the lookup tables used to convert ASCII characters to keystrokes](reference_keymap_extras.md#sendstring-support). +By default, Send String assumes your OS keyboard layout is set to US ANSI. If you are using a different keyboard layout, you can [override the lookup tables used to convert ASCII characters to keystrokes](reference_keymap_extras#sendstring-support). -## Examples :id=examples +## Examples {#examples} -### Hello World :id=example-hello-world +### Hello World {#example-hello-world} A simple custom keycode which types out "Hello, world!" and the Enter key when pressed. @@ -70,7 +72,7 @@ bool process_record_user(uint16_t keycode, keyrecord_t *record) { } ``` -### Keycode Injection :id=example-keycode-injection +### Keycode Injection {#example-keycode-injection} This example types out opening and closing curly braces, then taps the left arrow key to move the cursor between the two. @@ -84,26 +86,26 @@ This example types Ctrl+A, then Ctrl+C, without releasing Ctrl. SEND_STRING(SS_LCTL("ac")); ``` -## API :id=api +## API {#api} -### `void send_string(const char *string)` :id=api-send-string +### `void send_string(const char *string)` {#api-send-string} Type out a string of ASCII characters. This function simply calls `send_string_with_delay(string, 0)`. -#### Arguments :id=api-send-string-arguments +#### Arguments {#api-send-string-arguments} - `const char *string` The string to type out. --- -### `void send_string_with_delay(const char *string, uint8_t interval)` :id=api-send-string-with-delay +### `void send_string_with_delay(const char *string, uint8_t interval)` {#api-send-string-with-delay} Type out a string of ASCII characters, with a delay between each character. -#### Arguments :id=api-send-string-with-delay-arguments +#### Arguments {#api-send-string-with-delay-arguments} - `const char *string` The string to type out. @@ -112,26 +114,26 @@ Type out a string of ASCII characters, with a delay between each character. --- -### `void send_string_P(const char *string)` :id=api-send-string-p +### `void send_string_P(const char *string)` {#api-send-string-p} Type out a PROGMEM string of ASCII characters. On ARM devices, this function is simply an alias for `send_string_with_delay(string, 0)`. -#### Arguments :id=api-send-string-p-arguments +#### Arguments {#api-send-string-p-arguments} - `const char *string` The string to type out. --- -### `void send_string_with_delay_P(const char *string, uint8_t interval)` :id=api-send-string-with-delay-p +### `void send_string_with_delay_P(const char *string, uint8_t interval)` {#api-send-string-with-delay-p} Type out a PROGMEM string of ASCII characters, with a delay between each character. On ARM devices, this function is simply an alias for `send_string_with_delay(string, interval)`. -#### Arguments :id=api-send-string-with-delay-p-arguments +#### Arguments {#api-send-string-with-delay-p-arguments} - `const char *string` The string to type out. @@ -140,76 +142,76 @@ On ARM devices, this function is simply an alias for `send_string_with_delay(str --- -### `void send_char(char ascii_code)` :id=api-send-char +### `void send_char(char ascii_code)` {#api-send-char} Type out an ASCII character. -#### Arguments :id=api-send-char-arguments +#### Arguments {#api-send-char-arguments} - `char ascii_code` The character to type. --- -### `void send_dword(uint32_t number)` :id=api-send-dword +### `void send_dword(uint32_t number)` {#api-send-dword} Type out an eight digit (unsigned 32-bit) hexadecimal value. The format is `[0-9a-f]{8}`, eg. `00000000` through `ffffffff`. -#### Arguments :id=api-send-dword-arguments +#### Arguments {#api-send-dword-arguments} - `uint32_t number` The value to type, from 0 to 4,294,967,295. --- -### `void send_word(uint16_t number)` :id=api-send-word +### `void send_word(uint16_t number)` {#api-send-word} Type out a four digit (unsigned 16-bit) hexadecimal value. The format is `[0-9a-f]{4}`, eg. `0000` through `ffff`. -#### Arguments :id=api-send-word-arguments +#### Arguments {#api-send-word-arguments} - `uint16_t number` The value to type, from 0 to 65,535. --- -### `void send_byte(uint8_t number)` :id=api-send-bytes +### `void send_byte(uint8_t number)` {#api-send-bytes} Type out a two digit (8-bit) hexadecimal value. The format is `[0-9a-f]{2}`, eg. `00` through `ff`. -#### Arguments :id=api-send-byte-arguments +#### Arguments {#api-send-byte-arguments} - `uint8_t number` The value to type, from 0 to 255. --- -### `void send_nibble(uint8_t number)` :id=api-send-nibble +### `void send_nibble(uint8_t number)` {#api-send-nibble} Type out a single hexadecimal digit. The format is `[0-9a-f]{1}`, eg. `0` through `f`. -#### Arguments :id=api-send-nibble-arguments +#### Arguments {#api-send-nibble-arguments} - `uint8_t number` The value to type, from 0 to 15. --- -### `void tap_random_base64(void)` :id=api-tap-random-base64 +### `void tap_random_base64(void)` {#api-tap-random-base64} Type a pseudorandom character from the set `A-Z`, `a-z`, `0-9`, `+` and `/`. --- -### `SEND_STRING(string)` :id=api-send-string-macro +### `SEND_STRING(string)` {#api-send-string-macro} Shortcut macro for `send_string_with_delay_P(PSTR(string), 0)`. @@ -217,7 +219,7 @@ On ARM devices, this define evaluates to `send_string_with_delay(string, 0)`. --- -### `SEND_STRING_DELAY(string, interval)` :id=api-send-string-delay-macro +### `SEND_STRING_DELAY(string, interval)` {#api-send-string-delay-macro} Shortcut macro for `send_string_with_delay_P(PSTR(string), interval)`. diff --git a/docs/feature_sequencer.md b/docs/feature_sequencer.md index 3af55197c5..c58b6225ca 100644 --- a/docs/feature_sequencer.md +++ b/docs/feature_sequencer.md @@ -2,7 +2,9 @@ Since QMK has experimental support for MIDI, you can now turn your keyboard into a [step sequencer](https://en.wikipedia.org/wiki/Music_sequencer#Step_sequencers)! -!> **IMPORTANT:** This feature is highly experimental, it has only been tested on a Planck EZ so far. Also, the scope will be limited to support the drum machine use-case to start with. +::: warning +**IMPORTANT:** This feature is highly experimental, it has only been tested on a Planck EZ so far. Also, the scope will be limited to support the drum machine use-case to start with. +::: ## Enable the step sequencer diff --git a/docs/feature_space_cadet.md b/docs/feature_space_cadet.md index 223a5b3ccf..cbb79e10ad 100644 --- a/docs/feature_space_cadet.md +++ b/docs/feature_space_cadet.md @@ -24,7 +24,7 @@ Firstly, in your keymap, do one of the following: ## Caveats -Space Cadet's functionality can conflict with the default Command functionality when both Shift keys are held at the same time. See the [Command feature](feature_command.md) for info on how to change it, or make sure that Command is disabled in your `rules.mk` with: +Space Cadet's functionality can conflict with the default Command functionality when both Shift keys are held at the same time. See the [Command feature](feature_command) for info on how to change it, or make sure that Command is disabled in your `rules.mk` with: ```make COMMAND_ENABLE = no diff --git a/docs/feature_split_keyboard.md b/docs/feature_split_keyboard.md index 99c252d03e..c39d0a7e08 100644 --- a/docs/feature_split_keyboard.md +++ b/docs/feature_split_keyboard.md @@ -8,20 +8,24 @@ QMK Firmware has a generic implementation that is usable by any board, as well a For this, we will mostly be talking about the generic implementation used by the Let's Split and other keyboards. -!> ARM split supports most QMK subsystems when using the 'serial' and 'serial_usart' drivers. I2C slave is currently unsupported. +::: warning +ARM split supports most QMK subsystems when using the 'serial' and 'serial_usart' drivers. I2C slave is currently unsupported. +::: -!> Both sides must use the same MCU family, for eg two Pro Micro-compatible controllers or two Blackpills. Currently, mixing AVR and ARM is not possible as ARM vs AVR uses different method for serial communication, and are not compatible. Moreover Blackpill's uses 3.3v logic, and atmega32u4 uses 5v logic. +::: warning +Both sides must use the same MCU family, for eg two Pro Micro-compatible controllers or two Blackpills. Currently, mixing AVR and ARM is not possible as ARM vs AVR uses different method for serial communication, and are not compatible. Moreover Blackpill's uses 3.3v logic, and atmega32u4 uses 5v logic. +::: ## Compatibility Overview | Transport | AVR | ARM | |------------------------------|--------------------|--------------------| -| ['serial'](serial_driver.md) | :heavy_check_mark: | :white_check_mark: 1 | +| ['serial'](serial_driver) | :heavy_check_mark: | :white_check_mark: 1 | | I2C | :heavy_check_mark: | | Notes: -1. Both hardware and software limitations are detailed within the [driver documentation](serial_driver.md). +1. Both hardware and software limitations are detailed within the [driver documentation](serial_driver). ## Hardware Configuration @@ -45,13 +49,17 @@ Another option is to use phone cables (as in, old school RJ-11/RJ-14 cables). Ma However, USB cables, SATA cables, and even just 4 wires have been known to be used for communication between the controllers. -!> Using USB cables for communication between the controllers works just fine, but the connector could be mistaken for a normal USB connection and potentially short out the keyboard, depending on how it's wired. For this reason, they are not recommended for connecting split keyboards. +::: warning +Using USB cables for communication between the controllers works just fine, but the connector could be mistaken for a normal USB connection and potentially short out the keyboard, depending on how it's wired. For this reason, they are not recommended for connecting split keyboards. +::: ### Serial Wiring The 3 wires of the TRS/TRRS cable need to connect GND, VCC, and D0/D1/D2/D3 (aka PD0/PD1/PD2/PD3) between the two Pro Micros. -?> Note that the pin used here is actually set by `SOFT_SERIAL_PIN` below. +::: tip +Note that the pin used here is actually set by `SOFT_SERIAL_PIN` below. +::: sk-pd0-connection-mono sk-pd2-connection-mono @@ -160,9 +168,13 @@ Reset the right controller and run: qmk flash -kb crkbd/rev1 -km default -bl avrdude-split-right ``` -?> Some controllers (e.g. Blackpill with DFU compatible bootloader) will need to be flashed with handedness bootloader parameter every time because it is not retained between flashes. +::: tip +Some controllers (e.g. Blackpill with DFU compatible bootloader) will need to be flashed with handedness bootloader parameter every time because it is not retained between flashes. +::: -?> [QMK Toolbox]() can also be used to flash EEPROM handedness files. Place the controller in bootloader mode and select menu option Tools -> EEPROM -> Set Left/Right Hand +::: tip +[QMK Toolbox]() can also be used to flash EEPROM handedness files. Place the controller in bootloader mode and select menu option Tools -> EEPROM -> Set Left/Right Hand +::: This setting is not changed when re-initializing the EEPROM using the `EE_CLR` key, or using the `eeconfig_init()` function. However, if you reset the EEPROM outside of the firmware's built in options (such as flashing a file that overwrites the `EEPROM`, like how the [QMK Toolbox]()'s "Reset EEPROM" button works), you'll need to re-flash the controller with the `EEPROM` files. @@ -183,7 +195,9 @@ If the USB cable is always connected to the left side, add the following to your #define MASTER_LEFT ``` -?> If neither options are defined, the handedness defaults to `MASTER_LEFT`. +::: tip +If neither options are defined, the handedness defaults to `MASTER_LEFT`. +::: ### Communication Options @@ -292,7 +306,9 @@ This enables transmitting the current ST7565 on/off status to the slave side of This enables transmitting the pointing device status to the master side of the split keyboard. The purpose of this feature is to enable use pointing devices on the slave side. -!> There is additional required configuration for `SPLIT_POINTING_ENABLE` outlined in the [pointing device documentation](feature_pointing_device.md?id=split-keyboard-configuration). +::: warning +There is additional required configuration for `SPLIT_POINTING_ENABLE` outlined in the [pointing device documentation](feature_pointing_device#split-keyboard-configuration). +::: ```c #define SPLIT_HAPTIC_ENABLE @@ -306,7 +322,7 @@ This enables the triggering of haptic feedback on the slave side of the split ke This synchronizes the activity timestamps between sides of the split keyboard, allowing for activity timeouts to occur. -### Custom data sync between sides :id=custom-data-sync +### Custom data sync between sides {#custom-data-sync} QMK's split transport allows for arbitrary data transactions at both the keyboard and user levels. This is modelled on a remote procedure call, with the master invoking a function on the slave side, with the ability to send data from master to slave, process it slave side, and send data back from slave to master. @@ -362,7 +378,9 @@ void housekeeping_task_user(void) { } ``` -!> It is recommended that any data sync between halves happens during the master side's _housekeeping task_. This ensures timely retries should failures occur. +::: warning +It is recommended that any data sync between halves happens during the master side's _housekeeping task_. This ensures timely retries should failures occur. +::: If only one-way data transfer is needed, helper methods are provided: @@ -381,7 +399,7 @@ By default, the inbound and outbound data is limited to a maximum of 32 bytes ea #define RPC_S2M_BUFFER_SIZE 48 ``` -### Hardware Configuration Options +### Hardware Configuration Options There are some settings that you may need to configure, based on how the hardware is set up. @@ -417,7 +435,9 @@ This option enables synchronization of the RGB Light modes between the controlle This sets how many LEDs are directly connected to each controller. The first number is the left side, and the second number is the right side. -?> This setting implies that `RGBLIGHT_SPLIT` is enabled, and will forcibly enable it, if it's not. +::: tip +This setting implies that `RGBLIGHT_SPLIT` is enabled, and will forcibly enable it, if it's not. +::: ```c @@ -430,7 +450,9 @@ Without this option, the master is the half that can detect voltage on the physi Enabled by default on ChibiOS/ARM. -?> This setting will stop the ability to demo using battery packs. +::: tip +This setting will stop the ability to demo using battery packs. +::: ```c #define SPLIT_USB_TIMEOUT 2000 diff --git a/docs/feature_stenography.md b/docs/feature_stenography.md index 5ca3ea945f..6827117a6b 100644 --- a/docs/feature_stenography.md +++ b/docs/feature_stenography.md @@ -1,10 +1,10 @@ -# Stenography in QMK :id=stenography-in-qmk +# Stenography in QMK {#stenography-in-qmk} [Stenography](https://en.wikipedia.org/wiki/Stenotype) is a method of writing most often used by court reports, closed-captioning, and real-time transcription for the deaf. In stenography words are chorded syllable by syllable with a mixture of spelling, phonetic, and shortcut (briefs) strokes. Professional stenographers can reach 200-300 WPM without any of the strain usually found in standard typing and with far fewer errors (>99.9% accuracy). The [Open Steno Project](https://www.openstenoproject.org/) has built an open-source program called Plover that provides real-time translation of steno strokes into words and commands. It has an established dictionary and supports -## Plover with QWERTY Keyboard :id=plover-with-qwerty-keyboard +## Plover with QWERTY Keyboard {#plover-with-qwerty-keyboard} Plover can work with any standard QWERTY keyboard, although it is more efficient if the keyboard supports NKRO (n-key rollover) to allow Plover to see all the pressed keys at once. An example keymap for Plover can be found in `planck/keymaps/default`. Switching to the `PLOVER` layer adjusts the position of the keyboard to support the number bar. @@ -12,7 +12,7 @@ To enable NKRO, add `NKRO_ENABLE = yes` in your `rules.mk` and make sure to pres You may also need to adjust your layout, either in QMK or in Plover, if you have anything other than a standard layout. You may also want to purchase some steno-friendly keycaps to make it easier to hit multiple keys. -## Plover with Steno Protocol :id=plover-with-steno-protocol +## Plover with Steno Protocol {#plover-with-steno-protocol} Plover also understands the language of several steno machines. QMK can speak a couple of these languages: TX Bolt and GeminiPR. An example layout can be found in `planck/keymaps/steno`. @@ -20,21 +20,25 @@ When QMK speaks to Plover over a steno protocol, Plover will not use the keyboar In this mode, Plover expects to speak with a steno machine over a serial port so QMK will present itself to the operating system as a virtual serial port in addition to a keyboard. -> Note: Due to hardware limitations, you might not be able to run both a virtual serial port and mouse emulation at the same time. +::: info +Note: Due to hardware limitations, you might not be able to run both a virtual serial port and mouse emulation at the same time. +::: -!> Serial stenography protocols are not supported on [V-USB keyboards](compatible_microcontrollers#atmel-avr). +::: warning +Serial stenography protocols are not supported on [V-USB keyboards](compatible_microcontrollers#atmel-avr). +::: To enable stenography protocols, add the following lines to your `rules.mk`: -```mk +```make STENO_ENABLE = yes ``` -### TX Bolt :id=tx-bolt +### TX Bolt {#tx-bolt} TX Bolt communicates the status of 24 keys over a simple protocol in variable-sized (1–4 bytes) packets. To select TX Bolt, add the following lines to your `rules.mk`: -```mk +```make STENO_ENABLE = yes STENO_PROTOCOL = txbolt ``` @@ -53,12 +57,12 @@ Examples of steno strokes and the associated packet: - `WAZ` = `00010000 01000010 11001000` - `PHAPBGS` = `00101000 01000010 10101100 11000010` -### GeminiPR :id=geminipr +### GeminiPR {#geminipr} GeminiPR encodes 42 keys into a 6-byte packet. While TX Bolt contains everything that is necessary for standard stenography, GeminiPR opens up many more options, including differentiating between top and bottom `S-`, and supporting non-English theories. To select GeminiPR, add the following lines to your `rules.mk`: -```mk +```make STENO_ENABLE = yes STENO_PROTOCOL = geminipr ``` @@ -80,12 +84,12 @@ Examples of steno strokes and the associated packet: - `WAZ` = `10000000 00000010 00100000 00000000 00000000 00000001` - `PHAPBGS` = `10000000 00000101 00100000 00000000 01101010 00000000` -### Switching protocols on the fly :id=switching-protocols-on-the-fly +### Switching protocols on the fly {#switching-protocols-on-the-fly} If you wish to switch the serial protocol used to transfer the steno chords without having to recompile your keyboard firmware every time, you can press the `QK_STENO_BOLT` and `QK_STENO_GEMINI` keycodes in order to switch protocols on the fly. To enable these special keycodes, add the following lines to your `rules.mk`: -```mk +```make STENO_ENABLE = yes STENO_PROTOCOL = all ``` @@ -98,11 +102,13 @@ Naturally, this option takes the most amount of firmware space as it needs to co The default value for `STENO_PROTOCOL` is `all`. -## Configuring QMK for Steno :id=configuring-qmk-for-steno +## Configuring QMK for Steno {#configuring-qmk-for-steno} After enabling stenography and optionally selecting a protocol, you may also need disable mouse keys, extra keys, or another USB endpoint to prevent conflicts. The builtin USB stack for some processors only supports a certain number of USB endpoints and the virtual serial port needed for steno fills 3 of them. -!> If you had *explicitly* set `VIRSTER_ENABLE = no`, none of the serial stenography protocols (GeminiPR, TX Bolt) will work properly. You are expected to either set it to `yes`, remove the line from your `rules.mk` or send the steno chords yourself in an alternative way using the [provided interceptable hooks](#interfacing-with-the-code). +::: warning +If you had *explicitly* set `VIRSTER_ENABLE = no`, none of the serial stenography protocols (GeminiPR, TX Bolt) will work properly. You are expected to either set it to `yes`, remove the line from your `rules.mk` or send the steno chords yourself in an alternative way using the [provided interceptable hooks](#interfacing-with-the-code). +::: In your keymap, create a new layer for Plover, that you can fill in with the [steno keycodes](#keycode-reference). Remember to create a key to switch to the layer as well as a key for exiting the layer. @@ -110,13 +116,13 @@ Once you have your keyboard flashed, launch Plover. Click the 'Configure...' but To test your keymap, you can chord keys on your keyboard and either look at the output of the 'paper tape' (Tools > Paper Tape) or that of the 'layout display' (Tools > Layout Display). If your strokes correctly show up, you are now ready to steno! -## Learning Stenography :id=learning-stenography +## Learning Stenography {#learning-stenography} * [Learn Plover!](https://sites.google.com/site/learnplover/) * [Steno Jig](https://joshuagrams.github.io/steno-jig/) * More resources at the Plover [Learning Stenography](https://github.com/openstenoproject/plover/wiki/Learning-Stenography) wiki -## Interfacing with the code :id=interfacing-with-the-code +## Interfacing with the code {#interfacing-with-the-code} The steno code has three interceptable hooks. If you define these functions, they will be called at certain points in processing; if they return true, processing continues, otherwise it's assumed you handled things. @@ -147,9 +153,11 @@ This is not always equal to the number of bits set to 1 (aka the [Hamming weight At the end of this scenario given as an example, `chord` would have five bits set to 1 but `n_pressed_keys` would be set to 2 because there are only two keys currently being pressed down. -## Keycode Reference :id=keycode-reference +## Keycode Reference {#keycode-reference} -> Note: TX Bolt does not support the full set of keys. The TX Bolt implementation in QMK will map the GeminiPR keys to the nearest TX Bolt key so that one key map will work for both. +::: info +Note: TX Bolt does not support the full set of keys. The TX Bolt implementation in QMK will map the GeminiPR keys to the nearest TX Bolt key so that one key map will work for both. +::: |GeminiPR|TX Bolt|Steno Key| |--------|-------|-----------| diff --git a/docs/feature_swap_hands.md b/docs/feature_swap_hands.md index e9c1d4b7ba..7546823d84 100644 --- a/docs/feature_swap_hands.md +++ b/docs/feature_swap_hands.md @@ -30,7 +30,7 @@ Note that the array indices are reversed same as the matrix and the values are o |`QK_SWAP_HANDS_TAP_TOGGLE` |`SH_TT` |Momentary swap when held, toggle when tapped | |`QK_SWAP_HANDS_ONE_SHOT` |`SH_OS` |Turn on hand swap while held or until next key press| -`SH_TT` swap-hands tap-toggle key is similar to [layer tap-toggle](feature_layers.md?id=switching-and-toggling-layers). Tapping repeatedly (5 taps by default) will toggle swap-hands on or off, like `SH_TOGG`. Tap-toggle count can be changed by defining a value for `TAPPING_TOGGLE`. +`SH_TT` swap-hands tap-toggle key is similar to [layer tap-toggle](feature_layers#switching-and-toggling-layers). Tapping repeatedly (5 taps by default) will toggle swap-hands on or off, like `SH_TOGG`. Tap-toggle count can be changed by defining a value for `TAPPING_TOGGLE`. ## Encoder Mapping @@ -45,7 +45,7 @@ const uint8_t PROGMEM encoder_hand_swap_config[NUM_ENCODERS] = { 1, 0 }; #endif ``` -### Functions :id=functions +### Functions {#functions} User callback functions to manipulate Swap-Hands: diff --git a/docs/feature_tap_dance.md b/docs/feature_tap_dance.md index bb1c2c8034..e43daf4196 100644 --- a/docs/feature_tap_dance.md +++ b/docs/feature_tap_dance.md @@ -1,12 +1,12 @@ # Tap Dance: A Single Key Can Do 3, 5, or 100 Different Things -## Introduction :id=introduction +## Introduction {#introduction} Hit the semicolon key once, send a semicolon. Hit it twice, rapidly -- send a colon. Hit it three times, and your keyboard's LEDs do a wild dance. That's just one example of what Tap Dance can do. It's one of the nicest community-contributed features in the firmware, conceived and created by [algernon](https://github.com/algernon) in [#451](https://github.com/qmk/qmk_firmware/pull/451). Here's how algernon describes the feature: With this feature one can specify keys that behave differently, based on the amount of times they have been tapped, and when interrupted, they get handled before the interrupter. -## How to Use Tap Dance :id=how-to-use +## How to Use Tap Dance {#how-to-use} First, you will need `TAP_DANCE_ENABLE = yes` in your `rules.mk`, because the feature is disabled by default. This adds a little less than 1k to the firmware size. @@ -17,7 +17,7 @@ Optionally, you might want to set a custom `TAPPING_TERM` time by adding somethi #define TAPPING_TERM_PER_KEY ``` -The `TAPPING_TERM` time is the maximum time allowed between taps of your Tap Dance key, and is measured in milliseconds. For example, if you used the above `#define` statement and set up a Tap Dance key that sends `Space` on single-tap and `Enter` on double-tap, then this key will send `ENT` only if you tap this key twice in less than 175ms. If you tap the key, wait more than 175ms, and tap the key again you'll end up sending `SPC SPC` instead. The `TAPPING_TERM_PER_KEY` definition is only needed if you control the tapping term through a [custom `get_tapping_term` function](tap_hold.md#tapping_term), which may be needed because `TAPPING_TERM` affects not just tap-dance keys. +The `TAPPING_TERM` time is the maximum time allowed between taps of your Tap Dance key, and is measured in milliseconds. For example, if you used the above `#define` statement and set up a Tap Dance key that sends `Space` on single-tap and `Enter` on double-tap, then this key will send `ENT` only if you tap this key twice in less than 175ms. If you tap the key, wait more than 175ms, and tap the key again you'll end up sending `SPC SPC` instead. The `TAPPING_TERM_PER_KEY` definition is only needed if you control the tapping term through a [custom `get_tapping_term` function](tap_hold#tapping_term), which may be needed because `TAPPING_TERM` affects not just tap-dance keys. Next, you will want to define some tap-dance keys, which is easiest to do with the `TD()` macro. That macro takes a number which will later be used as an index into the `tap_dance_actions` array and turns it into a tap-dance keycode. @@ -32,13 +32,15 @@ After this, you'll want to use the `tap_dance_actions` array to specify what act The first option is enough for a lot of cases, that just want dual roles. For example, `ACTION_TAP_DANCE_DOUBLE(KC_SPC, KC_ENT)` will result in `Space` being sent on single-tap, `Enter` otherwise. -!> Keep in mind that only [basic keycodes](keycodes_basic.md) are supported here. Custom keycodes are not supported. +::: warning +Keep in mind that only [basic keycodes](keycodes_basic) are supported here. Custom keycodes are not supported. +::: Similar to the first option, the second and third option are good for simple layer-switching cases. For more complicated cases, like blink the LEDs, fiddle with the backlighting, and so on, use the fourth or fifth option. Examples of each are listed below. -## Implementation Details :id=implementation +## Implementation Details {#implementation} Well, that's the bulk of it! You should now be able to work through the examples below, and to develop your own Tap Dance functionality. But if you want a deeper understanding of what's going on behind the scenes, then read on for the explanation of how it all works! @@ -48,9 +50,9 @@ To accomplish this logic, the tap dance mechanics use three entry points. The ma This means that you have `TAPPING_TERM` time to tap the key again; you do not have to input all the taps within a single `TAPPING_TERM` timeframe. This allows for longer tap counts, with minimal impact on responsiveness. -## Examples :id=examples +## Examples {#examples} -### Simple Example: Send `ESC` on Single Tap, `CAPS_LOCK` on Double Tap :id=simple-example +### Simple Example: Send `ESC` on Single Tap, `CAPS_LOCK` on Double Tap {#simple-example} Here's a simple example for a single definition: @@ -77,7 +79,7 @@ const uint16_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] = { }; ``` -### Complex Examples :id=complex-examples +### Complex Examples {#complex-examples} This section details several complex tap dance examples. All the enums used in the examples are declared like this: @@ -93,7 +95,7 @@ enum { }; ``` -#### Example 1: Send "Safety Dance!" After 100 Taps :id=example-1 +#### Example 1: Send "Safety Dance!" After 100 Taps {#example-1} ```c void dance_egg(tap_dance_state_t *state, void *user_data) { @@ -108,7 +110,7 @@ tap_dance_action_t tap_dance_actions[] = { }; ``` -#### Example 2: Turn LED Lights On Then Off, One at a Time :id=example-2 +#### Example 2: Turn LED Lights On Then Off, One at a Time {#example-2} ```c // On each tap, light up one LED, from right to left @@ -157,7 +159,7 @@ tap_dance_action_t tap_dance_actions[] = { }; ``` -#### Example 3: Send `:` on Tap, `;` on Hold :id=example-3 +#### Example 3: Send `:` on Tap, `;` on Hold {#example-3} With a little effort, powerful tap-hold configurations can be implemented as tap dances. To emit taps as early as possible, we need to act on releases of the tap dance key. There is no callback for this in the tap dance framework, so we use `process_record_user()`. @@ -217,7 +219,7 @@ tap_dance_action_t tap_dance_actions[] = { }; ``` -#### Example 4: 'Quad Function Tap-Dance' :id=example-4 +#### Example 4: 'Quad Function Tap-Dance' {#example-4} By [DanielGGordon](https://github.com/danielggordon) @@ -356,9 +358,11 @@ tap_dance_action_t tap_dance_actions[] = { And then simply use `TD(X_CTL)` anywhere in your keymap. -> In this configuration "hold" takes place **after** tap dance timeout. 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`). +::: info +In this configuration "hold" takes place **after** tap dance timeout. To achieve instant hold, remove `state->interrupted` checks in conditions. As a result you may use comfortable longer tapping periods to have more time for taps and not to wait too long for holds (try starting with doubled `TAPPING_TERM`). +::: -#### Example 5: Using tap dance for advanced mod-tap and layer-tap keys :id=example-5 +#### Example 5: Using tap dance for advanced mod-tap and layer-tap keys {#example-5} Tap dance can be used to emulate `MT()` and `LT()` behavior when the tapped code is not a basic keycode. This is useful to send tapped keycodes that normally require `Shift`, such as parentheses or curly braces—or other modified keycodes, such as `Control + X`. @@ -450,7 +454,7 @@ tap_dance_action_t tap_dance_actions[] = { Wrap each tapdance keycode in `TD()` when including it in your keymap, e.g. `TD(ALT_LP)`. -#### Example 6: Using tap dance for momentary-layer-switch and layer-toggle keys :id=example-6 +#### Example 6: Using tap dance for momentary-layer-switch and layer-toggle keys {#example-6} Tap Dance can be used to mimic MO(layer) and TG(layer) functionality. For this example, we will set up a key to function as `KC_QUOT` on single-tap, as `MO(_MY_LAYER)` on single-hold, and `TG(_MY_LAYER)` on double-tap. diff --git a/docs/feature_tri_layer.md b/docs/feature_tri_layer.md index 3087fb5a55..a67ec97a89 100644 --- a/docs/feature_tri_layer.md +++ b/docs/feature_tri_layer.md @@ -1,4 +1,4 @@ -# Tri Layers :id=tri-layers +# Tri Layers {#tri-layers} This enables support for the OLKB style "Tri Layer" keycodes. These function similar to the `MO` (momentary) function key, but if both the "Lower" and "Upper" keys are pressed, it activates a third "Adjust" layer. To enable this functionality, add this line to your `rules.mk`: @@ -8,9 +8,9 @@ TRI_LAYER_ENABLE = yes Note that the "upper", "lower" and "adjust" names don't have a particular significance, they are just used to identify and clarify the behavior. Layers are processed from highest numeric value to lowest, however the values are not required to be consecutive. -For a detailed explanation of how the layer stack works, check out [Keymap Overview](keymap.md#keymap-and-layers). +For a detailed explanation of how the layer stack works, check out [Keymap Overview](keymap#keymap-and-layers). -## Keycodes :id=keycodes +## Keycodes {#keycodes} | Keycode | Alias | Description | |----------------------|-----------|---------------------------------------------------------------------------------------------------------| @@ -45,4 +45,6 @@ Eg, if you wanted to set the "Adjust" layer to be layer 5, you'd add this to you | `get_tri_layer_upper_layer()` | Gets the current "upper" layer. | | `get_tri_layer_adjust_layer()` | Gets the current "adjust" layer. | -!> Note: these settings are not persistent, and will be reset to the default on power loss or power cycling of the controller. +::: warning +Note: these settings are not persistent, and will be reset to the default on power loss or power cycling of the controller. +::: diff --git a/docs/feature_unicode.md b/docs/feature_unicode.md index 2c6d2ef002..aa5a064e20 100644 --- a/docs/feature_unicode.md +++ b/docs/feature_unicode.md @@ -1,12 +1,12 @@ -# Unicode :id=unicode +# Unicode {#unicode} With a little help from your OS, practically any Unicode character can be input using your keyboard. -## Caveats :id=caveats +## Caveats {#caveats} There are some limitations to this feature. Because there is no "standard" method of Unicode input across all operating systems, each of them require their own setup process on both the host *and* in the firmware, which may involve installation of additional software. This also means Unicode input will not "just work" when the keyboard is plugged into another device. -## Usage :id=usage +## Usage {#usage} The core Unicode API can be used purely programmatically. However, there are also additional subsystems which build on top of it and come with keycodes to make things easier. See below for more details. @@ -16,7 +16,7 @@ Add the following to your keymap's `rules.mk`: UNICODE_COMMON = yes ``` -## Basic Configuration :id=basic-configuration +## Basic Configuration {#basic-configuration} Add the following to your `config.h`: @@ -29,9 +29,9 @@ Add the following to your `config.h`: |`UNICODE_CYCLE_PERSIST` |`true` |Whether to persist the current Unicode input mode to EEPROM | |`UNICODE_TYPE_DELAY` |`10` |The amount of time to wait, in milliseconds, between Unicode sequence keystrokes| -### Audio Feedback :id=audio-feedback +### Audio Feedback {#audio-feedback} -If you have the [Audio](feature_audio.md) feature enabled on your board, you can configure it to play sounds when the input mode is changed. +If you have the [Audio](feature_audio) feature enabled on your board, you can configure it to play sounds when the input mode is changed. Add the following to your `config.h`: @@ -43,13 +43,13 @@ Add the following to your `config.h`: |`UNICODE_SONG_WIN` |*n/a* |The song to play when the Windows input mode is selected | |`UNICODE_SONG_WINC`|*n/a* |The song to play when the WinCompose input mode is selected| -## Input Subsystems :id=input-subsystems +## Input Subsystems {#input-subsystems} Each of these subsystems have their own pros and cons in terms of flexibility and ease of use. Choose the one that best fits your needs. - +::::tabs -### ** Basic ** +=== Basic This is the easiest to use, albeit somewhat limited. It supports code points up to `U+7FFF`, which covers characters for most modern languages (including East Asian), as well as many symbols, but does not include emoji. @@ -61,7 +61,7 @@ UNICODE_ENABLE = yes You can then add `UC(c)` keycodes to your keymap, where *c* is the code point of the desired character (in hexadecimal - the `U+` prefix will not work). For example, `UC(0x40B)` will output [Ћ](https://unicode-table.com/en/040B/), and `UC(0x30C4)` will output [ツ](https://unicode-table.com/en/30C4). -### ** Unicode Map ** +=== Unicode Map Unicode Map supports all possible code points (up to `U+10FFFF`). Here, the code points are stored in a separate mapping table (which may contain at most 16,384 entries), instead of directly in the keymap. @@ -89,7 +89,7 @@ const uint32_t PROGMEM unicode_map[] = { Finally, add `UM(i)` keycodes to your keymap, where *i* is an index into the `unicode_map[]` array. If you defined the enum above, you can use those names instead, for example `UM(BANG)` or `UM(SNEK)`. -#### Lower and Upper Case Pairs :id=unicodemap-pairs +#### Lower and Upper Case Pairs {#unicodemap-pairs} Some writing systems have lowercase and uppercase variants of each character, such as å and Å. To make inputting these characters easier, you can use the `UP(i, j)` keycode in your keymap, where *i* and *j* are the mapping table indices of the lowercase and uppercase characters, respectively. If you're holding down Shift or have Caps Lock turned on when you press the key, the uppercase character will be inserted; otherwise, the lowercase character will be inserted. @@ -104,7 +104,7 @@ This is most useful when creating a keymap for an international layout with spec Due to keycode size constraints, *i* and *j* can each only refer to one of the first 128 characters in your `unicode_map`. In other words, 0 ≤ *i* ≤ 127 and 0 ≤ *j* ≤ 127. -### ** UCIS ** +=== UCIS As with Unicode Map, the UCIS method also supports all possible code points, and requires the use of a mapping table. However, it works much differently - Unicode characters are input by replacing a typed mnemonic. @@ -129,9 +129,9 @@ By default, each table entry may be up to three code points long. This can be ch To invoke UCIS input, the `ucis_start()` function must first be called (for example, in a custom "Unicode" keycode). Then, type the mnemonic for the mapping table entry (such as "rofl"), and hit Space or Enter. The "rofl" text will be backspaced and the emoji inserted. - +:::: -## Input Modes :id=input-modes +## Input Modes {#input-modes} Unicode input works by typing a sequence of characters, similar to a macro. However, since this sequence depends on your OS, you will need to prepare both your host machine and QMK to recognise and send the correct Unicode input sequences respectively. @@ -147,9 +147,9 @@ These modes can then be cycled through using the `UC_NEXT` and `UC_PREV` keycode If your keyboard has working EEPROM, it will remember the last used input mode and continue using it on the next power up. This can be disabled by defining `UNICODE_CYCLE_PERSIST` to `false`. - +:::::tabs -### ** macOS ** +==== macOS **Mode Name:** `UNICODE_MODE_MACOS` @@ -157,7 +157,7 @@ macOS has built-in support for Unicode input as its own input source. It support To enable, go to **System Preferences → Keyboard → Input Sources**, then add Unicode Hex Input to the list (under Other), and activate it from the input dropdown in the menu bar. Note that this may disable some Option-based shortcuts such as Option+Left and Option+Right. -### ** Linux (IBus) ** +==== Linux (IBus) **Mode Name:** `UNICODE_MODE_LINUX` @@ -165,7 +165,7 @@ For Linux distros with IBus, Unicode input is enabled by default, supports all p Users who would like support in non-GTK apps without IBus may need to resort to a more indirect method, such as creating a custom keyboard layout. -### ** Windows (WinCompose) ** +==== Windows (WinCompose) **Mode Name:** `UNICODE_MODE_WINCOMPOSE` @@ -173,11 +173,13 @@ This mode requires a third-party tool called [WinCompose](https://github.com/sam To enable, install the [latest release from GitHub](https://github.com/samhocevar/wincompose/releases/latest). Once installed, it will automatically run on startup. This works reliably under all versions of Windows supported by WinCompose. -### ** Windows (HexNumpad) ** +==== Windows (HexNumpad) **Mode Name:** `UNICODE_MODE_WINDOWS` -!> This input mode is *not* the "Alt code" system. Alt codes are not Unicode; they instead follow [the Windows-1252 character set](https://en.wikipedia.org/wiki/Alt_code). +::: warning +This input mode is *not* the "Alt code" system. Alt codes are not Unicode; they instead follow [the Windows-1252 character set](https://en.wikipedia.org/wiki/Alt_code). +::: This is Windows' built-in hex numpad Unicode input mode. It only supports code points up to `U+FFFF`, and is not recommended due to reliability and compatibility issues. @@ -187,21 +189,21 @@ To enable, run the following as an administrator, then reboot: reg add "HKCU\Control Panel\Input Method" -v EnableHexNumpad -t REG_SZ -d 1 ``` -### ** Emacs ** +==== Emacs **Mode Name:** `UNICODE_MODE_EMACS` Emacs supports code point input with the `insert-char` command. -### ** BSD ** +==== BSD **Mode Name:** `UNICODE_MODE_BSD` -Not currently implemented. If you're a BSD user and want to contribute support for this input mode, please [feel free](contributing.md)! +Not currently implemented. If you're a BSD user and want to contribute support for this input mode, please [feel free](contributing)! - +::::: -## Keycodes :id=keycodes +## Keycodes {#keycodes} |Key |Aliases |Description | |----------------------------|---------|----------------------------------------------------------------| @@ -217,64 +219,64 @@ Not currently implemented. If you're a BSD user and want to contribute support f |`QK_UNICODE_MODE_WINCOMPOSE`|`UC_WINC`|Switch to Windows input using WinCompose | |`QK_UNICODE_MODE_EMACS` |`UC_EMAC`|Switch to emacs (`C-x-8 RET`) | -## API :id=api +## API {#api} -### `uint8_t get_unicode_input_mode(void)` :id=api-get-unicode-input-mode +### `uint8_t get_unicode_input_mode(void)` {#api-get-unicode-input-mode} Get the current Unicode input mode. -#### Return Value :id=api-get-unicode-input-mode-return-value +#### Return Value {#api-get-unicode-input-mode-return-value} The currently active Unicode input mode. --- -### `void set_unicode_input_mode(uint8_t mode)` :id=api-set-unicode-input-mode +### `void set_unicode_input_mode(uint8_t mode)` {#api-set-unicode-input-mode} Set the Unicode input mode. -#### Arguments :id=api-set-unicode-input-mode-arguments +#### Arguments {#api-set-unicode-input-mode-arguments} - `uint8_t mode` The input mode to set. --- -### `void unicode_input_mode_step(void)` : id=api-unicode-input-mode-step +### `void unicode_input_mode_step(void)` : {#api-unicode-input-mode-step} Change to the next Unicode input mode. --- -### `void unicode_input_mode_step_reverse(void)` : id=api-unicode-input-mode-step-reverse +### `void unicode_input_mode_step_reverse(void)` : {#api-unicode-input-mode-step-reverse} Change to the previous Unicode input mode. --- -### `void unicode_input_mode_set_user(uint8_t input_mode)` :id=api-unicode-input-mode-set-user +### `void unicode_input_mode_set_user(uint8_t input_mode)` {#api-unicode-input-mode-set-user} User-level callback, invoked when the input mode is changed. -#### Arguments :id=api-unicode-input-mode-set-user-arguments +#### Arguments {#api-unicode-input-mode-set-user-arguments} - `uint8_t input_mode` The new input mode. --- -### `void unicode_input_mode_set_kb(uint8_t input_mode)` :id=api-unicode-input-mode-set-kb +### `void unicode_input_mode_set_kb(uint8_t input_mode)` {#api-unicode-input-mode-set-kb} Keyboard-level callback, invoked when the input mode is changed. -#### Arguments :id=api-unicode-input-mode-set-kb-arguments +#### Arguments {#api-unicode-input-mode-set-kb-arguments} - `uint8_t input_mode` The new input mode. --- -### `void unicode_input_start(void)` :id=api-unicode-input-start +### `void unicode_input_start(void)` {#api-unicode-input-start} Begin the Unicode input sequence. The exact behavior depends on the currently selected input mode: @@ -288,7 +290,7 @@ This function is weakly defined, and can be overridden in user code. --- -### `void unicode_input_finish(void)` :id=api-unicode-input-finish +### `void unicode_input_finish(void)` {#api-unicode-input-finish} Complete the Unicode input sequence. The exact behavior depends on the currently selected input mode: @@ -302,7 +304,7 @@ This function is weakly defined, and can be overridden in user code. --- -### `void unicode_input_cancel(void)` :id=api-unicode-input-cancel +### `void unicode_input_cancel(void)` {#api-unicode-input-cancel} Cancel the Unicode input sequence. The exact behavior depends on the currently selected input mode: @@ -316,137 +318,137 @@ This function is weakly defined, and can be overridden in user code. --- -### `void register_unicode(uint32_t code_point)` :id=api-register-unicode +### `void register_unicode(uint32_t code_point)` {#api-register-unicode} Input a single Unicode character. A surrogate pair will be sent if required by the input mode. -#### Arguments :id=api-register-unicode-arguments +#### Arguments {#api-register-unicode-arguments} - `uint32_t code_point` The code point of the character to send. --- -### `void send_unicode_string(const char *str)` :id=api-send-unicode-string +### `void send_unicode_string(const char *str)` {#api-send-unicode-string} Send a string containing Unicode characters. -#### Arguments :id=api-send-unicode-string-arguments +#### Arguments {#api-send-unicode-string-arguments} - `const char *str` The string to send. --- -### `uint8_t unicodemap_index(uint16_t keycode)` :id=api-unicodemap-index +### `uint8_t unicodemap_index(uint16_t keycode)` {#api-unicodemap-index} Get the index into the `unicode_map` array for the given keycode, respecting shift state for pair keycodes. -#### Arguments :id=api-unicodemap-index-arguments +#### Arguments {#api-unicodemap-index-arguments} - `uint16_t keycode` The Unicode Map keycode to get the index of. -#### Return Value :id=api-unicodemap-index-return-value +#### Return Value {#api-unicodemap-index-return-value} An index into the `unicode_map` array. --- -### `uint32_t unicodemap_get_code_point(uint8_t index)` :id=api-unicodemap-get-code-point +### `uint32_t unicodemap_get_code_point(uint8_t index)` {#api-unicodemap-get-code-point} Get the code point for the given index in the `unicode_map` array. -#### Arguments :id=unicodemap-get-code-point-arguments +#### Arguments {#unicodemap-get-code-point-arguments} - `uint8_t index` The index into the `unicode_map` array. -#### Return Value :id=unicodemap-get-code-point-return-value +#### Return Value {#unicodemap-get-code-point-return-value} A Unicode code point value. --- -### `void register_unicodemap(uint8_t index)` :id=api-register-unicodemap +### `void register_unicodemap(uint8_t index)` {#api-register-unicodemap} Send the code point for the given index in the `unicode_map` array. -#### Arguments :id=api-register-unicodemap-arguments +#### Arguments {#api-register-unicodemap-arguments} - `uint8_t index` The index into the `unicode_map` array. --- -### `void ucis_start(void)` :id=api-ucis-start +### `void ucis_start(void)` {#api-ucis-start} Begin the input sequence. --- -### `bool ucis_active(void)` :id=api-ucis-active +### `bool ucis_active(void)` {#api-ucis-active} Whether UCIS is currently active. -#### Return Value :id=api-ucis-active-return-value +#### Return Value {#api-ucis-active-return-value} `true` if UCIS is active. --- -### `uint8_t ucis_count(void)` :id=api-ucis-count +### `uint8_t ucis_count(void)` {#api-ucis-count} Get the number of characters in the input sequence buffer. -#### Return Value :id=api-ucis-count-return-value +#### Return Value {#api-ucis-count-return-value} The current input sequence buffer length. --- -### `bool ucis_add(uint16_t keycode)` :id=api-ucis-add +### `bool ucis_add(uint16_t keycode)` {#api-ucis-add} Add the given keycode to the input sequence buffer. -#### Arguments :id=api-ucis-add-arguments +#### Arguments {#api-ucis-add-arguments} - `uint16_t keycode` The keycode to add. Must be between `KC_A` and `KC_Z`, or `KC_1` and `KC_0`. -#### Return Value :id=api-ucis-add-return-value +#### Return Value {#api-ucis-add-return-value} `true` if the keycode was added. --- -### `bool ucis_remove_last(void)` :id=api-ucis-remove-last +### `bool ucis_remove_last(void)` {#api-ucis-remove-last} Remove the last character from the input sequence buffer. -#### Return Value :id=api-ucis-remove-last +#### Return Value {#api-ucis-remove-last-return-value} `true` if the sequence was not empty. --- -### `void ucis_finish(void)` :id=api-ucis-finish +### `void ucis_finish(void)` {#api-ucis-finish} Mark the input sequence as complete, and attempt to match. --- -### `void ucis_cancel(void)` :id=api-ucis-cancel +### `void ucis_cancel(void)` {#api-ucis-cancel} Cancel the input sequence. --- -### `void register_ucis(void)` :id=api-register-ucis +### `void register_ucis(void)` {#api-register-ucis} Send the code point(s) for the given UCIS index. -#### Arguments :id=api-register-ucis-arguments +#### Arguments {#api-register-ucis-arguments} - `uint8_t index` The index into the UCIS symbol table. diff --git a/docs/feature_userspace.md b/docs/feature_userspace.md index aabf18e393..1e7c3b37cd 100644 --- a/docs/feature_userspace.md +++ b/docs/feature_userspace.md @@ -1,6 +1,8 @@ # Userspace: Sharing Code Between Keymaps -!> Please note, userspace submissions to the upstream `qmk/qmk_firmware` repository are no longer being accepted. The userspace feature itself remains functional and can be configured locally. +::: warning +Please note, userspace submissions to the upstream `qmk/qmk_firmware` repository are no longer being accepted. The userspace feature itself remains functional and can be configured locally. +::: If you use more than one keyboard with a similar keymap, you might see the benefit in being able to share code between them. Create your own folder in `users/` named the same as your keymap (ideally your GitHub username, ``) with the following structure: @@ -24,7 +26,9 @@ For example, Will include the `/users/jack/` folder in the path, along with `/users/jack/rules.mk`. -!> This `name` can be [overridden](#override-default-userspace), if needed. +::: warning +This `name` can be [overridden](#override-default-userspace), if needed. +::: ## `Rules.mk` @@ -56,7 +60,7 @@ endif ### Override default userspace -By default the userspace used will be the same as the keymap name. In some situations this isn't desirable. For instance, if you use the [layout](feature_layouts.md) feature you can't use the same name for different keymaps (e.g. ANSI and ISO). You can name your layouts `mylayout-ansi` and `mylayout-iso` and add the following line to your layout's `rules.mk`: +By default the userspace used will be the same as the keymap name. In some situations this isn't desirable. For instance, if you use the [layout](feature_layouts) feature you can't use the same name for different keymaps (e.g. ANSI and ISO). You can name your layouts `mylayout-ansi` and `mylayout-iso` and add the following line to your layout's `rules.mk`: ``` USER_NAME := mylayout @@ -70,7 +74,7 @@ Additionally, `config.h` here will be processed like the same file in your keyma The reason for this, is that `.h` won't be added in time to add settings (such as `#define TAPPING_TERM 100`), and including the `` file in any `config.h` files will result in compile issues. -!>You should use the `config.h` for [configuration options](config_options.md), and the `.h` file for user or keymap specific settings (such as the enum for layer or keycodes) +!>You should use the `config.h` for [configuration options](config_options), and the `.h` file for user or keymap specific settings (such as the enum for layer or keycodes) ## Readme (`readme.md`) @@ -119,12 +123,12 @@ For a more complicated example, checkout [`/users/drashna/`](https://github.com/ ### Customized Functions -QMK has a bunch of [functions](custom_quantum_functions.md) that have [`_quantum`, `_kb`, and `_user` versions](custom_quantum_functions.md#a-word-on-core-vs-keyboards-vs-keymap) that you can use. You will pretty much always want to use the user version of these functions. But the problem is that if you use them in your userspace, then you don't have a version that you can use in your keymap. +QMK has a bunch of [functions](custom_quantum_functions) that have [`_quantum`, `_kb`, and `_user` versions](custom_quantum_functions#a-word-on-core-vs-keyboards-vs-keymap) that you can use. You will pretty much always want to use the user version of these functions. But the problem is that if you use them in your userspace, then you don't have a version that you can use in your keymap. However, you can actually add support for keymap version, so that you can use it in both your userspace and your keymap! -For instance, let's look at the `layer_state_set_user()` function. You can enable the [Tri Layer State](ref_functions.md#olkb-tri-layers) functionality on all of your boards, while also retaining the Tri Layer functionality in your `keymap.c` files. +For instance, let's look at the `layer_state_set_user()` function. You can enable the [Tri Layer State](ref_functions#olkb-tri-layers) functionality on all of your boards, while also retaining the Tri Layer functionality in your `keymap.c` files. In your `` file, you'd want to add this: ```c @@ -254,4 +258,6 @@ Also, holding Shift will add the flash target (`:flash`) to the command. Holdin And for the boards that lack a shift key, or that you want to always attempt the flashing part, you can add `FLASH_BOOTLOADER = yes` to the `rules.mk` of that keymap. -?> This should flash the newly compiled firmware automatically, using the correct utility, based on the bootloader settings (or default to just generating the HEX file). However, it should be noted that this may not work on all systems. AVRDUDE doesn't work on WSL, namely. +::: tip +This should flash the newly compiled firmware automatically, using the correct utility, based on the bootloader settings (or default to just generating the HEX file). However, it should be noted that this may not work on all systems. AVRDUDE doesn't work on WSL, namely. +::: diff --git a/docs/flash_driver.md b/docs/flash_driver.md index fa7fed5171..4160721350 100644 --- a/docs/flash_driver.md +++ b/docs/flash_driver.md @@ -1,4 +1,4 @@ -# FLASH Driver Configuration :id=flash-driver-configuration +# FLASH Driver Configuration {#flash-driver-configuration} The FLASH driver can be swapped out depending on the needs of the keyboard, or whether extra hardware is present. @@ -7,7 +7,7 @@ Driver | Description `FLASH_DRIVER = spi` | Supports writing to almost all NOR Flash chips. See the driver section below. -## SPI FLASH Driver Configuration :id=spi-flash-driver-configuration +## SPI FLASH Driver Configuration {#spi-flash-driver-configuration} Currently QMK supports almost all NOR Flash chips over SPI. As such, requires a working spi_master driver configuration. You can override the driver configuration via your config.h: @@ -21,4 +21,6 @@ Currently QMK supports almost all NOR Flash chips over SPI. As such, requires a `#define EXTERNAL_FLASH_SIZE` | The total size of the FLASH in bytes, as specified in the datasheet | `(512 * 1024)` `#define EXTERNAL_FLASH_ADDRESS_SIZE` | The Flash address size in bytes, as specified in datasheet | `3` -!> All the above default configurations are based on MX25L4006E NOR Flash. +::: warning +All the above default configurations are based on MX25L4006E NOR Flash. +::: diff --git a/docs/flashing.md b/docs/flashing.md index 4867c20bec..c1e9f2a43d 100644 --- a/docs/flashing.md +++ b/docs/flashing.md @@ -8,7 +8,7 @@ You will also be able to use the CLI to flash your keyboard, by running: ``` $ qmk flash -kb -km ``` -See the [`qmk flash`](cli_commands.md#qmk-flash) documentation for more information. +See the [`qmk flash`](cli_commands#qmk-flash) documentation for more information. ## Atmel DFU @@ -53,7 +53,7 @@ QMK maintains [a fork of the LUFA DFU bootloader](https://github.com/qmk/lufa/tr //#define QMK_LED E6 //#define QMK_SPEAKER C6 ``` -Currently we do not recommend making `QMK_ESC` the same key as the one designated for [Bootmagic Lite](feature_bootmagic.md), as holding it down will cause the MCU to loop back and forth between entering and exiting the bootloader. +Currently we do not recommend making `QMK_ESC` the same key as the one designated for [Bootmagic Lite](feature_bootmagic), as holding it down will cause the MCU to loop back and forth between entering and exiting the bootloader. The manufacturer and product strings are automatically pulled from `config.h`, with " Bootloader" appended to the product string. @@ -209,7 +209,7 @@ To enable the additional features, add the following defines to your `config.h`: //#define QMK_SPEAKER C6 ``` -Currently we do not recommend making `QMK_ESC` the same key as the one designated for [Bootmagic Lite](feature_bootmagic.md), as holding it down will cause the MCU to loop back and forth between entering and exiting the bootloader. +Currently we do not recommend making `QMK_ESC` the same key as the one designated for [Bootmagic Lite](feature_bootmagic), as holding it down will cause the MCU to loop back and forth between entering and exiting the bootloader. The manufacturer and product strings are automatically pulled from `config.h`, with " Bootloader" appended to the product string. diff --git a/docs/flashing_bootloadhid.md b/docs/flashing_bootloadhid.md index aacf2cc2c4..6e55a4e7fd 100644 --- a/docs/flashing_bootloadhid.md +++ b/docs/flashing_bootloadhid.md @@ -13,7 +13,9 @@ 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. +::: tip +Using the QMK installation script, detailed [here](newbs_getting_started), 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/getting_started_docker.md b/docs/getting_started_docker.md index c4da8af968..6e69b17d34 100644 --- a/docs/getting_started_docker.md +++ b/docs/getting_started_docker.md @@ -52,4 +52,6 @@ RUNTIME="podman" util/docker_build.sh keyboard:keymap:target On Windows and macOS, it requires [Docker Machine](http://gw.tnode.com/docker/docker-machine-with-usb-support-on-windows-macos/) to be running. This is tedious to set up, so it's not recommended; use [QMK Toolbox](https://github.com/qmk/qmk_toolbox) instead. -!> Docker for Windows requires [Hyper-V](https://docs.microsoft.com/en-us/virtualization/hyper-v-on-windows/quick-start/enable-hyper-v) to be enabled. This means that it cannot work on versions of Windows which don't have Hyper-V, such as Windows 7, Windows 8 and **Windows 10 Home**. +::: warning +Docker for Windows requires [Hyper-V](https://docs.microsoft.com/en-us/virtualization/hyper-v-on-windows/quick-start/enable-hyper-v) to be enabled. This means that it cannot work on versions of Windows which don't have Hyper-V, such as Windows 7, Windows 8 and **Windows 10 Home**. +::: diff --git a/docs/getting_started_github.md b/docs/getting_started_github.md index 9232bc6229..b8587dbb13 100644 --- a/docs/getting_started_github.md +++ b/docs/getting_started_github.md @@ -2,7 +2,9 @@ GitHub can be a little tricky to those that aren't familiar with it - this guide will walk through each step of forking, cloning, and submitting a pull request with QMK. -?> This guide assumes you're somewhat comfortable with running things at the command line, and have git installed on your system. +::: tip +This guide assumes you're somewhat comfortable with running things at the command line, and have git installed on your system. +::: Start on the [QMK GitHub page](https://github.com/qmk/qmk_firmware), and you'll see a button in the upper right that says "Fork": diff --git a/docs/getting_started_introduction.md b/docs/getting_started_introduction.md index 8020335345..9417351747 100644 --- a/docs/getting_started_introduction.md +++ b/docs/getting_started_introduction.md @@ -8,7 +8,7 @@ QMK is a fork of [Jun Wako](https://github.com/tmk)'s [tmk_keyboard](https://git ### Userspace Structure -Within the folder `users` is a directory for each user. This is a place for users to put code that they might use between keyboards. See the docs for [Userspace feature](feature_userspace.md) for more information. +Within the folder `users` is a directory for each user. This is a place for users to put code that they might use between keyboards. See the docs for [Userspace feature](feature_userspace) for more information. ### Keyboard Project Structure @@ -17,12 +17,12 @@ Within the folder `keyboards`, its subfolder `handwired` and its vendor and manu * `keymaps/`: Different keymaps that can be built * `rules.mk`: The file that sets the default "make" options. Do not edit this file directly, instead use a keymap specific `rules.mk`. * `config.h`: The file that sets the default compile time options. Do not edit this file directly, instead use a keymap specific `config.h`. -* `info.json`: The file used for setting layout for QMK Configurator. See [Configurator Support](reference_configurator_support.md) for more information. +* `info.json`: The file used for setting layout for QMK Configurator. See [Configurator Support](reference_configurator_support) for more information. * `readme.md`: A brief overview of the keyboard. * `.h`: This file is where the keyboard layout is defined against the keyboard's switch matrix. * `.c`: This file is where you can find custom code for the keyboard. -For more information on project structure, see [QMK Keyboard Guidelines](hardware_keyboard_guidelines.md). +For more information on project structure, see [QMK Keyboard Guidelines](hardware_keyboard_guidelines). ### Keymap Structure diff --git a/docs/getting_started_make_guide.md b/docs/getting_started_make_guide.md index 3d98e4602b..8a66a65c21 100644 --- a/docs/getting_started_make_guide.md +++ b/docs/getting_started_make_guide.md @@ -15,8 +15,8 @@ The `` means the following * If no target is given, then it's the same as `all` below * `all` compiles as many keyboard/revision/keymap combinations as specified. For example, `make planck/rev4:default` will generate a single .hex, while `make planck/rev4:all` will generate a hex for every keymap available to the planck. * `flash`, `dfu`, `teensy`, `avrdude`, `dfu-util`, or `bootloadhid` compile and upload the firmware to the keyboard. If the compilation fails, then nothing will be uploaded. The programmer to use depends on the keyboard. For most keyboards it's `dfu`, but for ChibiOS keyboards you should use `dfu-util`, and `teensy` for standard Teensys. To find out which command you should use for your keyboard, check the keyboard specific readme. - Visit the [Flashing Firmware](flashing.md) guide for more details of the available bootloaders. - * **Note**: some operating systems need privileged access for these commands to work. This means that you may need to setup [`udev rules`](faq_build.md#linux-udev-rules) to access these without root access, or to run the command with root access (`sudo make planck/rev4:default:flash`). + Visit the [Flashing Firmware](flashing) guide for more details of the available bootloaders. + * **Note**: some operating systems need privileged access for these commands to work. This means that you may need to setup [`udev rules`](faq_build#linux-udev-rules) to access these without root access, or to run the command with root access (`sudo make planck/rev4:default:flash`). * `clean`, cleans the build output folders to make sure that everything is built from scratch. Run this before normal compilation if you have some unexplainable problems. * `distclean` removes .hex files and .bin files. @@ -115,19 +115,19 @@ This allows you to send Unicode characters using `UM()` in your keyma This allows you to send Unicode characters by inputting a mnemonic corresponding to the character you want to send. You will need to maintain a mapping table in your keymap file. All possible code points (up to `0x10FFFF`) are supported. -For further details, as well as limitations, see the [Unicode page](feature_unicode.md). +For further details, as well as limitations, see the [Unicode page](feature_unicode). `AUDIO_ENABLE` -This allows you output audio on the C6 pin (needs abstracting). See the [audio page](feature_audio.md) for more information. +This allows you output audio on the C6 pin (needs abstracting). See the [audio page](feature_audio) for more information. `VARIABLE_TRACE` -Use this to debug changes to variable values, see the [tracing variables](unit_testing.md#tracing-variables) section of the Unit Testing page for more information. +Use this to debug changes to variable values, see the [tracing variables](unit_testing#tracing-variables) section of the Unit Testing page for more information. `KEY_LOCK_ENABLE` -This enables [key lock](feature_key_lock.md). +This enables [key lock](feature_key_lock). `SPLIT_KEYBOARD` @@ -139,7 +139,7 @@ As there is no standard split communication driver for ARM-based split keyboards `CUSTOM_MATRIX` -Lets you replace the default matrix scanning routine with your own code. For further details, see the [Custom Matrix page](custom_matrix.md). +Lets you replace the default matrix scanning routine with your own code. For further details, see the [Custom Matrix page](custom_matrix). `DEBOUNCE_TYPE` @@ -147,7 +147,7 @@ Lets you replace the default key debouncing routine with an alternative one. If `DEFERRED_EXEC_ENABLE` -Enables deferred executor support -- timed delays before callbacks are invoked. See [deferred execution](custom_quantum_functions.md#deferred-execution) for more information. +Enables deferred executor support -- timed delays before callbacks are invoked. See [deferred execution](custom_quantum_functions#deferred-execution) for more information. ## Customizing Makefile Options on a Per-Keymap Basis diff --git a/docs/gpio_control.md b/docs/gpio_control.md index 90798fc87b..9ce4f2aa20 100644 --- a/docs/gpio_control.md +++ b/docs/gpio_control.md @@ -1,8 +1,8 @@ -# GPIO Control :id=gpio-control +# GPIO Control {#gpio-control} QMK has a GPIO control abstraction layer which is microcontroller agnostic. This is done to allow easy access to pin control across different platforms. -## Macros :id=macros +## Macros {#macros} The following macros provide basic control of GPIOs and are found in `platforms//gpio.h`. @@ -20,11 +20,11 @@ The following macros provide basic control of GPIOs and are found in `platforms/ |`gpio_read_pin(pin)` |Returns the level of the pin | |`gpio_toggle_pin(pin)` |Invert pin level, assuming it is an output | -## Advanced Settings :id=advanced-settings +## Advanced Settings {#advanced-settings} Each microcontroller can have multiple advanced settings regarding its GPIO. This abstraction layer does not limit the use of architecture-specific functions. Advanced users should consult the datasheet of their desired device. For AVR, the standard `avr/io.h` library is used; for STM32, the ChibiOS [PAL library](https://chibios.sourceforge.net/docs3/hal/group___p_a_l.html) is used. -## Atomic Operation :id=atomic-operation +## Atomic Operation {#atomic-operation} The above functions are not always guaranteed to work atomically. Therefore, if you want to prevent interruptions in the middle of operations when using multiple combinations of the above functions, use the following `ATOMIC_BLOCK_FORCEON` macro. diff --git a/docs/hand_wire.md b/docs/hand_wire.md index cfae38d6d2..460e8e8be6 100644 --- a/docs/hand_wire.md +++ b/docs/hand_wire.md @@ -88,7 +88,7 @@ Note that these methods can be combined. Prepare your lengths of wire before mo ### A note on split keyboards -If you are planning a split keyboard (e.g. Dactyl) each half will require a controller and a means of communicating between them (like a TRRS or hardwired cable). Further information can be found in the [QMK split keyboard documentation.](feature_split_keyboard.md) +If you are planning a split keyboard (e.g. Dactyl) each half will require a controller and a means of communicating between them (like a TRRS or hardwired cable). Further information can be found in the [QMK split keyboard documentation.](feature_split_keyboard) ### Soldering @@ -177,7 +177,7 @@ From here, you should have a working keyboard once you program a firmware. Simple firmware can be created easily using the [Keyboard Firmware Builder](https://kbfirmware.com/) website. Recreate your layout using [Keyboard Layout Editor](https://www.keyboard-layout-editor.com), import it and recreate the matrix (if not already done as part of [planning the matrix](#planning-the-matrix)). -Go through the rest of the tabs, assigning keys until you get to the last one where you can compile and download your firmware. The .hex file can be flashed straight onto your keyboard, or for advanced functionality, compiled locally after [Setting up Your Environment](newbs_getting_started.md). +Go through the rest of the tabs, assigning keys until you get to the last one where you can compile and download your firmware. The .hex file can be flashed straight onto your keyboard, or for advanced functionality, compiled locally after [Setting up Your Environment](newbs_getting_started). The source given by Keyboard Firmware Builder is QMK, but is based on a version of QMK from early 2017. To compile the firmware in a modern version of QMK Firmware, you'll need to export via the `Save Configuration` button, then run: @@ -244,6 +244,6 @@ There are a lot of possibilities inside the firmware - explore [docs.qmk.fm](htt This page used to include more content. We have moved a section that used to be part of this page its own page. Everything below this point is simply a redirect so that people following old links on the web find what they're looking for. -## Preamble: How a Keyboard Matrix Works (and why we need diodes) :id=preamble-how-a-keyboard-matrix-works-and-why-we-need-diodes +## Preamble: How a Keyboard Matrix Works (and why we need diodes) {#preamble-how-a-keyboard-matrix-works-and-why-we-need-diodes} -* [How a Keyboard Matrix Works](how_a_matrix_works.md) +* [How a Keyboard Matrix Works](how_a_matrix_works) diff --git a/docs/hardware_drivers.md b/docs/hardware_drivers.md index a157501326..6960bbcaa1 100644 --- a/docs/hardware_drivers.md +++ b/docs/hardware_drivers.md @@ -16,20 +16,20 @@ Support for addressing pins on the ProMicro by their Arduino name rather than th ## SSD1306 OLED Driver -Support for SSD1306 based OLED displays. For more information see the [OLED Driver Feature](feature_oled_driver.md) page. +Support for SSD1306 based OLED displays. For more information see the [OLED Driver Feature](feature_oled_driver) page. ## WS2812 -Support for WS2811/WS2812{a,b,c} LED's. For more information see the [RGB Light](feature_rgblight.md) page. +Support for WS2811/WS2812{a,b,c} LED's. For more information see the [RGB Light](feature_rgblight) page. ## IS31FL3731 -Support for up to 2 drivers. Each driver impliments 2 charlieplex matrices to individually address LEDs using I2C. This allows up to 144 same color LEDs or 32 RGB LEDs. For more information on how to setup the driver see the [RGB Matrix](feature_rgb_matrix.md) page. +Support for up to 2 drivers. Each driver impliments 2 charlieplex matrices to individually address LEDs using I2C. This allows up to 144 same color LEDs or 32 RGB LEDs. For more information on how to setup the driver see the [RGB Matrix](feature_rgb_matrix) page. ## IS31FL3733 -Support for up to a single driver with room for expansion. Each driver can control 192 individual LEDs or 64 RGB LEDs. For more information on how to setup the driver see the [RGB Matrix](feature_rgb_matrix.md) page. +Support for up to a single driver with room for expansion. Each driver can control 192 individual LEDs or 64 RGB LEDs. For more information on how to setup the driver see the [RGB Matrix](feature_rgb_matrix) page. ## 24xx series external I2C EEPROM -Support for an external I2C-based EEPROM instead of using the on-chip EEPROM. For more information on how to setup the driver see the [EEPROM Driver](eeprom_driver.md) page. +Support for an external I2C-based EEPROM instead of using the on-chip EEPROM. For more information on how to setup the driver see the [EEPROM Driver](eeprom_driver) page. diff --git a/docs/hardware_keyboard_guidelines.md b/docs/hardware_keyboard_guidelines.md index 684ccc73f6..e7c62321f6 100644 --- a/docs/hardware_keyboard_guidelines.md +++ b/docs/hardware_keyboard_guidelines.md @@ -70,11 +70,11 @@ Your keyboard should be located in `qmk_firmware/keyboards/` and the folder name ### `readme.md` -All projects need to have a `readme.md` file that explains what the keyboard is, who made it and where it's available. If applicable, it should also contain links to more information, such as the maker's website. Please follow the [published template](documentation_templates.md#keyboard-readmemd-template). +All projects need to have a `readme.md` file that explains what the keyboard is, who made it and where it's available. If applicable, it should also contain links to more information, such as the maker's website. Please follow the [published template](documentation_templates#keyboard-readmemd-template). ### `info.json` -This file is used by the [QMK API](https://github.com/qmk/qmk_api). It contains the information [QMK Configurator](https://config.qmk.fm/) needs to display a representation of your keyboard. You can also set metadata here. For more information see the [reference page](reference_info_json.md). +This file is used by the [QMK API](https://github.com/qmk/qmk_api). It contains the information [QMK Configurator](https://config.qmk.fm/) needs to display a representation of your keyboard. You can also set metadata here. For more information see the [reference page](reference_info_json). ### `config.h` @@ -87,7 +87,7 @@ The `config.h` files can also be placed in sub-folders, and the order in which t * `keyboards/top_folder/sub_1/sub_2/config.h` * `keyboards/top_folder/sub_1/sub_2/sub_3/config.h` * `keyboards/top_folder/sub_1/sub_2/sub_3/sub_4/config.h` - * [`.build/objs_/src/info_config.h`](data_driven_config.md#add-code-to-generate-it) see [Data Driven Configuration](data_driven_config.md) + * [`.build/objs_/src/info_config.h`](data_driven_config#add-code-to-generate-it) see [Data Driven Configuration](data_driven_config) * `users/a_user_folder/config.h` * `keyboards/top_folder/keymaps/a_keymap/config.h` * `keyboards/top_folder/sub_1/sub_2/sub_3/sub_4/post_config.h` @@ -130,7 +130,9 @@ The `post_config.h` file can be used for additional post-processing, depending o #endif ``` -?> If you define options using `post_config.h` as in the above example, you should not define the same options in the keyboard- or user-level `config.h`. +::: tip +If you define options using `post_config.h` as in the above example, you should not define the same options in the keyboard- or user-level `config.h`. +::: ### `rules.mk` @@ -177,7 +179,9 @@ The `post_rules.mk` file can interpret `features` of a keyboard-level before `co endif ``` -?> See `build_keyboard.mk` and `common_features.mk` for more details. +::: tip +See `build_keyboard.mk` and `common_features.mk` for more details. +::: ### `` @@ -208,7 +212,9 @@ As an example, if you have a 60% PCB that supports ANSI and ISO you might define | LAYOUT_ansi | default_ansi | An ANSI layout | | LAYOUT_iso | default_iso | An ISO layout | -?> Providing only `LAYOUT_all` is invalid - especially when implementing the additional layouts within 3rd party tooling. +::: tip +Providing only `LAYOUT_all` is invalid - especially when implementing the additional layouts within 3rd party tooling. +::: ## Image/Hardware Files @@ -222,7 +228,7 @@ Given the amount of functionality that QMK exposes it's very easy to confuse new ### Magic Keycodes and Command -[Magic Keycodes](keycodes_magic.md) and [Command](feature_command.md) are two related features that allow a user to control their keyboard in non-obvious ways. We recommend you think long and hard about if you're going to enable either feature, and how you will expose this functionality. Keep in mind that users who want this functionality can enable it in their personal keymaps without affecting all the novice users who may be using your keyboard as their first programmable board. +[Magic Keycodes](keycodes_magic) and [Command](feature_command) are two related features that allow a user to control their keyboard in non-obvious ways. We recommend you think long and hard about if you're going to enable either feature, and how you will expose this functionality. Keep in mind that users who want this functionality can enable it in their personal keymaps without affecting all the novice users who may be using your keyboard as their first programmable board. By far the most common problem new users encounter is accidentally triggering Bootmagic while they're plugging in their keyboard. They're holding the keyboard by the bottom, unknowingly pressing in alt and spacebar, and then they find that these keys have been swapped on them. We recommend leaving this feature disabled by default, but if you do turn it on consider setting `BOOTMAGIC_KEY_SALT` to a key that is hard to press while plugging your keyboard in. @@ -230,7 +236,7 @@ If your keyboard does not have 2 shift keys you should provide a working default ## Custom Keyboard Programming -As documented on [Customizing Functionality](custom_quantum_functions.md) you can define custom functions for your keyboard. Please keep in mind that your users may want to customize that behavior as well, and make it possible for them to do that. If you are providing a custom function, for example `process_record_kb()`, make sure that your function calls the `_user()` version of the call too. You should also take into account the return value of the `_user()` version, and only run your custom code if the user returns `true`. +As documented on [Customizing Functionality](custom_quantum_functions) you can define custom functions for your keyboard. Please keep in mind that your users may want to customize that behavior as well, and make it possible for them to do that. If you are providing a custom function, for example `process_record_kb()`, make sure that your function calls the `_user()` version of the call too. You should also take into account the return value of the `_user()` version, and only run your custom code if the user returns `true`. ## Non-Production/Handwired Projects @@ -257,7 +263,3 @@ The year should be the first year the file is created. If work was done to that ## License The core of QMK is licensed under the [GNU General Public License](https://www.gnu.org/licenses/licenses.en.html). If you are shipping binaries for AVR processors you may choose either [GPLv2](https://www.gnu.org/licenses/old-licenses/gpl-2.0.html) or [GPLv3](https://www.gnu.org/licenses/gpl.html). If you are shipping binaries for ARM processors you must choose [GPL Version 3](https://www.gnu.org/licenses/gpl.html) to comply with the [ChibiOS](https://www.chibios.org) GPLv3 license. - -## Technical Details - -If you're looking for more information on making your keyboard work with QMK, [check out the hardware section](hardware.md)! diff --git a/docs/how_a_matrix_works.md b/docs/how_a_matrix_works.md index 48e41e5c7d..ebe90eb3de 100644 --- a/docs/how_a_matrix_works.md +++ b/docs/how_a_matrix_works.md @@ -96,4 +96,4 @@ Further reading: - [Deskthority article](https://deskthority.net/wiki/Keyboard_matrix) - [Keyboard Matrix Help by Dave Dribin (2000)](https://www.dribin.org/dave/keyboard/one_html/) - [How Key Matrices Works by PCBheaven](https://pcbheaven.com/wikipages/How_Key_Matrices_Works/) (animated examples) -- [How keyboards work - QMK documentation](how_keyboards_work.md) +- [How keyboards work - QMK documentation](how_keyboards_work) diff --git a/docs/how_keyboards_work.md b/docs/how_keyboards_work.md index 0f4b039fd4..9d620f0060 100644 --- a/docs/how_keyboards_work.md +++ b/docs/how_keyboards_work.md @@ -55,7 +55,7 @@ layout is set to QWERTY, a sample of the matching table is as follows: ## Back to the Firmware -As the layout is generally fixed (unless you create your own), the firmware can actually call a keycode by its layout name directly to ease things for you. This is exactly what is done here with `KC_A` actually representing `0x04` in QWERTY. The full list can be found in [keycodes](keycodes.md). +As the layout is generally fixed (unless you create your own), the firmware can actually call a keycode by its layout name directly to ease things for you. This is exactly what is done here with `KC_A` actually representing `0x04` in QWERTY. The full list can be found in [keycodes](keycodes). ## List of Characters You Can Send diff --git a/docs/i2c_driver.md b/docs/i2c_driver.md index 9a3c08b90b..ccc21137b3 100644 --- a/docs/i2c_driver.md +++ b/docs/i2c_driver.md @@ -1,10 +1,10 @@ -# I2C Master Driver :id=i2c-master-driver +# I2C Master Driver {#i2c-master-driver} The I2C Master drivers used in QMK have a set of common functions to allow portability between MCUs. -## Usage :id=usage +## Usage {#usage} -In most cases, the I2C Master driver code is automatically included if you are using a feature or driver which requires it, such as [OLED](feature_oled_driver.md). +In most cases, the I2C Master driver code is automatically included if you are using a feature or driver which requires it, such as [OLED](feature_oled_driver). However, if you need to use the driver standalone, add the following to your `rules.mk`: @@ -14,7 +14,7 @@ I2C_DRIVER_REQUIRED = yes You can then call the I2C API by including `i2c_master.h` in your code. -## I2C Addressing :id=note-on-i2c-addresses +## I2C Addressing {#note-on-i2c-addresses} All of the addresses expected by this driver should be pushed to the upper 7 bits of the address byte. Setting the lower bit (indicating read/write) will be done by the respective functions. Almost all I2C addresses listed @@ -29,7 +29,7 @@ You can either do this on each call to the functions below, or once in your defi See https://www.robot-electronics.co.uk/i2c-tutorial for more information about I2C addressing and other technical details. -## AVR Configuration :id=avr-configuration +## AVR Configuration {#avr-configuration} The following defines can be used to configure the I2C master driver: @@ -46,9 +46,11 @@ No further setup is required - just connect the `SDA` and `SCL` pins of your I2C |ATmega32A |`C0` |`C1` | |ATmega328/P |`C5` |`C4` | -?> The ATmega16/32U2 does not possess I2C functionality, and so cannot use this driver. +::: tip +The ATmega16/32U2 does not possess I2C functionality, and so cannot use this driver. +::: -## ChibiOS/ARM Configuration :id=arm-configuration +## ChibiOS/ARM Configuration {#arm-configuration} You'll need to determine which pins can be used for I2C -- a an example, STM32 parts generally have multiple I2C peripherals, labeled I2C1, I2C2, I2C3 etc. @@ -84,7 +86,7 @@ Configuration-wise, you'll need to set up the peripheral as per your MCU's datas The following configuration values depend on the specific MCU in use. -### I2Cv1 :id=arm-configuration-i2cv1 +### I2Cv1 {#arm-configuration-i2cv1} * STM32F1xx * STM32F2xx @@ -100,7 +102,7 @@ See [this page](https://www.playembedded.org/blog/stm32-i2c-chibios/#7_I2Cv1_con |`I2C1_CLOCK_SPEED` |`100000` | |`I2C1_DUTY_CYCLE` |`STD_DUTY_CYCLE`| -### I2Cv2 :id=arm-configuration-i2cv2 +### I2Cv2 {#arm-configuration-i2cv2} * STM32F0xx * STM32F3xx @@ -117,9 +119,9 @@ See [this page](https://www.playembedded.org/blog/stm32-i2c-chibios/#8_I2Cv2_I2C |`I2C1_TIMINGR_SCLH` |`38U` | |`I2C1_TIMINGR_SCLL` |`129U` | -## API :id=api +## API {#api} -### `void i2c_init(void)` :id=api-i2c-init +### `void i2c_init(void)` {#api-i2c-init} Initialize the I2C driver. This function must be called only once, before any of the below functions can be called. @@ -138,11 +140,11 @@ void i2c_init(void) { --- -### `i2c_status_t i2c_transmit(uint8_t address, uint8_t *data, uint16_t length, uint16_t timeout)` :id=api-i2c-transmit +### `i2c_status_t i2c_transmit(uint8_t address, uint8_t *data, uint16_t length, uint16_t timeout)` {#api-i2c-transmit} Send multiple bytes to the selected I2C device. -#### Arguments :id=api-i2c-transmit-arguments +#### Arguments {#api-i2c-transmit-arguments} - `uint8_t address` The 7-bit I2C address of the device. @@ -153,17 +155,17 @@ Send multiple bytes to the selected I2C device. - `uint16_t timeout` The time in milliseconds to wait for a response from the target device. -#### Return Value :id=api-i2c-transmit-return +#### Return Value {#api-i2c-transmit-return} `I2C_STATUS_TIMEOUT` if the timeout period elapses, `I2C_STATUS_ERROR` if some other error occurs, otherwise `I2C_STATUS_SUCCESS`. --- -### `i2c_status_t i2c_receive(uint8_t address, uint8_t* data, uint16_t length, uint16_t timeout)` :id=api-i2c-receive +### `i2c_status_t i2c_receive(uint8_t address, uint8_t* data, uint16_t length, uint16_t timeout)` {#api-i2c-receive} Receive multiple bytes from the selected I2C device. -#### Arguments :id=api-i2c-receive-arguments +#### Arguments {#api-i2c-receive-arguments} - `uint8_t address` The 7-bit I2C address of the device. @@ -174,17 +176,17 @@ Receive multiple bytes from the selected I2C device. - `uint16_t timeout` The time in milliseconds to wait for a response from the target device. -#### Return Value :id=api-i2c-receive-return +#### Return Value {#api-i2c-receive-return} `I2C_STATUS_TIMEOUT` if the timeout period elapses, `I2C_STATUS_ERROR` if some other error occurs, otherwise `I2C_STATUS_SUCCESS`. --- -### `i2c_status_t i2c_write_register(uint8_t devaddr, uint8_t regaddr, uint8_t* data, uint16_t length, uint16_t timeout)` :id=api-i2c-write-register +### `i2c_status_t i2c_write_register(uint8_t devaddr, uint8_t regaddr, uint8_t* data, uint16_t length, uint16_t timeout)` {#api-i2c-write-register} Writes to a register with an 8-bit address on the I2C device. -#### Arguments :id=api-i2c-write-register-arguments +#### Arguments {#api-i2c-write-register-arguments} - `uint8_t devaddr` The 7-bit I2C address of the device. @@ -197,17 +199,17 @@ Writes to a register with an 8-bit address on the I2C device. - `uint16_t timeout` The time in milliseconds to wait for a response from the target device. -#### Return Value :id=api-i2c-write-register-return +#### Return Value {#api-i2c-write-register-return} `I2C_STATUS_TIMEOUT` if the timeout period elapses, `I2C_STATUS_ERROR` if some other error occurs, otherwise `I2C_STATUS_SUCCESS`. --- -### `i2c_status_t i2c_write_register16(uint8_t devaddr, uint16_t regaddr, uint8_t* data, uint16_t length, uint16_t timeout)` :id=api-i2c-write-register16 +### `i2c_status_t i2c_write_register16(uint8_t devaddr, uint16_t regaddr, uint8_t* data, uint16_t length, uint16_t timeout)` {#api-i2c-write-register16} Writes to a register with a 16-bit address (big endian) on the I2C device. -#### Arguments :id=api-i2c-write-register16-arguments +#### Arguments {#api-i2c-write-register16-arguments} - `uint8_t devaddr` The 7-bit I2C address of the device. @@ -220,17 +222,17 @@ Writes to a register with a 16-bit address (big endian) on the I2C device. - `uint16_t timeout` The time in milliseconds to wait for a response from the target device. -#### Return Value :id=api-i2c-write-register16-return +#### Return Value {#api-i2c-write-register16-return} `I2C_STATUS_TIMEOUT` if the timeout period elapses, `I2C_STATUS_ERROR` if some other error occurs, otherwise `I2C_STATUS_SUCCESS`. --- -### `i2c_status_t i2c_read_register(uint8_t devaddr, uint8_t regaddr, uint8_t* data, uint16_t length, uint16_t timeout)` :id=api-i2c-read-register +### `i2c_status_t i2c_read_register(uint8_t devaddr, uint8_t regaddr, uint8_t* data, uint16_t length, uint16_t timeout)` {#api-i2c-read-register} Reads from a register with an 8-bit address on the I2C device. -#### Arguments :id=api-i2c-read-register-arguments +#### Arguments {#api-i2c-read-register-arguments} - `uint8_t devaddr` The 7-bit I2C address of the device. @@ -241,17 +243,17 @@ Reads from a register with an 8-bit address on the I2C device. - `uint16_t timeout` The time in milliseconds to wait for a response from the target device. -#### Return Value :id=api-i2c-read-register-return +#### Return Value {#api-i2c-read-register-return} `I2C_STATUS_TIMEOUT` if the timeout period elapses, `I2C_STATUS_ERROR` if some other error occurs, otherwise `I2C_STATUS_SUCCESS`. --- -### `i2c_status_t i2c_read_register16(uint8_t devaddr, uint16_t regaddr, uint8_t* data, uint16_t length, uint16_t timeout)` :id=api-i2c-read-register16 +### `i2c_status_t i2c_read_register16(uint8_t devaddr, uint16_t regaddr, uint8_t* data, uint16_t length, uint16_t timeout)` {#api-i2c-read-register16} Reads from a register with a 16-bit address (big endian) on the I2C device. -#### Arguments :id=api-i2c-read-register16-arguments +#### Arguments {#api-i2c-read-register16-arguments} - `uint8_t devaddr` The 7-bit I2C address of the device. @@ -262,13 +264,13 @@ Reads from a register with a 16-bit address (big endian) on the I2C device. - `uint16_t timeout` The time in milliseconds to wait for a response from the target device. -#### Return Value :id=api-i2c-read-register16-return +#### Return Value {#api-i2c-read-register16-return} `I2C_STATUS_TIMEOUT` if the timeout period elapses, `I2C_STATUS_ERROR` if some other error occurs, otherwise `I2C_STATUS_SUCCESS`. --- -### `i2c_status_t i2c_ping_address(uint8_t address, uint16_t timeout)` :id=api-i2c-ping-address +### `i2c_status_t i2c_ping_address(uint8_t address, uint16_t timeout)` {#api-i2c-ping-address} Pings the I2C bus for a specific address. diff --git a/docs/index.html b/docs/index.html deleted file mode 100644 index 4827024bdc..0000000000 --- a/docs/index.html +++ /dev/null @@ -1,147 +0,0 @@ - - - - - QMK Firmware - - - - - - - - - - - - - - - - - -
- - - - - - - - - - - - - - - diff --git a/docs/README.md b/docs/index.md similarity index 76% rename from docs/README.md rename to docs/index.md index 9330f0face..91f27a8a80 100644 --- a/docs/README.md +++ b/docs/index.md @@ -8,21 +8,25 @@ QMK (*Quantum Mechanical Keyboard*) is an open source community centered around
-?> **Basic** [QMK Configurator](newbs_building_firmware_configurator.md)
+::: tip +**Basic** [QMK Configurator](newbs_building_firmware_configurator)
+::: User friendly graphical interfaces, no programming knowledge required. -?> **Advanced** [Use The Source](newbs.md)
+::: tip +**Advanced** [Use The Source](newbs)
+::: More powerful, but harder to use.
## Make It Yours -QMK has lots of features to explore, and a good deal of reference documentation to dig through. Most features are taken advantage of by modifying your [keymap](keymap.md), and changing the [keycodes](keycodes.md). +QMK has lots of features to explore, and a good deal of reference documentation to dig through. Most features are taken advantage of by modifying your [keymap](keymap), and changing the [keycodes](keycodes). ## Need help? -Check out the [support page](support.md) to see how you can get help using QMK. +Check out the [support page](support) to see how you can get help using QMK. ## Give Back @@ -32,6 +36,5 @@ There are a lot of ways you can contribute to the QMK Community. The easiest way * [/r/olkb](https://www.reddit.com/r/olkb/) * [Discord Server](https://discord.gg/Uq7gcHh) * Contribute to our documentation by clicking "Edit This Page" at the bottom -* [Translate our documentation into your language](translating.md) * [Report a bug](https://github.com/qmk/qmk_firmware/issues/new/choose) -* [Open a Pull Request](contributing.md) +* [Open a Pull Request](contributing) diff --git a/docs/internals/defines.md b/docs/internals/defines.md deleted file mode 100644 index fdcb553589..0000000000 --- a/docs/internals/defines.md +++ /dev/null @@ -1,78 +0,0 @@ -# group `defines` {#group__defines} - -## Summary - - Members | Descriptions ---------------------------------|--------------------------------------------- -`define `[`SYSEX_BEGIN`](#group__defines_1ga1a3c39bb790dda8a368c4247caabcf79) | -`define `[`SYSEX_END`](#group__defines_1ga753706d1d28e6f96d7caf1973e80feed) | -`define `[`MIDI_STATUSMASK`](#group__defines_1gab78a1c818a5f5dab7a8946543f126c69) | -`define `[`MIDI_CHANMASK`](#group__defines_1ga239edc0a6f8405d3a8f2804f1590b909) | -`define `[`MIDI_CC`](#group__defines_1ga45f116a1daab76b3c930c2cecfaef215) | -`define `[`MIDI_NOTEON`](#group__defines_1gafd416f27bf3590868c0c1f55c30be4c7) | -`define `[`MIDI_NOTEOFF`](#group__defines_1gabed24bea2d989fd655e2ef2ad0765adc) | -`define `[`MIDI_AFTERTOUCH`](#group__defines_1ga3a322d8cfd53576a2e167c1840551b0f) | -`define `[`MIDI_PITCHBEND`](#group__defines_1gabcc799504e8064679bca03f232223af4) | -`define `[`MIDI_PROGCHANGE`](#group__defines_1gaefb3f1595ffbb9db66b46c2c919a3d42) | -`define `[`MIDI_CHANPRESSURE`](#group__defines_1gaeb3281cc7fcd0daade8ed3d2dfc33dbe) | -`define `[`MIDI_CLOCK`](#group__defines_1gafa5e4e295aafd15ab7893344599b3b89) | -`define `[`MIDI_TICK`](#group__defines_1ga3b99408ff864613765d4c3c2ceb52aa7) | -`define `[`MIDI_START`](#group__defines_1ga8233631c85823aa546f932ad8975caa4) | -`define `[`MIDI_CONTINUE`](#group__defines_1gab24430f0081e27215b0da84dd0ee745c) | -`define `[`MIDI_STOP`](#group__defines_1ga3af9271d4b1f0d22904a0b055f48cf62) | -`define `[`MIDI_ACTIVESENSE`](#group__defines_1gacd88ed42dba52bb4b2052c5656362677) | -`define `[`MIDI_RESET`](#group__defines_1ga02947f30ca62dc332fdeb10c5868323b) | -`define `[`MIDI_TC_QUARTERFRAME`](#group__defines_1gaaa072f33590e236d1bfd8f28e833ae31) | -`define `[`MIDI_SONGPOSITION`](#group__defines_1ga412f6ed33a2150051374bee334ee1705) | -`define `[`MIDI_SONGSELECT`](#group__defines_1gafcab254838b028365ae0259729e72c4e) | -`define `[`MIDI_TUNEREQUEST`](#group__defines_1ga8100b907b8c0a84e58b1c53dcd9bd795) | -`define `[`SYSEX_EDUMANUFID`](#group__defines_1ga5ef855ed955b00a2239ca16afbeb164f) | - -## Members - -#### `define `[`SYSEX_BEGIN`](#group__defines_1ga1a3c39bb790dda8a368c4247caabcf79) {#group__defines_1ga1a3c39bb790dda8a368c4247caabcf79} - -#### `define `[`SYSEX_END`](#group__defines_1ga753706d1d28e6f96d7caf1973e80feed) {#group__defines_1ga753706d1d28e6f96d7caf1973e80feed} - -#### `define `[`MIDI_STATUSMASK`](#group__defines_1gab78a1c818a5f5dab7a8946543f126c69) {#group__defines_1gab78a1c818a5f5dab7a8946543f126c69} - -#### `define `[`MIDI_CHANMASK`](#group__defines_1ga239edc0a6f8405d3a8f2804f1590b909) {#group__defines_1ga239edc0a6f8405d3a8f2804f1590b909} - -#### `define `[`MIDI_CC`](#group__defines_1ga45f116a1daab76b3c930c2cecfaef215) {#group__defines_1ga45f116a1daab76b3c930c2cecfaef215} - -#### `define `[`MIDI_NOTEON`](#group__defines_1gafd416f27bf3590868c0c1f55c30be4c7) {#group__defines_1gafd416f27bf3590868c0c1f55c30be4c7} - -#### `define `[`MIDI_NOTEOFF`](#group__defines_1gabed24bea2d989fd655e2ef2ad0765adc) {#group__defines_1gabed24bea2d989fd655e2ef2ad0765adc} - -#### `define `[`MIDI_AFTERTOUCH`](#group__defines_1ga3a322d8cfd53576a2e167c1840551b0f) {#group__defines_1ga3a322d8cfd53576a2e167c1840551b0f} - -#### `define `[`MIDI_PITCHBEND`](#group__defines_1gabcc799504e8064679bca03f232223af4) {#group__defines_1gabcc799504e8064679bca03f232223af4} - -#### `define `[`MIDI_PROGCHANGE`](#group__defines_1gaefb3f1595ffbb9db66b46c2c919a3d42) {#group__defines_1gaefb3f1595ffbb9db66b46c2c919a3d42} - -#### `define `[`MIDI_CHANPRESSURE`](#group__defines_1gaeb3281cc7fcd0daade8ed3d2dfc33dbe) {#group__defines_1gaeb3281cc7fcd0daade8ed3d2dfc33dbe} - -#### `define `[`MIDI_CLOCK`](#group__defines_1gafa5e4e295aafd15ab7893344599b3b89) {#group__defines_1gafa5e4e295aafd15ab7893344599b3b89} - -#### `define `[`MIDI_TICK`](#group__defines_1ga3b99408ff864613765d4c3c2ceb52aa7) {#group__defines_1ga3b99408ff864613765d4c3c2ceb52aa7} - -#### `define `[`MIDI_START`](#group__defines_1ga8233631c85823aa546f932ad8975caa4) {#group__defines_1ga8233631c85823aa546f932ad8975caa4} - -#### `define `[`MIDI_CONTINUE`](#group__defines_1gab24430f0081e27215b0da84dd0ee745c) {#group__defines_1gab24430f0081e27215b0da84dd0ee745c} - -#### `define `[`MIDI_STOP`](#group__defines_1ga3af9271d4b1f0d22904a0b055f48cf62) {#group__defines_1ga3af9271d4b1f0d22904a0b055f48cf62} - -#### `define `[`MIDI_ACTIVESENSE`](#group__defines_1gacd88ed42dba52bb4b2052c5656362677) {#group__defines_1gacd88ed42dba52bb4b2052c5656362677} - -#### `define `[`MIDI_RESET`](#group__defines_1ga02947f30ca62dc332fdeb10c5868323b) {#group__defines_1ga02947f30ca62dc332fdeb10c5868323b} - -#### `define `[`MIDI_TC_QUARTERFRAME`](#group__defines_1gaaa072f33590e236d1bfd8f28e833ae31) {#group__defines_1gaaa072f33590e236d1bfd8f28e833ae31} - -#### `define `[`MIDI_SONGPOSITION`](#group__defines_1ga412f6ed33a2150051374bee334ee1705) {#group__defines_1ga412f6ed33a2150051374bee334ee1705} - -#### `define `[`MIDI_SONGSELECT`](#group__defines_1gafcab254838b028365ae0259729e72c4e) {#group__defines_1gafcab254838b028365ae0259729e72c4e} - -#### `define `[`MIDI_TUNEREQUEST`](#group__defines_1ga8100b907b8c0a84e58b1c53dcd9bd795) {#group__defines_1ga8100b907b8c0a84e58b1c53dcd9bd795} - -#### `define `[`SYSEX_EDUMANUFID`](#group__defines_1ga5ef855ed955b00a2239ca16afbeb164f) {#group__defines_1ga5ef855ed955b00a2239ca16afbeb164f} - diff --git a/docs/internals/input_callback_reg.md b/docs/internals/input_callback_reg.md deleted file mode 100644 index 4ea132a83a..0000000000 --- a/docs/internals/input_callback_reg.md +++ /dev/null @@ -1,169 +0,0 @@ -# group `input_callback_reg` {#group__input__callback__reg} - -These are the functions you use to register your input callbacks. - -The functions are called when the appropriate midi message is matched on the associated device's input. - -## Summary - - Members | Descriptions ---------------------------------|--------------------------------------------- -`public void `[`midi_register_cc_callback`](#group__input__callback__reg_1ga64ab672abbbe393c9c4a83110c8df718)`(`[`MidiDevice`](#struct__midi__device)` * device,midi_three_byte_func_t func)` | Register a control change message (cc) callback. -`public void `[`midi_register_noteon_callback`](#group__input__callback__reg_1ga3962f276c17618923f1152779552103e)`(`[`MidiDevice`](#struct__midi__device)` * device,midi_three_byte_func_t func)` | Register a note on callback. -`public void `[`midi_register_noteoff_callback`](#group__input__callback__reg_1gac847b66051bd6d53b762958be0ec4c6d)`(`[`MidiDevice`](#struct__midi__device)` * device,midi_three_byte_func_t func)` | Register a note off callback. -`public void `[`midi_register_aftertouch_callback`](#group__input__callback__reg_1gaa95bc901bd9edff956a667c9a69dd01f)`(`[`MidiDevice`](#struct__midi__device)` * device,midi_three_byte_func_t func)` | Register an after touch callback. -`public void `[`midi_register_pitchbend_callback`](#group__input__callback__reg_1ga071a28f02ba14f53de219be70ebd9a48)`(`[`MidiDevice`](#struct__midi__device)` * device,midi_three_byte_func_t func)` | Register a pitch bend callback. -`public void `[`midi_register_songposition_callback`](#group__input__callback__reg_1gaf2adfd79637f3553d8f26deb1ca22ed6)`(`[`MidiDevice`](#struct__midi__device)` * device,midi_three_byte_func_t func)` | Register a song position callback. -`public void `[`midi_register_progchange_callback`](#group__input__callback__reg_1gae6ba1a35a4cde9bd15dd42f87401d127)`(`[`MidiDevice`](#struct__midi__device)` * device,midi_two_byte_func_t func)` | Register a program change callback. -`public void `[`midi_register_chanpressure_callback`](#group__input__callback__reg_1ga39b31f1f4fb93917ce039b958f21b4f5)`(`[`MidiDevice`](#struct__midi__device)` * device,midi_two_byte_func_t func)` | Register a channel pressure callback. -`public void `[`midi_register_songselect_callback`](#group__input__callback__reg_1gaf9aafc76a2dc4b9fdbb4106cbda6ce72)`(`[`MidiDevice`](#struct__midi__device)` * device,midi_two_byte_func_t func)` | Register a song select callback. -`public void `[`midi_register_tc_quarterframe_callback`](#group__input__callback__reg_1ga0a119fada2becc628cb15d753b257e6e)`(`[`MidiDevice`](#struct__midi__device)` * device,midi_two_byte_func_t func)` | Register a tc quarter frame callback. -`public void `[`midi_register_realtime_callback`](#group__input__callback__reg_1ga764f440e857b89084b1a07f9da2ff93a)`(`[`MidiDevice`](#struct__midi__device)` * device,midi_one_byte_func_t func)` | Register a realtime callback. -`public void `[`midi_register_tunerequest_callback`](#group__input__callback__reg_1gae40ff3ce20bda79fef87da24b8321cb1)`(`[`MidiDevice`](#struct__midi__device)` * device,midi_one_byte_func_t func)` | Register a tune request callback. -`public void `[`midi_register_sysex_callback`](#group__input__callback__reg_1ga63ce9631b025785c1848d0122d4c4c48)`(`[`MidiDevice`](#struct__midi__device)` * device,midi_sysex_func_t func)` | Register a sysex callback. -`public void `[`midi_register_fallthrough_callback`](#group__input__callback__reg_1ga7ed189164aa9682862b3181153afbd94)`(`[`MidiDevice`](#struct__midi__device)` * device,midi_var_byte_func_t func)` | Register fall through callback. -`public void `[`midi_register_catchall_callback`](#group__input__callback__reg_1ga9dbfed568d047a6cd05708f11fe39e99)`(`[`MidiDevice`](#struct__midi__device)` * device,midi_var_byte_func_t func)` | Register a catch all callback. - -## Members - -#### `public void `[`midi_register_cc_callback`](#group__input__callback__reg_1ga64ab672abbbe393c9c4a83110c8df718)`(`[`MidiDevice`](#struct__midi__device)` * device,midi_three_byte_func_t func)` {#group__input__callback__reg_1ga64ab672abbbe393c9c4a83110c8df718} - -Register a control change message (cc) callback. - -#### Parameters -* `device` the device associate with - -* `func` the callback function to register - -#### `public void `[`midi_register_noteon_callback`](#group__input__callback__reg_1ga3962f276c17618923f1152779552103e)`(`[`MidiDevice`](#struct__midi__device)` * device,midi_three_byte_func_t func)` {#group__input__callback__reg_1ga3962f276c17618923f1152779552103e} - -Register a note on callback. - -#### Parameters -* `device` the device associate with - -* `func` the callback function to register - -#### `public void `[`midi_register_noteoff_callback`](#group__input__callback__reg_1gac847b66051bd6d53b762958be0ec4c6d)`(`[`MidiDevice`](#struct__midi__device)` * device,midi_three_byte_func_t func)` {#group__input__callback__reg_1gac847b66051bd6d53b762958be0ec4c6d} - -Register a note off callback. - -#### Parameters -* `device` the device associate with - -* `func` the callback function to register - -#### `public void `[`midi_register_aftertouch_callback`](#group__input__callback__reg_1gaa95bc901bd9edff956a667c9a69dd01f)`(`[`MidiDevice`](#struct__midi__device)` * device,midi_three_byte_func_t func)` {#group__input__callback__reg_1gaa95bc901bd9edff956a667c9a69dd01f} - -Register an after touch callback. - -#### Parameters -* `device` the device associate with - -* `func` the callback function to register - -#### `public void `[`midi_register_pitchbend_callback`](#group__input__callback__reg_1ga071a28f02ba14f53de219be70ebd9a48)`(`[`MidiDevice`](#struct__midi__device)` * device,midi_three_byte_func_t func)` {#group__input__callback__reg_1ga071a28f02ba14f53de219be70ebd9a48} - -Register a pitch bend callback. - -#### Parameters -* `device` the device associate with - -* `func` the callback function to register - -#### `public void `[`midi_register_songposition_callback`](#group__input__callback__reg_1gaf2adfd79637f3553d8f26deb1ca22ed6)`(`[`MidiDevice`](#struct__midi__device)` * device,midi_three_byte_func_t func)` {#group__input__callback__reg_1gaf2adfd79637f3553d8f26deb1ca22ed6} - -Register a song position callback. - -#### Parameters -* `device` the device associate with - -* `func` the callback function to register - -#### `public void `[`midi_register_progchange_callback`](#group__input__callback__reg_1gae6ba1a35a4cde9bd15dd42f87401d127)`(`[`MidiDevice`](#struct__midi__device)` * device,midi_two_byte_func_t func)` {#group__input__callback__reg_1gae6ba1a35a4cde9bd15dd42f87401d127} - -Register a program change callback. - -#### Parameters -* `device` the device associate with - -* `func` the callback function to register - -#### `public void `[`midi_register_chanpressure_callback`](#group__input__callback__reg_1ga39b31f1f4fb93917ce039b958f21b4f5)`(`[`MidiDevice`](#struct__midi__device)` * device,midi_two_byte_func_t func)` {#group__input__callback__reg_1ga39b31f1f4fb93917ce039b958f21b4f5} - -Register a channel pressure callback. - -#### Parameters -* `device` the device associate with - -* `func` the callback function to register - -#### `public void `[`midi_register_songselect_callback`](#group__input__callback__reg_1gaf9aafc76a2dc4b9fdbb4106cbda6ce72)`(`[`MidiDevice`](#struct__midi__device)` * device,midi_two_byte_func_t func)` {#group__input__callback__reg_1gaf9aafc76a2dc4b9fdbb4106cbda6ce72} - -Register a song select callback. - -#### Parameters -* `device` the device associate with - -* `func` the callback function to register - -#### `public void `[`midi_register_tc_quarterframe_callback`](#group__input__callback__reg_1ga0a119fada2becc628cb15d753b257e6e)`(`[`MidiDevice`](#struct__midi__device)` * device,midi_two_byte_func_t func)` {#group__input__callback__reg_1ga0a119fada2becc628cb15d753b257e6e} - -Register a tc quarter frame callback. - -#### Parameters -* `device` the device associate with - -* `func` the callback function to register - -#### `public void `[`midi_register_realtime_callback`](#group__input__callback__reg_1ga764f440e857b89084b1a07f9da2ff93a)`(`[`MidiDevice`](#struct__midi__device)` * device,midi_one_byte_func_t func)` {#group__input__callback__reg_1ga764f440e857b89084b1a07f9da2ff93a} - -Register a realtime callback. - -The callback will be called for all of the real time message types. - -#### Parameters -* `device` the device associate with - -* `func` the callback function to register - -#### `public void `[`midi_register_tunerequest_callback`](#group__input__callback__reg_1gae40ff3ce20bda79fef87da24b8321cb1)`(`[`MidiDevice`](#struct__midi__device)` * device,midi_one_byte_func_t func)` {#group__input__callback__reg_1gae40ff3ce20bda79fef87da24b8321cb1} - -Register a tune request callback. - -#### Parameters -* `device` the device associate with - -* `func` the callback function to register - -#### `public void `[`midi_register_sysex_callback`](#group__input__callback__reg_1ga63ce9631b025785c1848d0122d4c4c48)`(`[`MidiDevice`](#struct__midi__device)` * device,midi_sysex_func_t func)` {#group__input__callback__reg_1ga63ce9631b025785c1848d0122d4c4c48} - -Register a sysex callback. - -#### Parameters -* `device` the device associate with - -* `func` the callback function to register - -#### `public void `[`midi_register_fallthrough_callback`](#group__input__callback__reg_1ga7ed189164aa9682862b3181153afbd94)`(`[`MidiDevice`](#struct__midi__device)` * device,midi_var_byte_func_t func)` {#group__input__callback__reg_1ga7ed189164aa9682862b3181153afbd94} - -Register fall through callback. - -This is only called if a more specific callback is not matched and called. For instance, if you don't register a note on callback but you get a note on message the fall through callback will be called, if it is registered. - -#### Parameters -* `device` the device associate with - -* `func` the callback function to register - -#### `public void `[`midi_register_catchall_callback`](#group__input__callback__reg_1ga9dbfed568d047a6cd05708f11fe39e99)`(`[`MidiDevice`](#struct__midi__device)` * device,midi_var_byte_func_t func)` {#group__input__callback__reg_1ga9dbfed568d047a6cd05708f11fe39e99} - -Register a catch all callback. - -If registered, the catch all callback is called for every message that is matched, even if a more specific or the fallthrough callback is registered. - -#### Parameters -* `device` the device associate with - -* `func` the callback function to register - diff --git a/docs/internals/midi_device.md b/docs/internals/midi_device.md deleted file mode 100644 index 5b57abd454..0000000000 --- a/docs/internals/midi_device.md +++ /dev/null @@ -1,143 +0,0 @@ -# group `midi_device` {#group__midi__device} - -You use the functions when you are implementing your own midi device. - -You set a send function to actually send bytes via your device, this method is called when you call a send function with this device, for instance midi_send_cc - -You use the midi_device_input to process input data from the device and pass it through the device's associated callbacks. - -You use the midi_device_set_pre_input_process_func if you want to have a function called at the beginning of the device's process function, generally to poll for input and pass that into midi_device_input - -## Summary - - Members | Descriptions ---------------------------------|--------------------------------------------- -`define `[`MIDI_INPUT_QUEUE_LENGTH`](#group__midi__device_1ga4aaa419caebdca2bbdfc1331e79781a8) | -`enum `[`input_state_t`](#group__midi__device_1gac203e877d3df4275ceb8e7180a61f621) | -`public void `[`midi_device_input`](#group__midi__device_1gad8d3db8eb35d9cfa51ef036a0a9d70db)`(`[`MidiDevice`](#struct__midi__device)` * device,uint8_t cnt,uint8_t * input)` | Process input bytes. This function parses bytes and calls the appropriate callbacks associated with the given device. You use this function if you are creating a custom device and you want to have midi input. -`public void `[`midi_device_set_send_func`](#group__midi__device_1ga59f5a46bdd4452f186cc73d9e96d4673)`(`[`MidiDevice`](#struct__midi__device)` * device,midi_var_byte_func_t send_func)` | Set the callback function that will be used for sending output data bytes. This is only used if you're creating a custom device. You'll most likely want the callback function to disable interrupts so that you can call the various midi send functions without worrying about locking. -`public void `[`midi_device_set_pre_input_process_func`](#group__midi__device_1ga4de0841b87c04fc23cb56b6451f33b69)`(`[`MidiDevice`](#struct__midi__device)` * device,midi_no_byte_func_t pre_process_func)` | Set a callback which is called at the beginning of the midi_device_process call. This can be used to poll for input data and send the data through the midi_device_input function. You'll probably only use this if you're creating a custom device. -`struct `[`_midi_device`](docs/api_midi_device.md#struct__midi__device) | This structure represents the input and output functions and processing data for a midi device. - -## Members - -#### `define `[`MIDI_INPUT_QUEUE_LENGTH`](#group__midi__device_1ga4aaa419caebdca2bbdfc1331e79781a8) {#group__midi__device_1ga4aaa419caebdca2bbdfc1331e79781a8} - -#### `enum `[`input_state_t`](#group__midi__device_1gac203e877d3df4275ceb8e7180a61f621) {#group__midi__device_1gac203e877d3df4275ceb8e7180a61f621} - - Values | Descriptions ---------------------------------|--------------------------------------------- -IDLE | -ONE_BYTE_MESSAGE | -TWO_BYTE_MESSAGE | -THREE_BYTE_MESSAGE | -SYSEX_MESSAGE | - -#### `public void `[`midi_device_input`](#group__midi__device_1gad8d3db8eb35d9cfa51ef036a0a9d70db)`(`[`MidiDevice`](#struct__midi__device)` * device,uint8_t cnt,uint8_t * input)` {#group__midi__device_1gad8d3db8eb35d9cfa51ef036a0a9d70db} - -Process input bytes. This function parses bytes and calls the appropriate callbacks associated with the given device. You use this function if you are creating a custom device and you want to have midi input. - -#### Parameters -* `device` the midi device to associate the input with - -* `cnt` the number of bytes you are processing - -* `input` the bytes to process - -#### `public void `[`midi_device_set_send_func`](#group__midi__device_1ga59f5a46bdd4452f186cc73d9e96d4673)`(`[`MidiDevice`](#struct__midi__device)` * device,midi_var_byte_func_t send_func)` {#group__midi__device_1ga59f5a46bdd4452f186cc73d9e96d4673} - -Set the callback function that will be used for sending output data bytes. This is only used if you're creating a custom device. You'll most likely want the callback function to disable interrupts so that you can call the various midi send functions without worrying about locking. - -#### Parameters -* `device` the midi device to associate this callback with - -* `send_func` the callback function that will do the sending - -#### `public void `[`midi_device_set_pre_input_process_func`](#group__midi__device_1ga4de0841b87c04fc23cb56b6451f33b69)`(`[`MidiDevice`](#struct__midi__device)` * device,midi_no_byte_func_t pre_process_func)` {#group__midi__device_1ga4de0841b87c04fc23cb56b6451f33b69} - -Set a callback which is called at the beginning of the midi_device_process call. This can be used to poll for input data and send the data through the midi_device_input function. You'll probably only use this if you're creating a custom device. - -#### Parameters -* `device` the midi device to associate this callback with - -* `midi_no_byte_func_t` the actual callback function - -# struct `_midi_device` {#struct__midi__device} - -This structure represents the input and output functions and processing data for a midi device. - -A device can represent an actual physical device [serial port, usb port] or something virtual. You should not need to modify this structure directly. - -## Summary - - Members | Descriptions ---------------------------------|--------------------------------------------- -`public midi_var_byte_func_t `[`send_func`](docs/api_midi_device.md#struct__midi__device_1a25d4c94b4bbccd5b98f1032b469f3ff9) | -`public midi_three_byte_func_t `[`input_cc_callback`](docs/api_midi_device.md#struct__midi__device_1a6da5236c1bc73877728df92d213a78d1) | -`public midi_three_byte_func_t `[`input_noteon_callback`](docs/api_midi_device.md#struct__midi__device_1aa10b15cf1a7fb825a5df0d2abbe34a1c) | -`public midi_three_byte_func_t `[`input_noteoff_callback`](docs/api_midi_device.md#struct__midi__device_1aaf290043078534d3a5a0ea4c840eba84) | -`public midi_three_byte_func_t `[`input_aftertouch_callback`](docs/api_midi_device.md#struct__midi__device_1acb0b4901c545cec4b28b126f2d8c315f) | -`public midi_three_byte_func_t `[`input_pitchbend_callback`](docs/api_midi_device.md#struct__midi__device_1a305fea672caeb996f2233bf8cd2bef18) | -`public midi_three_byte_func_t `[`input_songposition_callback`](docs/api_midi_device.md#struct__midi__device_1a5f3f13638b3fef3fc561ed1bf301d586) | -`public midi_two_byte_func_t `[`input_progchange_callback`](docs/api_midi_device.md#struct__midi__device_1adaf1da617c9a10a9dcad00ab1959d3da) | -`public midi_two_byte_func_t `[`input_chanpressure_callback`](docs/api_midi_device.md#struct__midi__device_1ab7ca2925c539915d43974eff604d85f7) | -`public midi_two_byte_func_t `[`input_songselect_callback`](docs/api_midi_device.md#struct__midi__device_1a89bed8a5a55376120cfc0a62b42f057f) | -`public midi_two_byte_func_t `[`input_tc_quarterframe_callback`](docs/api_midi_device.md#struct__midi__device_1ad9813e75d22e284f9f65a907d20600f0) | -`public midi_one_byte_func_t `[`input_realtime_callback`](docs/api_midi_device.md#struct__midi__device_1a9448eba4afb7e43650434748db3777be) | -`public midi_one_byte_func_t `[`input_tunerequest_callback`](docs/api_midi_device.md#struct__midi__device_1a0cb8fd53e00cf1d4202d4fa04d038e8d) | -`public midi_sysex_func_t `[`input_sysex_callback`](docs/api_midi_device.md#struct__midi__device_1afff9a0ce641762aaef24c1e6953ec9a2) | -`public midi_var_byte_func_t `[`input_fallthrough_callback`](docs/api_midi_device.md#struct__midi__device_1abb974ec6d734001b4a0e370f292be503) | -`public midi_var_byte_func_t `[`input_catchall_callback`](docs/api_midi_device.md#struct__midi__device_1aae0d535129d4fd650edc98eb3f7584f8) | -`public midi_no_byte_func_t `[`pre_input_process_callback`](docs/api_midi_device.md#struct__midi__device_1aeb0bb8923d66c23d874e177dc4265754) | -`public uint8_t `[`input_buffer`](docs/api_midi_device.md#struct__midi__device_1a7c5684857d6af4ebc4dc12da27bd6b2a) | -`public input_state_t `[`input_state`](docs/api_midi_device.md#struct__midi__device_1a69a687d2d1c449ec15a11c07a5722e39) | -`public uint16_t `[`input_count`](docs/api_midi_device.md#struct__midi__device_1a68dea8e7b6151e89c85c95caa612ee5d) | -`public uint8_t `[`input_queue_data`](docs/api_midi_device.md#struct__midi__device_1ada41de021135dc423abedcbb30f366ff) | -`public `[`byteQueue_t`](#structbyte_queue__t)` `[`input_queue`](#struct__midi__device_1a49c8538a8a02193c58e28a56eb695d8f) | - -## Members - -#### `public midi_var_byte_func_t `[`send_func`](docs/api_midi_device.md#struct__midi__device_1a25d4c94b4bbccd5b98f1032b469f3ff9) {#struct__midi__device_1a25d4c94b4bbccd5b98f1032b469f3ff9} - -#### `public midi_three_byte_func_t `[`input_cc_callback`](docs/api_midi_device.md#struct__midi__device_1a6da5236c1bc73877728df92d213a78d1) {#struct__midi__device_1a6da5236c1bc73877728df92d213a78d1} - -#### `public midi_three_byte_func_t `[`input_noteon_callback`](docs/api_midi_device.md#struct__midi__device_1aa10b15cf1a7fb825a5df0d2abbe34a1c) {#struct__midi__device_1aa10b15cf1a7fb825a5df0d2abbe34a1c} - -#### `public midi_three_byte_func_t `[`input_noteoff_callback`](docs/api_midi_device.md#struct__midi__device_1aaf290043078534d3a5a0ea4c840eba84) {#struct__midi__device_1aaf290043078534d3a5a0ea4c840eba84} - -#### `public midi_three_byte_func_t `[`input_aftertouch_callback`](docs/api_midi_device.md#struct__midi__device_1acb0b4901c545cec4b28b126f2d8c315f) {#struct__midi__device_1acb0b4901c545cec4b28b126f2d8c315f} - -#### `public midi_three_byte_func_t `[`input_pitchbend_callback`](docs/api_midi_device.md#struct__midi__device_1a305fea672caeb996f2233bf8cd2bef18) {#struct__midi__device_1a305fea672caeb996f2233bf8cd2bef18} - -#### `public midi_three_byte_func_t `[`input_songposition_callback`](docs/api_midi_device.md#struct__midi__device_1a5f3f13638b3fef3fc561ed1bf301d586) {#struct__midi__device_1a5f3f13638b3fef3fc561ed1bf301d586} - -#### `public midi_two_byte_func_t `[`input_progchange_callback`](docs/api_midi_device.md#struct__midi__device_1adaf1da617c9a10a9dcad00ab1959d3da) {#struct__midi__device_1adaf1da617c9a10a9dcad00ab1959d3da} - -#### `public midi_two_byte_func_t `[`input_chanpressure_callback`](docs/api_midi_device.md#struct__midi__device_1ab7ca2925c539915d43974eff604d85f7) {#struct__midi__device_1ab7ca2925c539915d43974eff604d85f7} - -#### `public midi_two_byte_func_t `[`input_songselect_callback`](docs/api_midi_device.md#struct__midi__device_1a89bed8a5a55376120cfc0a62b42f057f) {#struct__midi__device_1a89bed8a5a55376120cfc0a62b42f057f} - -#### `public midi_two_byte_func_t `[`input_tc_quarterframe_callback`](docs/api_midi_device.md#struct__midi__device_1ad9813e75d22e284f9f65a907d20600f0) {#struct__midi__device_1ad9813e75d22e284f9f65a907d20600f0} - -#### `public midi_one_byte_func_t `[`input_realtime_callback`](docs/api_midi_device.md#struct__midi__device_1a9448eba4afb7e43650434748db3777be) {#struct__midi__device_1a9448eba4afb7e43650434748db3777be} - -#### `public midi_one_byte_func_t `[`input_tunerequest_callback`](docs/api_midi_device.md#struct__midi__device_1a0cb8fd53e00cf1d4202d4fa04d038e8d) {#struct__midi__device_1a0cb8fd53e00cf1d4202d4fa04d038e8d} - -#### `public midi_sysex_func_t `[`input_sysex_callback`](docs/api_midi_device.md#struct__midi__device_1afff9a0ce641762aaef24c1e6953ec9a2) {#struct__midi__device_1afff9a0ce641762aaef24c1e6953ec9a2} - -#### `public midi_var_byte_func_t `[`input_fallthrough_callback`](docs/api_midi_device.md#struct__midi__device_1abb974ec6d734001b4a0e370f292be503) {#struct__midi__device_1abb974ec6d734001b4a0e370f292be503} - -#### `public midi_var_byte_func_t `[`input_catchall_callback`](docs/api_midi_device.md#struct__midi__device_1aae0d535129d4fd650edc98eb3f7584f8) {#struct__midi__device_1aae0d535129d4fd650edc98eb3f7584f8} - -#### `public midi_no_byte_func_t `[`pre_input_process_callback`](docs/api_midi_device.md#struct__midi__device_1aeb0bb8923d66c23d874e177dc4265754) {#struct__midi__device_1aeb0bb8923d66c23d874e177dc4265754} - -#### `public uint8_t `[`input_buffer`](docs/api_midi_device.md#struct__midi__device_1a7c5684857d6af4ebc4dc12da27bd6b2a) {#struct__midi__device_1a7c5684857d6af4ebc4dc12da27bd6b2a} - -#### `public input_state_t `[`input_state`](docs/api_midi_device.md#struct__midi__device_1a69a687d2d1c449ec15a11c07a5722e39) {#struct__midi__device_1a69a687d2d1c449ec15a11c07a5722e39} - -#### `public uint16_t `[`input_count`](docs/api_midi_device.md#struct__midi__device_1a68dea8e7b6151e89c85c95caa612ee5d) {#struct__midi__device_1a68dea8e7b6151e89c85c95caa612ee5d} - -#### `public uint8_t `[`input_queue_data`](docs/api_midi_device.md#struct__midi__device_1ada41de021135dc423abedcbb30f366ff) {#struct__midi__device_1ada41de021135dc423abedcbb30f366ff} - -#### `public `[`byteQueue_t`](#structbyte_queue__t)` `[`input_queue`](#struct__midi__device_1a49c8538a8a02193c58e28a56eb695d8f) {#struct__midi__device_1a49c8538a8a02193c58e28a56eb695d8f} - diff --git a/docs/internals/midi_device_setup_process.md b/docs/internals/midi_device_setup_process.md deleted file mode 100644 index ae82197c5c..0000000000 --- a/docs/internals/midi_device_setup_process.md +++ /dev/null @@ -1,31 +0,0 @@ -# group `midi_device_setup_process` {#group__midi__device__setup__process} - -These are method that you must use to initialize and run a device. - -## Summary - - Members | Descriptions ---------------------------------|--------------------------------------------- -`public void `[`midi_device_init`](#group__midi__device__setup__process_1gaf29deddc94ea98a59daa0bde1aefd9d9)`(`[`MidiDevice`](#struct__midi__device)` * device)` | Initialize a device. -`public void `[`midi_device_process`](#group__midi__device__setup__process_1gaa3d5993d0e998a1b59bbf5ab9c7b492b)`(`[`MidiDevice`](#struct__midi__device)` * device)` | Process input data. - -## Members - -#### `public void `[`midi_device_init`](#group__midi__device__setup__process_1gaf29deddc94ea98a59daa0bde1aefd9d9)`(`[`MidiDevice`](#struct__midi__device)` * device)` {#group__midi__device__setup__process_1gaf29deddc94ea98a59daa0bde1aefd9d9} - -Initialize a device. - -You must call this before using the device in question. - -#### Parameters -* `device` the device to initialize - -#### `public void `[`midi_device_process`](#group__midi__device__setup__process_1gaa3d5993d0e998a1b59bbf5ab9c7b492b)`(`[`MidiDevice`](#struct__midi__device)` * device)` {#group__midi__device__setup__process_1gaa3d5993d0e998a1b59bbf5ab9c7b492b} - -Process input data. - -This method drives the input processing, you must call this method frequently if you expect to have your input callbacks called. - -#### Parameters -* `device` the device to process - diff --git a/docs/internals/midi_util.md b/docs/internals/midi_util.md deleted file mode 100644 index 97821bd180..0000000000 --- a/docs/internals/midi_util.md +++ /dev/null @@ -1,54 +0,0 @@ -# group `midi_util` {#group__midi__util} - -## Summary - - Members | Descriptions ---------------------------------|--------------------------------------------- -`enum `[`midi_packet_length_t`](#group__midi__util_1gae29ff56aee2b430ffe53933b97e5e79e) | An enumeration of the possible packet length values. -`public bool `[`midi_is_statusbyte`](#group__midi__util_1ga12e3b42ff9cbb4b4f2bc455fc8743ee5)`(uint8_t theByte)` | Test to see if the byte given is a status byte. -`public bool `[`midi_is_realtime`](#group__midi__util_1gad2f52c363e34a8000d80c983c324e2d7)`(uint8_t theByte)` | Test to see if the byte given is a realtime message. -`public `[`midi_packet_length_t`](#group__midi__util_1gae29ff56aee2b430ffe53933b97e5e79e)` `[`midi_packet_length`](#group__midi__util_1gaa168b43af6ae9de0debce1625e4b8175)`(uint8_t status)` | Find the length of the packet associated with the status byte given. - -## Members - -#### `enum `[`midi_packet_length_t`](#group__midi__util_1gae29ff56aee2b430ffe53933b97e5e79e) {#group__midi__util_1gae29ff56aee2b430ffe53933b97e5e79e} - - Values | Descriptions ---------------------------------|--------------------------------------------- -UNDEFINED | -ONE | -TWO | -THREE | - -An enumeration of the possible packet length values. - -#### `public bool `[`midi_is_statusbyte`](#group__midi__util_1ga12e3b42ff9cbb4b4f2bc455fc8743ee5)`(uint8_t theByte)` {#group__midi__util_1ga12e3b42ff9cbb4b4f2bc455fc8743ee5} - -Test to see if the byte given is a status byte. - -#### Parameters -* `theByte` the byte to test - -#### Returns -true if the byte given is a midi status byte - -#### `public bool `[`midi_is_realtime`](#group__midi__util_1gad2f52c363e34a8000d80c983c324e2d7)`(uint8_t theByte)` {#group__midi__util_1gad2f52c363e34a8000d80c983c324e2d7} - -Test to see if the byte given is a realtime message. - -#### Parameters -* `theByte` the byte to test - -#### Returns -true if it is a realtime message, false otherwise - -#### `public `[`midi_packet_length_t`](#group__midi__util_1gae29ff56aee2b430ffe53933b97e5e79e)` `[`midi_packet_length`](#group__midi__util_1gaa168b43af6ae9de0debce1625e4b8175)`(uint8_t status)` {#group__midi__util_1gaa168b43af6ae9de0debce1625e4b8175} - -Find the length of the packet associated with the status byte given. - -#### Parameters -* `status` the status byte - -#### Returns -the length of the packet, will return UNDEFINED if the byte is not a status byte or if it is a sysex status byte - diff --git a/docs/internals/send_functions.md b/docs/internals/send_functions.md deleted file mode 100644 index b331508008..0000000000 --- a/docs/internals/send_functions.md +++ /dev/null @@ -1,241 +0,0 @@ -# group `send_functions` {#group__send__functions} - -These are the functions you use to send midi data through a device. - -## Summary - - Members | Descriptions ---------------------------------|--------------------------------------------- -`public void `[`midi_send_cc`](#group__send__functions_1gaaf884811c92df405ca8fe1a00082f960)`(`[`MidiDevice`](#struct__midi__device)` * device,uint8_t chan,uint8_t num,uint8_t val)` | Send a control change message (cc) via the given device. -`public void `[`midi_send_noteon`](#group__send__functions_1ga467bcf46dbf03ec269ce565b46bc2775)`(`[`MidiDevice`](#struct__midi__device)` * device,uint8_t chan,uint8_t num,uint8_t vel)` | Send a note on message via the given device. -`public void `[`midi_send_noteoff`](#group__send__functions_1gaedb7d8805425eef5d47d57ddcb4c7a49)`(`[`MidiDevice`](#struct__midi__device)` * device,uint8_t chan,uint8_t num,uint8_t vel)` | Send a note off message via the given device. -`public void `[`midi_send_aftertouch`](#group__send__functions_1ga0014847571317a0e34b2ef46a6bc584f)`(`[`MidiDevice`](#struct__midi__device)` * device,uint8_t chan,uint8_t note_num,uint8_t amt)` | Send an after touch message via the given device. -`public void `[`midi_send_pitchbend`](#group__send__functions_1gae5a4a1e71611e7534be80af9ce3d3491)`(`[`MidiDevice`](#struct__midi__device)` * device,uint8_t chan,int16_t amt)` | Send a pitch bend message via the given device. -`public void `[`midi_send_programchange`](#group__send__functions_1ga7b15588ef25e5e1ff09c2afc3151ce86)`(`[`MidiDevice`](#struct__midi__device)` * device,uint8_t chan,uint8_t num)` | Send a program change message via the given device. -`public void `[`midi_send_channelpressure`](#group__send__functions_1gaf23e69fdf812e89c0036f51f88ab2e1b)`(`[`MidiDevice`](#struct__midi__device)` * device,uint8_t chan,uint8_t amt)` | Send a channel pressure message via the given device. -`public void `[`midi_send_clock`](#group__send__functions_1ga4e1b11a7cdb0875f6e03ce7c79c581aa)`(`[`MidiDevice`](#struct__midi__device)` * device)` | Send a clock message via the given device. -`public void `[`midi_send_tick`](#group__send__functions_1ga2b43c7d433d940c5b907595aac947972)`(`[`MidiDevice`](#struct__midi__device)` * device)` | Send a tick message via the given device. -`public void `[`midi_send_start`](#group__send__functions_1ga1569749a8d58ccc56789289d7c7245cc)`(`[`MidiDevice`](#struct__midi__device)` * device)` | Send a start message via the given device. -`public void `[`midi_send_continue`](#group__send__functions_1gaed5dc29d754a27372e89ab8bc20ee120)`(`[`MidiDevice`](#struct__midi__device)` * device)` | Send a continue message via the given device. -`public void `[`midi_send_stop`](#group__send__functions_1ga026e1a620276cb653ac501aa0d12a988)`(`[`MidiDevice`](#struct__midi__device)` * device)` | Send a stop message via the given device. -`public void `[`midi_send_activesense`](#group__send__functions_1ga9b6e4c6ce4719d2604187b325620db37)`(`[`MidiDevice`](#struct__midi__device)` * device)` | Send an active sense message via the given device. -`public void `[`midi_send_reset`](#group__send__functions_1ga3671e39a6d93ca9568fc493001af1b1b)`(`[`MidiDevice`](#struct__midi__device)` * device)` | Send a reset message via the given device. -`public void `[`midi_send_tcquarterframe`](#group__send__functions_1ga5b85639910eec280bb744c934d0fd45a)`(`[`MidiDevice`](#struct__midi__device)` * device,uint8_t time)` | Send a tc quarter frame message via the given device. -`public void `[`midi_send_songposition`](#group__send__functions_1gab1c9eeef3b57a8cd2e6128d18e85eb7f)`(`[`MidiDevice`](#struct__midi__device)` * device,uint16_t pos)` | Send a song position message via the given device. -`public void `[`midi_send_songselect`](#group__send__functions_1ga42de7838ba70d949af9a50f9facc3c50)`(`[`MidiDevice`](#struct__midi__device)` * device,uint8_t song)` | Send a song select message via the given device. -`public void `[`midi_send_tunerequest`](#group__send__functions_1ga8db6c7e04d48e4d2266dd59118ca0656)`(`[`MidiDevice`](#struct__midi__device)` * device)` | Send a tune request message via the given device. -`public void `[`midi_send_byte`](#group__send__functions_1ga857e85eb90b288385642d4d991e09881)`(`[`MidiDevice`](#struct__midi__device)` * device,uint8_t b)` | Send a byte via the given device. -`public void `[`midi_send_data`](#group__send__functions_1ga36e2f2e45369d911b76969361679054b)`(`[`MidiDevice`](#struct__midi__device)` * device,uint16_t count,uint8_t byte0,uint8_t byte1,uint8_t byte2)` | Send up to 3 bytes of data. -`public void `[`midi_send_array`](#group__send__functions_1ga245243cb1da18d2cea18d4b18d846ead)`(`[`MidiDevice`](#struct__midi__device)` * device,uint16_t count,uint8_t * array)` | Send an array of formatted midi data. - -## Members - -#### `public void `[`midi_send_cc`](#group__send__functions_1gaaf884811c92df405ca8fe1a00082f960)`(`[`MidiDevice`](#struct__midi__device)` * device,uint8_t chan,uint8_t num,uint8_t val)` {#group__send__functions_1gaaf884811c92df405ca8fe1a00082f960} - -Send a control change message (cc) via the given device. - -#### Parameters -* `device` the device to use for sending - -* `chan` the channel to send on, 0-15 - -* `num` the cc num - -* `val` the value of that cc num - -#### `public void `[`midi_send_noteon`](#group__send__functions_1ga467bcf46dbf03ec269ce565b46bc2775)`(`[`MidiDevice`](#struct__midi__device)` * device,uint8_t chan,uint8_t num,uint8_t vel)` {#group__send__functions_1ga467bcf46dbf03ec269ce565b46bc2775} - -Send a note on message via the given device. - -#### Parameters -* `device` the device to use for sending - -* `chan` the channel to send on, 0-15 - -* `num` the note number - -* `vel` the note velocity - -#### `public void `[`midi_send_noteoff`](#group__send__functions_1gaedb7d8805425eef5d47d57ddcb4c7a49)`(`[`MidiDevice`](#struct__midi__device)` * device,uint8_t chan,uint8_t num,uint8_t vel)` {#group__send__functions_1gaedb7d8805425eef5d47d57ddcb4c7a49} - -Send a note off message via the given device. - -#### Parameters -* `device` the device to use for sending - -* `chan` the channel to send on, 0-15 - -* `num` the note number - -* `vel` the note velocity - -#### `public void `[`midi_send_aftertouch`](#group__send__functions_1ga0014847571317a0e34b2ef46a6bc584f)`(`[`MidiDevice`](#struct__midi__device)` * device,uint8_t chan,uint8_t note_num,uint8_t amt)` {#group__send__functions_1ga0014847571317a0e34b2ef46a6bc584f} - -Send an after touch message via the given device. - -#### Parameters -* `device` the device to use for sending - -* `chan` the channel to send on, 0-15 - -* `note_num` the note number - -* `amt` the after touch amount - -#### `public void `[`midi_send_pitchbend`](#group__send__functions_1gae5a4a1e71611e7534be80af9ce3d3491)`(`[`MidiDevice`](#struct__midi__device)` * device,uint8_t chan,int16_t amt)` {#group__send__functions_1gae5a4a1e71611e7534be80af9ce3d3491} - -Send a pitch bend message via the given device. - -#### Parameters -* `device` the device to use for sending - -* `chan` the channel to send on, 0-15 - -* `amt` the bend amount range: -8192..8191, 0 means no bend - -#### `public void `[`midi_send_programchange`](#group__send__functions_1ga7b15588ef25e5e1ff09c2afc3151ce86)`(`[`MidiDevice`](#struct__midi__device)` * device,uint8_t chan,uint8_t num)` {#group__send__functions_1ga7b15588ef25e5e1ff09c2afc3151ce86} - -Send a program change message via the given device. - -#### Parameters -* `device` the device to use for sending - -* `chan` the channel to send on, 0-15 - -* `num` the program to change to - -#### `public void `[`midi_send_channelpressure`](#group__send__functions_1gaf23e69fdf812e89c0036f51f88ab2e1b)`(`[`MidiDevice`](#struct__midi__device)` * device,uint8_t chan,uint8_t amt)` {#group__send__functions_1gaf23e69fdf812e89c0036f51f88ab2e1b} - -Send a channel pressure message via the given device. - -#### Parameters -* `device` the device to use for sending - -* `chan` the channel to send on, 0-15 - -* `amt` the amount of channel pressure - -#### `public void `[`midi_send_clock`](#group__send__functions_1ga4e1b11a7cdb0875f6e03ce7c79c581aa)`(`[`MidiDevice`](#struct__midi__device)` * device)` {#group__send__functions_1ga4e1b11a7cdb0875f6e03ce7c79c581aa} - -Send a clock message via the given device. - -#### Parameters -* `device` the device to use for sending - -#### `public void `[`midi_send_tick`](#group__send__functions_1ga2b43c7d433d940c5b907595aac947972)`(`[`MidiDevice`](#struct__midi__device)` * device)` {#group__send__functions_1ga2b43c7d433d940c5b907595aac947972} - -Send a tick message via the given device. - -#### Parameters -* `device` the device to use for sending - -#### `public void `[`midi_send_start`](#group__send__functions_1ga1569749a8d58ccc56789289d7c7245cc)`(`[`MidiDevice`](#struct__midi__device)` * device)` {#group__send__functions_1ga1569749a8d58ccc56789289d7c7245cc} - -Send a start message via the given device. - -#### Parameters -* `device` the device to use for sending - -#### `public void `[`midi_send_continue`](#group__send__functions_1gaed5dc29d754a27372e89ab8bc20ee120)`(`[`MidiDevice`](#struct__midi__device)` * device)` {#group__send__functions_1gaed5dc29d754a27372e89ab8bc20ee120} - -Send a continue message via the given device. - -#### Parameters -* `device` the device to use for sending - -#### `public void `[`midi_send_stop`](#group__send__functions_1ga026e1a620276cb653ac501aa0d12a988)`(`[`MidiDevice`](#struct__midi__device)` * device)` {#group__send__functions_1ga026e1a620276cb653ac501aa0d12a988} - -Send a stop message via the given device. - -#### Parameters -* `device` the device to use for sending - -#### `public void `[`midi_send_activesense`](#group__send__functions_1ga9b6e4c6ce4719d2604187b325620db37)`(`[`MidiDevice`](#struct__midi__device)` * device)` {#group__send__functions_1ga9b6e4c6ce4719d2604187b325620db37} - -Send an active sense message via the given device. - -#### Parameters -* `device` the device to use for sending - -#### `public void `[`midi_send_reset`](#group__send__functions_1ga3671e39a6d93ca9568fc493001af1b1b)`(`[`MidiDevice`](#struct__midi__device)` * device)` {#group__send__functions_1ga3671e39a6d93ca9568fc493001af1b1b} - -Send a reset message via the given device. - -#### Parameters -* `device` the device to use for sending - -#### `public void `[`midi_send_tcquarterframe`](#group__send__functions_1ga5b85639910eec280bb744c934d0fd45a)`(`[`MidiDevice`](#struct__midi__device)` * device,uint8_t time)` {#group__send__functions_1ga5b85639910eec280bb744c934d0fd45a} - -Send a tc quarter frame message via the given device. - -#### Parameters -* `device` the device to use for sending - -* `time` the time of this quarter frame, range 0..16383 - -#### `public void `[`midi_send_songposition`](#group__send__functions_1gab1c9eeef3b57a8cd2e6128d18e85eb7f)`(`[`MidiDevice`](#struct__midi__device)` * device,uint16_t pos)` {#group__send__functions_1gab1c9eeef3b57a8cd2e6128d18e85eb7f} - -Send a song position message via the given device. - -#### Parameters -* `device` the device to use for sending - -* `pos` the song position - -#### `public void `[`midi_send_songselect`](#group__send__functions_1ga42de7838ba70d949af9a50f9facc3c50)`(`[`MidiDevice`](#struct__midi__device)` * device,uint8_t song)` {#group__send__functions_1ga42de7838ba70d949af9a50f9facc3c50} - -Send a song select message via the given device. - -#### Parameters -* `device` the device to use for sending - -* `song` the song to select - -#### `public void `[`midi_send_tunerequest`](#group__send__functions_1ga8db6c7e04d48e4d2266dd59118ca0656)`(`[`MidiDevice`](#struct__midi__device)` * device)` {#group__send__functions_1ga8db6c7e04d48e4d2266dd59118ca0656} - -Send a tune request message via the given device. - -#### Parameters -* `device` the device to use for sending - -#### `public void `[`midi_send_byte`](#group__send__functions_1ga857e85eb90b288385642d4d991e09881)`(`[`MidiDevice`](#struct__midi__device)` * device,uint8_t b)` {#group__send__functions_1ga857e85eb90b288385642d4d991e09881} - -Send a byte via the given device. - -This is a generic method for sending data via the given midi device. This would be useful for sending sysex data or messages that are not implemented in this API, if there are any. Please contact the author if you find some so we can add them. - -#### Parameters -* `device` the device to use for sending - -* `b` the byte to send - -#### `public void `[`midi_send_data`](#group__send__functions_1ga36e2f2e45369d911b76969361679054b)`(`[`MidiDevice`](#struct__midi__device)` * device,uint16_t count,uint8_t byte0,uint8_t byte1,uint8_t byte2)` {#group__send__functions_1ga36e2f2e45369d911b76969361679054b} - -Send up to 3 bytes of data. - -% 4 is applied to count so that you can use this to pass sysex through - -#### Parameters -* `device` the device to use for sending - -* `count` the count of bytes to send, %4 is applied - -* `byte0` the first byte - -* `byte1` the second byte, ignored if cnt % 4 != 2 - -* `byte2` the third byte, ignored if cnt % 4 != 3 - -#### `public void `[`midi_send_array`](#group__send__functions_1ga245243cb1da18d2cea18d4b18d846ead)`(`[`MidiDevice`](#struct__midi__device)` * device,uint16_t count,uint8_t * array)` {#group__send__functions_1ga245243cb1da18d2cea18d4b18d846ead} - -Send an array of formatted midi data. - -Can be used for sysex. - -#### Parameters -* `device` the device to use for sending - -* `count` the count of bytes to send - -* `array` the array of bytes - diff --git a/docs/internals/sysex_tools.md b/docs/internals/sysex_tools.md deleted file mode 100644 index 55dbe9e164..0000000000 --- a/docs/internals/sysex_tools.md +++ /dev/null @@ -1,61 +0,0 @@ -# group `sysex_tools` {#group__sysex__tools} - -## Summary - - Members | Descriptions ---------------------------------|--------------------------------------------- -`public uint16_t `[`sysex_encoded_length`](#group__sysex__tools_1ga061e5607030412d6e62e2390d8013f0a)`(uint16_t decoded_length)` | Compute the length of a message after it is encoded. -`public uint16_t `[`sysex_decoded_length`](#group__sysex__tools_1ga121fc227d3acc1c0ea08c9a5c26fa3b0)`(uint16_t encoded_length)` | Compute the length of a message after it is decoded. -`public uint16_t `[`sysex_encode`](#group__sysex__tools_1ga54d77f8d32f92a6f329daefa2b314742)`(uint8_t * encoded,const uint8_t * source,uint16_t length)` | Encode data so that it can be transmitted safely in a sysex message. -`public uint16_t `[`sysex_decode`](#group__sysex__tools_1gaaad1d9ba2d5eca709a0ab4ba40662229)`(uint8_t * decoded,const uint8_t * source,uint16_t length)` | Decode encoded data. - -## Members - -#### `public uint16_t `[`sysex_encoded_length`](#group__sysex__tools_1ga061e5607030412d6e62e2390d8013f0a)`(uint16_t decoded_length)` {#group__sysex__tools_1ga061e5607030412d6e62e2390d8013f0a} - -Compute the length of a message after it is encoded. - -#### Parameters -* `decoded_length` The length, in bytes, of the message to encode. - -#### Returns -The length, in bytes, of the message after encodeing. - -#### `public uint16_t `[`sysex_decoded_length`](#group__sysex__tools_1ga121fc227d3acc1c0ea08c9a5c26fa3b0)`(uint16_t encoded_length)` {#group__sysex__tools_1ga121fc227d3acc1c0ea08c9a5c26fa3b0} - -Compute the length of a message after it is decoded. - -#### Parameters -* `encoded_length` The length, in bytes, of the encoded message. - -#### Returns -The length, in bytes, of the message after it is decoded. - -#### `public uint16_t `[`sysex_encode`](#group__sysex__tools_1ga54d77f8d32f92a6f329daefa2b314742)`(uint8_t * encoded,const uint8_t * source,uint16_t length)` {#group__sysex__tools_1ga54d77f8d32f92a6f329daefa2b314742} - -Encode data so that it can be transmitted safely in a sysex message. - -#### Parameters -* `encoded` The output data buffer, must be at least sysex_encoded_length(length) bytes long. - -* `source` The input buffer of data to be encoded. - -* `length` The number of bytes from the input buffer to encode. - -#### Returns -number of bytes encoded. - -#### `public uint16_t `[`sysex_decode`](#group__sysex__tools_1gaaad1d9ba2d5eca709a0ab4ba40662229)`(uint8_t * decoded,const uint8_t * source,uint16_t length)` {#group__sysex__tools_1gaaad1d9ba2d5eca709a0ab4ba40662229} - -Decode encoded data. - -#### Parameters -* `decoded` The output data buffer, must be at least sysex_decoded_length(length) bytes long. - -* `source` The input buffer of data to be decoded. - -* `length` The number of bytes from the input buffer to decode. - -#### Returns -number of bytes decoded. - diff --git a/docs/isp_flashing_guide.md b/docs/isp_flashing_guide.md index 80fd1ddda1..afebcc6ad6 100644 --- a/docs/isp_flashing_guide.md +++ b/docs/isp_flashing_guide.md @@ -33,7 +33,9 @@ To use a 5V/16MHz Pro Micro as an ISP flashing tool, you will first need to load |`16` (`B2`)|`MOSI` | |`14` (`B3`)|`MISO` | -!> Note that the `10` pin on the Pro Micro should be wired to the `RESET` pin on the keyboard's controller. ***DO NOT*** connect the `RESET` pin on the Pro Micro to the `RESET` on the keyboard. +::: warning +Note that the `10` pin on the Pro Micro should be wired to the `RESET` pin on the keyboard's controller. ***DO NOT*** connect the `RESET` pin on the Pro Micro to the `RESET` on the keyboard. +::: ### Arduino Uno / Micro as ISP @@ -66,7 +68,9 @@ A standard Uno or Micro can be used as an ISP flashing tool using the [example " |`16` (`B2`)|`MOSI` | |`14` (`B3`)|`MISO` | -!> Note that the `10` pin on the Uno/Micro should be wired to the `RESET` pin on the keyboard's controller. ***DO NOT*** connect the `RESET` pin on the Uno/Micro to the `RESET` on the keyboard. +::: warning +Note that the `10` pin on the Uno/Micro should be wired to the `RESET` pin on the keyboard's controller. ***DO NOT*** connect the `RESET` pin on the Uno/Micro to the `RESET` on the keyboard. +::: ### Teensy 2.0 as ISP @@ -89,7 +93,9 @@ To use a Teensy 2.0 as an ISP flashing tool, you will first need to load a [spec |`B2` |`MOSI` | |`B3` |`MISO` | -!> Note that the `B0` pin on the Teensy should be wired to the `RESET` pin on the keyboard's controller. ***DO NOT*** connect the `RESET` pin on the Teensy to the `RESET` on the keyboard. +::: warning +Note that the `B0` pin on the Teensy should be wired to the `RESET` pin on the keyboard's controller. ***DO NOT*** connect the `RESET` pin on the Teensy to the `RESET` on the keyboard. +::: ### SparkFun PocketAVR / USBtinyISP @@ -97,7 +103,9 @@ To use a Teensy 2.0 as an ISP flashing tool, you will first need to load a [spec [SparkFun PocketAVR](https://www.sparkfun.com/products/9825) [Adafruit USBtinyISP](https://www.adafruit.com/product/46) -!> SparkFun PocketAVR and USBtinyISP **DO NOT support** AVR chips with more than 64 KiB of flash (e.g., the AT90USB128 series). This limitation is mentioned on the [shop page for SparkFun PocketAVR](https://www.sparkfun.com/products/9825) and in the [FAQ for USBtinyISP](https://learn.adafruit.com/usbtinyisp/f-a-q#faq-2270879). If you try to use one of these programmers with AT90USB128 chips, you will get verification errors from `avrdude`, and the bootloader won't be flashed properly (e.g., see the [issue #3286](https://github.com/qmk/qmk_firmware/issues/3286)). +::: warning +SparkFun PocketAVR and USBtinyISP **DO NOT support** AVR chips with more than 64 KiB of flash (e.g., the AT90USB128 series). This limitation is mentioned on the [shop page for SparkFun PocketAVR](https://www.sparkfun.com/products/9825) and in the [FAQ for USBtinyISP](https://learn.adafruit.com/usbtinyisp/f-a-q#faq-2270879). If you try to use one of these programmers with AT90USB128 chips, you will get verification errors from `avrdude`, and the bootloader won't be flashed properly (e.g., see the [issue #3286](https://github.com/qmk/qmk_firmware/issues/3286)). +::: **AVRDUDE Programmer**: `usbtiny` **AVRDUDE Port**: `usb` @@ -137,7 +145,9 @@ To use a Teensy 2.0 as an ISP flashing tool, you will first need to load a [spec [Adafruit Bus Pirate](https://www.adafruit.com/product/237) -!> The 5-pin "ICSP" header is for ISP flashing the PIC microcontroller of the Bus Pirate. Connect your target board to the 10-pin header opposite the USB connector instead. +::: warning +The 5-pin "ICSP" header is for ISP flashing the PIC microcontroller of the Bus Pirate. Connect your target board to the 10-pin header opposite the USB connector instead. +::: **AVRDUDE Programmer**: `buspirate` **AVRDUDE Port**: Serial @@ -157,7 +167,7 @@ To use a Teensy 2.0 as an ISP flashing tool, you will first need to load a [spec [QMK Toolbox](https://github.com/qmk/qmk_toolbox/releases) supports flashing both the ISP firmware and bootloader, but note that it cannot (currently) set the AVR fuse bytes for the actual ISP flashing step, so you may want to work with `avrdude` directly instead. -Setting up the [QMK environment](newbs.md) is highly recommended, as it automatically installs `avrdude` along with a host of other tools. +Setting up the [QMK environment](newbs) is highly recommended, as it automatically installs `avrdude` along with a host of other tools. ## Bootloader Firmware @@ -194,7 +204,9 @@ There are several variants depending on the vendor, but they all mostly work the |[Arduino Leonardo](https://github.com/arduino/ArduinoCore-avr/blob/master/bootloaders/caterina/Caterina-Leonardo.hex)* |`0xFF`|`0xD8`|`0xFB` |`2341:0036`| |[Arduino Micro](https://github.com/arduino/ArduinoCore-avr/blob/master/bootloaders/caterina/Caterina-Micro.hex)* |`0xFF`|`0xD8`|`0xFB` |`2341:0037`| -?> Files marked with a * have combined Arduino sketches, which runs by default and also appears as a serial port. However, this is *not* the bootloader device. +::: tip +Files marked with a * have combined Arduino sketches, which runs by default and also appears as a serial port. However, this is *not* the bootloader device. +::: ### BootloadHID (PS2AVRGB) @@ -273,7 +285,9 @@ avrdude done. Thank you. This is a slightly more advanced topic, but may be necessary if you are switching from one bootloader to another (for example, Caterina to Atmel/QMK DFU on a Pro Micro). Fuses control some of the low-level functionality of the AVR microcontroller, such as clock speed, whether JTAG is enabled, and the size of the section of flash memory reserved for the bootloader, among other things. You can find a fuse calculator for many AVR parts [here](https://www.engbedded.com/conffuse/). -!> **WARNING:** Setting incorrect fuse values, in particular the clock-related bits, may render the MCU practically unrecoverable without high voltage programming (not covered here)! Make sure to double check the commands you enter before you execute them. +::: warning +**WARNING:** Setting incorrect fuse values, in particular the clock-related bits, may render the MCU practically unrecoverable without high voltage programming (not covered here)! Make sure to double check the commands you enter before you execute them. +::: To set the fuses, add the following to the `avrdude` command: @@ -283,7 +297,9 @@ To set the fuses, add the following to the `avrdude` command: where the `lfuse`, `hfuse` and `efuse` arguments represent the low, high and extended fuse bytes as listed in the [Hardware](#hardware) section. -?> You may get a warning from `avrdude` that the extended fuse byte does not match what you provided when reading it back. If the second hex digit matches, this can usually be safely ignored, because the top four bits of this fuse do not actually exist on many AVR parts, and may read back as anything. +::: tip +You may get a warning from `avrdude` that the extended fuse byte does not match what you provided when reading it back. If the second hex digit matches, this can usually be safely ignored, because the top four bits of this fuse do not actually exist on many AVR parts, and may read back as anything. +::: ## Creating a "Production" Firmware diff --git a/docs/ja/README.md b/docs/ja/README.md deleted file mode 100644 index aefacbc414..0000000000 --- a/docs/ja/README.md +++ /dev/null @@ -1,47 +0,0 @@ -# Quantum Mechanical Keyboard Firmware - - - -[![現在のバージョン](https://img.shields.io/github/tag/qmk/qmk_firmware.svg)](https://github.com/qmk/qmk_firmware/tags) -[![Discord](https://img.shields.io/discord/440868230475677696.svg)](https://discord.gg/Uq7gcHh) -[![ドキュメントの状態](https://img.shields.io/badge/docs-ready-orange.svg)](https://docs.qmk.fm) -[![GitHub 貢献者](https://img.shields.io/github/contributors/qmk/qmk_firmware.svg)](https://github.com/qmk/qmk_firmware/pulse/monthly) -[![GitHub フォーク](https://img.shields.io/github/forks/qmk/qmk_firmware.svg?style=social&label=Fork)](https://github.com/qmk/qmk_firmware/) - -## QMK ファームウェアとは何でしょうか？ - -QMK (*Quantum Mechanical Keyboard*)は、コンピュータ入力デバイスの開発を中心としたオープンソースコミュニティです。コミュニティには、キーボード、マウス、MIDI デバイスなど、全ての種類の入力デバイスが含まれます。協力者の中心グループは、[QMK ファームウェア](https://github.com/qmk/qmk_firmware)、[QMK Configurator](https://config.qmk.fm)、[QMK ツールボックス](https://github.com/qmk/qmk_toolbox)、[qmk.fm](https://qmk.fm)、そして、このドキュメントを、あなたのようなコミュニティメンバーの助けを借りて保守しています。 - -## 始めましょう - -QMK は初めてですか？始めるには2つの方法があります: - -* 基本: [QMK Configurator](https://config.qmk.fm) - * ドロップダウンからあなたのキーボードを選択し、キーボードをプログラムします。 - * 見ることができる [紹介ビデオ](https://www.youtube.com/watch?v=-imgglzDMdY) があります。 - * 読むことができる概要 [ドキュメント](ja/newbs_building_firmware_configurator.md) があります。 -* 発展: [ソースを使用します](ja/newbs.md) - * より強力ですが、使うのはより困難です。 - -## 自分用にアレンジします - -QMK には、探求すべき多くの[機能](ja/features.md)と、深く知るためのリファレンスドキュメントがたくさんあります。ほとんどの機能は[キーマップ](ja/keymap.md)を変更し、[キーコード](ja/keycodes.md)を変更することで活用されます。 - -## 手助けが必要ですか？ - -[サポートページ](ja/support.md) をチェックして、QMK の使い方について手助けを得る方法を確認してください。 - -## 貢献する - -QMK コミュニティに貢献する方法はたくさんあります。始める最も簡単な方法は、それを使って友人に QMK という単語を広めることです。 - -* フォーラムやチャットルームで人々を支援します: - * [/r/olkb](https://www.reddit.com/r/olkb/) - * [Discord サーバ](https://discord.gg/Uq7gcHh) -* 下にある「Edit This Page」をクリックしてドキュメントに貢献します -* [ドキュメントをあなたの言語に翻訳します](ja/translating.md) -* [バグを報告します](https://github.com/qmk/qmk_firmware/issues/new/choose) -* [プルリクエストを開きます](ja/contributing.md) diff --git a/docs/ja/_summary.md b/docs/ja/_summary.md deleted file mode 100644 index f26665e614..0000000000 --- a/docs/ja/_summary.md +++ /dev/null @@ -1,180 +0,0 @@ -* チュートリアル - * [入門](ja/newbs.md) - * [セットアップ](ja/newbs_getting_started.md) - * [初めてのファームウェアの構築](ja/newbs_building_firmware.md) - * [ファームウェアのフラッシュ](ja/newbs_flashing.md) - * [手助けを得る/サポート](ja/support.md) - * [他のリソース](ja/newbs_learn_more_resources.md) - * [シラバス](ja/syllabus.md) - -* FAQ - * [一般的な FAQ](ja/faq_general.md) - * [QMK のビルド/コンパイル](ja/faq_build.md) - * [QMK のデバッグ](ja/faq_debug.md) - * [QMK のトラブルシューティング](ja/faq_misc.md) - * [キーマップ FAQ](ja/faq_keymap.md) - * [用語](ja/reference_glossary.md) - -* Configurator - * [概要](ja/newbs_building_firmware_configurator.md) - * [ステップ・バイ・ステップ](ja/configurator_step_by_step.md) - * [トラブルシューティング](ja/configurator_troubleshooting.md) - * QMK API - * [概要](ja/api_overview.md) - * [API ドキュメント](ja/api_docs.md) - * [キーボードサポート](ja/reference_configurator_support.md) - * [デフォルトキーマップの追加](ja/configurator_default_keymaps.md) - -* CLI - * [概要](ja/cli.md) - * [設定](ja/cli_configuration.md) - * [コマンド](ja/cli_commands.md) - * [Tab 補完](ja/cli_tab_complete.md) - -* QMK を使う - * ガイド - * [機能のカスタマイズ](ja/custom_quantum_functions.md) - * [Zadig を使ったドライバのインストール](ja/driver_installation_zadig.md) - * [キーマップの概要](ja/keymap.md) - * 開発環境 - * [Docker のガイド](ja/getting_started_docker.md) - * 書き込み - * [書き込み](ja/flashing.md) - * [ATmega32A の書き込み (ps2avrgb)](ja/flashing_bootloadhid.md) - * IDE - * [QMK での Eclipse の使用](ja/other_eclipse.md) - * [QMK での VSCode の使用](ja/other_vscode.md) - * Git のベストプラクティス - * [入門](ja/newbs_git_best_practices.md) - * [フォーク](ja/newbs_git_using_your_master_branch.md) - * [マージの競合の解決](ja/newbs_git_resolving_merge_conflicts.md) - * [ブランチの修正](ja/newbs_git_resynchronize_a_branch.md) - * キーボードを作る - * [Hand Wiring ガイド](ja/hand_wire.md) - * [ISP 書き込みガイド](ja/isp_flashing_guide.md) - - * 単純なキーコード - * [完全なリスト](ja/keycodes.md) - * [基本的なキーコード](ja/keycodes_basic.md) - * [言語固有のキーコード](ja/reference_keymap_extras.md) - * [修飾キー](ja/feature_advanced_keycodes.md) - * [Quantum キーコード](ja/quantum_keycodes.md) - - * 高度なキーコード - * [コマンド](ja/feature_command.md) - * [動的マクロ](ja/feature_dynamic_macros.md) - * [グレイブ エスケープ](ja/feature_grave_esc.md) - * [リーダーキー](ja/feature_leader_key.md) - * [モッドタップ](ja/mod_tap.md) - * [マクロ](ja/feature_macros.md) - * [マウスキー](ja/feature_mouse_keys.md) - * [Repeat Key](ja/feature_repeat_key.md) - * [Space Cadet Shift](ja/feature_space_cadet.md) - * [US ANSI シフトキー](ja/keycodes_us_ansi_shifted.md) - - * ソフトウェア機能 - * [自動シフト](ja/feature_auto_shift.md) - * [コンボ](ja/feature_combo.md) - * [デバウンス API](ja/feature_debounce_type.md) - * [キーロック](ja/feature_key_lock.md) - * [レイヤー](ja/feature_layers.md) - * [ワンショットキー](ja/one_shot_keys.md) - * [ポインティング デバイス](ja/feature_pointing_device.md) - * [ロー HID](ja/feature_rawhid.md) - * [シーケンサー](ja/feature_sequencer.md) - * [スワップハンド](ja/feature_swap_hands.md) - * [タップダンス](ja/feature_tap_dance.md) - * [タップホールド設定](ja/tap_hold.md) - * [ユニコード](ja/feature_unicode.md) - * [ユーザスペース](ja/feature_userspace.md) - * [WPM 計算](ja/feature_wpm.md) - - * ハードウェア機能 - * 表示 - * [HD44780 LCD コントローラ](ja/feature_hd44780.md) - * [OLED ドライバ](ja/feature_oled_driver.md) - * 電飾 - * [バックライト](ja/feature_backlight.md) - * [LED マトリックス](ja/feature_led_matrix.md) - * [RGB ライト](ja/feature_rgblight.md) - * [RGB マトリックス](ja/feature_rgb_matrix.md) - * [オーディオ](ja/feature_audio.md) - * [Bluetooth](ja/feature_bluetooth.md) - * [ブートマジック](ja/feature_bootmagic.md) - * [カスタムマトリックス](ja/custom_matrix.md) - * [DIP スイッチ](ja/feature_dip_switch.md) - * [エンコーダ](ja/feature_encoders.md) - * [触覚フィードバック](ja/feature_haptic_feedback.md) - * [ジョイスティック](ja/feature_joystick.md) - * [LED インジケータ](ja/feature_led_indicators.md) - * [Proton C 変換](ja/proton_c_conversion.md) - * [PS/2 マウス](ja/feature_ps2_mouse.md) - * [分割キーボード](ja/feature_split_keyboard.md) - * [速記](ja/feature_stenography.md) - * [感熱式プリンタ](ja/feature_thermal_printer.md) - -* QMK の開発 - * [PR チェックリスト](ja/pr_checklist.md) - * 互換性を破る変更/Breaking changes - * [概要](ja/breaking_changes.md) - * [プルリクエストにフラグが付けられた](ja/breaking_changes_instructions.md) - * [最近の変更履歴](ChangeLog/20210227.md "QMK v0.12.0 - 2021 Feb 27") - * [過去の互換性を破る変更](ja/breaking_changes_history.md) - - * C 開発 - * [ARM デバッグ ガイド](ja/arm_debugging.md) - * [AVR プロセッサ](ja/hardware_avr.md) - * [コーディング規約](ja/coding_conventions_c.md) - * [互換性のあるマイクロコントローラ](ja/compatible_microcontrollers.md) - * [ドライバ](ja/hardware_drivers.md) - * [ADC ドライバ](ja/adc_driver.md) - * [オーディオドライバ](ja/audio_driver.md) - * [I2C ドライバ](ja/i2c_driver.md) - * [SPI ドライバ](ja/spi_driver.md) - * [WS2812 ドライバ](ja/ws2812_driver.md) - * [EEPROM ドライバ](ja/eeprom_driver.md) - * [シリアル ドライバ](ja/serial_driver.md) - * [UART ドライバ](ja/uart_driver.md) - * [GPIO 制御](ja/gpio_control.md) - * [キーボード ガイドライン](ja/hardware_keyboard_guidelines.md) - - * Python 開発 - * [コーディング規約](ja/coding_conventions_python.md) - * [QMK CLI 開発](ja/cli_development.md) - - * Configurator 開発 - * QMK API - * [開発環境](ja/api_development_environment.md) - * [アーキテクチャの概要](ja/api_development_overview.md) - - * ハードウェアプラットフォーム開発 - * Arm/ChibiOS - * [MCU の選択](ja/platformdev_selecting_arm_mcu.md) - * [早期初期化](ja/platformdev_chibios_earlyinit.md) - - * QMK Reference - * [QMK への貢献](ja/contributing.md) - * [QMK ドキュメントの翻訳](ja/translating.md) - * [設定オプション](ja/config_options.md) - * [データ駆動型コンフィギュレーション](ja/data_driven_config.md) - * [Make ドキュメント](ja/getting_started_make_guide.md) - * [ドキュメント ベストプラクティス](ja/documentation_best_practices.md) - * [ドキュメント テンプレート](ja/documentation_templates.md) - * [コミュニティレイアウト](ja/feature_layouts.md) - * [ユニットテスト](ja/unit_testing.md) - * [便利な関数](ja/ref_functions.md) - * [info.json 形式](ja/reference_info_json.md) - - * より深く知るために - * [キーボードがどのように動作するか](ja/how_keyboards_work.md) - * [マトリックスがどのように動作するか](ja/how_a_matrix_works.md) - * [QMK を理解する](ja/understanding_qmk.md) - - * QMK の内部詳細(作成中) - * [定義](ja/internals/defines.md) - * [入力コールバック登録](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) - * [Midi 送信関数](ja/internals/send_functions.md) - * [Sysex Tools](ja/internals/sysex_tools.md) diff --git a/docs/ja/adc_driver.md b/docs/ja/adc_driver.md deleted file mode 100644 index 0a531c8db9..0000000000 --- a/docs/ja/adc_driver.md +++ /dev/null @@ -1,155 +0,0 @@ -# ADC ドライバ - - - -QMK は対応している MCU のアナログ・デジタルコンバータ（ADC) を使用し、特定のピンの電圧を計測することができます。この機能はデジタル出力の[ロータリーエンコーダ](ja/feature_encoders.md)などではなく、アナログ計測が必要な可変抵抗器を使用したボリュームコントロールや Bluetooth キーボードのバッテリー残量表示などの実装に役立ちます。 - -このドライバは現在 AVR と一部の ARM デバイスをサポートしています。返される値は 0V と VCC (通常 AVR の場合は 5V または 3.3V、ARM の場合は 3.3V)の間でマッピングされた 10ビットの整数 (0-1023) ですが、ARM の場合、もしもより精度が必要であれば `#define` を使うと操作をより柔軟に制御できます。 - -## 使い方 - -このドライバを使うには、`rules.mk` に以下を追加します: - -```make -SRC += analog.c -``` - -そして、コードの先頭に以下の include を置きます: - -```c -#include "analog.h" -``` - -## チャンネル - -### AVR - -|Channel|AT90USB64/128|ATmega16/32U4|ATmega32A|ATmega328/P| -|-------|-------------|-------------|---------|-----------| -|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` | | | - -\* ATmega328/P には余分な2つの ADC チャンネルがありますが、DIP ピンアウトには存在せず、GPIO ピンとは共有されません。これらに直接アクセスするために、`adc_read()` を使えます。 - -### ARM - -これらのピンの一部は同じチャンネルを使って ADC 上でダブルアップされることに注意してください。これは、これらのピンがどちらかの ADC に使われる可能性があるからです。 - -また、F0 と F3 は異なるナンバリングスキーマを使うことに注意してください。F0 には1つの ADC があり、チャンネルは0から始まるインデックスですが、F3 には4つの ADC があり、チャンネルは1から始まるインデックスです。これは、F0 が ADC の `ADCv1` 実装を使用するのに対し、F3 が `ADCv3` 実装を使用するためです。 - -|ADC|Channel|STM32F0xx|STM32F3xx| -|---|-------|---------|---------| -|1 |0 |`A0` | | -|1 |1 |`A1` |`A0` | -|1 |2 |`A2` |`A1` | -|1 |3 |`A3` |`A2` | -|1 |4 |`A4` |`A3` | -|1 |5 |`A5` |`F4` | -|1 |6 |`A6` |`C0` | -|1 |7 |`A7` |`C1` | -|1 |8 |`B0` |`C2` | -|1 |9 |`B1` |`C3` | -|1 |10 |`C0` |`F2` | -|1 |11 |`C1` | | -|1 |12 |`C2` | | -|1 |13 |`C3` | | -|1 |14 |`C4` | | -|1 |15 |`C5` | | -|1 |16 | | | -|2 |1 | |`A4` | -|2 |2 | |`A5` | -|2 |3 | |`A6` | -|2 |4 | |`A7` | -|2 |5 | |`C4` | -|2 |6 | |`C0` | -|2 |7 | |`C1` | -|2 |8 | |`C2` | -|2 |9 | |`C3` | -|2 |10 | |`F2` | -|2 |11 | |`C5` | -|2 |12 | |`B2` | -|2 |13 | | | -|2 |14 | | | -|2 |15 | | | -|2 |16 | | | -|3 |1 | |`B1` | -|3 |2 | |`E9` | -|3 |3 | |`E13` | -|3 |4 | | | -|3 |5 | | | -|3 |6 | |`E8` | -|3 |7 | |`D10` | -|3 |8 | |`D11` | -|3 |9 | |`D12` | -|3 |10 | |`D13` | -|3 |11 | |`D14` | -|3 |12 | |`B0` | -|3 |13 | |`E7` | -|3 |14 | |`E10` | -|3 |15 | |`E11` | -|3 |16 | |`E12` | -|4 |1 | |`E14` | -|4 |2 | |`B12` | -|4 |3 | |`B13` | -|4 |4 | |`B14` | -|4 |5 | |`B15` | -|4 |6 | |`E8` | -|4 |7 | |`D10` | -|4 |8 | |`D11` | -|4 |9 | |`D12` | -|4 |10 | |`D13` | -|4 |11 | |`D14` | -|4 |12 | |`D8` | -|4 |13 | |`D9` | -|4 |14 | | | -|4 |15 | | | -|4 |16 | | | - -## 関数 - -### AVR - -|関数 |説明 | -|----------------------------|------------------------------------------------------------------------------------------------------------------------------------| -|`analogReference(mode)` |アナログの電圧リファレンスソースを設定する。`ADC_REF_EXTERNAL`、`ADC_REF_POWER`、`ADC_REF_INTERNAL` のいずれかでなければなりません。| -|`analogReadPin(pin)` |指定されたピンから値を読み取ります。例えば、ATmega32U4 の ADC6 の場合 `F6`。 | -|`pinToMux(pin)` |指定されたピンを mux 値に変換します。サポートされていないピンが指定された場合、"0V (GND)" の mux 値を返します。 | -|`adc_read(mux)` |指定された mux に従って ADC から値を読み取ります。詳細は、MCU のデータシートを見てください。 | - -### ARM - -|関数 |説明 | -|----------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -|`analogReadPin(pin)` |指定されたピンから値を読み取ります。STM32F0 では チャンネル 0 の `A0`、STM32F3 ではチャンネル 1 の ADC1。ピンを複数の ADC に使える場合は、この関数のために番号の小さい ADC が選択されることに注意してください。例えば、`C0` は、ADC2 にも使える場合、ADC1 のチャンネル 6 になります。 | -|`analogReadPinAdc(pin, adc)`|指定されたピンと ADC から値を読み取ります。例えば、`C0, 1` は、ADC1 ではなく ADC2 のチャンネル 6 から読み取ります。この関数では、ADC はインデックス 0 から始まることに注意してください。 | -|`pinToMux(pin)` |指定されたピンをチャンネルと ADC の組み合わせに変換します。サポートされていないピンが指定された場合、"0V (GND)" の mux 値を返します。 | -|`adc_read(mux)` |指定されたピンと ADC の組み合わせに応じて ADC から値を読み取ります。詳細は、MCU のデータシートを見てください。 | - -## 設定 - -## ARM - -ADC の ARM 実装には、独自のキーボードとキーマップでオーバーライドして動作方法を変更できる幾つかの追加オプションがあります。利用可能なオプションの詳細については、特定のマイクロコントローラについて ChibiOS の対応する `hal_adc_lld.h` を調べてください。 - -|`#define` |型 |既定値 |説明 | -|---------------------|------|---------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -|`ADC_CIRCULAR_BUFFER`|`bool`|`false` |`true` の場合、この実装は循環バッファを使います。 | -|`ADC_NUM_CHANNELS` |`int` |`1` |ADC 動作の一部としてスキャンされるチャンネル数を設定します。現在の実装は `1` のみをサポートします。 | -|`ADC_BUFFER_DEPTH` |`int` |`2` |各結果の深さを設定します。デフォルトでは12ビットの結果しか取得できないため、これを2バイトに設定して1つの値を含めることができます。8ビット以下の結果を選択した場合は、これを 1 に設定できます。 | -|`ADC_SAMPLING_RATE` |`int` |`ADC_SMPR_SMP_1P5` |ADC のサンプリングレートを設定します。デフォルトでは、最も速い設定に設定されています。 | -|`ADC_RESOLUTION` |`int` |`ADC_CFGR1_RES_12BIT`|結果の分解能。デフォルトでは12ビットを選択しますが、12、10、8、6ビットを選択できます。 | diff --git a/docs/ja/api_development_environment.md b/docs/ja/api_development_environment.md deleted file mode 100644 index 8dce1ba2fd..0000000000 --- a/docs/ja/api_development_environment.md +++ /dev/null @@ -1,8 +0,0 @@ -# 開発環境のセットアップ - - - -開発環境をセットアップするには、[qmk_web_stack](https://github.com/qmk/qmk_web_stack) に行ってください。 diff --git a/docs/ja/api_development_overview.md b/docs/ja/api_development_overview.md deleted file mode 100644 index 0612507b4d..0000000000 --- a/docs/ja/api_development_overview.md +++ /dev/null @@ -1,49 +0,0 @@ -# QMK コンパイラ開発ガイド - - - -このページでは、開発者に QMK コンパイラを紹介しようと思います。コードを読まなければならないような核心となる詳細に立ち入って調べることはしません。ここで得られるものは、コードを読んで理解を深めるためのフレームワークです。 - -# 概要 - -QMK Compile API は、いくつかの可動部分からできています: - -![構造図](https://raw.githubusercontent.com/qmk/qmk_api/master/docs/architecture.svg) - -API クライアントは API サービスと排他的にやりとりをします。ここでジョブをサブミットし、状態を調べ、結果をダウンロードします。API サービスはコンパイルジョブを [Redis Queue](https://python-rq.org) に挿入し、それらのジョブの結果について RQ と S3 の両方を調べます。 - -ワーカーは RQ から新しいコンパイルジョブを取り出し、ソースとバイナリを S3 互換のストレージエンジンにアップロードします。 - -# ワーカー - -QMK コンパイラワーカーは実際のビルド作業に責任を持ちます。ワーカーは RQ からジョブを取り出し、ジョブを完了するためにいくつかの事を行います: - -* 新しい qmk_firmware のチェックアウトを作成する -* 指定されたレイヤーとキーボードメタデータを使って `keymap.c` をビルドする -* ファームウェアをビルドする -* ソースのコピーを zip 形式で圧縮する -* ファームウェア、ソースの zip ファイル、メタデータファイルを S3 にアップロードする -* ジョブの状態を RQ に送信する - -# API サービス - -API サービスは比較的単純な Flask アプリケーションです。理解しておくべきことが幾つかあります。 - -## @app.route('/v1/compile', methods=['POST']) - -これは API の主なエントリーポイントです。クライアントとのやりとりはここから開始されます。クライアントはキーボードを表す JSON ドキュメントを POST し、API はコンパイルジョブをサブミットする前にいくらかの(とても)基本的な検証を行います。 - -## @app.route('/v1/compile/<string:job_id>', methods=['GET']) - -これは最もよく呼ばれるエンドポイントです。ジョブの詳細が redis から利用可能であればそれを取り出し、そうでなければ S3 からキャッシュされたジョブの詳細を取り出します。 - -## @app.route('/v1/compile/<string:job_id>/download', methods=['GET']) - -このメソッドによりユーザはコンパイルされたファームウェアファイルをダウンロードすることができます。 - -## @app.route('/v1/compile/<string:job_id>/source', methods=['GET']) - -このメソッドによりユーザはファームウェアのソースをダウンロードすることができます。 diff --git a/docs/ja/api_docs.md b/docs/ja/api_docs.md deleted file mode 100644 index 19d52a724a..0000000000 --- a/docs/ja/api_docs.md +++ /dev/null @@ -1,73 +0,0 @@ -# QMK API - - - -このページは QMK API の使い方を説明します。もしあなたがアプリケーション開発者であれば、全ての [QMK](https://qmk.fm) キーボードのファームウェアをコンパイルするために、この API を使うことができます。 - -## 概要 - -このサービスは、カスタムキーマップをコンパイルするための非同期 API です。API に 何らかの JSON を POST し、定期的に状態をチェックし、ファームウェアのコンパイルが完了していれば、結果のファームウェアと(もし希望すれば)そのファームウェアのソースコードをダウンロードすることができます。 - -#### JSON ペイロードの例: - -```json -{ - "keyboard": "clueboard/66/rev2", - "keymap": "my_awesome_keymap", - "layout": "LAYOUT_all", - "layers": [ - ["KC_GRV","KC_1","KC_2","KC_3","KC_4","KC_5","KC_6","KC_7","KC_8","KC_9","KC_0","KC_MINS","KC_EQL","KC_GRV","KC_BSPC","KC_PGUP","KC_TAB","KC_Q","KC_W","KC_E","KC_R","KC_T","KC_Y","KC_U","KC_I","KC_O","KC_P","KC_LBRC","KC_RBRC","KC_BSLS","KC_PGDN","KC_CAPS","KC_A","KC_S","KC_D","KC_F","KC_G","KC_H","KC_J","KC_K","KC_L","KC_SCLN","KC_QUOT","KC_NUHS","KC_ENT","KC_LSFT","KC_NUBS","KC_Z","KC_X","KC_C","KC_V","KC_B","KC_N","KC_M","KC_COMM","KC_DOT","KC_SLSH","KC_RO","KC_RSFT","KC_UP","KC_LCTL","KC_LGUI","KC_LALT","KC_MHEN","KC_SPC","KC_SPC","KC_HENK","KC_RALT","KC_RCTL","MO(1)","KC_LEFT","KC_DOWN","KC_RIGHT"], - ["KC_ESC","KC_F1","KC_F2","KC_F3","KC_F4","KC_F5","KC_F6","KC_F7","KC_F8","KC_F9","KC_F10","KC_F11","KC_F12","KC_TRNS","KC_DEL","BL_STEP","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","_______","KC_TRNS","KC_PSCR","KC_SCRL","KC_PAUS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","MO(2)","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_PGUP","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","MO(1)","KC_LEFT","KC_PGDN","KC_RGHT"], - ["KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","QK_BOOT","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","MO(2)","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","MO(1)","KC_TRNS","KC_TRNS","KC_TRNS"] - ] -} -``` - -ご覧のとおり、ペイロードにはファームウェアを作成および生成するために必要なキーボードの全ての側面を記述します。各レイヤーは QMK キーコードの1つのリストで、キーボードの `LAYOUT` マクロと同じ長さです。もしキーボードが複数の `LAYOUT` マクロをサポートする場合、どのマクロを使うかを指定することができます。 - -## コンパイルジョブのサブミット - -キーマップをファームウェアにコンパイルするには、単純に JSON を `/v1/compile` エンドポイントに POST します。以下の例では、JSON ペイロードを `json_data` という名前のファイルに配置しています。 - -``` -$ curl -H "Content-Type: application/json" -X POST -d "$(< json_data)" https://api.qmk.fm/v1/compile -{ - "enqueued": true, - "job_id": "ea1514b3-bdfc-4a7b-9b5c-08752684f7f6" -} -``` - -## 状態のチェック - -キーマップをサブミットした後で、簡単な HTTP GET 呼び出しを使って状態をチェックすることができます: - -``` -$ curl https://api.qmk.fm/v1/compile/ea1514b3-bdfc-4a7b-9b5c-08752684f7f6 -{ - "created_at": "Sat, 19 Aug 2017 21:39:12 GMT", - "enqueued_at": "Sat, 19 Aug 2017 21:39:12 GMT", - "id": "f5f9b992-73b4-479b-8236-df1deb37c163", - "status": "running", - "result": null -} -``` - -これは、ジョブをキューに入れることに成功し、現在実行中であることを示しています。5つの状態がありえます: - -* **failed**: なんらかの理由でコンパイルサービスが失敗しました。 -* **finished**: コンパイルが完了し、結果を見るには `result` をチェックする必要があります。 -* **queued**: キーマップはコンパイルサーバが利用可能になるのを待っています。 -* **running**: コンパイルが進行中で、まもなく完了するはずです。 -* **unknown**: 深刻なエラーが発生し、[バグを報告](https://github.com/qmk/qmk_compiler/issues)する必要があります。 - -## 完了した結果を検証 - -コンパイルジョブが完了したら、`result` キーをチェックします。このキーの値は幾つかの情報を含むハッシュです: - -* `firmware_binary_url`: 書き込み可能なファームウェアの URL のリスト -* `firmware_keymap_url`: `keymap.c` の URL のリスト -* `firmware_source_url`: ファームウェアの完全なソースコードの URL のリスト -* `output`: このコンパイルジョブの stdout と stderr。エラーはここで見つけることができます。 diff --git a/docs/ja/api_overview.md b/docs/ja/api_overview.md deleted file mode 100644 index e563bdd103..0000000000 --- a/docs/ja/api_overview.md +++ /dev/null @@ -1,20 +0,0 @@ -# QMK API - - - -QMK API は、Web と GUI ツールが [QMK](https://qmk.fm/) によってサポートされるキーボード用の任意のキーマップをコンパイルするために使うことができる、非同期 API を提供します。標準のキーマップテンプレートは、C コードのサポートを必要としない全ての QMK キーコードをサポートします。キーボードのメンテナは独自のカスタムテンプレートを提供して、より多くの機能を実現することができます。 - -## アプリケーション開発者 - -もしあなたがアプリケーションでこの API を使うことに興味があるアプリケーション開発者であれば、[API の使用](ja/api_docs.md) に行くべきです。 - -## キーボードのメンテナ - -もし QMK Compiler API でのあなたのキーボードのサポートを強化したい場合は、[キーボードサポート](ja/reference_configurator_support.md) の節に行くべきです。 - -## バックエンド開発者 - -もし API 自体に取り組むことに興味がある場合は、[開発環境](ja/api_development_environment.md)のセットアップから始め、それから [API のハッキング](ja/api_development_overview.md) を調べるべきです。 diff --git a/docs/ja/arm_debugging.md b/docs/ja/arm_debugging.md deleted file mode 100644 index afb5c4e0e6..0000000000 --- a/docs/ja/arm_debugging.md +++ /dev/null @@ -1,92 +0,0 @@ -# Eclipse を使った ARM デバッグ - - - -このページでは、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 @xpack-dev-tools/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 @xpack-dev-tools/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 Toolchains Paths を選択します。xPack を押して OK を押します。OpenOCD Path で同じことを繰り返し、Windows の場合は、Build Tools Path でも同じことを繰り返します。Apply and Close を選択します。 - -ここで、必要な MCU パッケージをインストールします。Window -> Perspective -> Open Perspective -> Other... -> Packs を選択して、Packs perspective に移動します。Packs タブの横にある黄色のリフレッシュ記号を選択します。これは様々な場所から MCU の定義を要求するため、時間が掛かります。一部のリンクが失敗した場合は、おそらく Ignore を選択できます。 - -これが終了すると、ビルドやデバッグする MCU を見つけることができるはずです。この例では、STM32F3 シリーズの MCU を使います。左側で、STMicroelectronics -> STM32F3 Series を選択します。中央のウィンドウに、pack が表示されます。右クリックし、Install を選択します。それが終了したら、Window -> Perspective -> Open Perspective -> Other... -> 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 Configurations... を選択します。ここで、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/breaking_changes.md b/docs/ja/breaking_changes.md deleted file mode 100644 index 35f5837897..0000000000 --- a/docs/ja/breaking_changes.md +++ /dev/null @@ -1,120 +0,0 @@ -# Breaking changes/互換性を破る変更 - - - -このドキュメントは QMK の互換性を破る変更(Breaking change) のプロセスについて説明します。 -互換性を破る変更とは、互換性がなかったり潜在的な危険が生じるように QMK の動作を変える変更を指します。 -ユーザが QMK ツリーを更新しても自分のキーマップが壊れない事を確信できるように、これらの変更を制限します。(訳注：以後、原文のまま Breaking change を用語として使用します。) - -Breaking change ピリオドとは、危険な変更、または予想外の変更を QMK へ行なう PR をマージする時のことです。 -付随するテスト期間があるため、問題が起きることはまれか、有りえないと確信しています。 - -## 過去の Breaking change には何が含まれますか？ - -* [2020年8月29日](ja/ChangeLog/20200829.md) -* [2020年5月30日](ja/ChangeLog/20200530.md) -* [2020年2月29日](ja/ChangeLog/20200229.md) -* [2019年8月30日](ja/ChangeLog/20190830.md) - -## 次の Breaking change はいつですか？ - -次の Breaking change は2020年11月28日に予定されています。 - -### 重要な日付 - -* [x] 2020年 8月29日 - `develop` が作成されました。毎週リベースされます。 -* [ ] 2020年10月31日 - `develop` は新しいPRを取り込みません。 -* [ ] 2020年10月31日 - テスターの募集。 -* [ ] 2020年11月26日 - `master`がロックされ、PR はマージされません。 -* [ ] 2020年11月28日 - `develop` を `master` にマージします。 -* [ ] 2020年11月28日 - `master` のロックが解除されます。PR を再びマージすることができます。 - -## どのような変更が含まれますか？ - -最新の Breaking change 候補を見るには、[`breaking_change` ラベル](https://github.com/qmk/qmk_firmware/pulls?q=is%3Aopen+label%3Abreaking_change+is%3Apr)を参照してください。 -現在から `develop` が閉じられるまでの間に新しい変更が追加される可能性があり、そのラベルが適用された PR はマージされることは保証されていません。 - -このラウンドに、あなたの Breaking change を含めたい場合は、`breaking_change` ラベルを持つ PR を作成し、`develop` が閉じる前に承認してもらう必要があります。 -`develop` が閉じた後は、新しい Breaking change は受け付けられません。 - -受け入れの基準: - -* PR が完了し、マージの準備ができている -* PR が ChangeLog を持つ - -# チェックリスト - -ここでは、Breaking change プロセスを実行する時に使用する様々なプロセスについて説明します。 - -## `master` から `develop` をリベースします - -これは `develop` が開いている間、毎週金曜日に実行されます。 - -プロセス: - -``` -cd qmk_firmware -git checkout master -git pull --ff-only -git checkout develop -git rebase master -git push --force -``` - -## `develop` ブランチの作成 - -以前の `develop` ブランチがマージされた直後に、これが発生します。 - -* `qmk_firmware` git commands - * [ ] `git checkout master` - * [ ] `git pull --ff-only` - * [ ] `git checkout -b develop` - * [ ] Edit `readme.md` - * [ ] これがテストブランチであることを上部に大きな通知で追加します。 - * [ ] このドキュメントへのリンクを含めます - * [ ] `git commit -m 'Branch point for Breaking Change'` - * [ ] `git tag breakpoint___
` - * [ ] `git tag ` # ブレーキング ポイント タグがバージョンの増分を混乱させないようにします - * [ ] `git push origin develop` - * [ ] `git push --tags` - -## マージの 4 週間前 - -* `develop` は新しい PR に対して閉じられ、現在の PR の修正のみがマージされる可能性があります。 -* テスターの呼び出しを投稿します - * [ ] Discord - * [ ] GitHub PR - * [ ] https://reddit.com/r/olkb - -## マージの 1 週間前 - -* master が < 2 日前> から <マージの日> まで閉じられることを発表します - * [ ] Discord - * [ ] GitHub PR - * [ ] https://reddit.com/r/olkb - -## マージの 2 日前 - -* master が 2 日間閉じられることを発表します - * [ ] Discord - * [ ] GitHub PR - * [ ] https://reddit.com/r/olkb - -## マージの日 - -* `qmk_firmware` git commands - * [ ] `git checkout develop` - * [ ] `git pull --ff-only` - * [ ] `git rebase origin/master` - * [ ] Edit `readme.md` - * [ ] `develop` についてのメモを削除 - * [ ] ChangeLog を 1 つのファイルにまとめます。 - * [ ] `git commit -m 'Merge point for Breaking Change'` - * [ ] `git push origin develop` -* GitHub Actions - * [ ] `develop`の PR を作成します - * [ ] `develop` PR をマージします diff --git a/docs/ja/breaking_changes_instructions.md b/docs/ja/breaking_changes_instructions.md deleted file mode 100644 index 69d17d73c5..0000000000 --- a/docs/ja/breaking_changes_instructions.md +++ /dev/null @@ -1,51 +0,0 @@ -# breaking changes/互換性を破る変更: プルリクエストにフラグが付けられた - - - -QMK のメンバーがあなたのプルリクエストに返信し、あなたの提出したものは Breaking change (互換性を破る変更) であると述べている場合があります。メンバーの判断では、あなたが提案した変更は QMK やその利用者にとってより大きな影響を持つと考えられます。 - -プルリクエストにフラグが立てられる原因となるものには、以下のようなものがあります: - -- **ユーザーのキーマップに対する編集** - ユーザーが自分のキーマップを QMK に提出した後、しばらくしてさらに更新してプルリクエストを開いたところ、それが `qmk/qmk_firmware` リポジトリで編集されていたためにマージできなかったことに気づくことがあるかもしれません。すべてのユーザーが Git や GitHub を使いこなせるわけではないので、ユーザー自身で問題を修正できないことに気づくかもしれません。 -- **期待される動作の変更** - QMK の動作を変更すると、既存の QMK 機能への変更を組み込んだ新しいファームウェアをフラッシュした場合、ユーザはハードウェアまたは QMK が壊れていると考え、希望する動作を復元する手段がないことに気付くことがあります。 -- **ユーザーのアクションを必要とする変更** - 変更には、ツールチェインを更新したり、Git で何らかのアクションを取るなど、ユーザーがアクションを行う必要がある場合もあります。 -- **精査が必要な変更** - 時には、投稿がプロジェクトとしての QMK に影響を与えることもあります。これは、著作権やライセンスの問題、コーディング規約、大規模な機能のオーバーホール、コミュニティによるより広範なテストを必要とする「リスクの高い」変更、あるいは全く別のものである可能性があります。 -- **エンドユーザーとのコミュニケーションを必要とする変更** - これには、将来の非推奨化への警告、時代遅れの慣習、その他伝えなければならないが上記のカテゴリのどれかに当てはまらないものが含まれます。 - -## 何をすればいいのか? - -提出したものが Breaking change だと判断された場合、手続きをスムーズに進めるためにできることがいくつかあります。 - -### PR を分割することを検討する - -あなたがコアコードを投稿していて、それが Breaking change プロセスを経る必要がある唯一の理由が、あなたの変更に合わせてキーマップを更新していることである場合、古いキーマップが機能し続けるような方法であなたの機能を投稿できるかどうかを検討してください。 -そののち、Breaking change プロセスを経て古いコードを削除する別の PR を提出してください。 - -### ChangeLog エントリの提供 - -Breaking change プロセスを経て提出する際には、変更ログのエントリを含めることを我々は要請します。 -エントリーは、あなたのプルリクエストが行う変更の短い要約としてください – [ここの各セクションは changelog として開始されました](ja/ChangeLog/20190830.md "n.b. This should link to the 2019 Aug 30 Breaking Changes doc - @noroadsleft")。 - -変更ログは `docs/ChangeLog/YYYYMMDD/PR####.md` に置いてください。 -ここで、`YYYYMMDD` は QMK の breaking change ブランチ – 通常は `develop` という名称 – が `master` ブランチにマージされる日付、`####` はプルリクエストの番号です。 - -ユーザー側でのアクションを必要とする場合、あなたの変更ログは、どのようなアクションを取らなければならないかをユーザーに指示するか、そのようなアクションを指示する場所にリンクする必要があります。 - -### 変更点を文書化する - -提出物の目的を理解し、それが必要とする可能性のある意味合いやアクションを理解することで、レビュープロセスをより簡単にすることができます。この目的のためには変更履歴で十分かもしれませんが、より広範囲の変更を行う場合には、変更履歴には不向きな詳細レベルが必要になるかもしれません。 - -あなたのプルリクエストにコメントしたり、質問やコメント、変更要求に対応したりすることは、非常にありがたいことです。 - -### 助けを求める - -あなたの提出物にフラグが立ったことで、あなたはびっくりしてしまったかもしれません。もし、あなた自身が脅されたり、圧倒されたりしていると感じたら、私たちに知らせてください。プルリクエストにコメントするか、[Discord で QMK チームに連絡を取ってください](https://discord.gg/Uq7gcHh)。 diff --git a/docs/ja/cli.md b/docs/ja/cli.md deleted file mode 100644 index 9e8169a84e..0000000000 --- a/docs/ja/cli.md +++ /dev/null @@ -1,43 +0,0 @@ -# QMK CLI :id=qmk-cli - - - -## 概要 :id=overview - -QMK CLI を使用すると QMK キーボードの構築と作業が簡単になります。QMK ファームウェアの取得とコンパイル、キーマップの作成などのようなタスクを簡素化し合理化するためのコマンドを多く提供します。 - -### 必要事項 :id=requirements - -QMK は Python 3.6 以上を必要とします。我々は必要事項の数を少なくしようとしていますが、[`requirements.txt`](https://github.com/qmk/qmk_firmware/blob/master/requirements.txt) に列挙されているパッケージもインストールする必要があります。これらは QMK CLI をインストールするときに自動的にインストールされます。 - -### Homebrew を使ったインストール (macOS、いくつかの Linux) :id=install-using-homebrew - -[Homebrew](https://brew.sh) をインストールしている場合は、タップして QMK をインストールすることができます: - -``` -brew install qmk/qmk/qmk -export QMK_HOME='~/qmk_firmware' # オプション、`qmk_firmware` の場所を設定します -qmk setup # これは `qmk/qmk_firmware` をクローンし、オプションでビルド環境をセットアップします -``` - -### pip を使ってインストール :id=install-using-easy_install-or-pip - -上で列挙した中にあなたのシステムがない場合は、QMK を手動でインストールすることができます。最初に、python 3.6 (以降)をインストールしていて、pip をインストールしていることを確認してください。次に以下のコマンドを使って QMK をインストールします: - -``` -python3 -m pip install qmk -export QMK_HOME='~/qmk_firmware' # オプション、`qmk_firmware` の場所を設定します -qmk setup # これは `qmk/qmk_firmware` をクローンし、オプションでビルド環境をセットアップします -``` - -### 他のオペレーティングシステムのためのパッケージ :id=packaging-for-other-operating-systems - -より多くのオペレーティングシステム用に `qmk` パッケージを作成および保守する人を探しています。OS 用のパッケージを作成する場合は、以下のガイドラインに従ってください: - -* これらのガイドラインと矛盾する場合は、OS のベストプラクティスに従ってください - * 逸脱する場合は、理由をコメントに文章化してください。 -* virtualenv を使ってインストールしてください -* 環境変数 `QMK_HOME` を設定して、ファームウェアソースを `~/qmk_firmware` 以外のどこかにチェックアウトするようにユーザに指示してください。 diff --git a/docs/ja/cli_commands.md b/docs/ja/cli_commands.md deleted file mode 100644 index b48de077cd..0000000000 --- a/docs/ja/cli_commands.md +++ /dev/null @@ -1,296 +0,0 @@ -# QMK CLI コマンド - - - -# ユーザー用コマンド - -## `qmk compile` - -このコマンドにより、任意のディレクトリからファームウェアをコンパイルすることができます。 からエクスポートした JSON をコンパイルするか、リポジトリ内でキーマップをコンパイルするか、現在の作業ディレクトリでキーボードをコンパイルすることができます。 - -このコマンドはディレクトリを認識します。キーボードやキーマップのディレクトリにいる場合、自動的に KEYBOARD や KEYMAP を入力します。 - -**Configurator Exports での使い方**: - -``` -qmk compile -``` - -**キーマップでの使い方**: - -``` -qmk compile -kb -km -``` - -**キーボードディレクトリでの使い方**: - -default キーマップのあるキーボードディレクトリ、キーボードのキーマップディレクトリ、`--keymap ` で与えられるキーマップディレクトリにいなければなりません。 -``` -qmk compile -``` - -**指定したキーマップをサポートする全てのキーボードをビルドする場合の使い方**: - -``` -qmk compile -kb all -km -``` - -**例**: -``` -$ qmk config compile.keymap=default -$ cd ~/qmk_firmware/keyboards/planck/rev6 -$ qmk compile -Ψ Compiling keymap with make planck/rev6:default -... -``` -あるいはオプションのキーマップ引数を指定して - -``` -$ cd ~/qmk_firmware/keyboards/clueboard/66/rev4 -$ qmk compile -km 66_iso -Ψ Compiling keymap with make clueboard/66/rev4:66_iso -... -``` -あるいはキーマップディレクトリで - -``` -$ cd ~/qmk_firmware/keyboards/gh60/satan/keymaps/colemak -$ qmk compile -Ψ Compiling keymap with make gh60/satan:colemak -... -``` - -**レイアウトディレクトリでの使い方**: - -`qmk_firmware/layouts/` 以下のキーマップディレクトリにいなければなりません。 -``` -qmk compile -kb -``` - -**例**: -``` -$ cd ~/qmk_firmware/layouts/community/60_ansi/mechmerlin-ansi -$ qmk compile -kb dz60 -Ψ Compiling keymap with make dz60:mechmerlin-ansi -... -``` - -## `qmk flash` - -このコマンドは `qmk compile` に似ていますが、ブートローダを対象にすることもできます。ブートローダはオプションで、デフォルトでは `:flash` に設定されています。 -違うブートローダを指定するには、`-bl ` を使ってください。利用可能なブートローダの詳細については、[ファームウェアを書き込む](ja/flashing.md)を見てください。 - -このコマンドはディレクトリを認識します。キーボードやキーマップのディレクトリにいる場合、自動的に KEYBOARD や KEYMAP を入力します。 - -**Configurator Exports での使い方**: - -``` -qmk flash -bl -``` - -**キーマップでの使い方**: - -``` -qmk flash -kb -km -bl -``` - -**ブートローダの列挙** - -``` -qmk flash -b -``` - -## `qmk config` - -このコマンドにより QMK の挙動を設定することができます。完全な `qmk config` のドキュメントについては、[CLI 設定](ja/cli_configuration.md)を見てください。 - -**使用法**: - -``` -qmk config [-ro] [config_token1] [config_token2] [...] [config_tokenN] -``` - -## `qmk doctor` - -このコマンドは環境を調査し、潜在的なビルドあるいは書き込みの問題について警告します。必要に応じてそれらの多くを修正できます。 - -**使用法**: - -``` -qmk doctor [-y] [-n] -``` - -**例**: - -環境に問題がないか確認し、それらを修正するよう促します: - - qmk doctor - -環境を確認し、見つかった問題を自動的に修正します: - - qmk doctor -y - -環境を確認し、問題のみをレポートします: - - qmk doctor -n - -## `qmk info` - -QMK のキーボードやキーマップに関する情報を表示します。キーボードに関する情報を取得したり、レイアウトを表示したり、基礎となるキーマトリックスを表示したり、JSON キーマップをきれいに印刷したりするのに使用できます。 - -**使用法**: - -``` -qmk info [-f FORMAT] [-m] [-l] [-km KEYMAP] [-kb KEYBOARD] -``` - -このコマンドはディレクトリを認識します。キーボードやキーマップのディレクトリにいる場合、自動的に KEYBOARD や KEYMAP を入力します。 - -**例**: - -キーボードの基本情報を表示する: - - qmk info -kb planck/rev5 - -キーボードのマトリクスを表示する: - - qmk info -kb ergodox_ez -m - -キーボードの JSON キーマップを表示する: - - qmk info -kb clueboard/california -km default - -## `qmk json2c` - -QMK Configurator からエクスポートしたものから keymap.c を生成します。 - -**使用法**: - -``` -qmk json2c [-o OUTPUT] filename -``` - -## `qmk list-keyboards` - -このコマンドは現在 `qmk_firmware` で定義されている全てのキーボードを列挙します。 - -**使用法**: - -``` -qmk list-keyboards -``` - -## `qmk list-keymaps` - -このコマンドは指定されたキーボード(とリビジョン)の全てのキーマップを列挙します。 - -このコマンドはディレクトリを認識します。キーボードのディレクトリにいる場合、自動的に KEYBOARD を入力します。 - -**使用法**: - -``` -qmk list-keymaps -kb planck/ez -``` - -## `qmk new-keymap` - -このコマンドは、キーボードの既存のデフォルトのキーマップに基づいて新しいキーマップを作成します。 - -このコマンドはディレクトリを認識します。キーボードやキーマップのディレクトリにいる場合、自動的に KEYBOARD や KEYMAP を入力します。 - -**使用法**: - -``` -qmk new-keymap [-kb KEYBOARD] [-km KEYMAP] -``` - ---- - -# 開発者用コマンド - -## `qmk format-c` - -このコマンドは clang-format を使って C コードを整形します。 - -引数無しで実行すると、変更された全てのコアコードを整形します。デフォルトでは `git diff` で `origin/master` をチェックし、ブランチは `-b ` を使って変更できます。 - -`-a` で全てのコアコードを整形するか、コマンドラインでファイル名を渡して特定のファイルに対して実行します。 - -**指定したファイルに対する使い方**: - -``` -qmk format-c [file1] [file2] [...] [fileN] -``` - -**全てのコアファイルに対する使い方**: - -``` -qmk format-c -a -``` - -**origin/master で変更されたファイルのみに対する使い方**: - -``` -qmk format-c -``` - -**branch_name で変更されたファイルのみに対する使い方**: - -``` -qmk format-c -b branch_name -``` - -## `qmk docs` - -このコマンドは、ドキュメントを参照または改善するために使うことができるローカル HTTP サーバを起動します。デフォルトのポートは 8936 です。 - -**使用法**: - -``` -qmk docs [-p PORT] -``` - -## `qmk kle2json` - -このコマンドにより、生の KLE データから QMK Configurator の JSON へ変換することができます。絶対パスあるいは現在のディレクトリ内のファイル名のいずれかを受け取ります。デフォルトでは、`info.json` が既に存在している場合は上書きしません。上書きするには、`-f` あるいは `--force` フラグを使ってください。 - -**使用法**: - -``` -qmk kle2json [-f] -``` - -**例**: - -``` -$ 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 format-python` - -このコマンドは `qmk_firmware` 内の python コードを整形します。 - -**使用法**: - -``` -qmk format-python -``` - -## `qmk pytest` - -このコマンドは python のテストスィートを実行します。python コードに変更を加えた場合、これの実行が成功することを確認する必要があります。 - -**使用法**: - -``` -qmk pytest -``` diff --git a/docs/ja/cli_configuration.md b/docs/ja/cli_configuration.md deleted file mode 100644 index 6ed791b471..0000000000 --- a/docs/ja/cli_configuration.md +++ /dev/null @@ -1,126 +0,0 @@ -# QMK CLI 設定 - - - -このドキュメントは `qmk config` がどのように動作するかを説明します。 - -# はじめに - -QMK CLI の設定はキーバリューシステムです。各キーはピリオドで区切られたサブコマンドと引数名で構成されます。これにより、設定キーと設定された引数の間で簡単かつ直接的な変換が可能になります。 - -## 簡単な例 - -例として、`qmk compile --keyboard clueboard/66/rev4 --keymap default` コマンドを見てみましょう。 - -設定から読み取ることができる2つのコマンドライン引数があります: - -* `compile.keyboard` -* `compile.keymap` - -これらを設定してみましょう: - -``` -$ qmk config compile.keyboard=clueboard/66/rev4 compile.keymap=default -compile.keyboard: None -> clueboard/66/rev4 -compile.keymap: None -> default -Ψ Wrote configuration to '/Users/example/Library/Application Support/qmk/qmk.ini' -``` - -これで、毎回キーボードとキーマップを設定することなく、`qmk compile` を実行することができます。 - -## ユーザデフォルトの設定 - -複数のコマンド間で設定を共有したい場合があります。例えば、いくつかのコマンドは引数 `--keyboard` を受け取ります。全てのコマンドでこの値を設定する代わりに、その引数を受け取る全てのコマンドで使われるユーザ値を設定することができます。 - -例: - -``` -$ qmk config user.keyboard=clueboard/66/rev4 user.keymap=default -user.keyboard: None -> clueboard/66/rev4 -user.keymap: None -> default -Ψ Wrote configuration to '/Users/example/Library/Application Support/qmk/qmk.ini' -``` - -# CLI ドキュメント (`qmk config`) - -`qmk config` コマンドは基礎となる設定とやり取りするために使われます。引数無しで実行すると、現在の設定を表示します。引数が指定された場合、それらは設定トークンと見なされます。設定トークンは以下の形式の空白を含まない文字列です: - - [.][=] - -## 設定値の設定 - -設定キーに等号 (=) を入れることで、設定値を設定することができます。キーは常に完全な `
.` 形式である必要があります。 - -例: - -``` -$ qmk config default.keymap=default -default.keymap: None -> default -Ψ Wrote configuration to '/Users/example/Library/Application Support/qmk/qmk.ini' -``` - -## 設定値の読み込み - -設定全体、単一のキー、あるいはセクション全体の設定値を読み取ることができます。1つ以上の値を表示するために複数のキーを指定することができます。 - -### 全体の構成例 - - qmk config - -### セクション全体の例 - - qmk config compile - -### 単一キーの例 :id=single-key-example - - qmk config compile.keyboard - -### 複数キーの例 - - qmk config user compile.keyboard compile.keymap - -## 設定値の削除 - -設定値を特別な文字列 `None` に設定することで、設定値を削除することができます。 - -例: - -``` -$ qmk config default.keymap=None -default.keymap: default -> None -Ψ Wrote configuration to '/Users/example/Library/Application Support/qmk/qmk.ini' -``` - -## 複数の操作 - -複数の読み込みおよび書き込み操作を1つのコマンドに組み合わせることができます。それらは順番に実行および表示されます: - -``` -$ qmk config compile default.keymap=default compile.keymap=None -compile.keymap=skully -compile.keyboard=clueboard/66_hotswap/gen1 -default.keymap: None -> default -compile.keymap: skully -> None -Ψ Wrote configuration to '/Users/example/Library/Application Support/qmk/qmk.ini' -``` - -# ユーザ設定オプション - -| キー | デフォルト値 | 説明 | -|-----|---------------|-------------| -| user.keyboard | None | キーボードのパス (例: `clueboard/66/rev4`) | -| user.keymap | None | キーマップ名 (例: `default`) | -| user.name | None | ユーザの GitHub のユーザ名。 | - -# 全ての設定オプション - -| キー | デフォルト値 | 説明 | -|-----|---------------|-------------| -| compile.keyboard | None | キーボードのパス (例: `clueboard/66/rev4`) | -| compile.keymap | None | キーマップ名 (例: `default`) | -| hello.name | None | 実行時の挨拶の名前 | -| new_keyboard.keyboard | None | キーボードのパス (例: `clueboard/66/rev4`) | -| new_keyboard.keymap | None | キーマップ名 (例: `default`) | diff --git a/docs/ja/cli_development.md b/docs/ja/cli_development.md deleted file mode 100644 index 082bc5dafa..0000000000 --- a/docs/ja/cli_development.md +++ /dev/null @@ -1,223 +0,0 @@ -# QMK CLI 開発 - - - -このドキュメントは、新しい `qmk` サブコマンドを書きたい開発者に役立つ情報が含まれています。 - -# 概要 - -QMK CLI は git で有名になったサブコマンドパターンを使って動作します。メインの `qmk` スクリプトは単に環境をセットアップし、実行する正しいエントリポイントを選択するためにあります。各サブコマンドは、何らかのアクションを実行しシェルのリターンコード、または None を返すエントリーポイント (`@cli.subcommand()` で修飾されます)を備えた自己完結型のモジュールです。 - -## 開発者モード: - -キーボードを保守、あるいは QMK に貢献したい場合は、CLI の「開発者」モードを有効にすることができます: - -`qmk config user.developer=True` - -これにより利用可能な全てのサブコマンドが表示されます。 -**注意:** 追加で必要なものをインストールする必要があります: -```bash -python3 -m pip install -r requirements-dev.txt -``` - -# サブコマンド - -[MILC](https://github.com/clueboard/milc) は、`qmk` が引数の解析、設定、ログ、およびほかの多くの機能を処理するために使用する CLI フレームワークです。グルーコードを書くために時間を無駄にすることなく、ツールの作成に集中できます。 - -ローカル CLI 内のサブコマンドは、常に `qmk_firmware/lib/python/qmk/cli` で見つかります。 - -サブコマンドの例を見てみましょう。これは `lib/python/qmk/cli/hello.py` です: - -```python -"""QMK Python Hello World - -This is an example QMK CLI script. -""" -from milc import cli - - -@cli.argument('-n', '--name', default='World', help='Name to greet.') -@cli.subcommand('QMK Hello World.') -def hello(cli): - """Log a friendly greeting. - """ - cli.log.info('Hello, %s!', cli.config.hello.name) -``` - -最初に `milc` から `cli` をインポートします。これが、ユーザとやり取りをし、スクリプトの挙動を制御する方法です。`@cli.argument()` を使って、コマンドラインフラグ `--name` を定義します。これは、ユーザが設定できる `hello.name` (そして対応する `user.name`) という名前の設定変数も作成し、引数を指定する必要が無くなります。`cli.subcommand()` デコレータは、この関数をサブコマンドとして指定します。サブコマンドの名前は関数の名前から取られます。 - -関数の中に入ると、典型的な "Hello, World!" プログラムが見つかります。`cli.log` を使って、基礎となる [ロガーオブジェクト](https://docs.python.org/3.6/library/logging.html#logger-objects) にアクセスし、その挙動はユーザが制御できます。またユーザが指定した名前の値に `cli.config.hello.name` でアクセスします。`cli.config.hello.name` の値は、ユーザが指定した `--name` 引数を調べることで決定されます。指定されていない場合、`qmk.ini` 設定ファイルの中の値が使われ、どちらも指定されていない場合は `cli.argument()` デコレータで指定されたデフォルトが代用されます。 - -# ユーザとの対話処理 - -MILC と QMK CLI にはユーザとやり取りするための幾つかの便利なツールがあります。これらの標準ツールを使うと、テキストに色を付けて対話し易くし、ユーザはその情報をいつどのように表示および保存するかを制御することができます。 - -## テキストの表示 - -サブコマンド内でテキストを出力するための2つの主な方法があります- `cli.log` と `cli.echo()`。それらは似た方法で動作しますが、ほとんどの一般的な目的の出力には `cli.log.info()` を使うことをお勧めします。 - -特別なトークンを使用してテキストを色付けし、プログラムの出力を理解しやすくすることができます。以下の[テキストの色付け](#colorizing-text)を見てください。 - -これらの両方の方法は python の [printf 形式の文字列書式化](https://docs.python.org/3.6/library/stdtypes.html#old-string-formatting) を使った組み込みの文字列書式化をサポートします。テキスト文字列内で`%s` と `%d` のようなトークンを使い、引数で値を渡すことができます。例として、上記の Hello、World プログラムを見てください。 - -書式演算子 (`%`) を直接使わないでください、常に引数で値を渡します。 - -### ログ (`cli.log`) - -`cli.log` オブジェクトは[ロガーオブジェクト](https://docs.python.org/3.6/library/logging.html#logger-objects)へのアクセスを与えます。ログ出力を設定し、ユーザに各ログレベルの素敵な絵文字(またはターミナルが unicode をサポートしない場合はログレベル名)を表示します。このようにして、ユーザは何か問題が発生した時に最も重要なメッセージを一目で確認することができます。 - -デフォルトのログレベルは `INFO` です。ユーザが `qmk -v ` を実行すると、デフォルトのログレベルは `DEBUG` に設定されます。 - -| 関数 | 絵文字 | -|----------|-------| -| cli.log.critical | `{bg_red}{fg_white}¬_¬{style_reset_all}` | -| cli.log.error | `{fg_red}☒{style_reset_all}` | -| cli.log.warning | `{fg_yellow}⚠{style_reset_all}` | -| cli.log.info | `{fg_blue}Ψ{style_reset_all}` | -| cli.log.debug | `{fg_cyan}☐{style_reset_all}` | -| cli.log.notset | `{style_reset_all}¯\\_(o_o)_/¯` | - -### 出力 (`cli.echo`) - -場合によっては単にログシステムの外部でテキストを出力する必要があります。これは、固定データを出力したり、ログに記録してはいけない何かを書きだす場合に適しています。ほとんどの場合、`cli.echo` よりも `cli.log.info()` を選ぶべきです。 - -### テキストの色付け - -テキスト内に色トークンを含めることで、テキストの出力を色付けすることができます。情報を伝えるためではなく、強調するために色を使います。ユーザは色を無効にできることを覚えておいてください。色を無効にした場合でもサブコマンドは引き続き使えるようにしてください。 - -背景色を設定するのは、あなたがやっていることに不可欠ではない限り、通常は避けるべきです。ユーザは、ターミナルの色に関しては多くの好みを持つため、あなたは黒と白のどちらの背景に対してもうまく機能する色を選択する必要があることを覚えておいてください。 - -'fg' という接頭辞の付いた色は、前景(テキスト)色に影響します。'bg' という接頭辞の付いた色は、背景色に影響します。 - -| 色 | 背景 | 拡張背景 | 前景 | 拡張前景 | -|-------|------------|---------------------|------------|--------------------| -| 黒 | {bg_black} | {bg_lightblack_ex} | {fg_black} | {fg_lightblack_ex} | -| 青 | {bg_blue} | {bg_lightblue_ex} | {fg_blue} | {fg_lightblue_ex} | -| シアン | {bg_cyan} | {bg_lightcyan_ex} | {fg_cyan} | {fg_lightcyan_ex} | -| 緑 | {bg_green} | {bg_lightgreen_ex} | {fg_green} | {fg_lightgreen_ex} | -| マゼンタ | {bg_magenta} | {bg_lightmagenta_ex} | {fg_magenta} | {fg_lightmagenta_ex} | -| 赤 | {bg_red} | {bg_lightred_ex} | {fg_red} | {fg_lightred_ex} | -| 白 | {bg_white} | {bg_lightwhite_ex} | {fg_white} | {fg_lightwhite_ex} | -| 黄 | {bg_yellow} | {bg_lightyellow_ex} | {fg_yellow} | {fg_lightyellow_ex} | - -ANSI 出力の挙動を変更するために使うことができる制御シーケンスもあります。 - -| 制御シーケンス | 説明 | -|-------------------|-------------| -| {style_bright} | テキストを明るくする | -| {style_dim} | テキストを暗くする | -| {style_normal} | テキストを通常にする (`{style_bright}` または `{style_dim}` のどちらでもない) | -| {style_reset_all} | 全てのテキストの属性をデフォルトに再設定する(これは自動的に全ての文字列の最後に自動的に追加されます。) | -| {bg_reset} | 背景色をユーザのデフォルトに再設定します。 | -| {fg_reset} | 背景色をユーザのデフォルトに再設定します。 | - -# 引数と設定 - -QMK は引数の解析と設定の詳細をあなたの代わりに処理します。新しい引数を追加すると、サブコマンドの名前と引数の長い名前に基づいて設定ツリーに自動的に組み込まれます。属性形式のアクセス (`cli.config..`) あるいは辞書形式のアクセス (`cli.config['']['']`) を使って、`cli.config` 内のこの設定にアクセスすることができます。 - -内部では、QMK は [設定ファイルのパーサ](https://docs.python.org/3/library/configparser.html) を使って設定を格納します。これにより、人間が編集可能な方法で設定を表す簡単で分かり易い方法を提供します。この設定へのアクセスをラップして、設定ファイルのパーサーが通常持たない幾つかの機能を提供しています。 - -## 設定値の読み込み - -通常期待される全ての方法で `cli.config` とやり取りすることができます。例えば、`qmk compile` コマンドは `cli.config.compile.keyboard` からキーボード名を取得します。値がコマンドライン、環境変数あるいは設定ファイルからきたものであるかどうかを知る必要はありません。 - -繰り返しもサポートされます: - -``` -for section in cli.config: - for key in cli.config[section]: - cli.log.info('%s.%s: %s', section, key, cli.config[section][key]) -``` - -## 設定値の設定 - -通常の方法で設定値を設定することができます。 - -辞書形式: - -``` -cli.config['
'][''] = -``` - -属性形式: - -``` -cli.config.
. = -``` - -## 設定値の削除 - -通常の方法で設定値を削除することができます。 - -辞書形式: - -``` -del(cli.config['
']['']) -``` - -属性形式: - -``` -del(cli.config.
.) -``` - -## 設定ファイルの書き方 - -設定は変更しても書き出されません。ほとんどのコマンドでこれをする必要はありません。ユーザに `qmk config` を使って設定を慎重に変更させることをお勧めします。 - -設定を書き出すために `cli.save_config()` を使うことができます。 - -## 設定からの引数の除外 - -一部の引数は設定ファイルに反映すべきではありません。これらは引数を作成する時に `arg_only=True` を追加することで除外することができます。 - -例: - -``` -@cli.argument('-o', '--output', arg_only=True, help='File to write to') -@cli.argument('filename', arg_only=True, help='Configurator JSON file') -@cli.subcommand('Create a keymap.c from a QMK Configurator export.') -def json_keymap(cli): - pass -``` - -`cli.args` を使ってのみこれらの引数にアクセスすることができます。例えば: - -``` -cli.log.info('Reading from %s and writing to %s', cli.args.filename, cli.args.output) -``` - -# テスト、リントおよびフォーマット - -nose2、flake8 および yapf を使ってコードをテスト、リントおよびフォーマットします。これらのテストを実行するために `pytest` と `format-python` サブコマンドを使うことができます。 - -### テストとリント - - qmk pytest - -### フォーマット - - qmk format-python - -## フォーマットの詳細 - -[yapf](https://github.com/google/yapf) を使ってコードを自動的にフォーマットします。フォーマットの設定は `setup.cfg` の `[yapf]` セクションにあります。 - -?> ヒント- 多くのエディタは yapf をプラグインとして使って、入力したコードを自動的にフォーマットすることができます。 - -## テストの詳細 - -テストは `lib/python/qmk/tests/` にあります。このディレクトリに単体テストと統合テストの両方があります。コードの単体テストと統合テストの両方を書いてほしいですが、一方のみ書く場合は統合テストを優先してください。 - -PR にテストの包括的なセットが含まれない場合は、次のようなコメントをコードに追加して、他の人が手助けできるようにしてください: - - # TODO(unassigned/): Write tests - -[nose2](https://nose2.readthedocs.io/en/latest/getting_started.html) を使ってテストを実行します。テスト関数でできることの詳細については、nose2 のドキュメントを参照してください。 - -## リントの詳細 - -flake8 を使ってコードをリントします。PR を開く前に、コードは flake8 をパスしなければなりません。これは `qmk pytest` を実行するときにチェックされ、PR を登録したときに CI によってチェックされます。 diff --git a/docs/ja/coding_conventions_c.md b/docs/ja/coding_conventions_c.md deleted file mode 100644 index c3d2de734e..0000000000 --- a/docs/ja/coding_conventions_c.md +++ /dev/null @@ -1,63 +0,0 @@ -# コーディング規約 (C) - - - -私たちのスタイルのほとんどはかなり理解しやすいですが、現時点では完全に一貫しているわけではありません。変更箇所周辺のコードのスタイルと一致させる必要がありますが、そのコードに一貫性が無い場合や不明瞭な場合は以下のガイドラインに従ってください: - -* 4つのスペース (ソフトタブ) を使ってインデントします。 -* 修正版 One True Brace Style を使います。 - * 開き括弧: ブロックを開始する文と同じ行の最後 - * 閉じ括弧: ブロックを開始した文と同じ字下げ - * Else If: 行の先頭に閉じ括弧を置き、次の開き括弧を同じ行の最後に置きます。 - * 省略可能な括弧: 常に括弧を付け加えます。 - * 良い: if (condition) { return false; } - * 悪い: if (condition) return false; -* C 形式のコメントの使用を推奨します: `/* */` - * コメントを機能を説明するストーリーと考えて下さい。 - * 特定の決定がなされた理由を充分なコメントで説明してください。 - * 分かり切ったコメントは書かないでください。 - * 分かり切ったコメントであるか確信できない場合は、コメントを含めてください。 -* 一般的に、行を折り返さないで、必要なだけ長くすることができます。行を折り返すことを選択した場合は、76列を超えて折り返さないでください。 -* 古い形式のインクルードガード (`#ifndef THIS_FILE_H`、`#define THIS_FILE_H`、...、`#endif`) ではなく、ヘッダファイルの先頭で `#pragma once` を使います。 -* プリプロセッサ if の両方の形式を受け付けます: `#ifdef DEFINED` と `#if defined(DEFINED)` - * どちらがいいかわからない場合は、`#if defined(DEFINED)` 形式を使ってください。 - * 複数の条件 `#if` に移行する場合を除き、既存のコードを別のスタイルに変更しないでください。 -* プリプロセッサディレクティブをインデントする方法(あるいはするかどうか)を決定する時は、以下の事に留意してください: - * 一貫性よりも読みやすさが重要です。 - * ファイルの既存のスタイルに従ってください。ファイルのスタイルが混在している場合は、修正しようとしているセクションに適したスタイルに従ってください。 - * インデントする時は、ハッシュを行の先頭に置き、`#` と `if` の間に空白を追加します。`#` の後ろに4つスペースを入れて開始します。 - * 周りの C コードのインデントレベルに従うか、プリプロセッサのディレクティブに独自のインデントレベルを設定することができます。コードの意図を最もよく伝えるスタイルを選択してください。 - -わかりやすいように例を示します: - -```c -/* Enums for foo */ -enum foo_state { - FOO_BAR, - FOO_BAZ, -}; - -/* Returns a value */ -int foo(void) { - if (some_condition) { - return FOO_BAR; - } else { - return -1; - } -} -``` - -# clang-format を使った自動整形 - -[Clang-format](https://clang.llvm.org/docs/ClangFormat.html) は LLVM の一部で、誰もが手動で整形するほど暇ではないため、コードを自動整形することができます。私たちは、上記のコーディング規約のほとんどを適用する設定ファイルを提供しています。空白と改行のみを変更するため、省略可能な括弧は自分で付け加えることを忘れないでください。 - -Windows で clang-format を入手するには [full LLVM インストーラ](https://llvm.org/builds/)を使い、Ubuntu では `sudo apt install clang-format` を使ってください。 - -コマンドラインから実行する場合、オプションとして `-style=file` を渡すと、QMK ルートディレクトリ内の .clang-format 設定ファイルを自動的に見つけます。 - -VSCode を使う場合は、標準の C/C++ プラグインが clang-format をサポートしますが、その他にも [独立した拡張機能](https://marketplace.visualstudio.com/items?itemName=LLVMExtensions.ClangFormat) があります。 - -幾つかのコード (LAYOUT マクロのような)が clang-format によって破壊されるため、これらのファイルで clang-format を実行しないか、整形したくないコードを `// clang-format off` と `// clang-format on` で囲みます。 diff --git a/docs/ja/coding_conventions_python.md b/docs/ja/coding_conventions_python.md deleted file mode 100644 index d8d4a31503..0000000000 --- a/docs/ja/coding_conventions_python.md +++ /dev/null @@ -1,331 +0,0 @@ -# コーディング規約 (Python) - - - -私たちのスタイルの大部分は PEP8 に従いますが、神経質にならないように幾つかのローカルな変更を加えています。 - -* サポートされる全てのプラットフォームとの互換性のために、Python 3.6 を対象にしています。 -* 4つのスペース (ソフトタブ) を使ってインデントします -* 充分なコメントを書くことを推奨します - * コメントを機能を説明するストーリーと考えて下さい - * 特定の決定がなされた理由を充分なコメントで説明してください。 - * 分かり切ったコメントは書かないでください - * 分かり切ったコメントであるか確信できない場合は、コメントを含めてください。 -* 全ての関数について、役に立つ docstring を必要とします。 -* 一般的に、行を折り返さないで、必要なだけ長くすることができます。行を折り返すことを選択した場合は、76列を超えて折り返さないでください。 -* 私たちの慣習の幾つかは、Python 使いでは無い人にコードベースをより身近にするために、python コミュニティに広まっているものとは競合しています。 - -# YAPF - -コードを整形するために [yapf](https://github.com/google/yapf) を使うことができます。[setup.cfg](setup.cfg) で設定を提供しています。 - -# インポート - -`import ...` や `from ... import ...` をいつ使うかについての厳密なルールはありません。理解しやすさと保守性が究極の目的です。 - -一般的に、コードを短く理解しやすくするためにモジュールから特定の関数とクラス名をインポートする方が望ましいです。これにより、名前が曖昧になることがあります。代わりにモジュールをインポートするようにします。互換性のあるモジュールをインポートする時を除いて、インポートする時は "as" キーワードを避けるべきです。 - -インポートは各モジュール1行にする必要があります。標準的な python ルールに従って、インポート文をシステム、サードパーティ、ローカルにグループ化します。 - -`from foo import *` を使わないでください。代わりにインポートしたいオブジェクトのリストを指定するか、モジュール全体をインポートします。 - -## インポートの例 - -良い: - -``` -from qmk import effects - -effects.echo() -``` - -悪い: - -``` -from qmk.effects import echo - -echo() # echoがどこから来たのかが不明瞭です -``` - -良い: - -``` -from qmk.keymap import compile_firmware - -compile_firmware() -``` - -良いですが、上の方がより良いです: - -``` -import qmk.keymap - -qmk.keymap.compile_firmware() -``` - -# 命令文 - -各行1文としてください。 - -可能な場合(例えば `if foo: bar`)でも、2つの文を1行にまとめないでください。 - -# 命名 - -`module_name`, `package_name`, `ClassName`, `method_name`, `ExceptionName`, `function_name`, `GLOBAL_CONSTANT_NAME`, `global_var_name`, `instance_var_name`, `function_parameter_name`, `local_var_name`. - -関数名、変数名 およびファイル名は説明的でなければなりません; 略語を避けます。特に、プロジェクト外の読み手に曖昧あるいは馴染みのない略語を使わず、単語内の文字を削除して略さないでください。 - -常に .py のファイル名の拡張子を使います。ダッシュを使わないでください。 - -## 避けるべき名前 - -* カウンタあるいはイテレータ以外の1文字の名前。try/except 文では例外の識別子として `e` を使うことができます。 -* パッケージ/モジュール名内のダッシュ (`-`) -* `__double_leading_and_trailing_underscore__` (2つのアンダースコアで始まる名前と終わる名前、Python で予約済み) - -# Docstring - -docstring の一貫性を維持するために、以下のガイドラインを設定しました。 - -* マークダウン(Markdown)形式の使用 -* 常に少なくとも1つの改行を含む3つのダブルクォートの docstring を使ってください: `"""\n"""` -* 最初の行は、関数が行うことの短い (70文字未満) 説明です。 -* docstring が更に必要な場合は、説明と残りの間に空白行を入れます。 -* 開始の3つのダブルクォートと同じインデントレベルでインデント行を始めます -* 以下で説明する形式を使って全ての関数の引数について記述します -* Args:、Returns: および Raises: が存在する場合、それらは docstring の最後の3つの要素で、それぞれ空白行で区切られなければなりません。 - -## 簡単な docstring の例 - -``` -def my_awesome_function(): - """1970 Jan 1 00:00 UTC からの秒数を返します。 - """ - return int(time.time()) -``` - -## 複雑な docstring の例 - -``` -def my_awesome_function(): - """1970 Jan 1 00:00 UTC からの秒数を返します。 - - この関数は常に整数の秒数を返します。 - """ - return int(time.time()) -``` - -## 関数の引数の docstring の例 - -``` -def my_awesome_function(start=None, offset=0): - """1970 Jan 1 00:00 UTC からの秒数を返します。 - - この関数は常に整数の秒数を返します。 - - - Args: - start - 1970 Jan 1 00:00 UTC の代わりの開始時間 - - offset - 最初の引数からこの秒数が引かれた答えを返します - - Returns: - 秒数を表す整数。 - - Raises: - ValueError - `start` あるいは `offset` が正の数ではない場合 - """ - if start < 0 or offset < 0: - raise ValueError('start and offset must be positive numbers.') - - if not start: - start = time.time() - - return int(start - offset) -``` - -# 例外 - -例外は例外的な状況を処理するために使われます。フローの制御のために使われるべきではありません。これは Python の「許しを請う」という規範からの逸脱です。例外をキャッチする場合、異常な状況を処理する必要があります。 - -何らかの理由で全ての例外のキャッチを使う場合は、cli.log を使って例外とスタックトレースを記録する必要があります。 - -try/except ブロックをできるだけ短くします。多数の try 文が必要な場合は、コードを再構成する必要があるかもしれません。 - -# タプル - -1項目のタプルを定義する場合、タプルを使用していることが明らかになるように、常に末尾のカンマを含めます。暗黙的な1項目のタプルのアンパックに頼らないでください。明確なリストを使う方が良いです。 - -これはよく使用される printf 形式の書式文字列を使う場合に、特に重要です。 - -# リストと辞書 - -シーケンス形式と末尾のカンマとを区別するように YAPF を設定しました。末尾のカンマが省略されると、YAPF はシーケンスを1つの行として整形します。末尾のカンマがある場合、YAPF はシーケンスを1行1項目で整形します。 - -一般的に1行が短い定義になるようにすべきです。読みやすさと保守性を向上させるために、後からではなく早めに複数の行を分割してください。 - -# 括弧 - -過度な括弧は避けますが、括弧を使ってコードを理解しやすくします。タプルを明示的に返すか、あるいは数式の一部である場合を除き、return 文で括弧を使わないでください。 - -# 書式文字列 - -一般的に printf 形式の書式文字列を用います。例: - -``` -name = 'World' -print('Hello, %s!' % (name,)) -``` - -このスタイルはログモジュールで使われており、私たちはそれを広範囲で利用しており、一貫性を保つために他の場所でも採用しています。これは、私たちの気まぐれな読者の大部分である C プログラマにもおなじみのスタイルです。 - -付属の CLI モジュールは、パーセント (%) 演算子を使わずにこれらを使うことをサポートしています。詳細は、`cli.echo()` と様々な `cli.log` 関数 (例えば、`cli.log.info()`) を見てください。 - -# 内包表記とジェネレータ表記 - -内包表記とジェネレータの自由な使用を推奨しますが、あまりに複雑にしないでください。複雑になる場合は、理解しやすい for ループで代替します。 - -# ラムダ - -使っても問題ありませんが、おそらく避けるべきです。内包表記とジェネレータを使えば、ラムダの必要性は以前ほど強くありません。 - -# 条件式 - -変数の割り当てでは問題ありませんが、そうでなければ避けるべきです。 - -条件式はコードに続く if 文です。例えば: - -``` -x = 1 if cond else 2 -``` - -一般にこれらを関数の引数、シーケンス項目などとして使用することはお勧めできません。見落としやすくなります。 - -# デフォルト引数 - -推奨されていますが、値は不変オブジェクトでなければなりません。 - -デフォルト値に引数リストを指定する場合は、その場で変更できないオブジェクトを指定するように常に注意してください。可変オブジェクトを使うと変更は呼び出しの間で持続しますが、これは通常あなたの望むものではありませんそれがあなたのやろうとしていることであっても、他の人にとっては混乱するもので理解を妨げます。 - -悪い: - -``` -def my_func(foo={}): - pass -``` - -良い: - -``` -def my_func(foo=None): - if not foo: - foo = {} -``` - -# プロパティ - -getter および setter 関数の代わりにプロパティを常に使います。 - -``` -class Foo(object): - def __init__(self): - self._bar = None - - @property - def bar(self): - return self._bar - - @bar.setter - def bar(self, bar): - self._bar = bar -``` - -# True/False の評価 - -一般的に、if 文で等価性を調べるのではなく、暗黙的な True/False 評価を行うべきです。 - -悪い: - -``` -if foo == True: - pass - -if bar == False: - pass -``` - -良い: - -``` -if foo: - pass - -if not bar: - pass -``` - -# デコレータ - -適切な時に使ってください。理解に役立つ時を除き、魔法の(ように見える技巧の)使いすぎは避けるようにしてください。 - -# スレッドとマルチプロセス - -避けるべきです。これが必要な場合は、私たちがコードをマージする前に十分な理由を述べる必要があります。 - -# 強力な機能 - -Python は非常に柔軟な言語で、独自のメタクラス、バイトコードへのアクセス、実行中コンパイル、動的な継承、オブジェクトの親の変更、インポートハック、リフレクション、システム内部の変更など、多くの素晴らしい機能を提供します。 - -これらを使わないでください。 - -パフォーマンスは私たちにとって重要な関心ごとではなく、コードのわかりやすさに関心があります。私たちは、コードベースを1日か2日しかいじっていない人が利用できるようにしたいです。これらの機能は一般的に理解のしやすさを犠牲にするため、より高速あるいはよりコンパクトなコードよりも、容易に理解できるコードの方が望ましいです。 - -一部の標準ライブラリモジュールはこれらの手法を使っており、これらのモジュールを利用しても問題ありません。ただし、それらを使う時には、読みやすさと理解のしやすさを忘れないでください。 - -# 型アノテーション付きコード - -今のところ型アノテーションシステムを使っていないため、コードにアノテーションをつけないようにしてください。将来的にはこれを再検討する可能性があります。 - -# 関数の長さ - -小さくて焦点のあった関数にしてください。 - -長い関数が時には適切であることを理解しているので、関数の長さには厳密な制限はありません。関数が約40行を超える場合は、プログラムの構造を損なわずに分割できるかどうかを検討してください。 - -今のところ長い関数が完全に機能するとしても、数か月でそれを変更する人が新しい挙動を追加するかもしれません。これにより見つけにくいバグが発生するかもしれません。関数を短くかつシンプルにすることで、他の人がコードを読んで修正しやすくします。 - -幾つかのコードで作業をすると、長く複雑な関数を見つけるかもしれません。既存コードを変更することを怖がらないでください: もし、難しいことが判明したり、エラーがデバッグしづらいとわかったり、いくつかの異なるコンテキストで一部を使いたいような関数を扱っている場合、関数を小さくてより扱いやすい単位に分割することを検討してください。 - -# FIXME - -FIXME をコードに残しても構いません。なぜでしょうか？このコードを文章化しないままにするよりも、少なくとも考え抜く必要がある(あるいは混乱している)コードの一部を文章化するように奨励する方が、このコードを文章化しないままにするよりも良いです。 - -全ての FIXME は以下のように書式化されるべきです: - -``` -FIXME(username): 何々機能が完了したらこのコードを再検討する。 -``` - -...username はあなたの GitHub のユーザ名です。 - -# テスト - -統合テストと単体テストの組み合わせを使ってコードが可能な限りバグが無いようにします。全てのテストは `lib/python/qmk/tests/` にあります。`qmk pytest` を使って全てのテストを実行することができます。 - -これを書いている時点では、テストは全く完全なものではありません。現在のテストを見て、テストされていない状況のための新しいテストケースを書くことは、コードベースに精通し、QMK に貢献するという両方の点で素晴らしい方法です。 - -## 統合テスト - -統合テストは `lib/python/qmk/tests/test_cli_commands.py` にあります。ここで実際に CLI コマンドが実行され、全体的な動作が検証されます。[`subprocess`](https://docs.python.org/3.6/library/subprocess.html#module-subprocess) を使って各 CLI コマンドを起動し、正しく動作するかを判断するために出力とリターンコードの組み合わせを使います。 - -## ユニットテスト - -`lib/python/qmk/tests/` 内の他の `test_*.py` ファイルはユニットテストを含みます。`lib/python/qmk/` 内の個々の関数のテストをここに書くことができます。一般的にこれらのファイルはモジュールに基づいて名前を付けられ、ドットはアンダースコアで置き換えられます。 - -これを書いている時点では、テストのためのモックを作っていません。これを変更する手伝いをしたい場合は、[issue を開く](https://github.com/qmk/qmk_firmware/issues/new?assignees=&labels=cli%2C+python&template=other_issues.md&title=) か [Discord の #cli に参加](https://discord.gg/heQPAgy)し、そこで会話を開始してください。 diff --git a/docs/ja/compatible_microcontrollers.md b/docs/ja/compatible_microcontrollers.md deleted file mode 100644 index 23f32bbb60..0000000000 --- a/docs/ja/compatible_microcontrollers.md +++ /dev/null @@ -1,54 +0,0 @@ -# 互換性のあるマイクロコントローラ - - - -QMK は十分な容量のフラッシュメモリを備えた USB 対応 AVR または ARM マイクロコントローラで実行されます - 一般的に 32kB 以上ですが、ほとんどの機能を無効にすると*ほんの* 16kB に詰め込むことができます。 - -## Atmel AVR - -以下は、USB スタックとして [LUFA](https://www.fourwalledcubicle.com/LUFA.php) を使います: - -* [ATmega16U2](https://www.microchip.com/wwwproducts/en/ATmega16U2) / [ATmega32U2](https://www.microchip.com/wwwproducts/en/ATmega32U2) -* [ATmega16U4](https://www.microchip.com/wwwproducts/en/ATmega16U4) / [ATmega32U4](https://www.microchip.com/wwwproducts/en/ATmega32U4) -* [AT90USB64](https://www.microchip.com/wwwproducts/en/AT90USB646) / [AT90USB128](https://www.microchip.com/wwwproducts/en/AT90USB1286) -* [AT90USB162](https://www.microchip.com/wwwproducts/en/AT90USB162) - -組み込みの USB インターフェースを持たない、いくつかの MCU は代わりに [V-USB](https://www.obdev.at/products/vusb/index.html) を使います: - -* [ATmega32A](https://www.microchip.com/wwwproducts/en/ATmega32A) -* [ATmega328P](https://www.microchip.com/wwwproducts/en/ATmega328P) -* [ATmega328](https://www.microchip.com/wwwproducts/en/ATmega328) - -## ARM - -[ChibiOS](https://www.chibios.org) がサポートする USB 付きの ARM チップを使うこともできます。ほとんどのチップには十分な容量のフラッシュメモリがあります。動作するとわかっているのは: - -### STMicroelectronics (STM32) - -* [STM32F0x2](https://www.st.com/en/microcontrollers-microprocessors/stm32f0x2.html) -* [STM32F103](https://www.st.com/en/microcontrollers-microprocessors/stm32f103.html) -* [STM32F303](https://www.st.com/en/microcontrollers-microprocessors/stm32f303.html) -* [STM32F401](https://www.st.com/en/microcontrollers-microprocessors/stm32f401.html) -* [STM32F405](https://www.st.com/en/microcontrollers-microprocessors/stm32f405-415.html) -* [STM32F407](https://www.st.com/en/microcontrollers-microprocessors/stm32f407-417.html) -* [STM32F411](https://www.st.com/en/microcontrollers-microprocessors/stm32f411.html) -* [STM32F446](https://www.st.com/en/microcontrollers-microprocessors/stm32f446.html) -* [STM32G431](https://www.st.com/en/microcontrollers-microprocessors/stm32g4x1.html) -* [STM32G474](https://www.st.com/en/microcontrollers-microprocessors/stm32g4x4.html) -* [STM32L412](https://www.st.com/en/microcontrollers-microprocessors/stm32l4x2.html) -* [STM32L422](https://www.st.com/en/microcontrollers-microprocessors/stm32l4x2.html) -* [STM32L433](https://www.st.com/en/microcontrollers-microprocessors/stm32l4x3.html) -* [STM32L443](https://www.st.com/en/microcontrollers-microprocessors/stm32l4x3.html) - -### NXP (Kinetis) - -* [MKL26Z64](https://www.nxp.com/products/processors-and-microcontrollers/arm-microcontrollers/general-purpose-mcus/kl-series-cortex-m0-plus/kinetis-kl2x-72-96-mhz-usb-ultra-low-power-microcontrollers-mcus-based-on-arm-cortex-m0-plus-core:KL2x) -* [MK20DX128](https://www.nxp.com/products/processors-and-microcontrollers/arm-microcontrollers/general-purpose-mcus/k-series-cortex-m4/k2x-usb/kinetis-k20-50-mhz-full-speed-usb-mixed-signal-integration-microcontrollers-based-on-arm-cortex-m4-core:K20_50) -* [MK20DX256](https://www.nxp.com/products/processors-and-microcontrollers/arm-microcontrollers/general-purpose-mcus/k-series-cortex-m4/k2x-usb/kinetis-k20-72-mhz-full-speed-usb-mixed-signal-integration-microcontrollers-mcus-based-on-arm-cortex-m4-core:K20_72) - -## Atmel ATSAM - -Atmel の ATSAM マイクロコントローラの一つである、[Massdrop keyboards](https://github.com/qmk/qmk_firmware/tree/master/keyboards/massdrop) で使用されている [ATSAMD51J18A](https://www.microchip.com/wwwproducts/en/ATSAMD51J18A) には限定的なサポートがあります。 diff --git a/docs/ja/config_options.md b/docs/ja/config_options.md deleted file mode 100644 index 6cc1b6bfcd..0000000000 --- a/docs/ja/config_options.md +++ /dev/null @@ -1,410 +0,0 @@ -# QMK の設定 - - - -QMK はほぼ無制限に設定可能です。可能なところはいかなるところでも、やりすぎな程、ユーザーがコードサイズを犠牲にしてでも彼らのキーボードをカスタマイズをすることを許しています。ただし、このレベルの柔軟性により設定が困難になります。 - -QMK には主に２種類の設定ファイルがあります- `config.h` と `rules.mk`。これらのファイルは QMK の様々なレベルに存在し、同じ種類の全てのファイルは最終的な設定を構築するために組み合わされます。最低の優先度から最高の優先度までのレベルは以下の通りです: - -* QMK デフォルト -* キーボード -* フォルダ (最大5レべルの深さ) -* キーマップ - -## QMK デフォルト - -QMK での全ての利用可能な設定にはデフォルトがあります。その設定がキーボード、フォルダ、あるいはキーマップレべルで設定されない場合、これが使用される設定です。 - -## キーボード - -このレベルにはキーボード全体に適用される設定オプションが含まれています。一部の設定は、リビジョンあるいはほとんどのキーマップで変更されません。他の設定はこのキーボードのデフォルトに過ぎず、フォルダあるいはキーマップによって上書きされる可能性があります。 - -## フォルダ - -一部のキーボードには、異なるハードウェア構成のためのフォルダとサブフォルダがあります。ほとんどのキーボードは深さ1のフォルダのみですが、QMK は最大深さ5のフォルダの構造をサポートします。各フォルダは、最終的な設定に組み込まれる独自の `config.h` と `rules.mk` ファイルを持つことができます。 - -## キーマップ - -このレベルには特定のキーマップのための全てのオプションが含まれています。以前の定義を上書きしたい場合は、`#undef ` を使って定義を解除し、エラー無しで再定義することができます。 - -# `config.h` ファイル - -これは最初に include されるものの 1 つである C ヘッダファイルで、プロジェクト全体(もし含まれる場合)にわたって持続します。多くの変数をここで設定し、他の場所からアクセスすることができます。`config.h` ファイルでは、以下のもの以外の、他の `config.h` ファイルやその他のファイルの include をしないでください: - -```c -#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 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 MATRIX_IO_DELAY 30` - * マトリックスピン状態の変更と値の読み取り間のマイクロ秒単位の遅延 -* `#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 AUDIO_PIN C4` を使ってください -* `#define C5_AUDIO` - * ピン C5 のオーディオを有効にします - * 非推奨。`#define AUDIO_PIN C5` を使ってください -* `#define C6_AUDIO` - * ピン C6 のオーディオを有効にします - * 非推奨。`#define AUDIO_PIN C6` を使ってください -* `#define B5_AUDIO` - * ピン B5 のオーディオを有効にします (C ピンの1つとともに B ピンの1つが有効にされている場合、疑似ステレオが有効にされます) - * 非推奨。もし `AUDIO_PIN` で `C` ピンを有効にしている場合は、`#define AUDIO_PIN_ALT B5` を使い、そうでなければ `#define AUDIO_PIN B5` を使います。 -* `#define B6_AUDIO` - * ピン B6 のオーディオを有効にします (C ピンの1つとともに B ピンの1つが有効にされている場合、疑似ステレオが有効にされます) - * 非推奨。もし `AUDIO_PIN` で `C` ピンを有効にしている場合は、`#define AUDIO_PIN_ALT B6` を使い、そうでなければ `#define AUDIO_PIN B6` を使います。 -* `#define B7_AUDIO` - * ピン B7 のオーディオを有効にします (C ピンの1つとともに B ピンの1つが有効にされている場合、疑似ステレオが有効にされます) - * 非推奨。もし `AUDIO_PIN` で `C` ピンを有効にしている場合は、`#define AUDIO_PIN_ALT B7` を使い、そうでなければ `#define AUDIO_PIN B7` を使います。 -* `#define BACKLIGHT_PIN B7` - * バックライトのピン -* `#define BACKLIGHT_LEVELS 3` - * バックライトのレベル数 (off を除いて最大31) -* `#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 USB_SUSPEND_WAKEUP_DELAY 0` - * ウェイクアップパケットを送信した後で一時停止するミリ秒を設定します -* `#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` - * キーリリースがどのレイヤーから来たのかを覚えるのではなく、現在のレイヤースタックを使って強制的に評価されるようにします (高度なケースに使われます) - -## 設定可能な挙動 :id=behaviors-that-can-be-configured - -* `#define TAPPING_TERM 200` - * タップがホールドになるまでの時間。 -* `#define TAPPING_TERM_PER_KEY` - * キーごとの `TAPPING_TERM` 設定の処理を有効にします -* `#define RETRO_TAPPING` - * 押下とリリースの間に他のキーによる中断がなければ、TAPPING_TERM の後であってもとにかくタップします - * 詳細は [Retro Tapping](ja/tap_hold.md#retro-tapping) を見てください -* `#define RETRO_TAPPING_PER_KEY` - * キーごとの `RETRO_TAPPING` 設定の処理を有効にします -* `#define TAPPING_TOGGLE 2` - * トグルを引き起こす前のタップ数 -* `#define PERMISSIVE_HOLD` - * `TAPPING_TERM` にヒットしていなくても、リリースする前に別のキーが押されると、タップとホールドキーがホールドを引き起こします - * 詳細は [Permissive Hold](ja/tap_hold.md#permissive-hold) を見てください -* `#define PERMISSIVE_HOLD_PER_KEY` - * キーごとの `PERMISSIVE_HOLD` 設定の処理を有効にします -* `#define TAPPING_FORCE_HOLD` - * タップされた直後に、デュアルロールキーを修飾子として使用できるようにします - * [Tapping Force Hold](ja/tap_hold.md#tapping-force-hold)を見てください - * タップトグル機能を無効にします (`TT` あるいは One Shot Tap Toggle) -* `#define TAPPING_FORCE_HOLD_PER_KEY` - * キーごとの `TAPPING_FORCE_HOLD` 設定処理を有効にします。 -* `#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 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_LAYERS` - * オンとオフを切り替えることができる [ライトレイヤー](ja/feature_rgblight.md?id=lighting-layers) を定義できます。現在のキーボードレイヤーまたは Caps Lock 状態を表示するのに最適です。 -* `#define RGBLIGHT_MAX_LAYERS` - * デフォルトは8です。もしさらに [ライトレイヤー](ja/feature_rgblight.md?id=lighting-layers) が必要であれば、32まで拡張できます。 - * メモ: 最大値を大きくするとファームウェアサイズが大きくなり、分割キーボードで同期が遅くなります。 -* `#define RGBLIGHT_LAYER_BLINK` - * 指定されたミリ秒の間、ライトレイヤーを [点滅](ja/feature_rgblight.md?id=lighting-layer-blink) する機能を追加します(例えば、アクションを確認するため)。 -* `#define RGBLIGHT_LAYERS_OVERRIDE_RGB_OFF` - * 定義されている場合、RGB ライトがオフになっている場合でも [ライトレイヤー](ja/feature_rgblight?id=overriding-rgb-lighting-onoff-status) が表示されます。 -* `#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 ベースの分割キーボードはこれを使わなければなりません。 - -### 左右の設定 - -1つ覚えておかなければならないことは、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 SPLIT_HAND_MATRIX_GRID ,` - * 左右はキーマトリックスのキースイッチが存在しない交点を使って決定されます。通常、この交点が短絡している(ローレベル)のときに右側と見なされます。もし `#define SPLIT_HAND_MATRIX_GRID_LOW_IS_LEFT` が定義されている場合は、ローレベルの時に左側と決定されます。 - -* `#define EE_HANDS` (`SPLIT_HAND_PIN` と `SPLIT_HAND_MATRIX_GRID` が定義されていない場合のみ動作します) - * `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 { }` -* `#define MATRIX_COL_PINS_RIGHT { }` - * 右半分に左半分と異なるピン配置を指定したい場合は、`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 ` (デフォルトの速度は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 2000` - * `SPLIT_USB_DETECT` を使う時のマスタ/スレーブを検出する場合の最大タイムアウト - -* `#define SPLIT_USB_TIMEOUT_POLL 10` - * `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` - * コンパイル・リンクリストにファイルを追加するために使われます。 -* `LIB_SRC` - * コンパイル・リンクリストにライブラリとしてファイルを追加するために使われます。 - `LIB_SRC` で指定されたファイルは、`SRC` で指定されたファイルの後にリンクされます。 - 例えば、次のように指定した場合: - ``` - SRC += a.c - LIB_SRC += lib_b.c - SRC += c.c - LIB_SRC += lib_d.c - ``` - リンク順は以下の通りです。 - ``` - ... a.o c.o ... lib_b.a lib_d.a ... - ``` -* `LAYOUTS` - * このキーボードがサポートする[レイアウト](ja/feature_layouts.md)のリスト -* `LTO_ENABLE` - * キーボードをコンパイルする時に、Link Time Optimization (LTO) を有効にします。これは処理に時間が掛かりますが、コンパイルされたサイズを大幅に減らします (そして、ファームウェアが小さいため、追加の時間は分からないくらいです)。 -ただし、LTO が有効な場合、古い TMK のマクロと関数の機能が壊れるため、自動的にこれらの機能を無効にします。これは `NO_ACTION_MACRO` と `NO_ACTION_FUNCTION` を自動的に定義することで行われます。(メモ: これは QMK の [マクロ](ja/feature_macros.md) と [レイヤー](ja/feature_layers.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` - -## 機能オプション :id=feature-options - -これらを使って特定の機能のビルドを有効または無効にします。有効にすればするほどファームウェアが大きくなり、MCU には大きすぎるファームウェアを構築するリスクがあります。 - -* `BOOTMAGIC_ENABLE` - * ブートマジックライトを有効にします -* `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` - * 現在のオプションは、AdafruitBLE、RN42 -* `SPLIT_KEYBOARD` - * 分割キーボード (let's split や bakingpy のキーボードのようなデュアル MCU) のサポートを有効にし、quantum/split_common にある全ての必要なファイルをインクルードします -* `CUSTOM_MATRIX` - * 標準マトリックス走査ルーチンを独自のものに置き換えることができます。 -* `DEBOUNCE_TYPE` - * 標準キーデバウンスルーチンを代替または独自のものに置き換えることができます。 -* `USB_WAIT_FOR_ENUMERATION` - * キーボードが起動する前に、USB 接続が確立されるのをキーボードに待機させます -* `NO_USB_STARTUP_CHECK` - * キーボードの起動後の usb サスペンドチェックを無効にします。通常、キーボードはタスクが実行される前にホストがウェイク アップするのを待ちます。分割キーボードは半分はウェイクアップコールを取得できませんが、マスタにコマンドを送信する必要があるため、役に立ちます。 - -## 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/configurator_step_by_step.md b/docs/ja/configurator_step_by_step.md deleted file mode 100644 index 92be0f16a9..0000000000 --- a/docs/ja/configurator_step_by_step.md +++ /dev/null @@ -1,67 +0,0 @@ -# QMK Configurator: ステップ・バイ・ステップ - - - -このページでは、QMK Configurator でファームウェアを構築する手順を説明します。 - -## ステップ 1: キーボードを選ぶ - -ドロップダウンボックスをクリックして、キーマップを作成するキーボードを選択します。 - -?> **キーボードに複数のバージョンがある場合は、正しいバージョンを選択してください。** - -大事なことなのでもう一度言います。 - -!> **正しいバージョンを選択してください!** - -キーボードが QMK を搭載していると宣伝されていてもリストにない場合は、開発者がまだ作業中か、私たちがまだマージするきっかけがなかった可能性があります。 -アクティブな [プルリクエスト](https://github.com/qmk/qmk_firmware/pulls?q=is%3Aopen+is%3Apr+label%3Akeyboard) がない場合、[qmk_firmware](https://github.com/qmk/qmk_firmware/issues)で報告して、その特定のキーボードのサポートをリクエストします。 -製作者自身の GitHub アカウントにある QMK 搭載キーボードもあります。 -それも再確認してください。 - -## ステップ2: キーボードのレイアウトを選択する - -作成したいと思うキーマップに最も近いレイアウトを選択します。一部のキーボードには、まだ十分なレイアウトや正しいレイアウトが定義されていません。これらは将来サポートされる予定です。 - -## ステップ3: キーマップの名前を決める - -お好みの名前をキーマップにつけます。 - -?> コンパイル時に問題が発生した場合は、もしかすると QMK ファームウェアリポジトリに既に同じ名前が存在しているのかもしれません。名前を変更してみてください。 - -## ステップ4: キーマップを定義する - -キーコードの入力は、3つの方法のいずれかで行います。 - -1. ドラッグ・アンド・ドロップ -2. レイアウト上の空の場所をクリックして、希望するキーコードをクリックします -3. レイアウト上の空の場所をクリックして、キーボードの物理キーを押します - -?> マウスをキーの上に置くと、そのキーコードの機能の短い説明文が出ます。より詳細な説明については以下を見てください: - -* [基本的なキーコードリファレンス](ja/keycodes_basic.md) -* [高度なキーコードリファレンス](ja/feature_advanced_keycodes.md) - -!> 選択したレイアウトが物理的なビルドと一致しない場合は、使用していないキーは空白のままにしておきます。どのキーが使用されているかわからない場合、例えば、バックスペースキーは1つだが `LAYOUT_all` には2つのキーがある場合は、同じキーコードを両方の場所に配置してください。 - -## ステップ5: 後日のためにキーマップを保存する - -キーマップに満足するか、または後で作業したい場合は、`Export Keymap' ボタンを押します。 -これでキーマップがあなたのコンピュータに保存されます。 -その後、`Import Keymap` ボタンを押すことで、この .json ファイルを後で読み込むことができます。 - -!> **注意:** このファイルは、kbfirmware.com またはその他のツールに使用される .json ファイルと同じ形式ではありません。これらのツールにこの .json を使用したり、QMK Configurator でこれらのツールの .json を使用しようとすると、問題が発生します。 - -## ステップ6: ファームウェアをコンパイルする - -緑色の `Compile` ボタンを押します。 - -コンパイルが完了すると、緑色の `Download Firmware` ボタンを押すことができます。 - -## 次のステップ: キーボードに書き込む(フラッシュする) - -[ファームウェアを書きこむ](ja/newbs_flashing.md) を参照してください。 diff --git a/docs/ja/configurator_troubleshooting.md b/docs/ja/configurator_troubleshooting.md deleted file mode 100644 index 5979341c6e..0000000000 --- a/docs/ja/configurator_troubleshooting.md +++ /dev/null @@ -1,32 +0,0 @@ -# Configurator トラブルシューティング - - - -## 私の .json ファイルが動きません - -.json ファイルが QMK Configurator で作ったものの場合、おめでとうございます。バグに遭遇しました。 [qmk_configurator](https://github.com/qmk/qmk_configurator/issues) で報告してください。 - -そうでない場合は、... 他の .json ファイルを使用しないようにという、上に書いた注意書きを見逃してませんか？ - -#### レイアウトに余分なスペースがありますか？どうすればいいですか？ - -もしスペースバーが3つに分かれている場合は、全てスペースバーで埋めるのが最善の方法です。バックスペースや Shift キーについても同じことができます。 - -#### キーコードってなに？ - -以下を見てください。 - -* [基本的なキーコードリファレンス](ja/keycodes_basic.md) -* [高度なキーコードリファレンス](ja/feature_advanced_keycodes.md) - -#### コンパイルできません - -キーマップの他のレイヤーを再確認して、おかしなキーが存在しないことを確認してください。 - -## 問題とバグ - -私たちは利用者の依頼やバグレポートを常に受け入れています。[qmk_configurator](https://github.com/qmk/qmk_configurator/issues) で報告してください。 diff --git a/docs/ja/contributing.md b/docs/ja/contributing.md deleted file mode 100644 index ef1271ad16..0000000000 --- a/docs/ja/contributing.md +++ /dev/null @@ -1,173 +0,0 @@ -# 貢献方法 - - - -👍🎉 まず、これを読み貢献する時間を作ってくれてありがとうございます！🎉👍 - -サードパーティの貢献は、QMK の成長と改善に役立ちます。プルリクエストと貢献プロセスを貢献者とメンテナの両方にとって便利で簡単なものにしたいです。この目的のために、大きな変更をせずにプルリクエストが受け入れられるように貢献者向けのガイドラインをまとめました。 - -* [プロジェクトの概要](#project-overview) -* [コーディング規約](#coding-conventions) -* [一般的なガイドライン](#general-guidelines) -* [行動規範は私にとって何を意味しますか？](#what-does-the-code-of-conduct-mean-for-me) - -## この全てを読みたくはありません！単純に質問があります！ - -QMK について質問したい場合は、[OLKB Subreddit](https://reddit.com/r/olkb) あるいは [Discord](https://discord.gg/Uq7gcHh) ですることができます。 - -以下の事を覚えておいてください: - -* 誰かがあなたの質問に答えるのに数時間掛かるかもしれません。しばらくお待ちください！ -* QMK に関わる全ての人が彼らの時間とエネルギーを提供しています。QMK に関する作業や質問への回答に対する報酬はありません。 -* できるだけ簡単に答えられるように質問してみてください。その方法が分からない場合は、以下に幾つかの良いガイドがあります: - * https://opensource.com/life/16/10/how-ask-technical-questions - * http://www.catb.org/esr/faqs/smart-questions.html - -# プロジェクトの概要 :id=project-overview - -QMK は主に C で書かれており、特定の機能と部品は C++ で書かれています。QMK は、キーボードの中の組み込みプロセッサ、特に AVR ([LUFA](https://www.fourwalledcubicle.com/LUFA.php)) と ARM ([ChibiOS](https://www.chibios.org)) を対象にしています。すでに Arduino プログラミングに精通している場合は、多くの概念と制限がおなじみのものです。QMK に貢献するには Arduino を使用した経験は必要ありません。 - - - -# どこで助けを得られますか？ - -助けが必要であれば、[issue を開く](https://github.com/qmk/qmk_firmware/issues) か [Discord で会話する](https://discord.gg/Uq7gcHh)ことができます。 - -# どうやって貢献することができますか？ - -以前にオープンソースに貢献したことはありませんか？ QMK で貢献がどのように機能するかが疑問ですか？ ここに簡単な説明があります！ - -0. [GitHub](https://github.com) アカウントにサインアップします。 -1. 貢献するためのキーマップをまとめるか、解決に興味がある[問題を見つける](https://github.com/qmk/qmk_firmware/issues)、あるいは追加したい[機能](https://github.com/qmk/qmk_firmware/issues?q=is%3Aopen+is%3Aissue+label%3Afeature)を見つけます。 -2. 問題に関連付けられているリポジトリをあなたの GitHub アカウントにフォークします。これは、`GitHub上のあなたのユーザー名/qmk_firmware` の下にリポジトリのコピーを持つことを意味します。 -3. `git clone https://github.com/GitHub上のあなたのユーザー名/repository-name.git` を使ってローカルマシンにリポジトリをクローンします。 -4. 新しい機能に取り組んでいる場合は、issue を開きこれから行う作業について話し合うことを検討してください。 -5. `git checkout -b branch-name-here` を使って修正用の新しいブランチを作成します。 -6. 解決しようとしている問題、あるいは追加したい機能について適切な変更を加えます。 -7. `git add insert-paths-of-changed-files-here` を使って変更されたファイルの内容を git がプロジェクトの状態を管理するために使用する "snapshot"、インデックスとしても知られている、に追加します。 -8. `git commit -m "Insert a short message of the changes made here"` を使って、説明的なメッセージとともにインデックスの内容を保存します。 -9. `git push origin branch-name-here` を使って GitHub 上のリポジトリに変更をプッシュします。 -10. プルリクエストを [QMK Firmware](https://github.com/qmk/qmk_firmware/pull/new/master) にサブミットします。 -11. 行われた変更の簡単な説明と、変更に関する問題またはバグ番号を使って、プルリクエストにタイトルを付けます。例えば、issue に "Added more log outputting to resolve #4352" のようなタイトルをつけることができます。 -12. プルリクエストの説明では、行った変更、行ったプルリクエストに存在すると思われる問題、およびメンテナに対する質問を説明します。プルリクエストが完ぺきではない場合(プルリクエストが無い場合)でも問題ありません。レビュワーが問題の修正と改善を手伝います。 -13. プルリクエストがメンテナによってレビューされるのを待ちます。 -14. レビューをしているメンテナが変更を推奨する場合は、プルリクエストに変更を加えます。 -15. プルリクエストがマージされた後で成功を祝います！ - -# コーディング規約 :id=coding-conventions - -私たちのスタイルのほとんどは簡単に理解できます。C あるいは Python のいずれかに精通している場合は、ローカルスタイルにそれほど問題はないはずです。 - -* [コーディング規約 - C](ja/coding_conventions_c.md) -* [コーディング規約 - Python](ja/coding_conventions_python.md) - -# 一般的なガイドライン :id=general-guidelines - -QMK には幾つかの異なるタイプの変更があり、それぞれ異なるレベルの厳密さが必要です。どのような種類の変更を行っても、次のガイドラインに留意してください。 - -* PR を論理単位に分割します。例えば、2つの個別の機能をカバーする1つの PR を送信するのではなく、代わりに機能ごとに個別の PR をサブミットします。 -* コミットする前に、`git diff --check` を使って不要な空白を確認します。 -* コードの変更が実際にコンパイルされることを確認してください。 - * キーマップ: `make keyboard:your_new_keymap` がエラーを返さないことを確認してください。 - * キーボード: `make keyboard:all` がエラーを返さないことを確認してください。 - * コア: `make all` がエラーを返さないことを確認してください。 -* コミットメッセージがそれ自体で理解できることを確認してください。最初の行に短い説明(70文字以内)を入れ、2行目は空にし、3行目以降では必要に応じてコミットを詳細に説明する必要があります。例: - -``` -kerpleplork の fronzlebop を調整します - -kerpleplork はエラーコード 23 で連続的に失敗していました。根本的な原因は fronzlebop 設定で、これにより kerpleplork は N 回の繰り返しごとにアクティブになります。 - -私が使用できるデバイスの限られた実験では、kerpleplork の混乱を避けるために 7 は十分高い値であることを示していますが、念のため ARM デバイスを持つ人たちからフィードバックを得たいです。 -``` - -!> **重要:** デフォルト以外のキーマップ、ユーザスペースおよびレイアウトのようなユーザコードへのバグ修正あるいは改善に貢献したい場合は、PR にコードの元の提出者にタグをつけてください。Git と GitHub のスキルレベルに関係なく、多くのユーザは知らないうちにコードが変更されることに混乱したりイライラしたりするかもしれません。 - -## ドキュメント - -ドキュメントは QMK への貢献を始める最も簡単な方法の1つです。ドキュメントが間違っているか不完全な場所を見つけ、これらを修正するのは簡単です！私たちもドキュメントを編集する人を非常に必要としています。編集するスキルがあるが、どこにどのように飛び乗ればいいのか分からない場合は、[助けをもとめて](#where-can-i-go-for-help)ください！ - -全てのドキュメントは `qmk_firmware/docs` ディレクトリの中にあります。あるいは web ベースのワークフローを使いたい場合は、https://docs.qmk.fm/ の各ページの下部にある "Edit this page" リンクをクリックすることができます。 - -ドキュメントの中にコードの例を提供する場合は、ドキュメント内の他の場所で使用されている命名規則を順守してください。例えば、一貫性を保つために、`my_layers` あるいは `my_keycodes` として列挙型を標準化します: - -```c -enum my_layers { - _FIRST_LAYER, - _SECOND_LAYER -}; - -enum my_keycodes { - FIRST_LAYER = SAFE_RANGE, - SECOND_LAYER -}; -``` - -### ドキュメントのプレビュー :id=previewing-the-documentation - -開発環境をセットアップした場合は、プルリクエストを開く前に以下のコマンドを `qmk_firmware/` フォルダから実行することで、あなたの変更をプレビューすることができます: - - qmk docs - -または、Python 3 のみがインストールされている場合: - - python3 -m http.server 8936 --directory docs - -その後、ウェブブラウザで、`http://localhost:8936/` を表示します。 - -## キーマップ - -ほとんどの初めての QMK 貢献者は、個人のキーマップから始めます。キーマップの標準はかなりカジュアルなものにしようとしています(キーマップは結局のところ作成者の性格を反映しています)が、他の人があなたのキーマップを簡単に見つけて学ぶことができるように、これらのガイドラインに従うようにお願いします。 - -* [テンプレート](ja/documentation_templates.md) を使って `readme.md` を書きます。 -* 全てのキーマップの PR は squash されるため、コミットがどのように squash されるかを気にする場合は、自分で行う必要があります。 -* キーマップの PR に機能をまとめないでください。最初に機能をサブミットし、次にキーマップのための2つ目の PR をサブミットします。 -* `Makefile` をキーマップフォルダに含めないでください(もう使われていません)。 -* ファイルヘッダの著作権を更新します (`%YOUR_NAME%` を探します) - -## キーボード - -キーボードは QMK の存在理由です。一部のキーボードはコミュニティによって管理されていますが、他のキーボードはそれぞれのキーボードを作成する責任者によって管理されています。`readme.md` を見るとそのキーボードを管理しているのが誰かが分かります。特定のキーボードに関する質問がある場合、[Issue を開いて](https://github.com/qmk/qmk_firmware/issues)質問にメンテナをタグ付けしてください。(訳注: タグ付け は [メンションする](https://help.github.com/ja/github/writing-on-github/basic-writing-and-formatting-syntax#mentioning-people-and-teams) という意味です。) - -また以下のガイドラインに従うことをお願いします: - -* [テンプレート](ja/documentation_templates.md) を使って `readme.md` を書きます。 -* コミットの数を適切に保ってください。そうでなければあなたの PR を squash します。 -* コア機能を新しいキーボードにまとめないでください。最初に機能をサブミットし、次にキーボード用に別の PR をサブミットしてください。 -* `.c`/`.h` ファイルにすぐ上の親フォルダに従って名前を付けます。例えば、`/keyboards///.[ch]` -* `Makefile` をキーボードフォルダに含めないでください(もう使われていません) -* ファイルヘッダの著作権を更新します (`%YOUR_NAME%` を探します) - -## Quantum/TMK コア - -新しい機能をビルドするために多くの作業を行う前に、最適な方法で実装していることを確認する必要があります。[QMK の理解](ja/understanding_qmk.md)を読むことで、QMK の基本的な理解を得ることができます。これはあなたを QMK のプログラムフローのツアーに連れて行きます。ここから、あなたのアイデアを実装するための最良の方法の感覚をつかむために、私たちと話す必要があります。これを行うには主に2つの方法があります: - -* [Discord でのチャット](https://discord.gg/Uq7gcHh) -* [Issue を開く](https://github.com/qmk/qmk_firmware/issues/new) - -機能とバグ修正の PR は全てのキーボードに影響します。また、私たちは QMK の再編も進めています。このため、実装が行われる前に特に重要な変更について議論することが特に重要です。最初に私たちと話をせずに PR を開いた場合、あなたの選択が私たちの計画した方向とうまく合わない場合は幾つかの大きな再作業を行う覚悟をしてください。 - -機能やバグの修正に取り組む時に留意すべき幾つかの事があります。 - -* **デフォルトで無効** - QMK がサポートするほとんどのチップでメモリがかなり制限されており、現在のキーマップが壊れていないことが重要です。ですので、あなたの機能をオフにするのではなく**オン**にするようにしてください。デフォルトでオンにすべき場合、あるいはコードのサイズを小さくする必要がある場合は、相談してください。 -* **サブミットする前にローカルでコンパイル** - これが明白であることを願っていますが、コンパイルする必要があります。プルリクエストを作成する前に、変更した内容がコンパイルできるかどうかを常に確認する必要があります。 -* **リビジョンと異なるチップベースを考慮** - 僅かに異なる設定、さらには異なるチップベースを可能にするリビジョンを持つキーボードが幾つかあります。ARM および AVR でサポートされる機能を作成する、あるいは動作しないプラットフォームでは自動的に無効化するようにしてください。 -* **機能の説明** - 新しいファイルあるいは既存のファイルの一部として、`docs/` の中に文章化します。文章化しないと、他の人はあなたの苦労から利益を得ることができません。 - -また以下のガイドラインに従うことをお願いします: - -* コミットの数を適切に保ってください。そうでなければあなたの PR を squash します。 -* キーボードあるいはキーマップをコアの変更にまとめないでください。コアの変更を最初にサブミットしてください。 -* 機能のための[ユニット テスト](ja/unit_testing.md)を書いてください。 -* 編集しているファイルのスタイルに従ってください。スタイルが明確でないか、スタイルが混在している場合は、上記の[コーディング規約](#coding-conventions)に準拠する必要があります。 - -## リファクタリング - -QMK で物事がどのようにレイアウトされるかについて明確なビジョンを維持するために、私たちはリファクタリングを詳細に計画し、変更をする協力者がいます。リファクタリングのアイデアあるいは提案がある場合は、[issue を開いてください](https://github.com/qmk/qmk_firmware/issues)。QMK を改善する方法についてお話ししたいと思います。 - -# 行動規範は私にとって何を意味しますか？ :id=what-does-the-code-of-conduct-mean-for-me - -私たちの[行動規範](https://github.com/qmk/qmk_firmware/blob/master/CODE_OF_CONDUCT.md)は、身元に関係なくあなたがプロジェクトの全員を敬意と礼儀を持って扱う責任があることを意味します。あなたが行動規範に記載されている不適切な行動やコメントの被害者である場合は、私たちはあなたのためにここにおり、私たちのコードに従って虐待者が適切に懲戒されるように最善を尽くします。 diff --git a/docs/ja/custom_matrix.md b/docs/ja/custom_matrix.md deleted file mode 100644 index 194960d77c..0000000000 --- a/docs/ja/custom_matrix.md +++ /dev/null @@ -1,114 +0,0 @@ -# カスタムマトリックス - - - -QMKは、デフォルトのマトリックススキャンルーチンを独自のコードで部分的に入れ替えたり全部入れ替えたりしたりするメカニズムを提供します。 - -この機能を使用する理由は次のとおりです: - -* キーボードのスイッチと MCU ピンの間に追加のハードウェアがある場合 - * I/O マルチプレクサ - * ラインデコーダー -* 一般的ではないキースイッチマトリックス - * `COL2ROW` と `ROW2COL` の同時使用 - -## 前提条件 - -カスタムマトリックスの実装には、通常、追加のソースファイルのコンパイルが含まれます。 -一貫性を保つために、このソースファイルのファイル名は `matrix.c` とすることをお勧めします。 - -あなたのキーボードディレクトリに新しいファイルを追加します: -```text -keyboards//matrix.c -``` - -そして、新しいファイルのコンパイルを指定するため、以下を `rules.mk` に追加します -```make -SRC += matrix.c -``` - -## マトリックスコードの部分置き換え :id=lite - -カスタムマトリックスを実装する際、定型コードを書かなくてすむように、さまざまなスキャン関数のデフォルト実装を提供しています。 - -設定するには、以下を `rules.mk` に追加します： -```make -CUSTOM_MATRIX = lite -``` - -そして、キーボードディレクトリの `matrix.c` ファイルに次の関数を実装します。 - -```c -void matrix_init_custom(void) { - // TODO: ここでハードウェアの初期化をする -} - -bool matrix_scan_custom(matrix_row_t current_matrix[]) { - bool matrix_has_changed = false; - - // TODO: ここで、マトリックススキャンを行なう - - return matrix_has_changed; -} -``` - -## マトリックスコードの全面置き換え - -スキャンルーチンをさらに変更する必要がある場合は、完全なスキャンルーチンを実装することを選択できます。 - -設定するには、以下を `rules.mk` に追加します： -```make -CUSTOM_MATRIX = yes -``` - -そして、キーボードディレクトリの `matrix.c` ファイルに次の関数を実装します。 - -```c -matrix_row_t matrix_get_row(uint8_t row) { - // TODO: 要求された行データを返します -} - -void matrix_print(void) { - // TODO: printf() を使って現在のマトリックスの状態をコンソールにダンプします -} - -void matrix_init(void) { - // TODO: ここでハードウェアとグローバルマトリックスの状態を初期化します - - // ハードウェアによるデバウンスがない場合 - 設定されているデバウンスルーチンを初期化します - debounce_init(MATRIX_ROWS); - - // 正しいキーボード動作のためにこれを呼び出す*必要があります* - matrix_init_kb(); -} - -uint8_t matrix_scan(void) { - bool changed = false; - - // TODO: ここにマトリックススキャンルーチンを追加します - - // ハードウェアによるデバウンスがない場合 - 設定されているデバウンスルーチンを使用します - changed = debounce(raw_matrix, matrix, MATRIX_ROWS, changed); - - // 正しいキーボード動作のためにこれを呼び出す*必要があります* - matrix_scan_kb(); - - return changed; -} -``` - -また、次のコールバックのデフォルトも提供します。 - -```c -__attribute__((weak)) void matrix_init_kb(void) { matrix_init_user(); } - -__attribute__((weak)) void matrix_scan_kb(void) { matrix_scan_user(); } - -__attribute__((weak)) void matrix_init_user(void) {} - -__attribute__((weak)) void matrix_scan_user(void) {} -``` diff --git a/docs/ja/custom_quantum_functions.md b/docs/ja/custom_quantum_functions.md deleted file mode 100644 index bd3f15a5fd..0000000000 --- a/docs/ja/custom_quantum_functions.md +++ /dev/null @@ -1,403 +0,0 @@ -# キーボードの挙動をカスタマイズする方法 - - - -多くの人にとって、カスタムキーボードはボタンの押下をコンピュータに送信するだけではありません。単純なボタンの押下やマクロよりも複雑なことを実行できるようにしたいでしょう。QMK にはコードを挿入したり、機能を上書きしたり、様々な状況でキーボードの挙動をカスタマイズできるフックがあります。 - -このページでは、QMK に関する特別な知識は想定していませんが、[QMK の理解](ja/understanding_qmk.md)を読むとより根本的なレベルで何が起きているかを理解するのに役立ちます。 - -## コア、キーボード、キーマップ階層 :id=a-word-on-core-vs-keyboards-vs-keymap - -私たちは QMK を階層として構造化しました: - -* コア (`_quantum`) - * キーボード/リビジョン (`_kb`) - * キーマップ (`_user`) - -以下で説明される各関数は `_kb()` サフィックスあるいは `_user()` サフィックスを使って定義することができます。`_kb()` サフィックスはキーボード/リビジョンレベルで使うことを意図しており、一方で `_user()` サフィックスはキーマップレベルで使われるべきです。 - -キーボード/リビジョンレベルで関数を定義する場合、`_kb()` は他の何かを実行する前に `_user()` を呼び出すよう実装することが重要です。そうでなければ、キーマップレベル関数は呼ばれないでしょう。 - -# カスタムキーコード - -最も一般的なタスクは、既存のキーコードの挙動を変更するか、新しいキーコードを作成することです。コードの観点からは、それぞれの仕組みは非常に似ています。 - -## 新しいキーコードの定義 - -独自のカスタムキーコードを作成する最初のステップは、それらを列挙することです。これは、カスタムキーコードに名前を付け、そのキーコードにユニークな番号を割り当てることの両方を意味します。QMK は、カスタムキーコードを固定範囲の番号に制限するのではなく、`SAFE_RANGE` マクロを提供します。カスタムキーコードを列挙する時に `SAFE_RANGE` を使うと、ユニークな番号を取得することが保証されます。 - - -これは2つのキーコードを列挙する例です。このブロックを `keymap.c` に追加した後で、キーマップの中で `FOO` と `BAR` を使うことができます。 - -```c -enum my_keycodes { - FOO = SAFE_RANGE, - BAR -}; -``` - -## 任意のキーコードの挙動のプログラミング :id=programming-the-behavior-of-any-keycode - -既存のキーの挙動を上書きしたい場合、あるいは新しいキーについて挙動を定義する場合、`process_record_kb()` および `process_record_user()` 関数を使うべきです。これらは実際のキーイベントが処理される前のキー処理中に QMK によって呼び出されます。これらの関数が `true` を返す場合、QMK はキーコードを通常通りに処理します。これは、キーを置き換えるのではなく、キーの機能を拡張するのに便利です。これらの関数が `false` を返す場合、QMK は通常のキー処理をスキップし、必要なキーのアップまたはダウンイベントを送信するのかはユーザ次第です。 - -これらの関数はキーが押されるか放されるたびに呼び出されます。 - -### `process_record_user()` の実装例 - -この例は2つの事を行います。`FOO` と呼ばれるカスタムキーコードの挙動を定義し、Enter キーが押されるたびに音を再生します。 - -```c -bool process_record_user(uint16_t keycode, keyrecord_t *record) { - switch (keycode) { - case FOO: - if (record->event.pressed) { - // 押された時に何かをします - } else { - // 放された時に何かをします - } - return false; // このキーの以降の処理をスキップします - case KC_ENTER: - // enter が押された時に音を再生します - if (record->event.pressed) { - PLAY_SONG(tone_qwerty); - } - return true; // QMK に enter のプレスまたはリリースイベントを送信させます - default: - return true; // 他の全てのキーコードを通常通りに処理します - } -} -``` - -### `process_record_*` 関数のドキュメント - -* キーボード/リビジョン: `bool process_record_kb(uint16_t keycode, keyrecord_t *record)` -* キーマップ: `bool process_record_user(uint16_t keycode, keyrecord_t *record)` - -`keycode` 引数はキーマップで定義されているものです。例えば `MO(1)`、`KC_L` など。これらのイベントを処理するには `switch...case` ブロックを使うべきです。 - -`record` 引数は実際のプレスに関する情報を含みます: - -```c -keyrecord_t record { - keyevent_t event { - keypos_t key { - uint8_t col - uint8_t row - } - bool pressed - uint16_t time - } -} -``` - -# キーボードの初期化コード - -キーボードの初期化プロセスには幾つかのステップがあります。何をしたいかによって、どの関数を使うべきかに影響します。 - -3つの主な初期化関数があり、呼び出される順番にリストされています。 - -* `keyboard_pre_init_*` - ほとんどのものが開始される前に起こります。非常に早くに実行したいハードウェアのセットアップに適しています。 -* `matrix_init_*` - ファームウェアのスタートアッププロセスの途中で起こります。ハードウェアは初期化されますが、機能はまだ初期化されていない場合があります。 -* `keyboard_post_init_*` - ファームウェアのスタートアッププロセスの最後に起こります。これはほとんどの場合、 "カスタマイズ"コードを配置する場所です。 - -!> ほとんどの人にとって、`keyboard_post_init_user` が呼び出したいものです。例えば、ここで RGB アンダーグローのセットアップを行います。 - -## キーボードの事前初期化コード - -これは USB さえ起動する前の、起動中の非常に早い段階で実行されます。 - -この直後にマトリックスが初期化されます。 - -これは主にハードウェア向きの初期化のためであるため、ほとんどのユーザは使うべきではありません。 - -ただし、初期化が必要なハードウェアがある場合には、これが最適な場所です (LED ピンの初期化など)。 - -### `keyboard_pre_init_user()` の実装例 - -この例は、キーボードレベルで、LED ピンとして B0、B1、B2、B3 および B4 をセットアップします。 - -```c -void keyboard_pre_init_user(void) { - // キーボードの事前初期コードを呼び出します。 - - // LED ピンを出力として設定します - setPinOutput(B0); - setPinOutput(B1); - setPinOutput(B2); - setPinOutput(B3); - setPinOutput(B4); -} -``` - -### `keyboard_pre_init_*` 関数のドキュメント :id=keyboard_pre_init_-function-documentation - -* キーボード/リビジョン: `void keyboard_pre_init_kb(void)` -* キーマップ: `void keyboard_pre_init_user(void)` - -## マトリックスの初期化コード - -これは、マトリックスが初期化され、ハードウェアの一部がセットアップされた後で、ただし機能の多くが初期化される前に、呼び出されます。 - -他の場所で必要になるかもしれないものをセットアップするのに役立ちますが、ハードウェアに関連するものではなく、開始場所に依存するものでもありません。 - - -### `matrix_init_*` 関数のドキュメント - -* キーボード/リビジョン: `void matrix_init_kb(void)` -* キーマップ: `void matrix_init_user(void)` - - -## キーボードの事後初期化コード - -キーボードの初期化プロセスの極めて最後のタスクとして実行されます。この時点で初期化される必要があるような、特定の機能を変更したい場合に便利です。 - - -### `keyboard_post_init_user()` の実装例 - -この例は、他の全てのものが初期化された後で実行され、rgb アンダーグローの設定をセットアップします。 - -```c -void keyboard_post_init_user(void) { - // post init コードを呼びます - rgblight_enable_noeeprom(); // 設定を保存せずに Rgb を有効にします - rgblight_sethsv_noeeprom(180, 255, 255); // 保存せずに色を青緑/シアンに設定します - rgblight_mode_noeeprom(RGBLIGHT_MODE_BREATHING + 3); // 保存せずにモードを高速なブリージングに設定します -} -``` - -### `keyboard_post_init_*` 関数のドキュメント - -* キーボード/リビジョン: `void keyboard_post_init_kb(void)` -* キーマップ: `void keyboard_post_init_user(void)` - -# マトリックススキャンコード :id=matrix-scanning-code - -可能であれば常に `process_record_*()` を使ってキーボードをカスタマイズし、その方法でイベントをフックし、コードがキーボードのパフォーマンスに悪影響を与えないようにします。ただし、まれにマトリックススキャンにフックする必要があります。これらの関数は1秒あたり少なくとも10回は呼び出されるため、これらの関数のコードのパフォーマンスに非常に注意してください。 - -### `matrix_scan_*` の実装例 - -この例は意図的に省略されています。このようなパフォーマンスに敏感な領域にフックする前に、例を使わずにこれを書くために、QMK 内部について十分理解する必要があります。助けが必要であれば、[issue を開く](https://github.com/qmk/qmk_firmware/issues/new) か [Discord で会話](https://discord.gg/Uq7gcHh)してください。 - -### `matrix_scan_*` 関数のドキュメント - -* キーボード/リビジョン: `void matrix_scan_kb(void)` -* キーマップ: `void matrix_scan_user(void)` - -この関数はマトリックススキャンのたびに呼び出されます。これは基本的に MCU が処理できる頻度です。大量に実行されるため、ここに何を置くかについては注意してください。 - -カスタムマトリックススキャンコードが必要な場合は、この関数を使う必要があります。また、カスタムステータス出力 (LED あるいはディスプレイなど)や、ユーザが入力していない場合でも定期的にトリガーするその他の機能のために使うことができます。 - -# キーボードハウスキーピング :id=keyboard-housekeeping - -* キーボード/リビジョン: `void housekeeping_task_kb(void)` -* キーマップ: `void housekeeping_task_user(void)` - -この関数は、全ての QMK 処理の最後に、次の繰り返しを開始する前に呼び出されます。`housekeeping_task_*` の関数が呼び出された時点で、QMK が最後のマトリックススキャンを処理したと、安全に見なすことができます -- レイヤーの状態が更新され、USB レポートが送信され、LED が更新され、表示が描画されています。 - -`matrix_scan_*` と同様に、これらは MCU が処理できる頻度で呼び出されます。キーボードの応答性を維持するために、これらの関数の呼び出し中にできるだけ何もしないことをお勧めします。実際に何か特別なものを実装する必要がある場合に動作を停止させる可能性があります。 - -# キーボードアイドリング/ウェイクコード - -キーボードがサポートしている場合、多くの機能を停止することで"アイドル"にすることができます。これの良い例は、RGB ライトあるいはバックライトです。これにより、電力消費を節約できるか、キーボードの動作が改善されるかもしれません。 - -これは2つの関数によって制御されます: `suspend_power_down_*` および `suspend_wakeup_init_*`。これらはシステムキーボードがアイドルになった時と、起動した時のそれぞれで呼ばれます。 - - -### suspend_power_down_user() と suspend_wakeup_init_user() の実装例 - - -```c -void suspend_power_down_user(void) { - // code will run multiple times while keyboard is suspended -} - -void suspend_wakeup_init_user(void) { - // code will run on keyboard wakeup -} -``` - -### キーボードサスペンド/ウェイク関数のドキュメント - -* キーボード/リビジョン : `void suspend_power_down_kb(void)` および `void suspend_wakeup_init_user(void)` -* キーマップ: `void suspend_power_down_kb(void)` および `void suspend_wakeup_init_user(void)` - -# レイヤー切り替えコード :id=layer-change-code - -これはレイヤーが切り替えられるたびにコードを実行します。レイヤー表示あるいはカスタムレイヤー処理に役立ちます。 - -### `layer_state_set_*` の実装例 - -この例は、レイヤーに基づいて [RGB アンダーグロー](ja/feature_rgblight.md)を設定する方法を示していて、Planck を例として使っています。 - -```c -layer_state_t layer_state_set_user(layer_state_t state) { - switch (get_highest_layer(state)) { - case _RAISE: - rgblight_setrgb (0x00, 0x00, 0xFF); - break; - case _LOWER: - rgblight_setrgb (0xFF, 0x00, 0x00); - break; - case _PLOVER: - rgblight_setrgb (0x00, 0xFF, 0x00); - break; - case _ADJUST: - rgblight_setrgb (0x7A, 0x00, 0xFF); - break; - default: // 他の全てのレイヤーあるいはデフォルトのレイヤー - rgblight_setrgb (0x00, 0xFF, 0xFF); - break; - } - return state; -} -``` - -特定のレイヤーの状態を確認するには、`IS_LAYER_ON_STATE(state, layer)` と `IS_LAYER_OFF_STATE(state, layer)` マクロを使います。 - -`layer_state_set_*` 関数の外では、グローバルなレイヤー状態を確認するために `IS_LAYER_ON(layer)` と `IS_LAYER_OFF(layer)` マクロを使えます。 - -### `layer_state_set_*` 関数のドキュメント - -* キーボード/リビジョン: `layer_state_t layer_state_set_kb(layer_state_t state)` -* キーマップ: `layer_state_t layer_state_set_user(layer_state_t state)` - - -[キーマップの概要](ja/keymap.md#keymap-layer-status)で説明されるように、`state` はアクティブなレイヤーのビットマスクです。 - - -# 永続的な設定 (EEPROM) - -これによりキーボードのための永続的な設定を設定することができます。これらの設定はコントローラの EEPROM に保存され、電源が落ちた後であっても保持されます。設定は `eeconfig_read_kb` および `eeconfig_read_user` を使って読み取ることができ、`eeconfig_update_kb` および `eeconfig_update_user` を使って書きこむことができます。これは切り替え可能な機能 (rgb レイヤーの表示の切り替えなど)に役立ちます。さらに、`eeconfig_init_kb` および `eeconfig_init_user` を使って EEPROM のデフォルト値を設定できます。 - -ここでの複雑な部分は、EEPROM を介してデータを保存およびアクセスできる方法がたくさんあり、これを行うための"正しい"方法が無いということです。ただし、各関数には DWORD (4 バイト)しかありません。 - -EEPROM の書き込み回数には制限があることに注意してください。これは非常に高い値ですが、EEPROM に書き込むのはこれだけではなく、もし頻繁に書き込むと、MCU の寿命を大幅に短くする可能性があります。 - -* この例を理解していない場合は、この機能はかなり複雑なため、この機能を使うことを避けても構いません。 - -### 実装例 - -これは、設定を追加し、読み書きする例です。この例では、ユーザキーマップを使っています。これは複雑な機能で、多くのことが行われています。実際、動作のために上記の多くの関数を使います！ - - -keymap.c ファイルの中で、先頭にこれを追加します: -```c -typedef union { - uint32_t raw; - struct { - bool rgb_layer_change :1; - }; -} user_config_t; - -user_config_t user_config; -``` - -これは、設定をメモリ内に保存し、EEPROM に書き込むことができる32ビット構造体をセットアップします。これを使うと、この構造体に変数が定義されるため、変数を定義する必要が無くなります。`bool` (boolean) の値は1ビットを使い、`uint8_t` は8ビットを使い、`uint16_t` は16ビットを使うことに注意してください。組み合わせて使うことができますが、順番の変更は読み書きされる値が変更されるため、問題が発生するかもしれません。 - -`layer_state_set_*` 関数のために `rgb_layer_change` を使い、全てを設定するために `keyboard_post_init_user` および `process_record_user` を使います。 - -ここで、上の `keyboard_post_init_user` コードを使って、作成したばかりの構造体を設定するために `eeconfig_read_user()` を追加します。そして、この構造体をすぐに使ってキーマップの機能を制御することができます。それは以下のようになります: -```c -void keyboard_post_init_user(void) { - // キーマップレベルのマトリックスの初期化処理を呼びます - - // EEPROM からユーザ設定を読み込みます - user_config.raw = eeconfig_read_user(); - - // 有効な場合はデフォルトレイヤーを設定します - if (user_config.rgb_layer_change) { - rgblight_enable_noeeprom(); - rgblight_sethsv_noeeprom_cyan(); - rgblight_mode_noeeprom(1); - } -} -``` -上記の関数は読み取ったばかりの EEPROM 設定を使い、デフォルトのレイヤーの RGB 色を設定します。その「生の」値は、上で作成した「共用体」に基づいて使用可能な構造に変換されます。 - -```c -layer_state_t layer_state_set_user(layer_state_t state) { - switch (get_highest_layer(state)) { - case _RAISE: - if (user_config.rgb_layer_change) { rgblight_sethsv_noeeprom_magenta(); rgblight_mode_noeeprom(1); } - break; - case _LOWER: - if (user_config.rgb_layer_change) { rgblight_sethsv_noeeprom_red(); rgblight_mode_noeeprom(1); } - break; - case _PLOVER: - if (user_config.rgb_layer_change) { rgblight_sethsv_noeeprom_green(); rgblight_mode_noeeprom(1); } - break; - case _ADJUST: - if (user_config.rgb_layer_change) { rgblight_sethsv_noeeprom_white(); rgblight_mode_noeeprom(1); } - break; - default: // 他の全てのレイヤーあるいはデフォルトのレイヤー - if (user_config.rgb_layer_change) { rgblight_sethsv_noeeprom_cyan(); rgblight_mode_noeeprom(1); } - break; - } - return state; -} -``` -これにより、値が有効になっていた場合のみ、RGB アンダーグローが変更されます。この値を設定するために、`RGB_LYR` と呼ばれる `process_record_user` 用の新しいキーコードを作成します。さらに、通常の RGB コードを使う場合、上記の例を使ってオフになることを確認します。以下のようになります: -```c -bool process_record_user(uint16_t keycode, keyrecord_t *record) { - switch (keycode) { - case FOO: - if (record->event.pressed) { - // 押された時に何かをします - } else { - // 放された時に何かをします - } - return false; // このキーの以降の処理をスキップします - case KC_ENTER: - // enter が押された時に音を再生します - if (record->event.pressed) { - PLAY_SONG(tone_qwerty); - } - return true; // QMK に enter のプレスまたはリリースイベントを送信させます - case RGB_LYR: // これにより、アンダーグローをレイヤー表示として、あるいは通常通りに使うことができます。 - if (record->event.pressed) { - user_config.rgb_layer_change ^= 1; // 状態を切り替えます - eeconfig_update_user(user_config.raw); // 新しい状態を EEPROM に書き込みます - if (user_config.rgb_layer_change) { // レイヤーの状態表示が有効な場合 - layer_state_set(layer_state); // すぐにレイヤーの色を更新します - } - } - return false; - case RGB_MODE_FORWARD ... RGB_MODE_GRADIENT: // 任意の RGB コード に対して(quantum_keycodes.h を見てください。400行目参照) - if (record->event.pressed) { // これはレイヤー表示を無効にします。これを変更する場合は、無効にしたいだろうため。 - if (user_config.rgb_layer_change) { // 有効な場合のみ - user_config.rgb_layer_change = false; // 無効にします - eeconfig_update_user(user_config.raw); // 設定を EEPROM に書き込みます - } - } - return true; break; - default: - return true; // 他の全てのキーコードを通常通りに処理します - } -} -``` -最後に、`eeconfig_init_user` 関数を追加して、EEPROM がリセットされた時にデフォルト値、さらにはカスタムアクションを指定できるようにします。EEPROM を強制的にリセットするには、`EEP_RST` キーコードあるいは[ブートマジック](ja/feature_bootmagic.md)機能を使います。例えば、デフォルトで rgb レイヤー表示を設定し、デフォルト値を保存したい場合。 - -```c -void eeconfig_init_user(void) { // EEPROM がリセットされます！ - user_config.raw = 0; - user_config.rgb_layer_change = true; // デフォルトでこれを有効にします - eeconfig_update_user(user_config.raw); // デフォルト値を EEPROM に書き込みます - - // これらの値も EEPROM に書き込むためには、noeeprom 以外のバージョンを使います - rgblight_enable(); // デフォルトで RGB を有効にします - rgblight_sethsv_cyan(); // デフォルトでシアンに設定します - rgblight_mode(1); // デフォルトでソリッドに設定します -} -``` - -これで完了です。RGB レイヤー表示は必要な場合にのみ機能します。キーボードを取り外した後でも保存されます。RGB コードのいずれかを使うと、レイヤー表示が無効になり、設定したモードと色がそのままになります。 - -### 'EECONFIG' 関数のドキュメント - -* キーボード/リビジョン: `void eeconfig_init_kb(void)`、`uint32_t eeconfig_read_kb(void)` および `void eeconfig_update_kb(uint32_t val)` -* キーマップ: `void eeconfig_init_user(void)`、`uint32_t eeconfig_read_user(void)` および `void eeconfig_update_user(uint32_t val)` - -`val` は EEPROM に書き込みたいデータの値です。`eeconfig_read_*` 関数は EEPROM から32ビット(DWORD) 値を返します。 diff --git a/docs/ja/data_driven_config.md b/docs/ja/data_driven_config.md deleted file mode 100644 index 6296173b66..0000000000 --- a/docs/ja/data_driven_config.md +++ /dev/null @@ -1,123 +0,0 @@ -# データ駆動型コンフィギュレーション - - - -このページでは、QMK のデータ駆動型 JSON コンフィギュレーションシステムがどのように動作するかを説明します。これは、QMK 自体に取り組みたい開発者を対象としています。 - -## ヒストリー - -これまで、QMK は、`rules.mk` と `config.h` の2つのメカニズムを組み合わせてコンフィギュレーションされてきました。 -この方法は、QMK がほんの一握りのキーボードをサポートしていたときは上手く機能していましたが、今では、サポートするキーボードは1500近くまで成長しました。 -`keyboards` の下だけで6000個の設定ファイルがあることが推定されます。 -これらのファイルの自由形式の性質と、重複を避けるために人々が使用してきたユニークなパターンが継続的なメンテナンスを困難にしており、また、多くのキーボードが時代遅れで時には理解が難しいパターンに従っています。 - -また、CLI に慣れていない人に QMK のパワーを提供することにも取り組んでおり、VIA などの他のプロジェクトでは、プログラムをインストールするのと同じくらい簡単に QMK を使用できるように取り組んでいます。 -これらのツールには、ユーザーが QMK を最大限に活用できるように、キーボードのレイアウト方法や使用可能なピンと機能に関する情報が必要です。 -その第一歩として `info.json` を導入しました。 -QMK API は、これら3つの情報源（`config.h`、` rules.mk`、および `info.json`）を、エンドユーザーツールが使用できる信頼できる単一の情報源に結合するための取り組みです。 - -これで、`info.json`から `rules.mk` と `config.h` の値を生成することがサポートされ、信頼できる単一の情報源を持つことができます。 -これにより、自動化されたツールを使用してキーボードを保守できるため、時間と保守作業を大幅に節約できます。 - -## 概要 - -C 側では何も変わりません。 -新しいルールを作成したり、定義したりする必要がある場合は、同じプロセスに従います。 - -1. `docs/config_options.md` に追加します。 -1. 適切なコアファイルにデフォルトを設定します。 -1. 必要に応じて ifdef 文を追加します。 - -次に、新しい構成のサポートを `info.json` に追加する必要があります。 -基本的なプロセスは次のとおりです。 - -1. `data/schemas/keyboards.jsonschema` のスキーマに追加します -1. `data/maps` にマッピングを追加します -1. （オプションおよび非推奨）構成を抽出/生成するコードを追加します。 - * `lib/python/qmk/info.py` - * `lib/python/qmk/cli/generate/config_h.py` - * `lib/python/qmk/cli/generate/rules_mk.py` - -## info.json にオプションを追加する - -このセクションでは、info.json に `config.h`/`rules.mk` の値のサポートを追加することについて説明します。 - -### スキーマに追加する - -QMK では、[jsonschema](https:json-schema.org) のファイルを `data/schemas` に保持しています。 -キーボード固有の `info.json` ファイルに入る値は `keyboard.jsonschema` に保持されています。 -エンドユーザーが編集できるようにしたい値はすべてここに入れなければなりません。 - -場合によっては、新しいトップレベルキーを追加するだけで済みます。 -従うべきいくつかの例は、 `keyboard_name`、`maintainer`、 `processor`、および `url` です。 -これは、オプションが自己完結型で、他のオプションと直接関係がない場合に適しています。 - -その他の場合、1つの `object` の中に、似ているオプションを集める必要があります。 -これは、機能のサポートを追加する場合に特に当てはまります。 -このために従うべきいくつかの例は、`indicators`、`matrix_pins`、および `rgblight` です。 -新しいオプションを統合する方法がわからない場合は、[問題を開く](https://github.com/qmk/qmk_firmware/issues/new?assignees=&labels=cli%2C+python&template=other_issues.md&title=)か、[Discord で #cli に参加](https://discord.gg/heQPAgy)して、そこで会話を始めてください。 - -### マッピングを追加する - -ほとんどの場合、単純なマッピングを追加することができます。 -これらは `data/mappings/info_config.json` と `data/mappings/info_rules.json` に JSON ファイルとして保持され、それぞれ `config.h` と `rules.mk` のマッピングを制御します。 -各マッピングは `config.h` または `rules.mk` 変数名をキーとし、値は以下のキーを持つハッシュです。 - -* `info_key`: (必須）この値の `info.json` 内の場所。 下記参照。 -* `value_type`: (オプション）デフォルトは `str`。 この変数の値の形式。 下記参照。 -* `to_json`: (オプション）デフォルトは `true`。 このマッピングを info.json から除外するには、`false` に設定します -* `to_c`: (オプション）デフォルトは `true`。 このマッピングを config.h から除外するには、`false` に設定します -* `warn_duplicate`: (オプション）デフォルトは `true`。 値が両方の場所に存在する場合に警告をオフにするには、`false` に設定します - -#### Info Key - -info.json 内の変数をアドレス指定するために JSON ドット表記を使用します。 -たとえば、`info_json["rgblight"]["split_count"]` にアクセスするには、`rgblight.split_count` を指定します。 -これにより、深くネストされたキーを単純な文字列でアドレス指定できます。 - -内部では [Dotty Dict](https://dotty-dict.readthedocs.io/en/latest/) を使用しています。これらの文字列がオブジェクトアクセスに変換される方法についてはそのドキュメントを参照してください。 - -#### Value Types - -デフォルトでは、すべての値を単純な文字列として扱います。 -値がより複雑な場合は、次のいずれかのタイプを使用してデータをインテリジェントに解析できます。 - -* `array`: 文字列のコンマ区切りの配列 -* `array.int`: 整数のコンマ区切り配列 -* `int`: 整数 -* `hex`: 16進数としてフォーマットされた数値 -* `list`: 文字列のスペース区切りの配列 -* `mapping`: キーと値のペアのハッシュ - -### 抽出するコードを追加する - -ほとんどのユースケースは、上記のマッピングファイルによって解決できます。 -できない場合は、代わりに設定値を抽出するコードを書くことができます。 - -QMK が完全な `info.json` を生成するときはいつでも、`config.h` と `rules.mk` から情報を抽出します。 -あなたの新しい設定値のためのコードを `lib/python/qmk/info.py` に追加する必要があります。 -通常、これは、新しい `_extract_()` 関数を追加してから、 `_extract_config_h()` または `_extract_rules_mk()` のいずれかで関数を呼び出すことを意味します。 - -このファイルの編集方法がわからない場合、または Python に慣れていない場合は、[issue を開く](https://github.com/qmk/qmk_firmware/issues/new?assignees=&labels=cli%2C+python&template=other_issues.md&title=）か [Discord で #cli に参加](https://discord.gg/heQPAgy)すると、この部分を誰かが手伝ってくれるでしょう。 - -### 生成するコードを追加する - -パズルの最後のピースは、ビルドシステムに新しいオプションを提供することです。 -これは、2つのファイルを生成することによって行われます。 - -* `.build/obj__/src/info_config.h` -* `.build/obj__/src/rules.mk` - -この2つのファイルは、次のコードによって生成されます。 - -* `lib/python/qmk/cli/generate/config_h.py` -* `lib/python/qmk/cli/generate/rules_mk.py` - -`config.h`値の場合、ルール用の関数を記述し、その関数を `generate_config_h()` で呼び出す必要があります。 - -`rules.mk` の新しいトップレベルの `info.json` キーがある場合は、`lib/python/qmk/cli/generate/rules_mk.py` の上部にある `info_to_rules` にキーを追加するだけです。 -それ以外の場合は、`generate_rules_mk()` で機能の新しい if ブロックを作成する必要があります。 diff --git a/docs/ja/documentation_best_practices.md b/docs/ja/documentation_best_practices.md deleted file mode 100644 index c866d39599..0000000000 --- a/docs/ja/documentation_best_practices.md +++ /dev/null @@ -1,69 +0,0 @@ -# ドキュメントベストプラクティス - - - -このページは QMK のためのドキュメントを作成する時のベストプラクティスを文章化するためのものです。これらのガイドラインに従うことで、一貫したトーンとスタイルを維持することでき、他の人が QMK をより理解しやすくすることができます。 - -# ページの開始 - -ドキュメントページは通常 H1 ヘッダで始まり、最初の段落を使ってこのページの内容を説明します。この見出しと段落は目次の次にあるため、見出しは短くして空白の無い長い文字列を避けるように気を付けてください。 - -例: - -``` -# My Page Title - -This page covers my super cool feature. You can use this feature to make coffee, squeeze fresh oj, and have an egg mcmuffin and hashbrowns delivered from your local macca's by drone. -``` - -# 見出し - -通常、ページには複数の "H1" 見出しが有るべきです。H1 と H2 見出しのみが目次に含まれるので、適切に計画してください。目次が広くなりすぎないように、H1 と H2 の見出しでは幅を広げないようにしてください。 - -# スタイル付きのヒントブロック - -注意を引くためにテキストの周りにスタイル付きのヒントブロックを描くことができます。 - -### 重要なもの - -``` -!> This is important -``` - -以下のように表示されます: - -!> This is important - -### 一般的なヒント - -``` -?> This is a helpful tip. -``` - -以下のように表示されます: - -?> This is a helpful tip. - - -# 機能を文章化する - -QMK のために新しい機能を作成した場合、そのドキュメントページを作成してください。長い必要は無く、機能を説明する幾つかの文と、関連するキーコードを列挙した表で十分です。以下は基本的なテンプレートです: - -```markdown -# My Cool Feature - -This page describes my cool feature. You can use my cool feature to make coffee and order cream and sugar to be delivered via drone. - -## My Cool Feature Keycodes - -|Long Name|Short Name|Description| -|---------|----------|-----------| -|KC_COFFEE||Make Coffee| -|KC_CREAM||Order Cream| -|KC_SUGAR||Order Sugar| -``` - -ドキュメントを `docs/feature_.md` に配置し、そのファイルを `docs/_summary.md` の適切な場所に追加します。キーコードを追加した場合は、機能ページに戻るリンクとともに `docs/keycodes.md` に追加するようにしてください。 diff --git a/docs/ja/documentation_templates.md b/docs/ja/documentation_templates.md deleted file mode 100644 index 0ba3caf5ec..0000000000 --- a/docs/ja/documentation_templates.md +++ /dev/null @@ -1,45 +0,0 @@ -# ドキュメントテンプレート - - - -このページでは、新しいキーマップやキーボードを QMK に提出する際に使うべきテンプレートをまとめています。 - -## キーマップ `readme.md` テンプレート :id=keyboard-readmemd-template - -ほとんどのキーマップには、レイアウトを表す画像があります。画像を作成するには、[Keyboard Layout Editor](https://keyboard-layout-editor.com) を使うことができます。画像は [Imgur](https://imgur.com) や別のホスティングサービスにアップロードし、プルリクエストに画像を含めないでください。 - -画像の下には、キーマップを理解してもらうための簡単な説明文を書いてください。 - -``` -![Clueboard Layout Image](https://i.imgur.com/7Capi8W.png) - -# Default Clueboard Layout - -This is the default layout that comes flashed on every Clueboard. For the most -part it's a straightforward and easy to follow layout. The only unusual key is -the key in the upper left, which sends Escape normally, but Grave when any of -the Ctrl, Alt, or GUI modifiers are held down. -``` - -## キーボード `readme.md` テンプレート - -``` -# Planck - -![Planck](https://i.imgur.com/q2M3uEU.jpg) - -A compact 40% (12x4) ortholinear keyboard kit made and sold by OLKB and Massdrop. [More info on qmk.fm](https://qmk.fm/planck/) - -* Keyboard Maintainer: [Jack Humbert](https://github.com/jackhumbert) -* Hardware Supported: Planck PCB rev1, rev2, rev3, rev4, Teensy 2.0 -* Hardware Availability: [OLKB.com](https://olkb.com), [Massdrop](https://www.massdrop.com/buy/planck-mechanical-keyboard?mode=guest_open) - -Make example for this keyboard (after setting up your build environment): - - make planck/rev4:default - -See the [build environment setup](https://docs.qmk.fm/#/getting_started_build_tools) and the [make instructions](https://docs.qmk.fm/#/getting_started_make_guide) for more information. Brand new to QMK? Start with our [Complete Newbs Guide](https://docs.qmk.fm/#/newbs). -``` diff --git a/docs/ja/driver_installation_zadig.md b/docs/ja/driver_installation_zadig.md deleted file mode 100644 index bd794b4076..0000000000 --- a/docs/ja/driver_installation_zadig.md +++ /dev/null @@ -1,53 +0,0 @@ -# Zadig を使ったブートローダドライバのインストール - - - -QMK はホストにたいして通常の HID キーボードデバイスとして振る舞うため特別なドライバは必要ありません。しかし、Windows でのキーボードへの書き込みは、多くの場合、キーボードをリセットした時に現れるブートローダデバイスで*行います*。 - -2つの注目すべき例外があります: 通常 Pro Micro で見られる Caterina ブートローダや、PJRC Teensy に書き込まれている HalfKay ブートローダは、それぞれシリアルポートと汎用 HID デバイスとして振る舞うため、ドライバは必要ありません。 - -[Zadig](https://zadig.akeo.ie/) ユーティリティを使うことをお勧めします。MSYS2 あるいは WSL を使って開発環境をセットアップした場合、`qmk_install.sh` スクリプトはドライバをインストールするかどうかをたずねます。 - -## インストール - -`RESET` キーコード (別のレイヤにあるかもしれません)を押すか、通常はキーボードの下面にあるリセットスイッチを押して、キーボードをブートローダモードにします。どちらもキーボードに無い場合は、Escape または Space+`B` を押しながら接続してみてください (詳細は、[ブートマジック](ja/feature_bootmagic.md) ドキュメントを見てください)。一部のキーボードはブートマジックの代わりに[コマンド](ja/feature_command.md)を使います。この場合、キーボードが接続されている状態で「左Shift + 右Shift + `B`」あるいは「左Shift + 右Shift + Escape」を押すと、ブートローダモードに入ることができます。 -一部のキーボードはブートローダに入るために特定の操作をする必要があります。例えば、[ブートマジック Lite](ja/feature_bootmagic.md#bootmagic-lite) キー (デフォルト: Escape) は別のキー(例えば、左Control)かもしれません。また、コマンドを有効にするキーの組み合わせ (デフォルト: 左Shift + 右Shift) は何か他のキー(例えば 左Control + 右Control)を押し続ける必要がある場合があります。不明な場合は、キーボードの README ファイルを参照してください。 - -USBaspLoader を使ってデバイスをブートローダモードにするには、`BOOT` ボタンを押しながら `RESET` ボタンをタップしてください。 -あるいは `BOOT` を押し続けながら USB ケーブルを挿入します。 - -Zadig は自動的にブートローダデバイスを検知します。**Options → List All Devices** を確認する必要がある場合があります。 - -- Atmel AVR MCU を搭載したキーボードの場合、ブートローダは `ATm32U4DFU` に似た名前が付けられ、ベンダー ID は `03EB` です。 -- USBasp ブートローダは `USBasp` として表示され、VID/PID は`16C0:05DC` です。 -- QMK-DFU ブートローダを使って書き込まれた AVR キーボードは ` Bootloader` という名前が付けられ、VID は `03EB` です。 -- ほとんどの ARM キーボードでは、`STM32 BOOTLOADER` と呼ばれ、VID/PID は `0483:DF11` です。 - -!> Zadig が `HidUsb` ドライバを使用する1つ以上のデバイスを表示する場合、キーボードはおそらくブートローダモードではありません。矢印はオレンジ色になり、システムドライバの変更を確認するように求められます。この場合、続行**しないでください**！ - -矢印が緑色で表示されたら、ドライバを選択し、**Install Driver** をクリックします。`libusb-win32` ドライバは通常 AVR で動作し、`WinUSB`は ARM で動作しますが、それでもキーボードに書き込みできない場合は、リストから異なるドライバをインストールしてみてください。USBAspLoader デバイスは `libusbK` ドライバを使わなければなりません。 - -![ブートローダドライバが正常にインストールされた Zadig](https://i.imgur.com/b8VgXzx.png) - -最後に、新しいドライバがロードされたことを確認するためにキーボードのプラグを抜いて再接続します。書き込みに QMK Toolbox を使う場合は、ドライバの変更を認識しない場合があるため、QMK Toolkit を終了して再起動します。 - -## 間違ったデバイスのインストールからの回復 - -キーボードが入力できなくなった場合は、ブートローダではなくキーボード自体のドライバを間違って入れ替えた可能性があります。これはキーボードがブートローダモードでない場合に起こりえます。これは Zadig で簡単に確認することができます - 健全なキーボードには、全てのインタフェースに `HidUsb` ドライバがインストールされています: - -![Zadig から見た健全なキーボード](https://i.imgur.com/Hx0E5kC.png) - -デバイスマネージャーを開き、キーボードと思われるデバイスを探します。 - -![デバイスマネージャーにおける、間違ったドライバがインストールされたキーボード](https://i.imgur.com/L3wvX8f.png) - -右クリックし、**デバイスのアンインストール** をクリックします。最初に **このデバイスのドライバーソフトウェアを削除します** にチェックが付いていることを確認してください。 - -!["ドライバの削除"にチェックボックスにチェックが付いた、デバイスのアンインストールダイアログ](https://i.imgur.com/aEs2RuA.png) - -**Action → Scan for hardware changes** をクリックします。この時点で、再び入力できるようになっているはずです。Zadig でキーボードデバイスが `HidUsb` ドライバを使っていることを再確認します。そうであれば完了です。キーボードは再び機能するはずです！ - -?> Windows が新しいドライバを使えるようにするために、この時点でコンピュータを完全に再起動する必要があるかもしれません。 diff --git a/docs/ja/faq_build.md b/docs/ja/faq_build.md deleted file mode 100644 index a1c55407ee..0000000000 --- a/docs/ja/faq_build.md +++ /dev/null @@ -1,73 +0,0 @@ -# よくあるビルドの質問 - - - -このページは QMK のビルドに関する質問を説明します。まだビルドをしていない場合は、[ビルド環境のセットアップ](ja/getting_started_build_tools.md) および [Make 手順](ja/getting_started_make_guide.md)ガイドを読むべきです。 - -## Linux でプログラムできません -デバイスを操作するには適切な権限が必要です。Linux ユーザの場合は、以下の `udev` ルールに関する指示を見てください。`udev` に問題がある場合は、回避策は `sudo` コマンドを使うことです。このコマンドに慣れていない場合は、`man sudo` コマンドでマニュアルを確認するか、[この web ページを見てください](https://linux.die.net/man/8/sudo)。 - -コントローラが ATMega32u4 の場合の `sudo` の使い方の例: - - $ sudo dfu-programmer atmega32u4 erase --force - $ sudo dfu-programmer atmega32u4 flash your.hex - $ sudo dfu-programmer atmega32u4 reset - -あるいは、単純に: - - $ sudo make ::flash - -`make` を `sudo` で実行することは一般的には良い考えでは***なく***、可能であれば前者の方法のいずれかを使うべきです。 - -### Linux の `udev` ルール :id=linux-udev-rules - -Linux では、ブートローダデバイスと通信するには適切な権限が必要です。ファームウェアを書き込む時に `sudo` を使うか(非推奨)、`/etc/udev/rules.d/` に[このファイル](https://github.com/qmk/qmk_firmware/tree/master/util/udev/50-qmk.rules)を配置することで、通信することができます。 - -追加が完了したら、以下を実行します: - -``` -sudo udevadm control --reload-rules -sudo udevadm trigger -``` - -**注意:** 古い(1.12以前の) ModemManager では、フィルタリングは厳密なモードではない場合にのみ動作し、以下のコマンドはその設定を更新することができます。 - -``` -printf '[Service]\nExecStart=\nExecStart=/usr/sbin/ModemManager --filter-policy=default' | sudo tee /etc/systemd/system/ModemManager.service.d/policy.conf -sudo systemctl daemon-reload -sudo systemctl restart ModemManager -``` - -### Linux のブートローダモードで Serial デバイスが検知されない -カーネルがデバイスを適切にサポートしていることを確認してください。デバイスが、Pro Micro (Atmega32u4) のように USB ACM を使う場合、`CONFIG_USB_ACM=y` を含めるようにしてください。他のデバイスは `USB_SERIAL` およびそのサブオプションを必要とするかもしれません。 - -## DFU ブートローダの不明なデバイス - -Windows 上でキーボードを書き込む時に発生する問題は、ブートローダ用に間違ったドライバがインストールされているか、全くインストールされていないかによるものがほとんどです。 - -QMK インストールスクリプト (MSYS2 あるいは WSL 内の `qmk_firmware` ディレクトリから `./util/qmk_install.sh`) を再実行するか、QMK Toolbox の再インストールでこの問題が解決するかもしれません。別のやり方として、手動で [`qmk_driver_installer`](https://github.com/qmk/qmk_driver_installer) パッケージをダウンロードして実行することができます。 - -それでもうまく行かない場合は、Zadig をダウンロードして実行する必要があります。詳細な情報は [Zadig を使ったブートローダドライバのインストール](ja/driver_installation_zadig.md)を見てください。 - -## USB VID と PID -`config.h` を編集することで任意の ID を使うことができます。おそらく未使用の ID を使っても、他の製品と衝突するとても低い可能性があることを除いて、実際には問題はありません。 - -QMK のほとんどのキーボードは、vendor ID として、`0xFEED` を使います。他のキーボードを調べて、ユニークな ID を選択してください。 - -またこれも見てください。 -https://github.com/tmk/tmk_keyboard/issues/150 - -ここで本当にユニークな VID:PID を買うことができます。個人的な使用にはこれは必要ないと思います。 -- https://www.obdev.at/products/vusb/license.html -- https://www.mcselec.com/index.php?page=shop.product_details&flypage=shop.flypage&product_id=92&option=com_phpshop&Itemid=1 - -### キーボードに書き込んだが何も起こらない、あるいはキーの押下が登録されない - ARM (rev6 planck、clueboard 60、hs60v2 など) でも同じ (Feb 2019) -ARM ベースのチップ上での EEPROM の動作によって、保存された設定が無効になる場合があります。これはデフォルトレイヤに影響し、まだ調査中の特定の環境下でキーボードが使えなくなるかも*しれません*。EEPROM のリセットでこれが修正されます。 - -[Planck rev6 reset EEPROM](https://cdn.discordapp.com/attachments/473506116718952450/539284620861243409/planck_rev6_default.bin) を使って eeprom のリセットを強制することができます。このイメージを書き込んだ後で、通常のファームウェアを書き込むと、キーボードが _通常_ の動作順序に復元されます。 -[Preonic rev3 reset EEPROM](https://cdn.discordapp.com/attachments/473506116718952450/537849497313738762/preonic_rev3_default.bin) - -いずれかの形式でブートマジックが有効になっている場合は、これも実行できるはずです (実行方法の詳細については、[ブートマジックドキュメント](ja/feature_bootmagic.md)とキーボード情報を見てください)。 diff --git a/docs/ja/faq_debug.md b/docs/ja/faq_debug.md deleted file mode 100644 index 236f43a6ef..0000000000 --- a/docs/ja/faq_debug.md +++ /dev/null @@ -1,131 +0,0 @@ -# デバッグの FAQ - - - -このページは、キーボードのトラブルシューティングについての様々な一般的な質問を説明します。 - -## デバッグ :id=debugging - -`rules.mk` へ `CONSOLE_ENABLE = yes` の設定をするとキーボードはデバッグ情報を出力します。デフォルトの出力は非常に限られたものですが、デバッグモードをオンにすることでデバッグ情報の量を増やすことが出来ます。キーマップの `DEBUG` キーコードを使用するか、デバッグモードを有効にする[コマンド](ja/feature_command.md)機能を使用するか、以下のコードをキーマップに追加します。 - -```c -void keyboard_post_init_user(void) { - // 希望する動作に合わせて値をカスタマイズします - debug_enable=true; - debug_matrix=true; - //debug_keyboard=true; - //debug_mouse=true; -} -``` - -## デバッグツール - -キーボードのデバッグに使えるツールは2つあります。 - -### 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 用が用意されています。 - -## 独自のデバッグメッセージを送信する - -[カスタムコード](ja/custom_quantum_functions.md)内からデバッグメッセージを出力すると便利な場合があります。それはとても簡単です。ファイルの先頭に `print.h` のインクルードを追加します: - -```c -#include "print.h" -``` - -その後は、いくつかの異なった print 関数を使用することが出来ます: - -* `print("string")`: シンプルな文字列を出力します -* `uprintf("%s string", var)`: フォーマットされた文字列を出力します -* `dprint("string")` デバッグモードが有効な場合のみ、シンプルな文字列を出力します -* `dprintf("%s string", var)`: デバッグモードが有効な場合のみ、フォーマットされた文字列を出力します - -## デバッグの例 - -以下は現実世界での実際のデバッグ手法の例を集めたものです。 - -### マトリックス上のどの場所でキー押下が起こったか？ - -移植する場合や、PCB の問題を診断する場合、キー入力が正しくスキャンされているかどうかを確認することが役立つ場合があります。この手法でのロギングを有効化するには、`keymap.c` へ以下のコードを追加します。 - -```c -bool process_record_user(uint16_t keycode, keyrecord_t *record) { - // コンソールが有効化されている場合、マトリックス上の位置とキー押下状態を出力します -#ifdef CONSOLE_ENABLE - uprintf("KL: kc: 0x%04X, col: %u, row: %u, pressed: %b, time: %u, interrupt: %b, count: %u\n", keycode, record->event.key.col, record->event.key.row, record->event.pressed, record->event.time, record->tap.interrupted, record->tap.count); -#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 -``` - -## `hid_listen` がデバイスを認識できない -デバイスのデバッグコンソールの準備ができていない場合、以下のように表示されます: - -``` -Waiting for device:......... -``` - -デバイスが接続されると、*hid_listen* がデバイスを見つけ、以下のメッセージが表示されます: - -``` -Waiting for new device:......................... -Listening: -``` - -この 'Listening:' のメッセージが表示されない場合は、[Makefile] を `CONSOLE_ENABLE=yes` に設定してビルドしてみてください - -Linux のような OS でデバイスにアクセスするには、特権が必要かもしれません。`sudo hid_listen` を試してください。 - -多くの Linux ディストリビューションでは、次の内容で `/etc/udev/rules.d/70-hid-listen.rules` というファイルを作成することで、root として hid_listen を実行する必要がなくなります: - -``` -SUBSYSTEM=="hidraw", ATTRS{idVendor}=="abcd", ATTRS{idProduct}=="def1", TAG+="uaccess", RUN{builtin}+="uaccess" -``` - -abcd と def1 をキーボードのベンダーとプロダクト IDに置き換えてください。文字は小文字でなければなりません。`RUN{builtin}+="uaccess"` の部分は、古いディストリビューションでのみ必要です。 - -## コンソールにメッセージが表示されない -以下を調べてください: -- *hid_listen* がデバイスを検出する。上記を見てください。 -- **Magic**+d を使ってデバッグを有効にする。[マジックコマンド](https://github.com/tmk/tmk_keyboard#magic-commands)を見てください。 -- `debug_enable=true` を設定します。[デバッグ](#debugging)を見てください。 -- デバッグプリントの代わりに `print` 関数を使ってみてください。**common/print.h** を見てください。 -- コンソール機能を持つ他のデバイスを切断します。[Issue #97](https://github.com/tmk/tmk_keyboard/issues/97) を見てください。 diff --git a/docs/ja/faq_general.md b/docs/ja/faq_general.md deleted file mode 100644 index 407846b788..0000000000 --- a/docs/ja/faq_general.md +++ /dev/null @@ -1,58 +0,0 @@ -# よくある質問 - - - -## QMK とは何か？ - -Quantum Mechanical Keyboard の略である [QMK](https://github.com/qmk) は、カスタムキーボードのためのツールをビルドしている人々のグループです。[TMK](https://github.com/tmk/tmk_keyboard) の大幅に修正されたフォークである [QMK ファームウェア](https://github.com/qmk/qmk_firmware)から始まりました。 - -## どこから始めればいいかわかりません！ - -この場合は、[初心者ガイド](ja/newbs.md) から始めるべきです。ここには多くの素晴らしい情報があり、それらはあなたが始めるのに必要な全てをカバーするはずです。 - -問題がある場合は、[QMK Configurator](https://config.qmk.fm)にアクセスしてください。あなたが必要なものの大部分が処理されます。 - -## ビルドしたファームウェアを書き込むにはどうすればいいですか？ - -まず、[コンパイル/書き込み FAQ ページ](ja/faq-build.md) に進みます。そこにはたくさんの情報があり、そこには一般的な問題に対する多くの解決策があります。 - -## ここで取り上げていない問題がある場合はどうしますか？ - -OK、問題ありません。[GitHub で issue を開く](https://github.com/qmk/qmk_firmware/issues) をチェックして、誰かが同じこと(似ているかだけでなく実際に同じであることを確認してください)を経験しているかどうかを確認してください。 - -もし何も見つからない場合は、[新しい issue](https://github.com/qmk/qmk_firmware/issues/new) を開いてください！ - -## バグを見つけたらどうしますか？ - -[issue](https://github.com/qmk/qmk_firmware/issues/new) を開いてください。そしてもし修正方法を知っている場合は、GitHub で修正のプルリクエストを開いてください。 - -## しかし、`git` と `GitHub` は怖いです！ - -心配しないでください。開発を容易にするために `git` と GitHub を使い始めるための、かなり良い [ガイドライン](ja/newbs_git_best_practices.md) があります。 - -さらに、追加の `git` と GitHub の関連リンクを [ここ](ja/newbs_learn_more_resources.md) に見つけることができます。 - -## サポートを追加したいキーボードがあります - -素晴らしい！プルリクエストを開いてください。私たちはコードをレビューし、マージします！ - -### `QMK` でブランドしたい場合はどうればいいですか？ - -素晴らしい！私たちはあなたを支援したいと思います！ - -実際、私たちにはあなたのページとキーボードに QMK ブランドを追加するための [完全なページ](https://qmk.fm/powered/) があります。これは QMK を公式にサポートするために必要なほぼ全て(知識と画像)をカバーしています。 - -これについて質問がある場合は、issue を開くか、[Discord](https://discord.gg/Uq7gcHh) に進んでください。 - -## QMK と TMK の違いは何か？ - -TMK は [Jun Wako](https://github.com/tmk) によって設計され実装されました。QMK は [Jack Humbert](https://github.com/jackhumbert) の Planck 用 TMK のフォークとして始まりました。しばらくして、Jack のフォークは TMK からかなり分岐し、2015年に Jack はフォークを QMK に名前を変えることにしました。 - -技術的な観点から、QMK は幾つかの新しい機能を追加した TMK に基づいています。最も注目すべきことは、QMK は利用可能なキーコードの数を増やし、`S()`、`LCTL()` および `MO()` などの高度な機能を実装するためにこれらを使っています。[キーコード](ja/keycodes.md)でこれらのキーコードの完全なリストを見ることができます。 - -プロジェクトとコミュニティの管理の観点から、TMK は公式にサポートされている全てのキーボードを自分で管理しており、コミュニティのサポートも少し受けています。他のキーボード用に別個のコミュニティが維持するフォークが存在するか、作成できます。デフォルトでは少数のキーマップのみが提供されるため、ユーザは一般的にお互いにキーマップを共有しません。QMK は集中管理されたリポジトリを介して、キーボードとキーマップの両方を共有することを奨励しており、品質基準に準拠する全てのプルリクエストを受け付けます。これらはほとんどコミュニティで管理されますが、必要な場合は QMK チームも支援します。 - -どちらのアプローチもメリットとデメリットがあり、理に適う場合は TMK と QMK の間でコードは自由にやり取りされます。 diff --git a/docs/ja/faq_keymap.md b/docs/ja/faq_keymap.md deleted file mode 100644 index 9c6cf6232d..0000000000 --- a/docs/ja/faq_keymap.md +++ /dev/null @@ -1,160 +0,0 @@ -# キーマップの FAQ - - - -このページは人々がキーマップについてしばしば持つ疑問について説明します。まだ読んだことが無い場合には、[キーマップの概要](ja/keymap.md)を最初に読むべきです。 - -## どのキーコードを使えますか？ -あなたが利用可能なキーコードのインデックスについては、[キーコード](ja/keycodes.md)を見てください。より広範なドキュメントがある場合は、そこからリンクしてあります。 - -キーコードは実際には [common/keycode.h](https://github.com/qmk/qmk_firmware/blob/master/quantum/keycode.h) で定義されています。 - -## デフォルトのキーコードとは何か？ - -世界中で使用されている ANSI、ISO および JIS の3つの標準キーボードがあります。北米では主に ANSI が使われ、ヨーロッパおよびアフリカでは主に ISO が使われ、日本では JIS が使われます。言及されていない地域では、ANSI あるいは ISO が使われています。これらのレイアウトに対応するキーコードは以下の通りです: - - -![キーボードのレイアウトイメージ](https://i.imgur.com/5wsh5wM.png) - -## 複雑なキーコードのカスタム名を作成する方法はありますか？ - -時には、読みやすくするために、一部のキーコードにカスタム名を定義すると役に立ちます。人々は、しばしば `#define` を使ってカスタム名を定義します。例えば: - -```c -#define FN_CAPS LT(_FL, KC_CAPSLOCK) -#define ALT_TAB LALT(KC_TAB) -``` - -これにより、キーマップで `FN_CAPS` と `ALT_TAB` を使えるようになり、読みやすくなります。 - -## 一部のキーが入れ替わっているか、または動作しない - -QMK には2つの機能、ブートマジックとコマンドがあり、これによりその場でキーボードの動作を変更することができます。これには Ctrl/Caps の交換、Gui の無効化、Alt/Gui の交換、Backspace/Backslash の交換、全てのキーの無効化およびその他の動作の変更が含まれますが、これらに限定されません。 - -迅速な解決策として、キーボードを接続している時に `Space`+`Backspace` を押してみてください。これはキーボードに保存されている設定をリセットし、これらのキーを通常の操作に戻します。うまく行かない場合は、以下を見てください: - -* [ブートマジック](ja/feature_bootmagic.md) -* [コマンド](ja/feature_command.md) - -## メニューキーが動作しない - -ほとんどの最近のキーボードにある、`KC_RGUI` と `KC_RCTL` の間にあるキーは、実際には `KC_APP` と呼ばれます。これは、そのキーが発明された時に、関連する標準にすでに `MENU` という名前のキーが存在していたため、MS はそれを `APP` キーと呼ぶことを選択したためです。 - -## `KC_SYSREQ` が動作しません -`KC_SYSREQ` の代わりに、Print Screen(`KC_PSCREEN` あるいは `KC_PSCR`) のキーコードを使ってください。'Alt + Print Screen' のキーの組み合わせは、'システムリクエスト' と認識されます。 - -[issue #168](https://github.com/tmk/tmk_keyboard/issues/168) と以下を見てください -* https://en.wikipedia.org/wiki/Magic_SysRq_key -* https://en.wikipedia.org/wiki/System_request - -## 電源キーが動作しません - -やや紛らわしいことに、QMK には2つの "Power" キーコードがあります: キーボード/キーパッド HID usage page では `KC_POWER`、Consumer page では `KC_SYSTEM_POWER` (あるいは `KC_PWR`)。 - -前者は macOS でのみ認識されますが、後者 `KC_SLEP` および `KC_WAKE` は3つの主要なオペレーティングシステム全てでサポートされるため、これらを使うことをお勧めします。Windows ではこれらのキーはすぐに機能しますが、macOS ではそれらはダイアログが表示されるまで押し続ける必要があります。 - -## ワンショットモディファイア -私の個人的な 'the' の問題を解決します。'The' ではなく 'the' あるいは 'THe' を間違って入力することがありました。ワンショットシフトはこれを軽減します。 -https://github.com/tmk/tmk_keyboard/issues/67 - -## モディファイヤ/レイヤスタック -修飾キーあるいはレイヤは、レイヤの切り替えが適切に設定されていない場合、スタックするかもしれません。 -修飾キーおよびレイヤ切り替えの場合、リリースイベント時に修飾キーの登録を解除する、もしくは前のレイヤに戻るために、目的のレイヤの同じ位置に `KC_TRANS` を配置する必要があります。 - -* https://github.com/tmk/tmk_core/blob/master/doc/keymap.md#31-momentary-switching -* https://geekhack.org/index.php?topic=57008.msg1492604#msg1492604 -* https://github.com/tmk/tmk_keyboard/issues/248 - - -## メカニカルロックスイッチのサポート - -この機能は [Alps](https://deskthority.net/wiki/Alps_SKCL_Lock) のような*メカニカルロックスイッチ*用です。以下を `config.h` に追加することで有効にすることができます: - -``` -#define LOCKING_SUPPORT_ENABLE -#define LOCKING_RESYNC_ENABLE -``` - -この機能を有効にした後で、キーマップでキーコード `KC_LCAP`、`KC_LNUM` および `KC_LSCR` を使います。 - -古いビンテージメカニカルキーボードにはロックスイッチが付いている場合がありますが、最新のものにはありません。***ほとんどの場合この機能は必要なく、単にキーコード `KC_CAPS`、`KC_NUM` および `KC_SCRL`*** を使います。 - -## セディーユ 'Ç' のような ASCII 以外の特別文字の入力 - -[ユニコード](ja/feature_unicode.md) 機能を見てください。 - -## macOS での `Fn` キー - -ほとんどの Fn キーと異なり、Apple のキーボードの Fn キーには実際には独自のキーコードのようなものがあります。基本的な 6KRO HID レポートの6番目のキーコードの代わりになります -- つまり、Apple キーボードは実際には 5KRO のみです。 - -QMK にこのキーを送信させることは技術的に可能です。ただし、そうするには Fn キーの状態を追加するためにレポート形式の修正を必要とします。 -さらに悪いことに、キーボードの VID と PID が実際の Apple のキーボードのものと一致しない限り、認識されません。公式の QMK がこの機能をサポートすることで法的な問題が起きるため、サポートされることはないでしょう。 - -詳細については、[この issue](https://github.com/qmk/qmk_firmware/issues/2179) を見てください。 - -## Mac OSX でサポートされるキーは？ -このソースコードから、どのキーコードが OSX でサポートされるかを知ることができます。 - -`usb_2_adb_keymap` 配列は、キーボード/キーパッドページの Page usages を ADB スキャンコード(OSX 内部キーコード)にマップします。 - -https://opensource.apple.com/source/IOHIDFamily/IOHIDFamily-606.1.7/IOHIDFamily/Cosmo_USB2ADB.c - -`IOHIDConsumer::dispatchConsumerEvent` は Consumer page usages を処理します。 - -https://opensource.apple.com/source/IOHIDFamily/IOHIDFamily-606.1.7/IOHIDFamily/IOHIDConsumer.cpp - - -## Mac OSX での JIS キー -`無変換(Muhenkan)`, `変換(Henkan)`, `ひらがな(hiragana)` のような日本語 JIS キーボード固有のキーは OSX では認識されません。**Seil** を使ってこれらのキーを使うことができます。以下のオプションを試してください。 - -* PC キーボードで NFER キーを有効にする -* PC キーボードで XFER キーを有効にする -* PC キーボードで KATAKANA キーを有効にする - -https://pqrs.org/osx/karabiner/seil.html - - -## RN-42 Bluetooth が Karabiner で動作しない -Karabiner - Mac OSX 上のキーマッピングツール - は、デフォルトでは RN-42 モジュールからの入力を無視します。Karabiner をキーボードで動作させるにはこのオプションを有効にする必要があります。 -https://github.com/tekezo/Karabiner/issues/403#issuecomment-102559237 - -この問題の詳細についてはこれらを見てください。 -https://github.com/tmk/tmk_keyboard/issues/213 -https://github.com/tekezo/Karabiner/issues/403 - - -## 単一のキーでの Esc と` - -[Grave Escape](ja/feature_grave_esc.md) 機能を見てください。 - -## Mac OSX での Eject -`KC_EJCT` キーコードは OSX で動作します。https://github.com/tmk/tmk_keyboard/issues/250 -Windows 10 はコードを無視し、Linux/Xorg は認識しますが、デフォルトではマッピングがありません。 - -実際の Apple キーボードにある Eject キーコードは実際には分かりません。HHKB は Mac モードでは Eject キー (`Fn+f`) に `F20` を使いますが、これはおそらく Apple の Eject キーコードと同じではありません。 - - -## `action_util.c` の `weak_mods` と `real_mods` は何か -___改善されるべきです___ - -real_mods は実際の物理的な修飾キーの状態を保持することを目的にしていますが、weak_mods は実際の修飾キーの状態に影響しない仮想あるいは一時的なモディファイアの状態を保持します。 - -物理的な左シフトキーを押しながら ACTION_MODS_KEY(LSHIFT, KC_A) を入力するとします - -weak_mods では、 -* (1) 左シフトキーを押し続ける: real_mods |= MOD_BIT(LSHIFT) -* (2) ACTION_MODS_KEY(LSHIFT, KC_A) を押す: weak_mods |= MOD_BIT(LSHIFT) -* (3) ACTION_MODS_KEY(LSHIFT, KC_A) を放す: weak_mods &= ~MOD_BIT(LSHIFT) -real_mods はモディファイアの状態を維持します。 - -weak mods 無しでは、 -* (1) 左シフトキーを押し続ける: real_mods |= MOD_BIT(LSHIFT) -* (2) ACTION_MODS_KEY(LSHIFT, KC_A) を押す: real_mods |= MOD_BIT(LSHIFT) -* (3) ACTION_MODS_KEY(LSHIFT, KC_A) を放す: real_mods &= ~MOD_BIT(LSHIFT) -ここで、real_mods は 'physical left shift' '物理的な左シフト' の状態を見失います。 - -キーボードレポートが送信される時、weak_mods は real_mods と論理和がとられます。 -https://github.com/tmk/tmk_core/blob/master/common/action_util.c#L57 diff --git a/docs/ja/faq_misc.md b/docs/ja/faq_misc.md deleted file mode 100644 index 24a0e18235..0000000000 --- a/docs/ja/faq_misc.md +++ /dev/null @@ -1,103 +0,0 @@ -# その他の FAQ - - - -## どうやってキーボードをテストすればいいですか？ :id=testing - -通常、キーボードのテストは非常に簡単です。全てのキーをひとつずつ押して、期待するキーが送信されることを確認します。例え QMK で動作していない場合でも、[QMK Configurator](https://config.qmk.fm/#/test/) のテストモードを使用すると、キーボードをチェックできます。 - -## 安全性の考慮 - -あなたはおそらくキーボードを「文鎮化」したくないでしょう。文鎮化するとファームウェアを書き換えられないようになります。リスクがあまりに高い(そしてそうでないかもしれない)ものの一部のリストを示します。 - -- キーボードマップに QK_BOOT が含まれない場合、DFU モードに入るには、PCB のリセットボタンを押す必要があります。底部のネジを外す必要があります。 -- tmk_core / common にあるファイルを触るとキーボードが操作不能になるかもしれません。 -- .hex ファイルが大きすぎると問題を引き起こします; `make dfu` コマンドはブロックを削除し、サイズを検査し(おっと、間違った順序です！)、エラーを出力し、 -キーボードへの書き込みに失敗し、DFU モードのままになります。 - - この目的のためには、Planck の最大の .hex ファイルサイズは 7000h (10進数で28672)であることに注意してください。 - -``` -Linking: .build/planck_rev4_cbbrowne.elf [OK] -Creating load file for Flash: .build/planck_rev4_cbbrowne.hex [OK] - -Size after: - text data bss dec hex filename - 0 22396 0 22396 577c planck_rev4_cbbrowne.hex -``` - - - 上のファイルのサイズは 22396/577ch で、28672/7000h より小さいです。 - - 適切な代わりの .hex ファイルがある限り、それをロードして再試行することができます。 - - あなたがキーボードの Makefile で指定したかもしれない一部のオプションは、余分なメモリを消費します; BOOTMAGIC_ENABLE、MOUSEKEY_ENABLE、EXTRAKEY_ENABLE、CONSOLE_ENABLE、API_SYSEX_ENABLE に注意してください。 -- DFU ツールは(オプションの余計なフルーツサラダを投げ込まない限り)ブートローダに書き込むことを許可しないので、ここにはリスクはほとんどありません。 -- EEPROM の書き込みサイクルは、約100000(10万)です。ファームウェアを繰り返し継続的に書き換えるべきではありません。それは最終的に EEPROM を焼き焦がします。 - -## NKRO が動作しません -最初に、**Makefile** 内でビルドオプション `NKRO_ENABLE` を使ってファームウェアをコンパイルする必要があります。 - -**NKRO** がまだ動作しない場合は、`Magic` **N** コマンド(デフォルトでは `LShift+RShift+N`)を試してみてください。**NKRO** モードと **6KRO** モード間を一時的に切り替えるためにこのコマンドを使うことができます。**NKRO** が機能しない状況、特に BIOS の場合は **6KRO** モードに切り替える必要があります。 - - -## トラックポイントははリセット回路が必要です (PS/2 マウスサポート) -リセット回路が無いとハードウェアの不適切な初期化のために一貫性の無い結果になります。TPM754 の回路図を見てください: - -- https://geekhack.org/index.php?topic=50176.msg1127447#msg1127447 -- https://www.mikrocontroller.net/attachment/52583/tpm754.pdf - - -## 16 を超えるマトリックの列を読み込めない -列が 16 を超える場合、[matrix.h] の `read_cols()` 内の `1<<16` の代わりに `1UL<<16` を使ってください。 - -C では、AVR の場合 `1` は [16 bit] である [int] 型の1を意味し、15を超えて左にシフトすることはできません。従って、`1<<16` を計算すると予期せずゼロになります。これを回避するには `1UL` として [unsigned long] 型を使う必要があります。 - -https://deskthority.net/workshop-f7/rebuilding-and-redesigning-a-classic-thinkpad-keyboard-t6181-60.html#p146279 - -## 特別なエクストラキーが動作しない(システム、オーディオコントロールキー) -QMK でそれらを使うには、`rules.mk` 内で `EXTRAKEY_ENABLE` を定義する必要があります。 - -``` -EXTRAKEY_ENABLE = yes # オーディオ制御とシステム制御 -``` - -## スリープから復帰しない - -**デバイスマネージャ**の**電源の管理**タブ内の `このデバイスで、コンピュータのスタンバイ状態を解除できるようにする` 設定を調べてください。また BIOS 設定も調べてください。スリープ中に任意のキーを押すとホストが起動するはずです。 - -## Arduino を使っていますか？ - -**Arduino のピンの命名は実際のチップと異なることに注意してください。** 例えば、Arduino のピン `D0` は `PD0` ではありません。回路図を自身で確認してください。 - -- https://arduino.cc/en/uploads/Main/arduino-leonardo-schematic_3b.pdf -- https://arduino.cc/en/uploads/Main/arduino-micro-schematic.pdf - -Arduino の Leonardo と micro には **ATMega32U4** が載っていて、TMK 用に使うことができますが、Arduino のブートローダが問題になることがあります。 - -## JTAG を有効にする - -デフォルトでは、キーボードが起動するとすぐに JTAG デバッグインタフェースが無効になります。JTAG 対応 MCU は `JTAGEN` ヒューズが設定された状態で出荷されており、キーボードがスイッチマトリックス、LED などに使用している可能性のある MCU の特定のピンを乗っ取ります。 - -JTAG を有効にしたままにしたい場合は、単に以下のものを `config.h` に追加します: - -```c -#define NO_JTAG_DISABLE -``` - -## USB 3 の互換性 -一部の問題は、USB 3.x ポートから USB 2.0 ポートに切り替えることで修正できます。 - - -## Mac の互換性 -### OS X 10.11 と Hub -こちらを見てください: https://geekhack.org/index.php?topic=14290.msg1884034#msg1884034 - - -## BIOS (UEFI) 設定/リジューム (スリープとウェークアップ)/電源サイクルの問題 -一部の人がキーボードが BIOS で動作しなくなった、またはリジューム(電源サイクル)の後で動作しなくなったと報告しました。 - -今のところ、この問題の根本は明確ではないですが、幾つかのビルドオプションが関係しているようです。Makefile で、`CONSOLE_ENABLE`、`NKRO_ENABLE`、`SLEEP_LED_ENABLE` あるいは他のオプションを無効にしてみてください。 - -より詳しい情報: -- https://github.com/tmk/tmk_keyboard/issues/266 -- https://geekhack.org/index.php?topic=41989.msg1967778#msg1967778 diff --git a/docs/ja/feature_advanced_keycodes.md b/docs/ja/feature_advanced_keycodes.md deleted file mode 100644 index 2416c742a0..0000000000 --- a/docs/ja/feature_advanced_keycodes.md +++ /dev/null @@ -1,185 +0,0 @@ -# 修飾キー :id=modifier-keys - - - -以下のようにキーコードとモディファイアを組み合わせることができます。押すと、モディファイアのキーダウンイベントが送信され、次に `kc` のキーダウンイベントが送信されます。放すと、`kc` のキーアップイベントが送信され、次にモディファイアのキーアップイベントが送信されます。 - -| キー | エイリアス | 説明 | -| ---------- | ---------------------------------- | ------------------------------------------------------------------- | -| `LCTL(kc)` | `C(kc)` | 左 Control を押しながら `kc` を押します。 | -| `LSFT(kc)` | `S(kc)` | 左 Shift を押しながら `kc` を押します。 | -| `LALT(kc)` | `A(kc)`, `LOPT(kc)` | 左 Alt を押しながら `kc`を押します。 | -| `LGUI(kc)` | `G(kc)`, `LCMD(kc)`, `LWIN(kc)` | 左 GUI を押しながら `kc` を押します。 | -| `RCTL(kc)` | | 右 Control を押しながら `kc` を押します。 | -| `RSFT(kc)` | | 右 Shift を押しながら `kc` を押します。 | -| `RALT(kc)` | `ROPT(kc)`, `ALGR(kc)` | 右 Alt を押しながら `kc` を押します。 | -| `RGUI(kc)` | `RCMD(kc)`, `LWIN(kc)` | 右 GUI を押しながら `kc` を押します。 | -| `LSG(kc)` | `SGUI(kc)`, `SCMD(kc)`, `SWIN(kc)` | 左 Shift と左 GUI を押しながら `kc` を押します。 | -| `LAG(kc)` | | 左 Alt と左 GUI を押しながら `kc` を押します。 | -| `RSG(kc)` | | 右 Shift と右 GUI を押しながら `kc` を押します。 | -| `RAG(kc)` | | 右 Alt と右 GUI を押しながら `kc` を押します。 | -| `LCA(kc)` | | 左 Control と左 Alt を押しながら `kc` を押します。 | -| `LSA(kc)` | | 左 Shift と左 Alt を押しながら `kc` を押します。 | -| `RSA(kc)` | `SAGR(kc)` | 右 Shift と右 Alt (AltGr) を押しながら `kc` を押します。 | -| `RCS(kc)` | | 右 Control と右 Shift を押しながら `kc` を押します。 | -| `LCAG(kc)` | | 左 Control、左 Alt、左 GUI を押しながら `kc` を押します。 | -| `MEH(kc)` | | 左 Control、左 Shift、左 Alt を押しながら `kc` を押します。 | -| `HYPR(kc)` | | 左 Control、左 Shift、左 Alt、左 GUI を押しながら `kc` を押します。 | - -また、それらを繋げることができます。例えば、`LCTL(LALT(KC_DEL))` または `C(A(KC_DEL))` は1回のキー押下で Control+Alt+Delete を送信するキーを作成します。 - -# モディファイアの状態を確認 :id=checking-modifier-state - - -現在のモディファイアの状態は、2つの関数によって主にアクセスされます。: `get_mods()` 関数は通常のモディファイアとモッドタップの状態を、`get_oneshot_mods()` 関数はワンショットモディファイアの状態を確認する関数です。(ワンショットモディファイアはキーが押されていない限り、通常のモディファイアキーのように動作します。) - -1つ以上の特定のモディファイアが現在のモディファイアの状態に含まれているかどうかは、モディファイアの状態と、照合したいモディファイアの組み合わせに相当するモッドマスクとを AND 演算することで検出できます。 -ビット演算が使われる理由は、モディファイアの状態が (GASC)R(GASC)L の形式で1バイトとして格納されるためです。 - -従って、例を挙げると、`01000010` は LShift+RALT の内部表現です。 -C 言語におけるビット演算のより詳しい情報は、[ここ](https://en.wikipedia.org/wiki/Bitwise_operations_in_C) をクリックして、Wikipedia のページのトピックを開いてください。 - -実際には、`get_mods() & MOD_BIT(KC_)`([モディファイアキーコードのリスト](ja/keycodes_basic.md#modifiers) 参照) で、あるモディファイアが有効かどうかをチェックできるということです、また左右のモディファイアの違いが重要ではなく、両方にマッチさせたい場合は、`get_mods() & MOD_MASK_`とします。ワンショットモディファイアについても、`get_mods()` を `get_oneshot_mods()` に置き換えれば同じことができます。 - -モディファイアの特定の組み合わせが同時にアクティブなのか確認する*だけ*なら、上で説明したモディファイアの状態とモッドマスクの論理積と、モッドマスク自身の結果を比較します。: `get_mods() & == ` - -例えば、左 Control キーと 左 Shift キーのワンショットモディファイアがオンで、その他のワンショットモディファイアがオフの場合にカスタムコードを起動したいとしましょう。そうするには、`(MOD_BIT(KC_LCTL) | MOD_BIT(KC_LSFT))` で左 Control キーと Shift キーのモッドビットを組み合わせて目的のモッドマスクを構成し、それらを差し込みます: `get_oneshot_mods & (MOD_BIT(KC_LCTL) | MOD_BIT(KC_LSFT)) == (MOD_BIT(KC_LCTL) | MOD_BIT(KC_LSFT))`。モッドビットマスクの代わりに `MOD_MASK_CS` 使うと、条件を満たすために4つのモディファイアキー (左右両方の Control キーと Shift キー) を押す必要があります。 - -モッドマスクの完全なリストは、以下のとおりです。 - -| モッドマスク名 | マッチするモディファイア | -|--------------------|-------------------------------------------------------------| -| `MOD_MASK_CTRL` | 左 Control , 右 Control | -| `MOD_MASK_SHIFT` | 左 Shift , 右 Shift | -| `MOD_MASK_ALT` | 左 Alt , 右 Alt | -| `MOD_MASK_GUI` | 左 GUI , 右 GUI | -| `MOD_MASK_CS` | Control , Shift | -| `MOD_MASK_CA` | (左/右) Control , (左/右) Alt | -| `MOD_MASK_CG` | (左/右) Control , (左/右) GUI | -| `MOD_MASK_SA` | (左/右) Shift , (左/右) Alt | -| `MOD_MASK_SG` | (左/右) Shift , (左/右) GUI | -| `MOD_MASK_AG` | (左/右) Alt , (左/右) GUI | -| `MOD_MASK_CSA` | (左/右) Control , (左/右) Shift , (左/右) Alt | -| `MOD_MASK_CSG` | (左/右) Control , (左/右) Shift , (左/右) GUI | -| `MOD_MASK_CAG` | (左/右) Control , (左/右) Alt , (左/右) GUI | -| `MOD_MASK_SAG` | (左/右) Shift , (左/右) Alt , (左/右) GUI | -| `MOD_MASK_CSAG` | (左/右) Control , (左/右) Shift , (左/右) Alt , (左/右) GUI | - -`get_mods()` 関数を使って現在アクティブなモディファイアにアクセスする以外に、モディファイアの状態を変更するために使えるいくつかの関数があります。ここでは、`mods` 引数はモディファイアビットマスクを表します。 - -* `add_mods(mods)`: その他のモディファイアに影響を与えずに `mods` を有効にします。 -* `register_mods(mods)`: `add_mods` に似ていますが、キーボードにすぐにレポートを送信します。 -* `del_mods(mods)`: その他のモディファイアに影響を与えずに `mods` を無効にします。 -* `unregister_mods(mods)`: `del_mods` に似ていますが、キーボードにすぐにレポートを送信します。 -* `set_mods(mods)`: `mods` で現在のモディファイアの状態を上書きします -* `clear_mods()`: 全てのモディファイアを無効にすることによって、モディファイアの状態をリセットします。 - -同様に、`get_oneshot_mods()` 関数に加えて、ワンショットモディファイアのための関数もあります。 - -* `add_oneshot_mods(mods)`: その他のワンショットモディファイアに影響を与えずに `mods` を有効にします -* `del_oneshot_mods(mods)`: その他のワンショットモディファイアに影響を与えずに `mods` を無効にします -* `set_oneshot_mods(mods)`: `mods` で現在のワンショットモディファイアの状態を上書きします -* `clear_oneshot_mods()`: 全てのワンショットモディファイアを無効にすることによって、ワンショットモディファイアの状態をリセットします。 - -## 例 :id=examples - -次の例は、[マクロについてのページ](ja/feature_macros.md) で読める [高度なマクロ](ja/feature_macros.md?id=advanced-macro-functions) を使っています。 -### Alt + Tab の代わりの Alt + Escape :id=alt-escape-for-alt-tab - -左 Alt と `KC_ESC` が押されたときに、アプリ切り替えの（左 Alt と） `KC_TAB` のように振る舞うことを実現する単純な例です。この例は、左 Alt だけがアクティブになっているかを厳格に確認します。つまり、Alt+Shift+Esc によるアプリの逆順での切り替えはできません。また、この例は、実際の Alt+Escape キーボードショートカットを起動することはできなくなりますが、AltGr+Escape キーボードショートカットを起動することはできることに留意してください。 - -```c -bool process_record_user(uint16_t keycode, keyrecord_t *record) { - switch (keycode) { - - case KC_ESC: - // 左 Alt だけがアクティブか検知します - if ((get_mods() & MOD_BIT(KC_LALT)) == MOD_BIT(KC_LALT)) { - if (record->event.pressed) { - // KC_LALT を登録する必要はありません。既にアクティブだからです。 - // Alt モディファイアはこの KC_TAB に適用されます。 - register_code(KC_TAB); - } else { - unregister_code(KC_TAB); - } - // QMK にこれ以上キーコードの処理をさせません。 - return false; - } - // それ以外の場合は、QMK に通常通り KC_ESC の処理をさせます。 - return true; - - } - return true; -}; -``` - -### Delete の代わりの Shift + Backspace :id=shift-backspace-for-delete - -`KC_BSPC` と組み合わせることで Shift の本来の動作が取り消され、そして、`KC_DEL` に完全に置き換えられる高度な例です。この例を適切に動作させるために2つのメイン変数が作られます。: `mod_state` と `delkey_registered` です。最初の1つ目の変数は、モディファイアの状態を記憶し、`KC_DEL` を登録した後に元に戻すために使われます。2つ目の変数はブール型変数 (true または false) で、`KC_DEL` の状態を追跡して Backspace/Delete キー全体のリリースを正確に管理します。 - -前の例と対照的に、この例は厳格なモディファイアの確認を行いません。このカスタムコードを起動するには、1つまたは2つの Shift キーがアクティブな間に `KC_BSPC` を押せば十分で、他のモディファイアの状態は関係ありません。この方法は、いくつかの特典を提供します。: Ctrl+Shift+Backspace は次の単語を削除 (Control+Delete) し、Ctrl+Alt+Shift+Backspace は Ctrl+Alt+Del キーボードショートカットを実行します。 - -```c -// アクティブなモディファイアを表すバイナリデータを保持する変数を初期化します -uint8_t mod_state; -bool process_record_user(uint16_t keycode, keyrecord_t *record) { - // 後々の参照のために現在のモディファイアの状態を変数に格納します - mod_state = get_mods(); - switch (keycode) { - - case KC_BSPC: - { - // Delete キーの状態（登録されているかどうか）を追跡するブール型変数を初期化します。 - static bool delkey_registered; - if (record->event.pressed) { - // いずれかの Shift がアクティブか検知します - if (mod_state & MOD_MASK_SHIFT) { - // 最初に、 Shift キーを KC_DEL に適用しないため、 - // 一時的に左右両方の Shift キーをキャンセルします - del_mods(MOD_MASK_SHIFT); - register_code(KC_DEL); - // KC_DEL の状態を反映させるためにブール型変数を更新します - delkey_registered = true; - // Backspace/Delete キーをタップした後でも押し続けている Shift キーが機能するように、 - // モディファイアの状態を再適用します。 - set_mods(mod_state); - return false; - } - } else { // KC_BSPC キーを離した場合 - // KC_BSPC を離しても KC_DEL が送信されている場合 - if (delkey_registered) { - unregister_code(KC_DEL); - delkey_registered = false; - return false; - } - } - // QMK に Shift キーを除いて KC_BSPC を通常通り処理させます - return true; - } - - } - return true; -}; -``` -# 過去の内容 :id=legacy-content - -このページには多くの機能が含まれていました。このページを構成していた多くのセクションをそれぞれのページに移動しました。これより下は全て単なるリダイレクトであるため、web上で古いリンクをたどっている人は探しているものを見つけることができます。 - -## レイヤー :id=switching-and-toggling-layers - -* [レイヤー](ja/feature_layers.md) - -## モッドタップ :id=mod-tap - -* [モッドタップ](ja/mod_tap.md) - -## ワンショットキー :id=one-shot-keys - -* [ワンショットキー](ja/one_shot_keys.md) - -## タップホールド設定オプション :id=tap-hold-configuration-options - -* [タップホールド設定オプション](ja/tap_hold.md) diff --git a/docs/ja/feature_audio.md b/docs/ja/feature_audio.md deleted file mode 100644 index 2d1fd8f78a..0000000000 --- a/docs/ja/feature_audio.md +++ /dev/null @@ -1,322 +0,0 @@ -# オーディオ - - - -キーボードは音を出すことができます！Planck、Preonic あるいは特定の PWM 対応ピンにアクセスできる AVR キーボードがある場合は、単純なスピーカーを接続してビープ音を鳴らすことができます。これらのビープ音を使ってレイヤーの変化、モディファイア、特殊キーを示したり、あるいは単にイカした8ビットの曲を鳴らすことができます。 - -最大2つの同時オーディオ音声がサポートされ、1つはタイマー1によってもう一つはタイマー3によって駆動されます。以下のピンは config.h の中でオーディオ出力として定義することができます: - -Timer 1: -`#define B5_AUDIO` -`#define B6_AUDIO` -`#define B7_AUDIO` - -Timer 3: -`#define C4_AUDIO` -`#define C5_AUDIO` -`#define C6_AUDIO` - -`rules.mk` に `AUDIO_ENABLE = yes` を追加すると、他の設定無しで自動的に有効になる幾つかの異なるサウンドがあります: - -``` -STARTUP_SONG // キーボードの起動時に再生 (audio.c) -GOODBYE_SONG // QK_BOOT キーを押すと再生 (quantum.c) -AG_NORM_SONG // AG_NORM キーを押すと再生 (quantum.c) -AG_SWAP_SONG // AG_SWAP キーを押すと再生 (quantum.c) -CG_NORM_SONG // CG_NORM キーを押すと再生 (quantum.c) -CG_SWAP_SONG // CG_SWAP キーを押すと再生 (quantum.c) -MUSIC_ON_SONG // 音楽モードがアクティブになると再生 (process_music.c) -MUSIC_OFF_SONG // 音楽モードが非アクティブになると再生 (process_music.c) -CHROMATIC_SONG // 半音階音楽モードが選択された時に再生 (process_music.c) -GUITAR_SONG // ギター音楽モードが選択された時に再生 (process_music.c) -VIOLIN_SONG // バイオリン音楽モードが選択された時に再生 (process_music.c) -MAJOR_SONG // メジャー音楽モードが選択された時に再生 (process_music.c) -``` - -`config.h` の中で以下のような操作を行うことで、デフォルトの曲を上書きすることができます: - -```c -#ifdef AUDIO_ENABLE - #define STARTUP_SONG SONG(STARTUP_SOUND) -#endif -``` - -サウンドの完全なリストは、[quantum/audio/song_list.h](https://github.com/qmk/qmk_firmware/blob/master/quantum/audio/song_list.h) で見つかります - このリストに自由に追加してください！利用可能な音は [quantum/audio/musical_notes.h](https://github.com/qmk/qmk_firmware/blob/master/quantum/audio/musical_notes.h) で見つかります。 - -特定の時にカスタムサウンドを再生するために、以下のように曲を定義することができます(ファイルの上部付近に): - -```c -float my_song[][2] = SONG(QWERTY_SOUND); -``` - -以下のように曲を再生します: - -```c -PLAY_SONG(my_song); -``` - -または、以下のようにループで再生することができます: - -```c -PLAY_LOOP(my_song); -``` - -オーディオがキーボードに組み込まれていない時に問題が起きる事を避けるために、`#ifdef AUDIO_ENABLE` / `#endif` で全てのオーディオ機能をくるむことをお勧めします。 - -オーディオで利用可能なキーコードは以下の通りです: - -* `AU_ON` - オーディオ機能をオン -* `AU_OFF` - オーディオ機能をオフ -* `AU_TOG` - オーディオ機能を切り替え - -!> これらのキーコードは全てのオーディオ機能をオンおよびオフにします。オフにするとオーディオフィードバック、オーディオクリック、音楽モードなどが完全に無効になります。 - -## ARM オーディオボリューム - -ARM デバイスの場合、DAC サンプル値を調整できます。キーボードがあなたやあなたの同僚にとって騒々しい場合、`config.h` 内の `DAC_SAMPLE_MAX` を使って最大量を設定することができます: - -```c -#define DAC_SAMPLE_MAX 65535U -``` - -## 音楽モード - -音楽モードは列を半音階に、行をオクターブにマップします。これは格子配列キーボードで最適に動作しますが、他のものでも動作させることができます。`0xFF` 未満の全てのキーコードはブロックされるため、音の演奏中は入力できません - 特別なキー/mod があればそれらは引き続き動作します。これを回避するには、音楽モードを有効にする前(あるいは後)で、KC_NO を使って別のレイヤーにジャンプします。 - -メモリの問題により、録音は実験的です - 奇妙な動作が発生した場合は、キーボードの取り外しと再接続で問題が解決するでしょう。 - -利用可能なキーコード: - -* `MU_ON` - 音楽モードをオン -* `MU_OFF` - 音楽モードをオフ -* `MU_TOG` - 音楽モードの切り替え -* `MU_MOD` - 音楽モードの循環 - * `CHROMATIC_MODE` - 半音階。行はオクターブを変更します - * `GUITAR_MODE` - 半音階、ただし行は弦を変更します (+5 階) - * `VIOLIN_MODE` - 半音階。ただし行は弦を変換します (+7 階) - * `MAJOR_MODE` - メージャースケール - -音楽モードでは、以下のキーコードは動作が異なり、通過しません: - -* `LCTL` - 録音を開始 -* `LALT` - 録音を停止/演奏を停止 -* `LGUI` - 録音を再生 -* `KC_UP` - 再生をスピードアップ -* `KC_DOWN` - 再生をスローダウン - -ピッチ標準 (`PITCH_STANDARD_A`) はデフォルトで 440.0f です - これを変更するには、`config.h` に以下のようなものを追加します: - - #define PITCH_STANDARD_A 432.0f - -音楽モードも完全に無効にすることができます。コントローラの容量が足りなくて困っている場合に役に立ちます。無効にするには、これを `config.h` に追加します: - - #define NO_MUSIC_MODE - -### 音楽マスク - -デフォルトで、`MUSIC_MASK` は `keycode < 0xFF` に設定されます。これは、`0xFF` 未満のキーコードが音に変換され、何も出力しないことを意味します。`config.h` の中で以下のものを定義することで、これを変更することができます: - - #define MUSIC_MASK keycode != KC_NO - -これは全てのキーコードを捕捉します - これは、キーボードを再起動するまで、音楽モードで動けなくなることに注意してください！ - -どのキーコードを引き続き処理するかを制御する、より高度な方法については、`.c` の中の `music_mask_kb(keycode)` および `keymap.c` の中の `music_mask_user(keycode)` を使うことができます: - - bool music_mask_user(uint16_t keycode) { - switch (keycode) { - case RAISE: - case LOWER: - return false; - default: - return true; - } - } - -false を返すものはマスクの一部では無く、常に処理されます。 - -### 音楽マップ - -デフォルトでは、音楽モードはキーのスケールを決定するために列と行を使います。キーボードレイアウトに一致する長方形のマトリックスを使うキーボードの場合、これで十分です。しかし、(Planck Rev6 あるいは多くの分割キーボードなどのように)より複雑なマトリックスを使うキーボードの場合、非常に歪んだ感じを受けることになります。 - -しかしながら、音楽マップオプションにより、音楽モードのためにスケーリングを再マップすることができるため、レイアウトに一致し、より自然になります。 - -この機能を使うには、`#define MUSIC_MAP` を `config.h` ファイルに追加します。そして、`キーボードの名前.c` または `keymap.c` に `uint8_t music_map` を追加します。 - -```c -const uint8_t music_map[MATRIX_ROWS][MATRIX_COLS] = LAYOUT_ortho_4x12( - 36, 37, 38, 39, 40, 41, 42, 43, 44, 45, 46, 47, - 24, 25, 26, 27, 28, 29, 30, 31, 32, 33, 34, 35, - 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, - 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11 -); -``` - -キーボードが使用する `LAYOUT` マクロも使用したいでしょう。これは正しいキーの位置にマップします。キーボードレイアウトの左下から開始し、右に移動してさらに上に移動します。完全なマトリックスができるまで、全てのエントリを入力します。 - -これを実装する方法の例として、[Planck Keyboard](https://github.com/qmk/qmk_firmware/blob/e9ace1487887c1f8b4a7e8e6d87c322988bec9ce/keyboards/planck/planck.c#L24-L29) を見ることができます。 - -## オーディオクリック - -これは、ボタンを押すたびにクリック音を追加し、キーボードからのクリック音をシミュレートします。キーを押すたびにわずかに音が異なるため、すばやく入力しても長い単一の音のようには聞こえません。 - -* `CK_TOGG` - ステータスを切り替えます (有効にされた場合、音を再生します) -* `CK_ON` - オーディオクリックをオンにします (音を再生します) -* `CK_OFF` - オーディオクリックをオフにします (音を再生しません） -* `CK_RST` - 周波数をデフォルトの状態に再設定します (デフォルトの周波数で音を再生します) -* `CK_UP` - クリック音の周波数を増やします (新しい周波数で音を再生します) -* `CK_DOWN` - クリック音の周波数を減らします (新しい周波数で音を再生します) - - -容量を節約するためにデフォルトではこの機能は無効です。有効にするには、`config.h` に以下を追加します: - - #define AUDIO_CLICKY - - -これらの値を定義することで、デフォルト、最小および最大周波数、ステッピングおよび組み込みのランダム性を設定することができます: - -| オプション | デフォルト値 | 説明 | -|--------|---------------|-------------| -| `AUDIO_CLICKY_FREQ_DEFAULT` | 440.0f | クリック音のデフォルト/開始音の周波数を設定します。 | -| `AUDIO_CLICKY_FREQ_MIN` | 65.0f | 最小周波数を設定します (60f 未満は少しバグがあります)。 | -| `AUDIO_CLICKY_FREQ_MAX` | 1500.0f | 最大周波数を設定します。高すぎると同僚があなたを攻撃する可能性があります。 | -| `AUDIO_CLICKY_FREQ_FACTOR` | 1.18921f | UP/DOWN キーコードのステップを設定します。これは掛け算の係数です。デフォルトでは、音楽のマイナーの1/3ずつ、周波数を上げ/下げします。 | -| `AUDIO_CLICKY_FREQ_RANDOMNESS` | 0.05f | クリックのランダム性の係数を設定します。これを `0f` に設定すると各クリックが同一になり、`1.0f` に設定するとこの音は90年代のコンピュータ画面のスクロール/タイピングの効果があります。 | -| `AUDIO_CLICKY_DELAY_DURATION` | 1 | 1がテンポの 1/16、または64分音符である整数音符の長さ (実装の詳細については、`quantum/audio/musical_notes.h` を見てください)。メインのクリック効果は、この時間だけ遅れます。これらを6-12前後の値に調整すると、うるさいスイッチの補正に役立ちます。 | - - - - -## MIDI 機能 - -これはまだ WIP ですが、何が起きているかを見るために、`quantum/process_keycode/process_midi.c` を調べてください。Makefile から有効にします。 - - -## オーディオキーコード - -| キー | エイリアス | 説明 | -|----------------|---------|----------------------------------| -| `AU_ON` | | オーディオモードオン | -| `AU_OFF` | | オーディオモードオフ | -| `AU_TOG` | | オーディオモードを切り替えます | -| `CLICKY_TOGGLE` | `CK_TOGG` | オーディオクリックモードを切り替えます | -| `CLICKY_UP` | `CK_UP` | クリック音の周波数を増やします | -| `CLICKY_DOWN` | `CK_DOWN` | クリック音の周波数を減らします | -| `CLICKY_RESET` | `CK_RST` | 周波数をデフォルトに再設定します | -| `MU_ON` | | 音楽モードをオンにします | -| `MU_OFF` | | 音楽モードをオフにします | -| `MU_TOG` | | 音楽モードを切り替えます | -| `MU_MOD` | | 音楽モードを循環します | - - diff --git a/docs/ja/feature_auto_shift.md b/docs/ja/feature_auto_shift.md deleted file mode 100644 index cf67b33977..0000000000 --- a/docs/ja/feature_auto_shift.md +++ /dev/null @@ -1,135 +0,0 @@ -# 自動シフト: なぜシフトキーが必要ですか？ - - - -キーをタップすると、その文字を取得します。キーをタップするが、*わずかに*長く押し続けると、シフト状態になります。ほら！シフトキーは必要ありません！ - -## なぜ自動シフトなのですか？ - -多くの人が腱鞘炎などの症状に苦しんでいます。一般的な原因は、指を繰り返し長い距離を伸ばすことです。私たちはキーボード上でシフトキーに手を伸ばすためにあまりにも頻繁に小指を伸ばします。自動シフトキーはそれを軽減しようとしています。 - -## どのように動作しますか？ - -キーをタップする時に、キーを放す前にほんの短い間押したままにします。この押したままにする時間は全ての人にとって異なる長さです。自動シフトは、定数 `AUTO_SHIFT_TIMEOUT` を定義し、これは普段の押された状態の時間の2倍に通常は設定されます。タイマーは、キーを押す時に開始され、キーを放す時に止まります。押された時間が `AUTO_SHIFT_TIMEOUT` 以上の場合に、キーのシフトバージョンが発行されます。時間が `AUTO_SHIFT_TIMEOUT` 時間よりも短い場合は、通常の状態が発行されます。 - -## 自動シフトには制限がありますか？ - -残念ながらあります。 - -1. キーリピートが動作しなくなります。例えば、20個の 'a' 文字が必要な場合、'a' キーを1、2秒押し続けるかもしれません。オペレーティングシステムに押されたキーの状態を発行する代わりに押された時間を計るので、自動シフトでは動作しません。 -2. シフトをするつもりがない時にシフトされた文字を取得し、シフトしたい時にそうではない他の文字を取得するでしょう。これは結局は練習になります。急いでいる時は、シフトされたバージョンのために十分長くキーを押したと思うかもしれませんが、そうではありませんでした。一方、キーをタップしていると思うかもしれませんが、実際には予想よりも少し長い間押していました。 - -## どうやって自動シフトを有効にしますか？ - -キーマップフォルダの `rules.mk` に追加します: - - AUTO_SHIFT_ENABLE = yes - -`rules.mk` が存在しない場合、それを作成することができます。 - -そして自動シフトキーを有効にした新しいファームウェアをコンパイルしてインストールします！以上です！ - -## モディファイア - -デフォルトで、1つ以上のモディファイアと一緒にキーが押されると自動シフトは無効になります。従って、本当に長い間 Ctrl+A を保持しても、Ctrl+Shift+A と同じではありません。 - -`config.h` に定義を追加することで、モディファイアの自動シフトを再度有効にすることができます - -```c -#define AUTO_SHIFT_MODIFIERS -``` - -この場合、`AUTO_SHIFT_TIMEOUT` を超えて押された Ctrl+A は Ctrl+Shift+A として送信されます - - -## 自動シフトの設定 - -必要に応じて、自動シフトの挙動を変更することができる幾つかの設定があります。キーマップフォルダにある `config.h` に様々な変数を設定することで行われます。`config.h` ファイルが存在しない場合、それを作成することができます。 - -例 - -```c -#pragma once - -#define AUTO_SHIFT_TIMEOUT 150 -#define NO_AUTO_SHIFT_SPECIAL -``` - -### AUTO_SHIFT_TIMEOUT (単位: ミリ秒) - -これは、シフトされた状態を取得するためにどれだけ長くキーを押し続けなければならないかを制御します。 -明らかにこれは人によって異なります。一般的な人にとって、135 から 150 の設定がうまく機能します。ただし、少なくとも 175 の値から開始する必要があります。これはデフォルト値です。その後、ここから下げていきます。間違って検出することなくシフトされた状態を取得するのに必要な、最も短い時間を得るという考え方です。 - -完璧に動作するまで、いろいろな値を試してみます。多くの人は、全てが所定の値で適切に動作するものの、時々、1つあるいは2つのキーがシフト状態を発行することが分かるでしょう。これは単に習慣と、幾つかのキーを他のキーよりも少し長く押し続けることによるものです。この値を見つけたら、問題のキーを通常よりも少し早くタップするとともに、その値を設定します。 - -?> 自動シフトには、この値を素早く取得するのに役立つ3つの特別なキーがあります。詳細は「自動シフトのセットアップ」を見てください！ - -### NO_AUTO_SHIFT_SPECIAL (単純にこのように定義します) - --\_, =+, [{, ]}, ;:, '", ,<, .> および /? を含む特殊キーを自動シフトしません - -### NO_AUTO_SHIFT_NUMERIC (単純にこのように定義します) - -0から9までの数字キーを自動シフトしません。 - -### NO_AUTO_SHIFT_ALPHA (単純にこのように定義します) - -AからZを含むアルファベット文字を自動シフトしません。 - -## 自動シフトセットアップの使用 - -これにより、`AUTO_SHIFT_TIMEOUT` で設定している時間を一時的に増減させたり報告するために、3つのキーを定義することができます。 - -### セットアップ - -3つのキーを一時的にキーマップにマップします: - -| キー名 | 説明 | -|----------|-----------------------------------------------------| -| KC_ASDN | 自動シフトタイムアウト変数を下げる | -| KC_ASUP | 自動シフトタイムアウト変数を上げる | -| KC_ASRP | 現在の自動シフトタイムアウト値を報告する | -| KC_ASON | 自動シフト機能をオンにする | -| KC_ASOFF | 自動シフト機能をオフにする | -| KC_ASTG | 自動シフト機能の状態を切り替える | - -新しいファームウェアをコンパイルしてアップロードします。 - -### 使い方 - -これらのテスト中は、完全に普段通り入力する必要があり、意図的にシフトされたキーを使わずに入力するように注意する必要があります。 - -1. アルファベットの複数の文を入力します。 -2. 大文字に注意してください。 -3. 大文字が存在しない場合は、自動シフトタイムアウト値を減らすために `KC_ASDN` にマップしたキーを押し、ステップ1に戻ります。 -4. 大文字が幾つかある場合は、押す時間を短くしてこれらのキーをタップする必要があるか、あるいはタイムアウトを増やす必要があるかを決定します。 -5. タイムアウトを増やすことに決めた場合は、`KC_ASUP` にマップしたキーを押し、ステップ1に戻ります。 -6. 結果に満足したら、`KC_ASRP` にマップしたキーを押します。キーボードは `AUTO_SHIFT_TIMEOUT` の値を自動的に入力します。 -7. 報告された値で `config.h` の `AUTO_SHIFT_TIMEOUT` を更新します。 -8. `config.h` に `AUTO_SHIFT_NO_SETUP` を追加します。 -9. `KC_ASDN`、`KC_ASUP` および `KC_ASRP` のキーバインディングを削除します。 -10. 新しいファームウェアをコンパイルしてアップロードします。 - -#### 実行例 - - hello world. my name is john doe. i am a computer programmer playing with - keyboards right now. - - [KC_ASDN を何度か押します] - - heLLo woRLd. mY nAMe is JOHn dOE. i AM A compUTeR proGRaMMER PlAYiNG witH - KEYboArDS RiGHT NOw. - - [KC_ASUP を数回押します] - - hello world. my name is john Doe. i am a computer programmer playing with - keyboarDs right now. - - [KC_ASRPを押します] - - 115 - -キーボードは現在の `AUTO_SHIFT_TIMEOUT` 値を表す `115` を入力しました。これで設定が完了しました！テスト中に現れる *D* キーを少し練習してください。それで完璧です。 diff --git a/docs/ja/feature_backlight.md b/docs/ja/feature_backlight.md deleted file mode 100644 index 150069607c..0000000000 --- a/docs/ja/feature_backlight.md +++ /dev/null @@ -1,225 +0,0 @@ -# バックライト :id=backlighting - - - -多くのキーボードは、キースイッチを貫通して配置されたり、キースイッチの下に配置された個々の LED によって、バックライトキーをサポートします。この機能は通常スイッチごとに単一の色しか使用できないため、[RGB アンダーグロー](ja/feature_rgblight.md)および [RGB マトリックス](ja/feature_rgb_matrix.md)機能のどちらとも異なりますが、キーボードに複数の異なる単一色の LED を取り付けることは当然可能です。 - -QMK は *パルス幅変調* (*Pulse Width Modulation*) すなわち PWM として知られている技術で、一定の比率で素早くオンおよびオフを切り替えることで、これらの LED の輝度を制御できます。PWM 信号のデューティサイクルを変えることで、調光の錯覚を起こすことができます。 - -MCU は、GPIO ピンにはそんなに電流を供給できません。MCU から直接バックライトに給電せずに、バックライトピンは LED への電力を切り替えるトランジスタあるいは MOSFET に接続されます。 - -ほとんどのキーボードではバックライトをサポートしている場合にデフォルトで有効になっていますが、もし機能しない場合は `rules.mk` が以下を含んでいることを確認してください: - -```makefile -BACKLIGHT_ENABLE = yes -``` - -## キーコード :id=keycodes - -有効にすると、以下のキーコードを使ってバックライトレベルを変更することができます。 - -| キー | 説明 | -| --------- | ------------------------------------ | -| `BL_TOGG` | バックライトをオンあるいはオフにする | -| `BL_STEP` | バックライトレベルを循環する | -| `BL_ON` | バックライトを最大輝度に設定する | -| `BL_OFF` | バックライトをオフにする | -| `BL_INC` | バックライトレベルを上げる | -| `BL_DEC` | バックライトレベルを下げる | -| `BL_BRTG` | バックライトの明滅動作を切り替える | - -## 関数群 :id=functions - -次の関数を使って、カスタムコードでバックライトを変更することができます: - -| 関数 | 説明 | -| ------------------------ | -------------------------------------------- | -| `backlight_toggle()` | バックライトをオンあるいはオフにする | -| `backlight_enable()` | バックライトをオンにする | -| `backlight_disable()` | バックライトをオフにする | -| `backlight_step()` | バックライトレベルを循環する | -| `backlight_increase()` | バックライトレベルを上げる | -| `backlight_decrease()` | バックライトレベルを下げる | -| `backlight_level(x)` | バックライトのレベルを特定のレベルに設定する | -| `get_backlight_level()` | 現在のバックライトレベルを返す | -| `is_backlight_enabled()` | バックライトが現在オンかどうかを返す | - -バックライトの明滅が有効の場合(以下を参照)、以下の関数も利用できます: - -| 関数 | 説明 | -|-----------------------|----------------------------------------------| -| `breathing_toggle()` | バックライトの明滅動作をオンまたはオフにする | -| `breathing_enable()` | バックライトの明滅動作をオンにする | -| `breathing_disable()` | バックライトの明滅動作をオフにする | - -## 設定 :id=configuration - -どのドライバを使うかを選択するには、以下を使って `rules.mk` を設定します: - -```makefile -BACKLIGHT_DRIVER = software -``` - -有効なドライバの値は `pwm`, `software`, `custom`, `no` です。各ドライバについてのヘルプは以下を見てください。 - -バックライトを設定するには、`config.h` の中で以下の `#define` をします: - -| 定義 | デフォルト | 説明 | -| ----------------------------- | ------------------ | --------------------------------------------------------------------------------------------- | -| `BACKLIGHT_PIN` | *定義なし* | LED を制御するピン | -| `BACKLIGHT_LEVELS` | `3` | 輝度のレベルの数 (オフを除いて最大 31) | -| `BACKLIGHT_CAPS_LOCK` | *定義なし* | バックライトを使って Caps Lock のインジケータを有効にする (専用 LED の無いキーボードのため) | -| `BACKLIGHT_BREATHING` | *定義なし* | サポートされる場合は、バックライトの明滅動作を有効にする | -| `BREATHING_PERIOD` | `6` | 各バックライトの "明滅" の長さ（秒） | -| `BACKLIGHT_ON_STATE` | `1` | バックライトが "オン" の時のバックライトピンの状態 - high の場合は `1`、low の場合は `0` | -| `BACKLIGHT_LIMIT_VAL` | `255` | バックライトの最大デューティサイクル -- `255` で最大輝度になり、それ未満では最大値が減少する | -| `BACKLIGHT_DEFAULT_LEVEL` | `BACKLIGHT_LEVELS` | EEPROM をクリアする時に使うデフォルトのバックライトレベル | -| `BACKLIGHT_DEFAULT_BREATHING` | *定義なし* | EEPROM をクリアする時に、バックライトのブリージングを有効にするかどうか | - -独自のキーボードを設計しているわけではない限り、通常は `BACKLIGHT_PIN` または `BACKLIGHT_ON_STATE` を変更する必要はありません。 - -### バックライトオン状態 :id=backlight-on-state - -ほとんどのバックライトの回路は N チャンネルの MOSFET あるいは NPN トランジスタによって駆動されます。これは、トランジスタを *オン* にして LED を点灯させるには、ゲートまたはベースに接続されているバックライトピンを *high* に駆動する必要があることを意味します。 -ただし、P チャンネルの MOSFET あるいは PNP トランジスタが使われる場合があります。この場合、トランジスタがオンの時、ピンは代わりに *low* で駆動されます。 - -この機能は `BACKLIGHT_ON_STATE` を定義することでキーボードレベルで設定されます。 - -### AVR ドライバ :id=avr-driver - -`pwm` ドライバはデフォルトで設定されますが、`rules.mk` 内での同等の設定は以下の通りです: - -```makefile -BACKLIGHT_DRIVER = pwm -``` - -#### 注意事項 :id=avr-caveats - -AVR ボードでは、QMK はどのドライバを使うかを以下の表に従って自動的に決定します: - -| バックライトピン | AT90USB64/128 | AT90USB162 | ATmega16/32U4 | ATmega16/32U2 | ATmega32A | ATmega328/P | -| ---------------- | ------------- | ---------- | ------------- | ------------- | --------- | ----------- | -| `B1` | | | | | | Timer 1 | -| `B2` | | | | | | Timer 1 | -| `B5` | Timer 1 | | Timer 1 | | | | -| `B6` | Timer 1 | | Timer 1 | | | | -| `B7` | Timer 1 | Timer 1 | Timer 1 | Timer 1 | | | -| `C4` | Timer 3 | | | | | | -| `C5` | Timer 3 | Timer 1 | | Timer 1 | | | -| `C6` | Timer 3 | Timer 1 | Timer 3 | Timer 1 | | | -| `D4` | | | | | Timer 1 | | -| `D5` | | | | | Timer 1 | | - -他の全てのピンはタイマー支援ソフトウェア PWM を使います。 - -| オーディオピン | オーディオタイマ | ソフトウェア PWM タイマ | -| -------------- | ---------------- | ----------------------- | -| `C4` | Timer 3 | Timer 1 | -| `C5` | Timer 3 | Timer 1 | -| `C6` | Timer 3 | Timer 1 | -| `B5` | Timer 1 | Timer 3 | -| `B6` | Timer 1 | Timer 3 | -| `B7` | Timer 1 | Timer 3 | - -両方のタイマーがオーディオのために使われている場合、バックライト PWM はハードウェアタイマを使うことができず、代わりにマトリックススキャンの間に引き起こされます。この場合、PWM の計算は十分なタイミングの精度で呼ばれない可能性があるため、バックライトの明滅はサポートされず、バックライトもちらつくかもしれません。 - -#### ハードウェア PWM 実装 :id=hardware-pwm-implementation - -バックライト用にサポートされているピンを使う場合、QMK は PWM 信号を出力するように設定されたハードウェアタイマを使います。タイマーは 0 にリセットする前に `ICRx` (デフォルトでは `0xFFFF`) までカウントします。 -希望の輝度が計算され、`OCRxx` レジスタに格納されます。カウンタがこの値まで達すると、バックライトピンは low になり、カウンタがリセットされると再び high になります。 -このように `OCRxx` は基本的に LED のデューティサイクル、従って輝度を制御します。`0x0000` は完全にオフで、 `0xFFFF` は完全にオンです。 - -明滅動作の効果はカウンタがリセットされる(秒間あたりおよそ244回)たびに呼び出される `TIMER1_OVF_vect` の割り込みハンドラを登録することで可能になります。 -このハンドラで、増分カウンタの値が事前に計算された輝度曲線にマップされます。明滅動作をオフにするには、割り込みを単純に禁止し、輝度を EEPROM に格納されているレベルに再設定します。 - -#### タイマー支援 PWM 実装 :id=timer-assisted-implementation - -`BACKLIGHT_PIN` がハードウェアバックライトピンに設定されていない場合、QMK はソフトウェア割り込みを引き起こすように設定されているハードウェアタイマを使います。タイマーは 0 にリセットする前に `ICRx` (デフォルトでは `0xFFFF`) までカウントします。 -0 に再設定すると、CPU は LED をオンにする OVF (オーバーフロー)割り込みを発火し、デューティサイクルを開始します。 -希望の輝度が計算され、`OCRxx` レジスタに格納されます。カウンタがこの値に達すると、CPU は比較出力一致割り込みを発火し、LED をオフにします。 -このように `OCRxx` は基本的に LED のデューティサイクル、従って輝度を制御します。 `0x0000` は完全にオフで、 `0xFFFF` は完全にオンです。 - -明滅の効果はハードウェア PWM 実装と同じです。 - -### ARM ドライバ :id=arm-configuration - -まだ初期段階ですが、ARM バックライトサポートは最終的に AVR と同等の機能を持つことを目指しています。`pwm` ドライバはデフォルトで設定されますが、`rules.mk` 内での同等の設定は以下の通りです: - -```makefile -BACKLIGHT_DRIVER = pwm -``` - -#### ChibiOS の設定 :id=arm-configuration - -以下の `#define` は ARM ベースのキーボードにのみ適用されます: - -| 定義 | デフォルト | 説明 | -| ----------------------- | ---------- | ----------------------- | -| `BACKLIGHT_PWM_DRIVER` | `PWMD4` | 使用する PWM ドライバ | -| `BACKLIGHT_PWM_CHANNEL` | `3` | 使用する PWM チャンネル | -| `BACKLIGHT_PAL_MODE` | `2` | 使用するピン代替関数 | - -これらの値を決定するには、特定の MCU の ST データシートを参照してください。独自のキーボードを設計しているわけではない場合、通常はこれらを変更する必要はありません。 - -#### 注意事項 :id=arm-caveats - -現在のところ、ハードウェア PWM のみがサポートされ、タイマー支援はなく、自動設定は提供されません。 - -### ソフトウェア PWM ドライバ :id=software-pwm-driver - -このモードでは、他のキーボードのタスクを実行中に PWM は「エミュレート」されます。追加のプラットフォーム設定なしで最大のハードウェア互換性を提供します。トレードオフは、キーボードが忙しい時にバックライトが揺れる可能性があることです。有効にするには、`rules.mk` に以下を追加します: - -```makefile -BACKLIGHT_DRIVER = software -``` - -#### 複数のバックライトピン :id=multiple-backlight-pins - -ほとんどのキーボードは、全てのバックライト LED を制御するたった1つのバックライトピンを持ちます (特にバックライトがハードウェア PWM ピンに接続されている場合)。 -ソフトウェア PWM では、複数のバックライトピンを定義することができます。これらのピンは PWM デューティサイクル時に同時にオンおよびオフになります。 - -この機能により、例えば Caps Lock LED (またはその他の制御可能な LED) の輝度を、バックライトの他の LED と同じレベルに設定することができます。Caps Lock LED は通常バックライトとは別のピンに配線されるため、Caps Lock の代わりに Control をマップしていて、Caps Lock がオンの時に Caps Lock LED ではなくバックライトの一部をアクティブにする必要がある場合に便利です。 - -複数のバックライトピンをアクティブにするには、`config.h` に `BACKLIGHT_PIN` の代わりに次のようなものを追加します: - -```c -#define BACKLIGHT_PINS { F5, B2 } -``` - -### カスタムドライバ :id=custom-driver - -上記ドライバのいずれもキーボードに適用されていない場合(例えば、バックライトを制御するのに別の IC を使用している場合)、QMK が提供しているこの簡単な API を使ってカスタムバックライトドライバを実装することができます。有効にするには、`rules.mk` に以下を追加します: - -```makefile -BACKLIGHT_DRIVER = custom -``` - -それから次のフックのいずれかを実装します: - -```c -void backlight_init_ports(void) { - // オプション - 起動時に実行されます - // 通常、ここでピンを設定します -} -void backlight_set(uint8_t level) { - // オプション - レベルの変更時に実行されます - // 通常、ここで新しい値に応答します -} - -void backlight_task(void) { - // オプション - 定期的に実行されます - // これはメインキーボードループで呼び出されることに注意してください - // そのため、ここで長時間実行されるアクションはパフォーマンスの問題を引き起こします -} -``` - -## 回路図の例 - -この一般的な例では、バックライト LED は全て N チャンネル MOSFET に向かって並列に接続されています。そのゲートピンは、リンギングを回避するため 470Ωの抵抗を介してマイクロコントローラの GPIO ピンの1つに接続されています。 -プルダウン抵抗もゲートピンとグランドの間に配置されており、MCU によって駆動されていない場合にプルダウン抵抗を定義された状態に保ちます。 -これらの抵抗値は重要ではありません。詳細については、[this Electronics StackExchange question](https://electronics.stackexchange.com/q/68748) を参照してください。 - -![バックライトの回路例](https://i.imgur.com/BmAvoUC.png) diff --git a/docs/ja/feature_bluetooth.md b/docs/ja/feature_bluetooth.md deleted file mode 100644 index 3c71a18ec1..0000000000 --- a/docs/ja/feature_bluetooth.md +++ /dev/null @@ -1,49 +0,0 @@ -# Bluetooth - - - -## Bluetooth の既知のサポートハードウェア - -現在のところ Bluetooth のサポートは AVR ベースのチップに限られます。Bluetooth 2.1 については、QMK は RN-42 モジュールをサポートします。より最近の BLE プロトコルについては、現在のところ Adafruit Bluefruit SPI Friend のみが直接サポートされています。iOS デバイスに接続するには、BLE が必要です。iOS はマウス入力をサポートしないことに注意してください。 - -| ボード | Bluetooth プロトコル | 接続タイプ | rules.mk | Bluetooth チップ | -| ---------------------------------------------------------------- | -------------------- | ---------- | ------------------------- | ---------------- | -| Roving Networks RN-42 (Sparkfun Bluesmirf) | Bluetooth Classic | UART | `BLUETOOTH = RN42` | RN-42 | -| [Bluefruit LE SPI Friend](https://www.adafruit.com/product/2633) | Bluetooth Low Energy | SPI | `BLUETOOTH = AdafruitBLE` | nRF51822 | - -まだサポートされていませんが、可能性のあるもの: -* [Bluefruit LE UART Friend](https://www.adafruit.com/product/2479)。[tmk 実装がおそらく見つかります](https://github.com/tmk/tmk_keyboard/issues/514) -* RN-42 ファームウェアが書き込まれた HC-05 ボード。どちらも明らかに CSR BC417 チップを使っています。RN-42 ファームウェアを使って書き込むと、HID 機能が提供されます。 -* Sparkfun Bluetooth Mate -* HM-13 ベースのボード - -### Adafruit BLE SPI Friend -現在のところ QMK によってサポートされている唯一の bluetooth チップセットは、Adafruit Bluefruit SPI Friend です。Adafruit のカスタムファームウェアを実行する Nordic nRF5182 ベースのチップです。データは Hardware SPI を介した Adafruit の SDEP を使って転送されます。[Feather 32u4 Bluefruit LE](https://www.adafruit.com/product/2829) は Adafruit ファームウェアを搭載した Nordic BLE チップに SPI 経由で接続された AVR mcu であるため、サポートされます。SPI friend を使ってカスタムボードを構築する場合、32u4 feather が使用するピン選択を使うのが最も簡単ですが、以下の定義で config.h オプションでピンを変更することができます: -* #define AdafruitBleResetPin D4 -* #define AdafruitBleCSPin B4 -* #define AdafruitBleIRQPin E6 - -Bluefruit UART friend は SPI friend に変換することができますが、これにはMDBT40 チップへの直接の再書き込みとはんだ付けが[必要です](https://github.com/qmk/qmk_firmware/issues/2274)。 - - -## Bluetooth の Rules.mk オプション - -現在サポートされている Bluetooth チップセットは [N-キーロールオーバー (NKRO)](ja/reference_glossary.md#n-key-rollover-nkro) をサポートしていません。そのため、`rules.mk` に `NKRO_ENABLE = no` を含めなければなりません。 - -Bluetooth を有効にするには、以下のうちの1つだけを使ってください: -* BLUETOOTH_ENABLE = yes (レガシーオプション) -* BLUETOOTH = RN42 -* BLUETOOTH = AdafruitBLE - -## Bluetooth キーコード - -これは複数のキーボードの出力が選択できる場合に使われます。現在のところ、これは USB と Bluetooth の両方をサポートするキーボードで、それらの間の切り替えのみが可能です。 - -| 名前 | 説明 | -| ---------- | ------------------------------------- | -| `OUT_AUTO` | USB と Bluetooth を自動的に切り替える | -| `OUT_USB` | USB のみ | -| `OUT_BT` | Bluetooth のみ | diff --git a/docs/ja/feature_bootmagic.md b/docs/ja/feature_bootmagic.md deleted file mode 100644 index c146176a7e..0000000000 --- a/docs/ja/feature_bootmagic.md +++ /dev/null @@ -1,182 +0,0 @@ -# ブートマジック - - - -再書き込みせずにキーボードの挙動を変更することができる、3つの独立した関連する機能があります。それぞれは似たような機能を持ちますが、キーボードがどのように設定されているかによって異なる方法でアクセスされます。 - -**ブートマジック**は初期化の間にキーボードを設定するためのシステムです。ブートマジックコマンドを起動するには、ブートマジックキーと1つ以上のコマンドキーを押し続けます。 - -**ブートマジックキーコード** は前に `MAGIC_` が付いており、キーボードが初期化された*後で*ブートマジックの機能にアクセスすることができます。キーコードを使うには、他のキーコードと同じようにそれらをキーマップに割り当てます。 - -以前は**マジック**として知られていた**コマンド**は、キーボードの異なる側面を制御することができる別の機能です。ブートマジックと一部の機能を共有しますが、コンソールにバージョン情報を出力するような、ブートマジックにはできないこともできます。詳細は、[コマンド](ja/feature_command.md)を見てください。 - -一部のキーボードでは、ブートマジックはデフォルトで無効になっています。その場合、`rules.mk` 内で以下のように明示的に有効にする必要があります: - -```make -BOOTMAGIC_ENABLE = yes -``` - -?> `full` の代わりに `yes` が使われていることがあるかもしれませんが、これは問題ありません。ただし、`yes` は非推奨で、理想的には `full` (あるいは`lite`) が使われるべきです。 - -さらに、以下を `rules.mk` ファイルに追加することで、[ブートマジックライト](#bootmagic-lite) (スケールダウンした、とても基本的なバージョンのブートマジック)を使うことができます: - -```make -BOOTMAGIC_ENABLE = lite -``` - -## ホットキー - -キーボードを接続しながら、ブートマジックキー(デフォルトはスペース)と目的のホットキーを押します。例えば、スペースと `B` を押したままにすると、ブートローダに入ります。 - -| ホットキー | 説明 | -|------------------|---------------------------------------------| -| エスケープ | EEPROM のブートマジック設定を無視する | -| `B` | ブートローダに入る | -| `D` | シリアルを介するデバッグ出力の切り替え | -| `X` | キーマトリックスのデバッグ出力の切り替え | -| `K` | キーボードのデバッグの切り替え | -| `M` | マウスのデバッグの切り替え | -| `L` | EE_HANDS 左右設定に、"左手"を設定 | -| `R` | EE_HANDS 左右設定に、"右手"を設定 | -| Backspace | EEPROM をクリア | -| Caps Lock | Caps Lock を左コントロールとして扱うかを切り替え | -| 左 Control | Caps Lock と左コントロールの入れ替えを切り替え | -| 左 Alt | 左 Alt と左 GUI の入れ替えを切り替え | -| 右 Alt | 右 Alt と右 GUI の入れ替えを切り替え | -| 左 GUI | GUI キーの有効・無効を切り替え (ゲームの時に便利です) | -| ` | ` とエスケープの入れ替えを切り替え | -| `\` | `\` とバックスペースの入れ替えを切り替え | -| `N` | N キーロールオーバー (NKRO) の有効・無効を切り替え | -| `0` | レイヤー 0 をデフォルトレイヤーにする | -| `1` | レイヤー 1 をデフォルトレイヤーにする | -| `2` | レイヤー 2 をデフォルトレイヤーにする | -| `3` | レイヤー 3 をデフォルトレイヤーにする | -| `4` | レイヤー 4 をデフォルトレイヤーにする | -| `5` | レイヤー 5 をデフォルトレイヤーにする | -| `6` | レイヤー 6 をデフォルトレイヤーにする | -| `7` | レイヤー 7 をデフォルトレイヤーにする | - -## キーコード :id=keycodes - -| キー | エイリアス | 説明 | -|----------------------------------|---------|--------------------------------------------------------------------------| -| `MAGIC_SWAP_CONTROL_CAPSLOCK` | `CL_SWAP` | Caps Lock と左コントロールの入れ替え | -| `MAGIC_UNSWAP_CONTROL_CAPSLOCK` | `CL_NORM` | Caps Lock と左コントロールの入れ替えの解除 | -| `MAGIC_CAPSLOCK_TO_CONTROL` | `CL_CTRL` | Caps Lock をコントロールとして扱う | -| `MAGIC_UNCAPSLOCK_TO_CONTROL` | `CL_CAPS` | Caps Lock をコントロールとして扱うことを止める | -| `MAGIC_SWAP_LCTL_LGUI` | `LCG_SWP` | 左コントロールと GUI の入れ替え | -| `MAGIC_UNSWAP_LCTL_LGUI` | `LCG_NRM` | 左コントロールと GUI の入れ替えを解除 | -| `MAGIC_SWAP_RCTL_RGUI` | `RCG_SWP` | 右コントロールと GUI の入れ替え | -| `MAGIC_UNSWAP_RCTL_RGUI` | `RCG_NRM` | 右コントロールと GUI の入れ替えを解除 | -| `MAGIC_SWAP_CTL_GUI` | `CG_SWAP` | 両側のコントロールと GUI の入れ替え | -| `MAGIC_UNSWAP_CTL_GUI` | `CG_NORM` | 両側のコントロールと GUI の入れ替えを解除 | -| `MAGIC_TOGGLE_CTL_GUI` | `CG_TOGG` | 両側のコントロールと GUI の入れ替えの切り替え | -| `MAGIC_SWAP_LALT_LGUI` | `LAG_SWP` | 左 Alt と GUI の入れ替え | -| `MAGIC_UNSWAP_LALT_LGUI` | `LAG_NRM` | 左 Alt と GUI の入れ替えを解除 | -| `MAGIC_SWAP_RALT_RGUI` | `RAG_SWP` | 右 Alt と GUI の入れ替え | -| `MAGIC_UNSWAP_RALT_RGUI` | `RAG_NRM` | 右 Alt と GUI の入れ替えを解除 | -| `MAGIC_SWAP_ALT_GUI` | `AG_SWAP` | 両側の Alt と GUI の入れ替え | -| `MAGIC_UNSWAP_ALT_GUI` | `AG_NORM` | 両側の Alt と GUI の入れ替えを解除 | -| `MAGIC_TOGGLE_ALT_GUI` | `AG_TOGG` | 両側の Alt と GUI の入れ替えの切り替え | -| `MAGIC_NO_GUI` | `GUI_OFF` | GUI キーを無効にする | -| `MAGIC_UNNO_GUI` | `GUI_ON` | GUI キーを有効にする | -| `MAGIC_SWAP_GRAVE_ESC` | `GE_SWAP` | ` とエスケープの入れ替え | -| `MAGIC_UNSWAP_GRAVE_ESC` | `GE_NORM` | ` とエスケープの入れ替えを解除 | -| `MAGIC_SWAP_BACKSLASH_BACKSPACE` | `BS_SWAP` | `\` とバックスペースを入れ替え | -| `MAGIC_UNSWAP_BACKSLASH_BACKSPACE` | `BS_NORM` | `\` とバックスペースの入れ替えを解除する | -| `MAGIC_HOST_NKRO` | `NK_ON` | N キーロールオーバーを有効にする | -| `MAGIC_UNHOST_NKRO` | `NK_OFF` | N キーロールオーバーを無効にする | -| `MAGIC_TOGGLE_NKRO` | `NK_TOGG` | N キーロールオーバーの有効・無効を切り替え | -| `MAGIC_EE_HANDS_LEFT` | `EH_LEFT` | 分割キーボードのマスター側を左手に設定(`EE_HANDS` 用) | -| `MAGIC_EE_HANDS_RIGHT` | `EH_RGHT` | 分割キーボードのマスター側を右手に設定(`EE_HANDS` 用) | - -## 設定 - -ブートマジックのためのホットキーの割り当てを変更したい場合は、キーボードあるいはキーマップレベルのどちらかで、`config.h` にこれらを `#define` します。 - -| 定義 | デフォルト | 説明 | -|----------------------------------------|-------------|---------------------------------------------------| -| `BOOTMAGIC_KEY_SALT` | `KC_SPACE` | ブートマジックキー | -| `BOOTMAGIC_KEY_SKIP` | `KC_ESC` | EEPROM のブートマジック設定を無視する | -| `BOOTMAGIC_KEY_EEPROM_CLEAR` | `KC_BSPACE` | EEPROM 設定をクリアする | -| `BOOTMAGIC_KEY_BOOTLOADER` | `KC_B` | ブートローダに入る | -| `BOOTMAGIC_KEY_DEBUG_ENABLE` | `KC_D` | シリアルを介するデバッグ出力の切り替え | -| `BOOTMAGIC_KEY_DEBUG_MATRIX` | `KC_X` | マトリックスのデバッグを切り替え | -| `BOOTMAGIC_KEY_DEBUG_KEYBOARD` | `KC_K` | キーボードのデバッグの切り替え | -| `BOOTMAGIC_KEY_DEBUG_MOUSE` | `KC_M` | マウスのデバッグの切り替え | -| `BOOTMAGIC_KEY_EE_HANDS_LEFT` | `KC_L` | EE_HANDS 左右設定に、"左手"を設定 | -| `BOOTMAGIC_KEY_EE_HANDS_RIGHT` | `KC_R` | EE_HANDS 左右設定に、"右手"を設定 | -| `BOOTMAGIC_KEY_SWAP_CONTROL_CAPSLOCK` | `KC_LCTRL` | 左コントロールと Caps Lock の入れ替え | -| `BOOTMAGIC_KEY_CAPSLOCK_TO_CONTROL` | `KC_CAPSLOCK` | Caps Lock を左コントロールとして扱うかを切り替え | -| `BOOTMAGIC_KEY_SWAP_LALT_LGUI` | `KC_LALT` | 左 Alt と左 GUI の入れ替えを切り替え (macOS 用) | -| `BOOTMAGIC_KEY_SWAP_RALT_RGUI` | `KC_RALT` | 右 Alt と右 GUI の入れ替えを切り替え (macOS 用) | -| `BOOTMAGIC_KEY_NO_GUI` | `KC_LGUI` | GUI キーの有効・無効を切り替え (ゲームの時に便利です) | -| `BOOTMAGIC_KEY_SWAP_GRAVE_ESC` | `KC_GRAVE` | ` とエスケープの入れ替えを切り替え | -| `BOOTMAGIC_KEY_SWAP_BACKSLASH_BACKSPACE` | `KC_BSLASH` | `\` とバックスペースの入れ替えを切り替え | -| `BOOTMAGIC_HOST_NKRO` | `KC_N` | N キーロールオーバー (NKRO) の有効・無効を切り替え | -| `BOOTMAGIC_KEY_DEFAULT_LAYER_0` | `KC_0` | レイヤー 0 をデフォルトレイヤーにする | -| `BOOTMAGIC_KEY_DEFAULT_LAYER_1` | `KC_1` | レイヤー 1 をデフォルトレイヤーにする | -| `BOOTMAGIC_KEY_DEFAULT_LAYER_2` | `KC_2` | レイヤー 2 をデフォルトレイヤーにする | -| `BOOTMAGIC_KEY_DEFAULT_LAYER_3` | `KC_3` | レイヤー 3 をデフォルトレイヤーにする | -| `BOOTMAGIC_KEY_DEFAULT_LAYER_4` | `KC_4` | レイヤー 4 をデフォルトレイヤーにする | -| `BOOTMAGIC_KEY_DEFAULT_LAYER_5` | `KC_5` | レイヤー 5 をデフォルトレイヤーにする | -| `BOOTMAGIC_KEY_DEFAULT_LAYER_6` | `KC_6` | レイヤー 6 をデフォルトレイヤーにする | -| `BOOTMAGIC_KEY_DEFAULT_LAYER_7` | `KC_7` | レイヤー 7 をデフォルトレイヤーにする | - -# ブートマジックライト :id=bootmagic-lite - -本格的なブートマジック機能の他に、ブートローダへのジャンプのみを処理するブートマジックライトがあります。これは、物理的なリセットボタンが無くブートローダにジャンプする方法が必要だが、ブートマジックが引き起こす問題を扱いたくないキーボードに適しています。 - -ブートマジックのこのバージョンを有効にするには、以下を使って `rules.mk` で有効にする必要があります: - -```make -BOOTMAGIC_ENABLE = lite -``` - -さらに、どのキーを使うかを指定したほうが良いかもしれません。これは普通ではないマトリックスを持つキーボードで特に便利です。そのためには、使いたいキーの行と列を指定する必要があります。`config.h` ファイルにこれらのエントリを追加します: - -```c -#define BOOTMAGIC_ROW 0 -#define BOOTMAGIC_COLUMN 1 -``` - -デフォルトでは、これらは 0 と 0 に設定されます。これは通常はほとんどのキーボードで "ESC" キーです。 - -ブートローダを起動するには、キーボードを接続する時にこのキーを押し続けます。たった1つのキーです。 - -!> ブートマジックライトを使用すると、EEPROM を**常にリセットします**。つまり保存された全ての設定は失われます。 - -## 分割キーボード - -`SPLIT_HAND_PIN` のようなオプションで、左右の設定があらかじめ決められている場合は、キーボードの左右で別のキーを設定する必要があるかもしれません。これを行うには、`config.h` ファイルに以下のエントリを追加します。 - -```c -#define BOOTMAGIC_ROW_RIGHT 4 -#define BOOTMAGIC_COLUMN_RIGHT 1 -``` - -デフォルトでは、これらの値は設定されていません。 - -## 高度なブートマジックライト - -`bootmagic_lite` 関数は必要に応じてコード内で置き換えることができるように、弱く定義されています。これの良い例は Zeal60 キーボードで、追加の処理が必要です。 - -関数を置き換えるには、以下のようなものをコードに追加するだけです: - -```c -void bootmagic_lite(void) { - matrix_scan(); - wait_ms(DEBOUNCE * 2); - matrix_scan(); - - if (matrix_get_row(BOOTMAGIC_ROW) & (1 << BOOTMAGIC_COLUMN)) { - // ブートローダにジャンプする。 - bootloader_jump(); - } -} -``` - -追加の機能をここに追加することができます。例えば、eeprom のリセットやブートマジックを起動するために押す必要がある追加のキーです。`bootmagic_lite` はファームウェア内で大部分の機能が初期化される前に呼ばれることに注意してください。 diff --git a/docs/ja/feature_combo.md b/docs/ja/feature_combo.md deleted file mode 100644 index 0c0591e5f7..0000000000 --- a/docs/ja/feature_combo.md +++ /dev/null @@ -1,108 +0,0 @@ -# コンボ - - - -コンボ機能は、同時押し方式でのカスタムアクション追加機能です。同時に複数のキーを押して、異なる効果を生み出すことができます。例えば、タッピング時間内で `A` と `S` を押すと、代わりに `ESC` が押されます。もっと複雑なタスクを実行させることもできます。 - -この機能を有効にするには、`rules.mk` に `COMBO_ENABLE = yes` を追加する必要があります。 - -さらに、使用するコンボの数を `config.h` の中で、`#define COMBO_COUNT 1` (1を使用するコンボの数で置き換えます)と書いて、指定する必要があります。 - - -また、デフォルトでは、コンボのタッピング時間は `TAPPING_TERM` と同じ値に設定されます (ほとんどのキーボードではデフォルトで 200)。ただし、`config.h` で定義することにより異なる値を指定することができます。例えば: `#define COMBO_TERM 300` はコンボのためのタイムアウト時間を 300ms に設定します。 - -次に、`keymap.c` ファイルに、`COMBO_END` で終了するキーのシーケンス、およびキーの組み合わせを列挙する構造体、その結果のアクションを定義する必要があります。 - -```c -const uint16_t PROGMEM test_combo[] = {KC_A, KC_B, COMBO_END}; -combo_t key_combos[] = {COMBO(test_combo, KC_ESC)}; -``` - -これは、A と B のキーを押した場合に、"Escape" を送信します。 - -!> このメソッドは[基本的なキーコード](ja/keycodes_basic.md)のみをサポートします。詳細な制御については例を見てください。 - -## 例 - -リストを追加したい場合は、以下のようなものを使います: - -```c -enum combos { - AB_ESC, - JK_TAB -}; - -const uint16_t PROGMEM ab_combo[] = {KC_A, KC_B, COMBO_END}; -const uint16_t PROGMEM jk_combo[] = {KC_J, KC_K, COMBO_END}; - -combo_t key_combos[] = { - [AB_ESC] = COMBO(ab_combo, KC_ESC), - [JK_TAB] = COMBO(jk_combo, KC_TAB) -}; -``` - -より複雑な実装として、カスタム処理を追加するために `process_combo_event` 関数を使うことができます。 - -```c -enum combo_events { - ZC_COPY, - XV_PASTE -}; - -const uint16_t PROGMEM copy_combo[] = {KC_Z, KC_C, COMBO_END}; -const uint16_t PROGMEM paste_combo[] = {KC_X, KC_V, COMBO_END}; - -combo_t key_combos[] = { - [ZC_COPY] = COMBO_ACTION(copy_combo), - [XV_PASTE] = COMBO_ACTION(paste_combo), -}; - -void process_combo_event(uint16_t combo_index, bool pressed) { - switch(combo_index) { - case ZC_COPY: - if (pressed) { - tap_code16(LCTL(KC_C)); - } - break; - case XV_PASTE: - if (pressed) { - tap_code16(LCTL(KC_V)); - } - break; - } -} -``` - -これは、Z と C を押すと Ctrl+C を送信し、X と V を押すと Ctrl+V を送信します。これを変更して、レイヤーの変更、サウンドの再生、設定の変更などを行うこともできます。 - -## 追加の設定 - -長いコンボあるいはさらに長いコンボを使っている場合、構造体があなたのしていることに対応するのに十分な大きさで無いかもしれないため、問題が発生するかもしれません。 - -この場合、`config.h` ファイルに `#define EXTRA_LONG_COMBOS` または `#define EXTRA_EXTRA_LONG_COMBOS` のどちらかを追加することができます。 - -`COMBO_ALLOW_ACTION_KEYS` を定義することでアクションキーを有効にすることもできます。 - -## キーコード - -その場でコンボ機能を有効、無効および切り替えすることができます。ゲームなどで、一時的にそれらを無効にする必要がある場合に便利です。 - -| キーコード | 説明 | -|----------|---------------------------------| -| `CMB_ON` | コンボ機能をオンにします | -| `CMB_OFF` | コンボ機能をオフにします | -| `CMB_TOG` | コンボ機能のオンとオフを切り替えます | - -## ユーザコールバック - -キーコードに加えて、状態を設定または状態をチェックするために使うことができる幾つかの関数があります: - -| 関数 | 説明 | -|-----------|--------------------------------------------------------------------| -| `combo_enable()` | コンボ機能を有効にします | -| `combo_disable()` | コンボ機能を無効にし、コンボバッファをクリアします | -| `combo_toggle()` | コンボ機能の状態を切り替えます | -| `is_combo_enabled()` | コンボ機能の状態(true か false)を返します | diff --git a/docs/ja/feature_command.md b/docs/ja/feature_command.md deleted file mode 100644 index f8b7e89294..0000000000 --- a/docs/ja/feature_command.md +++ /dev/null @@ -1,56 +0,0 @@ -# コマンド - - - -コマンド(旧称:マジック)は、ファームウェアを書き込んだり、[ブートマジック](ja/feature_bootmagic.md)を使うためにプラグを抜いたりすることなくキーボードの挙動を変更する方法です。この機能と[ブートマジックキーコード](feature_bootmagic.md#keycodes)には多くの重複があります。可能な限り、コマンドでは無くブートマジックキーコードの機能を使うことをお勧めします。 - -一部のキーボードではコマンドがデフォルトで無効になっています。その場合、`rules.mk` 内で明示的に有効にする必要があります: - -```make -COMMAND_ENABLE = yes -``` - -## 使用法 - -コマンドを使うには、`IS_COMMAND()` マクロで定義されたキーの組み合わせを押し続けます。デフォルトでは、これは「左Shift + 右Shift」です。次に、目的のコマンドに対応するキーを押します。例えば、現在の QMK バージョンを QMK Toolbox コンソールに出力するには、「左Shift + 右Shift + `V`」を押します。 - -## 設定 - -コマンドのためのキーの割り当てを変更したい場合は、キーボードあるいはキーマップレベルのどちらかで、`config.h` にこれらを `#define` します。ここで割り当てる全てのキーコードは `KC_` 接頭辞を省略する必要があります。 - -| 定義 | デフォルト | 説明 | -|------------------------------------|--------------------------------|------------------------------------------------| -| `IS_COMMAND()` | `(get_mods() == MOD_MASK_SHIFT)` | コマンドをアクティブにするキーの組み合わせ | -| `MAGIC_KEY_SWITCH_LAYER_WITH_FKEYS` | `true` | ファンクション行を使ってデフォルトレイヤーを設定 | -| `MAGIC_KEY_SWITCH_LAYER_WITH_NKEYS` | `true` | 数字キーでデフォルトレイヤーを設定 | -| `MAGIC_KEY_SWITCH_LAYER_WITH_CUSTOM` | `false` | `MAGIC_KEY_LAYER0..9` を使ってデフォルトレイヤーを設定 | -| `MAGIC_KEY_DEBUG` | `D` | シリアルを介するデバッグの切り替え | -| `MAGIC_KEY_DEBUG_MATRIX` | `X` | キーマトリックスのデバッグの切り替え | -| `MAGIC_KEY_DEBUG_KBD` | `K` | キーボードのデバッグの切り替え | -| `MAGIC_KEY_DEBUG_MOUSE` | `M` | マウスのデバッグの切り替え | -| `MAGIC_KEY_CONSOLE` | `C` | コマンドコンソールを有効にする | -| `MAGIC_KEY_VERSION` | `V` | コンソールに実行中の QMK バージョンを出力 | -| `MAGIC_KEY_STATUS` | `S` | コンソールに現在のキーボードの状態を出力 | -| `MAGIC_KEY_HELP` | `H` | コンソールにコマンドのヘルプを出力 | -| `MAGIC_KEY_HELP_ALT` | `SLASH` | コンソールにコマンドのヘルプを出力 (代替) | -| `MAGIC_KEY_LAYER0` | `0` | レイヤー 0 をデフォルトレイヤーにする | -| `MAGIC_KEY_LAYER0_ALT` | `GRAVE` | レイヤー 0 をデフォルトレイヤーにする (代替) | -| `MAGIC_KEY_LAYER1` | `1` | レイヤー 1 をデフォルトレイヤーにする | -| `MAGIC_KEY_LAYER2` | `2` | レイヤー 2 をデフォルトレイヤーにする | -| `MAGIC_KEY_LAYER3` | `3` | レイヤー 3 をデフォルトレイヤーにする | -| `MAGIC_KEY_LAYER4` | `4` | レイヤー 4 をデフォルトレイヤーにする | -| `MAGIC_KEY_LAYER5` | `5` | レイヤー 5 をデフォルトレイヤーにする | -| `MAGIC_KEY_LAYER6` | `6` | レイヤー 6 をデフォルトレイヤーにする | -| `MAGIC_KEY_LAYER7` | `7` | レイヤー 7 をデフォルトレイヤーにする | -| `MAGIC_KEY_LAYER8` | `8` | レイヤー 8 をデフォルトレイヤーにする | -| `MAGIC_KEY_LAYER9` | `9` | レイヤー 9 をデフォルトレイヤーにする | -| `MAGIC_KEY_BOOTLOADER` | `B` | ブートローダにジャンプする | -| `MAGIC_KEY_BOOTLOADER_ALT` | `ESC` | ブートローダにジャンプする (代替) | -| `MAGIC_KEY_LOCK` | `CAPS` | 何も入力できないようにキーボードをロック | -| `MAGIC_KEY_EEPROM` | `E` | 保存された EEPROM 設定をコンソールに出力 | -| `MAGIC_KEY_EEPROM_CLEAR` | `BSPACE` | EEPROM をクリア | -| `MAGIC_KEY_NKRO` | `N` | N キーロールオーバー (NKRO) の有効・無効を切り替え | -| `MAGIC_KEY_SLEEP_LED` | `Z` | コンピュータがスリープの時に LED を切り替え | diff --git a/docs/ja/feature_debounce_type.md b/docs/ja/feature_debounce_type.md deleted file mode 100644 index 258ca194da..0000000000 --- a/docs/ja/feature_debounce_type.md +++ /dev/null @@ -1,128 +0,0 @@ -# 接点バウンス / 接点チャタリング - - - -メカニカルスイッチは押した状態と放した状態の間の移行が単純ではないことが良くあります。 - -理想的な世界では、スイッチを押すと、デジタルピンが次のようになることが期待されます: -(X 軸は時間を表します -``` -voltage +---------------------- - ^ | - | | - | ------------------+ - ----> time -``` - -しかし実際の世界では、値が最終的に落ち着くまでに 0 と 1 の間を行ったり来たりする接点バウンスを見ることになるでしょう。（訳注：日本語では、バウンスとチャタリングを区別せずにチャタリングと呼んでいることが多いようです。） -``` - +-+ +--+ +------------- - | | | | | - | | | | | -+-----------------+ +-+ +-+ -``` -スイッチが落ち着くまでにかかる時間は、スイッチの種類や経年、押す技術によって異なる場合があります。 - -デバイスが接点バウンスを緩和しないことを選択した場合、スイッチが押された時に起きるアクションが複数回繰り返されることがよくあります。 - -接点バウンス(「デバウンス」)を処理する方法はたくさんあります。RC フィルタのような追加のハードウェアを採用する方法もありますが、ソフトウェアでデバウンスを行う様々な方法もあり、よくデバウンスアルゴリズムと呼ばれます。このページでは、QMK で利用できるデバウンスメソッドについて説明します。 - -技術的には接点バウンス/接点チャタリングとは見なされませんが、一部のスイッチテクノロジーはノイズの影響を受けやすく、キーの状態が変化していない時に、時々短くランダムに 0 と 1 の間を行き来する様子がデジタル回路によって読み取られる場合があります。例えば: -``` - +-+ - | | - | | -+-----------------+ +-------------------- -``` - -多くのデバウンスメソッド(全てではないですが)は、デバイスにノイズ耐性を持たせます。 -ノイズの影響を受けやすい技術を使っている場合は、ノイズを緩和するデバウンスメソッドを選択しなければなりません。 - -## デバウンスアルゴリズムの種類 - -1) 時間の単位: タイムスタンプ (ミリ秒) vs 周期 (スキャン) - * デバウンスアルゴリズムは1つの「デバウンス時間」パラメータを持つことがよくあり、スイッチ接点の最大セトリング時間を指定します。 - この時間は様々な単位で測定される場合があります: - * 周期ベースデバウンスは n 周期(スキャン)待機し、matrix_scan ごとにカウントを1減らします。 - * タイムスタンプベースのデバウンスは、変更が発生したミリ秒のタイムスタンプを格納し、経過時間を計算するために減算を行います。 - * 通常、タイムスタンプベースのデバウンスは、特にノイズ耐性のあるデバイスで優れています。なぜなら、物理スイッチのセトリング時間は時間の単位で指定されており、キーボードのマトリックススキャンレートに依存しないからです。 - * 周期ベースのデバウンスは、補正できるセトリング時間がマトリックススキャンコードのパフォーマンスに依存するため、劣ると見なされる場合があります。 - 周期ベースのデバウンスを使う場合、スキャンコードのパフォーマンスを大幅に向上させると、デバウンスの効果が低下する場合があります。 - 周期ベースのデバウンスが望ましい状況は、ノイズが存在し、スキャンアルゴリズムが遅い、もしくは速度が可変である場合です。 - デバウンスアルゴリズムが基本的にノイズ耐性がある場合でも、スキャンが遅く、タイムスタンプベースのアルゴリズムを使っている場合は、 - 2つのサンプル値に基づいてデバウンスを決定するため、アルゴリズムのノイズ耐性は制限されます。 - * 現在、全ての組み込みデバウンスアルゴリズムは、タイムスタンプベースのデバウンスのみサポートしています。将来的には周期ベースのデバウンスを実装し、```config.h``` マクロを介して選択できるようになるでしょう。 - -2) 対称 vs 非対称 - * 対称 - キーアップとキーダウンイベントの両方に、同じデバウンスアルゴリズムを適用します。 - * 推奨される命名規則: ```sym_*``` - * 非対称 - キーダウンとキーアップイベントに異なるデバウンスアルゴリズムを適用します。例えば、キーダウンはイーガー、キーアップはデファー。 - * 推奨される命名規則: ```asym_*``` の後に、キーダウン、キーアップの順に使っているアルゴリズムタイプの詳細が続きます。 - -3) イーガー vs デファー - * イーガー - キーの変更はすぐに報告されます。DEBOUNCE ミリ秒以降の全ての入力は無視されます。 - * イーガーアルゴリズムはノイズ耐性はありません - * 推奨される命名規則: - * ```sym_eager_*``` - * ```asym_eager_*_*```: キーダウンはイーガーアルゴリズムを使います - * ```asym_*_eager_*```: キーアップはイーガーアルゴリズムを使います - * デファー - 変更を報告する前に DEBOUNCE ミリ秒の間変更がないことを待機します - * デファーアルゴリズムはノイズ耐性があります - * 推奨される命名規則: - * ```sym_defer_*``` - * ```asym_defer_*_*```: キーダウンはデファーアルゴリズムを使います - * ```asym_*_defer_*```: キーアップはデファーアルゴリズムを使います - -4) グローバル vs キーごと vs 行ごと - * グローバル - 全てのキーに対して1つのタイマー。キーの変更状態は、グローバルタイマーに影響を与えます。 - * 推奨される命名規則: ```*_g``` - * キーごと - キーごとに1つのタイマー。 - * 推奨される命名規則: ```*_pk``` - * 行ごと - 行ごとに1つのタイマー。 - * 推奨される命名規則: ```*_pr``` - * キーごとや行ごとのアルゴリズムはより多くのリソース(パフォーマンスと RAM 使用量の観点で)を消費しますが、高速なタイピストはグローバルよりもそれらを好む場合があります。 - -## QMK でサポートされるデバウンスアルゴリズム - -QMK はデバウンス API を介して複数のデバウンスアルゴリズムをサポートします。 - -### デバウンスの選択 - -| DEBOUNCE_TYPE | 説明 | 他に必要なもの | -| ------------- | ------------------------------------------------------------- | ---------------------------------------------------------------------------- | -| 未定義 | デフォルトのアルゴリズム、現在のところ sym_defer_g を使います | 無し | -| custom | 独自のデバウンスコードを使います | ```SRC += debounce.c``` で独自の debounce.c を追加し、必要な関数を実装します | -| その他 | quantum/debounce/* から他のアルゴリズムを使います | 無し | - -**分割キーボードについて**: -デバウンスコードは分割キーボードと互換性があります。 - -### インクルードされているデバウンスメソッドの選択 -キーボードは、```rules.mk``` に次の行を追加することで、既に実装されているデバウンスメソッドの1つを選択できます: -``` -DEBOUNCE_TYPE = <アルゴリズムの名前> -``` -アルゴリズムの名前は次のいずれかです: -* ```sym_defer_g``` - キーボードごとにデバウンスします。状態が変化すると、グローバルタイマが設定されます。```DEBOUNCE``` ミリ秒の間何も変化がなければ、全ての入力の変更がプッシュされます。 - * これは現在のデフォルトアルゴリズムです。これはメモリ使用量が最も少ない最高のパフォーマンスのアルゴリズムで、ノイズ耐性もあります。 -* ```sym_eager_pr``` - 行ごとにデバウンスします。状態が変化すると、応答は即座に行われ、その後その行は ```DEBOUNCE``` ミリ秒の間入力されません。 -```NUM_KEYS``` の 8ビットカウンタの更新に高い計算コストがかかる、もしくは低スキャンレートのキーボード用で、各指は通常一度に1行しか叩かないようになっています。これは ErgoDox モデルに適しています; マトリックスは90度回転しているため、その「行」は実際には「列」であり、通常の使用では各指は一度に1つの「行」にしか当たりません。 -* ```sym_eager_pk``` - キーごとにデバウンスします。状態が変化すると、応答は即座に行われ、その後そのキーは ```DEBOUNCE``` ミリ秒の間入力されません。 -* ```sym_defer_pk``` - キーごとにデバウンスします。状態が変化すると、キーごとのタイマーが設定されます。```DEBOUNCE``` ミリ秒の間そのキーに変化がなければ、キーの状態の変更がプッシュされます。 - -### 将来実装される可能性のあるいくつかのアルゴリズム: -* ```sym_defer_pr``` -* ```sym_eager_g``` -* ```asym_eager_defer_pk``` - -### 独自のデバウンスコードの使用 -独自のデバウンスアルゴリズムを実装するためのオプションがあります。次のようにします: -* ```rules.mk``` に ```DEBOUNCE_TYPE = custom``` を設定します。 -* ```rules.mk``` に ```SRC += debounce.c``` を追加します。 -* 独自の ```debounce.c``` を追加します。例については、```quantum/debounce``` にある現在の実装を見てください。 -* デバウンスは、全てのマトリクススキャンの後で発生します。 -* MATRIX_ROWS ではなく num_rows を使って、分割キーボードが正しくサポートされるようにします。 -* アルゴリズムが他のキーボードにも適用できる可能性がある場合、```quantum/debounce``` に追加することを検討してください。 diff --git a/docs/ja/feature_dip_switch.md b/docs/ja/feature_dip_switch.md deleted file mode 100644 index 8d0eeafa5a..0000000000 --- a/docs/ja/feature_dip_switch.md +++ /dev/null @@ -1,115 +0,0 @@ -# DIP スイッチ - - - -DIP スイッチは、以下を `rules.mk` に追加することでサポートされます: - - DIP_SWITCH_ENABLE = yes - -さらに、以下を `config.h` に追加します: - -```c -// Connects each switch in the dip switch to the GPIO pin of the MCU -#define DIP_SWITCH_PINS { B14, A15, A10, B9 } -// For split keyboards, you can separately define the right side pins -#define DIP_SWITCH_PINS_RIGHT { ... } -``` - -あるいは - -```c -// Connect each switch in the DIP switch to an unused intersections in the key matrix. -#define DIP_SWITCH_MATRIX_GRID { {0,6}, {1,6}, {2,6} } // List of row and col pairs -``` - -## コールバック - -コールバック関数を `.c` に記述することができます: - -```c -bool dip_switch_update_kb(uint8_t index, bool active) { - if !(dip_switch_update_user(index, active)) { return false; } - return true; -} -``` - - -あるいは `keymap.c` に記述することもできます: - -```c -bool dip_switch_update_user(uint8_t index, bool active) { - switch (index) { - case 0: - if(active) { audio_on(); } else { audio_off(); } - break; - case 1: - if(active) { clicky_on(); } else { clicky_off(); } - break; - case 2: - if(active) { music_on(); } else { music_off(); } - break; - case 3: - if (active) { - #ifdef AUDIO_ENABLE - PLAY_SONG(plover_song); - #endif - layer_on(_PLOVER); - } else { - #ifdef AUDIO_ENABLE - PLAY_SONG(plover_gb_song); - #endif - layer_off(_PLOVER); - } - break; - } - return true; -} -``` - -更に、より複雑な処理ができるビットマスク関数をサポートします。 - - -```c -bool dip_switch_update_mask_kb(uint32_t state) { - if (!dip_switch_update_mask_user(state)) { return false; } - return true; -} -``` - - -あるいは `keymap.c` に記述することもできます: - -```c -bool dip_switch_update_mask_user(uint32_t state) { - if (state & (1UL<<0) && state & (1UL<<1)) { - layer_on(_ADJUST); // C on esc - } else { - layer_off(_ADJUST); - } - if (state & (1UL<<0)) { - layer_on(_TEST_A); // A on ESC - } else { - layer_off(_TEST_A); - } - if (state & (1UL<<1)) { - layer_on(_TEST_B); // B on esc - } else { - layer_off(_TEST_B); - } - return true; -} -``` - - -## ハードウェア - -### DIP スイッチの各スイッチを MCU の GPIO ピンに接続する - -DIP スイッチの片側は MCU のピンへ直接配線し、もう一方の側はグラウンドに配線する必要があります。機能的に同じであるため、どちら側がどちらに接続されているかは問題にはならないはずです。 - -### DIP スイッチの各スイッチをキーマトリクスの未使用の交点に接続する - -キースイッチと同じように、ダイオードと DIP スイッチが ROW 線と COL 線に接続します。 diff --git a/docs/ja/feature_dynamic_macros.md b/docs/ja/feature_dynamic_macros.md deleted file mode 100644 index fa1a1df931..0000000000 --- a/docs/ja/feature_dynamic_macros.md +++ /dev/null @@ -1,72 +0,0 @@ -# 動的マクロ: ランタイムでのマクロの記録および再生 - - - -QMK はその場で作られた一時的なマクロをサポートします。これらを動的マクロと呼びます。それらはユーザがキーボードから定義し、キーボードのプラグを抜くか再起動すると失われます。 - -1つまたは2つのマクロに合計128のキー押下を保存できます。RAM をより多く使用してサイズを増やすことができます。 - -有効にするには、最初に `rules.mk` に `DYNAMIC_MACRO_ENABLE = yes` を記述します。そして、以下のキーをキーマップに追加します: - -| キー | Alias | 説明 | -|------------------|----------|---------------------------------------------------| -| `DYN_REC_START1` | `DM_REC1` | マクロ 1 の記録を開始します | -| `DYN_REC_START2` | `DM_REC2` | マクロ 2 の記録を開始します | -| `DYN_MACRO_PLAY1` | `DM_PLY1` | マクロ 1 を再生します | -| `DYN_MACRO_PLAY2` | `DM_PLY2` | マクロ 2 を再生します | -| `DYN_REC_STOP` | `DM_RSTP` | 現在記録中のマクロの記録を終了します。 | - -これが必要な全てです。 - -マクロの記録を開始するには、`DYN_REC_START1` または `DYN_REC_START2` のどちらかを押します。 - -記録を終了するには、`DYN_REC_STOP` レイヤーボタンを押します。`DYN_REC_START1` または `DYN_REC_START2` をもう一度押すことでも記録を終了することができます。 - -マクロを再生するには、`DYN_MACRO_PLAY1` あるいは `DYN_MACRO_PLAY2` のどちらかを押します。 - -マクロの一部としてマクロを再生することができます。マクロ 1 を記録中にマクロ 2 を再生、またはその逆も問題ありません。ただし、再帰的なマクロ、つまりマクロ 1 を再生するマクロ 1 は作成しないでください。もしそうしてキーボードが反応しなくなった場合は、キーボードを取り外し再び接続します。これを完全に無効にするには、`config.h` ファイルで `DYNAMIC_MACRO_NO_NESTING` を定義します。 - -?> 動的マクロの内部の詳細については、`process_dynamic_macro.h` および `process_dynamic_macro.c` ファイルのコメントを読んでください。 - -## カスタマイズ - -ある程度のカスタマイズを可能にするオプションがいくつか追加されています。 - -| 定義 | デフォルト | 説明 | -|----------------------------|----------------|-----------------------------------------------------------------------------------------------------------------| -| `DYNAMIC_MACRO_SIZE` | 128 | 動的マクロが使用できるメモリ量を設定します。これは限られたリソースであり、コントローラに依存します。 | -| `DYNAMIC_MACRO_USER_CALL` | *定義なし* | これを定義すると、ユーザの `keymap.c` ファイルを使ってマクロが起動されます。 | -| `DYNAMIC_MACRO_NO_NESTING` | *定義なし* | これを定義すると、別のマクロからマクロを呼び出す(入れ子になったマクロ)機能を無効にします。 | -| `DYNAMIC_MACRO_DELAY` | *定義なし* | 各キーを送信する時の待ち時間（ms単位）を設定します。 | - - -記録中にキーを押すたびに LED が点滅し始めた場合は、マクロバッファにマクロを入れるスペースがもう無いことを意味します。マクロを入れるには、他のマクロ(それらは同じバッファを共有します)を短くするか、`config.h` に `DYNAMIC_MACRO_SIZE` 定義を追加することでバッファを増やします(デフォルト値: 128; ヘッダ内のコメントを読んでください)。 - - -### DYNAMIC_MACRO_USER_CALL - -以前のバージョンの動的マクロをお使いの方へ: 専用の `DYN_REC_STOP` キーを使わずに動的マクロキーへのアクセスに使われるレイヤーモディファイアのみを使って、マクロの記録を終了することもまだ可能です。この動作に戻したい場合は、`#define DYNAMIC_MACRO_USER_CALL` を `config.h` に追加し、以下のスニペットを `process_record_user()` 関数の先頭に記述します: - -```c - uint16_t macro_kc = (keycode == MO(_DYN) ? DYN_REC_STOP : keycode); - - if (!process_record_dynamic_macro(macro_kc, record)) { - return false; - } -``` - -### ユーザフック - -カスタム機能とフィードバックオプションを動的マクロ機能に追加するために使うことができるフックが幾つかあります。これによりある程度のカスタマイズが可能になります。 - -direction がどのマクロであるかを示すことに注意してください。`1` がマクロ 1、`-1` がマクロ 2、0 がマクロ無しです。 - -* `dynamic_macro_record_start_user(int8_t direction)` - マクロの記録を開始する時に起動されます。 -* `dynamic_macro_play_user(int8_t direction)` - マクロを再生する時に起動されます。 -* `dynamic_macro_record_key_user(int8_t direction, keyrecord_t *record)` - マクロの記録中に各キー押下で起動されます。 -* `dynamic_macro_record_end_user(int8_t direction)` - マクロの記録を停止した時に起動されます。 - -さらに、動的マクロ機能が有効な場合にバックライトを点滅させるために `dynamic_macro_led_blink()` を呼び出すことができます。 diff --git a/docs/ja/feature_encoders.md b/docs/ja/feature_encoders.md deleted file mode 100644 index b93d9a9a28..0000000000 --- a/docs/ja/feature_encoders.md +++ /dev/null @@ -1,85 +0,0 @@ -# エンコーダ - - - -以下を `rules.mk` に追加することで基本的なエンコーダがサポートされます: - -```make -ENCODER_ENABLE = yes -``` - -さらに、以下を `config.h` に追加します: - -```c -#define ENCODERS_PAD_A { B12 } -#define ENCODERS_PAD_B { B13 } -``` - -各 PAD_A/B 変数は配列を定義するため、複数のエンコーダを定義することができます。例えば: - -```c -#define ENCODERS_PAD_A { encoder1a, encoder2a } -#define ENCODERS_PAD_B { encoder1b, encoder2b } -``` - -エンコーダの時計回りの方向が間違っている場合は、A と B のパッド定義を交換することができます。define を使って逆にすることもできます: - -```c -#define ENCODER_DIRECTION_FLIP -``` - -さらに、エンコーダが各戻り止め(デテント)間に登録するパルス数を定義する解像度は、次のように定義できます: - -```c -#define ENCODER_RESOLUTION 4 -``` - -## 分割キーボード - -分割キーボードのそれぞれの側のエンコーダに異なるピン配列を使っている場合、右側のピン配列を以下のように定義することができます: - -```c -#define ENCODERS_PAD_A_RIGHT { encoder1a, encoder2a } -#define ENCODERS_PAD_B_RIGHT { encoder1b, encoder2b } -``` - -## コールバック - -コールバック関数を `.c` に記述することができます: - -```c -bool encoder_update_kb(uint8_t index, bool clockwise) { - if (!encoder_update_user(index, clockwise)) { - return false; - } - -} -``` - -あるいは `keymap.c` に記述することもできます: - -```c -bool encoder_update_user(uint8_t index, bool clockwise) { - if (index == 0) { /* First encoder */ - if (clockwise) { - tap_code(KC_PGDN); - } else { - tap_code(KC_PGUP); - } - } else if (index == 1) { /* Second encoder */ - if (clockwise) { - tap_code(KC_DOWN); - } else { - tap_code(KC_UP); - } - } - return false; -} -``` - -## ハードウェア - -エンコーダの A と B の線は MCU に直接配線し、C/common 線はグランドに配線する必要があります。 diff --git a/docs/ja/feature_grave_esc.md b/docs/ja/feature_grave_esc.md deleted file mode 100644 index 746e9e5d14..0000000000 --- a/docs/ja/feature_grave_esc.md +++ /dev/null @@ -1,37 +0,0 @@ -# グレイブエスケープ - - - -60% キーボード、またはファンクションキー行の無い他のレイアウトを使っている場合、専用の Escape キーが無いことに気付くでしょう。グレイブエスケープは grave キー (` および `~`) を Escape と共有することができる機能です。 - -## 使用法 - -キーマップ内の `KC_GRAVE` キー (通常は`1` キーの左)を `QK_GESC` に置き換えます。ほとんどの場合、このキーは押された時に `KC_ESC` を出力します。ただし、Shift あるいは GUI を押したままにすると、代わりに `KC_GRV` を出力します。 - -## OS に見えるもの - -メアリーがキーボードで GESC を押すと、OS には KC_ESC 文字が見えます。メアリーが Shift を押しながら GESC を押すと、`~` または Shift された時はバッククォートを出力します。彼女が GUI/CMD/WIN を押したままにすると、1つの ` 文字を出力します。 - -## キーコード - -| キー | エイリアス | 説明 | -|---------|-----------|------------------------------------------------------------------| -| `QK_GESC` | `GRAVE_ESC` | 押された場合に Escape。Shift あるいは GUI が押されたままの場合は ` | - -### 注意事項 - -macOS では、Command+` はデフォルトで "次のウィンドウを操作対象にする" にマップされます。つまりバッククォートを出力しません。さらに、ショートカットがキーボード環境設定で変更された場合でも、ターミナルは常にこのショートカットを認識してウィンドウを切り替えます。 - -## 設定 - -グレイブエスケープが壊す可能性のあるキーの組み合わせが幾つかあります。その中には、Windows では Control+Shift+Escape、macOSでは Command+Option+Escape があります。これを回避するには、`config.h` で以下のオプションを `#define` することができます: - -| 定義 | 説明 | -|--------------------------|-----------------------------------------| -| `GRAVE_ESC_ALT_OVERRIDE` | Alt が押された場合、常に Escape を送信する | -| `GRAVE_ESC_CTRL_OVERRIDE` | Control が押された場合、常に Escape を送信する | -| `GRAVE_ESC_GUI_OVERRIDE` | GUI が押された場合、常に Escape を送信する | -| `GRAVE_ESC_SHIFT_OVERRIDE` | Shift が押された場合、常に Escape を送信する | diff --git a/docs/ja/feature_haptic_feedback.md b/docs/ja/feature_haptic_feedback.md deleted file mode 100644 index 687788014a..0000000000 --- a/docs/ja/feature_haptic_feedback.md +++ /dev/null @@ -1,173 +0,0 @@ -# 触覚フィードバック - - - -## 触覚フィードバック の rules.mk オプション - -現在のところ、`rules.mk` で触覚フィードバック用に以下のオプションを利用可能です: - -``` -HAPTIC_ENABLE = yes - -HAPTIC_DRIVER += DRV2605L -HAPTIC_DRIVER += SOLENOID -``` - -## サポートされる既知のハードウェア - -| 名前 | 説明 | -|--------------------|-------------------------------------------------| -| [LV061228B-L65-A](https://www.digikey.com/product-detail/en/jinlong-machinery-electronics-inc/LV061228B-L65-A/1670-1050-ND/7732325) | z-axis 2v LRA | -| [Mini Motor Disc](https://www.adafruit.com/product/1201) | small 2-5v ERM | - -## 触覚キーコード - -以下のキーコードは、選択した触覚メカニズムに依存して動作するかどうか決まります。 - -| 名前 | 説明 | -|-----------|-------------------------------------------------------| -| `HPT_ON` | 触覚フィードバックをオン | -| `HPT_OFF` | 触覚フィードバックをオフ | -| `HPT_TOG` | 触覚フィードバックのオン/オフを切り替え | -| `HPT_RST` | 触覚フィードバック設定をデフォルトに戻す | -| `HPT_FBK` | キー押下またはリリースまたはその両方でフィードバックを切り替え | -| `HPT_BUZ` | ソレノイドのブザー音のオン/オフを切り替え | -| `HPT_MODI` | 次の DRV2605L 波形に移動 | -| `HPT_MODD` | 前の DRV2605L 波形に移動 | -| `HPT_CONT` | 連続触覚モードのオン/オフを切り替え | -| `HPT_CONI` | DRV2605L の連続触覚強度を増加 | -| `HPT_COND` | DRV2605L の連続触覚強度を減少 | -| `HPT_DWLI` | ソレノイドの滞留時間を増加 | -| `HPT_DWLD` | ソレノイドの滞留時間を減少 | - -### ソレノイド - -ほとんどの MCU はソレノイドのコイルを駆動するために必要な電流を供給できないため、最初に MOSFET を介してソレノイドを駆動する回路を構築する必要があります。 - -[Adafruit が提供する配線図](https://cdn-shop.adafruit.com/product-files/412/412_solenoid_driver.pdf) - - -| 設定 | デフォルト | 説明 | -|--------------------------|---------------|-------------------------------------------------------| -| `SOLENOID_PIN` | *定義なし* | ソレノイドが接続されているピンを設定する。 | -| `SOLENOID_DEFAULT_DWELL` | `12` ms | ソレノイドのデフォルトの滞留時間を設定する。 | -| `SOLENOID_MIN_DWELL` | `4` ms | 滞留時間の下限を設定する。 | -| `SOLENOID_MAX_DWELL` | `100` ms | 滞留時間の上限を設定する。 | -| `SOLENOID_DWELL_STEP_SIZE` | `1` ms | `HPT_DWL*` キーコードが送信される時に使われるステップサイズ | -| `SOLENOID_DEFAULT_BUZZ` | `0` (無効) | HPT_RST では、この値が "1" の場合、ブザー音が "on" に設定されます | -| `SOLENOID_BUZZ_ACTUATED` | `SOLENOID_MIN_DWELL` | ソレノイドがブザー音モードの場合の動作時間 | -| `SOLENOID_BUZZ_NONACTUATED` | `SOLENOID_MIN_DWELL` | ソレノイドがブザー音モードの場合の非動作時間 | - -* ソレノイドのブザー音がオフの場合、滞留時間は「プランジャー」が作動したままになる時間です。滞留時間により、ソレノイドの音が変わります。 -* ソレノイドのブザー音がオンの場合、滞留時間は振動の長さを設定しますが、`SOLENOID_BUZZ_ACTUATED` と `SOLENOID_BUZZ_NONACTUATED` はブザー音の間の(非)動作時間を設定します。 -* 現在の実装では、上記の時間設定のいずれについても、設定の精度はキーボードがマトリックスをスキャンできる速度によって影響を受ける可能性があります。 - したがって、キーボードのスキャンルーチンが遅い場合は、`SOLENOID_DWELL_STEP_SIZE` をキーボードのスキャンに掛かる時間よりもわずかに小さい値に設定することをお勧めします。 - -ブートローダ実行中に一部のピンが給電されているかもしれず (例えば、STM32F303 チップ上の A13)、そうすると書き込みプロセスの間ずっとソレノイドがオン状態になることに注意してください。これはソレノイドを加熱し損傷を与えるかもしれません。ソレノイドが接続されているピンがブートローダ/DFU 実行中にソレノイドをオンにしていることが分かった場合は、他のピンを選択してください。 - -### DRV2605L - -DRV2605Lは i2c プロトコルで制御され、SDA および SCL ピンに接続する必要があります。これらは使用する MCU によって異なります。 - -#### フィードバックモータのセットアップ - -このドライバは2つの異なるフィードバックモータをサポートします。選択したモータに基づいて、`config.h` で以下を設定します。 - -##### ERM - -偏心回転質量振動モータ (ERM) は偏りのある重りが取り付けられたモータで、駆動信号が取り付けられると偏りのある重りが回転し、正弦波が振動に変換されます。 - -``` -#define FB_ERM_LRA 0 -#define FB_BRAKEFACTOR 3 /* For 1x:0, 2x:1, 3x:2, 4x:3, 6x:4, 8x:5, 16x:6, Disable Braking:7 */ -#define FB_LOOPGAIN 1 /* For Low:0, Medium:1, High:2, Very High:3 */ - -/* 特定のモータに最適な設定については、データシートを参照してください。*/ -#define RATED_VOLTAGE 3 -#define V_PEAK 5 -``` -##### LRA - -線形共振アクチュエータ (LRA、線形バイブレータとしても知られています)は、ERM と異なります。LRA は重りと磁石をバネで吊るしたものとボイスコイルで構成されています。駆動信号が印加されるとされると、重りは単一の軸で振動します (左右または上下)。重りはバネに取り付けられているため、特定の周波数で共振効果があります。この周波数は LRA が最も効率的に動作する箇所です。この周波数の推奨範囲については、モータのデータシートを参照してください。 - -``` -#define FB_ERM_LRA 1 -#define FB_BRAKEFACTOR 3 /* For 1x:0, 2x:1, 3x:2, 4x:3, 6x:4, 8x:5, 16x:6, Disable Braking:7 */ -#define FB_LOOPGAIN 1 /* For Low:0, Medium:1, High:2, Very High:3 */ - -/* 特定のモータに最適な設定については、データシートを参照してください。*/ -#define RATED_VOLTAGE 2 -#define V_PEAK 2.8 -#define V_RMS 2.0 -#define V_PEAK 2.1 -#define F_LRA 205 /* 共振周波数 */ -``` - -#### DRV2605L 波形ライブラリ - -DRV2605L には呼び出して再生できる様々な波形シーケンスのプリロードライブラリが同梱されています。マクロを書く場合、これらの波形は `DRV_pulse(*sequence name or number*)` を使って再生することができます - -データシートの波形シーケンスのリスト - -| seq# | シーケンス名 | seq# | シーケンス名 | seq# | シーケンス名 | -|-----|---------------------|-----|-----------------------------------|-----|--------------------------------------| -| 1 | strong_click | 43 | lg_dblclick_med_60 | 85 | transition_rampup_med_smooth2 | -| 2 | strong_click_60 | 44 | lg_dblsharp_tick | 86 | transition_rampup_short_smooth1 | -| 3 | strong_click_30 | 45 | lg_dblsharp_tick_80 | 87 | transition_rampup_short_smooth2 | -| 4 | sharp_click | 46 | lg_dblsharp_tick_60 | 88 | transition_rampup_long_sharp1 | -| 5 | sharp_click_60 | 47 | buzz | 89 | transition_rampup_long_sharp2 | -| 6 | sharp_click_30 | 48 | buzz_80 | 90 | transition_rampup_med_sharp1 | -| 7 | soft_bump | 49 | buzz_60 | 91 | transition_rampup_med_sharp2 | -| 8 | soft_bump_60 | 50 | buzz_40 | 92 | transition_rampup_short_sharp1 | -| 9 | soft_bump_30 | 51 | buzz_20 | 93 | transition_rampup_short_sharp2 | -| 10 | dbl_click | 52 | pulsing_strong | 94 | transition_rampdown_long_smooth1_50 | -| 11 | dbl_click_60 | 53 | pulsing_strong_80 | 95 | transition_rampdown_long_smooth2_50 | -| 12 | trp_click | 54 | pulsing_medium | 96 | transition_rampdown_med_smooth1_50 | -| 13 | soft_fuzz | 55 | pulsing_medium_80 | 97 | transition_rampdown_med_smooth2_50 | -| 14 | strong_buzz | 56 | pulsing_sharp | 98 | transition_rampdown_short_smooth1_50 | -| 15 | alert_750ms | 57 | pulsing_sharp_80 | 99 | transition_rampdown_short_smooth2_50 | -| 16 | alert_1000ms | 58 | transition_click | 100 | transition_rampdown_long_sharp1_50 | -| 17 | strong_click1 | 59 | transition_click_80 | 101 | transition_rampdown_long_sharp2_50 | -| 18 | strong_click2_80 | 60 | transition_click_60 | 102 | transition_rampdown_med_sharp1_50 | -| 19 | strong_click3_60 | 61 | transition_click_40 | 103 | transition_rampdown_med_sharp2_50 | -| 20 | strong_click4_30 | 62 | transition_click_20 | 104 | transition_rampdown_short_sharp1_50 | -| 21 | medium_click1 | 63 | transition_click_10 | 105 | transition_rampdown_short_sharp2_50 | -| 22 | medium_click2_80 | 64 | transition_hum | 106 | transition_rampup_long_smooth1_50 | -| 23 | medium_click3_60 | 65 | transition_hum_80 | 107 | transition_rampup_long_smooth2_50 | -| 24 | sharp_tick1 | 66 | transition_hum_60 | 108 | transition_rampup_med_smooth1_50 | -| 25 | sharp_tick2_80 | 67 | transition_hum_40 | 109 | transition_rampup_med_smooth2_50 | -| 26 | sharp_tick3_60 | 68 | transition_hum_20 | 110 | transition_rampup_short_smooth1_50 | -| 27 | sh_dblclick_str | 69 | transition_hum_10 | 111 | transition_rampup_short_smooth2_50 | -| 28 | sh_dblclick_str_80 | 70 | transition_rampdown_long_smooth1 | 112 | transition_rampup_long_sharp1_50 | -| 29 | sh_dblclick_str_60 | 71 | transition_rampdown_long_smooth2 | 113 | transition_rampup_long_sharp2_50 | -| 30 | sh_dblclick_str_30 | 72 | transition_rampdown_med_smooth1 | 114 | transition_rampup_med_sharp1_50 | -| 31 | sh_dblclick_med | 73 | transition_rampdown_med_smooth2 | 115 | transition_rampup_med_sharp2_50 | -| 32 | sh_dblclick_med_80 | 74 | transition_rampdown_short_smooth1 | 116 | transition_rampup_short_sharp1_50 | -| 33 | sh_dblclick_med_60 | 75 | transition_rampdown_short_smooth2 | 117 | transition_rampup_short_sharp2_50 | -| 34 | sh_dblsharp_tick | 76 | transition_rampdown_long_sharp1 | 118 | long_buzz_for_programmatic_stopping | -| 35 | sh_dblsharp_tick_80 | 77 | transition_rampdown_long_sharp2 | 119 | smooth_hum1_50 | -| 36 | sh_dblsharp_tick_60 | 78 | transition_rampdown_med_sharp1 | 120 | smooth_hum2_40 | -| 37 | lg_dblclick_str | 79 | transition_rampdown_med_sharp2 | 121 | smooth_hum3_30 | -| 38 | lg_dblclick_str_80 | 80 | transition_rampdown_short_sharp1 | 122 | smooth_hum4_20 | -| 39 | lg_dblclick_str_60 | 81 | transition_rampdown_short_sharp2 | 123 | smooth_hum5_10 | -| 40 | lg_dblclick_str_30 | 82 | transition_rampup_long_smooth1 | | | -| 41 | lg_dblclick_med | 83 | transition_rampup_long_smooth2 | | | -| 42 | lg_dblclick_med_80 | 84 | transition_rampup_med_smooth1 | | | -### オプションの DRV2605L の定義 - -``` -#define DRV_GREETING *sequence name or number* -``` -触覚フィードバッグが有効な場合、キーボード起動時に特定のシーケンスに合わせて振動します。以下の定義を使って選択することができます: - -``` -#define DRV_MODE_DEFAULT *sequence name or number* -``` -これにより HPT_RST がアクティブモードとして設定するシーケンスを設定します。未定義の場合、HPT_RST が押された時にモードが 1 に設定されます。 - -### DRV2605L 連続触覚モード - -このモードは強さを増減するオプションを使って連続触覚フィードバッグを設定します。 diff --git a/docs/ja/feature_hd44780.md b/docs/ja/feature_hd44780.md deleted file mode 100644 index b4e1ef03ab..0000000000 --- a/docs/ja/feature_hd44780.md +++ /dev/null @@ -1,62 +0,0 @@ -# HD44780 LCD ディスプレイ - - - -これは Peter Fleury の LCD ライブラリの統合です。このページは基本について説明します。[詳細なドキュメントについてはこのページをご覧ください](http://www.peterfleury.epizy.com/doxygen/avr-gcc-libraries/group__pfleury__lcd.html) - -HD44780 ディスプレイのサポートを有効にするには、キーボードの `rules.mk` の `HD44780_ENABLE` フラグを yes に設定します。 - -## 設定 - -ディスプレイで使用されるピンとディスプレイの行と列の数を、キーボードの `config.h` に設定する必要があります。 - - -HD44780 のラベルが付いたセクションのコメントを外し、必要に応じてパラメータを変更します。 -```` -/* - * HD44780 LCD ディスプレイ設定 - */ - -#define LCD_LINES 2 //< ディスプレイの表示行数 -#define LCD_DISP_LENGTH 16 //< ディスプレイの行ごとの表示文字数 -#define LCD_IO_MODE 1 //< 0: メモリマップモード 1: IO ポートモード -#if LCD_IO_MODE -#define LCD_PORT PORTB //< LCD 行のためのポート -#define LCD_DATA0_PORT LCD_PORT //< 4ビットデータビット 0 のポート -#define LCD_DATA1_PORT LCD_PORT //< 4ビットデータビット 1 のポート -#define LCD_DATA2_PORT LCD_PORT //< 4ビットデータビット 2 のポート -#define LCD_DATA3_PORT LCD_PORT //< 4ビットデータビット 3 のポート -#define LCD_DATA0_PIN 4 //< 4ビットデータビット 0 のピン -#define LCD_DATA1_PIN 5 //< 4ビットデータビット 1 のピン -#define LCD_DATA2_PIN 6 //< 4ビットデータビット 2 のピン -#define LCD_DATA3_PIN 7 //< 4ビットデータビット 3 のピン -#define LCD_RS_PORT LCD_PORT //< RS 線のためのポート -#define LCD_RS_PIN 3 //< RS 線のためのピン -#define LCD_RW_PORT LCD_PORT //< RW 線のためのポート -#define LCD_RW_PIN 2 //< RW 線のためのピン -#define LCD_E_PORT LCD_PORT //< Enable 線のためのポート -#define LCD_E_PIN 1 //< Enable 線のためのピン -#endif -```` - -他のプロパティを設定する必要がある場合は、それらを `quantum/hd44780.h` からコピーし、`config.h` に設定することができます。（訳注）`quantum/hd44780.h` は `drivers/avr/hd44780.h` の間違いではないかと思われます。 - -## 使用法 - -ディスプレイを初期化するには、以下のパラメータのうちの1つを使って `lcd_init()` を呼び出します: -```` -LCD_DISP_OFF : ディスプレイオフ -LCD_DISP_ON : ディスプレイオン、カーソルオフ -LCD_DISP_ON_CURSOR : ディスプレイオン、カーソルオン -LCD_DISP_ON_CURSOR_BLINK : ディスプレイオン、点滅カーソル -```` -これはキーボードの `matrix_init_kb` またはキーマップの `matrix_init_user` で行うのが最適です。 -使用前にディスプレイをクリアすることをお勧めします。 -そのためには、`lcd_clrscr()` を呼びます。 - -ディスプレイに何かを表示するには、最初に `lcd_gotoxy(column, line)` を呼びます。最初の行の先頭に移動するには、`lcd_gotoxy(0, 0)` を呼び出し、その後 `lcd_puts("example string")` を使って文字列を出力します。 - -ディスプレイを制御することができる、より多くのメソッドがあります。[詳細なドキュメントについてはリンクされたページをご覧ください](http://www.peterfleury.epizy.com/doxygen/avr-gcc-libraries/group__pfleury__lcd.html) diff --git a/docs/ja/feature_key_lock.md b/docs/ja/feature_key_lock.md deleted file mode 100644 index 22cd9fb810..0000000000 --- a/docs/ja/feature_key_lock.md +++ /dev/null @@ -1,27 +0,0 @@ -# キーロック - - - -特定のキーを長時間押すことが必要になる場合があります。キーロックは次に押すキーを押したままにします。もう一度押すと、リリースされます。 - -いくつかの文を全て大文字で入力する必要があるとしましょう。`KC_LOCK` を押し、次にシフトを押します。これで、シフトは次にタップするまで押していると見なされます。キーロックを Caps Lock と考えることができますが、さらに強力です。 - -## 使用法 - -最初に `rules.mk` で `KEY_LOCK_ENABLE = yes` を設定することでキーロックを有効にします。次に、キーマップでキーを選択し、それをキーコード `KC_LOCK` に割り当てます。 - -## キーコード - -| キーコード | 説明 | -|---------|--------------------------------------------------------------| -| `KC_LOCK` | キーが再び押されるまで次のキーを押したままにします。 | - -## 注意事項 - -キーロックは、標準アクションキーと[ワンショットモディファイア](ja/one_shot_keys.md)キー (例えば、Shift を `OSM(MOD_LSFT)` と定義した場合)のみを押し続けることができます。 -これは、QMK の特殊機能(ワンショットモディファイアを除く)、または `KC_LPRN` のような shift を押されたキーのバージョンは含みません。[基本的なキーコード](ja/keycodes_basic.md)リストにある場合、押したままにすることができます。 - -レイヤーの切り替えは、キーロックを解除しません。 diff --git a/docs/ja/feature_layers.md b/docs/ja/feature_layers.md deleted file mode 100644 index ca3e055835..0000000000 --- a/docs/ja/feature_layers.md +++ /dev/null @@ -1,97 +0,0 @@ -# レイヤー :id=layers - - - -QMK ファームウェアの最も強力で良く使われている機能の一つは、レイヤーを使う機能です。ほとんどの人にとって、これはラップトップやタブレットキーボードにあるのと同じように、様々なキーを可能にするファンクションキーに相当します。 - -レイヤースタックがどのように動作するかの詳細な説明については、[キーマップの概要](ja/keymap.md#keymap-and-layers)を調べてください。 - -## レイヤーの切り替えとトグル :id=switching-and-toggling-layers - -以下の関数により、様々な方法でレイヤーをアクティブにすることができます。レイヤーは通常、独立したレイアウトでは無いことに注意してください -- 複数のレイヤーを一度にアクティブにすることができ、レイヤーが `KC_TRNS` を使ってキーの押下を下のレイヤーへと透過させることが一般的です。MO()、LM()、TT() あるいは LT() を使って一時的なレイヤーの切り替えを使う場合、上のレイヤーのキーを透過にするようにしてください。さもないと意図したように動作しないかもしれません。 - -* `DF(layer)` - デフォルトレイヤーを切り替えます。デフォルトレイヤーは、他のレイヤーがその上に積み重なっている、常にアクティブな基本レイヤーです。デフォルトレイヤーの詳細については以下を見てください。これは QWERTY から Dvorak レイアウトに切り替えるために使うことができます。(これは一時的な切り替えであり、キーボードの電源が切れるまでしか持続しないことに注意してください。デフォルトレイヤーを永続的に変更するには、[process_record_user](ja/custom_quantum_functions.md#programming-the-behavior-of-any-keycode) 内で `set_single_persistent_default_layer` 関数を呼び出すなど、より深いカスタマイズが必要です。) -* `MO(layer)` - 一時的に*レイヤー*をアクティブにします。キーを放すとすぐに、レイヤーは非アクティブになります。 -* `LM(layer, mod)` - (`MO` のように)一時的に*レイヤー*をアクティブにしますが、モディファイア *mod* がアクティブな状態です。layer 0-15 と、左モディファイアのみをサポートします: `MOD_LCTL`、`MOD_LSFT`、`MOD_LALT`、`MOD_LGUI` (`KC_` 定数の代わりに `MOD_` 定数を使うことに注意してください)。これらのモディファイアは、例えば `LM(_RAISE, MOD_LCTL | MOD_LALT)` のように、ビット単位の OR を使って組み合わせることができます。 -* `LT(layer, kc)` - ホールドされた時に*レイヤー*を一時的にアクティブにし、タップされた時に *kc* を送信します。layer 0-15 のみをサポートします。 -* `OSL(layer)` - 次のキーが押されるまで、一時的に*レイヤー*をアクティブにします。詳細と追加機能については、[ワンショットキー](ja/one_shot_keys.md)を見てください。 -* `TG(layer)` - *レイヤー*を切り替えます。非アクティブな場合はアクティブにし、逆も同様です。 -* `TO(layer)` - *レイヤー*をアクティブにし、他の全てのレイヤー(デフォルトレイヤーを除く)を非アクティブにします。この関数は特別です。1つのレイヤーをアクティブなレイヤースタックに追加/削除する代わりに、現在のアクティブなレイヤーを完全に置き換え、唯一上位のレイヤーを下位のレイヤーで置き換えることができるからです。これはキーダウンで(キーが押されるとすぐに)アクティブになります。 -* `TT(layer)` - レイヤーのタップ切り替え。キーを押したままにすると*レイヤー*がアクティブにされ、放すと非アクティブになります (`MO` 風)。繰り返しタップすると、レイヤーはオンあるいはオフを切り替えます (`TG` 風)。デフォルトでは5回のタップが必要ですが、`TAPPING_TOGGLE` を定義することで変更することができます -- 例えば、2回のタップだけで切り替えるには、`#define TAPPING_TOGGLE 2` を定義します。 - -### 注意事項 :id=caveats - -現在のところ、`LT()` の `layer` 引数はレイヤー 0-15 に制限され、`kc` 引数は[基本的なキーコードセット](ja/keycodes_basic.md)に制限されています。つまり、`LCTL()`、`KC_TILD` あるいは `0xFF` より大きなキーコードを使うことができません。これは、QMK が16ビットのキーコードを使うためです。4ビットは機能の識別のために使われ、4ビットはレイヤーのために使われ、キーコードには8ビットしか残されていません。 - -これを拡張してもせいぜい複雑になるだけでしょう。32ビットキーコードに移行すると、これの多くが解決されますが、キーマップマトリックスが使用する領域が2倍になります。また、問題が起きる可能性もあります。タップしたキーコードにモディファイアを適用する必要がある場合は、[タップダンス](ja/feature_tap_dance.md#example-5-using-tap-dance-for-advanced-mod-tap-and-layer-tap-keys)を使うことができます。 - -## レイヤーとの連携 :id=working-with-layers - -レイヤーを切り替える時は注意してください。(キーボードを取り外さずに)そのレイヤーを非アクティブにすることができずレイヤーから移動できなくなる可能性があります。最も一般的な問題を避けるためのガイドラインを作成しました。 - -### 初心者 :id=beginners - -QMK を使い始めたばかりの場合は、全てを単純にしたいでしょう。レイヤーをセットアップする時は、これらのガイドラインに従ってください: - -* デフォルトの "base" レイヤーとして、layer 0 をセットアップします。これは通常の入力レイヤーであり、任意のレイアウト (qwerty、dvorak、colemak など)にすることができます。通常はキーボードのキーのほとんどまたは全てが定義されているため、これを最下位のレイヤーとして設定することが重要です。そうすることで、もしそれが他のレイヤーの上 (つまりレイヤー番号が大きい)にある場合の影響を防ぎます。 -* layer 0 をルートとして、レイヤーを "ツリー" レイアウトに配置します。他の複数のレイヤーから同じレイヤーに行こうとしないでください。 -* 各レイヤーのキーマップでは、より高い番号のレイヤーのみを参照します。レイヤーは最大の番号(最上位)のアクティブレイヤーから処理されるため、下位レイヤーの状態を変更するのは難しくエラーが発生しやすくなります。 - -### 中級ユーザ :id=intermediate-users - -複数の基本レイヤーが必要な場合があります。例えば、QWERTY と Dvorak を切り替える場合、国ごとに異なるレイアウトを切り替える場合、あるいは異なるビデオゲームごとにレイアウトを切り替える場合などです。基本レイヤーは常に最小の番号のレイヤーである必要があります。複数の基本レイヤーがある場合、常にそれらを相互排他的に扱う必要があります。1つの基本レイヤーがオンの場合、他をオフにします。 - -### 上級ユーザ :id=advanced-users - -レイヤーがどのように動作し、何ができるかを理解したら、より創造的になります。初心者のセクションで列挙されている規則は、幾つかの巧妙な詳細を回避するのに役立ちますが、特に超コンパクトなキーボードのユーザにとって制約になる場合があります。レイヤーの仕組みを理解することで、レイヤーをより高度な方法で使うことができます。 - -レイヤーは番号順に上に積み重なっています。キーの押下の動作を決定する時に、QMK は上から順にレイヤーを走査し、`KC_TRNS` に設定されていない最初のアクティブなレイヤーに到達すると停止します。結果として、現在のレイヤーよりも数値的に低いレイヤーをアクティブにし、現在のレイヤー(あるいはアクティブでターゲットレイヤーよりも高い別のレイヤー)に `KC_TRNS` 以外のものがある場合、それが送信されるキーであり、アクティブ化したばかりのレイヤー上のキーではありません。これが、ほとんどの人の "なぜレイヤーが切り替わらないのか" 問題の原因です。 - -場合によっては、マクロ内あるいはタップダンスルーチンの一部としてレイヤーを切り替えほうが良いかもしれません。`layer_on` はレイヤーをアクティブにし、`layer_off` はそれを非アクティブにします。もっと多くのレイヤーに関する関数は、[action_layer.h](https://github.com/qmk/qmk_firmware/blob/master/quantum/action_layer.h) で見つけることができます。 - -## 関数 :id=functions - -レイヤーの使用あるいは操作に関係する多くの関数(と変数)があります。 - -| 関数 | 説明 | -| -------------------------------------------- | ---------------------------------------------------------------------------------------------------------- | -| `layer_state_set(layer_mask)` | 直接レイヤーの状態を設定する (推奨。何をしているのか分かっていない場合は使わないでください)。 | -| `layer_clear()` | 全てのレイヤーを消去する (全てをオフにします)。 | -| `layer_move(layer)` | 指定されたレイヤーをオンにし、それ以外をオフにする。 | -| `layer_on(layer)` | 指定されたレイヤーをオンにし、それ以外を既存の状態のままにする。 | -| `layer_off(layer)` | 指定されたレイヤーをオフにし、それ以外を既存の状態のままにする。 | -| `layer_invert(layer)` | 指定されたレイヤーの状態を反転/トグルする。 | -| `layer_or(layer_mask)` | 指定されたレイヤーと既存のレイヤー状態の間で一致するビットに基づいてレイヤーをオンにする。 | -| `layer_and(layer_mask)` | 指定されたレイヤーと既存のレイヤー状態の間で有効なビットに基づいてレイヤーをオンにする。 | -| `layer_xor(layer_mask)` | 指定されたレイヤーと既存のレイヤー状態の間で一致しないビットに基づいてレイヤーをオンにする。 | -| `layer_debug(layer_mask)` | デバッガのコンソールに現在のビットマスクと最も高いレイヤーを出力する。 | -| `default_layer_set(layer_mask)` | 直接デフォルトレイヤーの状態を設定する (推奨。何をしているのか分かっていない場合は使わないでください)。 | -| `default_layer_or(layer_mask)` | 指定されたレイヤーと既存のデフォルトレイヤー状態の間で一致するビットに基づいてレイヤーをオンにする。 | -| `default_layer_and(layer_mask)` | 指定されたレイヤーと既存のデフォルトレイヤー状態の間で一致する有効なビットに基づいてレイヤーをオンにする。 | -| `default_layer_xor(layer_mask)` | 指定されたレイヤーと既存のデフォルトレイヤー状態の間で一致しないビットに基づいてレイヤーをオンにする。 | -| `default_layer_debug(layer_mask)` | デバッガのコンソールに現在のビットマスクと最も高いアクティブなレイヤーを出力する。 | -| [`set_single_persistent_default_layer(layer)`](ja/ref_functions.md#setting-the-persistent-default-layer) | デフォルトレイヤーを設定し、それを永続化メモリ (EEPROM) に書き込む。 | -| [`update_tri_layer(x, y, z)`](ja/ref_functions.md#update_tri_layerx-y-z) | レイヤー `x` と `y` の両方がオンであるかを調べ、それに基づいて `z` を設定する(両方がオンの場合オン、そうでなければオフ)。 | -| [`update_tri_layer_state(state, x, y, z)`](ja/ref_functions.md#update_tri_layer_statestate-x-y-z) | `update_tri_layer(x, y, z)` と同じことをするが、`layer_state_set_*` 関数から呼ばれる。 | - - -呼び出すことができる関数に加えて、レイヤーが変更されるたびに呼び出されるコールバック関数が幾つかあります。これはレイヤー状態を関数に渡し、読み取りや変更することができます。 - -| コールバック | 説明 | -| --------------------------------------------------- | ------------------------------------------------------------------------------------------------ | -| `layer_state_set_kb(layer_state_t state)` | キーボードレベルのレイヤー関数のためのコールバック。 | -| `layer_state_set_user(layer_state_t state)` | ユーザレベルのレイヤー関数のためのコールバック。 | -| `default_layer_state_set_kb(layer_state_t state)` | キーボードレベルのデフォルトレイヤー関数のためのコールバック。キーボードの初期化時に呼ばれます。 | -| `default_layer_state_set_user(layer_state_t state)` | ユーザレベルのデフォルトレイヤー関数のためのコールバック。キーボードの初期化時に呼ばれます。 | - -?> これらのコールバックを使うための追加の情報については、[レイヤー変換コード](ja/custom_quantum_functions.md#layer-change-code)のドキュメントを調べてください。 - -次の関数やマクロを使って、特定のレイヤーの状態を確認することもできます。 - -| 関数 | 説明 | 別名 | -| ------------------------------- | ------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------- | -| `layer_state_is(layer)` | 指定された `layer` がグローバルに有効かどうかを確認する。 | `IS_LAYER_ON(layer)`, `IS_LAYER_OFF(layer)` | -| `layer_state_cmp(state, layer)` | `state` を確認して指定された `layer` が有効かどうかを確認する。レイヤーのコールバックで使うことを目的とする。 | `IS_LAYER_ON_STATE(state, layer)`, `IS_LAYER_OFF_STATE(state, layer)` | diff --git a/docs/ja/feature_layouts.md b/docs/ja/feature_layouts.md deleted file mode 100644 index 9b36a1eda5..0000000000 --- a/docs/ja/feature_layouts.md +++ /dev/null @@ -1,114 +0,0 @@ -# レイアウト: 複数のキーボードで1つのキーマップを使用 - - - -`layouts/` フォルダは、様々なキーボードに適用できる色々な物理キーレイアウトを含みます。 - -``` -layouts/ -+ default/ -| + 60_ansi/ -| | + readme.md -| | + layout.json -| | + a_good_keymap/ -| | | + keymap.c -| | | + readme.md -| | | + config.h -| | | + rules.mk -| | + / -| | + ... -| + / -+ community/ -| + / -| + ... -``` - -`layouts/default/` と `layouts/community/` は、レイアウト「repositories」の2つの例です。現在のところ、`default` にはユーザの参考用に、レイアウトに関する全ての情報および、`default_` という名前の1つのデフォルトのキーマップが含まれています。`community` には全ての共有キーマップが含まれており、それらはユーザが `layouts/` にクローンするための別のリポジトリに分割することを最終的な目的としていますQMK は `layouts/` 内のすべてのフォルダを検索するため、ここに複数のリポジトリを持つことができます。 - -各レイアウトフォルダは、レイアウトの物理的な側面に基づいて、可能な限り一般的な名称で(`[a-z0-9_]`)という名前が付けられ、キーボードで定義されるレイアウトと一緒に `readme.md` を含みます。 - -```md -# 60_ansi - - LAYOUT_60_ansi -``` - -新しい名前は既存のレイアウトで設定された標準に準拠しようと努力する必要があり、必要に応じて PR/Issue で議論することができます。 - -## レイアウトのサポート - -キーボードがレイアウトをサポートするために、変数は `.h` で定義し、引数/キー (できれば物理レイアウト)の数に一致している必要があります。 - - #define LAYOUT_60_ansi KEYMAP_ANSI - -レイアウトの名前は次の正規表現に一致しなければなりません: `[a-z0-9_]+` - -フォルダ名はキーボードの `rules.mk` に追加する必要があります: - - LAYOUTS = 60_ansi - -`LAYOUTS` は任意のキーボードフォルダレべルの `rules.mk` に設定することができます: - - LAYOUTS = 60_iso - -ただし、`LAYOUT_` 変数は `.h` でも定義する必要があります。 - -## キーマップのビルド - -以下の形式でコマンドを使ってキーボードキーマップを作成できるはずです: - - make : - -### レイアウトの競合 -キーボードが複数のレイアウトオプションをサポートし、 - - LAYOUTS = ortho_4x4 ortho_4x12 - -なおかつ両方のオプションについてレイアウトが存在する場合、 -``` -layouts/ -+ community/ -| + ortho_4x4/ -| | + / -| | | + ... -| + ortho_4x12/ -| | + / -| | | + ... -| + ... -``` - -FORCE_LAYOUT 引数はどのレイアウトをビルドするかを指定するために使うことができます - - make : FORCE_LAYOUT=ortho_4x4 - make : FORCE_LAYOUT=ortho_4x12 - -## キーボードに依存しないレイアウトを作成するためのヒント - -### インクルード - -`#include "planck.h"` を使う代わりに、以下の行を使ってコンパイルされる `.h` (`.h` はここでインクルードすべきではありません)ファイルをインクルードすることができます: - - #include QMK_KEYBOARD_H - -キーボード固有のコードを保持したい場合は、これらの変数を使って `#ifdef` 文でエスケープすることができます: - -* `KEYBOARD__` - -例えば: - -```c -#ifdef KEYBOARD_planck - #ifdef KEYBOARD_planck_rev4 - planck_rev4_function(); - #endif -#endif -``` - -名前は小文字でキーボード/リビジョンのフォルダ/ファイル名と正確に一致することに注意してください。 - -### キーマップ - -同じレイアウトで分割および非分割キーボードをサポートするためには、キーマップでキーボード非依存の `LAYOUT_` マクロを使う必要があります。例えば、Let's Split および Planck が同じレイアウトを共有するには、`LAYOUT_planck_grid` や C 配列の場合の単なる `{}` の代わりに、`LAYOUT_ortho_4x12` を使う必要があります。 diff --git a/docs/ja/feature_leader_key.md b/docs/ja/feature_leader_key.md deleted file mode 100644 index b826b068eb..0000000000 --- a/docs/ja/feature_leader_key.md +++ /dev/null @@ -1,164 +0,0 @@ -# リーダーキー: 新しい種類のモディファイア - - - -もしあなたが Vim を使ったことがある場合、リーダーキーは何であるかを知っています。そうでなければ、素晴らしい概念を発見しようとしています。:) 例えば、Alt+Shift+W を押す(3つのキーを同時に押す)代わりに、キーの_シーケンス_を押すことができたらどうでしょう？つまり、特別なモディファイア (リーダーキー)を押して、続けて W と C を押すと (単純にキーを高速に繋げます)、何かが起こります。 - -それが `KC_LEAD` の機能です。以下は例です: - -1. リーダーキーとして使いたいキーボードのキーを選択します。それにキーコード `KC_LEAD` を割り当てます。このキーはこのためだけの専用です -- 単一アクションのキーで、他の用途には使うことができません。 -2. `config.h` に `#define LEADER_TIMEOUT 300` という行を追加します。これによって `KC_LEAD` キーのタイムアウトを設定します。具体的には、`KC_LEAD` キーを押してからリーダーキーのシーケンスを完了するまで一定の時間しかありません。ここでの `300` はそれを300msに設定します。この値を増やして、シーケンスを入力する時間を増やすことができます。ただし、この時間中に押されたキーは全て途中で遮られ、送信されません。そのためこの値は小さくしておいたほうが良いかもしれません。 - * デフォルトでは、このタイムアウトは、`KC_LEAD` を押してからシーケンス全体が完了するまでに掛かる時間です。これは一部の人にとっては非常に短いかもしれません。そのため、このタイムアウトを増やしたほうが良い場合もあります。必要に応じて、`LEADER_PER_KEY_TIMING` オプションを有効にしたほうが良い場合もあります。これは各キーがタップされる度にタイムアウトまでの時間をリセットする機能です。これにより、タイムアウト時間を短くしつつも、比較的長いシーケンスを使うことができます。このオプションを有効にするには、`config.h` に `#define LEADER_PER_KEY_TIMING` を追加します。 -3. `matrix_scan_user` 関数の中で、以下のようなものを追加します: - -```c -LEADER_EXTERNS(); - -void matrix_scan_user(void) { - LEADER_DICTIONARY() { - leading = false; - leader_end(); - - SEQ_ONE_KEY(KC_F) { - // マクロ内でできること - SEND_STRING("QMK is awesome."); - } - SEQ_TWO_KEYS(KC_D, KC_D) { - SEND_STRING(SS_LCTL("a") SS_LCTL("c")); - } - SEQ_THREE_KEYS(KC_D, KC_D, KC_S) { - SEND_STRING("https://start.duckduckgo.com\n"); - } - SEQ_TWO_KEYS(KC_A, KC_S) { - register_code(KC_LGUI); - register_code(KC_S); - unregister_code(KC_S); - unregister_code(KC_LGUI); - } - } -} -``` - -ご覧のとおり、幾つかの関数があります。`SEQ_ONE_KEY` を単一キーシーケンス (リーダーの後に1つのキーのみ)に使い、より長いシーケンスについては `SEQ_TWO_KEYS`、`SEQ_THREE_KEYS` から `SEQ_FIVE_KEYS` を使うことができます。 - -これらはそれぞれ1つ以上のキーコードを引数として受け付けます。これは重要な点です: **キーボードの任意のレイヤー**のキーコードを使うことができます。当たり前ですが、リーダーマクロが発動するにはそのレイヤーがアクティブである必要があります - -## `rules.mk` にリーダーキーサポートを追加 - -リーダーキーのサポートを追加するには、単純にキーマップの `rules.mk` に1行を追加します: - -```make -LEADER_ENABLE = yes -``` - -## リーダーキーのキーごとのタイミング - -長いリーダーキー文字列のためや 200wpm のタイピングスキルが無い場合に、非常に長いタイムアウト時間に頼るのではなく、キーを押すごとに入力を完了するまでの時間を増やす機能を使用することができます。これは、リーダーキーを使ってタップダンスを再現する場合に非常に役立ちます (C, C, C のような同じキーを複数回タップする場合)。 - -これを有効にするには、以下を `config.h` に配置します: -```c -#define LEADER_PER_KEY_TIMING -``` - -この後、`LEADER_TIMEOUT` を 300ms 未満に下げることをお勧めします。 - -```c -#define LEADER_TIMEOUT 250 -``` - -これで、リーダーキーのタイムアウト時間を 1000ms に設定することなく以下のようなことが可能になると思われます。 - -```c -SEQ_THREE_KEYS(KC_C, KC_C, KC_C) { - SEND_STRING("Per key timing is great!!!"); -} -``` - -## リーダーキーの無限タイムアウト - -リーダーキーが、シーケンスの残りのキーのような快適な場所にない場合があります。リーダーキーが右上の外側のキーの1つである場合、リーダーキーに届くように手の位置を変えなければならないことがあります。 -これにより、シーケンスの大部分をすばやく入力できたとしても、シーケンス全体を時間通りに入力するのが難しい場合があります。例えば、シーケンスが `Leader + asd` の場合、手をホーム行に置けば `asd` を素早く打つのは非常に簡単です。しかし、リーダーキーに届くようにホーム行から手を移動し、戻った後、時間内にシーケンスを開始することはできません。 -この状況が手に与えるストレスを取り除くために、リーダーキーだけに無限のタイムアウトを有効にすることができます。つまり、リーダーキーを押した後、シーケンスの残りを開始するまでの時間が無限になり、シーケンスの残りを快適に入力するための最適な位置に手を置くことができます。 -この無限のタイムアウトはリーダーキーにのみ影響するため、前述の `Leader + asd` の例では、`Leader` と `a` の間に無限の時間があります。ただし、シーケンスを開始すると、(グローバルまたはキーごとに)設定したタイムアウトは正常に機能します。 -このようにして、非常に短い `LEADER_TIMEOUT` を設定できますが、それでも手を置く時間は十分にあります。 - -これを有効にするには、以下を `config.h` に配置します: -```c -#define LEADER_NO_TIMEOUT -``` - -## 厳密なキー処理 - -デフォルトでは、リーダーキー機能は、リーダーシーケンスの確認時に [`モッドタップ`](ja/mod_tap.md) および [`レイヤータップ`](ja/feature_layers.md#switching-and-toggling-layers) 機能からのキーコードをフィルターします。つまり、`LT(3, KC_A)` を使っている場合、`LT(3, KC_A)` ではなくシーケンスの `KC_A` として取り出され、新しいユーザにとってより期待される動作を提供します。 - -ほとんどの場合これで問題ありませんが、シーケンスでキーコード全体(例えば、上の例での `LT(3, KC_A)`) を指定したい場合は、`config.h` ファイルに `#define LEADER_KEY_STRICT_KEY_PROCESSING` を追加することこのような機能を有効にすることができます。これでフィルタリングが無効になり、キーコード全体を指定する必要があります。 - -## カスタマイズ - -リーダーキー機能には、リーダーキー機能の動作にいくらかのカスタマイズを追加する方法があります。リーダーキー機能のプロセスの特定の部分で呼び出すことができる2つの関数、`leader_start()` と `leader_end()` です。 - -`KC_LEAD` キーがタップされた時に `leader_start()` 関数が呼ばれ、リーダーシーケンスが完了するか、リーダータイムアウトの時間に達した時に `leader_end()` 関数が呼ばれます。 - -リーダーシーケンスにフィードバック(ビープまたは音楽を再生するなど)を追加するために、これらの関数をコード (通常 は`keymap.c`)に追加することができます。 - -```c -void leader_start(void) { - // シーケンスの開始 -} - -void leader_end(void) { - // シーケンスの終了 (成功しない/失敗を検知) -} -``` - -### 例 - -この例では、リーダーシーケンスを開始するために `KC_LEAD` を押すとマリオの "One Up" 音が再生され、正常に完了した場合は "All Star" が再生され、失敗した場合は "Rick Roll" を再生されます。 - -```c -bool did_leader_succeed; -#ifdef AUDIO_ENABLE -float leader_start[][2] = SONG(ONE_UP_SOUND ); -float leader_succeed[][2] = SONG(ALL_STAR); -float leader_fail[][2] = SONG(RICK_ROLL); -#endif -LEADER_EXTERNS(); - -void matrix_scan_user(void) { - LEADER_DICTIONARY() { - did_leader_succeed = leading = false; - - SEQ_ONE_KEY(KC_E) { - // マクロ内でできること - SEND_STRING(SS_LCTL(SS_LSFT("t"))); - did_leader_succeed = true; - } else - SEQ_TWO_KEYS(KC_E, KC_D) { - SEND_STRING(SS_LGUI("r") "cmd\n" SS_LCTL("c")); - did_leader_succeed = true; - } - leader_end(); - } -} - -void leader_start(void) { -#ifdef AUDIO_ENABLE - PLAY_SONG(leader_start); -#endif -} - -void leader_end(void) { - if (did_leader_succeed) { -#ifdef AUDIO_ENABLE - PLAY_SONG(leader_succeed); -#endif - } else { -#ifdef AUDIO_ENABLE - PLAY_SONG(leader_fail); -#endif - } -} -``` diff --git a/docs/ja/feature_led_indicators.md b/docs/ja/feature_led_indicators.md deleted file mode 100644 index 94ee063234..0000000000 --- a/docs/ja/feature_led_indicators.md +++ /dev/null @@ -1,119 +0,0 @@ -# LED インジケータ - - - -QMK は HID 仕様で定義された5つの LED の読み取りメソッドを提供します: - -* Num Lock -* Caps Lock -* Scroll Lock -* Compose -* Kana - -ロック LED の状態を取得するには3つの方法があります: -* `config.h` で設定オプションを指定する -* `bool led_update_kb(led_t led_state)` あるいは `_user(led_t led_state)` を実装する、または -* `led_t host_keyboard_led_state()` を呼び出す - -!> `host_keyboard_led_state()` は `led_update_user()` が呼ばれる前に新しい値を既に反映している場合があります。 - -LED の状態を `uint8_t` として提供する2つの非推奨の関数があります: - -* `uint8_t led_set_user(uint8_t usb_led)` -* `uint8_t host_keyboard_leds()` - -## 設定オプション :id=configuration-options - -インジケータを設定するには、`config.h` で以下の `#define` をします: - -| 定義 | 既定値 | 説明 | -|-----------------------|------------|----------------------------------| -| `LED_NUM_LOCK_PIN` | *定義なし* | `Num Lock` LED を制御するピン | -| `LED_CAPS_LOCK_PIN` | *定義なし* | `Caps Lock` LED を制御するピン | -| `LED_SCROLL_LOCK_PIN` | *定義なし* | `Scroll Lock` LED を制御するピン | -| `LED_COMPOSE_PIN` | *定義なし* | `Compose` LED を制御するピン | -| `LED_KANA_PIN` | *定義なし* | `Kana` LED を制御するピン | -| `LED_PIN_ON_STATE` | `1` | LED が "オン" の時のインジケータピンの状態 - high の場合は`1`、low の場合は`0` | - -独自のキーボードを設計しているわけではない限り、通常は上記の設定オプションを変更する必要はありません。 - -## `led_update_*()` - -設定オプションが十分な柔軟性を提供しない場合は、提供される API フックにより LED の挙動の独自の制御ができます。これらの関数はこれら5つの LED のいずれかの状態が変化すると呼ばれます。LED の状態を構造体のパラメータとして受け取ります。 - -慣例により、`led_update_kb()` にそのコードを実行するようフックさせるために `led_update_user()` から `true` を返し、`led_update_kb()` でコードを実行したくない場合は `false` を返します。 - -以下はいくつかの例です: - -- レイヤー表示のような何かのために LED を使うために LED を上書きする - - `_kb()` 関数を実行したくないので、`false` を返します。これはレイヤーの挙動を上書きするためです。 -- LED がオンあるいはオフになった時に音楽を再生する。 - - `_kb` 関数を実行したいので、`true` を返します。これはデフォルトの LED の挙動に追加されます。 - -?> `led_set_*` 関数は `bool` の代わりに `void` を返すため、キーボードの LED 制御を上書きすることができません。従って、代わりに `led_update_*` を使うことをお勧めします。 - -### `led_update_kb()` の実装例 - -```c -bool led_update_kb(led_t led_state) { - bool res = led_update_user(led_state); - if(res) { - // writePin は 1 でピンを high に、0 で low に設定します。 - // この例では、ピンは反転していて、 - // low/0 は LED がオンになり、high/1 は LED がオフになります。 - // この挙動は、LED がピンと VCC の間にあるか、ピンと 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); - } - return res; -} -``` - -### `led_update_user()` の実装例 - -この不完全な例は Caps Lock がオンまたはオフになった場合に音を再生します。また LED の状態を保持する必要があるため、`true` を返します。 - -```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_update_*` 関数のドキュメント - -* キーボード/リビジョン: `bool led_update_kb(led_t led_state)` -* キーマップ: `bool led_update_user(led_t led_state)` - -## `host_keyboard_led_state()` - -最後に受信した LED の状態を `led_t` として取得するためにこの関数を呼びます。これは、`led_update_*` の外部から、例えば [`matrix_scan_user()`](#matrix-scanning-code) の中で LED の状態を読み取るのに便利です。 - -## 物理的な LED の状態の設定 - -一部のキーボードの実装は、物理的な LED の状態を設定するための便利なメソッドを提供しています。 - -### Ergodox キーボード - -Ergodox の実装は、個々の LED をオンあるいはオフにするために `ergodox_right_led_1`/`2`/`3_on`/`off()` と、インデックスによってそれらをオンあるいはオフにするために `ergodox_right_led_on`/`off(uint8_t led)` を提供します。 - -さらに、LED の明度を指定することができます。全ての LED に同じ明度を指定するなら `ergodox_led_all_set(uint8_t n)` を使い、個別の LED の明度を指定するなら `ergodox_right_led_1`/`2`/`3_set(uint8_t n)` を使い、LED のインデックスを指定して明度を指定するには `ergodox_right_led_set(uint8_t led, uint8_t n)` を使います。 - -Ergodox キーボードは、最低の明度として `LED_BRIGHTNESS_LO` を、最高の輝度(これはデフォルトです)として `LED_BRIGHTNESS_HI` も定義しています。 diff --git a/docs/ja/feature_led_matrix.md b/docs/ja/feature_led_matrix.md deleted file mode 100644 index 2b1979ec68..0000000000 --- a/docs/ja/feature_led_matrix.md +++ /dev/null @@ -1,96 +0,0 @@ -# LED マトリックスライト - - - -この機能により、外部ドライバによって駆動される LED マトリックスを使うことができます。この機能は、バックライト制御と同じキーコードを使えるようにするため、バックライトシステムに接続します。 - -RGB LED を使いたい場合は、代わりに [RGB マトリックスサブシステム](ja/feature_rgb_matrix.md) を使うべきです。 - -## ドライバ設定 - -### IS31FL3731 - -I2C IS31FL3731 RGB コントローラを使ったアドレス指定可能な LED マトリックスライトのための基本的なサポートがあります:有効にするには、`rules.mk` に以下を追加します: - - LED_MATRIX_ENABLE = yes - LED_MATRIX_DRIVER = IS31FL3731 - -1から4個の IS31FL3731 IC を使うことができます。キーボード上に存在しない IC の `LED_DRIVER_ADDR_` 定義を指定しないでください。`config.h` に以下の項目を定義することができます: - -| 変数 | 説明 | デフォルト | -|----------|-------------|---------| -| `ISSI_TIMEOUT` | (オプション) i2c メッセージを待つ時間 | 100 | -| `ISSI_PERSISTENCE` | (オプション) 失敗したメッセージをこの回数再試行する | 0 | -| `LED_DRIVER_COUNT` | (必須) LED ドライバ IC の数 | | -| `DRIVER_LED_TOTAL` | (必須) 全てのドライバの LED ライトの数 | | -| `LED_DRIVER_ADDR_1` | (必須) 最初の LED ドライバのアドレス | | -| `LED_DRIVER_ADDR_2` | (オプション) 2番目の LED ドライバのアドレス | | -| `LED_DRIVER_ADDR_3` | (オプション) 3番目の LED ドライバのアドレス | | -| `LED_DRIVER_ADDR_4` | (オプション) 4番目の LED ドライバのアドレス | | - -2つのドライバを使う例です。 - - // これは7ビットのアドレスで、左シフトされます - // ビット0に0を設定すると書き込み、1を設定すると読み込みです (I2C プロトコルに従う) - // アドレスは配線によって変わります: - // 0b1110100 AD <-> GND - // 0b1110111 AD <-> VCC - // 0b1110101 AD <-> SCL - // 0b1110110 AD <-> SDA - #define LED_DRIVER_ADDR_1 0b1110100 - #define LED_DRIVER_ADDR_2 0b1110110 - - #define LED_DRIVER_COUNT 2 - #define LED_DRIVER_1_LED_COUNT 25 - #define LED_DRIVER_2_LED_COUNT 24 - #define DRIVER_LED_TOTAL LED_DRIVER_1_LED_TOTAL + LED_DRIVER_2_LED_TOTAL - -現在、2つのドライバのみがサポートされますが、4つの組み合わせ全てをサポートすることは簡単です。 - -`.c` に全ての LED を列挙する配列を定義します: - - const is31_led PROGMEM g_is31_leds[DRIVER_LED_TOTAL] = { - /* これらの位置については IS31 マニュアルを参照してください - * driver - * | LED address - * | | */ - {0, C3_3}, - .... - } - -ここで、`Cx_y` は[データシート](https://www.issi.com/WW/pdf/31FL3731.pdf)およびヘッダファイル `drivers/led/issi/is31fl3731-simple.h` で定義されるマトリックス内の LED の位置です。`driver` は `config.h` で定義したドライバのインデックス(`0`、`1`、`2`、`3`のいずれか)です。 - -## キーコード - -現在のところ、全ての LED マトリックスのキーコードは[バックライトシステム](ja/feature_backlight.md)と共有されます。 - -## LED マトリックス効果 - -現在のところ、LED マトリックス効果は作成されていません。 - -## カスタムレイヤー効果 - -カスタムレイヤー効果は `.c` 内で以下を定義することで行うことができます: - - void led_matrix_indicators_kb(void) { - led_matrix_set_value(index, value); - } - -同様の関数がキーマップ内で `led_matrix_indicators_user` として動作します。 - -## サスペンド状態 - -サスペンド機能を使うには、以下を `.c` に追加します: - - void suspend_power_down_kb(void) - { - led_matrix_set_suspend_state(true); - } - - void suspend_wakeup_init_kb(void) - { - led_matrix_set_suspend_state(false); - } diff --git a/docs/ja/feature_macros.md b/docs/ja/feature_macros.md deleted file mode 100644 index 6371f0c20a..0000000000 --- a/docs/ja/feature_macros.md +++ /dev/null @@ -1,303 +0,0 @@ -# マクロ - - - -マクロにより、1つのキーを押すだけで複数のキーストロークを送信することができます。QMK にはマクロを定義し使う方法が幾つかあります。これらはなんでもすることができます: よく使うフレーズの入力、コピーペースト、反復的なゲームの動き、あるいはコードを書くことさえ手助けします。 - -!> **セキュリティの注意**: マクロを使って、パスワード、クレジットカード番号、その他の機密情報のいずれも送信することが可能ですが、それは非常に悪い考えです。あなたのキーボードを手に入れた人は誰でもテキストエディタを開いてその情報にアクセスすることができます。 - -## `SEND_STRING()` と `process_record_user` - -単語またはフレーズを入力するキーが欲しい時があります。最も一般的な状況のために `SEND_STRING()` を提供しています。これは文字列(つまり、文字のシーケンス)を入力します。簡単にキーコードに変換することができる全ての ASCII 文字がサポートされています (例えば、`qmk 123\n\t`)。 - -以下は2キーのキーボードのための `keymap.c` の例です: - -```c -enum custom_keycodes { - QMKBEST = SAFE_RANGE, -}; - -bool process_record_user(uint16_t keycode, keyrecord_t *record) { - switch (keycode) { - case QMKBEST: - if (record->event.pressed) { - // キーコード QMKBEST が押された時 - SEND_STRING("QMK is the best thing ever!"); - } else { - // キーコード QMKBEST が放された時 - } - break; - } - return true; -}; - -const uint16_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] = { - [0] = { - {QMKBEST, KC_ESC}, - // ... - }, -}; -``` - -ここで起きることは以下の通りです: -最初に他のキーコードで使用されていない範囲で新しいカスタムキーコードを定義します。 -次に、`process_record_user` 関数を使います。これはキーが押されるか放されるたびに呼び出され、カスタムキーコードがアクティブかどうかを確認します。 -アクティブな場合、`SEND_STRING` マクロ (これは C プロセッサのマクロで、QMK のマクロと混同しないでください)を介して文字列 `"QMK is the best thing ever!"` をコンピュータに送信します。 -呼び出し元に、処理したばかりのキー押下を通常通り(機能を置き換えたり変更したりしなかったので)処理し続けるよう指示するため、`true` を返します。 -最後に、最初のボタンがマクロをアクティブにし、2番目のボタンが単なるエスケープボタンになるようにキーマップを定義します。 - -複数のマクロを追加することもできます。 -以下のように、別のキーコードを追加し、switch 文に別の case ラベルを追加することで、それを行うことができます: - -```c -enum custom_keycodes { - QMKBEST = SAFE_RANGE, - QMKURL, - MY_OTHER_MACRO, -}; - -bool process_record_user(uint16_t keycode, keyrecord_t *record) { - switch (keycode) { - case QMKBEST: - if (record->event.pressed) { - // キーコード QMKBEST が押された時 - SEND_STRING("QMK is the best thing ever!"); - } else { - // キーコード QMKBEST が放された時 - } - break; - - case QMKURL: - if (record->event.pressed) { - // キーコード QMKURL が押された場合 - SEND_STRING("https://qmk.fm/\n"); - } else { - // キーコード QMKURL が放された場合 - } - break; - - case MY_OTHER_MACRO: - if (record->event.pressed) { - SEND_STRING(SS_LCTL("ac")); // 全てを選択しコピーします - } - break; - } - return true; -}; - -const uint16_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] = { - [0] = { - {MY_CUSTOM_MACRO, MY_OTHER_MACRO}, - // ... - }, -}; -``` - -### 高度なマクロ - -`process_record_user()` 関数のほかに、`post_process_record_user()` 関数があります。これは `process_record` の後に実行され、キーストロークが送信された後の処理に使用できます。これは例えば、通常のキーの前に押され、通常のキーの後で放されるキーがほしい場合に便利です。 - -この例では、通常のキー入力を変更して、キーストロークが通常送信される前に `F22` が押されるようにし、キーが放された__後にのみ__ `F22` キーを放します。 - -```c -static uint8_t f22_tracker; - -bool process_record_user(uint16_t keycode, keyrecord_t *record) { - switch (keycode) { - case KC_A ... KC_F21: // F22 をスキップする方法に注意してください - case KC_F23 ... KC_EXSEL: //exsel は修飾キーの直前のキーです - if (record->event.pressed) { - register_code(KC_F22); //これは F22 を押したことを送信することを意味します - f22_tracker++; - register_code(keycode); - return false; - } - break; - } - return true; -} - -void post_process_record_user(uint16_t keycode, keyrecord_t *record) { - switch (keycode) { - case KC_A ... KC_F21: // F22 をスキップする方法に注意してください - case KC_F23 ... KC_EXSEL: //exsel は修飾キーの直前のキーです - if (!record->event.pressed) { - f22_tracker--; - if (!f22_tracker) { - unregister_code(KC_F22); //これは F22 を放したことを送信することを意味します - } - } - break; - } -} -``` - - -### タップ、ダウン、アップ - -`Ctrl` あるいは `Home` など、ソースコードに文字列として表記できないキーをマクロで使うこともできます。 -以下のようにラップすることで任意のコードを送信することができます: - -* `SS_TAP()` キーを押して放します。 -* `SS_DOWN()` キーを押します (ただし、放しません)。 -* `SS_UP()` キーを放します。 - -例えば: - - SEND_STRING(SS_TAP(X_HOME)); - -`KC_HOME` をタップします - プリフィックスが `X_` で `KC_` ではないことに注意してください。以下のように、他の文字列と組み合わせることもできます: - - SEND_STRING("VE"SS_TAP(X_HOME)"LO"); - -これは "VE" に続けて `KC_HOME` をタップ、そして "LO" (新しい行の場合は "LOVE" と綴る)を送信します。 - -文字列に遅延を追加することもできます: - -* `SS_DELAY(msecs)` は指定されたミリ秒だけ遅らせます。 - -例えば: - - SEND_STRING("VE" SS_DELAY(1000) SS_TAP(X_HOME) "LO"); - -これは "VE" 、1秒の遅延、`KC_HOME` をタップ、"LO" (新しい行の場合は "LOVE" と綴るが、中間に遅延がある) を送信します。 - -使用できるモッドショートカットもいくつかあります: - -* `SS_LCTL(文字列)` -* `SS_LSFT(文字列)` -* `SS_LALT(文字列)`、`SS_LOPT(文字列)` -* `SS_LGUI(文字列)`、`SS_LCMD(文字列)`、`SS_LWIN(文字列)` -* `SS_RCTL(文字列)` -* `SS_RSFT(文字列)` -* `SS_RALT(文字列)`、`SS_ROPT(文字列)`、`SS_ALGR(文字列)` -* `SS_RGUI(文字列)`、`SS_RCMD(文字列)`、`SS_RWIN(文字列)` - -これらはそれぞれの修飾キーを押し、指定された文字列を送信してから、修飾キーを解放します。 -それらは以下のように使うことができます: - - SEND_STRING(SS_LCTL("a")); - -これは、左 Control +`a` (左 Control をダウンし、`a`、左 Control をアップ)を送信します - それらは文字列(例えば `"k"`)であり、`X_K` キーコードでは無いことに注意してください。 - -### 代替キーマップ - -デフォルトでは、QWERTY レイアウトの US キーマップを想定しています; それを変更したい場合(例えば OS がソフトウェア Colemak を使う場合)、キーマップのどこかに以下を含めます: - -```c -#include "sendstring_colemak.h" -``` - -### メモリ内の文字列 - -何らかの理由で文字列を操作していて、(リテラル、文字列定数の代わりに)生成したばかりのものを出力する必要がある場合は、以下のように `send_string()` を使うことができます: - -```c -char my_str[4] = "ok."; -send_string(my_str); -``` - -上で定義したショートカットは `send_string()` では動作しないですが、必要に応じて別の行に分けることができます: - -```c -char my_str[4] = "ok."; -SEND_STRING("I said: "); -send_string(my_str); -SEND_STRING(".."SS_TAP(X_END)); -``` - - -## 高度なマクロ関数 :id=advanced-macro-functions - -マクロの生成に役立つ関数が幾つかあります。マクロの中にかなり高度なコードを書くことができますが、機能が複雑になりすぎる場合は、代わりにカスタムキーコードを定義することをお勧めします。マクロはシンプルにしなければなりません。 - -?> 追加の機能として、[便利な関数](ja/ref_functions.md) の中で説明される関数を使うこともできます。例えば `reset_keyboard()` によりマクロの一部としてキーボードをリセットすることができます。 - -### `record->event.pressed` - -これでスイッチが押されているか放されているかどうかをテストすることができます。以下が例です。 - -```c - if (record->event.pressed) { - // キーダウン時 - } else { - // キーアップ時 - } -``` - -### `register_code();` - -これはコンピュータに `` キーダウンイベントを送信します。例として `KC_ESC`、`KC_C`、`KC_4` や、`KC_LSFT` と `KC_LGUI` のような修飾キーなどもあります。 - -### `unregister_code();` - -`register_code` 関数と対応して、これは `` キーアップイベントをコンピュータに送信します。これを使わない場合、キーは送信されるまで押し続けられます。 - -### `tap_code();` - -これは `register_code()` を送信し、その後 `unregister_code()` を送信します。押下とリリースイベントの両方を送信する場合に便利です (押し続けるのではなく、キーを"タップ"する)。 - -タップの登録(解除)に問題がある場合、`config.h` ファイルで `#define TAP_CODE_DELAY 100` を設定することで、登録イベントと解除イベントの間に遅延を追加することができます。値はミリ秒です。 - -### `register_code16();`、`unregister_code16();`、`tap_code16();` - -これらの関数は対応する通常の関数と同様に機能しますが、修飾キーで修飾されたキーコードを使うことができます (Shift、Alt、Control、GUI を適用)。 - -例えば、修飾キーを押して(`register_code()`して)、キーコードを押す(`register_code()`する)代わりに、`register_code16(S(KC_5));` を使うことができます。 - -### `clear_keyboard();` - -これは現在押されている全ての修飾キーとキーをクリアします。 - -### `clear_mods();` - -これは現在押されている全ての修飾キーをクリアします。 - -### `clear_keyboard_but_mods();` - -これは現在押されている修飾キー以外の全てのキーをクリアします。 - -## 高度な例: - -### スーパー ALT↯TAB - -このマクロは `KC_LALT` を登録し、`KC_TAB` をタップして、1000ms 待ちます。キーが再度タップされると、別の `KC_TAB` が送信されます; タップが無い場合、`KC_LALT` が登録解除され、ウィンドウを切り替えることができます。 - -```c -bool is_alt_tab_active = false; // keymap.c の先頭付近にこれを追加します -uint16_t alt_tab_timer = 0; // すぐにそれらを使います - -enum custom_keycodes { // 素晴らしいキーコードを用意してください - ALT_TAB = SAFE_RANGE, -}; - -bool process_record_user(uint16_t keycode, keyrecord_t *record) { - switch (keycode) { // これはキーコードを利用したつまらない作業のほとんどを行います。 - case ALT_TAB: - if (record->event.pressed) { - if (!is_alt_tab_active) { - is_alt_tab_active = true; - register_code(KC_LALT); - } - alt_tab_timer = timer_read(); - register_code(KC_TAB); - } else { - unregister_code(KC_TAB); - } - break; - } - return true; -} - -void matrix_scan_user(void) { // とても重要なタイマー - if (is_alt_tab_active) { - if (timer_elapsed(alt_tab_timer) > 1000) { - unregister_code(KC_LALT); - is_alt_tab_active = false; - } - } -} -``` diff --git a/docs/ja/feature_mouse_keys.md b/docs/ja/feature_mouse_keys.md deleted file mode 100644 index e4fa9dfb45..0000000000 --- a/docs/ja/feature_mouse_keys.md +++ /dev/null @@ -1,147 +0,0 @@ -# マウスキー - - - -マウスキーは、キーボードを使ってマウスをエミュレートできる機能です。様々な速度でポインタを移動し、5つのボタンを押し、8方向にスクロールすることができます。 - -## キーボードにマウスキーを追加 - -マウスキーを使うためには、少なくともマウスキーサポートを有効にし、マウスアクションをキーボードのキーにマップする必要があります。 - -### マウスキーを有効にする - -マウスキーを有効にするには、キーマップの `rules.mk` に以下の行を追加します: - -```c -MOUSEKEY_ENABLE = yes -``` - -### マウスアクションのマッピング - -キーマップでキー押下をマウスアクションにマップするために、以下のキーコードを使うことができます: - -| キー | エイリアス | 説明 | -|----------------|---------|-----------------| -| `KC_MS_UP` | `KC_MS_U` | カーソルを上に移動 | -| `KC_MS_DOWN` | `KC_MS_D` | カーソルを下に移動 | -| `KC_MS_LEFT` | `KC_MS_L` | カーソルを左に移動 | -| `KC_MS_RIGHT` | `KC_MS_R` | カーソルを右に移動 | -| `KC_MS_BTN1` | `KC_BTN1` | ボタン1を押す | -| `KC_MS_BTN2` | `KC_BTN2` | ボタン2を押す | -| `KC_MS_BTN3` | `KC_BTN3` | ボタン3を押す | -| `KC_MS_BTN4` | `KC_BTN4` | ボタン4を押す | -| `KC_MS_BTN5` | `KC_BTN5` | ボタン5を押す | -| `KC_MS_BTN6` | `KC_BTN6` | ボタン6を押す | -| `KC_MS_BTN7` | `KC_BTN7` | ボタン7を押す | -| `KC_MS_BTN8` | `KC_BTN8` | ボタン8を押す | -| `KC_MS_WH_UP` | `KC_WH_U` | ホイールを向こう側に回転 | -| `KC_MS_WH_DOWN` | `KC_WH_D` | ホイールを手前側に回転 | -| `KC_MS_WH_LEFT` | `KC_WH_L` | ホイールを左に倒す | -| `KC_MS_WH_RIGHT` | `KC_WH_R` | ホイールを右に倒す | -| `KC_MS_ACCEL0` | `KC_ACL0` | 速度を0に設定 | -| `KC_MS_ACCEL1` | `KC_ACL1` | 速度を1に設定 | -| `KC_MS_ACCEL2` | `KC_ACL2` | 速度を2に設定 | - -## マウスキーの設定 - -マウスキーはカーソルを移動するための3つの異なるモードをサポートします: - -* **加速 (デフォルト):** 移動キーを押したままにすると、カーソルが最大速度に達するまでカーソルを加速します。 -* **定速:** 移動キーを押したままにすると、カーソルを一定の速度で移動します。 -* **混合:** 移動キーを押したままにすると、カーソルが最大速度に達するまでカーソルを加速し、加速キーと移動キーを同時に押すとカーソルは一定の速度で移動します。 - -同じ原則がスクロールにも適用されます。 - -時間、間隔、遅延の設定オプションは、ミリ秒で指定されます。スクロール速度はデフォルトスクロールステップの倍数として渡されます。例えば、スクロール速度8は、各スクロールアクションがオペレーティングシステムまたはアプリケーションで定義されるデフォルトのスクロールステップの8倍の距離進むことを意味します。 - -### 加速モード - -これはデフォルトのモードです。キーマップの `config.h` ファイルの以下の設定を使ってカーソルとスクロールの加速を調整することができます: - -| 定義 | デフォルト | 説明 | -|----------------------------|-------|---------------------------------------------------------| -| `MOUSEKEY_DELAY` | 300 | 移動キーを押してからカーソルが移動するまでの遅延 | -| `MOUSEKEY_INTERVAL` | 50 | カーソル移動間の時間 | -| `MOUSEKEY_MAX_SPEED` | 10 | 加速が停止する最大のカーソル速度 | -| `MOUSEKEY_TIME_TO_MAX` | 20 | 最大カーソル速度に達するまでの時間 | -| `MOUSEKEY_WHEEL_DELAY` | 300 | ホイールキーを押してからホイールが動くまでの遅延 | -| `MOUSEKEY_WHEEL_INTERVAL` | 100 | ホイールの動きの間の時間 | -| `MOUSEKEY_WHEEL_MAX_SPEED` | 8 | スクロールアクションごとのスクロールステップの最大数 | -| `MOUSEKEY_WHEEL_TIME_TO_MAX` | 40 | 最大スクロール速度に達するまでの時間 | - -ヒント: - -* `MOUSEKEY_DELAY` の設定が低すぎるとカーソルが応答しなくなります。設定が高すぎると小さな動きが難しくなります。 -* カーソルの動きをスムーズにするには、`MOUSEKEY_INTERVAL` の値を低くします。ディスプレイのリフレッシュレートが60Hzの場合、`16` (1/60) に設定することができます。これによりカーソルの速度が大幅に向上するため、`MOUSEKEY_MAX_SPEED` を下げた方が良いかもしれません。 -* `MOUSEKEY_TIME_TO_MAX` または `MOUSEKEY_WHEEL_TIME_TO_MAX` を `0` に設定すると、それぞれカーソルの速度またはスクロールの加速が無効になります。この方法では、一方を加速しながら他方を一定にすることができますが、これは定速モードでは不可能です。 -* `MOUSEKEY_WHEEL_INTERVAL` の設定が低すぎるとスクロールがとても速くなります。設定が高すぎるとホイールキーを押したままにした時にスクロールがとても遅くなります - -カーソルの加速は、X Window System MouseKeysAccel 機能と同じアルゴリズムを使います。詳細については [Wikipedia](https://en.wikipedia.org/wiki/Mouse_keys) をご覧ください。 - -### 定速モード - -このモードでは、カーソルおよびマウスホイールの両方について複数の異なる速度を定義することができます。加速はありません。`KC_ACL0`、`KC_ACL1` および `KC_ACL2` は、カーソルとスクロールの速度をそれぞれの設定に変更します。 - -速度の選択は、一時的とタップ選択のどちらかを選べます: - -* **一時的:** 選択された速度は、それぞれのキーを押している間のみアクティブになります。キーを放すと、マウスキーは変更される前の速度に戻ります。 -* **タップ選択:** それぞれのキーを押すと選択された速度がアクティブになり、キーを放した後もアクティブのままになります。デフォルトの速度は `KC_ACL1` です。未変更の速度はありません。 - -最も遅い速度から最も速い速度までのデフォルトの速度は以下の通りです: - -* **一時的:** `KC_ACL0` < `KC_ACL1` < *変更無し* < `KC_ACL2` -* **タップ選択:** `KC_ACL0` < `KC_ACL1` < `KC_ACL2` - -定速モードを使うには、少なくともキーマップの keymaps ディレクトリの `config.h` ファイルに `MK_3_SPEED` を定義する必要があります。 - -```c -#define MK_3_SPEED -``` - -一時的モードを有効にするには、`MK_MOMENTARY_ACCEL` も定義します: - -```c -#define MK_MOMENTARY_ACCEL -``` - -カーソル移動あるいはスクロールを調整する場合は、以下の設定を使います: - -| 定義 | デフォルト | 説明 | -|---------------------|-------------|-------------------------------------------| -| `MK_3_SPEED` | *定義なし* | 定速カーソルを有効にする | -| `MK_MOMENTARY_ACCEL` | *定義なし* | 一時的モードを有効にする | -| `MK_C_OFFSET_UNMOD` | 16 | 移動ごとのカーソルオフセット (変更無し) | -| `MK_C_INTERVAL_UNMOD` | 16 | カーソルの移動間の時間 (変更無し) | -| `MK_C_OFFSET_0` | 1 | 移動ごとのカーソルオフセット (`KC_ACL0`) | -| `MK_C_INTERVAL_0` | 32 | カーソル移動間の時間 (`KC_ACL0`) | -| `MK_C_OFFSET_1` | 4 | 移動ごとのカーソルオフセット (`KC_ACL1`) | -| `MK_C_INTERVAL_1` | 16 | カーソル移動間の時間 (`KC_ACL1`) | -| `MK_C_OFFSET_2` | 32 | 移動ごとのカーソルオフセット (`KC_ACL2`) | -| `MK_C_INTERVAL_2` | 16 | カーソル移動間の時間 (`KC_ACL2`) | -| `MK_W_OFFSET_UNMOD` | 1 | スクロールアクションごとのスクロールステップ (変更無し) | -| `MK_W_INTERVAL_UNMOD` | 40 | スクロールステップ間の時間 (変更無し) | -| `MK_W_OFFSET_0` | 1 | スクロールアクションごとのスクロールステップ (`KC_ACL0`) | -| `MK_W_INTERVAL_0` | 360 | スクロールステップ間の時間 (`KC_ACL0`) | -| `MK_W_OFFSET_1` | 1 | スクロールアクションごとのスクロールステップ (`KC_ACL1`) | -| `MK_W_INTERVAL_1` | 120 | スクロールステップ間の時間 (`KC_ACL1`) | -| `MK_W_OFFSET_2` | 1 | スクロールアクションごとのスクロールステップ (`KC_ACL2`) | -| `MK_W_INTERVAL_2` | 20 | スクロールステップ間の時間 (`KC_ACL2`) | - -### 混合モード - -このモードは **加速** モードのように機能しますが、`KC_ACL0`、`KC_ACL1`、`KC_ACL2` を押したままにすることで -一時的(押している間)にカーソルとスクロール速度を定速に設定できます。 -加速キーが押されていない場合、このモードは **加速** モードと同じで、関連する全ての設定を使って変更できます。 - -* **KC_ACL0:** この加速はカーソルをできるだけ遅い速度に設定します。これはカーソルを非常に小さく詳細に移動する場合に便利です。 -* **KC_ACL1:** この加速はカーソルを最大(ユーザ定義)速度の半分に設定します。 -* **KC_ACL2:** この加速はカーソルを最大(コンピュータ定義)速度に設定します。これは、正確性を多少犠牲にしてカーソルを大きく移動する場合に便利です。 - -混合モードを使うには、キーマップの `config.h` ファイルに少なくとも `MK_COMBINED` を定義しなければなりません: - -```c -#define MK_COMBINED -``` diff --git a/docs/ja/feature_pointing_device.md b/docs/ja/feature_pointing_device.md deleted file mode 100644 index 0f472f0ffe..0000000000 --- a/docs/ja/feature_pointing_device.md +++ /dev/null @@ -1,58 +0,0 @@ -# ポインティングデバイス :id=pointing-device - - - -ポインティングデバイスは汎用的な機能の総称です: システムポインタを移動します。マウスキーのような他のオプションも確かにありますが、これは簡単に変更可能で軽量であることを目指しています。機能を制御するためにカスタムキーを実装したり、他の周辺機器から情報を収集してここに直接挿入したりできます - QMK に処理を任せてください。 - -ポインティングデバイスを有効にするには、rules.mk の以下の行のコメントを解除します: - -```makefile -POINTING_DEVICE_ENABLE = yes -``` - -マウスレポートを操作するために、以下の関数を使うことができます: - -* `pointing_device_get_report()` - ホストコンピュータに送信された情報を表す現在の report_mouse_t を返します。 -* `pointing_device_set_report(report_mouse_t mouse_report)` - ホストコンピュータに送信される report_mouse_t を上書き保存します。 - -report_mouse_t (ここでは "mouseReport") が以下のプロパティを持つことを覚えておいてください: - -* `mouseReport.x` - これは、x軸の動き(+ 右へ、- 左へ)を表す -127 から 127 (128ではなく、USB HID 仕様で定義されています)の符号付き整数です。 -* `mouseReport.y` - これは、y軸の動き(+ 上へ、- 下へ)を表す -127 から 127 (128ではなく、USB HID 仕様で定義されています)の符号付き整数です。 -* `mouseReport.v` - これは、垂直スクロール(+ 上へ、- 下へ)を表す -127 から 127 (128ではなく、USB HID 仕様で定義されています)の符号付き整数です。 -* `mouseReport.h` - これは、水平スクロール(+ 右へ、- 左へ)を表す -127 から 127 (128ではなく、USB HID 仕様で定義されています)の符号付き整数です。 -* `mouseReport.buttons` - これは uint8_t で、8ビット全てを使っています。これらのビットはマウスボタンの状態を表します - ビット 0 はマウスボタン 1、ビット 7 はマウスボタン 8 です。 - -マウスレポートに必要な変更を行ったら、それを送信する必要があります: - -* `pointing_device_send()` - マウスレポートをホストに送信し、レポートをゼロにします。 - -マウスレポートが送信されると、x、y、v、h のいずれの値も 0 に設定されます (これは `pointing_device_send()` で行われます。この挙動を回避するためにオーバーライドすることができます)。このように、ボタンの状態は持続しますが、動きは1度だけ起こります。さらにカスタマイズするために、`pointing_device_init` と `pointing_device_task` のどちらもオーバーライドすることができます。 - -さらに、デフォルトでは、`pointing_device_send()` はレポートが実際に変更された場合のみレポートを送信します。これにより、マウスレポートが継続的に送信されてホストシステムが起動されたままになることを防ぎます。この動作は、独自の `pointing_device_send()` 関数を作成することで変更できます。 - -また、`has_mouse_report_changed(new_report, old_report)` 関数を使って、レポートが変更されたかどうかを確認できます。(訳注：独自の `pointing_device_send()` 関数を作成する場合でも、その中で `has_mouse_report_changed(new_report, old_report)` 関数でチェックして、デフォルトの `pointing_device_send()` と類似の無駄なレポートの抑制をして、ホストシステムがスリープ状態に入れる余地を残すようにしておくのが良いでしょう。) - -以下の例では、カスタムキーを使ってマウスをクリックし垂直および水平方向に127単位スクロールし、リリースされた時にそれを全て元に戻します - なぜならこれは完全に便利な機能だからです。いいですか、以下はひとつの例です: - -```c -case MS_SPECIAL: - report_mouse_t currentReport = pointing_device_get_report(); - if (record->event.pressed) { - currentReport.v = 127; - currentReport.h = 127; - currentReport.buttons |= MOUSE_BTN1; // this is defined in report.h - } else { - currentReport.v = -127; - currentReport.h = -127; - currentReport.buttons &= ~MOUSE_BTN1; - } - pointing_device_set_report(currentReport); - pointing_device_send(); - break; -``` - -マウスレポートは送信されるたびに 0 (ボタンを除く)に設定されることを思い出してください。そのため、スクロールはそれぞれの場合に1度だけ発生します。 diff --git a/docs/ja/feature_ps2_mouse.md b/docs/ja/feature_ps2_mouse.md deleted file mode 100644 index 2798f61283..0000000000 --- a/docs/ja/feature_ps2_mouse.md +++ /dev/null @@ -1,288 +0,0 @@ -# PS/2 マウスサポート :id=ps2-mouse-support - - - -PS/2 マウス (例えばタッチパッドあるいはトラックポイント)を複合デバイスとしてキーボードに接続することができます。 - -トラックポイントを接続するには、トラックポイントモジュールを入手し (つまり、Thinkpad キーボードから部品を取って)、モジュールの各ピンの機能を特定し、コントローラとトラックポイントモジュールの間に必要な回路を作成する必要があります。詳細については、Deskthority Wiki の[トラックポイントハードウェア](https://deskthority.net/wiki/TrackPoint_Hardware)ページを参照してください。 - -PS/2 デバイスの接続は、USART(最善)、割り込み(次善)、 または busywait(非推奨)の3つのやり方が有ります。 - -## トラックポイントとコントローラ間の回路 :id=the-circuitry-between-trackpoint-and-controller - -動作させるには、DATA と CLK のふたつのラインを 4.7k の抵抗で 5V にプルアップしてやる必要があります。 - -``` - DATA ----------+--------- PIN - | - 4.7K - | -MODULE 5+ --------+--+--------- PWR CONTROLLER - | - 4.7K - | - CLK ------+------------ PIN -``` - - -## Busywait バージョン :id=busywait-version - -注意: これは非推奨です。ギクシャクした動きや、未送信の入力が発生するかもしれません。可能であれば、割り込みまたは USART バージョンを使ってください。 - -rules.mk で: - -```makefile -PS2_MOUSE_ENABLE = yes -PS2_ENABLE = yes -PS2_DRIVER = busywait -``` - -キーボードの config.h で: - -```c -#ifdef PS2_DRIVER_BUSYWAIT -# define PS2_CLOCK_PIN D1 -# define PS2_DATA_PIN D2 -#endif -``` - -## 割り込みバージョン :id=interrupt-version - -以下の例はクロックのために D2 を、データのために D5 を使います。クロックには任意の INT あるいは PCINT ピンを、データには任意のピンを使うことができます。 - -rules.mk で: - -```makefile -PS2_MOUSE_ENABLE = yes -PS2_ENABLE = yes -PS2_DRIVER = interrupt -``` - -キーボードの config.h で: - -```c -#ifdef PS2_DRIVER_INTERRUPT -#define PS2_CLOCK_PIN D2 -#define PS2_DATA_PIN D5 - -#define PS2_INT_INIT() do { \ - EICRA |= ((1< - -Raw HID は、HID インタフェースを介して QMK とホストコンピュータ間の双方向通信を可能にします。これには、キーマップをその場で切り替えたり、RGB LED の色とモードを変更したりなど、多くの潜在的な使用方法があります。 - -キーボードで raw HID を機能させるには、2つの主要なコンポーネントがあります。 - -## キーボードファームウェア - -ファームウェアの実装はとても簡単です。 -`rules.mk` に以下を追加します: - -```make -RAW_ENABLE = yes -``` - -`keymap.c` に `"raw_hid.h"` を include し、以下を実装します: - -```C -void raw_hid_receive(uint8_t *data, uint8_t length) { - // ここにコードを書きます。data はホストから受信したパケットです。 -} -``` - -`"raw_hid.h"` ヘッダは、キーボードからホストにパケットを送信できる `void raw_hid_send(uint8_t *data, uint8_t length);` も宣言します。例として、全てのデータをホストに返すことで、ホストアプリケーションを構築する時のデバッグに使うこともできます。 - -```C -void raw_hid_receive(uint8_t *data, uint8_t length) { - raw_hid_send(data, length); -} -``` - -これら2つの関数は、ホストとの間で長さ `RAW_EPSIZE` バイトのパケットを送受信します (LUFA/ChibiOS/V-USB では 32、ATSAM では 64)。 - -ホスト側での作業を進める前に、raw 対応のファームウェアを書き込むようにしてください。 - -## ホスト (Windows/macOS/Linux) - -これは幾つかの掘り下げが必要になるため、より複雑な部分です。 - -ホストコンピュータを raw HID を使ってキーボードに接続するには、キーボードについての4つの情報が必要です。 - -1. Vendor ID -2. Product ID -3. Usage Page -4. Usage - -前半の2つは、キーボードのメインディレクトリにあるキーボードの `config.h` で、`VENDOR_ID` と `PRODUCT_ID` で簡単に見つかります。 - -後半の2つは、キーボードのメインディレクトリにあるキーボードの `config.h` で、値を再定義することで上書きすることができます: `#define RAW_USAGE_PAGE 0xFF60` と `#define RAW_USAGE_ID 0x61`。 - -デフォルトでは、**Usage Page** は `0xFF60` で、**Usage** は `0x61` です。 - -### ホストの構築 - -独自に作成したくない場合は、利用可能な HID 実装ライブラリがある任意の言語を使ってホストを構築することができます。人気のある言語でよく使われるライブラリは以下の通りです: - -* Node: [node-hid](https://github.com/node-hid/node-hid)。 -* C: [hidapi](https://github.com/libusb/hidapi)。 -* Java: [purejavahidapi](https://github.com/nyholku/purejavahidapi) と [hid4java](https://github.com/gary-rowe/hid4java)。 -* Python: [pyhidapi](https://pypi.org/project/hid/)。 - -これは完全なクロスプラットフォームのリストではありませんが、最初に始めるのに十分なはずです。raw HID を使うための特別な要件は無いため、どの HID ライブラリでも動作するはずです。 - -これで、キーボードへの HID インタフェースを開くために必要な4つの情報全てが揃いました。必要なのは、ライブラリの利用可能な関数を使って ID パラメータを使ってデバイスを開くことだけです。 - -Vendor ID と Product ID はデバイスを開くために実際には必要ないことに注意してください。それらは接続した多くの HID デバイスから特定のデバイスをフィルターするためだけに使われます。多くのライブラリでは、代わりに製品名と製造元名を使ってデバイスを開くオプションがあります。`node-hid` が代表的な例です。これは USB ハブが組み込まれているデバイスや、同じ製品名または同じ製造元の複数のインタフェースがある特別な HID インタフェースで問題になります。Product ID と Vendor ID を合わせると単一のインタフェースの固有名を作成できるため、この問題を防げます。したがって、ライブラリで必要が無い場合でも、この問題を防ぐためにそれらを使うことをお勧めします。 -ただし、Vendor ID や Product ID と異なり、Usage Page と Usage は通信を成功させるために必要です。 - -言うまでもなく、使っているライブラリに関係なく、終了したらインタフェースを必ず閉じる必要があります。オペレーティングシステムと特定の環境によっては、明示的に接続が閉じられていない場合、後で他のクライアントまたは同じクライアントの他のインスタンスに接続しなおした時に問題が発生する可能性があります。 diff --git a/docs/ja/feature_split_keyboard.md b/docs/ja/feature_split_keyboard.md deleted file mode 100644 index c84b782d87..0000000000 --- a/docs/ja/feature_split_keyboard.md +++ /dev/null @@ -1,251 +0,0 @@ -# 分割キーボード - - - -QMK ファームウェアリポジトリの多くのキーボードは、"分割"キーボードです。それらは2つのコントローラを使います — 1つは USB に接続し、もう1つは TRRS または同様のケーブルを介してシリアルまたは I2C 接続で接続します。 - -分割キーボードには多くの利点がありますが、有効にするには追加の作業が必要です。 - -QMK ファームウェアには、任意のキーボードで使用可能な一般的な実装と、多くのキーボード固有の実装があります。 - -このため、主に Let's Split とその他のキーボードで使われる一般的な実装について説明します。 - -!> ARM はまだ完全には分割キーボードをサポートしておらず、様々な制限があります。進捗はしていますが、機能の100%にはまだ達していません。 - - -## 互換性の概要 - -| Transport | AVR | ARM | -|------------------------------|--------------------|--------------------| -| ['serial'](ja/serial_driver.md) | :heavy_check_mark: | :white_check_mark: 1 | -| I2C | :heavy_check_mark: | | - -注意: - -1. ハードウェアとソフトウェアの両方の制限は、[ドライバーのドキュメント](ja/serial_driver.md)の中で説明されます。 - -## ハードウェア設定 - -2つの Pro Micro 互換のコントローラを使っており、キーボードの左右を接続するために TRRS ジャックを使っていることを前提とします。 - -### ハードウェア要件 - -左右それぞれのキーボードマトリックスのためのダイオードとスイッチとは別に、2個の TRRS ソケットと 1本の TRRS ケーブルが必要です。 - -あるいは、少なくとも3本のワイヤがあるケーブルとソケットを使うことができます。 - -キーボードの左右間で通信するために I2C を使いたい場合は、少なくとも4本のワイヤを備えたケーブルと 2個の 4.7kΩ プルアップ抵抗が必要です。 - -#### 考慮事項 - -最も一般的に使われる接続は、TRRS ケーブルとジャックです。これらは4本のワイヤを提供し、分割キーボードに非常に有用で、簡単に見つけることができます。 - -ただし、ワイヤのうちの1本が Vcc を供給するため、キーボードはホットプラグ不可能です。TRRS ケーブルを抜き差しする前に、必ずキーボードのUSB接続をはずす必要があります。そうしなければ、コントローラを短絡させたり、もっと悪いことが起こるかもしれません。 - -別のオプションは電話ケーブルを使うことです (例えば、旧式の RJ-11/RJ-14 ケーブル)。実際に4本のワイヤ/レーンをサポートするものを使うようにしてください。 - -ただし、USB ケーブル、SATA ケーブル、そして単に4本の電線でもコントローラ間の通信に使用できることがわかっています。 - -!> コントローラ間の通信に USB ケーブルを使っても問題ありませんが、コネクタは通常の USB 接続と間違えられるかもしれず、配線方法によってはキーボードが短絡する可能性があります。このため、分割キーボードの接続のためにはお勧めできません。 - -### シリアル配線 - -2つの Pro Micro 間で GND、Vcc、D0/D1/D2/D3 (別名 PD0/PD1/PD2/PD3) を TRS/TRRS ケーブルの3本のワイヤで接続します。 - -?> ここで使われるピンは実際には以下の `SOFT_SERIAL_PIN` によって設定されることに注意してください。 - -sk-pd0-connection-mono -sk-pd2-connection-mono - -### I2C 配線 - -2つの Pro Micro 間で GND、Vcc、さらに SCL と SDA (それぞれ 別名 PD0/ピン3 および PD1/ピン2) を TRRS ケーブルの4本のワイヤで接続します。 - -プルアップ抵抗はキーボードの左右どちら側にも配置することができます。もし各側を単独で使いたい場合は、4つの抵抗を使い、両側にプルアップ抵抗を配置することもできます。 - -sk-i2c-connection-mono - -## ファームウェア設定 - -分割キーボード機能を有効にするには、以下を `rules.mk` に追加してください: - -```make -SPLIT_KEYBOARD = yes -``` - -カスタムトランスポート (通信メソッド)を使っている場合は、以下を追加する必要もあります: - -```make -SPLIT_TRANSPORT = custom -``` - -### 左右の設定 - -デフォルトでは、ファームウェアはどちら側がどちらであるかを認識しません; 決定するには幾つかの助けが必要です。これを行うには幾つかの方法があり、以下に優先順に列挙します。 - -#### ピンによる左右の設定 - -左右を決定するためにコントローラ上のピンを読むようにファームウェアを設定することができます。これを行うには、以下を `config.h` ファイルに追加します: - -```c -#define SPLIT_HAND_PIN B7 -``` - -これは指定されたピンを読み込みます。high の場合、コントローラはそれを左側だと仮定し、low の場合、それは右側であると仮定します。 - -#### マトリックスピンによる左右の設定 - -左右を決定するためにコントローラのキーマトリックスピンを読むようにファームウェアを設定することができます。これを行うには、以下を `config.h` ファイルに追加します: - -```c -#define SPLIT_HAND_MATRIX_GRID D0, F1 -``` - -最初のピンは出力ピンで、2つ目は入力ピンです。 - -キーマトリックスに未使用の交点があるキーボードがあります。この設定は、左右の決定にこれらの未使用の交点の1つを使用します。 - -通常、ダイオードが交点に接続されている場合、右側と判断されます。次の定義を追加すると、左側と判断されます。 - -```c -#define SPLIT_HAND_MATRIX_GRID_LOW_IS_LEFT -``` - -#### EEPROM による左右の設定 - -このメソッドは永続ストレージ(`EEPROM`)のフラグを設定することで、キーボードの左右を設定します。これはコントローラが最初に起動する時にチェックされ、キーボードのどちら側であるかとキーボードのレイアウトの向きを決定します。 - - -このメソッドを有効にするには、以下を `config.h` ファイルに追加します: - -```c -#define EE_HANDS -``` - -ただし、各コントローラに正しい側の EEPROM ファイルを書き込む必要があります。これを手動で行うこともできますが、ファームウェアを書き込む時にこれを行う avrdude および dfu のターゲットが存在します。 - -* `:avrdude-split-left` -* `:avrdude-split-right` -* `:dfu-split-left` -* `:dfu-split-right` -* `:dfu-util-split-left` -* `:dfu-util-split-right` - -この設定は、`EEP_RST` キーや `eeconfig_init()` 関数を使って EEPROM を再初期化する時には変更されません。ただし、ファームウェアの組み込みオプション以外で EEPROM をリセット([QMK Toolbox]() の "Reset EEPROM" ボタンの動作のように、`EEPROM` を上書きするファイルを書きこむなど)した場合、`EEPROM` ファイルを再書き込みする必要があります。 - -`EEPROM` ファイルは、QMK ファームウェアのリポジトリ内の[ここ](https://github.com/qmk/qmk_firmware/tree/master/quantum/split_common)にあります。 - -#### `#define` による左右の設定 - -コンパイル時に左右を設定することができます。これは以下を `config.h` ファイルに追加することで行うことができます: - -```c -#define MASTER_RIGHT -``` - -あるいは - -```c -#define MASTER_LEFT -``` - -どちらも定義されていない場合、左右のデフォルトは `MASTER_LEFT` になります。 - - -### 通信オプション - -全ての分割キーボードが同一であるとは限らないため、`config.h` ファイル内で設定することができる多くの追加のオプションがあります。 - -```c -#define USE_I2C -``` - -これは分割キーボードの I2C サポートを有効にします。これは厳密には通信用ではありませんが、OLED あるいは I2C ベースのデバイスに使うことができます。 - -```c -#define SOFT_SERIAL_PIN D0 -``` - -これはシリアル通信用に使われるピンを設定します。シリアルを使っていない場合は、これを定義する必要はありません。 - -ただし、キーボード上でシリアルおよび I2C を使っている場合は、これを設定し、D0 および D1 以外の値に設定する必要があります (これらは I2C 通信のために使われます)。 - -```c -#define SELECT_SOFT_SERIAL_SPEED {#}` -``` - -シリアル通信に問題がある場合は、この値を変更して、シリアル用の通信速度を制御することができます。デフォルトは1で、可能な値は以下の通りです: - -* **`0`**: 約189kbps (実験用途専用) -* **`1`**: 約137kbps (デフォルト) -* **`2`**: 約75kbps -* **`3`**: 約39kbps -* **`4`**: 約26kbps -* **`5`**: 約20kbps - -### ハードウェア設定オプション - -ハードウェアのセットアップ方法に基づいて、設定する必要のある設定が幾つかあります。 - -```c -#define MATRIX_ROW_PINS_RIGHT { } -#define MATRIX_COL_PINS_RIGHT { } -``` - -これにより、右側のマトリックスに異なるピンのセットを指定することができます。これは、左右の形が違うキーボード (Keebio の Quefrency など)で、左右で別の構成が必要な場合に便利です。 - -```c -#define DIRECT_PINS_RIGHT { { F1, F0, B0, C7 }, { F4, F5, F6, F7 } } -``` - -これにより右側のための異なる直接ピンのセットを指定することができます。 - -```c -#define ENCODERS_PAD_A_RIGHT { encoder1a, encoder2a } -#define ENCODERS_PAD_B_RIGHT { encoder1b, encoder2b } -``` - -これにより右側のための異なるエンコーダピンのセットを指定することができます。 - -```c -#define RGBLIGHT_SPLIT -``` - -このオプションは、分割キーボードのコントローラ間で RGB ライトモードの同期を有効にします。これはコントローラに直接配線されている RGB LED を持つキーボード用です (つまり、それらは TRRS ケーブルで "追加データ"オプションを使っていません)。 - -```c -#define RGBLED_SPLIT { 6, 6 } -``` - -これは各コントローラに直接接続されている LED の数を設定します。最初の数は左側、2番目の数は右側です。 - -?> この設定は `RGBLIGHT_SPLIT` が有効になっていることを意味し、有効になっていない場合は強制的に有効にします。 - - -```c -#define SPLIT_USB_DETECT -``` -このオプションは、スタートアップの挙動を変更して、マスタ/スレーブの決定時にアクティブな USB 接続を検出します。このオプションがタイムアウトになった場合、その片側はスレーブと見なされます。これは ARM のデフォルトの挙動で、AVR Teensy ボードに必要です (ハードウェアの制限のため)。 - -?> この設定はバッテリパックを使ったデモの機能を停止します。 - -```c -#define SPLIT_USB_TIMEOUT 2000 -``` -これは、`SPLIT_USB_DETECT` を使う時のマスタ/スレーブを検出する場合の最大タイムアウトを設定します。 - -```c -#define SPLIT_USB_TIMEOUT_POLL 10 -``` -これは `SPLIT_USB_DETECT` を使う時のマスタ/スレーブを検出する場合のポーリング頻度を設定します - -## 追加のリソース(英語) - -Nicinabox には Let's Split キーボードのための[非常に優れた詳細なガイド](https://github.com/nicinabox/lets-split-guide)があり、トラブルシューティング情報を含む知っておくべきほとんど全てをカバーします。 - -ただし、RGB ライトセクションは、RGB Split コードが QMK ファームウェアに追加されるずっと前に書かれたため、古くなっています。ガイドに従う代わりに、各 LED テーブ(訳注: LED strip とも呼びます)を直接コントローラに配線します。 - - diff --git a/docs/ja/feature_stenography.md b/docs/ja/feature_stenography.md deleted file mode 100644 index 9551221696..0000000000 --- a/docs/ja/feature_stenography.md +++ /dev/null @@ -1,135 +0,0 @@ -# QMK での速記 :id=stenography-in-qmk - - - -[速記](https://en.wikipedia.org/wiki/Stenotype)は裁判所のレポート、字幕および耳が不自由な人のためのリアルタイムの文字起こしで最もよく使われる記述方法です。速記では単語はスペル、音声およびショートカット(短い)ストロークが混在する音節ごとに音節化されます。プロの速記者は、標準的なタイピングで通常見られる負担を掛けずに、はるかに少ないエラー(99.9%より高い精度)で、200-300 WPM に到達できます。 - -[Open Steno Project](https://www.openstenoproject.org/)は、速記ストロークを単語とコマンドにリアルタイムに変換する Plover と呼ばれるオープンソースプログラムを構築しました。確立された辞書とサポートがあります。 - -## QWERTY キーボードを使った Plover :id=plover-with-qwerty-keyboard - -Plover は全ての標準的な QWERTY キーボードで動作しますが、キーボードが NKRO (n-キーロールオーバー)をサポートする場合は Plover は一度に押された全てのキーが分かるためより効率的です。Plover 用のキーマップの例は `planck/keymaps/default` で見つかります。`PLOVER` レイヤーに切り替えると、数字バーをサポートするためにキーボードの位置が調整されます。 - -QMK で Plover を使うには、NKRO を有効にし、標準レイアウト以外のレイアウトの場合はオプションでレイアウトを調整します。複数のキーを押しやすくするために、なんらかの速記フレンドリなキーキャップを購入することもできます。 - -## 速記プロトコルを使った Plover :id=plover-with-steno-protocol - -Plover は幾つかの速記マシンの言語も理解します。QMK はこれらの言語の内2つの言語、TX Bolt と GeminiPR を話すことができます。レイアウトの例は `planck/keymaps/steno` で見つけることができます。 - -QMKが steno プロトコルを使って Plover と話す場合は、Plover は入力としてキーボードを使いません。標準のキーボードと速記キーボードを行き来したり、あるいは Plover をアクティブ/非アクティブにする必要なく Plover と標準のレイヤーを行き来することができることを意味します。 - -このモードでは、Plover はシリアルポートを介して速記マシンと通信すると想定しているため、QMK はオペレーティングシステムに対してキーボードに加えて仮想シリアルポートとして存在しています。デフォルトでは、QMK は TX Bolt プロトコルを話しますが、GeminiPR に切り替えることができます; 最後に使われたプロトコルが不揮発性メモリに格納されるため QMK は再起動時に同じプロトコルを使います。 - -> 注意: ハードウェアの制限により、仮想シリアルポートとマウスエミュレーションの両方を同時に実行することができないかもしれません。 - -### TX Bolt :id=tx-bolt - -TX Bolt は可変サイズ(1-5バイト)のパケットで非常に単純なプロトコルを介して24個のキーのステータスを通信します。 - -### GeminiPR :id=geminipr - -GeminiPR は42個のキーを6バイトのパケットにエンコードします。TX Bolt は標準的な速記に必要な全てを含んでいますが、GeminiPR は英語以外の速記法のサポートを含む、より多くのオプションにも開け放たれています。 - -## 速記のための QMK の設定 :id=configuring-qmk-for-steno - -最初にキーマップの Makefile で速記を有効にします。競合を避けるために、マウスキー、追加キーあるいはその他の USB エンドポイントを無効にする必要もあります。幾つかのプロセッサの内蔵の USB スタックは一定数の USB エンドポイントと仮想シリアルポートのみをサポートし、速記はそれらのうちの3つを使います。 - -```makefile -STENO_ENABLE = yes -MOUSEKEY_ENABLE = no -``` - -キーマップで Plover 用の新しいレイヤーを作成します。`keymap_steno.h` をインクルードする必要があります。例については `planck/keymaps/steno/keymap.c` を見てください。レイヤーに切り替えるためのキーとレイヤーから抜けるためのキーを作成することを忘れないでください。その場でモードを切り替えたい場合は、キーコード `QK_STENO_BOLT` および `QK_STENO_GEMINI` を使うことができます。プロトコルのうちの1つのみを使う場合は、初期化関数の中でそれをセットアップすることができます: - -```c -void eeconfig_init_user() { - steno_set_mode(STENO_MODE_GEMINI); // あるいは STENO_MODE_BOLT -} -``` - -キーボードを書き込んだら、Plover を起動します。'Configure...' ボタンをクリックします。'Machine' タブの中で目的のプロトコルに対応する速記マシンを選択します。このタブの 'Configure...' ボタンをクリックし、シリアルポートを入力するか 'Scan' をクリックします。ボーレートは 9600 で問題ありません (ただし、115200まで問題無く設定することができるはずです)。それ以外はデフォルトの設定(データビット長: 8、ストップビット長: 1、パリティチェック: なし、フロー制御なし)を使います。 - -ディスプレイタブで 'Open stroke display' をクリックします。Plover を無効にすると、キーボードのキーを押すとストローク表示ウィンドウにそれらが表示されるはずです。これを使ってキーマップが正しくセットアップされたことを確認してください。これで速記をする準備ができました！ - -## 速記の学習 :id=learning-stenography - -* [Learn Plover!](https://sites.google.com/site/learnplover/) -* [Steno Jig](https://joshuagrams.github.io/steno-jig/) -* Plover [Learning Stenography](https://github.com/openstenoproject/plover/wiki/Learning-Stenography) wiki のより多くのリソース - -## コードとのインターフェイス :id=interfacing-with-the-code - -速記コードには3つの捕捉可能なフックがあります。これらの関数を定義した場合、処理の特定のポイントでそれらが呼び出されます; それらが true を返す場合処理が継続され、そうでなければあなたが物事を処理すると想定します。 - -```c -bool send_steno_chord_user(steno_mode_t mode, uint8_t chord[6]); -``` - -この関数はコードが送信されようとしている時に呼ばれます。モードは `STENO_MODE_BOLT` あるいは `STENO_MODE_GEMINI` のいずれかです。これはいずれかのプロトコルを介して送信される実際のコードを表します。提供されるコードを修正して送信されるものを変更することができます。通常の送信プロセスにしたい場合は true を返すのを忘れないでください。 - -```c -bool process_steno_user(uint16_t keycode, keyrecord_t *record) { return true; } -``` - -この関数はキーが押されるとキーが処理される前に呼び出されます。キーコードは `QK_STENO_BOLT`、`QK_STENO_GEMINI` あるいは `STN_*` キー値のいずれかでなければなりません。 - -```c -bool post_process_steno_user(uint16_t keycode, keyrecord_t *record, steno_mode_t mode, uint8_t chord[6], int8_t pressed); -``` - -この関数はキーが処理された後、ただしコードを送信するかどうかを決める前に呼び出されます。`record->event.pressed` が false で、`pressed` が 0 または 1 の場合は、コードはまもなく送信されますが、まだ送信されてはいません。ここが速記コードあるいはキーのライブ表示などのフックを配置する場所です。 - - -## キーコードリファレンス :id=keycode-reference - -`keymap_steno.h` で定義されています。 - -> 注意: TX Bolt はキーの完全なセットをサポートしません。QMK での TX Bolt の実装は、GeminiPR キーを最も近い TX Bolt キーにマップします。そのため1つのキーマップが両方で動作します。 - -| GeminiPR | TX Bolt | Steno Key | -|--------|-------|-----------| -| `STN_N1` | `STN_NUM` | Number bar #1 | -| `STN_N2` | `STN_NUM` | Number bar #2 | -| `STN_N3` | `STN_NUM` | Number bar #3 | -| `STN_N4` | `STN_NUM` | Number bar #4 | -| `STN_N5` | `STN_NUM` | Number bar #5 | -| `STN_N6` | `STN_NUM` | Number bar #6 | -| `STN_N7` | `STN_NUM` | Number bar #7 | -| `STN_N8` | `STN_NUM` | Number bar #8 | -| `STN_N9` | `STN_NUM` | Number bar #9 | -| `STN_NA` | `STN_NUM` | Number bar #A | -| `STN_NB` | `STN_NUM` | Number bar #B | -| `STN_NC` | `STN_NUM` | Number bar #C | -| `STN_S1` | `STN_SL` | `S-` upper | -| `STN_S2` | `STN_SL` | `S-` lower | -| `STN_TL` | `STN_TL` | `T-` | -| `STN_KL` | `STN_KL` | `K-` | -| `STN_PL` | `STN_PL` | `P-` | -| `STN_WL` | `STN_WL` | `W-` | -| `STN_HL` | `STN_HL` | `H-` | -| `STN_RL` | `STN_RL` | `R-` | -| `STN_A` | `STN_A` | `A` vowel | -| `STN_O` | `STN_O` | `O` vowel | -| `STN_ST1` | `STN_STR` | `*` upper-left | -| `STN_ST2` | `STN_STR` | `*` lower-left | -| `STN_ST3` | `STN_STR` | `*` upper-right | -| `STN_ST4` | `STN_STR` | `*` lower-right | -| `STN_E` | `STN_E` | `E` vowel | -| `STN_U` | `STN_U` | `U` vowel | -| `STN_FR` | `STN_FR` | `-F` | -| `STN_PR` | `STN_PR` | `-P` | -| `STN_RR` | `STN_RR` | `-R` | -| `STN_BR` | `STN_BR` | `-B` | -| `STN_LR` | `STN_LR` | `-L` | -| `STN_GR` | `STN_GR` | `-G` | -| `STN_TR` | `STN_TR` | `-T` | -| `STN_SR` | `STN_SR` | `-S` | -| `STN_DR` | `STN_DR` | `-D` | -| `STN_ZR` | `STN_ZR` | `-Z` | -| `STN_FN` | (GeminiPR のみ) | -| `STN_RES1` | (GeminiPR のみ) | -| `STN_RES2` | (GeminiPR のみ) | -| `STN_PWR` | (GeminiPR のみ) | diff --git a/docs/ja/feature_swap_hands.md b/docs/ja/feature_swap_hands.md deleted file mode 100644 index cd0b150e50..0000000000 --- a/docs/ja/feature_swap_hands.md +++ /dev/null @@ -1,36 +0,0 @@ -# スワップハンドアクション - - - -スワップハンドアクションにより、別のレイヤーを必要とせずに片手入力をサポートします。Makefile に `SWAP_HANDS_ENABLE` を設定し、キーマップに `hand_swap_config` エントリを定義します。これで `ACTION_SWAP_HANDS` コマンドキーが押されるたびにキーボードがミラーされます。例えば、QWERTY で "Hello, World" を入力するには、`^Ge^s^s^w^c W^wr^sd` を入力します。 - -## 設定 - -設定テーブルは列/行から新しい列/行にマップするための単純な2次元配列です。Planck の `hand_swap_config` の例: - -```C -const keypos_t PROGMEM hand_swap_config[MATRIX_ROWS][MATRIX_COLS] = { - {{11, 0}, {10, 0}, {9, 0}, {8, 0}, {7, 0}, {6, 0}, {5, 0}, {4, 0}, {3, 0}, {2, 0}, {1, 0}, {0, 0}}, - {{11, 1}, {10, 1}, {9, 1}, {8, 1}, {7, 1}, {6, 1}, {5, 1}, {4, 1}, {3, 1}, {2, 1}, {1, 1}, {0, 1}}, - {{11, 2}, {10, 2}, {9, 2}, {8, 2}, {7, 2}, {6, 2}, {5, 2}, {4, 2}, {3, 2}, {2, 2}, {1, 2}, {0, 2}}, - {{11, 3}, {10, 3}, {9, 3}, {8, 3}, {7, 3}, {6, 3}, {5, 3}, {4, 3}, {3, 3}, {2, 3}, {1, 3}, {0, 3}}, -}; -``` - -配列のインデックスはマトリックスと同様に逆になり、値の型は `{col, row}` である `keypos_t` で、全ての値はゼロベースであることに注意してください。上の例では、`hand_swap_config[2][4]` (第3行, 第5列)は `{7, 2}` (第3行, 第8列) を返します。はい。紛らわしいです。 - -## キーコードの入れ替え - -| キー | 説明 | -|-----------|-------------------------------------------------------------------------| -| `SH_T(key)` | タップで `key` を送信する。押している時の一時的な入れ替え。 | -| `SH_ON` | 入れ替えをオンにして、そのままにする。 | -| `SH_OFF` | 入れ替えをオフにして、そのままにする。既知の状態に戻るのに適しています。 | -| `SH_MON` | 押すとスワップハンドし、放すと通常に戻る (一時的)。 | -| `SH_MOFF` | 一時的に入れ替えをオフする。 | -| `SH_TG` | キーを押すたびに入れ替えのオンとオフを切り替える。 | -| `SH_TT` | タップで切り替える。押されている時の一時的なもの。 | -| `SH_OS` | ワンショットスワップハンド: 押されている時あるいは次のキーを押すまで切り替える。 | diff --git a/docs/ja/feature_tap_dance.md b/docs/ja/feature_tap_dance.md deleted file mode 100644 index b4e025d282..0000000000 --- a/docs/ja/feature_tap_dance.md +++ /dev/null @@ -1,530 +0,0 @@ -# タップダンス: 1つのキーが3つ、5つまたは100の異なる動作をします - - - -## イントロダクション :id=introduction - -セミコロンキーを1回叩くと、セミコロンが送信されます。2回素早く叩くと、コロンが送信されます。3回叩くと、あなたのキーボードのLEDが激しく踊るように明滅します。これは、タップダンスでできることの一例です。それは、コミュニティが提案したとても素敵なファームウェアの機能の1つで、[algernon](https://github.com/algernon) がプルリクエスト [#451](https://github.com/qmk/qmk_firmware/pull/451) で考えて作ったものです。algernon が述べる機能は次の通りです: - -この機能を使うと、特定のキーが、タップした回数に基づいて異なる振る舞いをします。そして、割り込みがあった時は、割り込み前に上手く処理されます。 - -## タップダンスの使い方 :id=how-to-use -最初に、あなたの `rules.mk` ファイルで `TAP_DANCE_ENABLE = yes` と設定する必要があります。なぜならば、デフォルトでは無効になっているからです。これでファームウェアのサイズが1キロバイトほど増加します。 - -オプションで、あなたの `config.h` ファイルに次のような設定を追加して、`TAPPING_TERM` の時間をカスタマイズしたほうが良いです。 - -```c -#define TAPPING_TERM 175 -``` - -`TAPPING_TERM` の時間は、あなたのタップダンスのキーのタップとタップの間の時間として許可された最大の時間で、ミリ秒単位で計測されます。例えば、もし、あなたがこの上にある `#define` ステートメントを使い、1回タップすると `Space` が送信され、2回タップすると `Enter` が送信されるタップダンスキーをセットアップした場合、175ミリ秒以内に2回キーをタップすれば `ENT` だけが送信されるでしょう。もし、1回タップしてから175ミリ秒以上待ってからもう一度タップすると、`SPC SPC` が送信されます。 - -次に、いくつかのタップダンスのキーを定義するためには、`TD()` マクロを使うのが最も簡単です。これは数字を受け取り、この数字は後で `tap_dance_actions` 配列のインデックスとして使われます。 - -その後、`tap_dance_actions` 配列を使って、タップダンスキーを押した時のアクションを定義します。現在は、5つの可能なオプションがあります: - -* `ACTION_TAP_DANCE_DOUBLE(kc1, kc2)`: 1回タップすると `kc1` キーコードを送信し、2回タップすると `kc2` キーコードを送信します。キーを押し続けているときは、適切なキーコードが登録されます: キーを押し続けた場合は `kc1`、一度タップしてから続けてもう一度キーを押してそのまま押し続けたときは、 `kc2` が登録されます。 -* `ACTION_TAP_DANCE_LAYER_MOVE(kc, layer)`: 1回タップすると `kc` キーコードが送信され、2回タップすると `layer` レイヤーに移動します(これは `TO` レイヤーキーコードのように機能します)。 -* `ACTION_TAP_DANCE_LAYER_TOGGLE(kc, layer)`: 1回タップすると `kc` キーコードが送信され、2回タップすると `layer` の状態をトグルします(これは `TG` レイヤーキーコードのように機能します)。 -* `ACTION_TAP_DANCE_FN(fn)`: ユーザーキーマップに定義した指定の関数が呼び出されます。タップダンス実行の回数分タップすると、最後の時点で呼び出されます。 -* `ACTION_TAP_DANCE_FN_ADVANCED(on_each_tap_fn, on_dance_finished_fn, on_dance_reset_fn)`: タップする度にユーザーキーマップに定義した最初の関数が呼び出されます。タップダンスの実行が終わった時点で2番目の関数が呼び出され、タップダンスの実行をリセットするときに最後の関数が呼び出されます。 -* ~~`ACTION_TAP_DANCE_FN_ADVANCED_TIME(on_each_tap_fn, on_dance_finished_fn, on_dance_reset_fn, tap_specific_tapping_term)`~~: これは `ACTION_TAP_DANCE_FN_ADVANCED` 関数と同じように機能します。しかし、`TAPPING_TERM` で事前に定義した時間の代わりに、カスタマイズしたタップ時間を使います。 - * [ここ](ja/custom_quantum_functions.md#Custom_Tapping_Term)で概説するように、これはキーごとのタッピング時間機能を優先して非推奨になりました。この特定のタップダンス機能を使う代わりに、使いたい特定の `TD()` マクロ(`TD(TD_ESC_CAPS)` のような)を確認する必要があります。 - - -最初のオプションで、1つのキーに2つの役割を持たせる大抵のケースには十分です。例えば、`ACTION_TAP_DANCE_DOUBLE(KC_SPC, KC_ENT)` は、1回タップすると `Space` を送信し、2回タップすると `Enter` を送信します。 - -!> ここでは [基本的なキーコード](ja/keycodes_basic.md) だけがサポートされていることを覚えておいてください。カスタムキーコードはサポートされていません。 - -最初のオプションに似ていますが、2番目のオプションは単純なレイヤー切替のケースに適しています。 - -これ以上に複雑なケースの場合、3番目か4番目のオプションを使います。（以下でそれらの例を列挙します） - -最後に、5番目のオプションは、もし、タップダンスキーをコードに追加した後、非タップダンスキーが奇妙な振る舞いを始めた時に特に役に立ちます。ありうる問題は、あなたがタップダンスキーを使いやすくするために `TAPPING_TERM` の時間を変更した結果、その他のキーが割り込みを処理する方法が変わってしまったというものです。 - - -## 実装の詳細 :id=implementation - -さて、説明の大部分はここまでです！ 以下に挙げているいくつかの例に取り組むことができるようになり、あなた自身のタップダンスの機能を開発できるようになります。しかし、もし、あなたが裏側で起きていることをより深く理解したいのであれば、続けてそれが全てどのように機能するかの説明を読みましょう！ - -メインエントリーポイントは、`process_tap_dance()` で、`process_record_quantum()` から呼び出されます。これはキーを押すたびに実行され、ハンドラは早期に実行されます。この関数は、押されたキーがタップダンスキーがどうか確認します。 -もし、押されたキーがタップダンスキーではなく、かつ、タップダンスが実行されていたなら、最初にそれを処理し、新しく押されたキーをキューに格納します。 -もし、押されたキーがタップダンスキーであるなら、既にアクティブなタップダンスと同じキーか確認します（もしアクティブなものがある場合、それと）。 -異なる場合、まず、古いタップダンスを処理し、続いて新しいタップダンスを登録します。 -同じ場合、カウンタの値を増やし、タイマーをリセットします。 - -このことは、あなたは再びキーをタップするまでの時間として `TAPPING_TERM` の時間を持っていることを意味します。そのため、あなたは1つの `TAPPING_TERM` の時間内に全てのタップを行う必要はありません。これにより、キーの反応への影響を最小限に抑えながら、より長いタップ回数を可能にします。 - -次は `tap_dance_task()` です。この関数はタップダンスキーのタイムアウトを制御します。 - -柔軟性のために、タップダンスは、キーコードの組み合わせにも、ユーザー関数にもなることができます。後者は、より高度なタップ回数の制御や、LED を点滅させたり、バックライトをいじったり、等々の制御を可能にします。これは、1つの共用体と、いくつかの賢いマクロによって成し遂げられています。 - -## 実装例 :id=examples - -### シンプルな実装例 :id=simple-example - -ここに1つの定義のための簡単な例があります。 - -1. `rules.mk` に `TAP_DANCE_ENABLE = yes` を追加します。 -2. `config.h` ファイル（`qmk_firmware/keyboards/planck/config.h` からあなたのキーマップディレクトリにコピーできます）に `#define TAPPING_TERM 200` を追加します。 -3. `keymap.c` ファイルに変数とタップダンスの定義を定義し、それからキーマップに追加します。 - -```c -// タップダンスの宣言 -enum { - TD_ESC_CAPS, -}; - -// タップダンスの定義 -qk_tap_dance_action_t tap_dance_actions[] = { - // 1回タップすると Escape キー、2回タップすると Caps Lock。 - [TD_ESC_CAPS] = ACTION_TAP_DANCE_DOUBLE(KC_ESC, KC_CAPS), -}; - -// キーマップにキーコードの代わりにタップダンスの項目を追加します -const uint16_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] = { - // ... - TD(TD_ESC_CAPS) - // ... -}; -``` - -### 複雑な実装例 :id=complex-examples - -このセクションでは、いくつかの複雑なタップダンスの例を詳しく説明します。 -例で使われている全ての列挙型はこのように宣言します。 - -```c -// 全ての例のための列挙型定義 -enum { - CT_SE, - CT_CLN, - CT_EGG, - CT_FLSH, - X_TAP_DANCE -}; -``` -#### 例1: 1回タップすると `:` を送信し、2回タップすると `;` を送信する :id=example-1 - -```c -void dance_cln_finished(qk_tap_dance_state_t *state, void *user_data) { - if (state->count == 1) { - register_code16(KC_COLN); - } else { - register_code(KC_SCLN); - } -} - -void dance_cln_reset(qk_tap_dance_state_t *state, void *user_data) { - if (state->count == 1) { - unregister_code16(KC_COLN); - } else { - unregister_code(KC_SCLN); - } -} - -// 全てのタップダンス関数はここに定義します。ここでは1つだけ示します。 -qk_tap_dance_action_t tap_dance_actions[] = { - [CT_CLN] = ACTION_TAP_DANCE_FN_ADVANCED(NULL, dance_cln_finished, dance_cln_reset), -}; -``` - -#### 例2: 100回タップした後に "Safety Dance!" を送信します :id=example-2 - -```c -void dance_egg(qk_tap_dance_state_t *state, void *user_data) { - if (state->count >= 100) { - SEND_STRING("Safety dance!"); - reset_tap_dance(state); - } -} - -qk_tap_dance_action_t tap_dance_actions[] = { - [CT_EGG] = ACTION_TAP_DANCE_FN(dance_egg), -}; -``` - -#### 例3: 1つずつ LED を点灯させてから消灯する :id=example-3 - -```c -// タップする毎に、LED を右から左に点灯します。 -// 4回目のタップで、右から左に消灯します。 -void dance_flsh_each(qk_tap_dance_state_t *state, void *user_data) { - switch (state->count) { - case 1: - ergodox_right_led_3_on(); - break; - case 2: - ergodox_right_led_2_on(); - break; - case 3: - ergodox_right_led_1_on(); - break; - case 4: - ergodox_right_led_3_off(); - wait_ms(50); - ergodox_right_led_2_off(); - wait_ms(50); - ergodox_right_led_1_off(); - } -} - -// 4回目のタップで、キーボードをフラッシュ状態にセットします。 -void dance_flsh_finished(qk_tap_dance_state_t *state, void *user_data) { - if (state->count >= 4) { - reset_keyboard(); - } -} - -// もしフラッシュ状態にならない場合、LED を左から右に消灯します。 -void dance_flsh_reset(qk_tap_dance_state_t *state, void *user_data) { - ergodox_right_led_1_off(); - wait_ms(50); - ergodox_right_led_2_off(); - wait_ms(50); - ergodox_right_led_3_off(); -} - -// 全てのタップダンス関数を一緒に表示しています。この例3は "CT_FLASH" です。 -qk_tap_dance_action_t tap_dance_actions[] = { - [CT_SE] = ACTION_TAP_DANCE_DOUBLE(KC_SPC, KC_ENT), - [CT_CLN] = ACTION_TAP_DANCE_FN_ADVANCED(NULL, dance_cln_finished, dance_cln_reset), - [CT_EGG] = ACTION_TAP_DANCE_FN(dance_egg), - [CT_FLSH] = ACTION_TAP_DANCE_FN_ADVANCED(dance_flsh_each, dance_flsh_finished, dance_flsh_reset) -}; -``` - -#### 例4: クアッドファンクションのタップダンス :id=example-4 - -[DanielGGordon](https://github.com/danielggordon) によるもの - -キーを押す回数と、キーを押し続けるかタップするかによって、1つのキーに4つ（またはそれ以上）の機能を持たせることができるようになります。 - -以下に例をあげます: -* 1回タップ = `x` を送信 -* 押し続ける = `Control` を送信 -* 2回タップ = `Escape` を送信 -* 2回タップして押し続ける = `Alt` を送信 - -'クアッドファンクションのタップダンス' を利用できるようにするには、いくつかのものが必要になります。 - -`keymap.c` ファイルの先頭、つまりキーマップの前に、以下のコードを追加します。 - -```c -typedef enum { - TD_NONE, - TD_UNKNOWN, - TD_SINGLE_TAP, - TD_SINGLE_HOLD, - TD_DOUBLE_TAP, - TD_DOUBLE_HOLD, - TD_DOUBLE_SINGLE_TAP, // Send two single taps - TD_TRIPLE_TAP, - TD_TRIPLE_HOLD -} td_state_t; - -typedef struct { - bool is_press_action; - td_state_t state; -} td_tap_t; - -// タップダンスの列挙型 -enum { - X_CTL, - SOME_OTHER_DANCE -}; - -td_state_t cur_dance(qk_tap_dance_state_t *state); - -// xタップダンスのための関数。キーマップで利用できるようにするため、ここに置きます。 -void x_finished(qk_tap_dance_state_t *state, void *user_data); -void x_reset(qk_tap_dance_state_t *state, void *user_data); -``` - -次に、`keymap.c` ファイルの末尾に、次のコードを追加する必要があります。 - -```c -/* 実行されるタップダンスの種類に対応する整数を返します。 - * - * タップダンスの状態を判別する方法: 割り込みと押下。 - * - * 割り込み: - * タップダンスの状態が「割り込み」の場合、他のキーがタップ時間中に押されたことを意味します。 - * これは通常、キーを「タップ」しようとしていることを示します。 - * - * 押下: - * キーがまだ押されているかどうか。この値が true の場合、タップ時間が終了したことを意味しますが、 - * キーはまだ押されたままです。これは通常、キーが「ホールド」されていることを意味します。 - * - * タップダンスに関して、qmk ソフトウェアで現在不可能なことの1つは、"permissive hold" 機能を - * 模倣することです。 - * 一般に、高度なタップダンスは一般的に入力される文字で使われた場合にうまく機能しません。 - * 例えば "A" の場合。タップダンスは文字の入力中に入力しない文字以外のキーで使うのが最適です。 - * - * 高度なタップダンスを配置するのに適した場所: - * z、q、x、j、k、v、b、ファンクションキー、home/end、コンマ、セミコロン - * - * タップダンスキーの「最適な配置場所」の基準: - * 文章中で頻繁に入力するキーでないこと - * ダブルタップに頻繁に使われるキーでないこと。例えば、'tab' はターミナルやウェブフォームで - * しばしばダブルタップされます。そのため、タップダンスでは 'tab' は良い選択ではありません。 - * 一般的な単語で2回続けて使われる文字でないこと。例えば 'pepper' 中の 'p'。もしタップダンス機能が - * 文字 'p' に存在する場合、'pepper' という単語は入力するのが非常にいらだたしいものになるでしょう。 - * - * 3つ目の点については、'TD_DOUBLE_SINGLE_TAP' が存在しますが、これは完全にはテストされていません - * - */ -td_state_t cur_dance(qk_tap_dance_state_t *state) { - if (state->count == 1) { - if (state->interrupted || !state->pressed) return TD_SINGLE_TAP; - // キーは割り込まれていませんが、まだ押し続けられています。'HOLD' を送信することを意味します。 - else return TD_SINGLE_HOLD; - } else if (state->count == 2) { - // TD_DOUBLE_SINGLE_TAP は "pepper" と入力することと、'pp' と入力したときに実際に - // ダブルタップしたい場合とを区別するためのものです。 - // この戻り値の推奨されるユースケースは、'ダブルタップ' 動作やマクロではなく、 - // そのキーの2つのキー入力を送信したい場合です。 - if (state->interrupted) return TD_DOUBLE_SINGLE_TAP; - else if (state->pressed) return TD_DOUBLE_HOLD; - else return TD_DOUBLE_TAP; - } - - // 誰も同じ文字を3回入力しようとしていないと仮定します(少なくとも高速には)。 - // タップダンスキーが 'KC_W' で、"www." と高速に入力したい場合、ここに例外を追加して - // 'TD_TRIPLE_SINGLE_TAP' を返し、'TD_DOUBLE_SINGLE_TAP' のようにその列挙型を定義する必要があります。 - if (state->count == 3) { - if (state->interrupted || !state->pressed) return TD_TRIPLE_TAP; - else return TD_TRIPLE_HOLD; - } else return TD_UNKNOWN; -} - -//'x' タップダンスの 'td_tap_t' のインスタンスを生成します。 -static td_tap_t xtap_state = { - .is_press_action = true, - .state = TD_NONE -}; - -void x_finished(qk_tap_dance_state_t *state, void *user_data) { - xtap_state.state = cur_dance(state); - switch (xtap_state.state) { - case TD_SINGLE_TAP: register_code(KC_X); break; - case TD_SINGLE_HOLD: register_code(KC_LCTRL); break; - case TD_DOUBLE_TAP: register_code(KC_ESC); break; - case TD_DOUBLE_HOLD: register_code(KC_LALT); break; - // 最後の case は高速入力用です。キーが `f` であると仮定します: - // 例えば、`buffer` という単語を入力するとき、`Esc` ではなく `ff` を送信するようにします。 - // 高速入力時に `ff` と入力するには、次の文字は `TAPPING_TERM` 以内に入力する必要があります。 - // `TAPPING_TERM` はデフォルトでは 200ms です。 - case TD_DOUBLE_SINGLE_TAP: tap_code(KC_X); register_code(KC_X); - } -} - -void x_reset(qk_tap_dance_state_t *state, void *user_data) { - switch (xtap_state.state) { - case TD_SINGLE_TAP: unregister_code(KC_X); break; - case TD_SINGLE_HOLD: unregister_code(KC_LCTRL); break; - case TD_DOUBLE_TAP: unregister_code(KC_ESC); break; - case TD_DOUBLE_HOLD: unregister_code(KC_LALT); - case TD_DOUBLE_SINGLE_TAP: unregister_code(KC_X); - } - xtap_state.state = TD_NONE; -} - -qk_tap_dance_action_t tap_dance_actions[] = { - [X_CTL] = ACTION_TAP_DANCE_FN_ADVANCED(NULL, x_finished, x_reset) -}; -``` - -これで、キーマップのどこでも簡単に `TD(X_CTL)` マクロが使えます。 - -> この設定の "hold" は、タップダンスのタイムアウト（`ACTION_TAP_DANCE_FN_ADVANCED_TIME` 参照）の **後** に起こります。即座に "hold" を得るためには、条件から `state->interrupted` の確認を除きます。結果として、複数回のタップのための時間をより多く持つことで快適な長いタップの期限を使うことができ、そして、"hold" のために長く待たないようにすることができます(2倍の `TAPPING TERM` で開始してみてください)。 - -#### 例5: タップダンスを高度なモッドタップとレイヤータップキーに使う :id=example-5 - -タップダンスは、タップされたコードが基本的なキーコード以外の場合に、 `MT()` と `LT()` マクロをエミュレートするのに利用できます。これは、通常 `Shift` を必要とする '(' や '{' のようなキーや、`Control + X` のように他の修飾されたキーコードをタップされたキーコードとして送信することに役立ちます。 - -あなたのレイヤーとカスタムキーコードの下に、以下のコードを追加します。 - -```c -// タップダンスのキーコード -enum td_keycodes { - ALT_LP // 例: 押していると `LALT`、タップすると `(`。それぞれのタップダンスの追加のキーコードを追加します -}; - -// 必要な数のタップダンス状態を含むタイプを定義します -typedef enum { - TD_NONE, - TD_UNKNOWN, - TD_SINGLE_TAP, - TD_SINGLE_HOLD, - TD_DOUBLE_SINGLE_TAP -} td_state_t; - -// タップダンスの状態の型のグローバルインスタンスを作ります -static td_state_t td_state; - -// タップダンス関数を宣言します: - -// 現在のタップダンスの状態を特定するための関数 -td_state_t cur_dance(qk_tap_dance_state_t *state); - -// それぞれのタップダンスキーコードに適用する `finished` と `reset` 関数 -void altlp_finished(qk_tap_dance_state_t *state, void *user_data); -void altlp_reset(qk_tap_dance_state_t *state, void *user_data); -``` - -キーレイアウト（`LAYOUT`）の下に、タップダンスの関数を定義します。 - -```c -// 返却するタップダンス状態を特定します -td_state_t cur_dance(qk_tap_dance_state_t *state) { - if (state->count == 1) { - if (state->interrupted || !state->pressed) return TD_SINGLE_TAP; - else return TD_SINGLE_HOLD; - } - - if (state->count == 2) return TD_DOUBLE_SINGLE_TAP; - else return TD_UNKNOWN; // 上記で返却する最大の状態の値より大きい任意の数 -} - -// 定義する各タップダンスキーコードのとりうる状態を制御します: - -void altlp_finished(qk_tap_dance_state_t *state, void *user_data) { - td_state = cur_dance(state); - switch (td_state) { - case TD_SINGLE_TAP: - register_code16(KC_LPRN); - break; - case TD_SINGLE_HOLD: - register_mods(MOD_BIT(KC_LALT)); // レイヤータップキーの場合、ここでは `layer_on(_MY_LAYER)` を使います - break; - case TD_DOUBLE_SINGLE_TAP: // タップ時間内に2つの括弧 `((` の入れ子を可能にします - tap_code16(KC_LPRN); - register_code16(KC_LPRN); - } -} - -void altlp_reset(qk_tap_dance_state_t *state, void *user_data) { - switch (td_state) { - case TD_SINGLE_TAP: - unregister_code16(KC_LPRN); - break; - case TD_SINGLE_HOLD: - unregister_mods(MOD_BIT(KC_LALT)); // レイヤータップキーの場合、ここでは `layer_off(_MY_LAYER)` を使います - break; - case TD_DOUBLE_SINGLE_TAP: - unregister_code16(KC_LPRN); - } -} - -// 各タップダンスキーコードの `ACTION_TAP_DANCE_FN_ADVANCED()` を定義し、`finished` と `reset` 関数を渡します -qk_tap_dance_action_t tap_dance_actions[] = { - [ALT_LP] = ACTION_TAP_DANCE_FN_ADVANCED(NULL, altlp_finished, altlp_reset) -}; -``` - -それぞれのタップダンスキーコードをキーマップに含めるときは、`TD()` マクロでキーコードをラップします。例: `TD(ALT_LP)` - -#### 例6: タップダンスを一時的なレイヤー切り替えとレイヤートグルキーに使う :id=example-6 - -タップダンスは、MO(layer) と TG(layer) 機能を模倣することにも使用できます。この例では、1回タップすると `KC_QUOT` 、1回押してそのまま押し続けたら `MO(_MY_LAYER)` 、2回タップしたときは `TG(_MY_LAYER)` として機能するキーを設定します。 - -最初のステップは、あなたの `keymap.c` ファイルの最初のあたりに以下のコードを追加することです。 - -```c -// 必要な数のタップダンス状態のタイプを定義します -typedef enum { - TD_NONE, - TD_UNKNOWN, - TD_SINGLE_TAP, - TD_SINGLE_HOLD, - TD_DOUBLE_TAP -} td_state_t; - -typedef struct { - bool is_press_action; - td_state_t state; -} td_tap_t; - -enum { - QUOT_LAYR, // カスタムタップダンスキー。他のタップダンスキーはこの列挙型に追加します -}; - -// タップダンスキーで使われる関数を宣言します - -// 全てのタップダンスに関連する関数 -td_state_t cur_dance(qk_tap_dance_state_t *state); - -// 個別のタップダンスに関連する関数 -void ql_finished(qk_tap_dance_state_t *state, void *user_data); -void ql_reset(qk_tap_dance_state_t *state, void *user_data); -``` - -あなたの `keymap.c` ファイルの最後の方に以下のコードを追加します。 - -```c -// 現在のタップダンスの状態を決定します -td_state_t cur_dance(qk_tap_dance_state_t *state) { - if (state->count == 1) { - if (!state->pressed) return TD_SINGLE_TAP; - else return TD_SINGLE_HOLD; - } else if (state->count == 2) return TD_DOUBLE_TAP; - else return TD_UNKNOWN; -} - -// この例のタップダンスキーに関連付けられた "tap" 構造体を初期化します -static td_tap_t ql_tap_state = { - .is_press_action = true, - .state = TD_NONE -}; - -// タップダンスキーの動作をコントロールする関数 -void ql_finished(qk_tap_dance_state_t *state, void *user_data) { - ql_tap_state.state = cur_dance(state); - switch (ql_tap_state.state) { - case TD_SINGLE_TAP: - tap_code(KC_QUOT); - break; - case TD_SINGLE_HOLD: - layer_on(_MY_LAYER); - break; - case TD_DOUBLE_TAP: - // レイヤーが既にセットされているか確認します - if (layer_state_is(_MY_LAYER)) { - // レイヤーが既にセットされていたら、オフにします。 - layer_off(_MY_LAYER); - } else { - // レイヤーがセットされていなかったら、オンにします。 - layer_on(_MY_LAYER); - } - break; - } -} - -void ql_reset(qk_tap_dance_state_t *state, void *user_data) { - // キーを押し続けていて今離したら、レイヤーをオフに切り替えます。 - if (ql_tap_state.state == TD_SINGLE_HOLD) { - layer_off(_MY_LAYER); - } - ql_tap_state.state = TD_NONE; -} - -// タップダンスキーを機能に関連付けます -qk_tap_dance_action_t tap_dance_actions[] = { - [QUOT_LAYR] = ACTION_TAP_DANCE_FN_ADVANCED_TIME(NULL, ql_finished, ql_reset, 275) -}; -``` - -上記のコードは、前の例で使われたコードに似ています。注意する1つのポイントは、必要に応じてレイヤーを切り替えられるように、どのレイヤーがアクティブになっているかいつでも確認できる必要があることです。これを実現するために、引数で与えられた `layer` がアクティブなら `true` を返す `layer_state_is(layer)` を使います。 - -`cur_dance()` と `ql_tap_state` の使い方は、上の例と似ています。 - -`ql_finished` 関数における `case: TD_SINGLE_TAP` は、上の例と似ています。`TD_SINGLE_HOLD` の case では、`ql_reset()` と連動してタップダンスキーを押している間 `_MY_LAYER` に切り替わり、キーを離した時に `_MY_LAYER` から離れます。これは、`MO(_MY_LAYER)` に似ています。`TD_DOUBLE_TAP` の case では、`_MY_LAYER` がアクティブレイヤーかどうかを確認することによって動きます。そして、その結果に基づいてレイヤーのオン・オフをトグルします。これは `TG(_MY_LAYER)` に似ています。 - -`tap_dance_actions[]` は、上の例に似ています。 `ACTION_TAP_DANCE_FN_ADVANCED()` の代わりに `ACTION_TAP_DANCE_FN_ADVANCED_TIME()` を使ったことに注意してください。 -この理由は、私は、非タップダンスキーを使うにあたり `TAPPING_TERM` が短い(175ミリ秒以内)方が好きなのですが、タップダンスのアクションを確実に完了させるには短すぎるとわかったからです——そのため、ここでは時間を275ミリ秒に増やしています。 - -最後に、このタップダンスキーを動かすため、忘れずに `TD(QUOT_LAYR)` を `keymaps[]` に加えてください。 diff --git a/docs/ja/feature_thermal_printer.md b/docs/ja/feature_thermal_printer.md deleted file mode 100644 index 508123bd64..0000000000 --- a/docs/ja/feature_thermal_printer.md +++ /dev/null @@ -1,15 +0,0 @@ -# 感熱式プリンタ - - - - - -## 感熱式プリンタのキーコード - -| キー | 説明 | -|-----------|----------------------------------------| -| `PRINT_ON` | ユーザが入力した全ての印刷を開始 | -| `PRINT_OFF` | ユーザが入力した全ての印刷を停止 | diff --git a/docs/ja/feature_unicode.md b/docs/ja/feature_unicode.md deleted file mode 100644 index 2158678f3c..0000000000 --- a/docs/ja/feature_unicode.md +++ /dev/null @@ -1,266 +0,0 @@ -# Unicode サポート - - - -Unicode 文字はキーボードから直接入力することができます！ただし幾つかの制限があります。 - -キーボードで Unicode サポートを有効にするには、以下の事をする必要があります: - -1. サポートされている Unicode 実装のいずれかを選択します: [Basic Unicode](#basic-unicode)、[Unicode Map](#unicode-map)、[UCIS](#ucis)。 -2. オペレーティングシステムとセットアップに最適な[入力モード](#input-modes)を見つけます。 -3. コンフィギュレーションに適切な入力モード(または複数のモード)を[設定](#setting-the-input-mode)します。 -4. キーマップに Unicode キーコードを追加します。 - - -## 1. メソッド :id=methods - -QMK は、Unicode 入力を有効にし、キーマップに Unicode 文字を追加するための3つの異なる方法をサポートします。それぞれに柔軟性と使いやすさの点で長所と短所があります。あなたの使い方に最適なものを選んでください。 - -ほとんどのユーザには Basic Unicode で十分です。ただし、サポートされる文字の範囲が広い(絵文字、珍しい記号など)ことが必要な場合には、Unicode Map を使う必要があります。 - -
- -### 1.1. Basic Unicode :id=basic-unicode - -多少制限はありますが、最も使いやすい方法です。Unicode 文字をキーコードとしてキーマップ自体に格納するため、`0x7FFF` までのコードポイントのみをサポートします。これは、ほとんどの現代言語(東アジアを含む)の文字と記号を対象としますが、絵文字は対象外です。 - -以下を `rules.mk` に追加します: - -```make -UNICODE_ENABLE = yes -``` - -次に、`UC(c)` キーコードをキーマップに追加します。ここで、_c_ は目的の文字のコードポイントです (できれば16進数で最大4桁の長さが望ましいです)。例えば、`UC(0x40B)` は [Ћ](https://unicode-table.com/en/040B/) を出力し、`UC(0x30C4)` は [ツ](https://unicode-table.com/en/30C4) を出力します。 - -
- -### 1.2. Unicode Map :id=unicode-map - -このメソッドは、標準の文字の範囲に加えて、絵文字、古代文字、珍しい記号なども対象にしています。実際、可能な全てのコードポイント(`0x10FFFF`まで)がサポートされています。Unicode 文字は独立のマッピングテーブルに格納されています。キーマップファイルに `unicode_map` 配列を維持する必要があります。これには最大 16384 エントリを含めることができます。 - -以下を `rules.mk` に追加します: - -```make -UNICODEMAP_ENABLE = yes -``` - -次に、`X(i)` キーコードをキーマップに追加します。ここで _i_ はマッピングテーブル内の目的の文字のインデックスです。これは数値にできますが、インデックスを列挙型に保持し、名前でアクセスすることをお勧めします。 - -```c -enum unicode_names { - BANG, - IRONY, - SNEK -}; - -const uint32_t PROGMEM unicode_map[] = { - [BANG] = 0x203D, // ‽ - [IRONY] = 0x2E2E, // ⸮ - [SNEK] = 0x1F40D, // 🐍 -}; -``` - -そして、キーマップで `X(BANG)`、`X(SNEK)` などを使うことができます。 - -#### 小文字と大文字 - -文字は å や Å のような小文字と大文字のペアで提供されることがあります。これらの文字を入力しやすくするために、キーマップで `XP(i, j)` を使うことができます。ここで、_i_ および _j_ はそれぞれ小文字と大文字のマッピングテーブルのインデックスです。キーを押した時に、シフトを押したままか Caps Lock をオンにしている場合は、2番目(大文字)の文字が挿入されます; そうでなければ最初(小文字)バージョンが出力されます。 - -これは特殊文字がある国際レイアウトのためのキーマップを作成している時に最も役立ちます。別々のキーに文字の小文字および大文字バージョンを置く代わりに、`XP()` を使ってそれら両方を同じキーに持つことができます。これは Unicode キーを通常のアルファベットと混ぜるのに役立ちます。 - -キーコードのサイズの制約により、_i_ と _j_ はそれぞれ `unicode_map` の最初の128文字のうち1つだけを参照できます。別の言い方をすると、0 ≤ _i_ ≤ 127 かつ 0 ≤ _j_ ≤ 127 です。これはほとんどのユースケースで十分ですが、インデックス計算をカスタマイズしたい場合は、[`unicodemap_index()`](https://github.com/qmk/qmk_firmware/blob/71f640d47ee12c862c798e1f56392853c7b1c1a8/quantum/process_keycode/process_unicodemap.c#L36) 関数をオーバーライドすることができます。これにより、例えば Shift/Caps の代わりに Ctrl をチェックすることもできます。 - -
- -### 1.3. UCIS :id=ucis - -この方法も全ての可能なコードポイントをサポートします。Unicode Map の方法と同様に、キーマップファイル内にマッピングテーブルを保持する必要があります。ただし、この機能のための組み込みのキーコードはありません — この機能を起動するカスタムキーコードあるいは関数を作成する必要があります。 - -以下を `rules.mk` に追加します: - -```make -UCIS_ENABLE = yes -``` - -次に、キーマップファイルでこのようにテーブルを定義します: - -```c -const qk_ucis_symbol_t ucis_symbol_table[] = UCIS_TABLE( - UCIS_SYM("poop", 0x1F4A9), // 💩 - UCIS_SYM("rofl", 0x1F923), // 🤣 - UCIS_SYM("cuba", 0x1F1E8, 0x1F1FA), // 🇨🇺 - UCIS_SYM("look", 0x0CA0, 0x005F, 0x0CA0), // ಠ_ಠ -); -``` - -デフォルトでは、各テーブルエントリの長さは、最大3コードポイントです。この番号は `#define UCIS_MAX_CODE_POINTS n` を `config.h` ファイルに追加することで変更できます。 - -UCIS 入力を使うには、`qk_ucis_start()` を呼び出します。次に、文字のニーモニック ("rofl" など) を入力し、Space か Enter か Esc を押します。QMK は "rofl" テキストを消去し、笑っている絵文字を挿入するはずです。 - -#### カスタマイズ - -この機能をカスタマイズするためにキーマップで定義できる幾つかの関数があります。 - -* `void qk_ucis_start_user(void)` – これは "start" 関数を呼び出す時に実行され、フィードバックを提供するために使うことができます。デフォルトでは、キーボードの絵文字を入力します。 -* `void qk_ucis_success(uint8_t symbol_index)` – これは入力が何かに一致して完了した時に実行されます。デフォルトでは何もしません。 -* `void qk_ucis_symbol_fallback (void)` – これは入力が何にも一致しない時に実行されます。デフォルトでは、入力を Unicode コードとして試そうとします。 - -[`process_ucis.c`](https://github.com/qmk/qmk_firmware/blob/master/quantum/process_keycode/process_ucis.c) でこれらの関数のデフォルトの実装を見つけることができます。 - - -## 2. Input モード :id=input-modes - -QMK での Unicode の入力は、マクロのように、OS への一連の文字列を入力することで動作します。残念ながら、これが行われる方法はプラットフォームによって異なります。特に各プラットフォームでは Unicode 入力を引き起こすために、異なるキーの組み合わせが必要です。従って、対応する入力モードが QMK で設定されなければなりません。 - -以下の入力モードが利用可能です: - -* **`UC_MAC`**: macOS の組み込み Unicode 16進数入力。`0x10FFFF` までのコードポイント(全ての利用可能なコードポイント)をサポートします。 - - 有効にするには、_システム環境設定 > キーボード > 入力ソース_ に移動し、(_その他_ の下の) _Unicode 16進数入力_ をリストに追加し、次にメニューバーの入力ドロップダウンからそれをアクティブにします。 - デフォルトでは、このモードは Unicode 入力のために左 Option キー (`KC_LALT`) を使いますが、これは他のキーで [`UNICODE_KEY_MAC`](#input-key-configuration) を定義することで変更できます。 - - !> _Unicode 16進数入力_ 入力ソースの使用は、Option + 左矢印および Option + 右矢印 のような、幾つかの Option ベースのショートカットを無効にするかもしれません。 - - !> `UC_OSX` は `UC_MAC` の非推奨のエイリアスで、QMK の将来のバージョンで削除されます。全ての新しいキーマップは、`UC_MAC` を使うべきです。 - -* **`UC_LNX`**: Linux の組み込み IBus Unicode 入力。`0x10FFFF` までのコードポイント(全ての利用可能なコードポイント)をサポートします。 - - デフォルトで有効になっていて、IBus が有効になったディストリビューションのほとんどどれでも動作します。IBus が無い場合、このモードは GTK アプリ下で動作しますが、他の場所ではほとんど動作しません。 - デフォルトでは、このモードは Unicode 入力を開始するために Ctrl+Shift+U (`LCTL(LSFT(KC_U))`) を使いますが、これは他のキーコードで [`UNICODE_KEY_LNX`](#input-key-configuration) を定義することで変更できます。これは、Ctrl+Shift+U の挙動が Ctrl+Shift+E に統合された IBus バージョン 1.5.15 以上を必要とするかもしれません。 - -* **`UC_WIN`**: _(非推奨)_ Windows の組み込み16進数テンキー Unicode 入力。`0xFFFF` までのコードポイントをサポートします。 - - 有効にするには、`HKEY_CURRENT_USER\Control Panel\Input Method` の下に、`EnableHexNumpad` という名前の `REG_SZ` 型のレジストリキーを作成し、その値を `1` に設定します。これは、管理者権限でコマンドラインプロンプトから `reg add "HKCU\Control Panel\Input Method" -v EnableHexNumpad -t REG_SZ -d 1` を実行することでできます。その後再起動します。 - 信頼性と互換性の問題から、このモードはお勧めできません; 代わりに `UC_WINC` モードを使ってください。 - -* **`UC_BSD`**: _(未実装)_ BSD での Unicode 入力。現時点では実装されていません。BSD ユーザでサポートを追加したい場合は、[GitHub で issue を開いて](https://github.com/qmk/qmk_firmware/issues)ください。 - -* **`UC_WINC`**: [WinCompose](https://github.com/samhocevar/wincompose) を使った Windows Unicode 入力。v0.9.0 の時点で、`0x10FFFF` までのコードポイント(全ての利用可能なコードポイント)をサポートします。 - - 有効にするには、[最新のリリース](https://github.com/samhocevar/wincompose/releases/latest)をインストールします。インストールすると、起動時に WinCompose が自動的に実行されます。このモードはアプリがサポートする全てのバージョンの Windows で確実に動作します。 - デフォルトでは、このモードは Compose キーとして右 Alt (`KC_RALT`) を使いますが、これは WinCompose 設定と他のキーで [`UNICODE_KEY_WINC`](#input-key-configuration) を定義することで変更できます。 - - -## 3. 入力モードの設定 :id=setting-the-input-mode - -目的の入力モードを設定するには、以下の定義を `config.h` に追加します: - -```c -#define UNICODE_SELECTED_MODES UC_LNX -``` - -この例では、キーボードのデフォルトの入力モードを `UC_LNX` に設定します。これは、`UC_MAC` か `UC_WINC` か[上記](#input-modes)に列挙されている他のモードのいずれかに置き換えることができます。手動で別のモード([下記](#keycodes)を見てください)に切り替えない限り、キーボードは起動時に選択したモードを自動的に使います。 - -複数の入力モードを選択することもできます。これにより、`UC_MOD`/`UC_RMOD` キーコードを使ってそれらを簡単に切り替えることができます。 - -```c -#define UNICODE_SELECTED_MODES UC_MAC, UC_LNX, UC_WINC -``` - -値はカンマで区切られていることに注意してください。キーボードは最後に使われた入力モードを記憶し、次の電源投入時にそれを使い続けます。`config.h` に `#define UNICODE_CYCLE_PERSIST false` を追加することで、これを無効にして常にリストの最初のモードで開始するように強制できます。 - -#### キーコード - -以下のキーコードを使って、いつでも入力モードを切り替えることができます。これらをキーマップに追加すると、`UNICODE_SELECTED_MODES` に列挙されていないモードを含む特定の入力モードに素早く切り替えることができます。 - -| キーコード |エイリアス | 入力モード | 説明 | -|------------------------|-----------|--------------|--------------------------------------------------------------------| -| `UNICODE_MODE_FORWARD` | `UC_MOD` | リストの次へ | 選択したモードを切り替えます。Shift が押された場合は逆方向 | -| `UNICODE_MODE_REVERSE` | `UC_RMOD` | リストの前へ | 逆方向に選択したモードを切り替えます。Shift が押された場合は順方向 | -| `UNICODE_MODE_MAC` | `UC_M_MA` | `UC_MAC` | macOS 入力に切り替え | -| `UNICODE_MODE_LNX` | `UC_M_LN` | `UC_LNX` | Linux 入力に切り替え | -| `UNICODE_MODE_WIN` | `UC_M_WI` | `UC_WIN` | Windows 入力に切り替え | -| `UNICODE_MODE_BSD` | `UC_M_BS` | `UC_BSD` | BSD 入力に切り替え _(未実装)_ | -| `UNICODE_MODE_WINC` | `UC_M_WC` | `UC_WINC` | WinCompose を使う Windows 入力に切り替え | - -コード内で `set_unicode_input_mode(x)` を呼び出すことで、入力モードを切り替えることもできます。ここで、_x_ は上記の入力モード定数のいずれか (例えば、`UC_LNX`) です。 - -?> `matrix_init_user()` または同様の関数の中で `set_unicode_input_mode()` を呼び出すよりも、`UNICODE_SELECTED_MODES` を使うほうが望ましいです。Unicode システムとの統合性が高く、EEPROM への不要な書き込みを回避できるという利点があるからです。 - -#### オーディオフィードバック - -キーボードで[オーディオ機能](ja/feature_audio.md)を有効にした場合、上記のキーを押したときにメロディーを再生するように設定できます。そのようにして、入力モードを切り替えた時になんらかのオーディオフィードバックを得ることができます。 - -例えば、`config.h` ファイルに下記の定義を追加することができます: - -```c -#define UNICODE_SONG_MAC AUDIO_ON_SOUND -#define UNICODE_SONG_LNX UNICODE_LINUX -#define UNICODE_SONG_BSD TERMINAL_SOUND -#define UNICODE_SONG_WIN UNICODE_WINDOWS -#define UNICODE_SONG_WINC UNICODE_WINDOWS -``` - - -## 追加のカスタマイズ - -Unicode は大規模で多目的な機能のため、システムでより適切に動作するようにカスタマイズできるオプションが幾つかあります。 - -### 入力関数の開始と終了 - -プラットフォームで Unicode 入力を開始および終了する機能は、ローカルで上書きできます。可能な用途には、デフォルトキーを使用しない場合の入力モードの挙動のカスタマイズ、あるいは Unicode 入力への視覚/音声フィードバックの追加があります。 - -* `void unicode_input_start(void)` – これはプラットフォームに Unicode 入力モードの入力を指示する初期シーケンスを送信します。例えば、Windows では左 Alt キーの後に Num+ を押したままにし、Linux では `UNICODE_KEY_LNX` の組み合わせ(デフォルト: Ctrl+Shift+U) を押します。 -* `void unicode_input_finish(void)` – これは、例えば Space を押すか Alt キーを放すなどして、Unicode 入力モードを終了するために呼ばれます。 - -[`process_unicode_common.c`](https://github.com/qmk/qmk_firmware/blob/master/quantum/process_keycode/process_unicode_common.c) でこれらの関数のデフォルトの実装を見つけることができます。 - -### 入力キーの設定 - -`config.h` に対応する定義を追加することで、macOS、Linux、WinCompose で Unicode 入力を引き起こすために使われるキーをカスタマイズできます。デフォルト値はプラットフォームのデフォルト設定に一致するため、Unicode 入力が動作しない、あるいは(例えば左あるいは右 Alt を解放するために)異なるキーを使いたい場合以外はこれを変更する必要はありません。 - -| 定義 | 型 | 既定値 | 例 | -|--------------------|------------|--------------------|---------------------------------------------| -| `UNICODE_KEY_MAC` | `uint8_t` | `KC_LALT` | `#define UNICODE_KEY_MAC KC_RALT` | -| `UNICODE_KEY_LNX` | `uint16_t` | `LCTL(LSFT(KC_U))` | `#define UNICODE_KEY_LNX LCTL(LSFT(KC_E))` | -| `UNICODE_KEY_WINC` | `uint8_t` | `KC_RALT` | `#define UNICODE_KEY_WINC KC_RGUI` | - - -## Unicode 文字列の送信 - -QMK は、Unicode 入力をプログラムでホストに送信できるようにする幾つかの関数を提供します: - -### `send_unicode_string()` - -この関数は、`send_string()` によく似ていますが、UTF-8 文字を直接入力できます。選択された入力モードでもサポートされている場合は、全てのコードポイントをサポートします。`keymap.c` ファイルが UTF-8 エンコーディングを使ってフォーマットされていることを確認してください。 - -```c -send_unicode_string("(ノಠ痊ಠ)ノ彡┻━┻"); -``` - -使用例には、[Macros](ja/feature_macros.md) で説明されているように、キーが押された時に Unicode 文字列を送信することが含まれます。 - -## 追加の言語サポート - -`quantum/keymap_extras` には、様々な言語ファイルがあります — これらは Colemak または BÉPO のような代替レイアウトのファイルと同じように動作します。これらの言語ヘッダのいずれかを `#include` すると、その言語/国のレイアウトに固有のキーコードにアクセスできます。このようなキーコードは、2文字の国/言語コードの後に、アンダースコアとキーが対応する4文字の略語が続くことで定義されます。例えば、キーマップに `keymap_french.h` を含め、`FR_UGRV` を使うと、ネイティブのフランス語 AZERTY レイアウトを使うシステムで入力すると、`ù` が出力されます。 - -マシンで使うプライマリシステムレイアウトが US ANSI と異なる場合、これらの言語固有のキーコードを使うと、QMK キーマップが実際に画面に出力されるものとより一致するようになります。ただし、これらのキーコードは、内部の対応するデフォルトの US キーコードのエイリアスに過ぎず、キーボードで使われる HID プロトコル自体は本質的に US ANSI に基づいていることに注意してください。 - - -## Windows での国際文字 - -### AutoHotkey - -この方法はキーボード自体で Unicode サポートを必要としませんが、代わりにバックグラウンドで [AutoHotkey](https://autohotkey.com) が実行されていることを当てにします。 - -最初にプログラムで使われていないモディファイアの組み合わせを選択する必要があります。 -Ctrl+Alt+Win はあまり広く使われていないため、これに最適なはずです。 -mod-tab コンボ `LCAG_T` 用に定義されたマクロがあります。 -この mod-tab マクロをキーボードのキーに追加します。例えば: `LCAG_T(KC_TAB)`。 -これにより、キーを押してすぐ放すとキーはタブキーのように振る舞いますが、他のキーと一緒に使うとモディファイアに変わります。 - -AutoHotkey のデフォルトのスクリプトで、カスタムホットキーを定義できます。 - - <^ - -似たキーマップを複数のキーボードで使う場合、それらの間でコードを共有できるという利点が得られることがあります。`users/`に以下の構造でキーマップ(理想的には GitHub のユーザ名、``)と同じ名前の独自のフォルダを作成します: - -* `/users//` (パスに自動的に追加されます) - * `readme.md` (オプション、推奨) - * `rules.mk` (自動的に含まれます) - * `config.h` (自動的に含まれます) - * `.h` (オプション) - * `.c` (オプション) - * `cool_rgb_stuff.c` (オプション) - * `cool_rgb_stuff.h` (オプション) - - -以下のように、`` という名前のキーマップをビルドする時のみ、これが全て起きます: - - make planck: - -例えば、 - - make planck:jack - -は、`/users/jack/rules.mk` に加えて、パスに `/users/jack/` フォルダを含めます。 - -!> この `name` は必要に応じて[上書き](#override-default-userspace)することができます。 - -## `Rules.mk` - -`rules.mk` は自動的に処理される2つファイルのうちの1つです。これにより、コンパイル時に追加のソースファイル( `.c` など)を追加できます。 - -追加されるデフォルトのソースファイルとして `.c` を使うことを強くお勧めします。それを追加するために、以下のように `rules.mk` に SRC を追加する必要があります: - - SRC += .c - -追加のファイルも同じ方法で追加できます - ただし、``.c/.h という名前のファイルを最初に用意することをお勧めします。 - -ビルド時に `/users//rules.mk` ファイルはキーマップの `rules.mk` の_後_でインクルードされます。これにより、キーボードによっては利用できないことのある個々の QMK 機能を利用する機能をユーザスペース `rules.mk` に持つことができます。 - -例えば、RGB ライトをサポートする全てのキーボード間で RGB 制御機能を共有する場合、RGBLIGHT 機能が有効であればサポートを追加することができます: -```make -ifeq ($(strip $(RGBLIGHT_ENABLE)), yes) - # ここにファンシーな rgb 関数のソースを含める - SRC += cool_rgb_stuff.c -endif -``` - -別のやり方として、キーマップの `rules.mk` で `define RGB_ENABLE` と定義し、以下のようにユーザスペースの `rules.mk` で変数をチェックすることができます: -```make -ifdef RGB_ENABLE - # ここにファンシーな rgb 関数のソースを含める - SRC += cool_rgb_stuff.c -endif -``` - -### デフォルトのユーザスペースの上書き :id=override-default-userspace - -デフォルトでは、使用されるユーザスペース名はキーマップ名と同じです。状況によってはこれは望ましくありません。例えば、[レイアウト](ja/feature_layouts.md)機能を使う場合、異なるキーマップに同じ名前 (例えば、ANSI および ISO) を使うことができません。レイアウトに `mylayout-ansi` や `mylayout-iso` という名前を付け、以下の行をレイアウトの `rules.mk` に追加します: - -``` -USER_NAME := mylayout -``` - -これは、基板上に物理的に異なる機能を備えた、複数の異なるキーボード(RGBライトを備えたキーボード、オーディオを備えたキーボード、LEDの数が異なる、コントローラ上の異なるPINに接続されているなど)がある場合にも役立ちます。 - -## 設定オプション (`config.h`) - -さらに、ここにある `config.h` はキーマップフォルダ内の同名のファイルと同じように処理されます。これは `.h` ファイルとは別個に処理されます。 - -この理由は、`.h` は (`#define TAPPING_TERM 100` などのような)設定を追加する時には追加されず、`config.h` ファイル内の `` ファイルを含めるとコンパイルの問題を引き起こすからです。 - -!>`config.h` は[設定オプション](ja/config_options.md)のために使い、`.h` ファイルはユーザあるいは(レイヤーあるいはキーコードのための enum のような)キーマップ固有の設定のために使うべきです - - -## Readme (`readme.md`) - -作者情報 (あなたの名前、GitHub ユーザ名、eメール)およびオプションで[GPL 互換のライセンス](https://www.gnu.org/licenses/license-list.html#GPLCompatibleLicenses)を含めてください。 - -以下をテンプレートとして使うことができます: -``` -Copyright @ - -This program is free software: you can redistribute it and/or modify -it under the terms of the GNU General Public License as published by -the Free Software Foundation, either version 2 of the License, or -(at your option) any later version. - -This program is distributed in the hope that it will be useful, -but WITHOUT ANY WARRANTY; without even the implied warranty of -MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -GNU General Public License for more details. - -You should have received a copy of the GNU General Public License -along with this program. If not, see . -``` - -年、名前、eメールおよび GitHub ユーザ名をあなたの情報に置き換えます。 - -さらに、コードを他の人に共有したい場合、ここはコードを文章化するのに適した場所です。 - -## 特定のキーマップをサポートする全てのキーボードをビルドする - -1つのコマンドで全てのキーマップのビルドを確認したいですか？以下で実行することができます: - - make all: - -例えば、 - - make all:jack - -これは、[_プルリクエスト_](https://github.com/qmk/qmk_firmware/pulls) を準備する時に全てが正常にコンパイルされることを確認したい場合に最適です。 - -## 例 - -簡単な例については、[`/users/_example/`](https://github.com/qmk/qmk_firmware/tree/master/users/_example) を調べてください。 -より複雑な例については、[`/users/drashna/`](https://github.com/qmk/qmk_firmware/tree/master/users/drashna) のユーザスペースを調べてください。 - - -### カスタマイズされた関数 :id=customized-functions - -QMK には、[`_quantum`、`_kb` および `_user` バージョン](ja/custom_quantum_functions.md#a-word-on-core-vs-keyboards-vs-keymap)を持つ使用可能な[関数](custom_quantum_functions.md)が山ほどあります。 ほとんどの場合、これらの関数のユーザバージョンを使う必要があります。しかし問題はそれらをユーザスペースで使う場合、キーマップで使うことができるバージョンが無いことです。 - -しかし、実際にはキーマップバージョンのサポートを追加し、ユーザスペースとキーマップの両方で使うことができます。 - - -例えば、`layer_state_set_user()` 関数を見てみましょう。全てのキーボードで [Tri Layer State](ja/ref_functions.md#olkb-tri-layers) 機能を有効にしながら、`keymap.c` ファイルで Tri Layer 機能を保持することができます。 - -`` ファイル内で、以下を追加する必要があります: -```c -__attribute__ ((weak)) -layer_state_t layer_state_set_keymap (layer_state_t state) { - return state; -} - -layer_state_t layer_state_set_user (layer_state_t state) { - state = update_tri_layer_state(state, 2, 3, 5); - return layer_state_set_keymap (state); -} -``` -`__attribute__ ((weak))` 部分は、コンパイラにこれが `keymap.c` 内のバージョンに置き換えられるプレースホルダ関数であることを伝えます。そうすれば、`keymap.c` に追加する必要はありませんが、追加しても関数が同じ名前を持つため競合することはありません。 - -ここでの `_keymap` 部分は重要では無く、`_quantum`、`_kb` あるいは `_user` は既に使われているため、それら以外のものである必要があります。`layer_state_set_mine`、`layer_state_set_fn` などを使うことができます。 - -[`users/drashna`](https://github.com/qmk/qmk_firmware/tree/master/users/drashna) 内の [`template.c`](https://github.com/qmk/qmk_firmware/blob/master/users/drashna/template.c) でこのリストと他の一般的な関数を見つけることができます。 - -### カスタム機能 - -ユーザスペース機能は膨大な数のキーボードをサポートすることができるため、特定の機能は有効にしたいが、他のキーボードでは有効にしたくないかもしれません。そして実際に自分のユーザスペースで有効あるいは無効にすることができる「機能」を作成することができます。 - -例えば、(スペースを節約するために)特定のキーボードでのみたくさんのマクロを利用したい場合、それらを `#ifdef MACROS_ENABLED` して「見えないように」してから、キーボードごとに有効にすることができます。これを行うには、以下を rules.mk に追加します。 -```make -ifeq ($(strip $(MACROS_ENABLED)), yes) - OPT_DEFS += -DMACROS_ENABLED -endif -``` -`OPT_DEFS` 設定は `MACROS_ENABLED` がキーボード用に定義されるようにし(名前の前に `-D` があることに注意してください)、c/h ファイルで状態をチェックするために `#ifdef MACROS_ENABLED` を使うことができ、それに基づいてそのコードを処理します。 - -次にキーマップの `rules.mk` に `MACROS_ENABLED = yes` を追加し、ユーザスペースでこの機能とコードを有効にします。 - -そして `process_record_user` 関数の中で、以下のようなことを行います: -```c -bool process_record_user(uint16_t keycode, keyrecord_t *record) { - switch (keycode) { -#ifdef MACROS_ENABLED - case MACRO1: - if (!record->event.pressed) { - SEND_STRING("This is macro 1!"); - } - break; - case MACRO2: - if (!record->event.pressed) { - SEND_STRING("This is macro 2!"); - } - break; -#endif - } - return true; -} -``` - - -### 結合マクロ - -全てのキーマップについてユーザスペースにマクロやそのほかの関数を統合したい場合は、そうすることができます。これは上記の[カスタマイズ関数](#customized-functions)の例に基づいています。これは異なるキーボード間で共有される大量のマクロを維持し、キーボード固有のマクロも可能です。 - -最初に、全ての `keymap.c` ファイルを調べ、代わりに `process_record_user` を `process_record_keymap` に置き換えます。この方法では、これらのキーボードでキーボード固有のコードを使用でき、カスタムの "global" キーコードも使うことができます。また、`SAFE_RANGE` を `NEW_SAFE_RANGE` に置き換えて、キーコードが重複しないようにすることもできます。 - -次に、全ての keymap.c ファイルに `#include ".h"` を追加します。これにより、各キーマップでそれらを再定義することなく新しいキーコードを使うことができます。 - -それが完了したら、必要なキーコードの定義を `.h` ファイルに設定します。例えば: -```c -#pragma once - -#include "quantum.h" -#include "action.h" -#include "version.h" - -// 全てを定義 -enum custom_keycodes { - KC_MAKE = SAFE_RANGE, - NEW_SAFE_RANGE // キーマップ固有のコードについては "NEW_SAFE_RANGE" を使用 -}; -``` - -ここで、`.c` ファイルを作成し、この内容をそれに追加します: - -```c -#include ".h" - -__attribute__ ((weak)) -bool process_record_keymap(uint16_t keycode, keyrecord_t *record) { - return true; -} - -bool process_record_user(uint16_t keycode, keyrecord_t *record) { - switch (keycode) { - case KC_MAKE: // ファームウェアをコンパイルし、キーボードのブートローダに基づく書き込みコマンドを追加します - if (!record->event.pressed) { - uint8_t temp_mod = get_mods(); - uint8_t temp_osm = get_oneshot_mods(); - clear_mods(); clear_oneshot_mods(); - SEND_STRING("make " QMK_KEYBOARD ":" QMK_KEYMAP); - #ifndef FLASH_BOOTLOADER - if ((temp_mod | temp_osm) & MOD_MASK_SHIFT) - #endif - { - SEND_STRING(":flash"); - } - if ((temp_mod | temp_osm) & MOD_MASK_CTRL) { - SEND_STRING(" -j8 --output-sync"); - } - tap_code(KC_ENT); - set_mods(temp_mod); - } - break; - - } - return process_record_keymap(keycode, record); -} -``` - -(マクロパッドのような) Shift ボタンを持たないキーボードについては、ブートローダオプションを常に含める方法が必要です。これを行うには、以下をユーザスペースフォルダ内の `rules.mk` に追加します: - -```make -ifeq ($(strip $(FLASH_BOOTLOADER)), yes) - OPT_DEFS += -DFLASH_BOOTLOADER -endif -``` - -これは任意のキーマップで使うことができる新しい `KC_MAKE` キーコードを追加します。そして、このキーコードは、`make :` を出力するため、頻繁なコンパイルを簡単にします。そして、これは現在のキーボードの情報を出力するため、全てのキーボードとキーマップで動作します。そのため毎回これを入力する必要はありません。 - -また、Shift を押したままにすると書き込みの対象 (`:flash`) をコマンドに追加します。Control を押したままにすると、複数のファイルを一度に処理することでコンパイル時間を短縮する幾つかのコマンドを追加します。 - -そして Shift キーが無いキーボード、あるいは常に書き込みを試したいキーボードについては、キーマップの `rules.mk` に `FLASH_BOOTLOADER = yes` を追加することができます。 - -?> これはブートローダの設定に基づいて正しいユーティリティを使って新しくコンパイルされたファームウェアを自動的に書き込むはずです (あるいはデフォルトで HEX ファイルを生成するだけ)。ただし、これは全てのシステムで動作するわけではないことに注意してください。はっきり言うと、AVRDUDE は WSL では動作しません。そして、これは BootloadHID あるいは mdloader をサポートしません。 diff --git a/docs/ja/feature_wpm.md b/docs/ja/feature_wpm.md deleted file mode 100644 index 3cb5e58fcb..0000000000 --- a/docs/ja/feature_wpm.md +++ /dev/null @@ -1,24 +0,0 @@ -# Word Per Minute (WPM) の計算 - - - -WPM 機能は、キーストローク間の時間から1分あたりの平均（移動平均）単語数を計算し、様々な用途で利用できるようにします。 - -`rules.mk` に以下を追加することで WPM システムを有効にします: - - WPM_ENABLE = yes - -ソフトシリアルを使っている分割キーボードについては、計算された WPM スコアがマスター側とスレーブ側で利用可能です。 - -## 公開関数 - -`uint8_t get_current_wpm(void);` -この関数は符号なし整数で現在の WPM を返します。 - - -## WPM 計算のためのカスタマイズ化されたキー - -デフォルトでは、WPM スコアは文字、空白、およびいくつかの句読点のみを含みます。WPM の計算に含むとみなす文字セットを変更したい場合は、`wpm_keycode_user(uint16_t keycode)` を実装し、計算に含めたい文字について true を返し、計算しない特定のキーコードに false を返すようにします。 diff --git a/docs/ja/flashing.md b/docs/ja/flashing.md deleted file mode 100644 index ce6646d4fe..0000000000 --- a/docs/ja/flashing.md +++ /dev/null @@ -1,247 +0,0 @@ -# 書き込みの手順とブートローダ情報 - - - -キーボードが使用するブートローダにはかなり多くの種類があり、ほぼ全てが異なる書き込みの方法を使います。幸いなことに、[QMK Toolbox](https://github.com/qmk/qmk_toolbox/releases) のようなプロジェクトは、あまり深く考える必要無しに様々なタイプと互換性を持つことを目指していますが、この文章では様々なタイプのブートローダとそれらを書き込むために利用可能な方法について説明します。 - -`rules.mk` の `BOOTLOADER` 変数で選択されたブートローダがある場合、QMK は .hex ファイルがデバイスに書き込むのに適切なサイズかどうかを自動的に計算し、合計サイズをバイト単位で(最大値とともに)出力します。 - -## DFU - -Atmel の DFU ブートローダはデフォルトで全ての atmega32u4 チップに搭載されており、PCB (旧 OLKB キーボード、Clueboard) に独自の IC を持つ多くのキーボードで使われています。一部のキーボードは、LUFA の DFU ブートローダ(または QMK のフォーク) (新しい OLKB キーボード)を使う場合もあり、そのハードウェアに固有の追加機能が追加されます。 - -DFU ブートローダとの互換性を確保するために、以下のブロックが `rules.mk` にあることを確認してください(オプションとして代わりに `lufa-dfu` や `qmk-dfu` が使えます): - -```make -# Bootloader selection -# Teensy halfkay -# Pro Micro caterina -# Atmel DFU atmel-dfu -# LUFA DFU lufa-dfu -# QMK DFU qmk-dfu -# ATmega32A bootloadHID -# ATmega328P USBasp -BOOTLOADER = atmel-dfu -``` - -互換性のあるフラッシャ: - -* [QMK Toolbox](https://github.com/qmk/qmk_toolbox/releases) (推奨の GUI) -* QMK の [dfu-programmer](https://github.com/dfu-programmer/dfu-programmer) / `:dfu` (推奨のコマンドライン) - -書き込み手順: - -1. `QK_BOOT` キーコードを押すか、RESET ボタンをタップします(または RST を GND にショートします)。 -2. OS がデバイスを検知するのを待ちます。 -3. メモリを消去します(自動的に実行されるかもしれません) -4. .hex ファイルを書き込みます -5. デバイスをアプリケーションモードにリセットします(自動的に実行されるかもしれません) - -あるいは: - - make ::dfu - -### QMK DFU - -QMK には LUFA DFU ブートローダのフォークがあり、ブートローダを終了してアプリケーションに戻る時に単純なマトリックススキャンを行うことができます。また、何かが起きた時に、LED を点滅したり、スピーカーでカチカチ音をたてたりします。これらの機能を有効にするには、`config.h` で以下のブロックを有効にします (ブートローダを終了するキーは、ここで定義された INPUT と OUTPUT に接続する必要があります): - - #define QMK_ESC_OUTPUT F1 // 通常 COL - #define QMK_ESC_INPUT D5 // 通常 ROW - #define QMK_LED E6 - #define QMK_SPEAKER C6 - -製造元と製品名は `config.h` から自動的に取得され、製品に「Bootloader」が追加されます。 - -このブートローダを生成するには、`bootloader` ターゲット、例えば `make planck/rev4:default:bootloader` を使います。 - -実稼働対応の .hex ファイル(アプリケーションおよびブートローダを含む)を生成するには、`production` ターゲット、例えば `make planck/rev4:default:production` を使います。 - -### 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 ボードとそのクローンは [Caterina ブートローダ](https://github.com/arduino/ArduinoCore-avr/tree/master/bootloaders/caterina) (Pro Micro またはそのクローンで構築されたキーボード)を使用し、avr109 プロトコルを使って仮想シリアルを介して通信します。[A-Star](https://www.pololu.com/docs/0J61/9) のようなブートローダは Caterina に基づいています。 - -Caterina ブートローダとの互換性を確保するために、以下のブロックが `rules.mk` にあることを確認してください: - -```make -# Bootloader selection -# Teensy halfkay -# Pro Micro caterina -# Atmel DFU atmel-dfu -# LUFA DFU lufa-dfu -# QMK DFU qmk-dfu -# ATmega32A bootloadHID -# ATmega328P USBasp -BOOTLOADER = caterina -``` - -互換性のあるフラッシャ: - -* [QMK Toolbox](https://github.com/qmk/qmk_toolbox/releases) (推奨の GUI) -* avr109 を使った [avrdude](https://www.nongnu.org/avrdude/) / `:avrdude` (推奨のコマンドライン) -* [AVRDUDESS](https://github.com/zkemble/AVRDUDESS) - -書き込み手順: - -1. `QK_BOOT` キーコードを押すか、RST をすばやく GND にショートします (入力後7秒で書き込みます) -2. OS がデバイスを検知するのを待ちます。 -3. .hex ファイルを書き込みます -4. デバイスが自動的にリセットされるのを待ちます - -あるいは - - make ::avrdude - - -### Caterina コマンド - -ファームウェアを DFU デバイスに書き込むために使用できる DFU コマンドがいくつかあります。 - -* `:avrdude` - これが通常のオプションで、Caterina デバイスが(新しい COM ポートを検出して)使用可能になるまで待機し、ファームウェアを書き込みます。 -* `:avrdude-loop` - これは `:avrdude` と同じコマンドを実行します。ただし書き込みが終了すると再び Caterina デバイスの書き込み待ちに戻ります。これは何台ものデバイスへ書き込むのに便利です。_Ctrl+C を押して、手動でこの繰り返しを終了させる必要があります。_ -* `:avrdude-split-left` - デフォルトオプション (`:avrdude`) と同様に通常のファームウェアが書き込まれます。ただし、分割キーボードの「左側の」 EEPROM ファイルも書き込まれます。_これは、Pro Micro ベースの分割キーボードに最適です。_ -* `:avrdude-split-right` - デフォルトオプション (`:avrdude`) と同様に通常のファームウェアが書き込まれます。ただし、分割キーボードの「右側の」 EEPROM ファイルも書き込まれます。_これは、Pro Micro ベースの分割キーボードに最適です。_ - - - -## Halfkay - -Halfkay は PJRC によって開発された超スリムなプロトコルであり、HID を使用し、全ての Teensys (つまり 2.0)に搭載されています。 - -Halfkay ブートローダとの互換性を確保するために、以下のブロックが `rules.mk` にあることを確認してください: - -```make -# Bootloader selection -# Teensy halfkay -# Pro Micro caterina -# Atmel DFU atmel-dfu -# LUFA DFU lufa-dfu -# QMK DFU qmk-dfu -# ATmega32A bootloadHID -# ATmega328P USBasp -BOOTLOADER = halfkay -``` - -互換性のあるフラッシャ: - -* [QMK Toolbox](https://github.com/qmk/qmk_toolbox/releases) (推奨の GUI) -* [Teensy ローダー](https://www.pjrc.com/teensy/loader.html) -* [Teensy ローダーコマンドライン](https://www.pjrc.com/teensy/loader_cli.html) (推奨のコマンドライン) - -書き込み手順: - -1. `QK_BOOT` キーコードを押すか、RST をすばやく GND にショートします (入力後7秒で書き込みます) -2. OS がデバイスを検知するのを待ちます。 -3. .hex ファイルを書き込みます -4. デバイスをアプリケーションモードにリセットします(自動的に実行されるかもしれません) - -## USBasploader - -USBasploader は matrixstorm によって開発されたブートローダです。V-USB を実行する ATmega328P のような非 USB AVR チップで使われます。 - -USBasploader ブートローダとの互換性を確保するために、以下のブロックが `rules.mk` にあることを確認してください: - -```make -# Bootloader selection -# Teensy halfkay -# Pro Micro caterina -# Atmel DFU atmel-dfu -# LUFA DFU lufa-dfu -# QMK DFU qmk-dfu -# ATmega32A bootloadHID -# ATmega328P USBasp -BOOTLOADER = USBasp -``` - -互換性のあるフラッシャ: - -* [QMK Toolbox](https://github.com/qmk/qmk_toolbox/releases) (推奨の GUI) -* `usbasp` プログラマを使った [avrdude](https://www.nongnu.org/avrdude/) -* [AVRDUDESS](https://github.com/zkemble/AVRDUDESS) - -書き込み手順: - -1. `QK_BOOT` キーコードを押すか、RST を GND にすばやくショートしながら、ブートピンを GND にショートしたままにします。 -2. OS がデバイスを検知するのを待ちます。 -3. .hex ファイルを書き込みます -4. デバイスをアプリケーションモードにリセットします(自動的に実行されるかもしれません) - -## BootloadHID - -BootloadHID は AVR マイクロコントローラ用の USB ブートローダです。アップローダーツールは Windows でカーネルレベルのドライバを必要としないため、DLL をインストールせずに実行することができます。 - -bootloadHID ブートローダとの互換性を確保するために、以下のブロックが `rules.mk` にあることを確認してください: - -```make -# Bootloader selection -# Teensy halfkay -# Pro Micro caterina -# Atmel DFU atmel-dfu -# LUFA DFU lufa-dfu -# QMK DFU qmk-dfu -# ATmega32A bootloadHID -# ATmega328P USBasp -BOOTLOADER = bootloadHID -``` - -互換性のあるフラッシャ: - -* [HIDBootFlash](http://vusb.wikidot.com/project:hidbootflash) (推奨の Windows GUI) -* [bootloadhid コマンドライン](https://www.obdev.at/products/vusb/bootloadhid.html) / QMK の `:BootloadHID` (推奨のコマンドライン) - -書き込み手順: - -1. 以下のいずれかの方法を使ってブートローダに入ります: - * `QK_BOOT` キーコードをタップします (全てのデバイスでは動作しないかもしれません) - * キーボードを接続しながらソルトキーを押し続けます (通常はキーボードの readme に書かれています) -2. OS がデバイスを検知するのを待ちます。 -3. .hex ファイルを書き込みます -4. デバイスをアプリケーションモードにリセットします(自動的に実行されるかもしれません) - -あるいは: - - make ::bootloadHID - -## STM32 - -全ての STM32 チップには、変更も削除もできない工場出荷時のブートローダがプリロードされています。一部の STM32 チップには USB プログラミングが付属していないブートローダがありますが(例えば STM32F103)、プロセスは同じです。 - -現時点では、STM32 の `rules.mk` には、`BOOTLOADER` 変数は不要です。 - -互換性のあるフラッシャ: - -* [QMK Toolbox](https://github.com/qmk/qmk_toolbox/releases) (推奨の GUI) -* [dfu-util](https://github.com/Stefan-Schmidt/dfu-util) / `:dfu-util` (推奨のコマンドライン) - -書き込み手順: - -1. 以下のいずれかの方法を使ってブートローダに入ります: - * `QK_BOOT` キーコードをタップします (STM32F042 デバイスでは動作しないかもしれません) - * リセット回路が存在する場合、RESET ボタンをタップします - * それ以外の場合は、(BOOT0 ボタンあるいはブリッジ経由で)BOOT0 を VCC にブリッジし、(REEST ボタンあるいはブリッジ経由で)RESET を GND にショートし、BOOT0 ブリッジを放す必要があります。 -2. OS がデバイスを検知するのを待ちます。 -3. .bin ファイルを書き込みます - * DFU 署名に関する警告が表示されます; 無視してください -4. デバイスをアプリケーションモードにリセットします(自動的に実行されるかもしれません) - * コマンドラインからビルドする場合(例えば、`make planck/rev6:default:dfu-util`)、`rules.mk` の中で `:leave` が `DFU_ARGS` 変数に渡されるようにしてください (例えば、`DFU_ARGS = -d 0483:df11 -a 0 -s 0x08000000:leave`)。そうすれば、書き込みの後でデバイスがリセットされます - -### 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 ユーティリティを介してファームウェアを書き込めます。 -* `:st-flash` - dfu-util ではなく、[STLink Tools](https://github.com/stlink-org/stlink) の `st-flash` ユーティリティを介してファームウェアを書き込めます。 diff --git a/docs/ja/flashing_bootloadhid.md b/docs/ja/flashing_bootloadhid.md deleted file mode 100644 index 5c67bd5f29..0000000000 --- a/docs/ja/flashing_bootloadhid.md +++ /dev/null @@ -1,75 +0,0 @@ -# BootloadHID の書き込み手順とブートローダの情報 - - - -ps2avr(GB) キーボードは ATmega32A マイクロコントローラを使い、異なるブートローダを使います。それは通常の QMK の方法を使って書き込むことができません。 - -一般的な書き込みシーケンス: - -1. 以下のいずれかの方法を使ってブートローダに入ります: - * `QK_BOOT` キーコードをタップします (全てのデバイスでは動作しないかもしれません) - * ソルトキーを押し続けながらキーボードを接続します (通常はキーボードの readme に書かれています) -2. OS がデバイスを検知するのを待ちます。 -3. .hex ファイルを書き込みます -4. デバイスをアプリケーションモードにリセットします(自動的に実行されるかもしれません) - -## bootloadHID の書き込みターゲット - -?> [こちら](ja/newbs_getting_started.md)で詳しく説明されている QMK インストールスクリプトを使うと、必要な bootloadHID ツールが自動的にインストールされます。 - -コマンドライン経由で書き込むには、以下のコマンドを実行してターゲット `:bootloadHID` を使います: - - make ::bootloadHID - -## GUI 書き込み - -### Windows -1. [HIDBootFlash](http://vusb.wikidot.com/project:hidbootflash) をダウンロードします。 -2. キーボードをリセットします。 -3. 設定された VendorID が `16c0` で、ProductID が `05df` であることを確認します -4. `Find Device` ボタンを押し、キーボードが見つかることを確認します。 -5. `Open .hex File` ボタンを押し、作成した `.hex` ファイルを見つけます。 -6. `Flash Device` ボタンを押し、処理が完了するまで待ちます。 - -## コマンドライン書き込み - -1. キーボードをリセットします。 -2. `bootloadHID -r` に続けて `.hex` ファイルへのパスを入力し、キーボードに書き込みます。 - -### Windows 手動インストール -MSYS2の場合: -1. https://www.obdev.at/downloads/vusb/bootloadHID.2012-12-08.tar.gz から BootloadHID ファームウェアパッケージをダウンロードします。 -2. 互換性のあるツール、例えば 7-Zip を使って内容を抽出します。 -3. 解凍された書庫から MSYS2 インストール先、通常 `C:\msys64\usr\bin` に `commandline/bootloadHID.exe` をコピーして、MSYS パスに追加します。 - -ネイティブの Windows 書き込みの場合、MSYS2 環境の外部で `bootloadHID.exe` を使うことができます。 - -### Linux 手動インストール -1. libusb development の依存関係をインストールします: - ```bash - # これは OS に依存します - Debian については以下で動作します -sudo apt-get install libusb-dev - ``` -2. BootloadHID ファームウェアパッケージをダウンロードします: - ``` - wget https://www.obdev.at/downloads/vusb/bootloadHID.2012-12-08.tar.gz -O - | tar -xz -C /tmp - ``` -3. bootloadHID 実行可能ファイルをビルドします: - ``` - cd /tmp/bootloadHID.2012-12-08/commandline/ -make -sudo cp bootloadHID /usr/local/bin - ``` - -### MacOS 手動インストール -1. 以下を入力して Homebrew をインストールします: - ``` - /usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)" - ``` -2. 以下のパッケージをインストールします: - ``` - brew install --HEAD https://raw.githubusercontent.com/robertgzr/homebrew-tap/master/bootloadhid.rb - ``` diff --git a/docs/ja/getting_started_docker.md b/docs/ja/getting_started_docker.md deleted file mode 100644 index ceaebb0179..0000000000 --- a/docs/ja/getting_started_docker.md +++ /dev/null @@ -1,60 +0,0 @@ -# Docker クイックスタート - - - -このプロジェクトは、プライマリオペレーティングシステムに大きな変更を加えることなくキーボードの新しいファームウェアを非常に簡単に構築することができる Docker ワークフローを含みます。これは、あなたがプロジェクトをクローンしビルドを実行した時に、他の人とまったく同じ環境と QMK ビルド基盤を持つことも保証します。これにより、人々はあなたが遭遇した問題の解決をより簡単に行えるようになります。 - -## 必要事項 - -主な前提条件は動作する `docker` または `podman` がインストールされていることです。 -* [Docker CE](https://docs.docker.com/install/#supported-platforms) -* [Podman](https://podman.io/getting-started/installation) - -## 使い方 - -(サブモジュールを含む) QMK のレポジトリのローカルコピーを取得する: - -```bash -git clone --recurse-submodules https://github.com/qmk/qmk_firmware.git -cd qmk_firmware -``` - -キーマップをビルドするために以下のコマンドを実行します: -```bash -util/docker_build.sh : -# 例えば: util/docker_build.sh planck/rev6:default -``` - -これは目的のキーボード/キーマップをコンパイルし、結果として書き込み用に `.hex` あるいは `.bin` ファイルを QMK ディレクトリの中に残します。`:keymap` が省略された場合は全てのキーマップが使われます。パラメータの形式は、`make` を使ってビルドする時と同じであることに注意してください。 - -`target` を指定して Docker から直接キーボードをビルドし、_かつ_ 書き込むためのサポートもあります。 - -```bash -util/docker_build.sh keyboard:keymap:target -# 例えば: util/docker_build.sh planck/rev6:default:flash -``` - -スクリプトをパラメータ無しで開始することもできます。この場合、1つずつビルドパラメータを入力するように求められます。これが使いやすいと思うかもしれません: - -```bash -util/docker_build.sh -# パラメータを入力として読み込みます (空白にすると全てのキーボード/キーマップ) -``` - -`RUNTIME` 環境変数にコンテナランタイム名やパスを設定することで、使用したいコンテナランタイムを手動で設定できます。 -デフォルトでは docker や podman は自動的に検出され、podman より docker が優先されます。 - -```bash -RUNTIME="podman" util/docker_build.sh keyboard:keymap:target -``` - -## FAQ - -### なぜ Windows/macOS 上で書き込めないのですか？ - -Windows と macOS では、実行するために [Docker Machine](http://gw.tnode.com/docker/docker-machine-with-usb-support-on-windows-macos/) が必要です。これはセットアップが面倒なので、お勧めではありません: 代わりに [QMK Toolbox](https://github.com/qmk/qmk_toolbox) を使ってください。 - -!> Docker for Windows は [Hyper-V](https://docs.microsoft.com/en-us/virtualization/hyper-v-on-windows/quick-start/enable-hyper-v) を有効にする必要があります。これは、Windows 7、Windows 8 および **Windows 10 Home** のような Hyper-V を搭載していない Windows のバージョンでは機能しないことを意味します。 diff --git a/docs/ja/getting_started_github.md b/docs/ja/getting_started_github.md deleted file mode 100644 index 6407011488..0000000000 --- a/docs/ja/getting_started_github.md +++ /dev/null @@ -1,69 +0,0 @@ -# QMK で GitHub を使う方法 - - - -GitHub は慣れていない人には少し注意が必要です - このガイドは、QMK におけるフォーク、クローン、プルリクエストのサブミットの各ステップについて説明します。 - -?> このガイドでは、あなたがコマンドラインでの実行にある程度慣れており、システムに git がインストールされていることを前提にしています。 - -[QMK GitHub ページ](https://github.com/qmk/qmk_firmware)を開くと、右上に "Fork" というボタンが見えます: - -![GitHub でのフォーク](https://i.imgur.com/8Toomz4.jpg) - -あなたが組織の一員である場合は、どのアカウントにフォークするかを選択する必要があります。ほとんどの場合、あなたの個人のアカウントにフォークしたいでしょう。フォークが完了したら(しばらく時間が掛かる場合があります)、"Clone or Download" ボタンをクリックします: - -![GitHub からダウンロード](https://i.imgur.com/N1NYcSz.jpg) - -必ず "HTTPS" を選択し、リンクを選択してコピーします: - -![HTTPS リンク](https://i.imgur.com/eGO0ohO.jpg) - -ここから、`git clone --recurse-submodules ` をコマンドラインに入力し、リンクを貼り付けます: - -``` -user@computer:~$ git clone --recurse-submodules https://github.com/whoeveryouare/qmk_firmware.git -Cloning into 'qmk_firmware'... -remote: Enumerating objects: 9, done. -remote: Counting objects: 100% (9/9), done. -remote: Compressing objects: 100% (5/5), done. -remote: Total 183883 (delta 5), reused 4 (delta 4), pack-reused 183874 -Receiving objects: 100% (183883/183883), 132.90 MiB | 9.57 MiB/s, done. -Resolving deltas: 100% (119972/119972), done. -... -Submodule path 'lib/chibios': checked out '587968d6cbc2b0e1c7147540872f2a67e59ca18b' -Submodule path 'lib/chibios-contrib': checked out 'ede48346eee4b8d6847c19bc01420bee76a5e486' -Submodule path 'lib/googletest': checked out 'ec44c6c1675c25b9827aacd08c02433cccde7780' -Submodule path 'lib/lufa': checked out 'ce10f7642b0459e409839b23cc91498945119b4d' -``` - -ローカルマシンに 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//qmk_firmware`)に戻ると、"New Pull Request" ボタンをクリックすることで新しいプルリクエストを作成することができます: - -![New Pull Request](https://i.imgur.com/DxMHpJ8.jpg) - -ここでは、コミットした内容を正確に確認することができます - 全て良いように見える場合は、"Create Pull Request" をクリックすることで最終的に承認することができます: - -![Create Pull Request](https://i.imgur.com/Ojydlaj.jpg) - -サブミットの後で、私たちはあなたの変更について話し、変更を依頼し、最終的にそれを受け入れるでしょう！QMK に貢献してくれてありがとう :) diff --git a/docs/ja/getting_started_introduction.md b/docs/ja/getting_started_introduction.md deleted file mode 100644 index a55391e0a1..0000000000 --- a/docs/ja/getting_started_introduction.md +++ /dev/null @@ -1,65 +0,0 @@ -# はじめに - - - -このページでは、QMK プロジェクトで作業するために知っておくべき基本的な情報について説明しようと思います。Unix シェルの操作に精通していることを前提としていますが、C について、または make を使ったコンパイルについて精通しているとは想定していません。 - -## 基本的な QMK の構造 - -QMK は [Jun Wako](https://github.com/tmk) の [tmk_keyboard](https://github.com/tmk/tmk_keyboard) プロジェクトのフォークです。変更された元の TMK コードは、`tmk_core` フォルダで見つけることができます。プロジェクトへの QMK の追加は、`quantum` フォルダで見つけることができます。キーボードプロジェクトは `handwired` および `keyboard` フォルダで見つけることができます。 - -### ユーザスペースの構造 - -`users` フォルダ内は各ユーザのためのディレクトリです。これはユーザがキーボード間で使うかもしれないコードを置くためのフォルダです。詳細は[ユーザスペース機能](ja/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 のためのレイアウトの設定に使われるファイル。詳細は [Configurator サポート](ja/reference_configurator_support.md)を見てください。 -* `readme.md`: キーボードの簡単な概要 -* `.h`: このファイルは、キーボードのスイッチマトリックスに対してキーボードレイアウトが定義されるファイルです。 -* `.c`: このファイルには、キーボードのためのカスタムコードがあります。 - -プロジェクトの構造についての詳細は、[QMK キーボードガイドライン](ja/hardware_keyboard_guidelines.md)を見てください。 - -### キーマップ構造 - -全てのキーマップフォルダには、以下のファイルがあります。`keymap.c` だけが必須で、残りのファイルが見つからない場合は、デフォルトのオプションが選択されます。 - -* `config.h`: キーマップを設定するためのオプション -* `keymap.c`: 全てのキーマップコード。必須 -* `rules.mk`: 有効になっている QMK の機能 -* `readme.md`: キーマップの説明。他の人が使う方法および機能の説明。imgur のようなサービスに画像をアップロードしてください。 - -# `config.h` ファイル - -3つの `config.h` の場所が考えられます: - -* キーボード (`/keyboards//config.h`) -* ユーザスペース (`/users//config.h`) -* キーマップ (`/keyboards//keymaps//config.h`) - -ビルドシステムは自動的に上の順に config ファイルを取得します。前の `config.h` で設定された設定を上書きしたい場合は、変更したい設定の準備のために最初に定型コードを置く必要があります。 - -``` -#pragma once -``` - -次に、前の `config.h` ファイルの設定を上書きするために、設定を `#undef` し再び `#define` する必要があります。 - -定型コードと設定は、以下のようになります: - -``` -#pragma once - -// ここに上書きします！ -#undef MY_SETTING -#define MY_SETTING 4 -``` diff --git a/docs/ja/getting_started_make_guide.md b/docs/ja/getting_started_make_guide.md deleted file mode 100644 index 07d7f0597a..0000000000 --- a/docs/ja/getting_started_make_guide.md +++ /dev/null @@ -1,161 +0,0 @@ -# より詳細な `make` 手順 - - - -`make` コマンドの完全な構文は `::` です: - -* `` はキーボードのパスです。例えば、`planck` - * 全てのキーボードをコンパイルするには `all` を使います。 - * リビジョンを選択してコンパイルするためのパスを指定します。例えば `planck/rev4` あるいは `planck/rev3` - * キーボードにフォルダが無い場合は、省略することができます - * デフォルトのフォルダをコンパイルする場合は、省略することができます -* `` はキーマップの名前です。例えば、`algernon` - * 全てのキーマップをコンパイルするには `all` を使います。 -* `` の詳細は以下で説明します。 - -`` は以下を意味します -* target が指定されない場合は、以下の `all` と同じです -* `all` は指定されたキーボード/リビジョン/キーマップの可能な全ての組み合わせのコンパイルを行います。例えば、`make planck/rev4:default` は1つの .hex を生成しますが、`make planck/rev4:all` は planck で利用可能な全てのキーマップについて hex を生成します。 -* `flash`、`dfu`、`teensy`、`avrdude`、`dfu-util`、`bootloadHID` はファームウェアをコンパイルし、キーボードにアップロードします。コンパイルが失敗すると、何もアップロードされません。使用するプログラマはキーボードに依存します。ほとんどのキーボードでは `dfu` ですが、ChibiOS キーボードについては `dfu-util` 、標準的な Teensy については `teensy` を使います。キーボードに使うコマンドを見つけるには、キーボード固有の readme をチェックしてください。 - 利用可能なブートローダの詳細は[ファームウェアの書き込み](ja/flashing.md)ガイドを参照してください。 - * **Note**: 一部のオペレーティングシステムでは、これらのコマンドが機能するためには特権アクセスが必要です。これは、root アクセスなしでこれらにアクセスするために [`udev ルール`](ja/faq_build.md#linux-udev-rules) を設定するか、あるいは root アクセスでコマンドを実行する (`sudo make planck/rev4:default:flash`) 必要があるかもしれないことを意味します。 -* `clean` は、全てをゼロからビルドするためにビルド出力フォルダを掃除します。説明できない問題がある場合は、通常のコンパイルの前にこれを実行してください。 -* `distclean` は、.hex ファイルと .bin ファイルを削除します。 - -次のターゲットは開発者向けです: - -* `show_path` ソースとオブジェクトファイルのパスを表示します。 -* `dump_vars` makefile 変数をダンプします。 -* `objs-size` 個々のオブジェクトファイルのサイズを表示します。 -* `show_build_options` 'rules.mk' のオプションセットを表示します。 -* `check-md5` 生成されたバイナリファイルの md5 チェックサムを表示します。 - -make コマンドの最後、つまり target の後に追加のオプションを追加することもできます - -* `make COLOR=false` - カラー出力をオフ -* `make SILENT=true` - エラー/警告以外の出力をオフ -* `make VERBOSE=true` - 全ての gcc のものを出力 (デバッグする必要が無い限り面白くありません) -* `make VERBOSE_LD_CMD=yes` - -v オプションを指定して ld コマンドを実行します。 -* `make VERBOSE_AS_CMD=yes` - -v オプションを指定して as コマンドを実行します。 -* `make VERBOSE_C_CMD=` - 指定された C ソースファイルをコンパイルするときに -v オプションを追加します。 -* `make DUMP_C_MACROS=` - 指定された C ソースファイルをコンパイルするときにプリプロセッサマクロをダンプします。 -* `make DUMP_C_MACROS= > ` - 指定された C ソースファイルをコンパイルするときにプリプロセッサマクロを `` にダンプします。 -* `make VERBOSE_C_INCLUDE=` - 指定された C ソースファイルをコンパイルするときにインクルードされるファイル名をダンプします。 -* `make VERBOSE_C_INCLUDE= 2> ` - 指定された C ソースファイルをコンパイルするときにインクルードされるファイル名を `` にダンプします。 - -make コマンド自体にもいくつかの追加オプションがあります。詳細は `make --help` を入力してください。最も有用なのはおそらく `-jx` です。これは複数の CPU を使ってコンパイルしたいことを指定し、`x` は使用したい CPU の数を表します。設定すると、特に多くのキーボード/キーマップをコンパイルしている場合は、コンパイル時間を大幅に短縮することができます。通常は、コンパイル中に他の作業を行うための余裕をもたせるために、持っている CPU の数より1つ少ない値に設定します。全てのオペレーティングシステムと make バージョンがオプションをサポートしているわけではないことに注意してください。 - -コマンドの例を幾つか示します - -* `make all:all` は、全てをビルドします (全てのキーボードフォルダ、全てのキーマップ)。`root` から単に `make` を実行すると、これを実行します。 -* `make ergodox_infinity:algernon:clean` は、Ergodox Infinity キーボードのビルド出力を掃除します。 -* `make planck/rev4:default:flash COLOR=false` カラー出力なしでキーマップをビルドしアップロードします。 - -## `rules.mk` オプション - -無効にするにはこれらの変数を `no` に設定します。有効にするには `yes` に設定します。 - -`BOOTMAGIC_ENABLE` - -これにより、1つのキーとソルトキー(デフォルトではスペース)を押し続けることで、電力が失われても持続する様々な EEPROM 設定へアクセスできます。誤って設定が変更されることが多く、デバッグするのが難しい混乱した結果を生成するため、これを無効にしておくことをお勧めします。ヘルプセッションで発生する、より一般的な問題の1つです。 - -`MOUSEKEY_ENABLE` - -これにより、キーコード/カスタム関数を介して、カーソルの動きとクリックを制御することができます。 - -`EXTRAKEY_ENABLE` - -これにより、システムとオーディオ制御キーコードを使うことができます。 - -`CONSOLE_ENABLE` - -これにより、[`hid_listen`](https://www.pjrc.com/teensy/hid_listen.html) を使って読むことができるメッセージを出力することができます。 - -デフォルトで、全てのデバッグ( *dprint* ) 出力 ( *print*、*xprintf* )、およびユーザ出力 ( *uprint* ) メッセージが有効になります。これにより、フラッシュメモリの大部分が消費され、キーボードの .hex ファイルが大きすぎてプログラムできなくなるかもしれません。 - -デバッグメッセージ( *dprint* ) を無効にし、.hex ファイルのサイズを小さくするには、`config.h` に `#define NO_DEBUG` を含めます。 - -出力メッセージ( *print*、*xprintf* )とユーザ出力( *uprint* ) を無効にし、.hex のファイルサイズを小さくするには、`config.h` に `#define NO_PRINT` を含めます。 - -出力メッセージ ( *print*、*xprintf* ) を無効にし、ユーザメッセージ ( *uprint* )を**そのままにする**には、`config.h` に `#define USER_PRINT` を含めます(この場合は、`#define NO_PRINT` も含めないでください)。 - -テキストを見るには、`hid_listen` を開き、出力メッセージを見るのを楽しんでください。 - -**注意:** キーマップコード以外の *uprint* メッセージを含めないでください。QMK システムフレームワーク内で使うべきではありません。さもないと、他の人の .hex ファイルが肥大化します。 - -`COMMAND_ENABLE` - -これはマジックコマンドを有効にし、通常はデフォルトのマジックキーの組み合わせ `LSHIFT+RSHIFT+KEY` で起動されます。マジックコマンドは、デバッグメッセージ (`MAGIC+D`) の有効化や NKRO の一時的な切り替え (`MAGIC+N`) を含みます。 - -`SLEEP_LED_ENABLE` - -コンピュータがスリープの間に LED がブレスできるようにします。ここでは Timer1 が使われます。この機能は大部分が未使用でテストされておらず、更新もしくは抽象化が必要です。 - -`NKRO_ENABLE` - -これにより、キーボードはホスト OS に最大 248 個のキーが同時に押されていることを伝えることができます (NKRO 無しのデフォルトは 6 です)。NKRO は、`NKRO_ENABLE` が設定されていたとしても、デフォルトではオフです。config.h に `#define FORCE_NKRO` を追加するか、`MAGIC_TOGGLE_NKRO` をキーにバインドしてキーを押すことで、NKRO を強制することができます。 - -`BACKLIGHT_ENABLE` - -これはスイッチ内の LED のバックライトを有効にします。`config.h` 内に以下を入れることでバックライトピンを指定することができます: - - #define BACKLIGHT_PIN B7 - -`MIDI_ENABLE` - -キーボードで MIDI の送受信を有効にします。MIDI 送信モードに入るためにキーコード `MI_ON` を使うことができ、オフにするために `MI_OFF` を使うことができます。これはほとんどテストされていない機能ですが、詳細については `quantum/quantum.c` ファイルで見つけることができます。 - -`UNICODE_ENABLE` - -これによりキーマップで `UC()` を使って Unicode 文字を送信することができます。`0x7FFF` までのコードポイントがサポートされます。これはほとんどの現代言語の文字と記号を対象にしますが、絵文字は対象外です。 - -`UNICODEMAP_ENABLE` - -これによりキーマップで `X()` を使って Unicode 文字を送信することができます。キーマップファイル内にマッピングテーブルを保持する必要があります。可能な全てのコードポイント( `0x10FFFF` まで)がサポートされます。 - -`UCIS_ENABLE` - -これにより、送信したい文字に対応するニーモニックを入力することで Unicode 文字を送信することができます。キーマップファイル内にマッピングテーブルを保持する必要があります。可能な全てのコードポイント( `0x10FFFF` まで)がサポートされます。 - -詳細と制限については、[Unicode ページ](ja/feature_unicode.md)を見てください。 - -`AUDIO_ENABLE` - -C6 ピン(抽象化が必要)でオーディオ出力できます。詳細は[オーディオページ](ja/feature_audio.md)を見てください。 - -`VARIABLE_TRACE` - -これを使って変数の値の変更をデバッグします。詳細についてはユニットテストのページの[変数のトレース](ja/unit_testing.md#tracing-variables)のセクションを見てください。 - -`API_SYSEX_ENABLE` - -これにより Quantum SYSEX API を使って文字列を(どこかに？)送信することができます - -`KEY_LOCK_ENABLE` - -これは[キーロック](ja/feature_key_lock.md)を有効にします。 - -`SPLIT_KEYBOARD` - -分割キーボード (let's split や bakingpy's boards のようなデュアル MCU) のサポートを有効にし、quantum/split_common にある全ての必要なファイルをインクルードします - -`SPLIT_TRANSPORT` - -ARM ベースの分割キーボード用の標準分割通信ドライバはまだ無いため、これらのために `SPLIT_TRANSPORT = custom` を使わなければなりません。カスタムの実装が使われるようにすることで、標準の分割キーボード通信コード(AVR 固有)が含まれないようにします。 - -`CUSTOM_MATRIX` - -デフォルトのマトリックス走査ルーチンを独自のコードで置き換えます。詳細については、[カスタムマトリックスページ](ja/custom_matrix.md)を見てください。 - -`DEBOUNCE_TYPE` - -デフォルトのキーデバウンスルーチンを別のものに置き換えます。`custom` の場合、独自の実装を提供する必要があります。 - -## キーマップごとに Makefile オプションをカスタマイズ - -あなたのキーマップディレクトリに `rules.mk` というファイルがある場合、そのファイルで設定した全てのオプションは、あなたのキーボードの他の `rules.mk` オプションよりも優先されます。 - -あなたのキーボードの `rules.mk` に `BACKLIGHT_ENABLE = yes` があるとします。あなたの特定のキーボードでバックライトが無いようにするには、`rules.mk` というファイルを作成し、`BACKLIGHT_ENABLE = no` を指定します。 diff --git a/docs/ja/gpio_control.md b/docs/ja/gpio_control.md deleted file mode 100644 index 7bece3e0c7..0000000000 --- a/docs/ja/gpio_control.md +++ /dev/null @@ -1,47 +0,0 @@ -# GPIO 制御 :id=gpio-control - - - -QMK には、マイクロコントローラに依存しない GPIO 制御抽象レイヤーがあります。これは異なるプラットフォーム間でピン制御に簡単にアクセスできるようにするためのものです。 - -## 関数 :id=functions - -以下の関数は GPIO の基本的な制御を提供し、`quantum/quantum.h` にあります。 - -| 関数 | 説明 | 古い AVR の例 | 古い ChibiOS/ARM の例 | -|------------------------|--------------------------------------------------|-------------------------------------------------|-------------------------------------------------| -| `setPinInput(pin)` | ピンを高インピーダンス(High-Z)の入力として設定 | `DDRB &= ~(1<<2)` | `palSetLineMode(pin, PAL_MODE_INPUT)` | -| `setPinInputHigh(pin)` | ピンを組み込みのプルアップ抵抗付きの入力として設定 | `DDRB &= ~(1<<2); PORTB \|= (1<<2)` | `palSetLineMode(pin, PAL_MODE_INPUT_PULLUP)` | -| `setPinInputLow(pin)` | ピンを組み込みのプルダウン抵抗付きの入力として設定 | N/A (AVR ではサポートされません) | `palSetLineMode(pin, PAL_MODE_INPUT_PULLDOWN)` | -| `setPinOutput(pin)` | ピンを出力として設定 | `DDRB \|= (1<<2)` | `palSetLineMode(pin, PAL_MODE_OUTPUT_PUSHPULL)` | -| `writePinHigh(pin)` | ピンレベルを high に設定 (ピンを出力として設定してあると仮定) | `PORTB \|= (1<<2)` | `palSetLine(pin)` | -| `writePinLow(pin)` | ピンレベルを low に設定 (ピンを出力として設定してあると仮定) | `PORTB &= ~(1<<2)` | `palClearLine(pin)` | -| `writePin(pin, level)` | ピンレベルを設定 (ピンを出力として設定してあると仮定) | `(level) ? PORTB \|= (1<<2) : PORTB &= ~(1<<2)` | `(level) ? palSetLine(pin) : palClearLine(pin)` | -| `readPin(pin)` | ピンのレベルを返す | `_SFR_IO8(pin >> 4) & _BV(pin & 0xF)` | `palReadLine(pin)` | -| `togglePin(pin)` | ピンレベルを反転 (ピンを出力として設定してあると仮定) | `PORTB ^= (1<<2)` | `palToggleLine(pin)` | - -## 高度な設定 :id=advanced-settings - -各マイクロコントローラは GPIO に関して複数の高度な設定を持つことができます。この抽象レイヤーは、アーキテクチャー固有の機能の使用法を制限しません。上級ユーザは、目的のデバイスのデータシートを参照し、必要なライブラリを含めてください。AVR については、標準 avr/io.h ライブラリが使われます; STM32 については ChibiOS [PAL ライブラリ](https://chibios.sourceforge.net/docs3/hal/group___p_a_l.html)が使われます。 - -## アトミック操作 :id=atomic-operation - -上記の関数は、必ずしもアトミックに動作することが保証されているわけではありません。そのため、上記の関数を複数組み合わせて使用する際に、操作の途中での割り込みを防ぎたい場合は、以下の `ATOMIC_BLOCK_FORCEON` マクロを使用してください。 - -例: -```c -void some_function() { - // 通常の処理 - ATOMIC_BLOCK_FORCEON { - // アトミックであることが必要な処理 - } - // 通常の処理 -} -``` - -`ATOMIC_BLOCK_FORCEON` は、ブロックが実行される前に、割り込みが有効か無効かに関わらず、強制的に割り込みを無効にします。そして、ブロックが実行された後に、割り込みを有効にします。 - -したがって、`ATOMIC_BLOCK_FORCEON`は、ブロックの実行前に割り込みが有効になっていることがわかっている場合や、ブロックの完了時に割り込みを有効にしても問題ないことがわかっている場合のみ使用できることに注意してください。 diff --git a/docs/ja/hardware_avr.md b/docs/ja/hardware_avr.md deleted file mode 100644 index cdc5f8cb86..0000000000 --- a/docs/ja/hardware_avr.md +++ /dev/null @@ -1,190 +0,0 @@ -# AVR マイコンを使ったキーボード - - - -このページでは QMK における AVR マイコンのサポートについて説明します。AVR マイコンには、Atmel 社製の atmega32u4、atmega32u2、at90usb1286 やその他のマイコンを含みます。AVR マイコンは、簡単に動かせるよう設計された8ビットの MCU です。キーボードでよく使用される AVR マイコンには USB 機能や大きなキーボードマトリックスのためのたくさんの GPIO を搭載しています。これらは、現在、キーボードで使われる最も一般的な MCU です。 - -まだ読んでない場合は、[キーボードガイドライン](ja/hardware_keyboard_guidelines.md) を読んで、キーボードを QMK にどのように適合させるかを把握する必要があります。 - -## AVR を使用したキーボードを QMK に追加する - -QMK には AVR を使ったキーボードでの作業を簡略化するための機能が多数あります。大体のキーボードでは1行もコードを書く必要がありません。まずはじめに、`qmk new-keyboard` を実行します。 - -``` -$ qmk new-keyboard -Ψ Generating a new QMK keyboard directory - -Keyboard Name: mycoolkeeb -Keyboard Type: - 1. avr - 2. ps2avrgb -Please enter your choice: [1] -Your Name: [John Smith] -Ψ Copying base template files... -Ψ Copying avr template files... -Ψ Renaming keyboard.[ch] to mycoolkeeb.[ch]... -Ψ Replacing %YEAR% with 2021... -Ψ Replacing %KEYBOARD% with mycoolkeeb... -Ψ Replacing %YOUR_NAME% with John Smith... - -Ψ Created a new keyboard called mycoolkeeb. -Ψ To start working on things, `cd` into keyboards/mycoolkeeb, -Ψ or open the directory in your preferred text editor. -``` - -これにより、新しいキーボードをサポートするために必要なすべてのファイルが作成され、デフォルト値で設定が入力されます。あとはあなたのキーボード用にカスタマイズするだけです。 - -## `readme.md` - -このファイルではキーボードに関する説明を記述します。[キーボード Readme テンプレート](ja/documentation_templates.md#keyboard-readmemd-template)に従って `readme.md` を記入して下さい。`readme.md` の上部に画像を配置することをお勧めします。画像は [Imgur](https://imgur.com) のような外部サービスを利用してください。 - -## `.c` - -このファイルではキーボード上で実行される全てのカスタマイズされたロジックを記述します。多くのキーボードの場合、何も書く必要はありません。 -[機能のカスタマイズ](ja/custom_quantum_functions.md)で、カスタマイズされたロジックの記述方法を詳しく学ぶことが出来ます。 - -## `.h` - -このファイルでは、[レイアウト](ja/feature_layouts.md)を定義します。最低限、以下のような `#define LAYOUT` を記述する必要があります。 - -```c -#define LAYOUT( \ - k00, k01, k02, \ - k10, k11 \ -) { \ - { k00, k01, k02 }, \ - { k10, KC_NO, k11 }, \ -} -``` - -`LAYOUT` マクロの前半部ではキーの物理的な配置を定義します。後半部ではスイッチが接続されるマトリックスを定義します。これによってマトリックス配線の順とは異なるキーを物理的に配置できます。 - -それぞれの `k__` 変数はユニークでなければいけません。通常は `k` というフォーマットに従って記述されます。 - -物理マトリックス（後半部）では、`MATRIX_ROWS` に等しい行数が必要であり、各行には正確に `MATRIX_COLS` と等しい数の要素が含まれていなければいけません。物理キーが存在しない場合は、`KC_NO` を使用して空白を埋める事ができます。 - -## `config.h` - -`config.h` ファイルには、ハードウェアや機能の設定を記述します。このファイルで設定できるオプションは列挙しきれないほどたくさんあります。利用できるオプションの概要は[設定オプション](ja/config_options.md)を参照して下さい。 - -### ハードウェアの設定 - -`config.h` の先頭には USB に関する設定があります。これらはキーボードが OS からどのように見えるかを制御しています。変更する理由がない場合は、`VENDOR_ID` を `0xFEED` のままにしておく必要があります。`PRODUCT_ID` にはまだ使用されていない番号を選ばなければいけません。 - -`MANUFACTURER`、 `PRODUCT` をキーボードにあった設定に変更します。 - -```c -#define VENDOR_ID 0xFEED -#define PRODUCT_ID 0x6060 -#define DEVICE_VER 0x0001 -#define MANUFACTURER You -#define PRODUCT my_awesome_keyboard -``` - -?> Windows や macOS では、`MANUFACTURER` と `PRODUCT` が USBデバイスのリストに表示されます。Linux 上の `lsusb` では、代わりに [USB ID Repository](http://www.linux-usb.org/usb-ids.html) によって維持されているリストの値を優先します。デフォルトでは、リストに `VENDOR_ID` / `PRODUCT_ID` を含まない場合にのみ、`MANUFACTURER` と `PRODUCT` を使います。`sudo lsusb -v` を使用するとデバイスから示された値を表示します。また、接続したときのカーネルログにも表示されます。 - -### キーボードマトリックスの設定 - -`config.h` ファイルの次のセクションではキーボードのマトリックスを扱います。最初に設定するのはマトリックスのサイズです。これは通常、常にではありませんが、物理キー配置と同じ数の行・列になります。 - -```c -#define MATRIX_ROWS 2 -#define MATRIX_COLS 3 -``` - -マトリックスのサイズを定義したら、MCU のどのピンを行と列に接続するかを定義します。そのためにはピンの名前を指定するだけです。 - -```c -#define MATRIX_ROW_PINS { D0, D5 } -#define MATRIX_COL_PINS { F1, F0, B0 } -#define UNUSED_PINS -``` - - -`MATRIX_ROW_PINS` の要素の数は `MATRIX_ROWS` に定義した数と同じでなければいけません。同様に `MATRIX_COL_PINS` の要素の数も `MATRIX_COLS` と等しい必要があります。`UNUSED_PINS` は定義しなくても問題ありませんがどのピンが空いているのか記録しておきたい場合は定義できます。 - -最後にダイオードの方向を定義します。これには `COL2ROW` か `ROW2COL` を設定します。 - -```c -#define DIODE_DIRECTION COL2ROW -``` - -#### ダイレクトピンマトリックス - -各スイッチが、列と行のピンを共有する代わりに、それぞれ個別のピンとグランドに接続されているキーボードを定義するには、`DIRECT_PINS` を使用します。マッピング定義では、列と行の各スイッチのピンを左から右の順に定義します。`MATRIX_ROWS` と `MATRIX_COLS` 内のサイズに準拠する必要があり、空白を埋めるには `NO_PIN` を使用します。これによって `DIODE_DIRECTION`、`MATRIX_ROW_PINS`、`MATRIX_COL_PINS` の動作を上書きします。 - -```c -// #define MATRIX_ROW_PINS { D0, D5 } -// #define MATRIX_COL_PINS { F1, F0, B0 } -#define DIRECT_PINS { \ - { F1, E6, B0, B2, B3 }, \ - { F5, F0, B1, B7, D2 }, \ - { F6, F7, C7, D5, D3 }, \ - { B5, C6, B6, NO_PIN, NO_PIN } \ -} -#define UNUSED_PINS - -/* COL2ROW, ROW2COL */ -//#define DIODE_DIRECTION -``` - -### バックライトの設定 - -QMK では GPIO ピンでのバックライト制御をサポートしています。これらの設定を選択して MCU から制御できます。詳しくは[バックライト](ja/feature_backlight.md)を参照して下さい。 - -```c -#define BACKLIGHT_PIN B7 -#define BACKLIGHT_LEVELS 3 -#define BACKLIGHT_BREATHING -#define BREATHING_PERIOD 6 -``` - -### その他の設定オプション - -`config.h` で設定・調整できる機能はたくさんあります。詳しくは[設定オプション](ja/config_options.md)を参照して下さい。 - -## `rules.mk` - -`rules.mk` ファイルを使用して、ビルドするファイルや有効にする機能をQMKへ指示します。atmega32u4 を使っている場合、これらのオプションはデフォルトのままにしておくことが出来ます。他の MCU を使用している場合はいくつかのパラメータを調整する必要があります。 - -### MCU オプション - -このオプションではビルドする CPU をビルドシステムに指示します。これらの設定を変更する場合は非常に注意して下さい。キーボードを操作不能にしてしまう可能性があります。 - -```make -MCU = atmega32u4 -F_CPU = 16000000 -ARCH = AVR8 -F_USB = $(F_CPU) -OPT_DEFS += -DINTERRUPT_CONTROL_ENDPOINT -``` - -### ブートローダー - -ブートローダーは MCU に保存されているプログラムをアップグレードするための特別なセクションです。キーボードのレスキューパーティションのようなものだと考えて下さい。 - -#### Teensy Bootloader の例 - -```make -BOOTLOADER = halfkay -``` - -#### Atmel DFU Loader の例 - -```make -BOOTLOADER = atmel-dfu -``` - -#### Pro Micro Bootloader の例 - -```make -BOOTLOADER = caterina -``` - -### ビルドオプション - -`rules.mk` にはオン・オフできるたくさんの機能があります。詳細なリストと説明は[設定オプション](ja/config_options.md#feature-options)を参照して下さい。 diff --git a/docs/ja/hardware_drivers.md b/docs/ja/hardware_drivers.md deleted file mode 100644 index e0061cb328..0000000000 --- a/docs/ja/hardware_drivers.md +++ /dev/null @@ -1,41 +0,0 @@ -# QMK ハードウェアドライバー - - - -QMK はたくさんの異なるハードウェアで使われています。最も一般的な MCU とマトリックス構成をサポートしていますが、キーボードへ他のハードウェアを追加し制御するためのドライバーもいくつか用意されています。例えば、マウスやポインティングデバイス、分割キーボード用の IO エキスパンダ、Bluetooth モジュール、LCD、OLED、TFT 液晶などがあります。 - - - -# 使用できるドライバー - -## ProMicro (AVR のみ) - -ProMicro のピンを AVR の名前ではなく、Arduino の名前で指定できます。この部分はより詳しく文書化される必要があります。もしこれを使用したい場合にコードを読んでも分からない場合、[issue を開く](https://github.com/qmk/qmk_firmware/issues/new)を通して助けることができるかもしれません。 - -## SSD1306 OLED ドライバー - -SSD1306 ベースの OLED ディスプレイのサポート。詳しくは[OLED ドライバ](ja/feature_oled_driver.md)を参照して下さい。 - -## WS2812 - -WS2811/WS2812{a,b,c} LED のサポート。 詳しくは [RGB ライト](ja/feature_rgblight.md)を参照して下さい。 - -## IS31FL3731 - -最大2つの LED ドライバーのサポート。各ドライバーは、I2C を使って個別に LED を制御する2つのチャーリープレクスマトリックスを実装しています。最大144個の単色 LED か32個の RGB LED を使用できます。ドライバーの設定方法の詳細は[RGB マトリックス](ja/feature_rgb_matrix.md)を参照して下さい。 - -## IS31FL3733 - -拡張の余地がある最大1つの LED ドライバーのサポート。各ドライバーは192個の単色 LED か64個の RGB LED を制御できます。ドライバーの設定方法の詳細は [RGB マトリックス](ja/feature_rgb_matrix.md)を参照して下さい。 - -## 24xx シリーズ 外部 I2C EEPROM - -オンチップ EEPROM の代わりに使用する I2C ベースの外部 EEPROM のサポート。ドライバーの設定方法の詳細は [EEPROM ドライバー](ja/eeprom_driver.md)を参照して下さい。 diff --git a/docs/ja/hardware_keyboard_guidelines.md b/docs/ja/hardware_keyboard_guidelines.md deleted file mode 100644 index ef5f6df2b9..0000000000 --- a/docs/ja/hardware_keyboard_guidelines.md +++ /dev/null @@ -1,239 +0,0 @@ -# QMK キーボードガイドライン - - - -QMK は開始以来、コミュニティにおけるキーボードの作成や保守に貢献しているあなたのような人たちのおかげで飛躍的に成長しました。私たちが成長するにつれて、うまくやるためのいくつかのパターンを発見しました。他の人たちがあなたの苦労の恩恵を受けやすくするため、それにあわせてもらえるようお願いします。 - -## QMK Lint を使う - -キーボードの問題をチェックできるツール、`qmk lint` を提供しています。キーボードとキーマップで作業をしている間は、頻繁に使うことをお勧めします。 - -チェックに合格した例: - -``` -$ qmk lint -kb rominronin/katana60/rev2 -Ψ Lint check passed! -``` - -チェックに失敗した例: - -``` -$ qmk lint -kb clueboard/66/rev3 -☒ Missing keyboards/clueboard/66/rev3/readme.md -☒ Lint check failed! -``` - -## あなたのキーボード/プロジェクトの名前を決める - -キーボードの名前は全て小文字で、アルファベット、数字、アンダースコア(`_`)のみで構成されています。アンダースコア(`_`)で始めてはいけません。スラッシュ(`/`)はサブフォルダの区切り文字として使用されます。 - -`test`、`keyboard`、`all` はmakeコマンド用に予約されており、キーボードまたはサブフォルダ名として使用することは出来ません。 - -正しい例: - -* `412_64` -* `chimera_ortho` -* `clueboard/66/rev3` -* `planck` -* `v60_type_r` - -## サブフォルダ - -QMK では、まとめるためや同じキーボードのリビジョン間でコードを共有するためにサブフォルダを使用します。フォルダは最大4階層までネストできます。 - - qmk_firmware/keyboards/top_folder/sub_1/sub_2/sub_3/sub_4 - -サブフォルダ内に `rules.mk` ファイルが存在するとコンパイル可能なキーボードとして見なされます。QMK Configurator から使用できるようになり、`make all` でテストされます。同じメーカーのキーボードをまとめるためにフォルダを使用している場合は `rules.mk` ファイルを置いてはいけません。 - -例: - -Clueboard は、サブフォルダをまとめるためとキーボードのリビジョン管理の両方のために使用しています。 - -* [`qmk_firmware`](https://github.com/qmk/qmk_firmware/tree/master) - * [`keyboards`](https://github.com/qmk/qmk_firmware/tree/master/keyboards) - * [`clueboard`](https://github.com/qmk/qmk_firmware/tree/master/keyboards/clueboard) ← これはまとめるためのフォルダです。 `rules.mk` ファイルはありません。 - * [`60`](https://github.com/qmk/qmk_firmware/tree/master/keyboards/clueboard/60) ← これはコンパイルできるキーボードです。`rules.mk` が存在します。 - * [`66`](https://github.com/qmk/qmk_firmware/tree/master/keyboards/clueboard/66) ← これもコンパイルできるキーボードです。 デフォルトのリビジョンとして `DEFAULT_FOLDER` に `rev3` を指定しています。 - * [`rev1`](https://github.com/qmk/qmk_firmware/tree/master/keyboards/clueboard/66/rev1) ← コンパイル可能: `make clueboard/66/rev1` - * [`rev2`](https://github.com/qmk/qmk_firmware/tree/master/keyboards/clueboard/66/rev2) ← コンパイル可能: `make clueboard/66/rev2` - * [`rev3`](https://github.com/qmk/qmk_firmware/tree/master/keyboards/clueboard/66/rev3) ← コンパイル可能: `make clueboard/66/rev3` もしくは `make clueboard/66` - -## キーボードのフォルダ構成 - -キーボードは `qmk_firmware/keyboards/` 内にあり、前のセクションで説明したようにフォルダ名はキーボードの名前にする必要があります。このフォルダ内にはいくつかのファイルがあります。 - -* `readme.md` -* `info.json` -* `config.h` -* `rules.mk` -* `.c` -* `.h` - -### `readme.md` - -全てのプロジェクトにはどのようなキーボードなのか、誰が設計したか、どこで入手できるかを説明する `readme.md` ファイルが必要です。もしあれば、メーカーの Web サイトなどの詳しい情報へのリンクも含める必要があります。[キーボード readme テンプレート](ja/documentation_templates.md#keyboard-readmemd-template)を参考にして下さい。 - -### `info.json` - -このファイルは [QMK API](https://github.com/qmk/qmk_api) から使用されます。[QMK Configurator](https://config.qmk.fm/) が必要とするキーボードの情報が含まれています。ここでメタデータを設定することもできます。詳しくは [info.json 形式](ja/reference_info_json.md) を参照して下さい。 - -### `config.h` - -全てのプロジェクトには、マトリックスサイズ、製品名、USB VID/PID、説明、その他の設定などが含まれた `config.h` ファイルが必要です。一般に、このファイルを使用して常に機能するキーボードの重要な情報やデフォルトを設定します。 - -また、`config.h` ファイルはサブフォルダにも置くことができ、その読み込み順は以下の通りです。 - -* `keyboards/top_folder/config.h` - * `keyboards/top_folder/sub_1/config.h` - * `keyboards/top_folder/sub_1/sub_2/config.h` - * `keyboards/top_folder/sub_1/sub_2/sub_3/config.h` - * `keyboards/top_folder/sub_1/sub_2/sub_3/sub_4/config.h` - * `users/a_user_folder/config.h` - * `keyboards/top_folder/keymaps/a_keymap/config.h` - * `keyboards/top_folder/sub_1/sub_2/sub_3/sub_4/post_config.h` - * `keyboards/top_folder/sub_1/sub_2/sub_3/post_config.h` - * `keyboards/top_folder/sub_1/sub_2/post_config.h` - * `keyboards/top_folder/sub_1/post_config.h` -* `keyboards/top_folder/post_config.h` - -`post_config.h` ファイルは、`config.h` ファイルで指定された内容に応じて、追加の後処理を行うために使用することができます。 -例えば、キーマップレベルの `config.h` ファイルで `IOS_DEVICE_ENABLE` マクロを以下のように定義すると、`post_config.h` ファイルでより詳細な設定を行うことができます。 - -* `keyboards/top_folder/keymaps/a_keymap/config.h` - ```c - #define IOS_DEVICE_ENABLE - ``` -* `keyboards/top_folder/post_config.h` - ```c - #ifndef IOS_DEVICE_ENABLE - // USB_MAX_POWER_CONSUMPTION value for this keyboard - #define USB_MAX_POWER_CONSUMPTION 400 - #else - // fix iPhone and iPad power adapter issue - // iOS device need lessthan 100 - #define USB_MAX_POWER_CONSUMPTION 100 - #endif - - #ifdef RGBLIGHT_ENABLE - #ifndef IOS_DEVICE_ENABLE - #define RGBLIGHT_LIMIT_VAL 200 - #define RGBLIGHT_VAL_STEP 17 - #else - #define RGBLIGHT_LIMIT_VAL 35 - #define RGBLIGHT_VAL_STEP 4 - #endif - #ifndef RGBLIGHT_HUE_STEP - #define RGBLIGHT_HUE_STEP 10 - #endif - #ifndef RGBLIGHT_SAT_STEP - #define RGBLIGHT_SAT_STEP 17 - #endif - #endif - ``` - -?> 上記の例のように `post_config.h` でオプションを定義する場合、キーボードやユーザレベルの `config.h` で同じオプションを定義してはいけません。 - -### `rules.mk` - -このファイルが存在するということは、フォルダがキーボードであり、`make` コマンドで使用できることを意味します。ここでキーボードのビルド環境を構築し、デフォルトの機能を設定します。 - -`rules.mk` ファイルはサブフォルダにも置くことができ、その読み込み順は以下の通りです。 - -* `keyboards/top_folder/rules.mk` - * `keyboards/top_folder/sub_1/rules.mk` - * `keyboards/top_folder/sub_1/sub_2/rules.mk` - * `keyboards/top_folder/sub_1/sub_2/sub_3/rules.mk` - * `keyboards/top_folder/sub_1/sub_2/sub_3/sub_4/rules.mk` - * `keyboards/top_folder/keymaps/a_keymap/rules.mk` - * `users/a_user_folder/rules.mk` -* `common_features.mk` - -`rules.mk` ファイルに書かれた多くの設定は `common_features.mk` によって解釈され、必要なソースファイルやコンパイラのオプションが設定されます。 - -?> 詳しくは `build_keyboard.mk` と `common_features.mk` を見てください。 - -### `` - -ここではキーボードのカスタマイズされたコードを記述します。通常、初期化してキーボードのハードウェアを制御するコードを記述します。キーボードが LED やスピーカー、その他付属ハードウェアのないキーマトリックスのみで構成されている場合は空にできます。 - -通常、以下の関数がこのファイルで定義されます。 - -* `void matrix_init_kb(void)` -* `void matrix_scan_kb(void)` -* `bool process_record_kb(uint16_t keycode, keyrecord_t *record)` -* `bool led_update_kb(led_t led_state)` - -### `` - -このファイルはキーボードのマトリックスを定義するために使用されます。配列をキーボードの物理的なスイッチマトリックスに変換する C マクロを最低限1つ定義する必要があります。複数のレイアウトでキーボードを構築出来る場合は、追加のマクロを定義しなければいけません。 - -レイアウトが1つしかない場合は、このマクロは `LAYOUT` とします。 - -複数のレイアウトを定義する場合、物理的に構成することが出来なくとも、マトリックス上で全てのスイッチ位置をサポートする `LAYOUT_all` という名前の基本となるレイアウトが必要です。これは `default` キーマップで使用すべきマクロです。次に、他のレイアウトマクロを使用する `default_` といった追加のキーマップを用意します。これによって、他の人が定義されたレイアウトを使いやすくなります。 - -レイアウトマクロの名前は全て小文字で、先頭の `LAYOUT` だけ大文字です。 - -例として、ANSI と ISO をサポートする 60% PCB がある場合、以下のようにレイアウトとキーマップを定義出来ます。 - -| レイアウト名 | キーマップ名 | 説明 | -|-------------|-------------|-------------| -| LAYOUT_all | default | ISO と ANSI のどちらもサポートしたレイアウト | -| LAYOUT_ansi | default_ansi | ANSI レイアウト | -| LAYOUT_iso | default_iso | ISO レイアウト | - -## 画像/ハードウェアのファイル - -リポジトリのサイズを小さく保つために、いくつかの例外を除いて、どの形式のバイナリファイルも受け入れないようになりました。外部の場所（など）でホストして、`readme.md` でリンクすることをおすすめします。 - -ハードウェアのファイル(プレートやケース、PCB など)は [qmk.fm リポジトリ](https://github.com/qmk/qmk.fm)に提供でき、[qmk.fm](https://qmk.fm) で利用可能になります。ダウンロード出来るファイルは `//`（名前は上記と同じ形式）に保存され、`https://qmk.fm//` で提供されます。ページは `/_pages//` から生成されて、同じ場所で提供されます（ .mdファイルはJekyllを通して .htmlファイル変換されます）。`lets_split` ファイルを参照して下さい。 - -## キーボードのデフォルト設定 - -QMK が提供する機能の量を考えれば、新しいユーザーが混乱するのは当たり前です。キーボードのデフォルトファームウェアをまとめるなら、有効にする機能とオプションをハードウェアのサポートに必要な最低限のセットにすることをおすすめします。特定の機能に関するおすすめは以下の通りです。 - -### ブートマジックとコマンド - -[ブートマジック](ja/feature_bootmagic.md) と[コマンド](ja/feature_command.md)は、ユーザーがキーボードを明白でない方法で制御出来るようにする2つの関連機能です。いずれかの機能を有効にする場合、この機能をどのように提供するかについて、よく考えることをおすすめします。この機能が必要なユーザーは、あなたのキーボードを最初のプログラムできるキーボードとして使用している初心者に影響を与えることなく、個人的なキーマップ内で有効に出来ることを覚えておきましょう。 - -新規ユーザーが遭遇する最も多い問題は、キーボードを接続している間に間違えてブートマジックをトリガーしてしまうことです。キーボードの下を持っているとき、知らない間に Alt とスペースバーを押して、これらのキーが交換されてしまったことに気づきます。デフォルトではこの機能を無効にすることをおすすめしますが、有効にする場合は、キーボードを接続している間に押し間違えないキーへ `BOOTMAGIC_KEY_SALT` を設定することを検討して下さい。 - -キーボードに2つの Shift キーがない場合は、`COMMAND_ENABLE = no` を指定していても `IS_COMMAND` が動作するデフォルトを設定しておくべきです。ユーザーがコマンドを有効化したときに使用するデフォルトが与えられます。 - -## カスタムキーボードプログラミング - -[機能のカスタマイズ](ja/custom_quantum_functions.md)にあるようにキーボードのカスタム関数を定義できます。ユーザーも同様にその動作をカスタマイズしたいかもしれないということと、ユーザーにそれを可能にすることを忘れないで下さい。 `process_record_kb()`のようなカスタム関数を提供している場合、関数がその関数の `_user()` 版を呼び出すことを確認して下さい。また、その関数の`_user()` 版の戻り値を確認して、user が `true` を返した場合のみカスタムコードを実行しなければいけません。 - -## 生産しない/手配線 プロジェクト - -プロトタイプや手配線によるものなど QMK を使用するどんなプロジェクトも受け入れますが、`/keyboards/` フォルダが乱雑になるのを防ぐために、`/keyboards/handwired/` を用意しています。いつかプロトタイプのプロジェクトが製品のプロジェクトになった時点でメインの `/keyboards/` フォルダへ移動します！ - -## エラーとしての警告 - -キーボードを開発するときは、全ての警告がエラーとして扱われることに注意して下さい。小さな警告が蓄積されて、将来大きなエラーを引き起こす可能性があります。(そして、警告を放っておくのは良くない習慣です) - -## 著作権表示 - -別のプロジェクトを元にしてキーボードの設定をするものの同じコードを使用しない場合は、ファイル上部にある著作権表示を次の形式に従って自分の名前を表示するよう、更新して下さい。 - - Copyright 2017 Your Name - - -他の人のコードを修正し、その変更が些細な部分のみであれば、著作権表示の名前をそのままにしておかないといけません。ファイルに対して重要な作業を行った場合、以下のようにあなたの名前を追加します。 - - Copyright 2017 Their Name Your Name - -年はファイルが作成された最初の年にします。後年にそのファイルに対して作業が行われた場合、次のように2つ目の年を追加して反映することが出来ます。 - - Copyright 2015-2017 Your Name - -## ライセンス - -QMK のコア部分は [GNU General Public License](https://www.gnu.org/licenses/licenses.en.html) でライセンスされます。AVR マイコン用のバイナリを提供する場合は、[GPLv2](https://www.gnu.org/licenses/old-licenses/gpl-2.0.html) か、[GPLv3](https://www.gnu.org/licenses/gpl.html) のどちらかから選択出来ます。ARM マイコン用のバイナリを提供する場合は、 [ChibiOS](https://www.chibios.org) の GPLv3 ライセンスに準拠するため、[GPL Version 3](https://www.gnu.org/licenses/gpl.html) を選択しなければいけません。 - -## 技術的な詳細 - -キーボードを QMK で動作させるための詳細は[ハードウェア](ja/hardware.md)を参照して下さい！ diff --git a/docs/ja/how_a_matrix_works.md b/docs/ja/how_a_matrix_works.md deleted file mode 100644 index e5dfc9f07d..0000000000 --- a/docs/ja/how_a_matrix_works.md +++ /dev/null @@ -1,104 +0,0 @@ -# キーボードマトリックスの仕組み - - - -キーボードスイッチのマトリックスは行と列に配置されます。マトリックス回路がなければ、各スイッチはコントローラに直接配線する必要があります。 - -回路が行と列に配置されている場合、キーが押されると、列ワイヤが行ワイヤと接触し、回路が完成します。キーボードコントローラはこの閉回路を検知し、キー押下として登録します。 - -マイクロコントローラはファームウェアを介してセットアップされ、論理1を一度に1つずつ列に送信し、行から一度に全てを読み取ります - このプロセスはマトリックススキャンと呼ばれます。マトリックスはデフォルトでは電流の通過を許可しないたくさんの開いたスイッチです - ファームウェアはキーが押されていないものとしてこれを読み取ります。1つのキーを押すとすぐに、キースイッチが接続されている列から来ていた論理1がスイッチを通過して対応する行に渡されます - 以下の 2x2 の例を確認してください: - - Column 0 being scanned Column 1 being scanned - x x - col0 col1 col0 col1 - | | | | - row0 ---(key0)---(key1) row0 ---(key0)---(key1) - | | | | - row1 ---(key2)---(key3) row1 ---(key2)---(key3) - -`x` は関連付けられた列と行の値が1であるか、HIGH であることを表します。ここでは、キーが押されていないことが分かります。そのため `x` を取得する行はありません。1つのキースイッチの二つの接点はそのスイッチのある行と列にそれぞれ接続されていることに注意してください。 - -`key0` を押すと、`col0` は `row0` に接続されるため、ファームウェアがその行に対して受け取る値は `0b01` です (ここで `0b` はこれがビット値であることを意味します。つまり次の数字は全てビット(0または1)であり、その列のキーを表します)。この表記を使用して、キースイッチが押されたことを示し、列と行が接続されていることを示します: - - Column 0 being scanned Column 1 being scanned - x x - col0 col1 col0 col1 - | | | | - x row0 ---(-+-0)---(key1) row0 ---(-+-0)---(key1) - | | | | - row1 ---(key2)---(key3) row1 ---(key2)---(key3) - -`row0` には `x` があるため、値が1であることがわかります。全体として、`key0` が押された時にファームウェアが受信するデータは、 - - col0: 0b01 - col1: 0b00 - │└row0 - └row1 - -一度に複数のキーを押し始めると問題が発生します。マトリックスをもう一度見ると、かなり明白になっているはずです: - - Column 0 being scanned Column 1 being scanned - x x - col0 col1 col0 col1 - | | | | - x row0 ---(-+-0)---(-+-1) x row0 ---(-+-0)---(-+-1) - | | | | - x row1 ---(key2)---(-+-3) x row1 ---(key2)---(-+-3) - - Remember that this ^ is still connected to row1 - -これから取得されるデータは以下の通りです: - - col0: 0b11 - col1: 0b11 - │└row0 - └row1 - -4つ全てではなく、3つのキーしか押されていないため、これは正確ではありません。この挙動はゴーストと呼ばれ、このような奇妙なシナリオでのみ発生しますが、より大きなキーボードではより一般的です。これを回避する方法は、キースイッチの後に、行に接続する前にダイオードを配置することです。ダイオードは、電流が一方向にのみ流れるようにします。これにより、前の例で他の列と行がアクティブにならないようにします。ダイオードマトリックスをこのように表します; - - Column 0 being scanned Column 1 being scanned - x x - col0 col1 col0 col1 - │ │ | │ - (key0) (key1) (key0) (key1) - ! │ ! │ ! | ! │ - row0 ─────┴────────┘ │ row0 ─────┴────────┘ │ - │ │ | │ - (key2) (key3) (key2) (key3) - ! ! ! ! - row1 ─────┴────────┘ row1 ─────┴────────┘ - -実際の用途では、ダイオードの黒い線が行に面するように、キースイッチから離れるように配置されます - この場合の `!` はダイオードで、隙間は黒い線を表します。これを覚える良い方法は、以下のシンボルを考えることです: `>|` - -次に、3つのキーを押して、ゴーストシナリオとなるものを実施します: - - Column 0 being scanned Column 1 being scanned - x x - col0 col1 col0 col1 - │ │ │ │ - (┌─┤0) (┌─┤1) (┌─┤0) (┌─┤1) - ! │ ! │ ! │ ! │ - x row0 ─────┴────────┘ │ x row0 ─────┴────────┘ │ - │ │ │ │ - (key2) (┌─┘3) (key2) (┌─┘3) - ! ! ! ! - row1 ─────┴────────┘ x row1 ─────┴────────┘ - -全てが期待通りに動きます！これにより、以下のデータが取得されます: - - col0: 0b01 - col1: 0b11 - │└row0 - └row1 - -ファームウェアはこの正しいデータを使って、何をすべきかを、最終的には OS に送信する必要のある信号を検出できます。 - -参考文献: -- [Wikipedia の記事](https://en.wikipedia.org/wiki/Keyboard_matrix_circuit) -- [Deskthority の記事](https://deskthority.net/wiki/Keyboard_matrix) -- [Dave Dribin による Keyboard Matrix Help (2000)](https://www.dribin.org/dave/keyboard/one_html/) -- [PCBheaven による How Key Matrices Works](https://pcbheaven.com/wikipages/How_Key_Matrices_Works/) (アニメーションの例) -- [キーボードの仕組み - QMK ドキュメント](ja/how_keyboards_work.md) diff --git a/docs/ja/how_keyboards_work.md b/docs/ja/how_keyboards_work.md deleted file mode 100644 index 5c54e5ff73..0000000000 --- a/docs/ja/how_keyboards_work.md +++ /dev/null @@ -1,74 +0,0 @@ -# キーが登録され、コンピュータで解釈される仕組み - - - -このファイルでは、USB を介してキーボードがどのように動作するかの概念を学習できます。ファームウェアを直接変更することで何が期待できるかをより良く理解することができます。 - -## 概略図 - -特定のキーを1つ入力するたびに、このような一連のアクションが発生します: - -```text -+------+ +-----+ +----------+ +----------+ +----+ -| User |-------->| Key |------>| Firmware |----->| USB wire |---->| OS | -+------+ +-----+ +----------+ +----------+ +----+ -``` - -この図は何が起こっているかを非常に単純に示したものです。詳細については次のセクションで説明します。 - -## 1. キーを押す - -キーを押すたびに、キーボードのファームウェアはこのイベントを登録することができます。 -キーが押され、保持され、放された時に登録することができます。 - -これは通常キー押下の定期的な走査で発生します。多くの場合、キーの機械的な応答時間、キー押下情報を転送するプロトコル(ここでは USB HID)、あるいは使用されるソフトウェアによって、この速度は制限されます。 - -## 2. ファームウェアが送信するもの - -[HID 仕様](https://www.usb.org/sites/default/files/documents/hut1_12v2.pdf)では、適切に認識されるためにキーボードが USB 経由で実際に送信できるものを規定しています。これには、`0x00` から `0xE7` までの単純な数字であるスキャンコードの定義済リストが含まれます。ファームウェアはスキャンコードをキーボードのそれぞれのキーに割り当てます。 - -ファームウェアは実際の文字を送信せず、スキャンコードだけを送信します。 -従って、ファームウェアを変更することで、特定のキーにたいして USB を介してどのスキャンコードが送信されるかだけを変更することができます。 - -## 3. イベント入力やカーネルが行うこと - -*スキャンコード*は、[マスターブランチの 60-keyboard.hwdb](https://github.com/systemd/systemd/blob/master/hwdb.d/60-keyboard.hwdb) キーボードに依存する*キーコード*にマップされます。このマッピングが無いと、オペレーティングシステムは有効なキーコードを受信せず、キー押下で何も有用なことができません。 - -## 4. オペレーティングシステムがすること - -キーコードがオペレーティングシステムに到達すると、ソフトウェアの一部はキーボードのレイアウトによって、実際の文字と照合しなければなりません。例えば、レイアウトが QWERTY に設定されている場合、照合テーブルの例は以下の通りです: - -| キーコード | 文字 | -|---------|-----------| -| 0x04 | a/A | -| 0x05 | b/B | -| 0x06 | c/C | -| ... | ... | -| 0x1C | y/Y | -| 0x1D | z/Z | -| ... | ... | - -## 説明をファームウェアに戻して - -(独自のものを作成していない限り)レイアウトは一般的に固定されているため、ファームウェアは実際には作業を簡単するためレイアウト名で直接キーコードを記述できます。これが、`KC_A` が実際に QWERTY で `0x04` を表す場合に行われることです。完全なリストは[キーコード](ja/keycodes.md)にあります。 - -## 送信できる文字のリスト - -ショートカットを別として、限られたキーコードのセットが限られたレイアウトにマップされていることは、**指定されたキーに割り当てることができる文字のリストは、レイアウト内に存在するものだけである**ことを意味します。 - -例えば、QWERTY US レイアウトがあり、1つのキーを `€` (ユーロ通貨記号)を生成するように割り当てたい場合、そうすることができないことを意味します。なぜなら、QWERTY US レイアウトはそのようなマッピングを持たないためです。QWERTY UK レイアウト、あるいは QWERTY US International を使うことでそれを修正することができます。 - -全ての Unicode を含むキーボードレイアウトがなぜ考案されていないのか疑問に思うかもしれません。USB を介して利用可能なキーコードの数の制限により、このようなことは許可されません。 - -## (おそらく) Unicode 文字を入力する方法 - -ファームウェアに *一連のキー* を送信させて、目的のオペレーティングシステムの[ソフトウェア Unicode インプットメソッド](https://en.wikipedia.org/wiki/Unicode_input#Hexadecimal_input)を使うことができます。このようにして、OS で定義されたレイアウトとは無関係に文字を効率的に入力することができます。 - -ただし、以下のような複数の欠点があります: - -- 一度に、一つの特定の OS に縛られます (OS を変更する時に再コンパイルする必要があります); -- 特定の OS では、全てのソフトウェアが動作するわけではありません; -- 一部のシステムでは Unicode のサブセットに制限されます。 diff --git a/docs/ja/i2c_driver.md b/docs/ja/i2c_driver.md deleted file mode 100644 index 92c4185370..0000000000 --- a/docs/ja/i2c_driver.md +++ /dev/null @@ -1,134 +0,0 @@ -# I2C マスタドライバ :id=i2c-master-driver - - - -QMK で使われる I2C マスタドライバには、MCU 間のポータビリティを提供するための一連の関数が用意されています。 - -## I2C アドレスについての重要なメモ :id=note-on-i2c-addresses - -このドライバが期待する全てのアドレスは、アドレスバイトの上位7ビットにプッシュする必要があります。最下位ビットの設定(読み込み/書き込みを示す)は、それぞれの関数によって行われます。データシートやインターネットで列挙されているほとんど全ての I2C アドレスは、下位7ビットを占める7ビットとして表され、1ビット左(より上位)にシフトする必要があります。これは、ビット単位のシフト演算子 `<< 1` を使用して簡単に実行できます。 - -これは、呼び出しごとに以下の関数を実行するか、アドレスの定義で1度だけ実行するかどちらかで行うことができます。例えば、デバイスのアドレスが `0x18` の場合: - -`#define MY_I2C_ADDRESS (0x18 << 1)` - -I2C アドレスと他の技術詳細について、さらなる情報を得るためには https://www.robot-electronics.co.uk/i2c-tutorial を見てください。 - -## 使用できる関数 :id=available-functions - -| 関数 | 説明 | -|-------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `void i2c_init(void);` | I2C ドライバを初期化します。他のあらゆるトランザクションを開始する前に、この関数を一度だけ呼ぶ必要があります。 | -| `i2c_status_t i2c_transmit(uint8_t address, uint8_t* data, uint16_t length, uint16_t timeout);` | I2C 経由でデータを送信します。アドレスは方向ビットのない7ビットスレーブアドレスです。トランザクションのステータスを返します。 | -| `i2c_status_t i2c_receive(uint8_t address, uint8_t* data, uint16_t length, uint16_t timeout);` | I2C 経由でデータを受信します。アドレスは方向ビットのない7ビットスレーブアドレスです。 `length` で指定した長さのバイト列を `data` に保存し、トランザクションのステータスを返します。 | -| `i2c_status_t i2c_writeReg(uint8_t devaddr, uint8_t regaddr, uint8_t* data, uint16_t length, uint16_t timeout);` | `i2c_transmit` と同様ですが、 `regaddr` でスレーブのデータ書き込み先のレジスタを指定します。 | -| `i2c_status_t i2c_readReg(uint8_t devaddr, uint8_t regaddr, uint8_t* data, uint16_t length, uint16_t timeout);` | `i2c_receive` と同様ですが、 `regaddr` でスレーブのデータ読み込み先のレジスタを指定します。 | -| `i2c_status_t i2c_ping_address(uint8_t address, uint16_t timeout);` | I2C アドレスをテストします。アドレスは方向ビットのない7ビットスレーブアドレスです。 | - -### 関数の戻り値 :id=function-return - -`void i2c_init(void)` を除く上にあるすべての関数は、次の真理値表にある値を返します。 - -|戻り値の定数 |値 |説明 | -|--------------------|---|----------------------------| -|`I2C_STATUS_SUCCESS`|0 |処理が正常に実行されました。| -|`I2C_STATUS_ERROR` |-1 |処理に失敗しました。 | -|`I2C_STATUS_TIMEOUT`|-2 |処理がタイムアウトしました。| - -## AVR :id=avr - -### 設定 :id=avr-configuration - -I2Cマスタドライバを設定するために、次の定義が使えます。 - -| 変数 | 説明 | 既定値 | -|---------|---------------------|--------| -| `F_SCL` | クロック周波数 (Hz) | 400KHz | - - -AVR は通常 I2C ピンとして使う GPIO が設定されているので、これ以上の設定は必要ありません。 - -## ARM :id=arm - -ARM の場合は、内部に ChibiOS I2C HAL ドライバがあります。この節では STM32 MCU を使用していると仮定します。 - -### 設定 :id=arm-configuration - -ARM MCU 用の設定はしばしば非常に複雑です。これは、多くの場合複数の I2C ドライバをさまざまなポートに対して割り当てられるためです。 - -最初に、必要なハードウェアドライバを有効にするために `mcuconf.h` ファイルをセットアップします。 - -| 変数 | 説明 | 既定値 | -|-------------------------------|------------------------------------------------------------------------------------------------|--------| -| `#STM32_I2C_USE_XXX` | ハードウェアドライバ XXX の有効化/無効化（すべてのドライバを明示的にリストアップする必要あり） | FALSE | -| `#STM32_I2C_BUSY_TIMEOUT` | レスポンスの受信がない場合に I2C コマンドを中断するまでの時間 (ms) | 50 | -| `#STM32_I2C_XXX_IRQ_PRIORITY` | ハードウェアドライバ XXX の割り込み優先度（上級者向けの設定） | 10 | -| `#STM32_I2C_USE_DMA` | MCU がデータ送信を DMA ユニットにオフロードする機能の有効化/無効化 | TRUE | -| `#STM32_I2C_XXX_DMA_PRIORITY` | ハードウェアドライバ XXX に使用する DMA ユニットの優先度（上級者向けの設定） | 1 | - -次に `halconf.h` ファイル内で `#define HAL_USE_I2C` を `TRUE` にします。これにより ChibiOS が I2C ドライバを読み込みます。 - -最後に、使用したい I2C ハードウェアドライバに応じて正しい GPIO ピンを割り当てます。 - -標準では I2C1 ハードウェアドライバが使われます。もし他のハードウェアドライバを使う場合、 `config.h` ファイルに `#define I2C_DRIVER I2CDX` を追加します（ X は使用するハードウェアドライバの番号です）。例えば I2C3 を有効化する場合、`config.h` ファイルに `#define I2C_DRIVER I2CD3` と定義します。これにより QMK I2C ドライバと ChibiOS I2C driver が同期されます。 - -STM32 MCU では、使用するハードウェアドライバにより、さまざまなピンを I2C ピンとして設定できます。標準では `B6`, `B7` ピンが I2C 用のピンです。 I2C 用のピンを設定するために次の定義が使えます： - -| 変数 | 説明 | 既定値 | -|-----------------------|-------------------------------------------------------------------------------------------|---------| -| `I2C1_SCL_PIN` | SCL のピン番号 | `B6` | -| `I2C1_SDA_PIN` | SDA のピン番号 | `B7` | - -ChibiOS I2C ドライバの設定項目は STM32 MCU の種類に依存します。 - - STM32F1xx, STM32F2xx, STM32F4xx, STM32L0xx, STM32L1xx では I2Cv1 が使われます。 - STM32F0xx, STM32F3xx, STM32F7xx, STM32L4xx では I2Cv2 が使われます。 - -#### I2Cv1 :id=i2cv1 - -STM32 MCU の I2Cv1 では、クロック周波数とデューティ比を次の変数で変更できます。詳しくは を参照してください。 - -| 変数 | 既定値 | -|--------------------|------------------| -| `I2C1_OPMODE` | `OPMODE_I2C` | -| `I2C1_CLOCK_SPEED` | `100000` | -| `I2C1_DUTY_CYCLE` | `STD_DUTY_CYCLE` | - -#### I2Cv2 :id=i2cv2 - -STM32 MCU の I2Cv2 では、信号のタイミングパラメータを次の変数で変更できます。詳しくは を参照してください。 - -| 変数 | 既定値 | -|-----------------------|--------| -| `I2C1_TIMINGR_PRESC` | `15U` | -| `I2C1_TIMINGR_SCLDEL` | `4U` | -| `I2C1_TIMINGR_SDADEL` | `2U` | -| `I2C1_TIMINGR_SCLH` | `15U` | -| `I2C1_TIMINGR_SCLL` | `21U` | - -STM32 MCU では GPIO ピンを設定するとき、別の「代替機能」モードを使うことができます。これは I2Cv2 モードで使われるピンを変更するために必要です。適切な設定値は、使用している MCU のデータシートを参照してください。 - -| 変数 | 既定値 | -|---------------------|--------| -| `I2C1_SCL_PAL_MODE` | `4` | -| `I2C1_SDA_PAL_MODE` | `4` | - -#### その他 :id=other - -`void i2c_init(void)` 関数は `weak` 属性が付いており、オーバーロードすることができます。この場合、上記で設定した変数は使用されません。可能な GPIO の設定については、 MCU のデータシートを参照してください。次に示すのは初期化関数の例です： - -```c -void i2c_init(void) -{ - setPinInput(B6); // Try releasing special pins for a short time - setPinInput(B7); - wait_ms(10); // Wait for the release to happen - - palSetPadMode(GPIOB, 6, PAL_MODE_ALTERNATE(4) | PAL_STM32_OTYPE_OPENDRAIN | PAL_STM32_PUPDR_PULLUP); // Set B6 to I2C function - palSetPadMode(GPIOB, 7, PAL_MODE_ALTERNATE(4) | PAL_STM32_OTYPE_OPENDRAIN | PAL_STM32_PUPDR_PULLUP); // Set B7 to I2C function -} -``` diff --git a/docs/ja/isp_flashing_guide.md b/docs/ja/isp_flashing_guide.md deleted file mode 100644 index d629b964b2..0000000000 --- a/docs/ja/isp_flashing_guide.md +++ /dev/null @@ -1,294 +0,0 @@ -# ISP 書き込みガイド - - - -ISP 書き込み(ICSP 書き込みと呼ぶ場合もあります)とは、マイクロコントローラーを直接プログラミングするプロセスです。 -これにより、ブートローダを交換したり、コントローラの「ヒューズ」を変更することができ、コントローラの速度や起動方法、その他のオプションなど、多くのハードウェアおよびソフトウェア関連の機能を制御します。 - -QMK の ISP 書き込みの主な用途は、AVRベースのコントローラ（Pro Micro、または V-USB チップ）のブートローダの書き込みまたは交換です。 - -?> これは Pro Micro や他の ATmega コントローラなどの AVR ベースのボードをプログラミングするためだけのものです。 Proton C などの Arm コントローラには使用できません。 - -## 破損したブートローダーの取り扱い - -ボードの書き込み/消去で問題が発生し、DFU ベースのコントローラで次のような不可解なエラーメッセージが表示される場合： - - libusb: warning [darwin_transfer_status] transfer error: timed out - dfu.c:844: -ETIMEDOUT: Transfer timed out, NAK 0xffffffc4 (-60) - atmel.c:1627: atmel_flash: flash data dfu_download failed. - atmel.c:1629: Expected message length of 1072, got -60. - atmel.c:1434: Error flashing the block: err -2. - ERROR - Memory write error, use debug for more info. - commands.c:360: Error writing memory data. (err -4) - - dfu.c:844: -EPIPE: a) Babble detect or b) Endpoint stalled 0xffffffe0 (-32) - Device is write protected. - dfu.c:252: dfu_clear_status( 0x7fff4fc2ea80 ) - atmel.c:1434: Error flashing the block: err -2. - ERROR - Memory write error, use debug for more info. - commands.c:360: Error writing memory data. (err -4) - -または、Pro Micro ベースのコントローラに対して次のようなメッセージが表示された場合: - - avrdude: butterfly_recv(): programmer is not responding - avrdude: butterfly_recv(): programmer is not responding - avrdude: verification error, first mismatch at byte 0x002a - 0x2b != 0x75 - avrdude: verification error; content mismatch - avrdude: verification error; content mismatch - - -あなたのボード/デバイスを再び動作させるには、ISP 書き込みが必要になるかもしれません。 - -## 必要なハードウェア - -実際に ISP の書き込みを行うには、以下のいずれか（その後に使用するプロトコルが続きます）が必要になります。 - -* [SparkFun PocketAVR](https://www.sparkfun.com/products/9825) - (USB Tiny) -* [USBtinyISP AVR Programmer Kit](https://www.adafruit.com/product/46) - (USB Tiny) -* [USBasp](https://www.fischl.de/usbasp/) - (usbasp) -* [Teensy 2.0](https://www.pjrc.com/store/teensy.html) - (avrisp) -* [Pro Micro](https://www.sparkfun.com/products/12640) - (avrisp) -* [Bus Pirate](https://www.adafruit.com/product/237) - (buspirate) - -ISP 書き込みに使用できるデバイスは他にもありますが、これらが主なものです。 -また、すべての製品リンクは公式バージョンへのものです。他の場所で入手することもできます。 - -また、「ISP プログラマ」をプログラミングするデバイスに配線するためのものも必要になります。 -PCB の中には直接使用できる ISP ヘッダがあるものもありますが、そうではない場合が多いので、コントローラ自体にハンダ付けするか、別のスイッチや他のコンポーネントにハンダ付けする必要があるでしょう。 - -### ISP ファームウェア - -Teensy と Pro Micro のコントローラを ISP プログラマとして使用するには、コントローラに ISP ファームウェアを書き込む必要があります。 -それ以外のハードウェアは、あらかじめプログラムされているはずです。 -そのため、これらのコントローラの場合は、正しい hex ファイルをダウンロードしてから書き込んでください。 - -* Teensy 2.0: [`util/teensy_2.0_ISP_B0.hex`](https://github.com/qmk/qmk_firmware/blob/master/util/teensy_2.0_ISP_B0.hex) (`B0`) -* Pro Micro: [`util/pro_micro_ISP_B6_10.hex`](https://github.com/qmk/qmk_firmware/blob/master/util/pro_micro_ISP_B6_10.hex) (`10/B6`) - -コントローラに書き込んだら、この hex ファイルはもう必要ありません。 - -## 必要なソフトウェア - -QMK ツールボックスは、このほとんど（すべて）に使用することができます。 - -ただし、Teensy 2.0 ボードを使っている場合は、[Teensy Loader](https://www.pjrc.com/teensy/loader.html) を使えば、Teensy 2.0 ボードに書き込むことができます。 -あるいは、`avrdude` (`qmk_install.sh` の一部としてインストールされています) や、[AVRDUDESS](https://blog.zakkemble.net/avrdudess-a-gui-for-avrdude/) (Windows 用) を使って、Pro Micro に書き込んだり、ISP を書き込んだりすることができます。 - -## 配線 - -これは非常に簡単です。次のようにして、相互に対応するものを接続します。 - -### SparkFun Pocket AVR - - PocketAVR RST <-> Keyboard RESET - PocketAVR SCLK <-> Keyboard B1 (SCLK) - PocketAVR MOSI <-> Keyboard B2 (MOSI) - PocketAVR MISO <-> Keyboard B3 (MISO) - PocketAVR VCC <-> Keyboard VCC - PocketAVR GND <-> Keyboard GND - -### USBasp - - USBasp RST <-> Keyboard RESET - USBasp SCLK <-> Keyboard B1 (SCLK) - USBasp MOSI <-> Keyboard B2 (MOSI) - USBasp MISO <-> Keyboard B3 (MISO) - USBasp VCC <-> Keyboard VCC - USBasp GND <-> Keyboard GND - -### Teensy 2.0 - - Teensy B0 <-> Keyboard RESET - Teensy B1 <-> Keyboard B1 (SCLK) - Teensy B2 <-> Keyboard B2 (MOSI) - Teensy B3 <-> Keyboard B3 (MISO) - Teensy VCC <-> Keyboard VCC - Teensy GND <-> Keyboard GND - -!> Teensy の B0 ピンはキーボードのコントローラの RESET/RST ピンと配線されています。 Teensy の RESET ピンをキーボードの RESET に配線しないでください。 - -### Pro Micro - - Pro Micro 10 (B6) <-> Keyboard RESET - Pro Micro 15 (B1) <-> Keyboard B1 (SCLK) - Pro Micro 16 (B2) <-> Keyboard B2 (MOSI) - Pro Micro 14 (B3) <-> Keyboard B3 (MISO) - Pro Micro VCC <-> Keyboard VCC - Pro Micro GND <-> Keyboard GND - -!> Pro Micro の 10/B6 ピンはキーボードのコントローラの RESET/RST ピンに配線されています。 Pro Micro の RESET ピンをキーボードの RESET に配線 ***しないでください***。 - -## キーボードへの書き込み - -ISP プログラマをセットアップして、キーボードに接続したら、キーボードに書き込みをします。 - -### ブートローダファイル - -普通の状態に戻す一番簡単で手っ取り早い方法は、キーボードにブートローダだけ書き込むことです。 -これが終れば、普通にキーボードを接続して、普通にキーボードに書き込みできるようになります。 - -標準のブートローダは[`util/` フォルダー](https://github.com/qmk/qmk_firmware/tree/master/util) にあります。 -チップの正しいブートローダを書き込んでください: - -* **Atmel DFU** - * [ATmega16U4](https://github.com/qmk/qmk_firmware/blob/master/util/bootloader_atmega16u4_1.0.1.hex) - * [ATmega32U4](https://github.com/qmk/qmk_firmware/blob/master/util/bootloader_atmega32u4_1.0.0.hex) - * [AT90USB64](https://github.com/qmk/qmk_firmware/blob/master/util/bootloader_at90usb64_1.0.0.hex) - * [AT90USB128](https://github.com/qmk/qmk_firmware/blob/master/util/bootloader_at90usb128_1.0.1.hex) -* **Caterina** - * [Pro Micro (5V/16MHz)](https://github.com/sparkfun/Arduino_Boards/blob/master/sparkfun/avr/bootloaders/caterina/Caterina-promicro16.hex) - * [Pro Micro (3.3V/8MHz)](https://github.com/sparkfun/Arduino_Boards/blob/master/sparkfun/avr/bootloaders/caterina/Caterina-promicro8.hex) -* **BootloadHID (PS2AVRGB)** - * [ATmega32A](https://github.com/qmk/qmk_firmware/blob/master/util/bootloader_ps2avrgb_bootloadhid_1.0.1.hex) - -お使いのボードが何を使っているかわからない場合は、QMK のキーボード用の `rules.mk` ファイルを見てください。 -`MCU` と `BOOTLOADER` の行には必要な値が書かれています。これはボードのバージョンによって異なるかもしれません。 - -### 製造手法 - -ブートローダと通常のファームウェアを同時に書き込みたい場合、2つの方法があります。 -手動で行うか、コンパイル時に `:production` ターゲットを使って行うかです。 - -手動で行うには: - -1. オリジナルのファームウェアの .hex ファイルをテキストエディタで開きます -2. 最後の行を削除してください。(`:00000001FF`になっているはずです - これは EOF メッセージです) -3. ブートローダの内容全体を新しい行にコピーして(行間に空行を入れないように)、元のファイルの最後に貼り付けてください。 -4. これを新しいファイルとして `__production.hex` という名前で保存します。 - -?> ここでは他のブートローダも同じように使うことができますが、__ブートローダが必要で__、そうしないとまた ISP を使ってキーボードに新しいファームウェアを書き込まなければならなくなります。 - -#### QMK DFU ブートローダとプロダクションイメージの作成 - -コンパイル時に `:production` ターゲットを使用して、ボード用のファームウェア、QMK DFU ブートローダ、プロダクションファームウェアイメージを作成することができます。 -これが完了すると、3つのファイルが表示されます: - -* `_.hex` -* `__bootloader.hex` -* `__production.hex` - -QMK DFU ブートローダは `atmega32u4` コントローラ (AVR ベースの Planck ボードや Pro Micro など) でしかテストされておらず、他のコントローラではテストされていません。 -しかし、`atmega32a` や `atmega328p` のような V-USB コントローラでは間違いなく動作しません。 - -ブートローダかプロダクションファームウェアファイルのどちらかを書き込むことができます。 -プロダクションファームウェアファイルの方が、より多くのデータを書き込むので、書き込みに時間がかかります。 - -?> 注意：同じブートローダを使用しつづけるべきです。すでに DFU を使用している場合は、QMK DFU に切り替えても問題ありません。しかし、例えば Pro Micro に QMK DFU を書き込むには、追加の手順が必要になります。 - -## ブートローダ/プロダクションファイルの書き込み - -キーボードがどのデバイスにも接続されていないことを確認し、ISP プログラマを接続してください。 - -ブートローダの種類を変更したい場合は、コマンドラインを使用する必要があります。 - -### QMK Toolbox - -1. `AVRISP device connected` または `USB Tiny device connected` が黄色で表示されます。 -2. `Open` ダイアログで正しいブートローダー/プロダクションの .hex ファイルを選択します（パスにスペースを含めることはできません） -3. 書きこもうとしているキーボード（ISP プログラマではなく）のための正しい `Microcontroller` オプションが選択されていることを確認してください。 -4. `Flash` を押します -5. 特にプロダクションファイルの場合、しばらくは何も出力されませんが、待ちましょう。 - -検証とヒューズのチェックに問題がなければ、完了です。 -ボードが自動的に再起動する場合があります。 -それ以外の場合は、Teensy のプラグを抜いて、キーボードを接続します。 -テスト中は、Teensy をキーボードに接続したままにすることができますが、すべてが正常に機能することを確認したら、はんだを外すか、配線を外すことをお勧めします。 - -### コマンドライン - -ターミナル（Windows の場合は `cmd`）を開いて、修正した .hex ファイルがある場所に移動します。 -ここでは、このファイルを `main.hex` と呼び、Teensy 2.0 が `COM3` ポートに接続されていると仮定します。 -よくわからない場合は、デバイスマネージャを開いて、`Ports > USB Serial Device` を探してください。ここにある COM ポートを使ってください。 -あなたはそれが正しいポートであることを確認することができます： - - avrdude -c avrisp -P COM3 -p atmega32u4 - -次のような出力が得られるはずです: - - avrdude: AVR device initialized and ready to accept instructions - - Reading | ################################################## | 100% 0.02s - - avrdude: Device signature = 0x1e9587 - - avrdude: safemode: Fuses OK - - avrdude done. Thank you. - -私たちのキーボードは `atmega32u4`（共通）を使用しているので、これが指定するチップです。 -以下が完全なコマンドです： - - avrdude -c avrisp -P COM3 -p atmega32u4 -U flash:w:main.hex:i - -ボードが `atmega32a`（jj40 など）を使用している場合、コマンドは次のとおりです（最後の追加コードによりヒューズが正しく設定されます）。 - - avrdude -c avrisp -P COM3 -p atmega32 -U flash:w:main.hex:i -U hfuse:w:0xD0:m -U lfuse:w:0x0F:m - -プログレスバーが表示されてから、以下が表示されるはずです。 - - avrdude: verifying ... - avrdude: 32768 bytes of flash verified - - avrdude: safemode: Fuses OK - - avrdude done. Thank you. - -これは全てうまく動作したことを示しています。 -ボードが自動的に再起動する場合もありますが、そうでない場合は、Teensy のプラグを抜いてキーボードを接続してください。 -テスト中は、Teensy をキーボードに接続したままにすることができますが、すべてが正常に機能することを確認したら、はんだを外すか、配線を外すことをお勧めします。 - -SparkFun PocketAVR Programmer や、他の USB Tiny ベースの ISP プログラマを使用している場合は、次のようなものを使用すると良いでしょう。 - - avrdude -c usbtiny -P usb -p atmega32u4 - -#### 上級者向け: ヒューズの変更 - -Pro Micro に QMK DFU を書き込むなど、ブートローダを切り替える場合は、ブートローダの hex ファイルの書き込みに加えて、ヒューズを変更する必要があります。 -これは、`caterina` (Pro Micro ブートローダ) と `dfu` では起動ルーチンの扱いが異なり、その動作はヒューズによって制御されるからです。 - -!> これは、ヒューズを変更することは、永久にあなたのコントローラをレンガ化(訳注:日本では文鎮化と呼ぶことが多い、コントローラがまったく無反応になる状態)することができる方法の1つであるため、それは非常に注意が必要な1つの領域です。 - -以下は、`atmega32u4`の 5V 16MHz 版（5V Pro Micro など）を想定しています。 - -`atmega32u4`の DFU の場合、必要なヒューズ設定は次のとおりです: - -| ヒューズ | 設定 | -|----------|------------------| -| Low | `0x5E` | -| High | `0xD9` or `0x99` | -| Extended | `0xC3` | - -High ヒューズは 0xD9 か 0x99 のどちらかになります。 -違いは、0xD9 は QMK Firmware がソフトウェアでも無効化している JTAG を無効化しているのに対し、0x99 は JTAG を無効化していないことです。 - -これを設定するには、`-U lfuse:w:0x5E:m -U hfuse:w:0xD9:m -U efuse:w:0xC3:m` をコマンドに追加します。 -そうすると、最終的なコマンドは次のようになります。 - - avrdude -c avrisp -P COM3 -p atmega32u4 -U flash:w:main.hex:i -U lfuse:w:0x5E:m -U hfuse:w:0xD9:m -U efuse:w:0xC3:m - -`atmega32u4`の Caterina では、以下があなたに必要なヒューズの設定です。 - -| ヒューズ | 設定 | -|----------|--------| -| Low | `0xFF` | -| High | `0xD8` | -| Extended | `0xCB` | - -これを設定するには、コマンドに `-U lfuse:w:0xFF:m -U hfuse:w:0xD8:m -U efuse:w:0xCB:m` を追加します。 -これで、最終的なコマンドは次のようになるはずです。 - - avrdude -c avrisp -P COM3 -p atmega32u4 -U flash:w:main.hex:i -U lfuse:w:0xFF:m -U hfuse:w:0xD8:m -U efuse:w:0xCB:m - - -別のコントローラーを使用している場合や、別の設定を希望する場合は、この[AVR ヒューズ計算機](https://www.engbedded.com/fusecalc/)を使用して、より適切な値を見つけることができます。 - -## ヘルプ - -ご質問・ご不明な点がありましたら、お気軽に[issue を開いてください](https://github.com/qmk/qmk_firmware/issues/new)！ diff --git a/docs/ja/ja_doc_status.sh b/docs/ja/ja_doc_status.sh deleted file mode 100644 index 3dfbbd2bc6..0000000000 --- a/docs/ja/ja_doc_status.sh +++ /dev/null @@ -1,34 +0,0 @@ -#! /bin/sh -# -# Script to display the Japanese translation status of documents -# -if [ ! -d docs/ja ]; then - echo "'docs/ja' not found." - echo "do:" - echo " cd \$(QMK_TOP)" - echo " ./docs/ja/ja_doc_status.sh" - exit 1 -fi - -en_docs=`cd docs;ls -1 [a-z]*.md` -ja_docs=`cd docs/ja;ls -1 [a-z]*.md` -en_count=`echo $en_docs | wc -w` -ja_count=`echo $ja_docs | wc -w` -echo "English documents $en_count files." -echo "Japanese documents $ja_count files." - -echo "Files that have not been translated yet:" -for docfile in $en_docs -do - if [ ! -f docs/ja/$docfile ]; then - wc docs/$docfile - fi -done | sort -echo "Files that have not been updated yet:" -grep --no-filename "^[ ]*git diff" docs/ja/*.md | while read cmd -do - cline=`echo $cmd | sh | wc -l` - if [ $cline -gt 0 ]; then - echo "$cline $cmd" - fi -done | sort diff --git a/docs/ja/keycodes.md b/docs/ja/keycodes.md deleted file mode 100644 index 2e339af35b..0000000000 --- a/docs/ja/keycodes.md +++ /dev/null @@ -1,574 +0,0 @@ -# キーコードの概要 - - - -[キーマップ](ja/keymap.md) を定義するときは、それぞれのキーに有効な定義が必要です。このページは、QMK で使えるキーコードに相当するシンボルについて記述しています。 - -このページは参照のみです。それぞれのキーの種類毎のリンク先のページに、それぞれのキーの機能についてもっと詳細に記載しています。 - -## 基本的なキーコード :id=basic-keycodes - -[基本的なキーコード](ja/keycodes_basic.md) も見てください。 - -?> 訳注: 以下の説明は、OS のキーボード配列の設定が「US」の場合のものです。OS のキーボード配列の設定が「JIS」の場合、一部のキーは下の表と異なる文字が入力されます。例えば、`KC_LBRC` は、OS のキーボード配列の設定が US であれば「`[` または `{`」が入力されますが、JIS の場合「`@` または `」が入力されます。 -?> これは、OS がキーボードから送信されたキーコードを解釈する際に、キーボード配列の設定によって対応する文字を変えるためです。もし、OS のキーボード配列の設定を JIS にする場合、`#include "keymap_jp.h"` を `keymap.c` に追加すると`JP_AT` のような JIS キーボードのキーキャップに対応したキーを指定できます。 - -|キー |エイリアス |説明 |Windows |macOS |Linux1| -|-----------------------|------------------------------|-----------------------------------------|-------------|-------------|-----------------| -|`KC_NO` |`XXXXXXX` |このキーを無視します (何もしません) 。 |*N/A* |*N/A* |*N/A* | -|`KC_TRANSPARENT` |`KC_TRNS`, `_______` | 次に低いレイヤーの非透過キーを使う |*N/A* |*N/A* |*N/A* | -|`KC_A` | |`a` と `A` |✔ |✔ |✔ | -|`KC_B` | |`b` と `B` |✔ |✔ |✔ | -|`KC_C` | |`c` と `C` |✔ |✔ |✔ | -|`KC_D` | |`d` と `D` |✔ |✔ |✔ | -|`KC_E` | |`e` と `E` |✔ |✔ |✔ | -|`KC_F` | |`f` と `F` |✔ |✔ |✔ | -|`KC_G` | |`g` と `G` |✔ |✔ |✔ | -|`KC_H` | |`h` と `H` |✔ |✔ |✔ | -|`KC_I` | |`i` と `I` |✔ |✔ |✔ | -|`KC_J` | |`j` と `J` |✔ |✔ |✔ | -|`KC_K` | |`k` と `K` |✔ |✔ |✔ | -|`KC_L` | |`l` と `L` |✔ |✔ |✔ | -|`KC_M` | |`m` と `M` |✔ |✔ |✔ | -|`KC_N` | |`n` と `N` |✔ |✔ |✔ | -|`KC_O` | |`o` と `O` |✔ |✔ |✔ | -|`KC_P` | |`p` と `P` |✔ |✔ |✔ | -|`KC_Q` | |`q` と `Q` |✔ |✔ |✔ | -|`KC_R` | |`r` と `R` |✔ |✔ |✔ | -|`KC_S` | |`s` と `S` |✔ |✔ |✔ | -|`KC_T` | |`t` と `T` |✔ |✔ |✔ | -|`KC_U` | |`u` と `U` |✔ |✔ |✔ | -|`KC_V` | |`v` と `V` |✔ |✔ |✔ | -|`KC_W` | |`w` と `W` |✔ |✔ |✔ | -|`KC_X` | |`x` と `X` |✔ |✔ |✔ | -|`KC_Y` | |`y` と `Y` |✔ |✔ |✔ | -|`KC_Z` | |`z` と `Z` |✔ |✔ |✔ | -|`KC_1` | |`1` と `!` |✔ |✔ |✔ | -|`KC_2` | |`2` と `@` |✔ |✔ |✔ | -|`KC_3` | |`3` と `#` |✔ |✔ |✔ | -|`KC_4` | |`4` と `$` |✔ |✔ |✔ | -|`KC_5` | |`5` と `%` |✔ |✔ |✔ | -|`KC_6` | |`6` と `^` |✔ |✔ |✔ | -|`KC_7` | |`7` と `&` |✔ |✔ |✔ | -|`KC_8` | |`8` と `*` |✔ |✔ |✔ | -|`KC_9` | |`9` と `(` |✔ |✔ |✔ | -|`KC_0` | |`0` と `)` |✔ |✔ |✔ | -|`KC_ENTER` |`KC_ENT` |Return (Enter) |✔ |✔ |✔ | -|`KC_ESCAPE` |`KC_ESC` |Escape |✔ |✔ |✔ | -|`KC_BSPACE` |`KC_BSPC` |Delete (Backspace) |✔ |✔ |✔ | -|`KC_TAB` | |Tab |✔ |✔ |✔ | -|`KC_SPACE` |`KC_SPC` |Spacebar |✔ |✔ |✔ | -|`KC_MINUS` |`KC_MINS` |`-` と `_` |✔ |✔ |✔ | -|`KC_EQUAL` |`KC_EQL` |`=` と `+` |✔ |✔ |✔ | -|`KC_LBRACKET` |`KC_LBRC` |`[` と `{` |✔ |✔ |✔ | -|`KC_RBRACKET` |`KC_RBRC` |`]` と `}` |✔ |✔ |✔ | -|`KC_BSLASH` |`KC_BSLS` |`\` と `\|` |✔ |✔ |✔ | -|`KC_NONUS_HASH` |`KC_NUHS` |Non-US `#` と `~` |✔ |✔ |✔ | -|`KC_SCOLON` |`KC_SCLN` |`;` と `:` |✔ |✔ |✔ | -|`KC_QUOTE` |`KC_QUOT` |`'` と `"` |✔ |✔ |✔ | -|`KC_GRAVE` |`KC_GRV`, `KC_ZKHK` |` と `~`, JIS 全角/半角 |✔ |✔ |✔ | -|`KC_COMMA` |`KC_COMM` |`,` と `<` |✔ |✔ |✔ | -|`KC_DOT` | |`.` と `>` |✔ |✔ |✔ | -|`KC_SLASH` |`KC_SLSH` |`/` と `?` |✔ |✔ |✔ | -|`KC_CAPSLOCK` |`KC_CLCK`, `KC_CAPS` |Caps Lock |✔ |✔ |✔ | -|`KC_F1` | |F1 |✔ |✔ |✔ | -|`KC_F2` | |F2 |✔ |✔ |✔ | -|`KC_F3` | |F3 |✔ |✔ |✔ | -|`KC_F4` | |F4 |✔ |✔ |✔ | -|`KC_F5` | |F5 |✔ |✔ |✔ | -|`KC_F6` | |F6 |✔ |✔ |✔ | -|`KC_F7` | |F7 |✔ |✔ |✔ | -|`KC_F8` | |F8 |✔ |✔ |✔ | -|`KC_F9` | |F9 |✔ |✔ |✔ | -|`KC_F10` | |F10 |✔ |✔ |✔ | -|`KC_F11` | |F11 |✔ |✔ |✔ | -|`KC_F12` | |F12 |✔ |✔ |✔ | -|`KC_PSCREEN` |`KC_PSCR` |Print Screen |✔ |✔2|✔ | -|`KC_SCROLLLOCK` |`KC_SCRL`, `KC_BRMD` |Scroll Lock, 画面の明るさダウン (macOS) |✔ |✔2|✔ | -|`KC_PAUSE` |`KC_PAUS`, `KC_BRK`, `KC_BRMU`|Pause, 画面の明るさアップ (macOS) |✔ |✔2|✔ | -|`KC_INSERT` |`KC_INS` |Insert |✔ | |✔ | -|`KC_HOME` | |Home |✔ |✔ |✔ | -|`KC_PGUP` | |Page Up |✔ |✔ |✔ | -|`KC_DELETE` |`KC_DEL` |Forward Delete |✔ |✔ |✔ | -|`KC_END` | |End |✔ |✔ |✔ | -|`KC_PGDOWN` |`KC_PGDN` |Page Down |✔ |✔ |✔ | -|`KC_RIGHT` |`KC_RGHT` |右矢印 |✔ |✔ |✔ | -|`KC_LEFT` | |左矢印 |✔ |✔ |✔ | -|`KC_DOWN` | |下矢印 |✔ |✔ |✔ | -|`KC_UP` | |上矢印 |✔ |✔ |✔ | -|`KC_NUMLOCK` |`KC_NUM` |テンキー Num Lock と Clear |✔ |✔ |✔ | -|`KC_KP_SLASH` |`KC_PSLS` |テンキー `/` |✔ |✔ |✔ | -|`KC_KP_ASTERISK` |`KC_PAST` |テンキー `*` |✔ |✔ |✔ | -|`KC_KP_MINUS` |`KC_PMNS` |テンキー `-` |✔ |✔ |✔ | -|`KC_KP_PLUS` |`KC_PPLS` |テンキー `+` |✔ |✔ |✔ | -|`KC_KP_ENTER` |`KC_PENT` |テンキー Enter |✔ |✔ |✔ | -|`KC_KP_1` |`KC_P1` |テンキー `1` と End |✔ |✔ |✔ | -|`KC_KP_2` |`KC_P2` |テンキー `2` と下矢印 |✔ |✔ |✔ | -|`KC_KP_3` |`KC_P3` |テンキー `3` と Page Down |✔ |✔ |✔ | -|`KC_KP_4` |`KC_P4` |テンキー `4` と左矢印 |✔ |✔ |✔ | -|`KC_KP_5` |`KC_P5` |テンキー `5` |✔ |✔ |✔ | -|`KC_KP_6` |`KC_P6` |テンキー `6` と右矢印 |✔ |✔ |✔ | -|`KC_KP_7` |`KC_P7` |テンキー `7` と Home |✔ |✔ |✔ | -|`KC_KP_8` |`KC_P8` |テンキー `8` と上矢印 |✔ |✔ |✔ | -|`KC_KP_9` |`KC_P9` |テンキー `9` と Page Up |✔ |✔ |✔ | -|`KC_KP_0` |`KC_P0` |テンキー `0` と Insert |✔ |✔ |✔ | -|`KC_KP_DOT` |`KC_PDOT` |テンキー `.` と Delete |✔ |✔ |✔ | -|`KC_NONUS_BSLASH` |`KC_NUBS` |Non-US `\` と `\|` |✔ |✔ |✔ | -|`KC_APPLICATION` |`KC_APP` |アプリケーションキー (Windows コンテキストメニューキー) |✔ | |✔ | -|`KC_POWER` | |システム電源 | |✔3|✔ | -|`KC_KP_EQUAL` |`KC_PEQL` |テンキー `=` |✔ |✔ |✔ | -|`KC_F13` | |F13 |✔ |✔ |✔ | -|`KC_F14` | |F14 |✔ |✔ |✔ | -|`KC_F15` | |F15 |✔ |✔ |✔ | -|`KC_F16` | |F16 |✔ |✔ |✔ | -|`KC_F17` | |F17 |✔ |✔ |✔ | -|`KC_F18` | |F18 |✔ |✔ |✔ | -|`KC_F19` | |F19 |✔ |✔ |✔ | -|`KC_F20` | |F20 |✔ | |✔ | -|`KC_F21` | |F21 |✔ | |✔ | -|`KC_F22` | |F22 |✔ | |✔ | -|`KC_F23` | |F23 |✔ | |✔ | -|`KC_F24` | |F24 |✔ | |✔ | -|`KC_EXECUTE` |`KC_EXEC` |Execute | | |✔ | -|`KC_HELP` | |Help | | |✔ | -|`KC_MENU` | |Menu | | |✔ | -|`KC_SELECT` |`KC_SLCT` |Select | | |✔ | -|`KC_STOP` | |Stop | | |✔ | -|`KC_AGAIN` |`KC_AGIN` |Again | | |✔ | -|`KC_UNDO` | |アンドゥ | | |✔ | -|`KC_CUT` | |カット | | |✔ | -|`KC_COPY` | |コピー | | |✔ | -|`KC_PASTE` |`KC_PSTE` |ペースト | | |✔ | -|`KC_FIND` | |検索 | | |✔ | -|`KC__MUTE` | |ミュート | |✔ |✔ | -|`KC__VOLUP` | |音量アップ | |✔ |✔ | -|`KC__VOLDOWN` | |音量ダウン | |✔ |✔ | -|`KC_LOCKING_CAPS` |`KC_LCAP` |Caps Lock のロック |✔ |✔ | | -|`KC_LOCKING_NUM` |`KC_LNUM` |Num Lock のロック |✔ |✔ | | -|`KC_LOCKING_SCROLL` |`KC_LSCR` |Scroll Lock のロック |✔ |✔ | | -|`KC_KP_COMMA` |`KC_PCMM` |テンキー `,` | | |✔ | -|`KC_KP_EQUAL_AS400` | |AS/400 キーボードのテンキー `=` | | | | -|`KC_INT1` |`KC_RO` |JIS `\` と `_` |✔ | |✔ | -|`KC_INT2` |`KC_KANA` |JIS カタカナ/ひらがな |✔ | |✔ | -|`KC_INT3` |`KC_JYEN` |JIS `¥` と `\|` |✔ | |✔ | -|`KC_INT4` |`KC_HENK` |JIS 変換 |✔ | |✔ | -|`KC_INT5` |`KC_MHEN` |JIS 無変換 |✔ | |✔ | -|`KC_INT6` | |JIS テンキー `,` | | |✔ | -|`KC_INT7` | |International 7 | | | | -|`KC_INT8` | |International 8 | | | | -|`KC_INT9` | |International 9 | | | | -|`KC_LANG1` |`KC_HAEN` |ハングル/英語 | | |✔ | -|`KC_LANG2` |`KC_HANJ` |韓文漢字 | | |✔ | -|`KC_LANG3` | |JIS カタカナ | | |✔ | -|`KC_LANG4` | |JIS ひらがな | | |✔ | -|`KC_LANG5` | |JIS 全角/半角 | | |✔ | -|`KC_LANG6` | |Language 6 | | | | -|`KC_LANG7` | |Language 7 | | | | -|`KC_LANG8` | |Language 8 | | | | -|`KC_LANG9` | |Language 9 | | | | -|`KC_ALT_ERASE` |`KC_ERAS` |Alternate Erase | | | | -|`KC_SYSREQ` | |SysReq/Attention | | | | -|`KC_CANCEL` | |Cancel | | | | -|`KC_CLEAR` |`KC_CLR` |Clear | | |✔ | -|`KC_PRIOR` | |Prior | | | | -|`KC_RETURN` | |Return | | | | -|`KC_SEPARATOR` | |Separator | | | | -|`KC_OUT` | |Out | | | | -|`KC_OPER` | |Oper | | | | -|`KC_CLEAR_AGAIN` | |Clear/Again | | | | -|`KC_CRSEL` | |CrSel/Props | | | | -|`KC_EXSEL` | |ExSel | | | | -|`KC_LCTRL` |`KC_LCTL` |左 Control |✔ |✔ |✔ | -|`KC_LSHIFT` |`KC_LSFT` |左 Shift |✔ |✔ |✔ | -|`KC_LALT` |`KC_LOPT` |左 Alt (Option) |✔ |✔ |✔ | -|`KC_LGUI` |`KC_LCMD`, `KC_LWIN` |左 GUI (Windows/Command/Meta key) |✔ |✔ |✔ | -|`KC_RCTRL` |`KC_RCTL` |右 Control |✔ |✔ |✔ | -|`KC_RSHIFT` |`KC_RSFT` |右 Shift |✔ |✔ |✔ | -|`KC_RALT` |`KC_ROPT`, `KC_ALGR` |右 Alt (Option/AltGr) |✔ |✔ |✔ | -|`KC_RGUI` |`KC_RCMD`, `KC_RWIN` |右 GUI (Windows/Command/Meta key) |✔ |✔ |✔ | -|`KC_SYSTEM_POWER` |`KC_PWR` |システム電源オフ |✔ |✔3|✔ | -|`KC_SYSTEM_SLEEP` |`KC_SLEP` |システムスリープ |✔ |✔3|✔ | -|`KC_SYSTEM_WAKE` |`KC_WAKE` |システムスリープ解除 | |✔3|✔ | -|`KC_AUDIO_MUTE` |`KC_MUTE` |ミュート |✔ |✔ |✔ | -|`KC_AUDIO_VOL_UP` |`KC_VOLU` |音量アップ |✔ |✔4|✔ | -|`KC_AUDIO_VOL_DOWN` |`KC_VOLD` |音量ダウン |✔ |✔4|✔ | -|`KC_MEDIA_NEXT_TRACK` |`KC_MNXT` |次の曲へ |✔ |✔5|✔ | -|`KC_MEDIA_PREV_TRACK` |`KC_MPRV` |前の曲へ |✔ |✔5|✔ | -|`KC_MEDIA_STOP` |`KC_MSTP` |再生停止 |✔ | |✔ | -|`KC_MEDIA_PLAY_PAUSE` |`KC_MPLY` |再生/一時停止 |✔ |✔ |✔ | -|`KC_MEDIA_SELECT` |`KC_MSEL` |Media Player 起動 |✔ | |✔ | -|`KC_MEDIA_EJECT` |`KC_EJCT` |イジェクト | |✔ |✔ | -|`KC_MAIL` | |メール起動 |✔ | |✔ | -|`KC_CALCULATOR` |`KC_CALC` |電卓起動 |✔ | |✔ | -|`KC_MY_COMPUTER` |`KC_MYCM` |マイコンピュータを開く |✔ | |✔ | -|`KC_WWW_SEARCH` |`KC_WSCH` |ブラウザ検索 |✔ | |✔ | -|`KC_WWW_HOME` |`KC_WHOM` |ブラウザホーム画面 |✔ | |✔ | -|`KC_WWW_BACK` |`KC_WBAK` |ブラウザ戻る |✔ | |✔ | -|`KC_WWW_FORWARD` |`KC_WFWD` |ブラウザ進む |✔ | |✔ | -|`KC_WWW_STOP` |`KC_WSTP` |ブラウザ読み込み中止 |✔ | |✔ | -|`KC_WWW_REFRESH` |`KC_WREF` |ブラウザ再読み込み |✔ | |✔ | -|`KC_WWW_FAVORITES` |`KC_WFAV` |ブラウザお気に入り |✔ | |✔ | -|`KC_MEDIA_FAST_FORWARD`|`KC_MFFD` |次の曲へ |✔ |✔5|✔ | -|`KC_MEDIA_REWIND` |`KC_MRWD` |前の曲へ |✔6|✔5|✔ | -|`KC_BRIGHTNESS_UP` |`KC_BRIU` |画面の明るさアップ |✔ |✔ |✔ | -|`KC_BRIGHTNESS_DOWN` |`KC_BRID` |画面の明るさダウン |✔ |✔ |✔ | - -1. Linux カーネル HID ドライバは [ほぼ全てのキーコード](https://github.com/torvalds/linux/blob/master/drivers/hid/hid-input.c) を識別しますが、デフォルトの関連付けは デスクトップ環境/ウィンドウマネージャによって決まります。
-2. F13-F15 として取り扱われます。
-3. 約3秒間押していると、プロンプトが表示されます。
-4. Shift と Option を押していると、ボリュームレベルの細かいコントロールが可能になります。
-5. iTunes では、タップすると1曲全体がスキップされます。押していると曲の中で早送り/巻き戻しになります。
-6. Windows Media Player は巻き戻しキーを識別しませんが、VLC では早送り/巻き戻しキーで再生速度が変更されます。 - -## Quantum キーコード :id=quantum-keycodes - -[Quantum キーコード](ja/quantum_keycodes.md#qmk-keycodes) も見てください。 - -|キー |エイリアス |説明 | -|-----------------|---------|---------------------------------------------------------| -|`QK_BOOTLOADER` |`QK_BOOT`|ファームウエア書き込みのためにキーボードをブートローダーモードにします | -|`QK_DEBUG_TOGGLE`|`DB_TOGG`|デバッグモードを切り替えます | -|`QK_CLEAR_EEPROM`|`EE_CLR` |キーボードの EEPROM (不揮発メモリ) を再初期化します | - -## オーディオキー :id=audio-keys - -[オーディオ](ja/feature_audio.md) も見てください。 - -|キー |エイリアス |説明 | -|----------------|------------|---------------------------------------| -|`AU_ON` | |オーディオモードオン | -|`AU_OFF` | |オーディオモードオフ | -|`AU_TOG` | |オーディオモードを切り替えます | -|`CLICKY_TOGGLE` |`CK_TOGG` |オーディオクリックモードを切り替えます | -|`CLICKY_UP` |`CK_UP` |クリック音の周波数を増やします | -|`CLICKY_DOWN` |`CK_DOWN` |クリック音の周波数を減らします | -|`CLICKY_RESET` |`CK_RST` |周波数をデフォルトに再設定します | -|`MU_ON` | |音楽モードをオンにします | -|`MU_OFF` | |音楽モードをオフにします | -|`MU_TOG` | |音楽モードを切り替えます | -|`MU_MOD` | |音楽モードを循環します | - -## バックライト :id=backlighting - -[バックライト](ja/feature_backlight.md) も見てください。 - -|キー |説明 | -|---------|-------------------------------------| -|`BL_TOGG`|バックライトをオンあるいはオフにする | -|`BL_STEP`|バックライトレベルを循環する | -|`BL_ON` |バックライトを最大輝度にセットする | -|`BL_OFF` |バックライトをオフにする | -|`BL_INC` |バックライトのレベルを上げる | -|`BL_DEC` |バックライトのレベルを下げる | -|`BL_BRTG`|バックライトの明滅動作を切り替える | - -## ブートマジック :id=bootmagic - -[ブートマジック](ja/feature_bootmagic.md) も見てください。 - -| キー | エイリアス| 説明 | -|------------------------------------|-----------|-------------------------------------------------------| -| `MAGIC_SWAP_CONTROL_CAPSLOCK` | `CL_SWAP` | Caps Lock と左 Control の入れ替え | -| `MAGIC_UNSWAP_CONTROL_CAPSLOCK` | `CL_NORM` | Caps Lock と左 Control の入れ替えの解除 | -| `MAGIC_CAPSLOCK_TO_CONTROL` | `CL_CTRL` | Caps Lock を Control として扱う | -| `MAGIC_UNCAPSLOCK_TO_CONTROL` | `CL_CAPS` | Caps Lock を Control として扱うことを止める | -| `MAGIC_SWAP_LCTL_LGUI` | `LCG_SWP` | 左 Control と GUI の入れ替え | -| `MAGIC_UNSWAP_LCTL_LGUI` | `LCG_NRM` | 左 Control と GUI の入れ替えを解除 | -| `MAGIC_SWAP_RCTL_RGUI` | `RCG_SWP` | 右 Control と GUI の入れ替え | -| `MAGIC_UNSWAP_RCTL_RGUI` | `RCG_NRM` | 右 Control と GUI の入れ替えを解除 | -| `MAGIC_SWAP_CTL_GUI` | `CG_SWAP` | 両側の Control と GUI の入れ替え | -| `MAGIC_UNSWAP_CTL_GUI` | `CG_NORM` | 両側の Control と GUI の入れ替えを解除 | -| `MAGIC_TOGGLE_CTL_GUI` | `CG_TOGG` | 両側の Control と GUI の入れ替えの切り替え | -| `MAGIC_SWAP_LALT_LGUI` | `LAG_SWP` | 左 Alt と GUI の入れ替え | -| `MAGIC_UNSWAP_LALT_LGUI` | `LAG_NRM` | 左 Alt と GUI の入れ替えを解除 | -| `MAGIC_SWAP_RALT_RGUI` | `RAG_SWP` | 右 Alt と GUI の入れ替え | -| `MAGIC_UNSWAP_RALT_RGUI` | `RAG_NRM` | 右 Alt と GUI の入れ替えを解除 | -| `MAGIC_SWAP_ALT_GUI` | `AG_SWAP` | 両側の Alt と GUI の入れ替え | -| `MAGIC_UNSWAP_ALT_GUI` | `AG_NORM` | 両側の Alt と GUI の入れ替えを解除 | -| `MAGIC_TOGGLE_ALT_GUI` | `AG_TOGG` | 両側の Alt と GUI の入れ替えの切り替え | -| `MAGIC_NO_GUI` | `GUI_OFF` | GUI キーを無効にする | -| `MAGIC_UNNO_GUI` | `GUI_ON` | GUI キーを有効にする | -| `MAGIC_SWAP_GRAVE_ESC` | `GE_SWAP` | ` とエスケープの入れ替え | -| `MAGIC_UNSWAP_GRAVE_ESC` | `GE_NORM` | ` とエスケープの入れ替えを解除 | -| `MAGIC_SWAP_BACKSLASH_BACKSPACE` | `BS_SWAP` | `\` と Backspace を入れ替え | -| `MAGIC_UNSWAP_BACKSLASH_BACKSPACE` | `BS_NORM` | `\` と Backspace の入れ替えを解除する | -| `MAGIC_HOST_NKRO` | `NK_ON` | N キーロールオーバーを有効にする | -| `MAGIC_UNHOST_NKRO` | `NK_OFF` | N キーロールオーバーを無効にする | -| `MAGIC_TOGGLE_NKRO` | `NK_TOGG` | N キーロールオーバーの有効・無効を切り替え | -| `MAGIC_EE_HANDS_LEFT` | `EH_LEFT` | 分割キーボードのマスター側を左手に設定(`EE_HANDS` 用) | -| `MAGIC_EE_HANDS_RIGHT` | `EH_RGHT` | 分割キーボードのマスター側を右手に設定(`EE_HANDS` 用) | - -## Bluetooth :id=bluetooth - -[Bluetooth](ja/feature_bluetooth.md) も見てください。 - - -|キー |説明 | -|----------|--------------------------------------| -|`OUT_AUTO`|USB と Bluetooth を自動的に切り替える | -|`OUT_USB` |USB のみ | -|`OUT_BT` |Bluetooth のみ | - -## 動的マクロ :id=dynamic-macros - -[動的マクロ](ja/feature_dynamic_macros.md) も見てください。 - -|キー |エイリアス |説明 | -|-----------------|---------|-------------------------------------| -|`DYN_REC_START1` |`DM_REC1`|マクロ 1 の記録を開始します | -|`DYN_REC_START2` |`DM_REC2`|マクロ 2 の記録を開始します | -|`DYN_MACRO_PLAY1`|`DM_PLY1`|マクロ 1 を再生します | -|`DYN_MACRO_PLAY2`|`DM_PLY2`|マクロ 2 を再生します | -|`DYN_REC_STOP` |`DM_RSTP`|現在記録中のマクロの記録を終了します | - -## グレイブエスケープ :id=grave-escape - -[グレイブエスケープ](ja/feature_grave_esc.md) も見てください。 - -|キー |エイリアス |説明 | -|-----------|---------|------------------------------------------------------------------| -|`GRAVE_ESC`|`KC_GESC`|押された場合に Escape。Shift あるいは GUI が押されたままの場合は `| - -## キーロック :id=key-lock - -[キーロック](ja/feature_key_lock.md) も見てください。 - -|キー |説明 | -|---------|--------------------------------------------------| -|`KC_LOCK`|キーが再び押されるまで次のキーを押したままにします | - -## レイヤー切り替え :id=layer-switching - -[レイヤー切り替え](ja/feature_layers.md#switching-and-toggling-layers) も見てください。 - -|キー |説明 | -|----------------|--------------------------------------------------------------------------------------------------------------------------------------| -|`DF(layer)` |指定されたレイヤーを基本 (デフォルト) レイヤーに設定する | -|`MO(layer)` |キーを押したら一時的に `layer` を切り替える。(切り替え先のレイヤーには `KC_TRNS` が必要です) | -|`OSL(layer)` |次のキーが押されるまで、一時的にレイヤーをアクティブにします。詳細は [ワンショットキー](ja/one_shot_keys.md) のとおり。 | -|`LM(layer, mod)`|`mod` がアクティブな状態で (MO のように) 一時的にレイヤーをアクティブにします。ここでは、`mod` は mods_bit のことです。Mod については [こちら](ja/mod_tap.md) で見ることができます。実装例: `LM(LAYER_1, MOD_LALT)` | -|`LT(layer, kc)` |押していると `layer` をオンにし、タップすると `kc` になります。 | -|`TG(layer)` |`layer` のオン・オフを切り替え | -|`TO(layer)` |`layer` をオンにして、デフォルトレイヤーを除く他のレイヤーをオフにします。 | -|`TT(layer)` |複数回タップしない限り `MO` のように動作し、複数回タップすると `layer` をオンにトグルします。 | - -## リーダーキー :id=leader-key - -[リーダーキー](ja/feature_leader_key.md) も見てください。 - -|キー |説明 | -|---------|-------------------------------| -|`KC_LEAD`|リーダーキーのシーケンスを開始 | - -## マウスキー :id=mouse-keys - -[マウスキー](ja/feature_mouse_keys.md) も見てください。 - -|キー |エイリアス |説明 | -|----------------|---------|-------------------------| -|`KC_MS_UP` |`KC_MS_U`|マウスカーソルを上に移動 | -|`KC_MS_DOWN` |`KC_MS_D`|マウスカーソルを下に移動 | -|`KC_MS_LEFT` |`KC_MS_L`|マウスカーソルを左に移動 | -|`KC_MS_RIGHT` |`KC_MS_R`|マウスカーソルを右に移動 | -|`KC_MS_BTN1` |`KC_BTN1`|ボタン1を押す | -|`KC_MS_BTN2` |`KC_BTN2`|ボタン2を押す | -|`KC_MS_BTN3` |`KC_BTN3`|ボタン3を押す | -|`KC_MS_BTN4` |`KC_BTN4`|ボタン4を押す | -|`KC_MS_BTN5` |`KC_BTN5`|ボタン5を押す | -|`KC_MS_WH_UP` |`KC_WH_U`|ホイールを向こう側に回転 | -|`KC_MS_WH_DOWN` |`KC_WH_D`|ホイールを手前側に回転 | -|`KC_MS_WH_LEFT` |`KC_WH_L`|ホイールを左に倒す | -|`KC_MS_WH_RIGHT`|`KC_WH_R`|ホイールを右に倒す | -|`KC_MS_ACCEL0` |`KC_ACL0`|速度を0に設定 | -|`KC_MS_ACCEL1` |`KC_ACL1`|速度を1に設定 | -|`KC_MS_ACCEL2` |`KC_ACL2`|速度を2に設定 | - -## 修飾キー :id=modifiers - -[修飾キー](ja/feature_advanced_keycodes.md#modifier-keys) も見てください。 - -| キー | エイリアス | 説明 | -|------------|---------------------------------|---------------------------------------------------------------| -| `LCTL(kc)` | `C(kc)` | 左 Control を押しながら `kc` を押します。 | -| `LSFT(kc)` | `S(kc)` | 左 Shift を押しながら `kc` を押します。 | -| `LALT(kc)` | `A(kc)`, `LOPT(kc)` | 左 Alt を押しながら `kc`を押します。 | -| `LGUI(kc)` | `G(kc)`, `LCMD(kc)`, `LWIN(kc)` | 左 GUI を押しながら `kc` を押します。 | -| `RCTL(kc)` | | 右 Control を押しながら `kc` を押します。 | -| `RSFT(kc)` | | 右 Shift を押しながら `kc` を押します。 | -| `RALT(kc)` | `ROPT(kc)`, `ALGR(kc)` | 右 Alt (AltGr) を押しながら `kc` を押します。 | -| `RGUI(kc)` | `RCMD(kc)`, `LWIN(kc)` | 右 GUI を押しながら `kc` を押します。 | -| `SGUI(kc)` | `SCMD(kc)`, `SWIN(kc)` | 左 Shift と GUI を押しながら `kc` を押します。 | -| `LCA(kc)` | | 左 Control と Alt を押しながら `kc` を押します。 | -| `LSA(kc)` | | 左 Shift と Alt を押しながら `kc` を押します。 | -| `RSA(kc)` |`SAGR(kc)` | 右 Shift と Alt (AltGr) を押しながら `kc` を押します。 | -| `RCS(kc)` | | 右 Control と Shift を押しながら `kc` を押します。 | -| `LCAG(kc)` | | 左 Control、Alt、GUI を押しながら `kc` を押します。 | -| `MEH(kc)` | | 左 Control、Shift、Alt を押しながら `kc` を押します。 | -| `HYPR(kc)` | | 左 Control、Shift、Alt、GUI を押しながら `kc` を押します。 | -| `KC_MEH` | | 左 Control、Shift、Alt | -| `KC_HYPR` | | 左 Control、Shift、Alt、GUI | - - -## モッドタップキー :id=mod-tap-keys - -[モッドタップキー](ja/mod_tap.md) も見てください。 - -|キー |エイリアス | 説明 | -|--------------|-------------------------------------------------------------------|------------------------------------------------------------------------| -| `MT(mod, kc)`| |押したままの場合は `mod` 、タップした場合は `kc` | -| `LCTL_T(kc)` | `CTL_T(kc)` | 押したままの場合は左 Control、タップした場合は `kc` | -| `LSFT_T(kc)` | `SFT_T(kc)` | 押したままの場合は左 Shift、タップした場合は `kc` | -| `LALT_T(kc)` | `LOPT_T(kc)`, `ALT_T(kc)`, `OPT_T(kc)` | 押したままの場合は左 Alt、タップした場合は `kc` | -| `LGUI_T(kc)` | `LCMD_T(kc)`, `LWIN_T(kc)`, `GUI_T(kc)`, `CMD_T(kc)`, `WIN_T(kc)` | 押したままの場合は左 GUI、タップした場合は `kc` | -| `RCTL_T(kc)` | | 押したままの場合は右 Control、タップした場合は `kc` | -| `RSFT_T(kc)` | | 押したままの場合は右 Shift、タップした場合は `kc` | -| `RALT_T(kc)` | `ROPT_T(kc)`, `ALGR_T(kc)` | 押したままの場合は右 Alt (AltGr) 、タップした場合は `kc` | -| `RGUI_T(kc)` | `RCMD_T(kc)`, `RWIN_T(kc)` | 押したままの場合は右 GUI、タップした場合は `kc` | -| `SGUI_T(kc)` | `SCMD_T(kc)`, `SWIN_T(kc)` | 押したままの場合は左 Shift と GUI、タップした場合は `kc` | -| `LCA_T(kc)` | | 押したままの場合は左 Control と Alt、タップした場合は `kc` | -| `LSA_T(kc)` | | 押したままの場合は左 Shift と Alt、タップした場合は `kc` | -| `RSA_T(kc)` |`SAGR_T(kc)` | 押したままの場合は右 Shift と Alt (AltGr) 、タップした場合は `kc` | -| `RCS_T(kc)` | | 押したままの場合は右 Control と Shift、タップした場合は `kc` | -| `LCAG_T(kc)` | | 押したままの場合は左 Control、Alt、GUI、タップした場合は `kc` | -| `RCAG_T(kc)` | | 押したままの場合は右 Control、Alt、GUI、タップした場合は `kc` | -| `C_S_T(kc)` | | 押したままの場合は左 Control と Shift、タップした場合は `kc` | -| `MEH_T(kc)` | | 押したままの場合は左 Control、Shift、Alt、タップした場合は `kc` | -| `HYPR_T(kc)` | `ALL_T(kc)` | 押したままの場合は左 Control、Shift、Alt、GUI、タップした場合は `kc` - より詳しくは[ここ](https://brettterpstra.com/2012/12/08/a-useful-caps-lock-key/)を見てください | - -## RGB ライト :id=rgb-lighting - -[RGB ライト](ja/feature_rgblight.md) も見てください。 - -|キー |エイリアス|説明 | -|-------------------|----------|---------------------------------------------------------------------| -|`RGB_TOG` | |RGB ライトのオン・オフを切り替え | -|`RGB_MODE_FORWARD` |`RGB_MOD` |RGB モードを順送りで変更し、Shift を押していると逆順で変更します。 | -|`RGB_MODE_REVERSE` |`RGB_RMOD`|RGB モードを逆順で変更し、Shift を押していると順送りで変更します。 | -|`RGB_HUI` | |色相 (HUE) を増加させ、Shift を押していると減少させます。 | -|`RGB_HUD` | |色相 (HUE) を減少させ、Shift を押していると増加させます。 | -|`RGB_SAI` | |彩度 (SAT) を増加させ、Shift を押していると減少させます。 | -|`RGB_SAD` | |彩度 (SAT) を減少させ、Shift を押していると増加させます。 | -|`RGB_VAI` | |明度 (VAL/brightness) を増加させ、Shift を押していると減少させます。 | -|`RGB_VAD` | |明度 (VAL/brightness) を減少させ、Shift を押していると増加させます。 | -|`RGB_MODE_PLAIN` |`RGB_M_P `|静止(動き無し) モードに固定します | -|`RGB_MODE_BREATHE` |`RGB_M_B` |明滅アニメーションモード | -|`RGB_MODE_RAINBOW` |`RGB_M_R` |レインボーアニメーションモード | -|`RGB_MODE_SWIRL` |`RGB_M_SW`|渦巻アニメーションモード | -|`RGB_MODE_SNAKE` |`RGB_M_SN`|スネークアニメーションモード | -|`RGB_MODE_KNIGHT` |`RGB_M_K` |「ナイトライダー」アニメーションモード | -|`RGB_MODE_XMAS` |`RGB_M_X` |クリスマスアニメーションモード | -|`RGB_MODE_GRADIENT`|`RGB_M_G` |固定階調アニメーションモード | -|`RGB_MODE_RGBTEST` |`RGB_M_T` |赤、緑、青のテストアニメーションモード | - -## RGB マトリックスライト :id=rgb-matrix-lighting - -[RGB マトリックスライト](ja/feature_rgb_matrix.md) も見てください。 - -|キー |エイリアス|説明 | -|-------------------|----------|--------------------------------------------------------------------------------------------------------| -|`RGB_TOG` | |RGB ライトのオン・オフを切り替え | -|`RGB_MODE_FORWARD` |`RGB_MOD` |RGB モードを順送りで変更し、Shift を押していると逆順で変更します。 | -|`RGB_MODE_REVERSE` |`RGB_RMOD`|RGB モードを逆順で変更し、Shift を押していると順送りで変更します。 | -|`RGB_HUI` | |色相 (HUE) を増加させ、Shift を押していると減少させます。 | -|`RGB_HUD` | |色相 (HUE) を減少させ、Shift を押していると増加させます。 | -|`RGB_SAI` | |彩度 (SAT) を増加させ、Shift を押していると減少させます。 | -|`RGB_SAD` | |彩度 (SAT) を減少させ、Shift を押していると増加させます。 | -|`RGB_VAI` | |明度 (VAL/brightness) を増加させ、Shift を押していると減少させます。 | -|`RGB_VAD` | |明度 (VAL/brightness) を減少させ、Shift を押していると増加させます。 | -|`RGB_SPI` | |エフェクトのスピード (EEPROM はまだサポートしていません) を増加させ、Shift を押していると減少させます。 | -|`RGB_SPD` | |エフェクトのスピード (EEPROM はまだサポートしていません) を減少させ、Shift を押していると増加させます。 | - -## 感熱式プリンタ :id=thermal-printer - -[感熱式プリンタ](ja/feature_thermal_printer.md) も見てください。 - -|キー |説明 | -|-----------|---------------------------------| -|`PRINT_ON` |ユーザが入力した全ての印刷を開始 | -|`PRINT_OFF`|ユーザが入力した全ての印刷を停止 | - -## US ANSI シフト済シンボル :id=us-ansi-shifted-symbols - -[US ANSI シフト済シンボル](ja/keycodes_us_ansi_shifted.md) も見てください。 - -|キー |エイリアス |説明| -|------------------------|-------------------|-----------| -|`KC_TILDE` |`KC_TILD` |`~` | -|`KC_EXCLAIM` |`KC_EXLM` |`!` | -|`KC_AT` | |`@` | -|`KC_HASH` | |`#` | -|`KC_DOLLAR` |`KC_DLR` |`$` | -|`KC_PERCENT` |`KC_PERC` |`%` | -|`KC_CIRCUMFLEX` |`KC_CIRC` |`^` | -|`KC_AMPERSAND` |`KC_AMPR` |`&` | -|`KC_ASTERISK` |`KC_ASTR` |`*` | -|`KC_LEFT_PAREN` |`KC_LPRN` |`(` | -|`KC_RIGHT_PAREN` |`KC_RPRN` |`)` | -|`KC_UNDERSCORE` |`KC_UNDS` |`_` | -|`KC_PLUS` | |`+` | -|`KC_LEFT_CURLY_BRACE` |`KC_LCBR` |`{` | -|`KC_RIGHT_CURLY_BRACE` |`KC_RCBR` |`}` | -|`KC_PIPE` | |`\|` | -|`KC_COLON` |`KC_COLN` |`:` | -|`KC_DOUBLE_QUOTE` |`KC_DQUO`, `KC_DQT`|`"` | -|`KC_LEFT_ANGLE_BRACKET` |`KC_LABK`, `KC_LT` |`<` | -|`KC_RIGHT_ANGLE_BRACKET`|`KC_RABK`, `KC_GT` |`>` | -|`KC_QUESTION` |`KC_QUES` |`?` | - -## ワンショットキー :id=one-shot-keys - -[ワンショットキー](ja/one_shot_keys.md) も見てください。 - -|キー |説明 | -|------------|--------------------------------| -|`OSM(mod)` | 次のキーが押されるまで、`mod` を押したままにします | -|`OSL(layer)`| 次のキーが押されるまで、一時的にレイヤーをアクティブにします | - -## Space Cadet :id=space-cadet - -[Space Cadet](ja/feature_space_cadet.md) も見てください。 - -|キー |説明 | -|-----------|-------------------------------------------| -|`KC_LCPO` |押したままの場合は左 Control、タップした場合は `(` | -|`KC_RCPC` |押したままの場合は右 Control、タップした場合は `)` | -|`KC_LSPO` |押したままの場合は左 Shift、タップした場合は `(`、 | -|`KC_RSPC` |押したままの場合は右 Shift、タップした場合は `)`、 | -|`KC_LAPO` |押したままの場合は左 Alt、タップした場合は `(`、 | -|`KC_RAPC` |押したままの場合は右 Alt、タップした場合は `)`、 | -|`KC_SFTENT`|押したままの場合は右 Shift、タップした場合は Enter | - -## スワップハンド :id=swap-hands - -[スワップハンド](ja/feature_swap_hands.md) も見てください。 - -|キー |説明 | -|-------------|----------------------------------------------------------------------------------| -| `SH_T(key)` | タップで `key` を送信する。押している時に一時的に入れ替え。 | -| `SH_ON` | 入れ替えをオンにして、そのままにする。 | -| `SH_OFF` | 入れ替えをオフにして、そのままにする。既知の状態に戻るのに適しています。 | -| `SH_MON` | 押すとスワップハンドし、放すと通常に戻る (一時的)。 | -| `SH_MOFF` | 一時的に入れ替えをオフする。 | -| `SH_TG` | キーを押すたびにオンとオフを切り替える。 | -| `SH_TT` | タップで切り替える。押している時に一時的に切り替える。 | -| `SH_OS` | ワンショットスワップハンド: 押している時あるいは次のキーを押すまで切り替える。 | - -## ユニコードサポート :id=unicode-support - -[ユニコードサポート](ja/feature_unicode.md) も見てください。 - -|キー |エイリアス |説明 | -|----------------------|-----------|----------------------------------------------------------------------| -|`UC(c)` | |コードポイント `c` のユニコードを送信 | -|`X(i)` | |`unicode_map` のインデックス `i` のユニコードを送信 | -|`XP(i, j)` | |Shift/Capsが有効なら、インデックス `i` または `j` のユニコードを送信 | -|`UNICODE_MODE_FORWARD`|`UC_MOD` |ユニコード入力方式を順送りで選択 | -|`UNICODE_MODE_REVERSE`|`UC_RMOD` |ユニコード入力方式を逆順で選択 | -|`UNICODE_MODE_OSX` |`UC_M_OS` |ユニコード入力方式を macOS 方式に切り替え | -|`UNICODE_MODE_LNX` |`UC_M_LN` |ユニコード入力方式を Linux 方式に切り替え | -|`UNICODE_MODE_WIN` |`UC_M_WI` |ユニコード入力方式を Windows 方式に切り替え | -|`UNICODE_MODE_BSD` |`UC_M_BS` |ユニコード入力方式を BSD 方式に切り替え (実装されていません) | -|`UNICODE_MODE_WINC` |`UC_M_WC` |ユニコード入力方式を WinCompose を使う Windows 方式に切り替え | diff --git a/docs/ja/keycodes_basic.md b/docs/ja/keycodes_basic.md deleted file mode 100644 index 2ef8e4955d..0000000000 --- a/docs/ja/keycodes_basic.md +++ /dev/null @@ -1,261 +0,0 @@ -# 基本的なキーコード - - - -基本的なキーコードのセットは、`KC_NO`、`KC_TRNS` と `0xA5-DF` の範囲のキーコードを除いて、[HID Keyboard/Keypad Usage Page (0x07)](https://www.usb.org/sites/default/files/documents/hut1_12v2.pdf) に基づいています。 - -## 文字と数字 - -|キー |説明 | -|------|----------| -|`KC_A`|`a` と `A`| -|`KC_B`|`b` と `B`| -|`KC_C`|`c` と `C`| -|`KC_D`|`d` と `D`| -|`KC_E`|`e` と `E`| -|`KC_F`|`f` と `F`| -|`KC_G`|`g` と `G`| -|`KC_H`|`h` と `H`| -|`KC_I`|`i` と `I`| -|`KC_J`|`j` と `J`| -|`KC_K`|`k` と `K`| -|`KC_L`|`l` と `L`| -|`KC_M`|`m` と `M`| -|`KC_N`|`n` と `N`| -|`KC_O`|`o` と `O`| -|`KC_P`|`p` と `P`| -|`KC_Q`|`q` と `Q`| -|`KC_R`|`r` と `R`| -|`KC_S`|`s` と `S`| -|`KC_T`|`t` と `T`| -|`KC_U`|`u` と `U`| -|`KC_V`|`v` と `V`| -|`KC_W`|`w` と `W`| -|`KC_X`|`x` と `X`| -|`KC_Y`|`y` と `Y`| -|`KC_Z`|`z` と `Z`| -|`KC_1`|`1` と `!`| -|`KC_2`|`2` と `@`| -|`KC_3`|`3` と `#`| -|`KC_4`|`4` と `$`| -|`KC_5`|`5` と `%`| -|`KC_6`|`6` と `^`| -|`KC_7`|`7` と `&`| -|`KC_8`|`8` と `*`| -|`KC_9`|`9` と `(`| -|`KC_0`|`0` と `)`| - -## ファンクションキー - -|キー |説明 | -|--------|-----| -|`KC_F1` |F1 | -|`KC_F2` |F2 | -|`KC_F3` |F3 | -|`KC_F4` |F4 | -|`KC_F5` |F5 | -|`KC_F6` |F6 | -|`KC_F7` |F7 | -|`KC_F8` |F8 | -|`KC_F9` |F9 | -|`KC_F10`|F10 | -|`KC_F11`|F11 | -|`KC_F12`|F12 | -|`KC_F13`|F13 | -|`KC_F14`|F14 | -|`KC_F15`|F15 | -|`KC_F16`|F16 | -|`KC_F17`|F17 | -|`KC_F18`|F18 | -|`KC_F19`|F19 | -|`KC_F20`|F20 | -|`KC_F21`|F21 | -|`KC_F22`|F22 | -|`KC_F23`|F23 | -|`KC_F24`|F24 | - -## パンクチュエーション - -|キー |エイリアス |説明 | -|-----------------|-------------------|----------------------------------------------| -|`KC_ENTER` |`KC_ENT` |Return (Enter) | -|`KC_ESCAPE` |`KC_ESC` |Escape | -|`KC_BSPACE` |`KC_BSPC` |Delete (Backspace) | -|`KC_TAB` | |Tab | -|`KC_SPACE` |`KC_SPC` |Spacebar | -|`KC_MINUS` |`KC_MINS` |`-` と `_` | -|`KC_EQUAL` |`KC_EQL` |`=` と `+` | -|`KC_LBRACKET` |`KC_LBRC` |`[` と `{` | -|`KC_RBRACKET` |`KC_RBRC` |`]` と `}` | -|`KC_BSLASH` |`KC_BSLS` |`\` と `\|` | -|`KC_NONUS_HASH` |`KC_NUHS` |Non-US `#` と `~` | -|`KC_SCOLON` |`KC_SCLN` |`;` と `:` | -|`KC_QUOTE` |`KC_QUOT` |`'` と `"` | -|`KC_GRAVE` |`KC_GRV`, `KC_ZKHK`|` と `~`, JIS 全角/半角 | -|`KC_COMMA` |`KC_COMM` |`,` と `<` | -|`KC_DOT` | |`.` と `>` | -|`KC_SLASH` |`KC_SLSH` |`/` と `?` | -|`KC_NONUS_BSLASH`|`KC_NUBS` |Non-US `\` と `\|` | - -## ロックキー - -|キー |エイリアス |説明 | -|-------------------|--------------------|---------------------------------------| -|`KC_CAPSLOCK` |`KC_CLCK`, `KC_CAPS`|Caps Lock | -|`KC_SCROLLLOCK` |`KC_SCRL`, `KC_BRMD`|Scroll Lock, 画面の明るさダウン (macOS)| -|`KC_NUMLOCK` |`KC_NUM` |テンキー Num Lock と Clear | -|`KC_LOCKING_CAPS` |`KC_LCAP` |Caps Lock のロック | -|`KC_LOCKING_NUM` |`KC_LNUM` |Num Lock のロック | -|`KC_LOCKING_SCROLL`|`KC_LSCR` |Scroll Lock のロック | - -## 修飾キー - -|キー |エイリアス |説明 | -|-----------|--------------------|---------------------------------| -|`KC_LCTRL` |`KC_LCTL` |左 Control | -|`KC_LSHIFT`|`KC_LSFT` |左 Shift | -|`KC_LALT` |`KC_LOPT` |左 Alt (Option) | -|`KC_LGUI` |`KC_LCMD`, `KC_LWIN`|左 GUI (Windows/Command/Meta キー)| -|`KC_RCTRL` |`KC_RCTL` |右 Control | -|`KC_RSHIFT`|`KC_RSFT` |右 Shift | -|`KC_RALT` |`KC_ROPT`, `KC_ALGR`|右 Alt (Option/AltGr) | -|`KC_RGUI` |`KC_RCMD`, `KC_RWIN`|右 GUI (Windows/Command/Meta キー)| - -## 国際化対応キー - -|キー |エイリアス|説明 | -|----------|----------|---------------------| -|`KC_INT1` |`KC_RO` |JIS `\` と ` _` | -|`KC_INT2` |`KC_KANA` |JIS カタカナ/ひらがな| -|`KC_INT3` |`KC_JYEN` |JIS `¥` と `\ |` | -|`KC_INT4` |`KC_HENK` |JIS 変換 | -|`KC_INT5` |`KC_MHEN` |JIS 無変換 | -|`KC_INT6` | |JIS テンキー `,` | -|`KC_INT7` | |International 7 | -|`KC_INT8` | |International 8 | -|`KC_INT9` | |International 9 | -|`KC_LANG1`|`KC_HAEN` |ハングル/英語 | -|`KC_LANG2`|`KC_HANJ` |韓文漢字 | -|`KC_LANG3`| |JIS カタカナ | -|`KC_LANG4`| |JIS ひらがな | -|`KC_LANG5`| |JIS 全角/半角 | -|`KC_LANG6`| |Language 6 | -|`KC_LANG7`| |Language 7 | -|`KC_LANG8`| |Language 8 | -|`KC_LANG9`| |Language 9 | - -## コマンドキー - -|キー |エイリアス |説明 | -|------------------|------------------------------|-------------------------------------------------------| -|`KC_PSCREEN` |`KC_PSCR` |Print Screen | -|`KC_PAUSE` |`KC_PAUS`, `KC_BRK`, `KC_BRMU`|Pause, 画面の明るさアップ (macOS) | -|`KC_INSERT` |`KC_INS` |Insert | -|`KC_HOME` | |Home | -|`KC_PGUP` | |Page Up | -|`KC_DELETE` |`KC_DEL` |Forward Delete | -|`KC_END` | |End | -|`KC_PGDOWN` |`KC_PGDN` |Page Down | -|`KC_RIGHT` |`KC_RGHT` |右矢印 | -|`KC_LEFT` | |左矢印 | -|`KC_DOWN` | |下矢印 | -|`KC_UP` | |上矢印 | -|`KC_APPLICATION` |`KC_APP` |アプリケーションキー (Windows コンテキストメニューキー)| -|`KC_POWER` | |システム電源 | -|`KC_EXECUTE` |`KC_EXEC` |Execute | -|`KC_HELP` | |Help | -|`KC_MENU` | |Menu | -|`KC_SELECT` |`KC_SLCT` |Select | -|`KC_STOP` | |Stop | -|`KC_AGAIN` |`KC_AGIN` |Again | -|`KC_UNDO` | |アンドゥ | -|`KC_CUT` | |カット | -|`KC_COPY` | |コピー | -|`KC_PASTE` |`KC_PSTE` |ペースト | -|`KC_FIND` | |検索 | -|`KC__MUTE` | |ミュート | -|`KC__VOLUP` | |音量アップ | -|`KC__VOLDOWN` | |音量ダウン | -|`KC_ALT_ERASE` |`KC_ERAS` |Alternate Erase | -|`KC_SYSREQ` | |SysReq/Attention | -|`KC_CANCEL` | |Cancel | -|`KC_CLEAR` |`KC_CLR` |Clear | -|`KC_PRIOR` | |Prior | -|`KC_RETURN` | |Return | -|`KC_SEPARATOR` | |Separator | -|`KC_OUT` | |Out | -|`KC_OPER` | |Oper | -|`KC_CLEAR_AGAIN` | |Clear/Again | -|`KC_CRSEL` | |CrSel/Props | -|`KC_EXSEL` | |ExSel | - -## メディアキー - -これらのキーコードは、HID Keyboard/Keypad usage ページにはありません。`SYSTEM_` キーコードは、Generic Desktop ページで見つかります。また、その他は Consumer ページにあります。 - -?> これらのキーコードのいくつかは、OS によって異なる動作をする可能性があります。例として、macOS では `KC_MEDIA_FAST_FORWARD`、`KC_MEDIA_REWIND`、`KC_MEDIA_NEXT_TRACK`、`KC_MEDIA_PREV_TRACK` は、押している間は現在の曲の中でスキップしますが、タップした時は曲全体をスキップします。 - -|キー |エイリアス |説明 | -|-----------------------|-----------|----------------------| -|`KC_SYSTEM_POWER` |`KC_PWR` |システム電源オフ | -|`KC_SYSTEM_SLEEP` |`KC_SLEP` |システムスリープ | -|`KC_SYSTEM_WAKE` |`KC_WAKE` |システムスリープ解除 | -|`KC_AUDIO_MUTE` |`KC_MUTE` |ミュート | -|`KC_AUDIO_VOL_UP` |`KC_VOLU` |音量アップ | -|`KC_AUDIO_VOL_DOWN` |`KC_VOLD` |音量ダウン | -|`KC_MEDIA_NEXT_TRACK` |`KC_MNXT` |次の曲へ | -|`KC_MEDIA_PREV_TRACK` |`KC_MPRV` |前の曲へ | -|`KC_MEDIA_STOP` |`KC_MSTP` |再生停止 | -|`KC_MEDIA_PLAY_PAUSE` |`KC_MPLY` |再生/一時停止 | -|`KC_MEDIA_SELECT` |`KC_MSEL` |Media Player 起動 | -|`KC_MEDIA_EJECT` |`KC_EJCT` |イジェクト | -|`KC_MAIL` | |メール起動 | -|`KC_CALCULATOR` |`KC_CALC` |電卓起動 | -|`KC_MY_COMPUTER` |`KC_MYCM` |マイコンピュータを開く| -|`KC_WWW_SEARCH` |`KC_WSCH` |ブラウザ検索 | -|`KC_WWW_HOME` |`KC_WHOM` |ブラウザホーム画面 | -|`KC_WWW_BACK` |`KC_WBAK` |ブラウザ戻る | -|`KC_WWW_FORWARD` |`KC_WFWD` |ブラウザ進む | -|`KC_WWW_STOP` |`KC_WSTP` |ブラウザ読み込み中止 | -|`KC_WWW_REFRESH` |`KC_WREF` |ブラウザ再読み込み | -|`KC_WWW_FAVORITES` |`KC_WFAV` |ブラウザお気に入り | -|`KC_MEDIA_FAST_FORWARD`|`KC_MFFD` |次の曲へ | -|`KC_MEDIA_REWIND` |`KC_MRWD` |前の曲へ | -|`KC_BRIGHTNESS_UP` |`KC_BRIU` |画面の明るさアップ | -|`KC_BRIGHTNESS_DOWN` |`KC_BRID` |画面の明るさダウン | - -## テンキー - -|キー |エイリアス |説明 | -|-------------------|-----------|-------------------------------| -|`KC_KP_SLASH` |`KC_PSLS` |テンキー `/` | -|`KC_KP_ASTERISK` |`KC_PAST` |テンキー `*` | -|`KC_KP_MINUS` |`KC_PMNS` |テンキー `-` | -|`KC_KP_PLUS` |`KC_PPLS` |テンキー `+` | -|`KC_KP_ENTER` |`KC_PENT` |テンキー Enter | -|`KC_KP_1` |`KC_P1` |テンキー `1` と End | -|`KC_KP_2` |`KC_P2` |テンキー `2` と 下矢印 | -|`KC_KP_3` |`KC_P3` |テンキー `3` と Page Down | -|`KC_KP_4` |`KC_P4` |テンキー `4` と 左矢印 | -|`KC_KP_5` |`KC_P5` |テンキー `5` | -|`KC_KP_6` |`KC_P6` |テンキー `6` と 右矢印 | -|`KC_KP_7` |`KC_P7` |テンキー `7` と Home | -|`KC_KP_8` |`KC_P8` |テンキー `8` と 上矢印 | -|`KC_KP_9` |`KC_P9` |テンキー `9` と Page Up | -|`KC_KP_0` |`KC_P0` |テンキー `0` と Insert | -|`KC_KP_DOT` |`KC_PDOT` |テンキー `.` と Delete | -|`KC_KP_EQUAL` |`KC_PEQL` |テンキー `=` | -|`KC_KP_COMMA` |`KC_PCMM` |テンキー `,` | -|`KC_KP_EQUAL_AS400`| |AS/400 キーボードのテンキー `=`| - -## 特別なキー - -これらのキーコードに加えて、`0xA5-DF` の範囲のキーコードは、内部処理のために予約されています。 - -|キー |エイリアス |説明 | -|----------------|--------------------|-----------------------------------| -|`KC_NO` |`XXXXXXX` |このキーを無視します (NOOP) | -|`KC_TRANSPARENT`|`KC_TRNS`, `_______`|次に低いレイヤーの非透過キーを使う | diff --git a/docs/ja/keycodes_us_ansi_shifted.md b/docs/ja/keycodes_us_ansi_shifted.md deleted file mode 100644 index 3a574d0bed..0000000000 --- a/docs/ja/keycodes_us_ansi_shifted.md +++ /dev/null @@ -1,41 +0,0 @@ -# US ANSI シフト記号 - - -これらのキーコードは、標準の US ANSI 配列のキーボードで「シフトされる」文字に対応します。これらのキーコードは自身のキーコードを持たず、`LSFT(kc)` の単なるショートカットであり、記号自体ではなく Shift キー抜きのキーコードと左 Shift キーを送信します。 - -## 注意書き - -残念ながら、これらのキーコードは、モッドタップやレイヤータップの中で使えません。キーコードで指定されたモディファイアは無視されるからです。 - -さらに、Windows でリモートデスクトップ接続を使う場合に、問題が発生する場合があります。なぜならば、これらのコードは Shift キーを非常に速く送信するため、リモートデスクトップがコードを見落とすかもしれないからです。 - -この問題を解決するには、リモートデスクトップ接続を開いて「オプションの表示」をクリックし、「ローカル リソース」タブを開きます。キーボードセクションでドロップダウンを「このコンピュータ」に変更します。これで問題が解決され、文字が正しく機能するようになります。 - -## キーコード - -|キー |エイリアス |説明 | -|------------------------|-------------------|-----------| -|`KC_TILDE` |`KC_TILD` |`~` | -|`KC_EXCLAIM` |`KC_EXLM` |`!` | -|`KC_AT` | |`@` | -|`KC_HASH` | |`#` | -|`KC_DOLLAR` |`KC_DLR` |`$` | -|`KC_PERCENT` |`KC_PERC` |`%` | -|`KC_CIRCUMFLEX` |`KC_CIRC` |`^` | -|`KC_AMPERSAND` |`KC_AMPR` |`&` | -|`KC_ASTERISK` |`KC_ASTR` |`*` | -|`KC_LEFT_PAREN` |`KC_LPRN` |`(` | -|`KC_RIGHT_PAREN` |`KC_RPRN` |`)` | -|`KC_UNDERSCORE` |`KC_UNDS` |`_` | -|`KC_PLUS` | |`+` | -|`KC_LEFT_CURLY_BRACE` |`KC_LCBR` |`{` | -|`KC_RIGHT_CURLY_BRACE` |`KC_RCBR` |`}` | -|`KC_PIPE` | |`\|` | -|`KC_COLON` |`KC_COLN` |`:` | -|`KC_DOUBLE_QUOTE` |`KC_DQUO`, `KC_DQT`|`"` | -|`KC_LEFT_ANGLE_BRACKET` |`KC_LABK`, `KC_LT` |`<` | -|`KC_RIGHT_ANGLE_BRACKET`|`KC_RABK`, `KC_GT` |`>` | -|`KC_QUESTION` |`KC_QUES` |`?` | diff --git a/docs/ja/keymap.md b/docs/ja/keymap.md deleted file mode 100644 index 2863bd49b5..0000000000 --- a/docs/ja/keymap.md +++ /dev/null @@ -1,189 +0,0 @@ -# キーマップの概要 - - - -QMK のキーマップは C のソースファイルの中で定義されます。そのデータ構造は配列の配列です。外側はレイヤーを要素とする配列で、レイヤーはキーを要素とする配列。ほとんどのキーボードは `LAYOUT()` マクロを定義して、この配列の配列を作成しやすくしています。 - - -## キーマップとレイヤー :id=keymap-and-layers -QMKでは、**`const uint16_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS]`**は、**アクションコード**を保持している **16 bit** データの中でキーマップ情報の複数の**レイヤー**を保持します。最大で**32個のレイヤー**を定義することができます。 - -普通のキー定義の場合、**アクションコード**の上位8ビットは全て0で、下位8ビットは**キーコード**としてキーによって生成された USB HID usage コードを保持します。 - -各レイヤーは同時に有効にできます。レイヤーには 0 から 31 までのインデックスが付けられ、上位のレイヤーが優先されます。 - - Keymap: 32 Layers Layer: action code matrix - ----------------- --------------------- - stack of layers array_of_action_code[row][column] - ____________ precedence _______________________ - / / | high / ESC / F1 / F2 / F3 .... - 31 /___________// | /-----/-----/-----/----- - 30 /___________// | / TAB / Q / W / E .... - 29 /___________/ | /-----/-----/-----/----- - : _:_:_:_:_:__ | : /LCtrl/ A / S / D .... - : / : : : : : / | : / : : : : - 2 /___________// | 2 `-------------------------- - 1 /___________// | 1 `-------------------------- - 0 /___________/ V low 0 `-------------------------- - - -TMK の歴史的経緯から、キーマップに保存されたアクションコードは、一部のドキュメントではキーコードと呼ばれる場合があります。 - -### キーマップレイヤーステータス :id=keymap-layer-status - -キーマップレイヤーの状態は、2つの32ビットパラメータによって決定されます。 - -* **`default_layer_state`** は、常に有効で参照される基本キーマップレイヤー (0-31) を示します (デフォルトレイヤー)。 -* **`layer_state`** は現在の各レイヤーのオン/オフの状態をビットで持ちます。 - -キーマップレイヤー '0' は通常 `default_layer` で、他のレイヤーはファームウェアの起動後に最初はオフになっていますが、これは `config.h` で異なる設定にすることが可能です。例えば Qwerty ではなく Colemak に切り替えるなど、キーレイアウトを完全に切り替える場合、`default_layer` を変更すると便利です。 - - Initial state of Keymap Change base layout - ----------------------- ------------------ - - 31 31 - 30 30 - 29 29 - : : - : : ____________ - 2 ____________ 2 / / - 1 / / ,->1 /___________/ - ,->0 /___________/ | 0 - | | - `--- default_layer = 0 `--- default_layer = 1 - layer_state = 0x00000001 layer_state = 0x00000002 - -一方、`layer_state` を変更して、基本レイヤーをナビゲーションキー、ファンクションキー (F1-F12)、メディアキー、特別なアクションなどの機能を持つ他のレイヤーでオーバーレイすることができます。 - - Overlay feature layer - --------------------- bit|status - ____________ ---+------ - 31 / / 31 | 0 - 30 /___________// -----> 30 | 1 - 29 /___________/ -----> 29 | 1 - : : | : - : ____________ : | : - 2 / / 2 | 0 - ,->1 /___________/ -----> 1 | 1 - | 0 0 | 0 - | + - `--- default_layer = 1 | - layer_state = 0x60000002 <-' - - - -### レイヤーの優先順位と透過性 -***上位のレイヤーはレイヤーのスタックでより高い優先順位を持つ***ことに注意してください。ファームウェアは最上位のアクティブレイヤーから下に向かってキーコードを検索します。ファームウェアがアクティブなレイヤーで `KC_TRNS` (透過)以外のキーコードを見つけると、検索を停止し、下位レイヤーは参照されません。 - - ____________ - / / <--- Higher layer - / KC_TRNS // - /___________// <--- Lower layer (KC_A) - /___________/ - - 上記シナリオでは、上位レイヤーに非透過のキーが定義されているとそのキーが使われますが、`KC_TRNS` (または同等のキーコード)が定義されている場合は常に下位レベルのキーコード(`KC_A`)が使われます。 - -**メモ:** 特定のレイヤーの透過性を示す有効な方法: -* `KC_TRANSPARENT` -* `KC_TRNS` (別名) -* `_______` (別名) - -これらのキーコードは、処理する非透過のキーコードを探すときに、下位レイヤーを検索させることができます。 - -## `keymap.c` の分析 - -この例では、[デフォルトの Clueboard 66% キーマップの古いバージョン](https://github.com/qmk/qmk_firmware/blob/ca01d94005f67ec4fa9528353481faa622d949ae/keyboards/clueboard/keymaps/default/keymap.c)を見ていきます。そのファイルを別のブラウザウィンドウで開くとコンテキスト内のすべてを見ることができるので便利です。 - -`keymap.c` ファイルには、あなたが関心があるであろう以下の2つの主要なセクションがあります: - -* [定義](#definitions) -* [レイヤー/キーマップデータ構造](#layers-and-keymaps) - -### 定義 :id=definitions - -ファイルの上部に以下のものがあります: - - #include QMK_KEYBOARD_H - - // 便利な定義 - #define GRAVE_MODS (MOD_BIT(KC_LSHIFT)|MOD_BIT(KC_RSHIFT)|MOD_BIT(KC_LGUI)|MOD_BIT(KC_RGUI)|MOD_BIT(KC_LALT)|MOD_BIT(KC_RALT)) - - /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * - * KC_TRNS (透過) の代わりに _______ を使うことができます * - * あるいは、KC_NO (NOOP) として XXXXXXX を使うことができます * - * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ - - // 各レイヤーは読みやすいように名前を持ちます。 - // アンダースコアは何も意味を持ちません - // STUFF あるいは他の名前のレイヤーを持つことができます。 - // レイヤー名は全て同じ長さである必要はなく、 - // また名前を完全に省略して単に数字を使うことができます。 - enum layer_names { - _BL, - _FL, - _CL, - }; - -これらはキーマップとカスタム関数を作成するときに使うことができる便利な定義です。`GRAVE_MODS` 定義は後でカスタム関数で使われ、その下の `_BL`、`_FL`、`_CL` 定義は各レイヤーを参照しやすくします。 - -注意: 古いキーマップファイルに `_______` および `XXXXXXX` の定義が含まれているかもしれません。これらはそれぞれ `KC_TRNS` および `KC_NO` の代わりに使うことができ、レイヤーがどのキーを上書きしているかを簡単に確認することができます。これらの定義はデフォルトで含まれるため、今では不要になりました。 - -### レイヤーとキーマップ :id=layers-and-keymaps - -このファイルの主要部分は `keymaps[]` 定義です。ここで、レイヤーとそれらの内容を列挙します。ファイルのこの部分は、以下の定義から始まります: - - const uint16_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] = { - -この後で、LAYOUT() マクロのリストがあります。LAYOUT() は単一のレイヤーを定義するためのキーのリストです。通常、1つ以上の"基本レイヤー" (QWERTY、Dvorak、Colemak など)があり、その上に1つ以上の"機能"レイヤーを重ねます。レイヤーの処理方法により、"より上位"のレイヤーの上に"より下位"のレイヤーを重ねることはできません。 - -QMK の `keymaps[][MATRIX_ROWS][MATRIX_COLS]` は、16ビットのアクションコード( quantum キーコードとも呼ばれる)を保持します。一般的なキーを表すキーコードの場合、その上位バイトは0で、その下位バイトはキーボードの USB HID usage ID です。 - -> QMK のフォーク元の TMK は、代わりに `const uint8_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS]` を使い、8ビットキーコードを保持します。一部のキーコード値は、`fn_actions[]` 配列を介して特定のアクションコードの実行を引き起こすために予約されています。 - -#### 基本レイヤー - -Clueboard の基本レイヤーの例です: - - /* Keymap _BL: Base Layer (Default Layer) - */ - [_BL] = LAYOUT( - F(0), KC_1, KC_2, KC_3, KC_4, KC_5, KC_6, KC_7, KC_8, KC_9, KC_0, KC_MINS, KC_EQL, KC_GRV, KC_BSPC, KC_PGUP, \ - KC_TAB, KC_Q, KC_W, KC_E, KC_R, KC_T, KC_Y, KC_U, KC_I, KC_O, KC_P, KC_LBRC, KC_RBRC, KC_BSLS, KC_PGDN, \ - KC_CAPS, KC_A, KC_S, KC_D, KC_F, KC_G, KC_H, KC_J, KC_K, KC_L, KC_SCLN, KC_QUOT, KC_NUHS, KC_ENT, \ - KC_LSFT, KC_NUBS, KC_Z, KC_X, KC_C, KC_V, KC_B, KC_N, KC_M, KC_COMM, KC_DOT, KC_SLSH, KC_RO, KC_RSFT, KC_UP, \ - KC_LCTL, KC_LGUI, KC_LALT, KC_MHEN, KC_SPC,KC_SPC, KC_HENK, KC_RALT, KC_RCTL, MO(_FL), KC_LEFT, KC_DOWN, KC_RGHT), - -これについて注意すべきいくつかの興味深いこと: - -* C ソースの観点からは、これは単一の配列に過ぎませんが、物理デバイス上の各キーがどこにあるかをより簡単に可視化するために、空白が埋め込まれています。 -* 単純なキーボードスキャンコードの先頭には KC_ が付いていますが、"特別な"キーには付いていません。 -* 左上のキーはカスタム機能 0 (`F(0)`) をアクティブにします。 -* "Fn" キーは `MO(_FL)` で定義され、そのキーが押されている間は `_FL` レイヤーに移動します。 - -#### 機能オーバーレイレイヤー - -機能レイヤーはコードの観点から基本レイヤーと違いはありません。ただし概念的には、置き換えの代わりにオーバーレイとしてそのレイヤーを構築します。多くの人にとってはこの区別は重要ではありませんが、より複雑なレイヤー設定を構築するにつれて、ますます重要になります。 - - [_FL] = LAYOUT( - KC_GRV, KC_F1, KC_F2, KC_F3, KC_F4, KC_F5, KC_F6, KC_F7, KC_F8, KC_F9, KC_F10, KC_F11, KC_F12, _______, KC_DEL, BL_STEP, \ - _______, _______, _______,_______,_______,_______,_______,_______,KC_PSCR,KC_SCRL, KC_PAUS, _______, _______, _______, _______, \ - _______, _______, MO(_CL),_______,_______,_______,_______,_______,_______,_______, _______, _______, _______, _______, \ - _______, _______, _______,_______,_______,_______,_______,_______,_______,_______, _______, _______, _______, _______, KC_PGUP, \ - _______, _______, _______, _______, _______,_______, _______, _______, _______, MO(_FL), KC_HOME, KC_PGDN, KC_END), - -注意すべきいくつかの興味深いこと: - -* `_______` 定義を使って、`KC_TRNS` を `_______` に変換しました。これによりこのレイヤーで変更されたキーを簡単に見つけることができます。 -* このレイヤーで `_______` キーのいずれかを押すと、次の下位のアクティブなレイヤーのキーがアクティブになります。 - -# 核心となる詳細 - -これで独自のキーマップを作成するための基本的な概要が得られました。詳細は以下のリソースを見てください: - -* [キーコード](ja/keycodes.md) -* [キーマップ FAQ](ja/faq_keymap.md) - -これらのドキュメントの改善に積極的に取り組んでいます。それらを改善する方法について提案がある場合は、[issue を報告](https://github.com/qmk/qmk_firmware/issues/new)してください！ diff --git a/docs/ja/mod_tap.md b/docs/ja/mod_tap.md deleted file mode 100644 index 1d96ed1ee8..0000000000 --- a/docs/ja/mod_tap.md +++ /dev/null @@ -1,71 +0,0 @@ -# モッドタップ - - - -モッドタップキー `MT(mod, kc)` は、押したままの時にモディファイアのように機能し、タップされた時に通常のキーのように振舞います。別の言い方をすると、タップした時に Escape を送信しますが、押したままの時に Control あるいは Shift キーとして機能するキーを持つことができます。 - -このキーコードと `OSM()` が受け付けるモディファイアは、`KC_` ではなく、`MOD_` の接頭辞が付いています: - -| モディファイア | 説明 | -|----------------|----------------------------------------------| -| `MOD_LCTL` | 左 Control | -| `MOD_LSFT` | 左 Shift | -| `MOD_LALT` | 左 Alt | -| `MOD_LGUI` | 左 GUI (Windows/Command/Meta キー) | -| `MOD_RCTL` | 右 Control | -| `MOD_RSFT` | 右 Shift | -| `MOD_RALT` | 右 Alt (AltGr) | -| `MOD_RGUI` | 右 GUI (Windows/Command/Meta キー) | -| `MOD_HYPR` | Hyper (左 Control、左 Shift、左 Alt、左 GUI) | -| `MOD_MEH` | Meh (左 Control、左 Shift、左 Alt) | - -以下のようにそれらを OR することで、これらを組み合わせることができます: - -```c -MT(MOD_LCTL | MOD_LSFT, KC_ESC) -``` - -押したままの時にこのキーは左 Control および左 Shift をアクティブにし、タップされた時に Escape を送信します。 - -便利なように、QMK はキーマップで一般的な組み合わせをよりコンパクトにするためのモッドタップショートカットを含んでいます: - -| キー | エイリアス | 説明 | -| ------------ | ----------------------------------------------------------------- | ---------------------------------------------------------------------- | -| `LCTL_T(kc)` | `CTL_T(kc)` | 押したままの場合は左 Control、タップした場合は `kc` | -| `LSFT_T(kc)` | `SFT_T(kc)` | 押したままの場合は左 Shift、タップした場合は `kc` | -| `LALT_T(kc)` | `LOPT_T(kc)`, `ALT_T(kc)`, `OPT_T(kc)` | 押したままの場合は左 Alt、タップした場合は `kc` | -| `LGUI_T(kc)` | `LCMD_T(kc)`, `LWIN_T(kc)`, `GUI_T(kc)`, `CMD_T(kc)`, `WIN_T(kc)` | 押したままの場合は左 GUI、タップした場合は `kc` | -| `RCTL_T(kc)` | | 押したままの場合は右 Control、タップした場合は `kc` | -| `RSFT_T(kc)` | | 押したままの場合は右 Shift、タップした場合は `kc` | -| `RALT_T(kc)` | `ROPT_T(kc)`, `ALGR_T(kc)` | 押したままの場合は右 Alt、タップした場合は `kc` | -| `RGUI_T(kc)` | `RCMD_T(kc)`, `RWIN_T(kc)` | 押したままの場合は右 GUI、タップした場合は `kc` | -| `LSG_T(kc)` | `SGUI_T(kc)`, `SCMD_T(kc)`, `SWIN_T(kc)` | 押したままの場合は左 Shift と左 GUI、タップした場合は `kc` | -| `LAG_T(kc)` | | 押したままの場合は左 Alt と左 GUI、タップした場合は `kc` | -| `RSG_T(kc)` | | 押したままの場合は右 Shift と右 GUI、タップした場合は `kc` | -| `RAG_T(kc)` | | 押したままの場合は右 Alt と右 GUI、タップした場合は `kc` | -| `LCA_T(kc)` | | 押したままの場合は左 Control と左 Alt、タップした場合は `kc` | -| `LSA_T(kc)` | | 押したままの場合は左 Shift と Alt、タップした場合は `kc` | -| `RSA_T(kc)` | `SAGR_T(kc)` | 押したままの場合は右 Shift と Alt (AltGr)、タップした場合は `kc` | -| `RCS_T(kc)` | | 押したままの場合は右 Control と Shift、タップした場合は `kc` | -| `LCAG_T(kc)` | | 押したままの場合は左 Control、左 Alt と左 GUI、タップした場合は `kc` | -| `RCAG_T(kc)` | | 押したままの場合は右 Control、右 Alt と右 GUI、タップした場合は `kc` | -| `C_S_T(kc)` | | 押したままの場合は左 Control と左 Shift、タップした場合は `kc` | -| `MEH_T(kc)` | | 押したままの場合は左 Control、左 Shift と左 Alt、タップした場合は `kc` | -| `HYPR_T(kc)` | `ALL_T(kc)` | 押したままの場合は左 Control、左 Shift、左 Alt と左 GUI、タップした場合は `kc` - より詳しくは[ここ](https://brettterpstra.com/2012/12/08/a-useful-caps-lock-key/)を見てください | - -## 注意事項 - -現在のところ、`MT()` の引数 `kc` は[基本的なキーコードセット](ja/keycodes_basic.md)に制限されています。つまり、`LCTL()`、`KC_TILD`、あるいは `0xFF` より大きなキーコードを使うことができません。これは、QMK が16ビットのキーコードを使うためです。3ビットは機能の識別のために使われ、1ビットは右または左の mod を選択するために使われ、4ビットはどの mod かを区別するために使われ、キーコードには8ビットしか残されていません。さらに、モッドタップで少なくとも1つの右手用のモディファイアが指定された場合、指定された全てのモディファイアが右手用になるため、2つをうまく組み合わせて一致させることはできません。例えば、左 Control と右 Shift は、右 Control と右 Shift になります。 - -これを拡張してもせいぜい複雑になるだけでしょう。32ビットキーコードに移行すると、これの多くが解決されますが、キーマップマトリックスが使用する領域が2倍になります。また、問題が起きる可能性もあります。タップしたキーコードにモディファイアを適用する必要がある場合は、[タップダンス](ja/feature_tap_dance.md#example-5)を使うことができます。 - -さらに、Windows でリモートデスクトップ接続を使う場合に、問題が発生する場合があります。なぜならば、これらのキーコードは人よりも速くキーイベントを送信するため、リモートデスクトップがキーコードを見落とすかもしれないからです。 -この問題を解決するには、リモートデスクトップ接続を開いて「オプションの表示」をクリックし、「ローカル リソース」タブを開きます。キーボードセクションで、ドロップダウンを「このコンピューター」に変更します。これで問題が解決され、文字が正しく機能するようになります。 -[`TAP_CODE_DELAY`](ja/config_options.md#behaviors-that-can-be-configured) を増やすことで緩和することもできます。 - -## 他のリソース - -モッドタップの動作を調整する追加フラグについては、[タップホールド設定オプション](ja/tap_hold.md)を参照してください。 diff --git a/docs/ja/newbs.md b/docs/ja/newbs.md deleted file mode 100644 index 5fdf40425a..0000000000 --- a/docs/ja/newbs.md +++ /dev/null @@ -1,40 +0,0 @@ -# QMK チュートリアル - - - -キーボードには、コンピュータ入っているものと似たようなプロセッサが入っています。 -このプロセッサでは、キーボードのボタンの押し下げの検出を担当し、キーが押されたときにコンピュータに通知するソフトウェアが動作しています。 -QMK Firmware は、そのソフトウェアの役割を果たし、ボタンの押下を検出しその情報をホストコンピュータに渡します。 -カスタムキーマップを作るということは、キーボード上で動くプログラムを作るということなのです。 - -QMK は、簡単なことは簡単に、そして、難しいことを可能なことにすることで、あなたの手にたくさんのパワーをもたらします。 -パワフルなキーマップを作るためにプログラムを作成する方法を知る必要はありません。いくつかのシンプルな文法に従うだけで OK です。 - -お使いのキーボードで QMK を実行できるかどうか不明ですか？ -もし作成したキーボードがメカニカルキーボードの場合、実行できる可能性が高いです。 -QMK は[多くの趣味のキーボード](https://qmk.fm/keyboards/)をサポートしています。 -現在使用しているキーボードが QMK を実行できない場合、QMK を実行できるキーボードの選択肢はたくさんあります。 - -?> **このガイドは私のためにあるのでしょうか？**
-もし、プログラミングの考え方に抵抗があるのであれば、代わりに[私たちのオンライン GUI](ja/newbs_building_firmware_configurator.md) を見てみてください。 - -## 概要 - -このガイドは、ソースコードを使ってキーボードのファームウェアを構築したいと考えている人に適しています。 もしあなたがすでにプログラマーであれば、このプロセスはとても身近で簡単に理解できるでしょう。このガイドには3つの主要なセクションがあります: - -1. [環境設定](ja/newbs_getting_started.md) -2. [コマンドラインを使用して初めてのファームウェアを構築する](ja/newbs_building_firmware.md) -3. [ファームウェアを書きこむ](ja/newbs_flashing.md) - -このガイドは、これまでソフトウェアをコンパイルしたことがない人を支援することに特化しています。 -その観点から選択と推奨を行います。 -これらの手順の多くには代替方法があり、これらの代替方法のほとんどをサポートしています。 -タスクを達成する方法について疑問がある場合は、[案内を求めることができます](ja/getting_started_getting_help.md)。 - -## 追加のリソース - -このガイドの他にも、QMK の学習に役立つリソースがいくつかあります。[シラバス](ja/syllabus.md)と[学習リソース](ja/newbs_learn_more_resources.md)のページにまとめました。 diff --git a/docs/ja/newbs_building_firmware.md b/docs/ja/newbs_building_firmware.md deleted file mode 100644 index 563efa7163..0000000000 --- a/docs/ja/newbs_building_firmware.md +++ /dev/null @@ -1,81 +0,0 @@ -# 初めてのファームウェアを構築する(コマンドライン版) - - - -ビルド環境をセットアップしたので、カスタムファームウェアのビルドを開始する準備ができました。 -ガイドのこのセクションでは、ファイルマネージャ、テキストエディタ、ターミナルウィンドウの3つのプログラム間を行き来します。 -キーボードファームウェアが完成して満足するまで、この3つすべてを開いたままにします。 - -## 新しいキーマップを作成する - -独自のキーマップを作成するには、`default` キーマップのコピーを作成する必要があります。最後のステップでビルド環境を設定した場合は、QMK CLI を使って簡単に行うことができます: - - qmk new-keymap - -もし環境が設定されていない場合や、複数のキーボードを所持している場合は、キーボード名を指定することができます: - - qmk new-keymap -kb - -そのコマンドの出力を見ると、次のようになっているはずです: - - Ψ keymap directory created in: /home/me/qmk_firmware/keyboards/clueboard/66/rev3/keymaps/ - -これがあなたの新しい `keymap.c` ファイルの場所です。 - -## あなたの好みのテキストエディタで `keymap.c` を開く - -テキストエディタで `keymap.c` ファイルを開きます。 -このファイル内には、キーボードの動作を制御する構造があります。 -`keymap.c`の上部には、キーマップを読みやすくする定義と列挙型があります。 -さらに下には、次のような行があります: - - const uint16_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] = { - -この行はレイヤーのリストの開始を表わしています。 -その下には、`LAYOUT` を含む行があり、これらの行はレイヤーの開始を表わしています。 -その行の下には、そのレイヤーを構成するキーのリストがあります。 - -!> キーマップファイルを編集するときは、カンマを追加したり削除したりしないように注意してください。そうするとファームウェアのコンパイルができなくなり、余分であったり欠落していたりするカンマがどこにあるのかを容易に把握できない場合があります。 - -## 好みに合わせてレイアウトをカスタマイズ - -納得のいくまでこのステップを繰り返します。 -気になる点をひとつづつ変更して試すのもよし、全部作りなおすのもよし。 -あるレイヤー全体が必要ない場合はレイヤーを削除することもでき、必要があれば、合計 32 個までレイヤーを追加することもできます。 -QMK にはたくさんの機能があり、完全なリストは左側のサイドバーの「QMK を使う」の下を調べてください。ここから始めるために、簡単に使える機能をいくつか紹介します: - -* [基本的なキーコード](ja/keycodes_basic.md) -* [Quantum キーコード](ja/quantum_keycodes.md) -* [グレイブ エスケープ](ja/feature_grave_esc.md) -* [マウスキー](ja/feature_mouse_keys.md) - -?> キーマップがどのように機能するかを感じながら、各変更を小さくしてください。大きな変更は、発生する問題のデバッグを困難にします。 - -## ファームウェアをビルドする :id=build-your-firmware - -キーマップの変更が完了したら、ファームウェアをビルドする必要があります。これを行うには、ターミナルウィンドウに戻り、コンパイルコマンドを実行します: - - qmk compile - -もし環境が設定されていない場合や、複数のキーボードを所持している場合は、キーボードやキーマップを指定することができます: - - qmk compile -kb -km - -これがコンパイルされる間、どのファイルがコンパイルされているかを知らせる多くの出力が画面に表示されます。 -次のような出力で終わるはずです: - -``` -Linking: .build/planck_rev5_default.elf [OK] -Creating load file for flashing: .build/planck_rev5_default.hex [OK] -Copying planck_rev5_default.hex to qmk_firmware folder [OK] -Checking file size of planck_rev5_default.hex [OK] - * The firmware size is fine - 27312/28672 (95%, 1360 bytes free) -``` - -## ファームウェアを書きこむ - -[「ファームウェアを書きこむ」](ja/newbs_flashing.md) に移動して、キーボードに新しいファームウェアを書き込む方法を学習します。 diff --git a/docs/ja/newbs_building_firmware_configurator.md b/docs/ja/newbs_building_firmware_configurator.md deleted file mode 100644 index 6b48e79de8..0000000000 --- a/docs/ja/newbs_building_firmware_configurator.md +++ /dev/null @@ -1,20 +0,0 @@ -# QMK Configurator - - - -[![QMK Configurator Screenshot](https://i.imgur.com/anw9cOL.png)](https://config.qmk.fm/) - -[QMK Configurator](https://config.qmk.fm) は、QMKファームウェアの `.hex` や `.bin` ファイルを生成するオンライングラフィカルユーザーインターフェイスです。 - -[ビデオチュートリアル](https://www.youtube.com/watch?v=-imgglzDMdY) を見てください。 -多くの人は、それが自分のキーボードのプログラミングを始めるのに十分な情報であることに気づくでしょう。 - -QMK Configurator は Chrome/Firefox で最適に動作します。 - -!> **注意: Keyboard Layout Editor (KLE) や kbfirmware などの他のツールのファイルは、QMK Configurator と互換性がありません。それらをロードしたり、インポートしたりしないでください。QMK Configurator は異なるツールです。** - -[QMK Configurator: ステップ・バイ・ステップ](ja/configurator_step_by_step.md)を参照してください。 diff --git a/docs/ja/newbs_flashing.md b/docs/ja/newbs_flashing.md deleted file mode 100644 index 39f5da88a8..0000000000 --- a/docs/ja/newbs_flashing.md +++ /dev/null @@ -1,133 +0,0 @@ -# ファームウェアを書き込む - - - -カスタムファームウェアは出来たので、いよいよキーボードへの書き込み(フラッシュ)です。 - -## キーボードを DFU (Bootloader) モードにする - -カスタムファームウェアを書き込むには、最初にキーボードを普段とは違う特別な状態、フラッシュモードにする必要があります。 -このモードでは、キーボードはキーボードとしての機能を果たしません。 -ファームウェアの書き込み中にキーボードのケーブルを抜いたり、書き込みプロセスを中断したりしないことが非常に重要です。 - -キーボードによって、この特別なモードに入る方法は異なります。 -PCB が現在 QMK、TMK、PS2AVRGB (Bootmapper Client) を実行しており、キーボードメーカーから具体的な指示が与えられていない場合は、次を順番に試してください。 - -* 両方のシフトキーを押しながら、`Pause` キーを押す -* 両方のシフトキーを押しながら、`B` キーを押す -* キーボードのケーブルを抜いて、スペースバーと `B` を同時に押しながら、キーボードを再び接続し、1秒待ってからキーを放す -* キーボードのケーブルを抜いて、左上か左下のキー(通常は Escape か左 Control)を押しながらキーボードを接続する -* 通常、PCB の裏側に付けられている物理的な `RESET` ボタンを押す -* PCB 上の `RESET` か `GND` のラベルの付いたヘッダピンを探し、PCB 接続中にそれらを互いにショートする - -上記を全て試してもうまくいかず、基板のメインチップに `STM32` と表示されている場合、これは少し複雑になる可能性があります。通常、最善の方法は [Discord](https://discord.gg/Uq7gcHh) で助けを求めることです。おそらく基板の写真をいくつか求められるでしょう。あらかじめそれらを準備することができれば物事を進めるのに役立ちます！ - -それ以外の場合は、QMK Toolbox で次のような黄色のメッセージが表示されます: - -``` -*** DFU device connected: Atmel Corp. ATmega32U4 (03EB:2FF4:0000) -``` - -そして、このブートローダデバイスはデバイスマネージャーやシステム情報.app、`lsusb` にも表示されます。 - -## QMK Toolbox を使ってキーボードに書き込む - -キーボードに書き込む最も簡単な方法は [QMK Toolbox](https://github.com/qmk/qmk_toolbox/releases) を使うことです。 - -ただし、QMK Toolbox は、現在は Windows と macOS でしか使えません。 -Linux を使用している場合(および、コマンドラインでファームウェアを書き込みたい場合)は、[コマンドラインからキーボードを書き込む](#flash-your-keyboard-from-the-command-line)節まで進んでください。 - -### QMK Toolbox にファイルをロードする - -まず QMK Toolbox アプリケーションを起動します。 -Finder またはエクスプローラーでファームウェアのファイルを探します。 -キーボードのファームウェアは `.hex` または `.bin` のどちらかの形式です。 -ビルド時に QMK は、キーボードに適した形式のものを `qmk_firmware` のトップフォルダにコピーしているはずです。 - -Windows か macOS を使用している場合、現在のフォルダをエクスプローラーか Finder で簡単に開くためのコマンドがあります。 - - - -#### ** Windows ** - -``` -start . -``` - -#### ** macOS ** - -``` -open . -``` - - - -ファームウェアファイルは常に以下の命名形式に従っています: - -``` -_.{bin,hex} -``` - -例えば、`plank/rev5` の `default` キーマップのファイル名は以下のようになります: - -``` -planck_rev5_default.hex -``` - -ファームウェアファイルを見つけたら、QMK Toolbox の "Local file" ボックスにドラッグするか、"Open" をクリックしてファームウェアファイルが格納されている場所を指定します。 - -### キーボードへの書き込み - -QMK Toolbox の `Flash` ボタンをクリックします。次のような出力が表示されます。 - -``` -*** DFU device connected: Atmel Corp. ATmega32U4 (03EB:2FF4:0000) -*** Attempting to flash, please don't remove device ->>> dfu-programmer.exe atmega32u4 erase --force - Erasing flash... Success - Checking memory from 0x0 to 0x6FFF... Empty. ->>> dfu-programmer.exe atmega32u4 flash "D:\Git\qmk_firmware\gh60_satan_default.hex" - Checking memory from 0x0 to 0x3F7F... Empty. - 0% 100% Programming 0x3F80 bytes... - [>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>] Success - 0% 100% Reading 0x7000 bytes... - [>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>] Success - Validating... Success - 0x3F80 bytes written into 0x7000 bytes memory (56.70%). ->>> dfu-programmer.exe atmega32u4 reset - -*** DFU device disconnected: Atmel Corp: ATmega32U4 (03EB:2FF4:0000) -``` - -## コマンドラインでファームウェアを書き込む :id=flash-your-keyboard-from-the-command-line - -これは、以前のものと比較して非常に単純になりました。 -ファームウェアをコンパイルして書き込む準備ができたら、ターミナルウィンドウを開いて書き込みコマンドを実行します: - - qmk flash - -もし CLI でキーボードやキーマップ名を設定していない場合や、複数のキーボードを持っている場合、キーボードとキーマップを指定することができます: - - qmk flash -kb -km - -これはキーボードの設定を確認し、指定されたブートローダに基づいて書き込もうとします。これはどのブートローダをキーボードが使っているか知る必要がないことを意味します。単にコマンドを実行し、コマンドに重い仕事をさせましょう。 - -ただし、これはキーボードごとに設定されているブートローダに依存します。 -もし、この情報が設定されていない場合、または、使用しているキーボードが、ファームウェア書き込みでサポートされているターゲットを持っていない場合、次のエラーが表示されます: - - WARNING: This board's bootloader is not specified or is not supported by the ":flash" target at this time. - -この場合、あなたは明示的にブートローダを指定する方法を使わなければなりません。詳細は、[ファームウェアのフラッシュ](ja/flashing.md)ガイドを参照してください。 - -## テストしましょう！ - -おめでとうございます！カスタムファームウェアがキーボードにプログラムされ、テストする準備ができました！ - -少し運が良ければ全てが完璧に機能しますが、そうでない場合は何が問題なのかを理解するのに役立つ手順があります。 -通常、キーボードのテストは非常に簡単です。全てのキーをひとつずつ押して、期待するキーが送信されることを確認します。例え QMK で動作していない場合でも、[QMK Configurator](https://config.qmk.fm/#/test/) のテストモードを使用すると、キーボードをチェックできます。 - -まだ動作しませんか？詳細については FAQ トピックを参照するか、[Discord でチャット](https://discord.gg/Uq7gcHh)してください。 diff --git a/docs/ja/newbs_getting_started.md b/docs/ja/newbs_getting_started.md deleted file mode 100644 index ece64e8d8b..0000000000 --- a/docs/ja/newbs_getting_started.md +++ /dev/null @@ -1,210 +0,0 @@ -# QMK 環境の構築 - - - -キーマップをビルドする前に、いくつかのソフトウェアをインストールしてビルド環境を構築する必要があります。 -ファームウェアをコンパイルするキーボードの数に関わらず、この作業を一度だけ実行する必要があります。 - -## 1. 前提条件 - -始めるために必要なソフトウェアがいくつかあります。 - -* [テキストエディタ](ja/newbs_learn_more_resources.md#text-editor-resources) - * プレーンテキストファイルを編集して保存できるプログラムが必要です。多くの OS に付属するデフォルトのエディタはプレーンテキストファイルを保存しないため、選択したエディタがプレーンテキストファイルを保存することを確認する必要があります。 -* [Toolbox (オプション)](https://github.com/qmk/qmk_toolbox) - * Windows と macOS で使える GUI を備えたプログラムで、カスタムキーボードのプログラミングとデバッグの両方ができます。 - -?> もし、Linux か Unix のコマンドを使ったことがない場合、こちらで基本的な概念や各種コマンドを学んでください。[これらの教材](ja/newbs_learn_more_resources.md#command-line-resources)で QMK を使うのに必要なことを学ぶことができます。 - -## 2. ビルド環境を準備する :id=set-up-your-environment - -私たちは、QMK を可能な限り簡単に構築できるように努力しています。Linux か Unix 環境を用意するだけで、QMK に残りをインストールさせることができます。 - - - -### ** Windows ** - -QMK は、MSYS2、CLI、および必要な全ての依存関係のバンドルを保守しています。また、正しい環境で直接起動するための便利な `QMK MSYS` ターミナルショートカットも提供しています。 - -#### 前提条件 - -[QMK MSYS](https://msys.qmk.fm/) をインストールする必要があります。最新リリースは[ここ](https://github.com/qmk/qmk_distro_msys/releases/latest)から入手できます。 - -または、MSYS2 を手動でインストールしたい場合、次のセクションでプロセスを説明します。 - -
- 手動インストール - -?> `QMK MSYS` を使う場合、次のステップは無視してください。 - -#### 前提条件 - -MSYS2 と Git と Python をインストールする必要があります。https://www.msys2.org のインストール手順に従ってください。 - -MSYS2 をインストールしたら、開いている MSYS の全ターミナル画面を閉じて、新しい MinGW 64-bit ターミナル画面を開きます。 - -!> **注意:** MinGW 64-bit ターミナルは、インストールが完了した時に開く MSYS ターミナルと*同じではありません*。プロンプトには、「MSYS」ではなく、紫色のテキストで「MINGW64」と表示されます。違いについての詳細は[このページ](https://www.msys2.org/wiki/MSYS2-introduction/#subsystems)を参照してください。 - -それから、次のように実行します: - - pacman --needed --noconfirm --disable-download-timeout -S git mingw-w64-x86_64-toolchain mingw-w64-x86_64-python3-pip - -#### インストール - -次のコマンドを実行して、QMK CLI をインストールします: - - python3 -m pip install qmk - -
- -### ** macOS ** - -QMK は CLI と全ての必要な依存関係を自動的にインストールする Homebrew tap と formula を保守しています。 - -#### 前提条件 - -Homebrew のインストールが必要です。https://brew.sh の手順に従ってください。 - -#### インストール - -次のコマンドを実行して、QMK CLI をインストールします: - - brew install qmk/qmk/qmk - -### ** Linux/WSL ** - -?> **WSL ユーザーへの注意**: デフォルトでは、インストールプロセスは QMK リポジトリを WSL ホームディレクトリに clone しますが、手動で clone した場合、Windows ファイルシステムではなく、WSL インスタンス内にある(つまり `/mnt` 内にない)ことを確認してください。これは、現在アクセスが[非常に遅い](https://github.com/microsoft/WSL/issues/4197)ためです。 - -#### 前提条件 - -Git と Python をインストールする必要があります。両方とも既にインストールされている可能性は高いですが、そうでない場合、次のコマンドのいずれかでそれらをインストールできます: - -* Debian / Ubuntu / Devuan: `sudo apt install -y git python3-pip` -* Fedora / Red Hat / CentOS: `sudo yum -y install git python3-pip` -* Arch / Manjaro: `sudo pacman --needed --noconfirm -S git python-pip libffi` -* Void: `sudo xbps-install -y git python3-pip` -* Solus: `sudo eopkg -y install git python3` -* Sabayon: `sudo equo install dev-vcs/git dev-python/pip` -* Gentoo: `sudo emerge dev-vcs/git dev-python/pip` - -#### インストール - -次のコマンドを実行して、QMK CLI をインストールします: - - python3 -m pip install --user qmk - -#### コミュニティパッケージ - -これらのパッケージはコミュニティメンバーによって保守されているため、最新ではないか、完全には機能しない可能性があります。問題が発生した場合は、それぞれのメンテナに報告してください。 - -Arch ベースのディストリビューションでは、公式リポジトリから CLI をインストールできます(注意: 執筆時点では、このパッケージは一部の依存関係をオプションとしてマークしていますが、そうではありません): - - sudo pacman -S qmk - -AUR から `qmk-git` パッケージを試すこともできます: - - yay -S qmk-git - -### ** FreeBSD ** - -#### インストール - -次のコマンドを実行して、QMK CLI の FreeBSD パッケージをインストールします: - - pkg install -g "py*-qmk" - -注意: インストールの最後に表示された指示に従うことを忘れないでください(再度表示するには、`pkg info -Dg "py*-qmk"` を使ってください)。 - - - -## 3. QMK の設定を行う :id=set-up-qmk - - - -### ** Windows ** - -QMK のインストール後に、このコマンドで設定できます: - - qmk setup - -ほとんどの場合、全てのプロンプトに `y` と答えます。 - -### ** macOS ** - -QMK のインストール後に、このコマンドで設定できます: - - qmk setup - -ほとんどの場合、全てのプロンプトに `y` と答えます。 - -### ** Linux/WSL ** - -QMK のインストール後に、このコマンドで設定できます: - - qmk setup - -ほとんどの場合、全てのプロンプトに `y` と答えます。 - -?>**Debian、Ubuntu、それらの派生に関する注意**: -次のようなエラーが表示される可能性があります: `bash: qmk: command not found`. -これは Debian の Bash 4.4 リリースで導入された[バグ](https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=839155)で、`$HOME/.local/bin` が PATH から削除されました。このバグは後に Debian や Ubuntu で修正されました。 -残念なことに、Ubuntu はこのバグを再導入し、[まだ修正していません](https://bugs.launchpad.net/ubuntu/+source/bash/+bug/1588562)。 -幸い、修正は簡単です。これをあなたのユーザで実行します: `echo 'PATH="$HOME/.local/bin:$PATH"' >> $HOME/.bashrc && source $HOME/.bashrc` - -### ** FreeBSD ** - -QMK のインストール後に、このコマンドで設定できます: - - qmk setup - -ほとんどの場合、全てのプロンプトに `y` と答えます。 - - - -?> qmk ホームフォルダは、セットアップ時に `qmk setup -H ` を使って指定し、[cli 構成](ja/cli_configuration.md?id=single-key-example)と変数 `user.qmk_home` を使って変更できます。利用可能な全てのオプションについては、`qmk setup --help` を実行します。 - -?> 既に GitHub の使い方を知っている場合、[これらの手順に従うことをお勧めします](ja/getting_started_github.md)。そして `qmk setup /qmk_firmware` を使って個人用の fork から clone します。この一文の意味が分からない場合、このメッセージは無視してかまいません。 - -## 4. ビルド環境の確認 - -これで QMK のビルド環境が用意できたので、キーボードのファームウェアをビルドできます。キーボードのデフォルトキーマップをビルドすることから始めます。次の形式のコマンドでビルドできるはずです: - - qmk compile -kb -km default - -例えば、Clueboard 66% のファームウェアをビルドする場合、次のようにします: - - qmk compile -kb clueboard/66/rev3 -km 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) -``` - -## 5. ビルド環境の設定(オプション) - -ビルド環境を設定してデフォルトを設定することで、QMK での作業をあまり面倒くさくないようにすることができます。今からやりましょう！ - -QMK を初めて使うほとんどの人は、キーボードを1つしか持っていません。`qmk config` コマンドでこのキーボードをデフォルトとして設定できます。例えば、デフォルトのキーボードを `clueboard/66/rev4` に設定するには: - - qmk config user.keyboard=clueboard/66/rev4 - -デフォルトキーマップ名を設定することもできます。ほとんどの人はここで GitHub ユーザ名を使いますが、そうすることをお勧めします。 - - qmk config user.keymap= - -この後、これらの引数をオフにして、次のようにキーボードをコンパイルできます: - - qmk compile - -# キーマップの作成 - -これであなた専用のキーマップを作成する準備ができました！次は[初めてのファームウェアの構築](ja/newbs_building_firmware.md)で専用のキーマップを作成します。 diff --git a/docs/ja/newbs_git_best_practices.md b/docs/ja/newbs_git_best_practices.md deleted file mode 100644 index 7ba16fce75..0000000000 --- a/docs/ja/newbs_git_best_practices.md +++ /dev/null @@ -1,24 +0,0 @@ -# QMK における Git 運用作法 :id=best-git-practices-for-working-with-qmk - - - -## または、"如何にして私は心配することをやめて Git を愛することを学んだか。" - -このセクションは、QMK への貢献をスムーズに行なう最もよい方法を初心者に教えることを目的としています。 -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) を両方とも完了している。 - ---- - -- パート 1: [あなたのフォークの master ブランチ: 更新は頻繁に、コミットはしないこと](ja/newbs_git_using_your_master_branch.md) -- パート 2: [マージの競合の解決](ja/newbs_git_resolving_merge_conflicts.md) -- パート 3: [同期のとれていない git ブランチの再同期](ja/newbs_git_resynchronize_a_branch.md) diff --git a/docs/ja/newbs_git_resolving_merge_conflicts.md b/docs/ja/newbs_git_resolving_merge_conflicts.md deleted file mode 100644 index 532b1e3001..0000000000 --- a/docs/ja/newbs_git_resolving_merge_conflicts.md +++ /dev/null @@ -1,94 +0,0 @@ -# マージの競合の解決 - - - -ブランチでの作業の完了に時間がかかる場合、他の人が行った変更が、プルリクエストを開いたときにブランチに加えた変更と競合することがあります。 -これは *マージの競合* と呼ばれ、複数の人が同じファイルの同じ部分を編集すると発生します。 - -?> このドキュメントは [あなたのフォークの master ブランチ: 更新は頻繁に、コミットはしないこと](ja/newbs_git_using_your_master_branch.md) で詳述されている概念に基づいています。 -その概念に慣れていない場合は、まずそれを読んでから、ここに戻ってください。 - -## 変更のリベース - -*リベース* は、コミット履歴のある時点で適用された変更を取得し、それらを元に戻し、次に同じ変更を別のポイントに適用する Git の方法です。 -マージの競合が発生した場合、ブランチをリベースして、ブランチを作成してから現在までに行われた変更を取得できます。 - -開始するには、次を実行します: - -``` -git fetch upstream -git rev-list --left-right --count HEAD...upstream/master -``` - -ここに入力された `git rev-list` コマンドは、現在のブランチと QMK の master ブランチで異なるコミットの数を返します。 -最初に `git fetch` を実行して、upstream リポジトリの現在の状態を表す refs があることを確認します。 -入力された `git rev-list` コマンドの出力は2つの数値を返します: - -``` -$ git rev-list --left-right --count HEAD...upstream/master -7 35 -``` - -最初の数字は、現在のブランチが作成されてからのコミット数を表し、2番目の数字は、現在のブランチが作成されてから `upstream/master` に対して行われたコミットの数であり、したがって、現在のブランチに記録されていない変更です。 - -現在のブランチと upstream リポジトリの両方の現在の状態がわかったので、リベース操作を開始できます: - -``` -git rebase upstream/master -``` - -これにより、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 ", 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". -``` - -これにより、マージの競合があることがわかり、競合のあるファイルの名前が示されます。 -テキストエディタで競合するファイルを開くと、ファイルのどこかに次のような行があります: - -``` -<<<<<<< HEAD -

For help with any issues, email us at support@webhost.us.

-======= -

Need help? Email support@webhost.us.

->>>>>>> Commit #1 -``` - -行 `<<<<<<< HEAD` はマージ競合の始まりを示し、行 `>>>>>>> commit #1` は終了を示し、競合するセクションは `=======` で区切られます。 -`HEAD` 側の部分はファイルの QMK master バージョンからのものであり、コミットメッセージでマークされた部分は現在のブランチとコミットからのものです。 - -Git はファイルの内容ではなく *ファイルへの変更* を直接追跡するため、Git がコミットの前にファイル内にあったテキストを見つけられない場合、ファイルの編集方法がわかりません。 -ファイルを再編集して、競合を解決します。 -変更を加えてから、ファイルを保存します。 - -``` -

Need help? Email support@webhost.us.

-``` - -そしてコマンド実行: - -``` -git add conflicting_file_1.txt -git rebase --continue -``` - -Git は、競合するファイルへの変更をログに記録し、ブランチのコミットが最後に達するまで適用し続けます。 diff --git a/docs/ja/newbs_git_resynchronize_a_branch.md b/docs/ja/newbs_git_resynchronize_a_branch.md deleted file mode 100644 index 567ec38bfe..0000000000 --- a/docs/ja/newbs_git_resynchronize_a_branch.md +++ /dev/null @@ -1,88 +0,0 @@ -# 同期のとれていない git ブランチの再同期 - - - -仮にあなたの `master` ブランチにあなたのコミットを行い、そしてあなたの QMK リポジトリの更新が必要になったとします。 -(フォーク元の) QMK の `master` ブランチをあなたの `master` ブランチに `git pull` することもできますが、GitHub は、あなたのブランチが `qmk:master` より何コミットか先行していると通知します、この状態で QMK にプルリクエストを行う場合、問題が発生する可能性があります。 -(訳注：この通知は、GitHub のあなたのリポジトリの code ペインのブランチ選択メニューの下のあたりで `This branch is 3 commit ahead of qmk:master` という様な文面で表示されています。) - -?> このドキュメントは [あなたのフォークの master ブランチ: 更新は頻繁に、コミットはしないこと](ja/newbs_git_using_your_master_branch.md) で詳述されている概念に基づいています。その概念に慣れていない場合は、まずそれを読んでから、ここに戻ってください。 -(訳注：この文書で言う、「同期のとれていない git ブランチ」とは、master ブランチに関する、この「コミットしない」方針を逸脱して、QMK の master リポジトリに存在しないコミットがあなたのフォークの master ブランチに入っている状態を指します。) - -## あなた自身の `master` ブランチでの変更のバックアップ（オプション） - -救えるものなら自分の行った変更を失いたくはないでしょう。 -あなたの `master` ブランチに既に加えた変更を保存したい場合、最も簡単な方法は、単に「ダーティな」`master` ブランチの複製を作成することです： - -```sh -git branch old_master master -``` - -これで、 `master` ブランチの複製である `old_master` という名前のブランチができました。 - -## あなたのブランチの再同期 - -さあ、`master` ブランチを再同期します。 -この手順では、QMK のリポジトリを git のリモートリポジトリとして設定する必要があります。 -設定済みのリモートリポジトリを確認するには、`git remote -v` を実行し、次のような結果が返されなければなりません。 - -```sh -QMKuser ~/qmk_firmware (master) -$ git remote -v -origin https://github.com//qmk_firmware.git (fetch) -origin https://github.com//qmk_firmware.git (push) -upstream https://github.com/qmk/qmk_firmware.git (fetch) -upstream https://github.com/qmk/qmk_firmware.git (push) -``` - -もし、上記のようにならずに以下のように参照されるフォークが、1つだけ表示される場合： - -```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) -``` - -新しいリモートリポジトリを追加します： - -```sh -git remote add upstream https://github.com/qmk/qmk_firmware.git -``` - -次に、`origin` リモートリポジトリを、あなた自身のフォークにリダイレクトします： - -```sh -git remote set-url origin https://github.com/<あなたのユーザ名>/qmk_firmware.git -``` - -両方のリモートリポジトリが設定されたので、次を実行して、QMK である `upstream` リポジトリの参照を更新する必要があります。 - -```sh -git fetch upstream -``` - -この時点で、次を実行してあなたの(訳注：master)ブランチを QMK のブランチに再同期します。 -(訳注： 今現在 `master` ブランチがチェックアウトされていなければなりません。 - そうなってなければ、`git checkout master` を先に実行しておく必要があります。) - -```sh -git reset --hard upstream/master -``` - -これらの手順により、あなたのコンピュータ上のリポジトリが更新されますが、あなたの GitHub 上のフォークはまだ同期されていません。 -GitHub 上のフォークを再同期するには、あなたのフォークにプッシュして、ローカルリポジトリに反映されていないリモート変更をオーバーライドするように Git に指示する必要があります。 -これを行うには、次を実行します： - -```sh -git push --force-with-lease -``` - -!> 他のユーザーがコミットを投稿するフォークで `git push --force-with-lease` を**実行しないでください**。これをすると、かれらのコミットが消去されてしまいます。 - -これで、あなたの GitHub フォーク、あなたのローカルファイル、および QMK のリポジトリはすべて同じになりました。 -ここから、[ブランチを使って](ja/newbs_git_using_your_master_branch.md#making-changes)さらに必要な変更を加え、通常どおりそれらを投稿できます。 diff --git a/docs/ja/newbs_git_using_your_master_branch.md b/docs/ja/newbs_git_using_your_master_branch.md deleted file mode 100644 index 308a61eded..0000000000 --- a/docs/ja/newbs_git_using_your_master_branch.md +++ /dev/null @@ -1,101 +0,0 @@ -# あなたのフォークの master ブランチ: 更新は頻繁に、コミットはしないこと - - - -QMK の開発では、何がどこで行われているかにかかわらず、`master` ブランチを最新の状態に保つことを強くお勧めします、しかし `master` ブランチには***絶対に直接コミットしないでください***。 -代わりに、あなたのすべての変更は開発ブランチで行い、あなたが開発する時にはそのブランチからプルリクエストを発行します。 - -マージの競合 — これは 2人以上のユーザーがファイルの同じ部分をそれぞれ異なる編集をして統合できなくなった状態 — の可能性を減らすため `master` ブランチをなるべく最新の状態に保ち、新しいブランチを作成して新しい開発を開始します。 - -## あなたの master ブランチを更新する - -`master` ブランチを最新の状態に保つには、git のリモートリポジトリとして QMK ファームウェアのリポジトリ(以降、QMK リポジトリ)を追加することをお勧めします。 -これを行うには、Git コマンドラインインターフェイスを開き、次のように入力します。 - -``` -git remote add upstream https://github.com/qmk/qmk_firmware.git -``` - -?> `upstream`(訳注: `upstream` は`上流`という意味です)という名前は任意ですが、一般的な慣習です。 -QMK のリモートリポジトリには、あなたにとって分かりやすい名前を付けることができます。 -Git の `remote` コマンドは、構文 `git remote add ` を使用します。 -`` はリモートリポジトリの省略形としてあなたが指定するものです。 -この名前は、`fetch`、`pull`、`push` やそれ以外の多くの Git コマンドで、対象のリモートリポジトリを指定するために使用されます。 - -リポジトリが追加されたことを確認するには、`git remote -v` を実行します。 -次のように表示されます。 - -``` -$ git remote -v -origin https://github.com//qmk_firmware.git (fetch) -origin https://github.com//qmk_firmware.git (push) -upstream https://github.com/qmk/qmk_firmware.git (fetch) -upstream https://github.com/qmk/qmk_firmware.git (push) -``` - -これが完了すると、`git fetch upstream` を実行してリポジトリの更新を確認できます。 -このコマンドは `upstream` というニックネームを持つ QMK リポジトリから、ブランチとタグ — "refs" と総称されます — を取得します。 -これで、あなたのフォーク `origin` のデータを QMK が保持するデータと比較できます。 - -あなたのフォークの `master` を更新するには、次を実行します、各行の後に Enter キーを押してください: - -``` -git checkout master -git fetch upstream -git pull upstream master -git push origin master -``` - -これにより、あなたの `master` ブランチに切り替わり、QMK リポジトリから 'refs' を取得し、現在の QMK の `master` ブランチをコンピュータにダウンロードしてから、あなたのフォークにアップロードします。 - -## 変更を行なう :id=making-changes - -変更するには、以下を入力して新しいブランチを作成します: - -``` -git checkout -b dev_branch -git push --set-upstream origin dev_branch -``` - -これにより、`dev_branch` という名前の新しいブランチが作成され、チェックアウトされ、新しいブランチがあなたのフォークに保存されます。 -`--set-upstream` 引数は、このブランチから `git push` または `git pull` を使用するたびに、あなたのフォークと `dev_branch` ブランチを使用するように git に指示します。 -この引数は最初のプッシュでのみ使用する必要があります。 -その後、残りの引数なしで `git push` または `git pull` を安全に使用できます。 - -?> `git push` では、`-set-upstream` の代わりに `-u` を使用できます、 `-u` は `--set-upstream` のエイリアスです。 - -ブランチにはほぼ任意の名前を付けることができますが、あなたが行なう変更を表す名前を付けることをお勧めします。 - -デフォルトでは、`git checkout -b`は、今チェックアウトされているブランチに基づいて新しいブランチを作成します。 -コマンド末尾に既存のブランチの名前を追加指定することにより、チェックアウトされていない既存のブランチを基にして新しいブランチを作成できます: - -``` -git checkout -b dev_branch master -``` - -これで開発ブランチができたのでテキストエディタを開き必要な変更を加えます。 -ブランチに対して多くの小さなコミットを行うことをお勧めします。 -そうすることで、問題を引き起こす変更をより簡単に特定し必要に応じて元に戻すことができます。 -変更を加えるには、更新が必要なファイルを編集して保存し、Git の *ステージングエリア* に追加してから、ブランチにコミットします: - -``` -git add path/to/updated_file -git commit -m "My commit message." -``` - -`git add`は、変更されたファイルを Git の *ステージングエリア* に追加します。 -これは、Git の「ロードゾーン」です。 -これには、`git commit` によって *コミット* される変更が含まれており、リポジトリへの変更が保存されます。 -変更内容が一目でわかるように、説明的なコミットメッセージを使用します。 - -?> 複数のファイルを変更した場合、`git add -- path/to/file1 path/to/file2 ...` を実行すれば、あなたの望むファイルを追加できます。 - -## 変更を公開する - -最後のステップは、変更をフォークにプッシュすることです。 -これを行うには、`git push`と入力します。 -Git は、 `dev_branch`の現在の状態をフォークに公開します。 diff --git a/docs/ja/newbs_learn_more_resources.md b/docs/ja/newbs_learn_more_resources.md deleted file mode 100644 index 686b924465..0000000000 --- a/docs/ja/newbs_learn_more_resources.md +++ /dev/null @@ -1,63 +0,0 @@ -# 学習リソース - - - -これらのリソースは、QMK コミュニティの新しいメンバーに、初心者向けドキュメントで提供されている情報に対する理解を深めることを目的としています。 - -## QMK に関するリソース - -### 英語 :id=english-resources-qmk - -* [Thomas Baart's QMK Basics Blog](https://thomasbaart.nl/category/mechanical-keyboards/firmware/qmk/qmk-basics/) – 新規ユーザーの視点から見た QMK ファームウェアの使い方の基本を網羅した、ユーザー作成のブログ。 - -### 日本語 :id=japanese-resources-qmk - -_日本語のリソース情報を募集中です。_ - -## コマンドラインに関するリソース :id=command-line-resources - -### 英語 :id=english-resources-cli - -* [Good General Tutorial on Command Line](https://www.codecademy.com/learn/learn-the-command-line) -* [Must Know Linux Commands](https://www.guru99.com/must-know-linux-commands.html)
-* [Some Basic Unix Commands](https://www.tjhsst.edu/~dhyatt/superap/unixcmd.html) - -### 日本語 :id=japanese-resources-cli - -_日本語のリソース情報を募集中です。_ - -## テキストエディタに関するリソース :id=text-editor-resources - -どのテキストエディタを使えば良いか分かりませんか？ - -### 英語 :id=english-resources-text-editor - -* [a great introduction to the subject](https://learntocodewith.me/programming/basics/text-editors/) - -### 日本語 :id=japanese-resources-text-editor - -_日本語のリソース情報を募集中です。_ - -コーディング用に特別に作成されたエディタ: -* [Sublime Text](https://www.sublimetext.com/) -* [VS Code](https://code.visualstudio.com/) - -## Git に関するリソース - -### 英語 :id=english-resources-git - -* [Great General Tutorial](https://www.codecademy.com/learn/learn-git) -* [Flight Rules For Git](https://github.com/k88hudson/git-flight-rules) -* [Git Game To Learn From Examples](https://learngitbranching.js.org/) - -### 日本語 :id=japanese-resources-git - -_日本語のリソース情報を募集中です。_ - -* [Git Game To Learn From Examples(日本語対応有り)](https://learngitbranching.js.org/) - git のブランチの作り方、マージの仕方などがビジュアルに学べます。 -* [QMK で GitHub を使う方法](ja/getting_started_github.md) diff --git a/docs/ja/newbs_testing_debugging.md b/docs/ja/newbs_testing_debugging.md deleted file mode 100644 index d64f0f6dff..0000000000 --- a/docs/ja/newbs_testing_debugging.md +++ /dev/null @@ -1,15 +0,0 @@ -# テストとデバッグ - - - -## テスト - -[ここに移動しました](ja/faq_misc.md#testing) - -## デバッグ :id=debugging - -[ここに移動しました](ja/faq_debug.md#debugging) diff --git a/docs/ja/one_shot_keys.md b/docs/ja/one_shot_keys.md deleted file mode 100644 index f049c2d6f7..0000000000 --- a/docs/ja/one_shot_keys.md +++ /dev/null @@ -1,110 +0,0 @@ -# ワンショットキー - - - -ワンショットキーは次のキーが押されるまでアクティブのままになり、そのあと放されるキーです。これにより一度に1つ以上のキーを押すことなく、キーボードの組み合わせを入力することができます。これらのキーは通常「スティッキーキー」あるいは「デッドキー」と呼ばれます。 - -例えば、キーを `OSM(MOD_LSFT)` と定義する場合、最初にシフトを押して放し、続いて A を押して放すことで、大文字の A キャラクタを入力することができます。コンピュータには、シフトが押された瞬間にシフトが押し続けられ、A が放された後ですぐにシフトキーが放されるように見えます。 - -ワンショットキーは通常のモディファイアのようにも動作します。ワンショットキーを押しながら他のキーを入力すると、キーを放した直後にワンショットキーが解除されます。 - -さらに、短時間でキーを5回押すと、そのキーをロックします。これはワンショットモディファイアとワンショットレイヤーに適用され、`ONESHOT_TAP_TOGGLE` 定義によって制御されます。 - -`config.h` でこれらを定義することでワンショットキーの挙動を制御することができます: - -```c -#define ONESHOT_TAP_TOGGLE 5 /* この回数をタップすると、もう一度タップするまでキーが押されたままになります。*/ -#define ONESHOT_TIMEOUT 5000 /* ワンショットキーが解除されるまでの時間 (ms) */ -``` - -* `OSM(mod)` - *mod*を一時的に押し続けます。[モッドタップ](ja/mod_tap.md)で示したように、`KC_*` コードでは無く、`MOD_*` キーコードを使わなければなりません。 -* `OSL(layer)` - 一時的に*レイヤー*に切り替えます。 -* `OS_ON` - ワンショットキーをオンにします。 -* `OS_OFF` - ワンショットキーをオフにします。OSM は通常の mod キーのように機能し、OSL は `MO` キーのように機能します。 -* `OS_TOGG` - ワンショットキーの状態を切り替えます。 - -ワンショットキーをマクロあるいはタップダンスルーチンの一部として有効にしたい場合があります。 - -ワンショットレイヤーについては、キーを押した時に `set_oneshot_layer(LAYER, ONESHOT_START)` を呼び出し、キーを放した時に `clear_oneshot_layer_state(ONESHOT_PRESSED)` を呼び出す必要があります。ワンショットをキャンセルする場合は、`reset_oneshot_layer()` を呼び出してください。 - -ワンショットモッドについては、設定するためには `set_oneshot_mods(MOD_BIT(KC_*))` を呼び出し、キャンセルするためには `clear_oneshot_mods()` を呼び出す必要があります。 - -!> リモートデスクトップ接続で OSM 変換に問題がある場合は、設定を開いて「ローカル リソース」タブに移動し、キーボードセクションでドロップダウンを「このコンピューター」に変更することで修正することができます。これにより問題が修正され、OSM がリモートデスクトップ上で適切に動作するようになります。 - -## コールバック - -ワンショットキーを押す時にカスタムロジックを実行したい場合、実装を選択できる幾つかのコールバックがあります。例えば、LED を点滅させたり、音を鳴らしたりして、ワンショットキーの変化を示すことができます。 - -`OSM(mod)` のためのコールバックがあります。ワンショット修飾キーの状態が変更されるたびに呼び出されます: オンに切り替わる時だけでなく、オフに切り替わる時にも呼び出されます。以下のように使うことができます: - -```c -void oneshot_mods_changed_user(uint8_t mods) { - if (mods & MOD_MASK_SHIFT) { - println("Oneshot mods SHIFT"); - } - if (mods & MOD_MASK_CTRL) { - println("Oneshot mods CTRL"); - } - if (mods & MOD_MASK_ALT) { - println("Oneshot mods ALT"); - } - if (mods & MOD_MASK_GUI) { - println("Oneshot mods GUI"); - } - if (!mods) { - println("Oneshot mods off"); - } -} -``` - -`mods` 引数は変更後のアクティブな mod が含まれるため、現在の状態が反映されます。 - -(`config.h` に `#define ONESHOT_TAP_TOGGLE 2` を追加して) ワンショットタップトグルを使う場合、指定された回数だけ修飾キーを押してロックすることができます。そのためのコールバックもあります: - -```c -void oneshot_locked_mods_changed_user(uint8_t mods) { - if (mods & MOD_MASK_SHIFT) { - println("Oneshot locked mods SHIFT"); - } - if (mods & MOD_MASK_CTRL) { - println("Oneshot locked mods CTRL"); - } - if (mods & MOD_MASK_ALT) { - println("Oneshot locked mods ALT"); - } - if (mods & MOD_MASK_GUI) { - println("Oneshot locked mods GUI"); - } - if (!mods) { - println("Oneshot locked mods off"); - } -} -``` - -最後に、`OSL(layer)` ワンショットキーのためのコールバックもあります: - -```c -void oneshot_layer_changed_user(uint8_t layer) { - if (layer == 1) { - println("Oneshot layer 1 on"); - } - if (!layer) { - println("Oneshot layer off"); - } -} -``` - -いずれかのワンショットレイヤーがオフの場合、`layer` は 0 になります。ワンショットレイヤーの変更では無く、レイヤーの変更で何かを実行したい場合は、`layer_state_set_user` は使用するのに良いコールバックです。 - -独自のキーボードを作成している場合、`_kb` と同等の機能もあります: - -```c -void oneshot_locked_mods_changed_kb(uint8_t mods); -void oneshot_mods_changed_kb(uint8_t mods); -void oneshot_layer_changed_kb(uint8_t layer); -``` - -他のコールバックと同様に、更にカスタマイズを可能にするために `_user` バージョンを呼ぶようにしてください。 diff --git a/docs/ja/other_eclipse.md b/docs/ja/other_eclipse.md deleted file mode 100644 index 9290166198..0000000000 --- a/docs/ja/other_eclipse.md +++ /dev/null @@ -1,89 +0,0 @@ -# QMK 開発のための Eclipse セットアップ - - - -[Eclipse][1]は Java 開発のために広く使われているオープンソースの [統合開発環境](https://en.wikipedia.org/wiki/Integrated_development_environment) (IDE) ですが、他の言語および用途のためにカスタマイズできる拡張可能なプラグインシステムがあります。 - -Eclipse のような IDE の使用は、プレーンテキストエディタの使用よりも多くの利点をもたらします。例えば、次のような利点です。 -* インテリジェントなコード補完 -* コード内の便利なナビゲーション -* リファクタリングツール -* 自動ビルド (コマンドラインは不要) -* Git 用の GUI -* 静的なコード解析 -* デバッグ、コードフォーマット、呼び出し階層の表示などの多くのツール。 - -このページの目的は、AVR ソフトウェアの開発および QMK コードベースで作業するために、Eclipse をセットアップする方法を文章化することです。 - -このセットアップは現時点では Ubuntu 16.04 でのみテストされていることに注意してください。 - -# 前提条件 -## ビルド環境 -始める前に、チュートリアルの[セットアップ](ja/newbs_getting_started.md)のセクションに従う必要があります。特に、[`qmk compile` コマンド](ja/newbs_building_firmware.md#build-your-firmware)でファームウェアをビルドできなければなりません。 - -## Java -Eclipse は Java アプリケーションであるため、実行するには Java 8 以降をインストールする必要があります。JRE または JDK を選択できますが、Java 開発を行う場合は後者が役に立ちます。 - -# Eclipse とプラグインのインストール -Eclipse は用途に応じて[いくつかのフレーバー](https://www.eclipse.org/downloads/eclipse-packages/)で提供されます。AVR スタックを構成するパッケージは無いため、Eclipse CDT (C/C++ 開発ツール)から始め、必要なプラグインをインストールする必要があります。 - -## Eclipse CDT のダウンロードとインストール -システムに既に Eclipse CDT がある場合は、この手順をスキップできます。ただし、より良いサポートのために最新の状態に保つことをお勧めします。 - -別の Eclipse パッケージをインストールしている場合は、通常は[その上に CDT プラグインをインストール](https://eclipse.org/cdt/downloads.php)することができます。しかし、軽くして、作業中のプロジェクトに必要のないツールが乱雑にならないように、ゼロから再インストールすることをお勧めします。 - -インストールは非常に簡単です: [5 Steps to install Eclipse](https://eclipse.org/downloads/eclipse-packages/?show_instructions=TRUE) に従い、ステップ3で **Eclipse IDE for C/C++ Developers** を選択します。 - -あるいは、直接 [Eclipse IDE for C/C++ Developers をダウンロード](https://www.eclipse.org/downloads/eclipse-packages/)([現在のバージョンへの直接リンク](https://www.eclipse.org/downloads/packages/eclipse-ide-cc-developers/neonr))し、選択した場所にパッケージを解凍することもできます (これにより `eclipse` フォルダが作成されます)。 - -## 最初の起動 -インストールが完了したら、Launch ボタンをクリックします。(パッケージを手動で解凍した場合は、Eclipse をインストールしたフォルダを開き、`eclipse` 実行可能ファイルをダブルクリックします) - -Workspace 選択で入力を促された場合は、Eclipse メタデータと通常のプロジェクトを保持するディレクトリを選択します。**`qmk_firmware` ディレクトリを選択しないでください**。これはプロジェクトディレクトリになります。代わりに親フォルダを選択するか、(できれば空の)他のフォルダを選択します(まだ使用していない場合は、デフォルトで問題ありません)。 - -開始したら、右上の Workbench ボタンをクリックし、workbench ビューに切り替えます (下部に開始時のようこそ画面をスキップするためのチェックボックスもあります)。 - -## 必要なプラグインをインストール -注意: プラグインをインストールするごとに、Eclipse を再起動する必要はありません。全てのプラグインがインストールされたら単に1回再起動します。 - -### [The AVR Plugin](https://avr-eclipse.sourceforge.net/) -これは最も重要なプラグインで、Eclipse が AVR C コードを_理解_できるようになります。[更新サイトを使うための指示](https://avr-eclipse.sourceforge.net/wiki/index.php/Plugin_Download#Update_Site)に従い、未署名コンテンツのセキュリティ警告に同意します。 - -### [ANSI Escape in Console](https://marketplace.eclipse.org/content/ansi-escape-console) -このプラグインは QMK makefile によって生成された色付きビルド出力を適切に表示するために必要です。 - -1. Help > Eclipse Marketplace… を開きます -2. _ANSI Escape in Console_ を検索します -3. プラグインの Install ボタンをクリックします -4. 指示に従い、未署名コンテンツのセキュリティ警告に再度同意します。 - -両方のプラグインがインストールされたら、プロンプトに従って Eclipse を再起動します。 - -# QMK 用の Eclipse の設定 -## プロジェクトのインポート -1. File > New > Makefile Project with Existing Code をクリックします -2. 次の画面で: -* _Existing Code Location_ としてリポジトリをクローンしたディレクトリを選択します。 -* (オプション) プロジェクトに別の名前を付けます¹ 例えば _QMK_ あるいは _Quantum_; -* _AVR-GCC Toolchain_ を選択します; -* 残りをそのままにして、Finish をクリックします - -![Eclipse での QMK のインポート](https://i.imgur.com/oHYR1yW.png) - -3. これでプロジェクトがロードされインデックスされます。左側の _Project Explorer_ から、簡単にファイルを参照できます。 - -¹ カスタム名でプロジェクトをインポートすると問題が発生するかもしれません。正しく動作しない場合は、デフォルトのプロジェクト名 (つまり、ディレクトリの名前、おそらく `qmk_firmware`) のままにしてみてください。 - -## キーボードのビルド - -プロジェクトのデフォルトの make 対象を `all` から私たちが取り組んでいる特定のキーボードとキーマップの組み合わせ、例えば `kinesis/kint36:stapelberg` に変更します。このようにすると、プロジェクトのクリーニングやビルドのようなプロジェクト全体のアクションは迅速に完了し、長い時間がかかったり Eclipse が完全にロックしたりすることがなくなります。 - -1. プロジェクト内の editor タブへフォーカスします -2. `Project` > `Properties` ウィンドウを開き、`C/C++ Build` リストエントリを選択して、`Behavior` タブに切り替えます。 -3. 有効な全てのビルドのデフォルトの `Make build target` テキストフィールドを、`all` から例えば `kinesis/kint41:stapelberg` に変更します。 -4. `Project` > `Clean...` を選択して、セットアップが動作することを確認します。 - -[1]: https://en.wikipedia.org/wiki/Eclipse_(software) diff --git a/docs/ja/other_vscode.md b/docs/ja/other_vscode.md deleted file mode 100644 index 2b6e27bb0a..0000000000 --- a/docs/ja/other_vscode.md +++ /dev/null @@ -1,119 +0,0 @@ -# QMK 開発用の Visual Studio Code のセットアップ - - - -[Visual Studio Code](https://code.visualstudio.com/) (VS Code) は多くの異なるプログラミング言語をサポートするオープンソースのコードエディタです。 - -VS Code のようなフル機能のエディタの使用は、プレーンテキストエディタの使用よりも多くの利点をもたらします。例えば、次のような利点です。: -* インテリジェントなコード補完 -* コード内の便利なナビゲーション -* リファクタリングツール -* 自動ビルド (コマンドラインは不要) -* Git 用のグラフィカルなフロントエンド -* デバッグ、コードフォーマット、呼び出し階層の表示などの多くのツール - -このページの目的は、QMK ファームウェアを開発するために VS Code をセットアップする方法を文章化することです。 - -このガイドは Windows および Ubuntu 18.04 で必要な全てを構成する方法を説明します。 - -# VS Code のセットアップ -はじめに、全てのビルドツールをセットアップし、QMK ファームウェアをクローンする必要があります。まだ設定していない場合は、[セットアップ](ja/newbs_getting_started.md)に進んでください。 - -## Windows - -### 前提条件 - -* [Git for Windows](https://git-scm.com/download/win) (このリンクはインストーラを保存あるいは実行するように促します) - - 1. `Git LFS (Large File Support)` および `Check daily for Git for Windows updates` 以外の全てのオプションを無効にします。 - 2. デフォルトのエディタを `Use Visual Studio Code as Git's default editor` に設定します。 - 3. ここで使用すべきオプションなので、`Use Git from Git Bash only` オプションを選択します。 - 4. `Choosing HTTPS transport backend` については、どちらのオプションでも問題ありません。 - 5. `Checkout as-is, commit Unix-style line endings` オプションを選択します。QMK ファームウェアは Unix スタイルのコミットを使います。 - 6. 追加のオプションについては、デフォルトのオプションをそのままにします。 - - このソフトウェアは、VS Code での Git サポートに必要です。これを含めないことも可能ですが、これを使う方が簡単です。 - -* [Git Credential Manager for Windows](https://github.com/Microsoft/Git-Credential-Manager-for-Windows/releases) (オプション) - - このソフトウェアは、git 証明書、MFA、パーソナルアクセストークン生成のためのセキュアストレージを提供することで、Git のより良いサポートを提供します。 - - これは厳密には必要ありませんが、お勧めします。 - - -### VS Code のインストール - -1. [VS Code](https://code.visualstudio.com/) に進み、インストーラをダウンロードします -2. インストーラを実行します - -この項は非常に簡単です。ただし、正しく構成されていることを確認するために、しなければならない幾つかの設定があります。 - -### VS Code の設定 - -最初に、IntelliSense をセットアップする必要があります。これは厳密には必要ではありませんが、あなたの人生をずっと楽にします。これを行うには、QMK ファームウェアフォルダに `.vscode/c_cpp_properties.json` ファイルを作成する必要があります。これは全て手動で行うことができますが、ほとんどの作業は既に完了しています。 - -[このファイル](https://gist.github.com/drashna/48e2c49ce877be592a1650f91f8473e8) を取得して保存します。MSYS2 をデフォルトの場所にインストールしなかった、または WSL か LxSS を使っている場合、このファイルを編集する必要があります。 - -このファイルを保存したら、VS Code が既に実行中の場合はリロードする必要があります。 - -?> また、`.vscode` フォルダ に `extensions.json` および `settings.json` ファイルがあるはずです。 - - -次に、VSCode に統合ターミナルとして表示されるように、MSYS2 ウィンドウを設定します。これには多くの利点があります。ほとんどの場合で、エラー上で Ctrl + クリックするとこれらのファイルにジャンプできます。これによりデバッグがはるかに簡単になります。また、他のウィンドウへジャンプする必要が無いという点でも優れています。 - -1. ファイル > ユーザー設定 > > 設定 をクリックします。 -2. 右上の {} ボタンをクリックし、`settings.json` ファイルを開きます。 -3. ファイルの内容を以下のように設定します: - - ```json - { - "terminal.integrated.shell.windows": "C:\\msys64\\usr\\bin\\bash.exe", - "terminal.integrated.env.windows": { - "MSYSTEM": "MINGW64", - "CHERE_INVOKING": "1" - }, - "terminal.integrated.shellArgs.windows": [ - "--login" - ], - "terminal.integrated.cursorStyle": "line" - } - ``` - - ここに既に設定がある場合は、最初と最後の波括弧の間に全てを追加し、既存の設定を新しく追加された設定とカンマで区切ります。 - -?> MSYS2 を別のフォルダにインストールした場合は、`terminal.integrated.shell.windows` のパスをシステムの正しいパスに変更する必要があります。 - -4. Ctrl-` (Grave) を押して、ターミナルを起動するか、表示 > ターミナル (コマンド `workbench.action.terminal.toggleTerminal`)に進みます。まだターミナルが開いていない場合は、新しいターミナルが開きます。 - - これにより、ワークスペースフォルダ(つまり `qmk_firmware` フォルダ)でターミナルが起動し、キーボードをコンパイルすることができます。 - - -## 他の全てのオペレーティングシステム - -1. [VS Code](https://code.visualstudio.com/) に進み、インストーラをダウンロードします -2. インストーラを実行します -3. 以上です - -いいえ、本当に以上です。必要なパスはパッケージのインストール時に既に含まれています。現在のワークスペースのファイルを検出し、IntelliSense 用に解析する方がより良いです。 - -## プラグイン - -インストールした方が良い拡張が幾つかあります。 - -* [Git Extension Pack](https://marketplace.visualstudio.com/items?itemName=donjayamanne.git-extension-pack) - -これは QMK ファームウェアで Git を簡単に使用できる Git 関連ツールを多数インスールします。 -* [EditorConfig for VS Code](https://marketplace.visualstudio.com/items?itemName=EditorConfig.EditorConfig) - _[オプション]_ - QMK コーディング規約にコードを準拠させるのに役立ちます。 -* [GitHub Markdown Preview](https://marketplace.visualstudio.com/items?itemName=bierner.github-markdown-preview) - _[オプション]_ - VS Code の markdown プレビューを GithHub のようにします。 -* [VS Live Share Extension Pack](https://marketplace.visualstudio.com/items?itemName=MS-vsliveshare.vsliveshare-pack) - _[オプション]_ - この拡張により、他の誰かがあなたのワークスペースにアクセスし(あるいは、あなたが他の誰かのワークスペースにアクセスし)、手伝うことができます。あなたが問題を抱えており、他の誰かの助けが必要な場合に便利です。 - -いずれかの拡張機能をインストールしたら、再起動します。 - -# QMK 用の VS Code の設定 -1. ファイル > フォルダーを開く をクリックします -2. GitHub からクローンした QMK ファームウェアフォルダを開きます。 -3. ファイル > 名前を付けてワークスペースを保存... をクリックします - -これで、VS Code で QMK ファームウェアをコーディングする準備ができました。 diff --git a/docs/ja/pr_checklist.md b/docs/ja/pr_checklist.md deleted file mode 100644 index caab2b4d50..0000000000 --- a/docs/ja/pr_checklist.md +++ /dev/null @@ -1,145 +0,0 @@ -# PR チェックリスト - - - -これは、提出された PR を QMK の協力者がレビューする際に何をチェックするのかの非網羅的なチェックリストです。 - -これらの推奨事項に矛盾がある場合は、このドキュメントに対して [issue を開く](https://github.com/qmk/qmk_firmware/issues/new)か、[Discord](https://discord.gg/Uq7gcHh) の QMK コラボレータに連絡することをお勧めします。 - -## 一般的な PR - -- PRは、ソースリポジトリ上の `master` ではないブランチを使って提出する必要があります - - これは、あなたの PR にとって別のブランチをターゲットにするという意味ではなく、むしろ自分の master ブランチで作業をしていないという意味です - - もし PR の提出者が自分の `master` ブランチを使っている場合は、マージ後に ["git の使い方"](https://docs.qmk.fm/#/ja/newbs_git_using_your_master_branch) ページへのリンクが表示されます - (このドキュメントの最後にはメッセージの内容が含まれます) -- 新しく追加されたディレクトリとファイル名は小文字でなければなりません - - 上流のソースが元々大文字を使っていた場合 (ChibiOS や他のリポジトリからインポートしたファイルなど)、このルールは緩和されるかもしれません - - 十分な正当性がある場合 (既存のコアファイルとの整合性など) は、このルールを緩和することができます。 - - ボードデザイナーがキーボードの名前を大文字にした場合は、十分な正当性とはみとめられません -- すべての `*.c` および `*.h` ソースファイルの有効なライセンスヘッダ - - 一貫性のために GPL2/GPL3 が推奨されています - - 他のライセンスも許可されていますが、GPL と互換性があり、再配布が許可されていなければなりません。異なるライセンスを使うと、PR がマージされるのをほぼ確実に遅らせることになります -- QMK コードベースの「ベストプラクティス」に従う - - これは網羅的なリストではありませんし、時間が経つにつれて修正される可能性が高いです - - ヘッダファイルでは、`#ifndef` インクルードガードの代わりに `#pragma once` を使います - - 「旧式の」 GPIO/I2C/SPI 関数を使用しない - 正当な理由がない限り、QMK の抽象化を使用しなければなりません (怠惰は正当な理由にはなりません) - - タイミングの抽象化にも従う必要があります: - - `_delay_ms()` のかわりに `wait_ms()` を。(`#include ` も消します) - - `timer_read()` と `timer_read32()` など。 -- タイミング API は [timer.h](https://github.com/qmk/qmk_firmware/blob/master/platforms/timer.h) を参照してください - - 新しい抽象化が有用だと思う場合は、次のことをお勧めします: - - 機能が完成するまで自分のキーボードでプロトタイプを作成する - - Discord の QMK コラボレータと話し合う - - 個別のコア変更としてそれをリファクタリングする - - あなたのキーボードからそのコピーを削除する -- PR を開く前にリベースしてマージの競合をすべて修正します (ヘルプやアドバイスが必要な場合は、Discord で QMK コラボレータに連絡してください)。 - -## キーマップの PR - -- 特定のボードファイルをインクルードするよりも `#include QMK_KEYBOARD_H` を推奨します -- レイヤーは `#define` よりも `enum` が好まれます -- カスタムキーコードは `#define` ではなく `enum` が必要です。最初のエントリには `= SAFE_RANGE` が必要です -- LAYOUT マクロ呼び出しのパラメータの途中の改行ではバックスラッシュ(`\`)は不要です -- スペーシング（コンマまたはキーコードの最初の文字の配置など）に注意を払うと、見栄えの良いキーマップになります - -## キーボードの PR - -終了した PR（インスピレーションを得るために、以前のレビューコメントセットは、自分のレビューのピンポンをなくすのに役立ちます）: -https://github.com/qmk/qmk_firmware/pulls?q=is%3Apr+is%3Aclosed+label%3Akeyboard - -- `info.json` - - 有効な URL - - 有効なメンテナ - - Configurator で正しく表示されること（Ctrl + Shift + I を押してローカルファイルをプレビューし、高速入力をオンにして順序を確認する） -- `readme.md` - - 標準テンプレートがあること - - 書き込みコマンドが `:flash` で終わっていること - - 有効なハードウェアの入手方法へのリンク (手配線の場合を除く) -- プライベートな共同購入は問題ありませんが、一回限りのプロトタイプは疑問視されます。オープンソースの場合は、ファイルへのリンクを提供してください - - ボードをブートローダーモードにリセットする方法を明確に説明してください - - キーボードの写真、できれば PCB の写真も添付してください -- `rules.mk` - - `MIDI_ENABLE`、`FAUXCLICKY_ENABLE`、`HD44780_ENABLE` は削除されました - - `# Enable Bluetooth with the Adafruit EZ-Key HID` は `# Enable Bluetooth` に変更されました - - 機能の有効化に関する `(-/+サイズ)` コメントはなくなりました - - ブートローダが指定されている場合は、代替ブートローダのリストを削除します - - [mcu_selection.mk](https://github.com/qmk/qmk_firmware/blob/master/quantum/mcu_selection.mk)の同等の MCU と比較した場合、同じ値の場合、デフォルトの MCU パラメータの再定義がないこと -- キーボードの `config.h` - - `PRODUCT` 値に `MANUFACTURER` を繰り返さないでください - - `#define DESCRIPTION` は要りません - - マジックキーオプション、 MIDI オプション、HD44780 コンフィギュレーションは要りません - - ユーザー設定の設定可能な `＃define` はキーマップ `config.h` に移動する必要があります - - "`DEBOUNCING_DELAY`" の代りに "`DEBOUNCE`" を使います - - キーボードが QMK で起動するために最低限必要なコードが存在する必要があります - - マトリックスと重要なデバイスの初期化コード - - (カスタムキーコードや特別なアニメーションなど)商用キーボードの既存の機能をミラーリングする場合は、`default` ではないキーマップを使って処理する必要があります - - Vial 関連のファイルまたは変更は QMK ファームウェアで使用されないため受け入れられません (Vial 固有のコアコードは提出またはマージされていません) -- `keyboard.c` - - 空の `xxxx_xxxx_kb()` または他の weak-define のデフォルト実装関数が削除されていること - - コメントアウトされた関数も削除されていること - - `matrix_init_board()` などが `keyboard_pre_init_kb()` に移行されました。[keyboard_pre_init*](https://docs.qmk.fm/#/ja/custom_quantum_functions?id=keyboard_pre_init_-function-documentation) を参照してください - - カスタムマトリックスを使用する場合は、`CUSTOM_MATRIX = lite` を選択し、標準のデバウンスを許可します。[マトリックスコードの部分置き換え](https://docs.qmk.fm/#/ja/custom_matrix?id=lite) を参照してください - - 可能な場合は、独自の `led_update_*()` 実装よりも LED インジケータの[設定オプション](https://docs.qmk.fm/#/ja/feature_led_indicators?id=configuration-options)を優先してください。 -- `keyboard.h` - - 先頭に `#include "quantum.h"` を置きます - - `LAYOUT` マクロは、該当する場合は標準の定義を使用してください - - 該当する場合はコミュニティレイアウトマクロ名を使用します (`LAYOUT`/`LAYOUT_all`よりも優先されます) -- キーマップの `config.h` - - キーボードから `rules.mk` や `config.h` が重複していないこと -- `keymaps/default/keymap.c` - - `QMKBEST`/`QMKURL` が削除されていること - - `MO(_LOWER)`および `MO(_RAISE)`キーコードまたは同等のものを使用していて、キーマップに両方のキーを押したときに adjust レイヤーがある場合 - キーマップに直接 adjust レイヤーに入るキーコードがない場合（`MO(_ADJUST)`のように）次のように記述します... - ``` - layer_state_t layer_state_set_user(layer_state_t state) { - return update_tri_layer_state(state, _LOWER, _RAISE, _ADJUST); - } - ``` - ...キーマップの `process_record_user()` 内で `layer_on()`、 `update_tri_layer()` を手動で処理する代わりに。 -- default (および via) のキーマップは「素朴」でなければなりません。 - - 他のユーザーが独自のユーザー固有のキーマップを開発するための「クリーンな状態」として使用するための最低限のもの。 - - これらのキーマップでは標準のレイアウトが推奨されます（可能な場合） - - デフォルトのキーマップは VIA を有効にするべきではありません -- VIA の統合ドキュメント類には `via` という名前のキーマップが必要です。 -- PR の提出者は、同じ PR に機能を紹介する個人的な（または豪華な）キーマップを持たせることができますが、「デフォルト」のキーマップに埋め込むべきではありません -- PR の提出者はまた、既存の商用キーボードへ QMK を移植する場合、その商用製品の既存の機能を反映する「製造業者に一致する」キーマップを持つことができます -- PR に VIA の json ファイルを含めないでください。これらは QMK ファームウェアで使われないため QMK リポジトリに属しません -- それらは [VIA のキーボードリポジトリ](https://github.com/the-via/keyboards)に属します。 - - -さらに、ChibiOS に固有で: -- 既存の ChibiOS ボード定義を使用することを**強く**推奨します。 - - 多くの場合、同等の Nucleo ボードは、同じファミリの異なるフラッシュサイズまたはわずかに異なるモデルで使用できます。 - - 例：STM32L082KZ の場合、STM32L073RZ に類似しているため、rules.mkで `BOARD = ST_NUCLEO64_L073RZ` を使用できます。 - - QMK は ChibiOS のアップグレード時のメンテナンス負担が継続的に発生するため、可能な限りカスタムボード定義を持たないように移行しています。 -- ボードの定義が避けられない場合、`board.c` には標準の `__early_init()` (通常の ChibiOS ボードの定義と同じ) と空の `boardInit()` を実装しなければなりません。 - - Arm/ChibiOS [早期初期化](https:/docs.qmk.fm/#/ja/platformdev_chibios_earlyinit?id=board-init)を参照してください - - `__early_init()`は、`early_hardware_init_pre()` または `early_hardware_init_post()` で適切に置き換える必要があります - - `boardInit()` は `board_init()` に移行する必要があります - -## コアの PR - -- `develop` ブランチをターゲットにする必要があります。これは、その後、breaking change のタイムラインで `master` にマージされます。 -- その他の注意事項 TBD - - 投稿された変更の幅を考えると、コアはもっと主観的です - ---- - -## 注意事項 - -人々が自分の `master` ブランチを使用する場合、マージ後に以下を投稿します： - -``` -For future reference, we recommend against committing to your `master` branch as you've done here, because pull requests from modified `master` branches can make it more difficult to keep your QMK fork updated. It is highly recommended for QMK development – regardless of what is being done or where – to keep your master updated, but **NEVER** commit to it. Instead, do all your changes in a branch (branches are basically free in Git) and issue PRs from your branches when you're developing. - -There are instructions on how to keep your fork updated here: - -[**Best Practices: Your Fork's Master: Update Often, Commit Never**](https://docs.qmk.fm/#/newbs_git_using_your_master_branch) - -[Fixing Your Branch](https://docs.qmk.fm/#/newbs_git_resynchronize_a_branch) will walk you through fixing up your `master` branch moving forward. If you need any help with this just ask. - -Thanks for contributing! -``` - -## レビュープロセス - -一般的に、PR がマージの対象となる前に、意味のある(例えば、コードを検査した)2つ(またはそれ以上)の承認を確認したいと考えています。これらのレビューはコラボレータに限られません -- 時間を割いてくれるコミュニティメンバーは誰でも歓迎(奨励)されます。唯一の違いは、チェックマークが緑にならないことですが、それは問題ありません。 - -また、PR レビューは自由な時間に行われるものです。それは好意で行われるものなので、私たちはレビューに費やす時間に対して、報酬はうけとっていませんし埋め合わせもありません。そのため、私たちがあなたのプルリクエストに取り掛かるのには時間がかかります。家族や生活のことで PR に手が回らなくなることもあり、そして燃え尽き症候群は深刻な懸念です。QMK ファームウェアリポジトリは、毎月平均200件の PR が開かれ、200件の PR がマージされますので、しばらくお待ちください。 diff --git a/docs/ja/proton_c_conversion.md b/docs/ja/proton_c_conversion.md deleted file mode 100644 index 8f0c857cba..0000000000 --- a/docs/ja/proton_c_conversion.md +++ /dev/null @@ -1,98 +0,0 @@ -# キーボードを Proton C を使うように変更 - - - -Proton C は Pro Micro の差し替え可能品であるため、簡単に使用することができます。 -このページでは、キーボードを変換するための便利な自動化されたプロセスと、Pro Micro では利用できない Proton C の機能を利用したい場合の手動プロセスについて説明しています。 - -## 自動で変換 - -QMK で現在サポートされているキーボードが Pro Micro（または互換ボード）を使用しており、Proton C を使用したい場合は、以下のように make 引数に `CONVERT_TO_PROTON_C=yes` (または `CTPC=yes`) を追加することでファームウェアを生成することができます。 - - make 40percentclub/mf68:default CTPC=yes - -同じ引数をキーマップの `rules.mk` に追加しても同じことができます。 - -これは、次のように、`＃ifdef` を使用してコード内で使用できる `CONVERT_TO_PROTON_C` フラグを公開します。 - -```c -#ifdef CONVERT_TO_PROTON_C - // Proton C code -#else - // Pro Micro code -#endif -``` - -`PORTB/DDRB` などが定義されていないというエラーが発生した場合は、ARM と AVR の両方で機能する [GPIO 制御](ja/gpio_control.md) を使用するようにキーボードのコードを変換する必要があります。これは AVR ビルドにまったく影響を与えません。 - -Proton C には1つのオンボード LED(C13)しかなく、デフォルトでは TXLED(D5) がそれにマップされています。代わりに RXLED(B0) をそれにマッピングしたい場合は、`config.h` に次のように追加してください。 - - #define CONVERT_TO_PROTON_C_RXLED - -## 機能の変換 - -下記は ARM ボードに実装されているものに基づいたデフォルトです。 - -| 機能 | 説明 | -|--------------------------------------|------------------------------------------------------------------------------------| -| [オーディオ](ja/feature_audio.md) | 有効 | -| [RGB ライト](ja/feature_rgblight.md) | 無効 | -| [バックライト](feature_backlight.md) | ARM が自動コンフィギュレーションを提供できるようになるまで、[タスク駆動 PWM](ja/(feature_backlight.md#software-pwm-driver))が強制されます | -| USB ホスト (例えば USB-USB コンバータ) | 未サポート (USB ホストコードは AVR 固有のもので、現在 ARM ではサポートされていません。 | -| [分割キーボード](ja/feature_split_keyboard.md) | 部分的 - 有効にする機能に大きく依存します | - -## 手動で変換 - -`CTPC = yes` を指定せずに Proton C をネイティブで使用するには、`rules.mk` の `MCU`行を変更する必要があります： - -``` -MCU = STM32F303 -BOARD = QMK_PROTON_C -``` - -次の変数が存在する場合は削除します。 - -* `BOOTLOADER` -* `EXTRA_FLAGS` - -最後に、`config.h`のすべてのピン割り当てを STM32 上の同等のものに変換します。 - -| Pro Micro 左側| Proton C 左側 | | Proton C 右側 | Pro Micro 右側 | -|--------------|--------------|-|--------------|---------------| -| `D3` | `A9` | | 5v | RAW (5v) | -| `D2` | `A10` | | GND | GND | -| GND | GND | | FLASH | RESET | -| GND | GND | | 3.3v | Vcc 1 | -| `D1` | `B7` | | `A2` | `F4` | -| `D0` | `B6` | | `A1` | `F5` | -| `D4` | `B5` | | `A0` | `F6` | -| `C6` | `B4` | | `B8` | `F7` | -| `D7` | `B3` | | `B13` | `B1` | -| `E6` | `B2` | | `B14` | `B3` | -| `B4` | `B1` | | `B15` | `B2` | -| `B5` | `B0` | | `B9` | `B6` | -| `B0` (RX LED) | `C13` 2 | | `C13` 2 | `D5` (TX LED) | - -また、Proton C の拡張部分にあるいくつかの新しいピンを利用することもできます。 - -| 左側 | | 右側 | -|------|-|-------| -| `A4`3 | | `B10` | -| `A5`4 | | `B11` | -| `A6` | | `B12` | -| `A7` | | `A14`5 (SWCLK) | -| `A8` | | `A13`5 (SWDIO) | -| `A15` | | RESET6 | - -注釈: - -1. Pro Micro の Vcc は 3.3V または 5V にすることができます。 -2. Proton C のオンボード LED は、Pro Micro のように2つはありません、1つだけです。Pro Micro には、RX LED(`D5`) と TX LED(`B0`)があります。 -3. `A4` ピンは、スピーカーと共有されています。 -4. `A5` ピンは、スピーカーと共有されています。 -5. `A13` と `A14` ピンはハードウェアデバッグ (SWD) に使用されます。GPIO にも使えますが、最後に使ってください。 -6. RESET を 3.3V とショート(プルアップ)して MCU をリブートします。これは Pro Micro のようにブートローダモードにはならず、MCU をリセットするだけです。 diff --git a/docs/ja/quantum_keycodes.md b/docs/ja/quantum_keycodes.md deleted file mode 100644 index 0795520c6e..0000000000 --- a/docs/ja/quantum_keycodes.md +++ /dev/null @@ -1,20 +0,0 @@ -# Quantum キーコード - - - -Quantum キーコードにより、カスタムアクションを定義することなく、基本的なものが提供するものより簡単にキーマップをカスタマイズすることができます。 - -quantum 内の全てのキーコードは `0x0000` と `0xFFFF` の間の数値です。`keymap.c` の中では、関数やその他の特別な場合があるように見えますが、最終的には C プリプロセッサによってそれらは単一の4バイト整数に変換されます。QMK は標準的なキーコードのために `0x0000` から `0x00FF` を予約しています。これらは、`KC_A`、`KC_1` および `KC_LCTL` のようなキーコードで、USB HID 仕様で定義された基本的なキーです。 - -このページでは、高度な quantum 機能を実装するために使われる `0x00FF` と `0xFFFF` の間のキーコードを説明します。独自のカスタムキーコードを定義する場合は、それらもこの範囲に配置されます。 - -## QMK キーコード :id=qmk-keycodes - -| キー | エイリアス | 説明 | -|-----------------|---------|--------------------------------------------------------| -|`QK_BOOTLOADER` |`QK_BOOT`| 書き込みのために、キーボードを bootloader モードにする | -|`QK_DEBUG_TOGGLE`|`DB_TOGG`| デバッグモードの切り替え | -|`QK_CLEAR_EEPROM`|`EE_CLR` | キーボードの EEPROM (永続化メモリ) を再初期化する | diff --git a/docs/ja/ref_functions.md b/docs/ja/ref_functions.md deleted file mode 100644 index 61e3943edd..0000000000 --- a/docs/ja/ref_functions.md +++ /dev/null @@ -1,124 +0,0 @@ -# キーボードをより良くするための便利なコア関数のリスト - - - -QMK には、信じられないほど便利な、またはあなたが望んでいた機能を少し追加する、隠された関数がたくさんあります。特定の機能に固有の関数はそれぞれの機能のページにあるため、ここには含まれていません。 - -## (OLKB) トライレイヤー :id=olkb-tri-layers - -目的に応じて、実際に使うことができる別個の関数があります。 - -### `update_tri_layer(x, y, z)` - -最初は `update_tri_layer(x, y, z)` 関数です。この関数はレイヤー `x` と `y` の両方がオンになっているかどうかを調べます。両方ともオンの場合は、レイヤー `z` がオンになります。それ以外の場合、`x` と `y` の両方がオンではない(一方のみがオン、またはどちらもオンでない)場合は、レイヤー `z` をオフにします。 - -この関数は、この機能を持つ特定のキーを作成したいが、他のレイヤーのキーコードではそうしたくない場合に便利です。 - -#### 例 - -```c -bool process_record_user(uint16_t keycode, keyrecord_t *record) { - switch (keycode) { - case LOWER: - if (record->event.pressed) { - layer_on(_LOWER); - update_tri_layer(_LOWER, _RAISE, _ADJUST); - } else { - layer_off(_LOWER); - update_tri_layer(_LOWER, _RAISE, _ADJUST); - } - return false; - case RAISE: - if (record->event.pressed) { - layer_on(_RAISE); - update_tri_layer(_LOWER, _RAISE, _ADJUST); - } else { - layer_off(_RAISE); - update_tri_layer(_LOWER, _RAISE, _ADJUST); - } - return false; - } - return true; -} -``` - -### `update_tri_layer_state(state, x, y, z)` -もう1つの関数は `update_tri_layer_state(state, x, y, z)` です。この関数は [`layer_state_set_*` 関数](ja/custom_quantum_functions.md#layer-change-code)から呼び出されることを意図しています。これは、キーコードを使ってレイヤーを変更するたびに、これがチェックされることを意味します。したがって、`LT(layer, kc)` を使ってレイヤーを変更すると、同じレイヤーチェックが引き起こされます。 - -このメソッドの注意点は2つあります: -1. `x` および `y` レイヤーをオンにしないと、`z` レイヤーにアクセスできません。これは、レイヤー `z` のみをアクティブにしようとすると、このコードが実行され、使用前にレイヤー `z` がオフになるからです。 -2. レイヤーは最上位の番号から処理されるので、`z` は `x` や `y` よりも上位のレイヤーでなければなりません。そうでなければアクセスできない場合があります。 - -#### 例 - -```c -layer_state_t layer_state_set_user(layer_state_t state) { - return update_tri_layer_state(state, _LOWER, _RAISE, _ADJUST); -} -``` - -あるいは、すぐに値を「返す」必要はありません。複数のトライレイヤーを追加、あるいは追加の効果を追加する場合に便利です。 - -```c -layer_state_t layer_state_set_user(layer_state_t state) { - state = update_tri_layer_state(state, _LOWER, _RAISE, _ADJUST); - state = update_tri_layer_state(state, _RAISE, _SYMB, _SPECIAL); - return state; -} -``` - -## 永続的なデフォルトレイヤーの設定 - -デフォルトレイヤーを設定して、キーボードを取り外しても保持されるようにしたいですか？そうであれば、これがそのための関数です。 - -これを使うには、`set_single_persistent_default_layer(layer)` を使います。レイヤーに名前が定義されている場合は、代わりにそれを使うことができます (_QWERTY、_DVORAK、_COLEMAK など)。 - -これは、デフォルトレイヤーを設定し、永続設定が更新され、もし [オーディオ](ja/feature_audio.md) がキーボードで有効でデフォルトレイヤーの音が設定されている場合は、曲を再生します。 - -デフォルトレイヤーの音を設定するには、以下のように `config.h` ファイルに定義する必要があります。 - -```c -#define DEFAULT_LAYER_SONGS { SONG(QWERTY_SOUND), \ - SONG(COLEMAK_SOUND), \ - SONG(DVORAK_SOUND) \ - } -``` - - -?> [quantum/audio/song_list.h](https://github.com/qmk/qmk_firmware/blob/master/quantum/audio/song_list.h) に使用できる多くの定義済みの曲があります。 - -## キーボードのリセット - -使用できる `RESET` quantum キーコードがあります。ただし、キーを個別に押すのではなくマクロの一部としてリセットしたい場合は、そうすることができます。 - -そのためには、`reset_keyboard()` を関数またはマクロに追加すると、ブートローダがリセットされます。 - -## EEPROM (永続ストレージ)の消去 - -オーディオ、RGB アンダーグロー、バックライト、キーの動作に問題がある場合は、EEPROM (永続的な設定のストレージ)をリセットすることができます。EEPROM を強制的にリセットするには、[`EEP_RST` キーコード](ja/quantum_keycodes.md)あるいは[ブートマジック](ja/feature_bootmagic.md)機能を使います。それらのいずれも選択肢にない場合は、カスタムマクロを使って行うことができます。 - -EEPROM を消去するには、関数またはマクロから `eeconfig_init()` を実行し、ほとんどの設定をデフォルトにリセットします。 - -## タップランダムキー - -ランダムな文字をホストコンピュータに送信する場合は、`tap_random_base64()` 関数を使うことができます。これは[疑似乱数的に](https://en.wikipedia.org/wiki/Pseudorandom_number_generator)0から63の数字を選択し、その選択に基づいてキー押下を送信します。(0–25 は `A`–`Z`、26–51 は `a`–`z`、52–61 は `0`–`9`、62 は `+`、63 は `/`)。 - -?> 言うまでもないですが、これはランダムに Base64 キーあるいはパスワードを生成する暗号的に安全な方法では _ありません_。 - -## ソフトウェアタイマー - -タイマーを開始し、時間固有のイベントの値を読み取ることができます。以下は例です: - -```c -static uint16_t key_timer; -key_timer = timer_read(); - -if (timer_elapsed(key_timer) < 100) { - // 経過時間が 100ms 未満の場合に何かを行う -} else { - // 経過時間が 100ms 以上の場合に何かを行う -} -``` diff --git a/docs/ja/reference_configurator_support.md b/docs/ja/reference_configurator_support.md deleted file mode 100644 index aefd04dd8a..0000000000 --- a/docs/ja/reference_configurator_support.md +++ /dev/null @@ -1,200 +0,0 @@ -# QMK Configurator でのキーボードのサポート - - - -このページは [QMK Configurator](https://config.qmk.fm/) でキーボードを適切にサポートする方法について説明します。 - - -## Configurator がキーボードを理解する方法 - -Configurator がキーボードをどのように理解するかを理解するには、最初にレイアウトマクロを理解する必要があります。この演習では、17キーのテンキー PCB を想定します。これを `numpad` と呼びます。 - -``` -|---------------| -|NLk| / | * | - | -|---+---+---+---| -|7 |8 |9 | + | -|---+---+---| | -|4 |5 |6 | | -|---+---+---+---| -|1 |2 |3 |Ent| -|-------+---| | -|0 | . | | -|---------------| -``` - -?> レイアウトマクロの詳細については、[QMK の理解: マトリックススキャン](ja/understanding_qmk.md?id=matrix-scanning) と [QMK の理解: マトリックスから物理レイアウトへのマップ](ja/understanding_qmk.md?id=matrix-to-physical-layout-map) を見てください。 - -Configurator の API はキーボードの `.h` ファイルを `qmk_firmware/keyboards//.h` から読み取ります。numpad の場合、このファイルは `qmk_firmware/keyboards/numpad/numpad.h` です: - -```c -#pragma once - -#define LAYOUT( \ - k00, k01, k02, k03, \ - k10, k11, k12, k13, \ - k20, k21, k22, \ - k30, k31, k32, k33, \ - k40, k42 \ - ) { \ - { k00, k01, k02, k03 }, \ - { k10, k11, k12, k13 }, \ - { k20, k21, k22, KC_NO }, \ - { k30, k31, k32, k33 }, \ - { k40, KC_NO, k42, KC_NO } \ -} -``` - -QMK は `KC_NO` を使って、スイッチマトリックス内のスイッチがない場所を指定します。デバッグが必要な場合に、このセクションを読みやすくするために、`XXX`、`___`、`____` を略記として使うこともあります。通常は `.h` ファイルの先頭近くで定義されます: - -```c -#pragma once - -#define XXX KC_NO - -#define LAYOUT( \ - k00, k01, k02, k03, \ - k10, k11, k12, k13, \ - k20, k21, k22, \ - k30, k31, k32, k33, \ - k40, k42 \ - ) { \ - { k00, k01, k02, k03 }, \ - { k10, k11, k12, k13 }, \ - { k20, k21, k22, XXX }, \ - { k30, k31, k32, k33 }, \ - { k40, XXX, k42, XXX } \ -} -``` - -!> この使用方法はキーマップマクロと異なります。キーマップマクロはほとんど常に`KC_NO`については`XXXXXXX` (7つの大文字の X) を、`KC_TRNS` については `_______` (7つのアンダースコア)を使います。 - -!> ユーザの混乱を防ぐために、`KC_NO` を使うことをお勧めします。 - -レイアウトマクロは、キーボードに17個のキーがあり、4列それぞれが5行に配置されていることを Configurator に伝えます。スイッチの位置は、0から始まる `k` という名前が付けられています。キーマップからキーコードを受け取る上部セクションと、マトリックス内の各キーの位置を指定する下部セクションとが一致する限り、名前自体は実際には問題ではありません。 - -物理的なキーボードに似た形でキーボードを表示するには、それぞれのキーの物理的な位置とサイズをスイッチマトリックスに結びつけることを Configurator に伝える JSON ファイルを作成する必要があります。 - -## JSON ファイルのビルド - -JSON ファイルをビルドする最も簡単な方法は、[Keyboard Layout Editor](https://www.keyboard-layout-editor.com/) ("KLE") でレイアウトを作成することです。この Raw Data を QMK tool に入れて、Configurator が読み出して使用する JSON ファイルに変換します。KLE は numpad レイアウトをデフォルトで開くため、Getting Started の説明を削除し、残りを使います。 - -レイアウトが望み通りのものになったら、KLE の Raw Data タブに移動し、内容をコピーします: - -``` -["Num Lock","/","*","-"], -["7\nHome","8\n↑","9\nPgUp",{h:2},"+"], -["4\n←","5","6\n→"], -["1\nEnd","2\n↓","3\nPgDn",{h:2},"Enter"], -[{w:2},"0\nIns",".\nDel"] -``` - -このデータを JSON に変換するには、[QMK KLE-JSON Converter](https://qmk.fm/converter/) に移動し、Raw Data を Input フィールド に貼り付け、Convert ボタンをクリックします。しばらくすると、JSON データが Output フィールドに表示されます。内容を新しいテキストドキュメントにコピーし、ドキュメントに `info.json` という名前を付け、`numpad.h` を含む同じフォルダに保存します。 - -`keyboard_name` オブジェクトを使ってキーボードの名前を設定します。説明のために、各キーのオブジェクトを各行に配置します。これはファイルを人間が読みやすいものにするためのもので、Configurator の機能には影響しません。 - -```json -{ - "keyboard_name": "Numpad", - "url": "", - "maintainer": "qmk", - "tags": { - "form_factor": "numpad" - }, - "layouts": { - "LAYOUT": { - "layout": [ - {"label":"Num Lock", "x":0, "y":0}, - {"label":"/", "x":1, "y":0}, - {"label":"*", "x":2, "y":0}, - {"label":"-", "x":3, "y":0}, - {"label":"7", "x":0, "y":1}, - {"label":"8", "x":1, "y":1}, - {"label":"9", "x":2, "y":1}, - {"label":"+", "x":3, "y":1, "h":2}, - {"label":"4", "x":0, "y":2}, - {"label":"5", "x":1, "y":2}, - {"label":"6", "x":2, "y":2}, - {"label":"1", "x":0, "y":3}, - {"label":"2", "x":1, "y":3}, - {"label":"3", "x":2, "y":3}, - {"label":"Enter", "x":3, "y":3, "h":2}, - {"label":"0", "x":0, "y":4, "w":2}, - {"label":".", "x":2, "y":4} - ] - } - } -} -``` - -`layouts` オブジェクトにはキーボードの物理レイアウトを表すデータが含まれます。このオブジェクトには `LAYOUT` という名前のオブジェクトがあり、このオブジェクト名は `numpad.h` のレイアウトマクロの名前と一致する必要があります。`LAYOUT` オブジェクト自体には `layout` という名前のオブジェクトがあります。このオブジェクトにはキーボードの物理キーごとに 1つの JSON オブジェクトが以下の形式で含まれています: - -``` - キーの名前。Configurator では表示されません。 - | - | キーボードの左端からのキー単位での - | | キーの X 軸の位置。 - | | - | | キーボードの上端(奥側)からのキー単位での - | | | キーの Y 軸位置。 - ↓ ↓ ↓ -{"label":"Num Lock", "x":0, "y":0}, -``` - -一部のオブジェクトには、それぞれキーの幅と高さを表す `"w"` 属性キーと `"h"` 属性キーがあります。 - -?> `info.json` ファイルの詳細については、[`info.json` 形式](ja/reference_info_json.md) を参照してください。 - - -## Configurator がキーをプログラムする方法 - -Configurator の API は、指定されたレイアウトマクロと JSON ファイルを使って、特定のキーに関連付けられた各ビジュアルオブジェクトを順番に持つキーボードのビジュアル表現を作成します: - -| レイアウトマクロのキー | 使用される JSON オブジェクト | -:---: | :---- -| k00 | {"label":"Num Lock", "x":0, "y":0} | -| k01 | {"label":"/", "x":1, "y":0} | -| k02 | {"label":"*", "x":2, "y":0} | -| k03 | {"label":"-", "x":3, "y":0} | -| k10 | {"label":"7", "x":0, "y":1} | -| k11 | {"label":"8", "x":1, "y":1} | -| k12 | {"label":"9", "x":2, "y":1} | -| k13 | {"label":"+", "x":3, "y":1, "h":2} | -| k20 | {"label":"4", "x":0, "y":2} | -| k21 | {"label":"5", "x":1, "y":2} | -| k22 | {"label":"6", "x":2, "y":2} | -| k30 | {"label":"1", "x":0, "y":3} | -| k31 | {"label":"2", "x":1, "y":3} | -| k32 | {"label":"3", "x":2, "y":3} | -| k33 | {"label":"Enter", "x":3, "y":3, "h":2} | -| k40 | {"label":"0", "x":0, "y":4, "w":2} | -| k42 | {"label":".", "x":2, "y":4} | - -ユーザが Configurator で左上のキーを選択し、Num Lock を割り当てると、Configurator は最初のキーとして `KC_NUM` を持つキーマップを作成し、同様にキーマップが作成されます。`label` キーは使われません; それらは `info.json` ファイルをデバッグする時に特定のキーを識別するためのユーザの参照のためだけのものです。 - - -## 問題と危険 - -現在のところ、Configurator はキーの回転または ISO Enter などの長方形ではないキーをサポートしません。さらに、"行"から垂直方向にずれているキー、— 顕著な例として [TKC1800](https://github.com/qmk/qmk_firmware/tree/4ac48a61a66206beaf2fdd5f2939d8bbedd0004c/keyboards/tkc1800/) のような1800レイアウト上の矢印キー — は、 `info.json` ファイルの提供者によって調整されていない場合は、KLE-to-JSON コンバータを混乱させます。 - -### 回避策 - -#### 長方形ではないキー - -ISO Enter キーについては、QMK custom は幅 1.25u、高さ 2u の長方形のキーとして表示し、右端が英数字キーブロックの右端に揃うように配置されます。 - -![](https://i.imgur.com/JKngtTw.png) -*QMK Configurator によって描画される標準 ISO レイアウトの60%キーボード。* - -#### 垂直方向にずれたキー - -垂直方向にずれたキーについては、ずれていないかのように KLE で配置し、変換された JSON ファイルで必要に応じて Y 値を編集します。 - -![](https://i.imgur.com/fmDvDzR.png) -*矢印キーに適用される垂直方向のずれのない、Keyboard Layout Editor で描画された1800レイアウトのキーボード。* - -![](https://i.imgur.com/8beYMBR.png) -*キーボードの JSON ファイルで矢印キーを垂直方向にずらすために必要な変更を示す、Unix の diff ファイル。* diff --git a/docs/ja/reference_glossary.md b/docs/ja/reference_glossary.md deleted file mode 100644 index 06c7196123..0000000000 --- a/docs/ja/reference_glossary.md +++ /dev/null @@ -1,173 +0,0 @@ -# QMK 用語集 - - - -## ARM -Atmel、Cypress、Kinetis、NXP、ST、TI など多くの企業が生産する 32 ビット MCU のライン。 - -## AVR -[Atmel](https://www.microchip.com/) が生産する 8 ビット MCU のライン。AVR は TMK がサポートしていた元のプラットフォームでした。 - -## AZERTY -標準的な Français (フランス) キーボードレイアウト。キーボードの最初の6つのキーから命名されました。 - -## バックライト -キーボードのライトの総称。バックライトが一般的ですが、それだけではなく、キーキャップあるいはスイッチを通して光る LED の配列。 - -## Bluetooth -短距離のピアツーピア無線プロトコル。キーボード用のもっとも一般的なワイヤレスプロトコル。 - -## ブートローダ -MCU の保護領域に書き込まれる特別なプログラムで、MCU が独自のファームウェアを通常は USB 経由でアップグレードできるようにします。 - -## ブートマジック -よくあるキーの交換あるいは無効化など、様々なキーボードの挙動の変更をその場で実行できる機能。 - -## C -システムコードに適した低レベルプログラミング言語。QMK のほとんどのコードは C で書かれています。 - -## Colemak -人気が出始めている代替キーボードレイアウト。 - -## コンパイル -人間が読めるコードを MCU が実行できるマシンコードに変換するプロセス。 - -## Dvorak -1930年代に Dr. August Dvorak によって開発された代替キーボードレイアウト。Dvorak Simplified Keyboard の短縮形。 - -## 動的マクロ -キーボードに記録されたマクロで、キーボードのプラグを抜くか、コンピュータを再起動すると失われます。 - -* [動的マクロドキュメント](ja/feature_dynamic_macros.md) - -## Eclipse -多くの C 開発者に人気のある IDE。 - -* [Eclipse セットアップ手順](ja/other_eclipse.md) - -## ファームウェア -MCU を制御するソフトウェア - -## git -コマンドラインで使用されるバージョン管理ソフトウェア - -## GitHub -QMK プロジェクトのほとんどをホストする Web サイト。git、課題管理、および QMK の実行に役立つその他の機能を統合して提供します。 - -## ISP -インシステムプログラミング。外部ハードウェアと JTAG ピンを使って AVR チップをプログラミングする方法。 - -## hid_listen -キーボードからデバッグメッセージを受信するためのインタフェース。[QMK Flasher](https://github.com/qmk/qmk_flasher) あるいは [PJRC の hid_listen](https://www.pjrc.com/teensy/hid_listen.html) を使ってこれらのメッセージを見ることができます。 - -## キーコード -特定のキーを表す2バイトの数値。`0x00`-`0xFF` は[基本キーコード](ja/keycodes_basic.md)に使われ、`0x100`-`0xFFFF` は [Quantum キーコード](ja/quantum_keycodes.md) に使われます。 - -## キーダウン -キーが押された時に発生し、キーが放される前に完了するイベント。 - -## キーアップ -キーが放された時に発生するイベント。 - -## キーマップ -物理的なキーボードレイアウトにマップされたキーコードの配列。キーの押下およびリリース時に処理されます。 - -## レイヤー -1つのキーが複数の目的を果たすために使われる抽象化。最上位のアクティブなレイヤーが優先されます。 - -## リーダーキー -リーダーキーに続けて1, 2 あるいは3つのキーをタップすることで、キーの押下あるいは他の quantum 機能をアクティブにする機能。 - -* [リーダーキードキュメント](ja/feature_leader_key.md) - -## LED -発光ダイオード。キーボードの表示に使われる最も一般的なデバイス。 - -## Make -全てのソースファイルをコンパイルするために使われるソフトウェアパッケージ。キーボードファームウェアをコンパイルするために、様々なオプションを指定して `make` を実行します。 - -## マトリックス -MCU がより少ないピン数でキー押下を検出できるようにする列と行の配線パターン。マトリックスには多くの場合、NKRO を可能にするためのダイオードが組み込まれています。 - -## マクロ -単一のキーのみを押した後で、複数のキー押下イベント (HID レポート) を送信できる機能。 - -* [マクロドキュメント](ja/feature_macros.md) - -## MCU -マイクロコントロールユニット。キーボードを動かすプロセッサ。 - -## モディファイア -別のキーを入力する間押したままにして、そのキーのアクションを変更するキー。例として、Ctrl、Alt および Shift があります。 -(訳注：モディファイヤ、モディファイヤキー、修飾キーなど、訳語が統一されていませんが同じものです) - -## マウスキー -キーボードからマウスカーソルを制御し、クリックできる機能。 - -* [マウスキードキュメント](ja/feature_mouse_keys.md) - -## N キーロールオーバー (NKRO) -一度に任意の数のキーの押下を送信できるキーボードに当てはまる用語。 - -## ワンショットモディファイア -別のキーが放されるまで押されているかのように機能するモディファイア。キーを押している間に mod を押し続けるのではなく、mod を押してからキーを押すことができます。スティッキーキーまたはデッドキーとも呼びます。 - -## ProMicro -低コストの AVR 開発ボード。このデバイスのクローンは ebay で非常に安価(5ドル未満)に見つかることがありますが、多くの場合 pro micro の書き込みに苦労します。 - -## プルリクエスト -QMK にコードを送信するリクエスト。全てのユーザが個人のキーマップのプルリクエストを送信することを推奨します。 - -## QWERTY -標準の英語キーボードレイアウト。多くの場合、他の言語の標準レイアウトへのショートカット。キーボードの最初の6文字から命名されました。 - -## QWERTZ -標準的な Deutsche (ドイツ語) キーボードレイアウト。キーボードの最初の6文字から命名されました。 - -## ロールオーバー -キーが既に押されている間にキーを押すことを指す用語。似たものに 2KRO、6KRO、NKRO が含まれます。 - -## スキャンコード -単一のキーを表す USB 経由の HID レポートの一部として送信される1バイトの数値。これらの値は、[USB-IF](https://www.usb.org/) が発行する [HID Usage Tables](https://www.usb.org/sites/default/files/documents/hut1_12v2.pdf) に記載されています。 - -## スペースカデットシフト -左または右 shift を1回以上タップすることで、様々なタイプの括弧を入力できる特別な shift キーのセット。 - -* [スペースカデットシフトドキュメント](ja/feature_space_cadet_shift.md) - -## タップ -キーを押して放す。状況によってはキーダウンイベントとキーアップイベントを区別する必要がありますが、タップは常に両方を一度に指します。 - -## タップダンス -押す回数に基づいて、同じキーに複数のキーコードを割り当てることができる機能。 - -* [タップダンスドキュメント](ja/feature_tap_dance.md) - -## Teensy -手配線での組み立てによく用いられる低コストの AVR 開発ボード。halfkay ブートローダによって書き込みが非常に簡単になるために、数ドル高いにもかかわらず teensy がしばしば選択されます。 - -## アンダーライト -キーボードの下側を照らす LED の総称。これらの LED は通常 PCB の底面からキーボードが置かれている表面に向けて照らします。 - -## ユニコード -大規模なコンピュータの世界では、ユニコードは任意の言語で文字を表現するためのエンコード方式のセットです。QMK に関しては、様々な OS スキームを使ってスキャンコードの代わりにユニコードコードポイントを送信することを意味します。 - -* [ユニコードドキュメント](ja/feature_unicode.md) - -## 単体テスト -QMK に対して自動テストを実行するためのフレームワーク。単体テストは、変更が何も壊さないことを確信するのに役立ちます。 - -* [単体テストドキュメント](ja/unit_testing.md) - -## USB -ユニバーサルシリアルバス。キーボード用の最も一般的な有線インタフェース。 - -## USB ホスト (あるいは単にホスト) -USB ホストは、あなたのコンピュータ、またはキーボードが差し込まれているデバイスのことです。 - -# 探している用語が見つかりませんでしたか？ - -質問についての [issue を開いて](https://github.com/qmk/qmk_firmware/issues) 、質問した用語についてここに追加することができます。さらに良いのは、定義についてのプルリクエストを開くことです。:) diff --git a/docs/ja/reference_info_json.md b/docs/ja/reference_info_json.md deleted file mode 100644 index e6a71adc9d..0000000000 --- a/docs/ja/reference_info_json.md +++ /dev/null @@ -1,68 +0,0 @@ -# `info.json` - - - -このファイルは [QMK API](https://github.com/qmk/qmk_api) によって使われます。このファイルは [QMK Configurator](https://config.qmk.fm/) がキーボードの画像を表示するために必要な情報を含んでいます。ここにメタデータを設定することもできます。 - -このメタデータを指定するために、`qmk_firmware/keyboards/` の下の全てのレベルで `info.json` を作成することができます。これらのファイルは結合され、より具体的なファイルがそうではないファイルのキーを上書きします。つまり、メタデータ情報を複製する必要はありません。例えば、`qmk_firmware/keyboards/clueboard/info.json` は `manufacturer` および `maintainer` を指定し、`qmk_firmware/keyboards/clueboard/66/info.json` は Clueboard 66% についてのより具体的な情報を指定します。 - -## `info.json` の形式 - -`info.json` ファイルは設定可能な以下のキーを持つ JSON 形式の辞書です。全てを設定する必要はなく、キーボードに適用するキーだけを設定します。 - -* `keyboard_name` - * キーボードを説明する自由形式のテキスト文字列。 - * 例: `Clueboard 66%` -* `url` - * キーボードの製品ページ、[QMK.fm/keyboards](https://qmk.fm/keyboards) のページ、あるいはキーボードに関する情報を説明する他のページの URL。 -* `maintainer` - * メンテナの GitHub のユーザ名、あるいはコミュニティが管理するキーボードの場合は `qmk` -* `layouts` - * 物理的なレイアウト表現。詳細は以下のセクションを見てください。 - -### レイアウトの形式 - -`info.json` ファイル内の辞書の `layouts` 部分は、幾つかの入れ子になった辞書を含みます。外側のレイヤーは QMK レイアウトマクロで構成されます。例えば、`LAYOUT_ansi` あるいは `LAYOUT_iso`。 - -* `layout` - * 物理レイアウトを説明するキー辞書のリスト。詳細は次のセクションを見てください。 - -### キー辞書形式 - -レイアウトの各キー辞書は、キーの物理プロパティを記述します。 の Raw Code に精通している場合、多くの概念が同じであることが分かります。可能な限り同じキー名とレイアウトの選択を再利用しますが、keyboard-layout-editor とは異なって各キーはステートレスで、前のキーからプロパティを継承しません。 - -全てのキーの位置と回転は、キーボードの左上と、各キーの左上を基準にして指定されます。 - -* `x` - * **必須**: 水平軸でのキーの絶対位置(キー単位)。 -* `y` - * **必須**: 垂直軸でのキーの絶対位置(キー単位)。 -* `w` - * キー単位でのキーの幅。`ks` が指定された場合は無視されます。デフォルト: `1` -* `h` - * キー単位でのキーの高さ。`ks` が指定された場合は無視されます。デフォルト: `1` -* `r` - * キーを回転させる時計回りの角度。 -* `rx` - * キーを回転させる点の水平軸における絶対位置。デフォルト: `x` -* `ry` - * キーを回転させる点の垂直軸における絶対位置。デフォルト: `y` -* `ks` - * キー形状: キー単位で頂点を列挙することでポリゴンを定義します。 - * **重要**: これらはキーの左上からの相対位置で、絶対位置ではありません。 - * ISO Enter の例: `[ [0,0], [1.5,0], [1.5,2], [0.25,2], [0.25,1], [0,1], [0,0] ]` -* `label` - * マトリックス内のこの位置につける名前。 - * これは通常 PCB 上でこの位置にシルクスクリーン印刷されるものと同じ名前でなければなりません。 - -## メタデータはどのように公開されますか？ - -このメタデータは主に2つの方法で使われます: - -* Web ベースの configurator が動的に UI を生成できるようにする。 -* 新しい `make keyboard:keymap:qmk` ターゲットをサポートする。これは、このメタデータをファームウェアにバンドルして QMK Toolbox をよりスマートにします。 - -Configurator の作成者は、JSON API の使用に関する詳細について、[QMK Compiler](https://docs.api.qmk.fm/using-the-api) ドキュメントを参照することができます。 diff --git a/docs/ja/reference_keymap_extras.md b/docs/ja/reference_keymap_extras.md deleted file mode 100644 index fb9d167ae0..0000000000 --- a/docs/ja/reference_keymap_extras.md +++ /dev/null @@ -1,89 +0,0 @@ -# 言語固有のキーコード - - - -キーボードは多くの言語をサポートすることができます。ただし、それらはキーを押したことで生成される実際の文字を送信しません - 代わりに数字のコードを送信します。USB HID の仕様ではそれらは "usages" と呼ばれますが、キーボードの文脈では「スキャンコード」あるいは「キーコード」と呼ばれることが多いです。 -HID Keyboard/Keypad usage ページでは 256 未満の usage が定義されており、それらの一部は現在のオペレーティングシステムでは機能しません。では、この言語のサポートはどのようにして実現されるのでしょうか？ - -簡単に言うと、オペレーティングシステムはユーザが設定したキーボードレイアウトに基づいて受け取った usage を適切な文字にマップします。例えば、スウェーデン人がキーボードの `å` という文字が刻印されたキーを押すと、キーボードは *実際には* `[` のキーコードを送信します。 - -明らかにこれは混乱する可能性があるため、QMK は多くのキーボードレイアウトのために言語固有のキーコードのエイリアスを提供します。これらはそれだけでは何もしません - さらに OS の設定で対応するキーボードレイアウトを設定する必要があります。それらをキーマップのキーキャップラベルと考えてください。 - -これらを使うには、`keymap.c` で対応する [ヘッダファイル](https://github.com/qmk/qmk_firmware/tree/master/quantum/keymap_extras) を `#include` し、それらで定義されているキーコードを `KC_` プリフィクスの代わりに追加します: - -| レイアウト | ヘッダファイル | -|-----------------------------|----------------------------------| -| Canadian Multilingual (CSA) | `keymap_canadian_multilingual.h` | -| Croatian | `keymap_croatian.h` | -| Czech | `keymap_czech.h` | -| Danish | `keymap_danish.h` | -| Dutch (Belgium) | `keymap_belgian.h` | -| English (Ireland) | `keymap_irish.h` | -| English (UK) | `keymap_uk.h` | -| English (US International) | `keymap_us_international.h` | -| Estonian | `keymap_estonian.h` | -| Finnish | `keymap_finnish.h` | -| French | `keymap_french.h` | -| French (AFNOR) | `keymap_french_afnor.h` | -| French (BÉPO) | `keymap_bepo.h` | -| French (Belgium) | `keymap_belgian.h` | -| French (Switzerland) | `keymap_fr_ch.h` | -| French (macOS, ISO) | `keymap_french_osx.h` | -| German | `keymap_german.h` | -| German (Switzerland) | `keymap_german_ch.h` | -| German (macOS) | `keymap_german_osx.h` | -| German (Neo2)* | `keymap_neo2.h` | -| Greek* | `keymap_greek.h` | -| Hebrew* | `keymap_hebrew.h` | -| Hungarian | `keymap_hungarian.h` | -| Icelandic | `keymap_icelandic.h` | -| Italian | `keymap_italian.h` | -| Italian (macOS, ANSI) | `keymap_italian_osx_ansi.h` | -| Italian (macOS, ISO) | `keymap_italian_osx_iso.h` | -| Japanese | `keymap_jp.h` | -| Korean | `keymap_korean.h` | -| Latvian | `keymap_latvian.h` | -| Lithuanian (ĄŽERTY) | `keymap_lithuanian_azerty.h` | -| Lithuanian (QWERTY) | `keymap_lithuanian_qwerty.h` | -| Norwegian | `keymap_norwegian.h` | -| Polish | `keymap_polish.h` | -| Portuguese | `keymap_portuguese.h` | -| Portuguese (macOS, ISO) | `keymap_portuguese_osx_iso.h` | -| Portuguese (Brazil) | `keymap_br_abnt2.h` | -| Romanian | `keymap_romanian.h` | -| Russian* | `keymap_russian.h` | -| Serbian* | `keymap_serbian.h` | -| Serbian (Latin) | `keymap_serbian_latin.h` | -| Slovak | `keymap_slovak.h` | -| Slovenian | `keymap_slovenian.h` | -| Spanish | `keymap_spanish.h` | -| Spanish (Dvorak) | `keymap_spanish_dvorak.h` | -| Swedish | `keymap_swedish.h` | -| Turkish (F) | `keymap_turkish_f.h` | -| Turkish (Q) | `keymap_turkish_q.h` | - -言語固有でないものもありますが、QWERTY レイアウトを使っていない場合に役立ちます: - -| レイアウト | ヘッダファイル | -|---------------------|--------------------------| -| Colemak | `keymap_colemak.h` | -| Dvorak | `keymap_dvorak.h` | -| Dvorak (French) | `keymap_dvorak_fr.h` | -| Dvorak (Programmer) | `keymap_dvp.h` | -| Norman | `keymap_norman.h` | -| Plover* | `keymap_plover.h` | -| Plover (Dvorak)* | `keymap_plover_dvorak.h` | -| Steno* | `keymap_steno.h` | -| Workman | `keymap_workman.h` | -| Workman (ZXCVM) | `keymap_workman_zxcvm.h` | - -## Sendstring サポート - -デフォルトでは、`SEND_STRING()` は US ANSI キーボードレイアウトが設定されたと見なします。別のレイアウトを使っている場合は、キーマップで(上記のように)`#include "sendstring_*.h"` して、ASCII 文字をキーコードにマッピングするために使われるルックアップテーブルを上書きすることができます。 - -ここで注意すべき重要な点は、`SEND_STRING()` は [ASCII 文字](https://en.wikipedia.org/wiki/ASCII#Character_set) でのみ機能するということです。これは、ユニコード文字を含む文字列を渡すことができないことを意味します - 残念ながら、これには希望のレイアウトに存在する可能性のあるアクセント付き文字が含まれています。 -多くのレイアウトでは、Grave または Tilde などの特定の文字を[デッドキー](https://en.wikipedia.org/wiki/Dead_key)としてのみ使えるようにしています。そのため、デッドキーが次の文字と潜在的に結合されることを防ぐためには、送信したい文字列の中のデッドキーのすぐ後にスペースを追加する必要があります。 -ラテン語由来のアルファベットを使わない(例えば、ギリシャ語やロシア語のような)他のレイアウトには、Sendstring ヘッダーがありません。従って ASCII 文字セットのほとんどを入力する方法がありません。これらは上記で `*` でマークされています。 diff --git a/docs/ja/serial_driver.md b/docs/ja/serial_driver.md deleted file mode 100644 index 72071f4f7e..0000000000 --- a/docs/ja/serial_driver.md +++ /dev/null @@ -1,75 +0,0 @@ -# 'シリアル' ドライバ - - - -このドライバは[分割キーボード](ja/feature_split_keyboard.md) 機能に使います。 - -?> この文章でのシリアルは、UART/USART/RS485/RS232 規格の実装ではなく、**一度に1ビットの情報を送信するもの**として読まれるべきです。 - -このカテゴリの全てのドライバには以下の特徴があります: -* 1本の線上でデータと信号を提供 -* シングルマスタ、シングルスレーブに限定 - -## サポートされるドライバの種類 - -| | AVR | ARM | -|-------------------|--------------------|--------------------| -| bit bang | :heavy_check_mark: | :heavy_check_mark: | -| USART Half-duplex | | :heavy_check_mark: | - -## ドライバ設定 - -### Bitbang -デフォルトのドライバ。設定がない場合はこのドライバが想定されます。設定するには、以下を rules.mk に追加します: - -```make -SERIAL_DRIVER = bitbang -``` - -config.h を介してドライバを設定します: -```c -#define SOFT_SERIAL_PIN D0 // または D1, D2, D3, E6 -#define SELECT_SOFT_SERIAL_SPEED 1 // または 0, 2, 3, 4, 5 - // 0: 約 189kbps (実験目的のみ) - // 1: 約 137kbps (デフォルト) - // 2: 約 75kbps - // 3: 約 39kbps - // 4: 約 26kbps - // 5: 約 20kbps -``` - -#### ARM - -!> bitbang ドライバは bitbang WS2812 ドライバと接続の問題があります - -上記の一般的なオプションに加えて、halconf.h で `PAL_USE_CALLBACKS` 機能もオンにする必要があります。 - -### USART Half-duplex -通信が USART ハードウェアデバイスに送信される STM32 ボードが対象です。これにより高速で正確なタイミングを提供できることが利点です。このドライバの `SOFT_SERIAL_PIN` は、設定された USART TX ピンです。**TX ピンに適切なプルアップ抵抗が必要です**。設定するには、以下を rules.mk に追加します: - -```make -SERIAL_DRIVER = usart -``` - -config.h を介してハードウェアを設定します: -```c -#define SOFT_SERIAL_PIN B6 // USART TX ピン -#define SELECT_SOFT_SERIAL_SPEED 1 // または 0, 2, 3, 4, 5 - // 0: 約 460800 ボー - // 1: 約 230400 ボー (デフォルト) - // 2: 約 115200 ボー - // 3: 約 57600 ボー - // 4: 約 38400 ボー - // 5: 約 19200 ボー -#define SERIAL_USART_DRIVER SD1 // TX ピンの USART ドライバ。デフォルトは SD1 -#define SERIAL_USART_TX_PAL_MODE 7 // 「代替機能」 ピン。MCU の適切な値については、それぞれのデータシートを見てください。デフォルトは 7 -``` - -また、ChibiOS `SERIAL` 機能を有効にする必要があります: -* キーボードの halconf.h: `#define HAL_USE_SERIAL TRUE` -* キーボードの mcuconf.h: `#define STM32_SERIAL_USE_USARTn TRUE` (ここで、'n' は MCU で選択した USART のペリフェラル番号と一致) - -必要な構成は、`UART` 周辺機器ではなく、`SERIAL` 周辺機器であることに注意してください。 diff --git a/docs/ja/support.md b/docs/ja/support.md deleted file mode 100644 index 01c2d41d19..0000000000 --- a/docs/ja/support.md +++ /dev/null @@ -1,22 +0,0 @@ -# 助けを得る - - - -QMK に関して助けを得るための多くのリソースがあります。 - -コミュニティスペースに参加する前に[行動規範](https://qmk.fm/coc/)を読んでください。 - -## リアルタイムチャット - -何かについて助けが必要な場合は、迅速なサポートを受けるための最良の場所は、[Discord Server](https://discord.gg/Uq7gcHh) です。通常は誰かがオンラインで、非常に助けになる多くの人がいます。 - -## OLKB Subreddit - -公式の QMK フォーラムは [reddit.com](https://reddit.com) の [/r/olkb](https://reddit.com/r/olkb) です。 - -## GitHub Issues - -[GitHub で issue](https://github.com/qmk/qmk_firmware/issues) を開くことができます。issue は長期的な議論あるいはデバッグを必要とする場合は、特に便利です。 diff --git a/docs/ja/syllabus.md b/docs/ja/syllabus.md deleted file mode 100644 index 9209cb49e0..0000000000 --- a/docs/ja/syllabus.md +++ /dev/null @@ -1,76 +0,0 @@ -# QMK シラバス - - - -このページは最初に基本を紹介し、そして、QMK に習熟するために必要な全ての概念を理解するように導くことで、QMK の知識を構築するのに役立ちます。 - -# 初級トピック - -他に何も読んでいない場合は、このセクションのドキュメントを読んでください。[QMK 初心者ガイド](ja/newbs.md)を読み終わると、基本的なキーマップを作成し、それをコンパイルし、キーボードに書き込みできるようになっているはずです。残りのドキュメントはこれらの基本的な知識を具体的に肉付けします。 - -* **QMK Tools の使い方を学ぶ** - * [QMK 初心者ガイド](ja/newbs.md) - * [CLI](ja/cli.md) - * [Git](ja/newbs_git_best_practices.md) -* **キーマップについて学ぶ** - * [レイヤー](ja/feature_layers.md) - * [キーコード](ja/keycodes.md) - * 使用できるキーコードの完全なリスト。中級または上級トピックにある知識が必要な場合もあることに注意してください。 -* **IDE の設定** - オプション - * [Eclipse](ja/other_eclipse.md) - * [VS Code](ja/other_vscode.md) - -# 中級トピック - -これらのトピックでは、QMK がサポートする幾つかの機能について掘り下げます。これらのドキュメントを全て読む必要はありませんが、これらの一部をスキップすると、上級トピックのセクションの一部のドキュメントが意味をなさなくなるかもしれません。 - -* **機能の設定方法を学ぶ** - - * [オーディオ](ja/feature_audio.md) - * 電飾 - * [バックライト](ja/feature_backlight.md) - * [LED マトリックス](ja/feature_led_matrix.md) - * [RGB ライト](ja/feature_rgblight.md) - * [RGB マトリックス](ja/feature_rgb_matrix.md) - * [タップホールド設定](ja/tap_hold.md) -* **キーマップについてさらに学ぶ** - * [キーマップ](ja/keymap.md) - * [カスタム関数とキーコード](ja/custom_quantum_functions.md) - * マクロ - * [動的マクロ](ja/feature_dynamic_macros.md) - * [コンパイル済みのマクロ](ja/feature_macros.md) - * [タップダンス](ja/feature_tap_dance.md) - * [コンボ](ja/feature_combo.md) - * [ユーザスペース](ja/feature_userspace.md) - * [キーオーバーライド](ja/feature_key_overrides.md) - -# 上級トピック - -以下の全ては多くの基礎知識を必要とします。高度な機能を使ってキーマップを作成できることに加えて、`config.h` と `rules.mk` の両方を使ってキーボードのオプションを設定することに慣れている必要があります。 - -* **QMK 内のキーボードの保守** - * [キーボードの手配線](ja/hand_wire.md) - * [キーボードガイドライン](ja/hardware_keyboard_guidelines.md) - * [info.json リファレンス](ja/reference_info_json.md) - * [デバウンス API](ja/feature_debounce_type.md) -* **高度な機能** - * [ユニコード](ja/feature_unicode.md) - * [API](ja/api_overview.md) - * [ブートマジックライト](ja/feature_bootmagic.md) -* **ハードウェア** - * [キーボードがどのように動作するか](ja/how_keyboards_work.md) - * [キーボードマトリックスの仕組み](ja/how_a_matrix_works.md) - * [分割キーボード](ja/feature_split_keyboard.md) - * [速記](ja/feature_stenography.md) - * [ポインティングデバイス](ja/feature_pointing_device.md) -* **コア開発** - * [コーディング規約](ja/coding_conventions_c.md) - * [互換性のあるマイクロコントローラ](ja/compatible_microcontrollers.md) - * [カスタムマトリックス](ja/custom_matrix.md) - * [QMK を理解する](ja/understanding_qmk.md) -* **CLI 開発** - * [コーディング規約](ja/coding_conventions_python.md) - * [CLI 開発の概要](ja/cli_development.md) diff --git a/docs/ja/tap_hold.md b/docs/ja/tap_hold.md deleted file mode 100644 index c9d94d07ce..0000000000 --- a/docs/ja/tap_hold.md +++ /dev/null @@ -1,167 +0,0 @@ -# タップホールド設定オプション - - - -タップホールドオプションは素晴らしいものですが、問題が無いわけではありません。デフォルト設定を適切なものにしようとしましたが、一部の人にとってまだ問題を引き起こすかもしれません。 - -次のオプションによりタップホールドキーの挙動を変更することができます。 - -## タッピング時間 - -以下の機能の全ての核心は、タッピング時間の設定です。これにより、何をタップとし、何をホールドとするかが決まります。これが自然に感じられるぴったりのタイミングは、キーボードごと、スイッチごと、あるいはキーごとに異ることもありえます。 - -`config.h` に以下の設定を追加することで、この時間を全体的に設定することができます: - -```c -#define TAPPING_TERM 200 -``` - -この設定はミリ秒で定義され、デフォルトは 200ms です。これは大多数の人にとっての適切な平均値です。 - -この機能をより細かく制御するために、以下を `config.h` に追加することができます: -```c -#define TAPPING_TERM_PER_KEY -``` - -そして、以下の関数をキーマップに追加します: - -```c -uint16_t get_tapping_term(uint16_t keycode, keyrecord_t *record) { - switch (keycode) { - case SFT_T(KC_SPC): - return TAPPING_TERM + 1250; - case LT(1, KC_GRV): - return 130; - default: - return TAPPING_TERM; - } -} -``` - - -## 許容ホールド - -[PR#1359](https://github.com/qmk/qmk_firmware/pull/1359/) 以降、新しい `config.h` オプションがあります: - -```c -#define PERMISSIVE_HOLD -``` - -これは高速なタイピストや高い `TAPPING_TERM` 設定に対して、タップとホールドキー(モッドタップのような)の動作を向上させます。 - -モッドタップキーを押し、他のキーをタップ(押して放す)して、モッドタップキーを放すという動作の全てをタッピング時間内に行うと、両方のキーのタッピング機能が出力されます。 - -例えば: - -- `SFT_T(KC_A)` を押す -- `KC_X` を押す -- `KC_X` を放す -- `SFT_T(KC_A)` を放す - -通常、これら全てを `TAPPING_TERM` (デフォルト: 200ms) 内で行うと、ファームウェアとホストシステムによって `ax` として登録されます。許容ホールドを有効にすると、別のキーがタップされた場合にモッドタップキーを修飾キーと見なすように処理を変更し、 `X` (`SHIFT`+`x`) と登録されます。 - -この機能をより細かく制御するために、以下を `config.h` に追加することができます: - -```c -#define PERMISSIVE_HOLD_PER_KEY -``` - -そして、以下の関数をキーマップに追加します: - -```c -bool get_permissive_hold(uint16_t keycode, keyrecord_t *record) { - switch (keycode) { - case LT(1, KC_BSPC): - return true; - default: - return false; - } -} -``` - -## タッピング強制ホールド - -`タッピング強制ホールド` を有効にするには、以下を `config.h` に追加します: - -```c -#define TAPPING_FORCE_HOLD -``` - -タップの後でユーザがキーをホールドすると、ホールド機能がアクティブになるのではなく、デフォルトでタッピング機能が繰り返されます。これにより、デュアルロールキーのタッピング機能を自動繰り返しする機能を維持することができます。`TAPPING_FORCE_HOLD` は、デュアルロールキーをタップした後ホールドした場合、ユーザがホールド機能をアクティブにする機能を削除します。 - -例: - -- `SFT_T(KC_A)` を押す -- `SFT_T(KC_A)` を放す -- `SFT_T(KC_A)` を押す -- タッピング時間が終了するまで待ちます... -- `SFT_T(KC_A)` を放す - -デフォルトの設定では、最初に放したときに `a` が送信され、2回目の押下で `a` が送信され、コンピュータに自動リピート機能を作動させることができます。 - -`TAPPING_FORCE_HOLD` を使うと、2回目の押下は Shift として解釈され、それをタップして使った後ですぐに修飾キーとして使うことができます。 - -!> `TAPPING_FORCE_HOLD` はタッピングトグル(`TT` レイヤーキーコード、ワンショットタップトグルなど)を使うものをすべて破壊します。 - -この機能をより細かく制御するために、以下を `config.h` に追加することができます: - -```c -#define TAPPING_FORCE_HOLD_PER_KEY -``` - -そして、以下の関数をキーマップに追加します: - -```c -bool get_tapping_force_hold(uint16_t keycode, keyrecord_t *record) { - switch (keycode) { - case LT(1, KC_BSPC): - return true; - default: - return false; - } -} -``` - -## レトロタッピング - -`レトロタッピング`を有効にするには、以下を `config.h` に追加してください: - -```c -#define RETRO_TAPPING -``` - -他のキーを押さずにデュアルファンクションキーを押して放しても何も起こりません。レトロタッピングを有効にすると、他のキーを押さずにキーを放すと、元のキーコードがタッピング時間外であっても送信されます。 - -例えば、他のキーを押すことなく `LT(2, KC_SPACE)` を押したり放したりしても何も起こりません。これを有効にすると、代わりに `KC_SPACE` を送信します。 - -この機能をより細かく制御するために、以下を `config.h` に追加することができます: - -```c -#define RETRO_TAPPING_PER_KEY -``` - -そして、以下の関数をキーマップに追加します: - -```c -bool get_retro_tapping(uint16_t keycode, keyrecord_t *record) { - switch (keycode) { - case LT(2, KC_SPACE): - return true; - default: - return false; - } -} -``` - -## キー別の関数にキーレコードを含めるのはなぜですか？ - -「キー別」の関数全てにキーレコードを含んでいることに気付いたかもしれません。そしてなぜそうしたのか不思議に思っているかもしれません。 - -まぁ、それは単純に本当にカスタマイズのためです。ただし、具体的には、それはキーボードの配線方法によって異なります。例えば、各行が実際にキーボードのマトリックスの1行を使っている場合、キーコード全体をチェックする代わりに、`if (record->event.key.row == 3)` を使うほうが簡単かもしれません。これは、ホームキー行でタップホールドタイプのキーを使っている人にとって特に便利です。そのため、通常のタイピングを妨げないように微調整することができるのではないでしょうか。 - -## `*_kb` や `*_user` 関数が無いのはなぜですか？ - -QMK にある他の多くの関数とは異なり、quantum あるいはキーボードレベルの関数を持つ必要はありません (または理由さえありません)。ここではユーザレベルの関数だけが有用なため、そのようにマークする必要はありません。 diff --git a/docs/ja/translating.md b/docs/ja/translating.md deleted file mode 100644 index f7a273308a..0000000000 --- a/docs/ja/translating.md +++ /dev/null @@ -1,60 +0,0 @@ -# QMK ドキュメントを翻訳する - - - -ルートフォルダ (`docs/`) にある全てのファイルは英語でなければなりません - 他の全ての言語は、ISO 639-1 言語コードと、それに続く`-`と関連する国コードのサブフォルダにある必要があります。[一般的なもののリストはここで見つかります](https://www.andiamo.co.uk/resources/iso-language-codes/)。このフォルダが存在しない場合、作成することができます。翻訳された各ファイルは英語バージョンと同じ名前でなければなりません。そうすることで、正常にフォールバックできます。 - -`_summary.md` ファイルはこのフォルダの中に存在し、各ファイルへのリンクのリスト、翻訳された名前、言語フォルダに続くリンクが含まれている必要があります。 - -```markdown - * [QMK简介](zh-cn/getting_started_introduction.md) -``` - -他の docs ページへの全てのリンクにも、言語のフォルダが前に付いている必要があります。もしリンクがページの特定の部分(例えば、特定の見出し)への場合、以下のように見出しに英語の ID を使う必要があります: - -```markdown -[建立你的环境](zh-cn/newbs-getting-started.md#set-up-your-environment) - -## 建立你的环境 :id=set-up-your-environment -``` - -新しい言語の翻訳が完了したら、以下のファイルも修正する必要があります: - -* [`docs/_langs.md`](https://github.com/qmk/qmk_firmware/blob/master/docs/_langs.md) -各行は、[GitHub emoji shortcode](https://github.com/ikatyang/emoji-cheat-sheet/blob/master/README.md#country-flag) の形式で国フラグと、それに続く言語で表される名前を含む必要があります。 - - ```markdown - - [:cn: 中文](/zh-cn/) - ``` - -* [`docs/index.html`](https://github.com/qmk/qmk_firmware/blob/master/docs/index.html) -`placeholder` と `noData` の両方のオブジェクトは、文字列で言語フォルダの辞書エントリが必要です: - - ```js - '/zh-cn/': '没有结果!', - ``` - - サイドバーの「QMK ファームウェア」の見出しリンクを設定するために、`nameLink` オブジェクトも以下のように追加される必要があります: - - ```js - '/zh-cn/': '/#/zh-cn/', - ``` - - また、`fallbackLanguages` リストに言語フォルダを追加して、404 ではなく英語に適切にフォールバックするようにしてください: - - ```js - fallbackLanguages: [ - // ... - 'zh-cn', - // ... - ], - ``` - -## 翻訳のプレビュー - -ドキュメントのローカルインスタンスをセットアップする方法については、[ドキュメントのプレビュー](ja/contributing.md#previewing-the-documentation)を見てください - 右上の "Translations" メニューから新しい言語を選択することができるはずです。 - -作業に満足したら、遠慮なくプルリクエストを開いてください！ diff --git a/docs/ja/understanding_qmk.md b/docs/ja/understanding_qmk.md deleted file mode 100644 index 0e8c99e692..0000000000 --- a/docs/ja/understanding_qmk.md +++ /dev/null @@ -1,190 +0,0 @@ -# QMK のコードの理解 - - - -このドキュメントでは、QMK ファームウェアがどのように機能するかを非常に高いレベルから説明しようとしています。基本的なプログラミングの概念を理解していることを前提としていますが、(実例を示す必要がある場合を除き) C に精通していることを前提にはしていません。以下のドキュメントの基本的な知識があることを前提としています。 - -* [入門](ja/getting_started_introduction.md) -* [キーボードがどのように動作するか](ja/how_keyboards_work.md) -* [FAQ](ja/faq_general.md) - -## スタートアップ - -QMK は他のコンピュータプログラムと何ら変わりないと考えることができます。開始され、タスクを実行し、そして終了します。プログラムのエントリーポイントは、他の C プログラムと同様に、`main()` 関数です。ただし、QMK を初めて触る人は、`main()` 関数が複数の場所に現れるため、混乱するかもしれません。また、どれを見ればよいか分かりにくいかもしれません。 - -複数ある理由は、QMK は様々なプラットフォームをサポートするからです。最も一般的なプラットフォームは `lufa` です。これは atmega32u4 のような AVR プロセッサ上で実行されます。また、`chibios` および `vusb` もサポートします。 - -ここでは AVR プロセッサに焦点を当てます。これは `lufa` プラットフォームを使います。`main()` 関数は [tmk_core/protocol/lufa/lufa.c](https://github.com/qmk/qmk_firmware/blob/e1203a222bb12ab9733916164a000ef3ac48da93/tmk_core/protocol/lufa/lufa.c#L1028) にあります。関数にざっと目を通すと、(ホストへの USB も含めて)設定された全てのハードウェアが初期化され、プログラムのコア部分が [`while(1)`](https://github.com/qmk/qmk_firmware/blob/e1203a222bb12ab9733916164a000ef3ac48da93/tmk_core/protocol/lufa/lufa.c#L1069) で開始されることが分かります。これが[メインループ](#the-main-loop)です。 - -## メインループ - -コードのこの部分は、同じ命令セットを永久にループ処理するため、「メインループ」と呼ばれます。ここはキーボードに必要なことを実行させる関数を QMK が呼び出す場所です。一見、多くの機能を持つように見えるかもしれませんが、大抵の場合、コードは `#define` によって無効にされます。 - -``` - keyboard_task(); -``` - -ここで、全てのキーボードの固有の機能が実行されます。`keyboard_task()` のソースコードは [tmk_core/common/keyboard.c](https://github.com/qmk/qmk_firmware/blob/e1203a222bb12ab9733916164a000ef3ac48da93/tmk_core/common/keyboard.c#L216) にあり、マトリックスの変化を検知し、LED の状態をオンオフする責任があります。 - -`keyboard_task()` に以下を処理するコードがあります: - -* [マトリックスのスキャン](#matrix-scanning) -* マウスの処理 -* シリアルリンク -* ビジュアライザ -* キーボードの状態の LED (Caps Lock, Num Lock, Scroll Lock) - -#### マトリックスのスキャン - -マトリックスのスキャンはキーボードファームウェアのコアの機能です。これは今どのキーが押されているかを検知するプロセスであり、キーボードはこの機能を1秒間に何度も何度も実行します。ファームウェアの CPU 時間の 99% はマトリックスのスキャンに費やされていると言っても過言ではありません。 - -実際のマトリックスの検知には様々な方法がありますが、それはこのドキュメントの対象外です。マトリックスのスキャンをブラックボックスとして扱っても問題ありません。マトリックスの現在の状態を求めると、以下のようなデータ構造を取得します: - - -``` -{ - {0,0,0,0}, - {0,0,0,0}, - {0,0,0,0}, - {0,0,0,0}, - {0,0,0,0} -} -``` - -これは 4行x5列のテンキー(訳注: 5行x4列の間違いと思われます)のマトリックスを表す直接的な表現のデータ構造です。キーが押されると、マトリックス内のそのキーの位置が、 `0` ではなく `1` として返されます。 - -マトリックスのスキャンは1秒間に何度も実行されます。正確なレートは様々ですが、知覚できるような遅延を避けるために、秒間に少なくとも10回実行します。 - -##### マトリックスから物理的なレイアウトへのマップ - -キーボード上の各スイッチの状態が分かると、それをキーコードへマップする必要があります。QMK ではキーコードへのマップは C マクロを使うことで行われ、C マクロにより物理的なレイアウトの定義はキーコードの定義から分離されています。(訳注：「キーコードの定義」は「キーコードのマトリクス配列による定義」と思われる) - -キーボードレベルで、キーボードのマトリックスを物理キーにマップする C マクロ (一般的には、`LAYOUT()` という名前)を定義します。マトリックスにスイッチがない場所がある場合、このマクロを使って KC_NO を事前に埋め込むことができ、キーマップの定義を扱いやすくすることができます。以下は、テンキー用の `LAYOUT()` マクロです: - -```c -#define LAYOUT( \ - k00, k01, k02, k03, \ - k10, k11, k12, k13, \ - k20, k21, k22, \ - k30, k31, k32, k33, \ - k40, k42 \ -) { \ - { k00, k01, k02, k03, }, \ - { k10, k11, k12, k13, }, \ - { k20, k21, k22, KC_NO, }, \ - { k30, k31, k32, k33, }, \ - { k40, KC_NO, k42, KC_NO } \ -} -``` - -`LAYOUT()` マクロの2つ目のブロックが、上記のマトリックススキャン配列とどのように一致しているかに注目してください。このマクロはマトリックスのスキャン配列をキーコードにマップするものです。ただし、17キーのテンキーを見ると、マトリックスにはスイッチが置けるが、キーが大きいために実際にはスイッチが無い箇所が3つあることが分かります。これらのスペースに `KC_NO` を設定したので、キーマップ定義には必要ありません。 - -このマクロを使って、少し変わったマトリックスのレイアウト、例えば [Clueboard rev 2](https://github.com/qmk/qmk_firmware/blob/e1203a222bb12ab9733916164a000ef3ac48da93/keyboards/clueboard/66/rev2/rev2.h) を扱うこともできます。その説明はこのドキュメントの範囲外です。 - -##### キーコードの割り当て - -キーマップレべルでは、上記の `LAYOUT()` マクロを使って、物理的な場所からマトリックスの場所にマッピングします。以下のようになります: - -``` -const uint16_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] = { -[0] = LAYOUT( - KC_NUM, KC_PSLS, KC_PAST, KC_PMNS, \ - KC_P7, KC_P8, KC_P9, KC_PPLS, \ - KC_P4, KC_P5, KC_P6, \ - KC_P1, KC_P2, KC_P3, KC_PENT, \ - KC_P0, KC_PDOT) -} -``` - -これら全ての引数が、前のセクションの `LAYOUT()` マクロの前半とどのように一致しているかについて注目してください。このようにして、キーコードを取得して、それを前述のマトリックススキャンにマップします。 - -##### 状態変更の検知 - -上記のマトリックススキャンはある時点のマトリックスの状態を伝えますが、コンピュータは変更のみを知りたいだけで、現在の状態を気にしません。QMK は最後のマトリックススキャンの結果を格納し、このマトリックスから結果を比較して、いつキーが押されたか放されたかを決定します。 - -例を見てみましょう。キーボードスキャンループの途中に移動して、前のスキャンが以下のようになっていることがわかったとします: - -``` -{ - {0,0,0,0}, - {0,0,0,0}, - {0,0,0,0}, - {0,0,0,0}, - {0,0,0,0} -} -``` - -現在のスキャンが完了すると、以下のように見えるとします: - -``` -{ - {1,0,0,0}, - {0,0,0,0}, - {0,0,0,0}, - {0,0,0,0}, - {0,0,0,0} -} -``` - -キーマップと比較すると、押されたキーが KC_NUM であることが分かります。ここから、`process_record` 関数群を呼び出します。 - - - -##### Process Record - -`process_record()` 関数自体は一見簡単に見えますが、その内部は QMK の様々なレベルで機能を上書きするためのゲートウェイが隠されています。キーボード/キーマップレベルの機能について調べる必要があるときは、以下に列挙した一連のイベントを手引帳として使います。`rules.mk` またはほかの場所で設定されたオプションに応じて、最終的なファームウェアに以下の関数のサブセットのみが含まれます。 - -* [`void process_record(keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/e1203a222bb12ab9733916164a000ef3ac48da93/tmk_core/common/action.c#L172) - * [`bool process_record_quantum(keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/e1203a222bb12ab9733916164a000ef3ac48da93/quantum/quantum.c#L206) - * [このレコードをキーコードにマップする](https://github.com/qmk/qmk_firmware/blob/e1203a222bb12ab9733916164a000ef3ac48da93/quantum/quantum.c#L226) - * [`void velocikey_accelerate(void)`](https://github.com/qmk/qmk_firmware/blob/c1c5922aae7b60b7c7d13d3769350eed9dda17ab/quantum/velocikey.c#L27) - * [`void preprocess_tap_dance(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/e1203a222bb12ab9733916164a000ef3ac48da93/quantum/process_keycode/process_tap_dance.c#L119) - * [`bool process_key_lock(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/e1203a222bb12ab9733916164a000ef3ac48da93/quantum/process_keycode/process_key_lock.c#L62) - * [`bool process_clicky(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/e1203a222bb12ab9733916164a000ef3ac48da93/quantum/process_keycode/process_clicky.c#L79) - * [`bool process_haptic(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/2cee371bf125a6ec541dd7c5a809573facc7c456/drivers/haptic/haptic.c#L216) - * [`bool process_record_kb(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/e1203a222bb12ab9733916164a000ef3ac48da93/keyboards/clueboard/card/card.c#L20) - * [`bool process_record_user(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/e1203a222bb12ab9733916164a000ef3ac48da93/keyboards/clueboard/card/keymaps/default/keymap.c#L58) - * [`bool process_midi(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/e1203a222bb12ab9733916164a000ef3ac48da93/quantum/process_keycode/process_midi.c#L81) - * [`bool process_audio(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/e1203a222bb12ab9733916164a000ef3ac48da93/quantum/process_keycode/process_audio.c#L19) - * [`bool process_steno(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/e1203a222bb12ab9733916164a000ef3ac48da93/quantum/process_keycode/process_steno.c#L160) - * [`bool process_music(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/e1203a222bb12ab9733916164a000ef3ac48da93/quantum/process_keycode/process_music.c#L114) - * [`bool process_key_override(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/5a1b857dea45a17698f6baa7dd1b7a7ea907fb0a/quantum/process_keycode/process_key_override.c#L397) - * [`bool process_tap_dance(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/e1203a222bb12ab9733916164a000ef3ac48da93/quantum/process_keycode/process_tap_dance.c#L141) - * [`bool process_unicode_common(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/e1203a222bb12ab9733916164a000ef3ac48da93/quantum/process_keycode/process_unicode_common.c#L169) は、以下のいずれかを呼び出します: - * [`bool process_unicode(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/e1203a222bb12ab9733916164a000ef3ac48da93/quantum/process_keycode/process_unicode.c#L20) - * [`bool process_unicodemap(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/e1203a222bb12ab9733916164a000ef3ac48da93/quantum/process_keycode/process_unicodemap.c#L46) - * [`bool process_ucis(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/e1203a222bb12ab9733916164a000ef3ac48da93/quantum/process_keycode/process_ucis.c#L95) - * [`bool process_leader(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/e1203a222bb12ab9733916164a000ef3ac48da93/quantum/process_keycode/process_leader.c#L51) - * [`bool process_combo(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/e1203a222bb12ab9733916164a000ef3ac48da93/quantum/process_keycode/process_combo.c#L115) - * [`bool process_printer(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/e1203a222bb12ab9733916164a000ef3ac48da93/quantum/process_keycode/process_printer.c#L77) - * [`bool process_auto_shift(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/e1203a222bb12ab9733916164a000ef3ac48da93/quantum/process_keycode/process_auto_shift.c#L94) - * [Quantum 固有のキーコードを識別して処理する](https://github.com/qmk/qmk_firmware/blob/e1203a222bb12ab9733916164a000ef3ac48da93/quantum/quantum.c#L291) - -この一連のイベントの中の任意のステップで (`process_record_kb()` のような)関数は `false` を返して、以降の処理を停止することができます。 - -この呼び出しの後で、`post_process_record()` が呼ばれます。これはキーコードが通常処理された後に実行する必要がある追加のクリーンアップを処理するために使うことができます。 - -* [`void post_process_record(keyrecord_t *record)`]() - * [`void post_process_record_quantum(keyrecord_t *record)`]() - * [このレコードをキーコードにマップする]() - * [`void post_process_clicky(uint16_t keycode, keyrecord_t *record)`]() - * [`void post_process_record_kb(uint16_t keycode, keyrecord_t *record)`]() - * [`void post_process_record_user(uint16_t keycode, keyrecord_t *record)`]() - - diff --git a/docs/keycodes.md b/docs/keycodes.md index 9d722216a9..38ed5ab18d 100644 --- a/docs/keycodes.md +++ b/docs/keycodes.md @@ -1,12 +1,12 @@ # Keycodes Overview -When defining a [keymap](keymap.md) each key needs a valid key definition. This page documents the symbols that correspond to keycodes that are available to you in QMK. +When defining a [keymap](keymap) each key needs a valid key definition. This page documents the symbols that correspond to keycodes that are available to you in QMK. This is a reference only. Each group of keys links to the page documenting their functionality in more detail. -## Basic Keycodes :id=basic-keycodes +## Basic Keycodes {#basic-keycodes} -See also: [Basic Keycodes](keycodes_basic.md) +See also: [Basic Keycodes](keycodes_basic) |Key |Aliases |Description |Windows |macOS |Linux1| |------------------------|-------------------------------|---------------------------------------|-------------|-------------|-----------------| @@ -219,9 +219,9 @@ See also: [Basic Keycodes](keycodes_basic.md) 5. Skips the entire track in iTunes when tapped, seeks within the current track when held.
6. WMP does not recognize the Rewind key, but both alter playback speed in VLC. -## Quantum Keycodes :id=quantum-keycodes +## Quantum Keycodes {#quantum-keycodes} -See also: [Quantum Keycodes](quantum_keycodes.md#qmk-keycodes) +See also: [Quantum Keycodes](quantum_keycodes#qmk-keycodes) |Key |Aliases |Description | |-----------------|---------|-------------------------------------------------------------------------------------------------------------------------------------------------| @@ -231,9 +231,9 @@ See also: [Quantum Keycodes](quantum_keycodes.md#qmk-keycodes) |`QK_MAKE` | |Sends `qmk compile -kb (keyboard) -km (keymap)`, or `qmk flash` if shift is held. Puts keyboard into bootloader mode if shift & control are held | |`QK_REBOOT` |`QK_RBT` |Resets the keyboard. Does not load the bootloader | -## Audio Keys :id=audio-keys +## Audio Keys {#audio-keys} -See also: [Audio](feature_audio.md) +See also: [Audio](feature_audio) |Key |Aliases |Description | |-------------------------|---------|-------------------------------------------| @@ -253,9 +253,9 @@ See also: [Audio](feature_audio.md) |`QK_AUDIO_VOICE_NEXT` |`AU_NEXT`|Cycles through the audio voices | |`QK_AUDIO_VOICE_PREVIOUS`|`AU_PREV`|Cycles through the audio voices in reverse | -## Auto Shift :id=auto-shift +## Auto Shift {#auto-shift} -See also: [Auto Shift](feature_auto_shift.md) +See also: [Auto Shift](feature_auto_shift) |Key |Aliases |Description | |----------------------|---------|--------------------------------------------| @@ -266,9 +266,9 @@ See also: [Auto Shift](feature_auto_shift.md) |`QK_AUTO_SHIFT_OFF` |`AS_OFF` |Turns off the Auto Shift Function | |`QK_AUTO_SHIFT_TOGGLE`|`AS_TOGG`|Toggles the state of the Auto Shift feature | -## Autocorrect :id=autocorrect +## Autocorrect {#autocorrect} -See also: [Autocorrect](feature_autocorrect.md) +See also: [Autocorrect](feature_autocorrect) |Key |Aliases |Description | |-----------------------|---------|----------------------------------------------| @@ -276,9 +276,9 @@ See also: [Autocorrect](feature_autocorrect.md) |`QK_AUTOCORRECT_OFF` |`AC_OFF` |Turns off the Autocorrect feature. | |`QK_AUTOCORRECT_TOGGLE`|`AC_TOGG`|Toggles the status of the Autocorrect feature.| -## Backlighting :id=backlighting +## Backlighting {#backlighting} -See also: [Backlighting](feature_backlight.md) +See also: [Backlighting](feature_backlight) | Key | Aliases | Description | |---------------------------------|-----------|-------------------------------------| @@ -290,9 +290,9 @@ See also: [Backlighting](feature_backlight.md) | `QK_BACKLIGHT_DOWN` | `BL_DOWN` | Decrease the backlight level | | `QK_BACKLIGHT_TOGGLE_BREATHING` | `BL_BRTG` | Toggle backlight breathing | -## Bluetooth :id=bluetooth +## Bluetooth {#bluetooth} -See also: [Bluetooth](feature_bluetooth.md) +See also: [Bluetooth](feature_bluetooth) |Key |Aliases |Description | |---------------------|---------|----------------------------------------------| @@ -300,17 +300,17 @@ See also: [Bluetooth](feature_bluetooth.md) |`QK_OUTPUT_USB` |`OU_USB` |USB only | |`QK_OUTPUT_BLUETOOTH`|`OU_BT` |Bluetooth only | -## Caps Word :id=caps-word +## Caps Word {#caps-word} -See also: [Caps Word](feature_caps_word.md) +See also: [Caps Word](feature_caps_word) |Key |Aliases |Description | |---------------------|---------|------------------------------| |`QK_CAPS_WORD_TOGGLE`|`CW_TOGG`|Toggles Caps Word | -## Dynamic Macros :id=dynamic-macros +## Dynamic Macros {#dynamic-macros} -See also: [Dynamic Macros](feature_dynamic_macros.md) +See also: [Dynamic Macros](feature_dynamic_macros) |Key |Aliases |Description | |---------------------------------|---------|--------------------------------------------------| @@ -320,17 +320,17 @@ See also: [Dynamic Macros](feature_dynamic_macros.md) |`QK_DYNAMIC_MACRO_PLAY_2` |`DM_PLY2`|Replay Macro 2 | |`QK_DYNAMIC_MACRO_RECORD_STOP` |`DM_RSTP`|Finish the macro that is currently being recorded.| -## Grave Escape :id=grave-escape +## Grave Escape {#grave-escape} -See also: [Grave Escape](feature_grave_esc.md) +See also: [Grave Escape](feature_grave_esc) |Key |Aliases |Description | |-----------------|---------|------------------------------------------------------------------| |`QK_GRAVE_ESCAPE`|`QK_GESC`|Escape when pressed, ` when Shift or GUI are held| -## Joystick :id=joystick +## Joystick {#joystick} -See also: [Joystick](feature_joystick.md) +See also: [Joystick](feature_joystick) |Key |Aliases|Description| |-----------------------|-------|-----------| @@ -367,40 +367,40 @@ See also: [Joystick](feature_joystick.md) |`QK_JOYSTICK_BUTTON_30`|`JS_30`|Button 30 | |`QK_JOYSTICK_BUTTON_31`|`JS_31`|Button 31 | -## Key Lock :id=key-lock +## Key Lock {#key-lock} -See also: [Key Lock](feature_key_lock.md) +See also: [Key Lock](feature_key_lock) |Key |Description | |---------|--------------------------------------------------------------| |`QK_LOCK`|Hold down the next key pressed, until the key is pressed again| -## Layer Switching :id=layer-switching +## Layer Switching {#layer-switching} -See also: [Layer Switching](feature_layers.md#switching-and-toggling-layers) +See also: [Layer Switching](feature_layers#switching-and-toggling-layers) |Key |Description | |----------------|----------------------------------------------------------------------------------| |`DF(layer)` |Set the base (default) layer | |`MO(layer)` |Momentarily turn on `layer` when pressed (requires `KC_TRNS` on destination layer)| -|`OSL(layer)` |Momentarily activates `layer` until a key is pressed. See [One Shot Keys](one_shot_keys.md) for details. | -|`LM(layer, mod)`|Momentarily turn on `layer` (like MO) with `mod` active as well. Where `mod` is a mods_bit. Mods can be viewed [here](mod_tap.md). Example Implementation: `LM(LAYER_1, MOD_LALT)`| +|`OSL(layer)` |Momentarily activates `layer` until a key is pressed. See [One Shot Keys](one_shot_keys) for details. | +|`LM(layer, mod)`|Momentarily turn on `layer` (like MO) with `mod` active as well. Where `mod` is a mods_bit. Mods can be viewed [here](mod_tap). Example Implementation: `LM(LAYER_1, MOD_LALT)`| |`LT(layer, kc)` |Turn on `layer` when held, `kc` when tapped | |`TG(layer)` |Toggle `layer` on or off | |`TO(layer)` |Turns on `layer` and turns off all other layers, except the default layer | |`TT(layer)` |Normally acts like MO unless it's tapped multiple times, which toggles `layer` on | -## Leader Key :id=leader-key +## Leader Key {#leader-key} -See also: [Leader Key](feature_leader_key.md) +See also: [Leader Key](feature_leader_key) |Key |Description | |---------|------------------------| |`QK_LEAD`|Begins a leader sequence| -## LED Matrix :id=led-matrix +## LED Matrix {#led-matrix} -See also: [LED Matrix](feature_led_matrix.md) +See also: [LED Matrix](feature_led_matrix) |Key |Aliases |Description | |-------------------------------|---------|-----------------------------------| @@ -414,9 +414,9 @@ See also: [LED Matrix](feature_led_matrix.md) |`QK_LED_MATRIX_SPEED_UP` |`LM_SPDU`|Increase the animation speed | |`QK_LED_MATRIX_SPEED_DOWN` |`LM_SPDD`|Decrease the animation speed | -## Magic Keycodes :id=magic-keycodes +## Magic Keycodes {#magic-keycodes} -See also: [Magic Keycodes](keycodes_magic.md) +See also: [Magic Keycodes](keycodes_magic) |Key |Aliases |Description | |-------------------------------------|---------|--------------------------------------------------------------------------| @@ -456,9 +456,9 @@ See also: [Magic Keycodes](keycodes_magic.md) |`QK_MAGIC_EE_HANDS_LEFT` |`EH_LEFT`|Set the master half of a split keyboard as the left hand (for `EE_HANDS`) | |`QK_MAGIC_EE_HANDS_RIGHT` |`EH_RGHT`|Set the master half of a split keyboard as the right hand (for `EE_HANDS`)| -## MIDI :id=midi +## MIDI {#midi} -See also: [MIDI](feature_midi.md) +See also: [MIDI](feature_midi) |Key |Aliases |Description | |-------------------------------|------------------|---------------------------------| @@ -607,9 +607,9 @@ See also: [MIDI](feature_midi.md) |`QK_MIDI_PITCH_BEND_DOWN` |`MI_BNDD` |Bend pitch down | |`QK_MIDI_PITCH_BEND_UP` |`MI_BNDU` |Bend pitch up | -## Mouse Keys :id=mouse-keys +## Mouse Keys {#mouse-keys} -See also: [Mouse Keys](feature_mouse_keys.md) +See also: [Mouse Keys](feature_mouse_keys) |Key |Aliases |Description | |----------------|---------|---------------------------| @@ -630,9 +630,9 @@ See also: [Mouse Keys](feature_mouse_keys.md) |`KC_MS_ACCEL1` |`KC_ACL1`|Set mouse acceleration to 1| |`KC_MS_ACCEL2` |`KC_ACL2`|Set mouse acceleration to 2| -## Modifiers :id=modifiers +## Modifiers {#modifiers} -See also: [Modifier Keys](feature_advanced_keycodes.md#modifier-keys) +See also: [Modifier Keys](feature_advanced_keycodes#modifier-keys) |Key |Aliases |Description | |----------|----------------------------------|------------------------------------------------------| @@ -658,9 +658,9 @@ See also: [Modifier Keys](feature_advanced_keycodes.md#modifier-keys) |`KC_MEH` | |Left Control, Shift and Alt | |`KC_HYPR` | |Left Control, Shift, Alt and GUI | -## Mod-Tap Keys :id=mod-tap-keys +## Mod-Tap Keys {#mod-tap-keys} -See also: [Mod-Tap](mod_tap.md) +See also: [Mod-Tap](mod_tap) |Key |Aliases |Description | |-------------|-----------------------------------------------------------------|--------------------------------------------------------------| @@ -687,7 +687,7 @@ See also: [Mod-Tap](mod_tap.md) |`MEH_T(kc)` | |Left Control, Shift and Alt when held, `kc` when tapped | |`HYPR_T(kc)` |`ALL_T(kc)` |Left Control, Shift, Alt and GUI when held, `kc` when tapped - more info [here](https://brettterpstra.com/2012/12/08/a-useful-caps-lock-key/)| -## Tapping Term Keys :id=tapping-term-keys +## Tapping Term Keys {#tapping-term-keys} See also: [Dynamic Tapping Term](tap_hold#dynamic-tapping-term) @@ -697,9 +697,9 @@ See also: [Dynamic Tapping Term](tap_hold#dynamic-tapping-term) |`QK_DYNAMIC_TAPPING_TERM_UP` |`DT_UP` | Increases the current tapping term by `DYNAMIC_TAPPING_TERM_INCREMENT`ms (5ms by default) | |`QK_DYNAMIC_TAPPING_TERM_DOWN` |`DT_DOWN`| Decreases the current tapping term by `DYNAMIC_TAPPING_TERM_INCREMENT`ms (5ms by default) | -## RGB Lighting :id=rgb-lighting +## RGB Lighting {#rgb-lighting} -See also: [RGB Lighting](feature_rgblight.md) +See also: [RGB Lighting](feature_rgblight) |Key |Aliases |Description | |-------------------|----------|--------------------------------------------------------------------| @@ -722,9 +722,9 @@ See also: [RGB Lighting](feature_rgblight.md) |`RGB_MODE_GRADIENT`|`RGB_M_G` |Static gradient animation mode | |`RGB_MODE_RGBTEST` |`RGB_M_T` |Red,Green,Blue test animation mode | -## RGB Matrix Lighting :id=rgb-matrix-lighting +## RGB Matrix Lighting {#rgb-matrix-lighting} -See also: [RGB Matrix Lighting](feature_rgb_matrix.md) +See also: [RGB Matrix Lighting](feature_rgb_matrix) |Key |Aliases |Description | |-------------------|----------|--------------------------------------------------------------------------------------| @@ -740,9 +740,9 @@ See also: [RGB Matrix Lighting](feature_rgb_matrix.md) |`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| -## US ANSI Shifted Symbols :id=us-ansi-shifted-symbols +## US ANSI Shifted Symbols {#us-ansi-shifted-symbols} -See also: [US ANSI Shifted Symbols](keycodes_us_ansi_shifted.md) +See also: [US ANSI Shifted Symbols](keycodes_us_ansi_shifted) |Key |Aliases |Description| |------------------------|-------------------|-----------| @@ -768,9 +768,9 @@ See also: [US ANSI Shifted Symbols](keycodes_us_ansi_shifted.md) |`KC_RIGHT_ANGLE_BRACKET`|`KC_RABK`, `KC_GT` |`>` | |`KC_QUESTION` |`KC_QUES` |`?` | -## One Shot Keys :id=one-shot-keys +## One Shot Keys {#one-shot-keys} -See also: [One Shot Keys](one_shot_keys.md) +See also: [One Shot Keys](one_shot_keys) |Key |Aliases |Description | |--------------------|---------|----------------------------------| @@ -780,9 +780,9 @@ See also: [One Shot Keys](one_shot_keys.md) |`QK_ONE_SHOT_ON` |`OS_ON` |Turns One Shot keys on | |`QK_ONE_SHOT_OFF` |`OS_OFF` |Turns One Shot keys off | -## Programmable Button Support :id=programmable-button +## Programmable Button Support {#programmable-button} -See also: [Programmable Button](feature_programmable_button.md) +See also: [Programmable Button](feature_programmable_button) |Key |Aliases|Description | |---------------------------|-------|----------------------| @@ -819,18 +819,18 @@ See also: [Programmable Button](feature_programmable_button.md) |`QK_PROGRAMMABLE_BUTTON_31`|`PB_31`|Programmable button 31| |`QK_PROGRAMMABLE_BUTTON_32`|`PB_32`|Programmable button 32| -## Repeat Key :id=repeat-key +## Repeat Key {#repeat-key} -See also: [Repeat Key](feature_repeat_key.md) +See also: [Repeat Key](feature_repeat_key) |Keycode |Aliases |Description | |-----------------------|---------|-------------------------------------| |`QK_REPEAT_KEY` |`QK_REP` |Repeat the last pressed key | |`QK_ALT_REPEAT_KEY` |`QK_AREP`|Perform alternate of the last key | -## Space Cadet :id=space-cadet +## Space Cadet {#space-cadet} -See also: [Space Cadet](feature_space_cadet.md) +See also: [Space Cadet](feature_space_cadet) |Key |Aliases |Description | |----------------------------------------------|---------|----------------------------------------| @@ -842,9 +842,9 @@ See also: [Space Cadet](feature_space_cadet.md) |`QK_SPACE_CADET_RIGHT_ALT_PARENTHESIS_CLOSE` |`SC_RAPC`|Right Alt when held, `)` when tapped | |`QK_SPACE_CADET_RIGHT_SHIFT_ENTER` |`SC_SENT`|Right Shift when held, Enter when tapped| -## Swap Hands :id=swap-hands +## Swap Hands {#swap-hands} -See also: [Swap Hands](feature_swap_hands.md) +See also: [Swap Hands](feature_swap_hands) |Key |Aliases |Description | |-----------------------------|---------|----------------------------------------------------| @@ -857,9 +857,9 @@ See also: [Swap Hands](feature_swap_hands.md) |`QK_SWAP_HANDS_TAP_TOGGLE` |`SH_TT` |Momentary swap when held, toggle when tapped | |`QK_SWAP_HANDS_ONE_SHOT` |`SH_OS` |Turn on hand swap while held or until next key press| -## Unicode Support :id=unicode-support +## Unicode Support {#unicode-support} -See also: [Unicode Support](feature_unicode.md) +See also: [Unicode Support](feature_unicode) |Key |Aliases |Description | |----------------------------|---------|----------------------------------------------------------------| diff --git a/docs/keycodes_basic.md b/docs/keycodes_basic.md index c95accd79e..6ff422f89b 100644 --- a/docs/keycodes_basic.md +++ b/docs/keycodes_basic.md @@ -191,7 +191,9 @@ The basic set of keycodes are based on the [HID Keyboard/Keypad Usage Page (0x07 These keycodes are not part of the Keyboard/Keypad usage page. The `SYSTEM_` keycodes are found in the Generic Desktop page, and the rest are located in the Consumer page. -?> Some of these keycodes may behave differently depending on the OS. For example, on macOS, the keycodes `KC_MEDIA_FAST_FORWARD`, `KC_MEDIA_REWIND`, `KC_MEDIA_NEXT_TRACK` and `KC_MEDIA_PREV_TRACK` skip within the current track when held, but skip the entire track when tapped. +::: tip +Some of these keycodes may behave differently depending on the OS. For example, on macOS, the keycodes `KC_MEDIA_FAST_FORWARD`, `KC_MEDIA_REWIND`, `KC_MEDIA_NEXT_TRACK` and `KC_MEDIA_PREV_TRACK` skip within the current track when held, but skip the entire track when tapped. +::: |Key |Aliases |Description | |-----------------------|---------|--------------------| diff --git a/docs/keycodes_magic.md b/docs/keycodes_magic.md index 8470612345..746af5b5e4 100644 --- a/docs/keycodes_magic.md +++ b/docs/keycodes_magic.md @@ -1,4 +1,4 @@ -# Magic Keycodes :id=magic-keycodes +# Magic Keycodes {#magic-keycodes} **Magic Keycodes** are prefixed with `MAGIC_`, and allow you to access the functionality of the deprecated Bootmagic feature *after* your keyboard has initialized. To use the keycodes, assign them to your keymap as you would any other keycode. diff --git a/docs/keymap.md b/docs/keymap.md index b9c5da6be7..e371fd9ba5 100644 --- a/docs/keymap.md +++ b/docs/keymap.md @@ -3,7 +3,7 @@ QMK keymaps are defined inside a C source file. The data structure is an array of arrays. The outer array is a list of layer arrays while the inner layer array is a list of keys. Most keyboards define a `LAYOUT()` macro to help you create this array of arrays. -## Keymap and Layers :id=keymap-and-layers +## Keymap and Layers {#keymap-and-layers} In QMK, **`const uint16_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS]`** holds multiple **layers** of keymap information in **16 bit** data holding the **action code**. You can define **32 layers** at most. For trivial key definitions, the higher 8 bits of the **action code** are all 0 and the lower 8 bits holds the USB HID usage code generated by the key as **keycode**. @@ -27,7 +27,7 @@ Respective layers can be validated simultaneously. Layers are indexed with 0 to Sometimes, the action code stored in keymap may be referred as keycode in some documents due to the TMK history. -### Keymap Layer Status :id=keymap-layer-status +### Keymap Layer Status {#keymap-layer-status} The state of the Keymap layer is determined by two 32 bit parameters: @@ -137,7 +137,9 @@ After this you'll find the layer definitions. Typically you'll have one or more `keymaps[][MATRIX_ROWS][MATRIX_COLS]` in QMK holds the 16 bit action code (sometimes referred as the quantum keycode) in it. For the keycode representing typical keys, its high byte is 0 and its low byte is the USB HID usage ID for keyboard. -> TMK from which QMK was forked uses `const uint8_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS]` instead and holds the 8 bit keycode. +::: info +TMK from which QMK was forked uses `const uint8_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS]` instead and holds the 8 bit keycode. +::: #### Base Layer @@ -185,7 +187,7 @@ Some interesting things to note: This should have given you a basic overview for creating your own keymap. For more details see the following resources: -* [Keycodes](keycodes.md) -* [Keymap FAQ](faq_keymap.md) +* [Keycodes](keycodes) +* [Keymap FAQ](faq_keymap) We are actively working to improve these docs. If you have suggestions for how they could be made better please [file an issue](https://github.com/qmk/qmk_firmware/issues/new)! diff --git a/docs/mod_tap.md b/docs/mod_tap.md index 8b953d76b4..0008967c52 100644 --- a/docs/mod_tap.md +++ b/docs/mod_tap.md @@ -53,13 +53,13 @@ For convenience, QMK includes some Mod-Tap shortcuts to make common combinations ## Caveats -Currently, the `kc` argument of `MT()` is limited to the [Basic Keycode set](keycodes_basic.md), meaning you can't use keycodes like `LCTL()`, `KC_TILD`, or anything greater than `0xFF`. This is because QMK uses 16-bit keycodes, of which 3 bits are used for the function identifier, 1 bit for selecting right or left mods, and 4 bits to tell which mods are used, leaving only 8 bits for the keycode. Additionally, if at least one right-handed modifier is specified in a Mod-Tap, it will cause all modifiers specified to become right-handed, so it is not possible to mix and match the two - for example, Left Control and Right Shift would become Right Control and Right Shift. +Currently, the `kc` argument of `MT()` is limited to the [Basic Keycode set](keycodes_basic), meaning you can't use keycodes like `LCTL()`, `KC_TILD`, or anything greater than `0xFF`. This is because QMK uses 16-bit keycodes, of which 3 bits are used for the function identifier, 1 bit for selecting right or left mods, and 4 bits to tell which mods are used, leaving only 8 bits for the keycode. Additionally, if at least one right-handed modifier is specified in a Mod-Tap, it will cause all modifiers specified to become right-handed, so it is not possible to mix and match the two - for example, Left Control and Right Shift would become Right Control and Right Shift. -Expanding this would be complicated, at best. Moving to a 32-bit keycode would solve a lot of this, but would double the amount of space that the keymap matrix uses. And it could potentially cause issues, too. If you need to apply modifiers to your tapped keycode, [Tap Dance](feature_tap_dance.md#example-5-using-tap-dance-for-advanced-mod-tap-and-layer-tap-keys) can be used to accomplish this. +Expanding this would be complicated, at best. Moving to a 32-bit keycode would solve a lot of this, but would double the amount of space that the keymap matrix uses. And it could potentially cause issues, too. If you need to apply modifiers to your tapped keycode, [Tap Dance](feature_tap_dance#example-5-using-tap-dance-for-advanced-mod-tap-and-layer-tap-keys) can be used to accomplish this. You may also run into issues when using Remote Desktop Connection on Windows. Because these keycodes send key events faster than a human, Remote Desktop could miss them. To fix this, open Remote Desktop Connection, click on "Show Options", open the "Local Resources" tab, and in the keyboard section, change the drop down to "On this Computer". This will fix the issue, and allow the characters to work correctly. -It can also be mitigated by increasing [`TAP_CODE_DELAY`](config_options.md#behaviors-that-can-be-configured). +It can also be mitigated by increasing [`TAP_CODE_DELAY`](config_options#behaviors-that-can-be-configured). ## Intercepting Mod-Taps @@ -132,4 +132,4 @@ bool process_record_user(uint16_t keycode, keyrecord_t *record) { ## Other Resources -See the [Tap-Hold Configuration Options](tap_hold.md) for additional flags that tweak Mod-Tap behavior. +See the [Tap-Hold Configuration Options](tap_hold) for additional flags that tweak Mod-Tap behavior. diff --git a/docs/newbs.md b/docs/newbs.md index b4d1494794..10d043c3ed 100644 --- a/docs/newbs.md +++ b/docs/newbs.md @@ -6,19 +6,21 @@ QMK tries to put a lot of power into your hands by making easy things easy, and Not sure if your keyboard can run QMK? If it's a mechanical keyboard you built yourself chances are good it can. We support a [large number of hobbyist boards](https://qmk.fm/keyboards/). If your current keyboard can't run QMK there are a lot of choices out there for boards that do. -?> **Is This Guide For Me?**
-If the thought of programming intimidates you, please [take a look at our online GUI](newbs_building_firmware_configurator.md) instead. +::: tip +**Is This Guide For Me?**
+::: +If the thought of programming intimidates you, please [take a look at our online GUI](newbs_building_firmware_configurator) instead. ## Overview This guide is suitable for everyone who wants to build a keyboard firmware using the source code. If you are already a programmer you will find the process very familiar and easier to follow. There are 3 main sections to this guide: -1. [Setup Your Environment](newbs_getting_started.md) -2. [Building Your First Firmware](newbs_building_firmware.md) -3. [Flashing Firmware](newbs_flashing.md) +1. [Setup Your Environment](newbs_getting_started) +2. [Building Your First Firmware](newbs_building_firmware) +3. [Flashing Firmware](newbs_flashing) -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). +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](support). ## Additional Resources -Beyond this guide there are several resources you may find helpful while you learn QMK. We've collected them on the [Syllabus](syllabus.md) and [Learning Resources](newbs_learn_more_resources.md) pages. +Beyond this guide there are several resources you may find helpful while you learn QMK. We've collected them on the [Syllabus](syllabus) and [Learning Resources](newbs_learn_more_resources) pages. diff --git a/docs/newbs_building_firmware.md b/docs/newbs_building_firmware.md index de9217e9f0..5e6a4452df 100644 --- a/docs/newbs_building_firmware.md +++ b/docs/newbs_building_firmware.md @@ -10,7 +10,9 @@ Most people new to QMK only have 1 keyboard. You can set this keyboard as your d qmk config user.keyboard=clueboard/66/rev4 -?> The keyboard option is the path relative to the keyboard directory, the above example would be found in `qmk_firmware/keyboards/clueboard/66/rev4`. If you're unsure you can view a full list of supported keyboards with `qmk list-keyboards`. +::: tip +The keyboard option is the path relative to the keyboard directory, the above example would be found in `qmk_firmware/keyboards/clueboard/66/rev4`. If you're unsure you can view a full list of supported keyboards with `qmk list-keyboards`. +::: You can also set your default keymap name. Most people use their GitHub username like the keymap name from the previous steps: @@ -40,20 +42,24 @@ Open your `keymap.c` file in your text editor. Inside this file you'll find the This line indicates where the list of Layers begins. Below that you'll find lines containing `LAYOUT`, and these lines indicate the start of a layer. Below that line is the list of keys that comprise a particular layer. -!> When editing your keymap file be careful not to add or remove any commas. If you do, you will prevent your firmware from compiling and it may not be easy to figure out where the extra, or missing, comma is. +::: warning +When editing your keymap file be careful not to add or remove any commas. If you do, you will prevent your firmware from compiling and it may not be easy to figure out where the extra, or missing, comma is. +::: ## Customize The Layout To Your Liking How to complete this step is entirely up to you. Make the one change that's been bugging you, or completely rework everything. You can remove layers if you don't need all of them, or add layers up to a total of 32. There are a lot of features in QMK, explore the sidebar to the left under "Using QMK" to see the full list. To get you started here are a few of the easier to use features: -* [Basic Keycodes](keycodes_basic.md) -* [Quantum Keycodes](quantum_keycodes.md) -* [Grave/Escape](feature_grave_esc.md) -* [Mouse keys](feature_mouse_keys.md) +* [Basic Keycodes](keycodes_basic) +* [Quantum Keycodes](quantum_keycodes) +* [Grave/Escape](feature_grave_esc) +* [Mouse keys](feature_mouse_keys) -?> While you get a feel for how keymaps work, keep each change small. Bigger changes make it harder to debug any problems that arise. +::: tip +While you get a feel for how keymaps work, keep each change small. Bigger changes make it harder to debug any problems that arise. +::: -## Build Your Firmware :id=build-your-firmware +## Build Your Firmware {#build-your-firmware} When your changes to the keymap are complete you will need to build the firmware. To do so go back to your terminal window and run the compile command: @@ -75,4 +81,4 @@ Checking file size of planck_rev5_default.hex ## Flash Your Firmware -Move on to [Flashing Firmware](newbs_flashing.md) to learn how to write your new firmware to your keyboard. +Move on to [Flashing Firmware](newbs_flashing) to learn how to write your new firmware to your keyboard. diff --git a/docs/newbs_building_firmware_configurator.md b/docs/newbs_building_firmware_configurator.md index 20256e5f28..85522e405c 100644 --- a/docs/newbs_building_firmware_configurator.md +++ b/docs/newbs_building_firmware_configurator.md @@ -4,12 +4,14 @@ The [QMK Configurator](https://config.qmk.fm) is an online graphical user interface that generates QMK Firmware `.hex` or `.bin` files. -It should be noted that Configurator cannot produce firmwares for keyboards using a different controller than they were designed for, i.e. an RP2040 controller on a board designed for pro micro. You will have to use the command line [converters](https://docs.qmk.fm/#/feature_converters?id=supported-converters) for this. +It should be noted that Configurator cannot produce firmwares for keyboards using a different controller than they were designed for, i.e. an RP2040 controller on a board designed for pro micro. You will have to use the command line [converters](feature_converters#supported-converters) for this. Watch the [Video Tutorial](https://www.youtube.com/watch?v=-imgglzDMdY). Many people find that is enough information to start programming their own keyboard. The QMK Configurator works best with Chrome or Firefox. -!> **Note: Files from other tools such as Keyboard Layout Editor (KLE), or kbfirmware will not be compatible with QMK Configurator. Do not load them, do not import them. QMK Configurator is a DIFFERENT tool.** +::: warning +**Note: Files from other tools such as Keyboard Layout Editor (KLE), or kbfirmware will not be compatible with QMK Configurator. Do not load them, do not import them. QMK Configurator is a DIFFERENT tool.** +::: -Please refer to [QMK Configurator: Step by Step](configurator_step_by_step.md). +Please refer to [QMK Configurator: Step by Step](configurator_step_by_step). diff --git a/docs/newbs_building_firmware_workflow.md b/docs/newbs_building_firmware_workflow.md index a3cc53ad86..01c2e69032 100644 --- a/docs/newbs_building_firmware_workflow.md +++ b/docs/newbs_building_firmware_workflow.md @@ -1,8 +1,10 @@ # Building QMK with GitHub Userspace -This is an intermediate QMK tutorial to setup an out-of-tree build environment with a personal GitHub repository. It avoids using a fork of the QMK firmware to store and build your keymap within its source tree. Keymap files will instead be stored in your own personal GitHub repository, in [Userspace](https://docs.qmk.fm/#/feature_userspace) format, and built with an action workflow. Unlike the [default tutorial](https://docs.qmk.fm/#/newbs), this guide requires some familiarity with using Git. +This is an intermediate QMK tutorial to setup an out-of-tree build environment with a personal GitHub repository. It avoids using a fork of the QMK firmware to store and build your keymap within its source tree. Keymap files will instead be stored in your own personal GitHub repository, in [Userspace](feature_userspace) format, and built with an action workflow. Unlike the [default tutorial](newbs), this guide requires some familiarity with using Git. -?> **Is This Guide For Me?**
+::: tip +**Is This Guide For Me?**
+::: This is a lean setup to avoid space-consuming local build environment in your computer. Troubleshooting compile-time errors will be slower with commit uploads to GitHub for the compiler workflow. @@ -12,7 +14,7 @@ The following are required to get started: * [GitHub Account](https://github.com/new) * A working account is required to setup and host your repository for GitHub Actions to build QMK firmware. -* [Text editor](newbs_learn_more_resources.md#text-editor-resources) +* [Text editor](newbs_learn_more_resources#text-editor-resources) * You’ll need a program that can edit and save plain text files. The default editor that comes with many OS's does not save plain text files, so you'll need to make sure that whatever editor you chose does. * [Toolbox](https://github.com/qmk/qmk_toolbox) * A graphical program for Windows and macOS that allows you to both program and debug your custom keyboard. @@ -20,23 +22,25 @@ The following are required to get started: ## Environment Setup -?> If you are familiar with using [github.dev](https://docs.github.com/en/codespaces/the-githubdev-web-based-editor), you can skip to [step 2](#_2-create-github-repository) and commit the code files that follows directly on GitHub using the web-based VSCode editor. +::: tip +If you are familiar with using [github.dev](https://docs.github.com/en/codespaces/the-githubdev-web-based-editor), you can skip to [step 2](#_2-create-github-repository) and commit the code files that follows directly on GitHub using the web-based VSCode editor. +::: ### 1. Install Git A working Git client is required for your local operating system to commit and push changes to GitHub. - +::::tabs -### ** Windows ** +=== Windows QMK maintains a bundle of MSYS2, the CLI and all necessary dependencies including Git. Install [QMK MSYS](https://msys.qmk.fm/) with the latest release [here](https://github.com/qmk/qmk_distro_msys/releases/latest). Git will be part of the bundle. -### ** macOS ** +=== macOS Install Homebrew following the instructions on https://brew.sh. Git will be part of the bundle. -### ** Linux/WSL ** +=== Linux/WSL It's very likely that you already have Git installed. If not, use one of the following commands: @@ -48,7 +52,7 @@ It's very likely that you already have Git installed. If not, use one of the fol * Sabayon: `sudo equo install dev-vcs/git` * Gentoo: `sudo emerge dev-vcs/git` - +:::: ### 2. GitHub authentication @@ -74,7 +78,9 @@ echo "SRC += source.c" > ~/qmk_keymap/rules.mk echo "#include QMK_KEYBOARD_H" > ~/qmk_keymap/source.c ``` -?> For Windows user running MSYS, those commands will create the folder `qmk_keymap/` and its content in the `C:\Users\\qmk_keymap\` path location. +::: tip +For Windows user running MSYS, those commands will create the folder `qmk_keymap/` and its content in the `C:\Users\\qmk_keymap\` path location. +::: ### Add a JSON keymap @@ -85,11 +91,13 @@ Visit the [QMK Configurator](https://config.qmk.fm/#/) to create a keymap file: 3. Customise the key layout according to your preference. 4. Select download next to **KEYMAP.JSON** and save the JSON file into the `~/qmk_keymap/` folder. -!> **Important:** Make sure that the GitHub username you use in step 2 is correct. If it is not, the build process will fail to locate your files in the right folder. +::: warning +**Important:** Make sure that the GitHub username you use in step 2 is correct. If it is not, the build process will fail to locate your files in the right folder. +::: ### Add a GitHub Action workflow -Open the file `~/qmk_keymap/.github/workflows/build.yml` with your favorite [text editor](newbs_learn_more_resources.md#text-editor-resources), paste the following workflow content, and save it: +Open the file `~/qmk_keymap/.github/workflows/build.yml` with your favorite [text editor](newbs_learn_more_resources#text-editor-resources), paste the following workflow content, and save it: ```yml name: Build QMK firmware on: [push, workflow_dispatch] @@ -137,7 +145,9 @@ jobs: ``` Replace `username.json` with the JSON file name that was downloaded from [QMK Configurator](https://config.qmk.fm/#/) in the previous step. -!> Do note that the `build.yml` file requires ***proper indentation*** for every line. Incorrect spacing will trigger workflow syntax errors. +::: warning +Do note that the `build.yml` file requires ***proper indentation*** for every line. Incorrect spacing will trigger workflow syntax errors. +::: ### Commit files to GitHub @@ -162,7 +172,9 @@ git branch -M main git remote add origin https://github.com/gh-username/qmk_keymap.git git push -u origin main ``` -?> Use your GitHub personal access token at the password prompt. If you have setup SSH access, replace `https://github.com/gh-username/qmk_keymap.git` with `git@github.com:gh-username/qmk_keymap.git` in the remote origin command above. +::: tip +Use your GitHub personal access token at the password prompt. If you have setup SSH access, replace `https://github.com/gh-username/qmk_keymap.git` with `git@github.com:gh-username/qmk_keymap.git` in the remote origin command above. +::: ### Review workflow output @@ -173,12 +185,12 @@ Files committed to GitHub in the previous step will automatically trigger the wo 4. Successfully compiled firmware will be under the "**Artifacts**" section. 5. If there are build errors, review the job log for details. -Download and flash the firmware file into your keyboard using [QMK Toolbox](https://docs.qmk.fm/#/newbs_flashing?id=flashing-your-keyboard-with-qmk-toolbox). +Download and flash the firmware file into your keyboard using [QMK Toolbox](newbs_flashing#flashing-your-keyboard-with-qmk-toolbox). ## Customising your keymap -This setup and workflow relies on the QMK [Userspace](https://docs.qmk.fm/#/feature_userspace) feature. The build process will copy the QMK source codes and clone your repository into its `users/` folder in a container. You must adhere to the following guidelines when customising your keymaps: +This setup and workflow relies on the QMK [Userspace](feature_userspace) feature. The build process will copy the QMK source codes and clone your repository into its `users/` folder in a container. You must adhere to the following guidelines when customising your keymaps: * Keymap layout files must be retained in JSON format and cannot be converted to `keymap.c`. * User callback and functions (e.g. `process_record_user()`) can be placed in the `source.c` file. @@ -191,4 +203,6 @@ This setup and workflow relies on the QMK [Userspace](https://docs.qmk.fm/#/feat * Code changes will require Git commit into GitHub to trigger the build workflow. -?> See [GitHub Actions guide](https://docs.github.com/en/actions/learn-github-actions) to learn more about development workflow. +::: tip +See [GitHub Actions guide](https://docs.github.com/en/actions/learn-github-actions) to learn more about development workflow. +::: diff --git a/docs/newbs_external_userspace.md b/docs/newbs_external_userspace.md index 9bdf4b0b18..fdc998c37a 100644 --- a/docs/newbs_external_userspace.md +++ b/docs/newbs_external_userspace.md @@ -4,21 +4,29 @@ QMK Firmware now officially supports storing user keymaps outside of the normal External Userspace mirrors the structure of the main QMK Firmware repository, but only contains the keymaps that you wish to build. You can still use `keyboards//keymaps/` to store your keymaps, or you can use the `layouts//` system as before -- they're just stored external to QMK Firmware. -The build system will still honor the use of `users/` if you rely on the traditional QMK Firmware [userspace feature](feature_userspace.md) -- it's now supported externally too, using the same location inside the External Userspace directory. +The build system will still honor the use of `users/` if you rely on the traditional QMK Firmware [userspace feature](feature_userspace) -- it's now supported externally too, using the same location inside the External Userspace directory. Additionally, there is first-class support for using GitHub Actions to build your keymaps, allowing you to automatically compile your keymaps whenever you push changes to your External Userspace repository. -!> External Userspace is new functionality and may have issues. Tighter integration with the `qmk` command will occur over time. +::: warning +External Userspace is new functionality and may have issues. Tighter integration with the `qmk` command will occur over time. +::: -?> Historical keymap.json and GitHub-based firmware build instructions can be found [here](newbs_building_firmware_workflow.md). This document supersedes those instructions, but they should still function correctly. +::: tip +Historical keymap.json and GitHub-based firmware build instructions can be found [here](newbs_building_firmware_workflow). This document supersedes those instructions, but they should still function correctly. +::: ## Setting up QMK Locally -If you wish to build on your local machine, you will need to set up QMK locally. This is a one-time process, and is documented in the [newbs setup guide](https://docs.qmk.fm/#/newbs). +If you wish to build on your local machine, you will need to set up QMK locally. This is a one-time process, and is documented in the [newbs setup guide](newbs). -!> If you wish to use any QMK CLI commands related to manipulating External Userspace definitions, you will currently need a copy of QMK Firmware as well. +::: warning +If you wish to use any QMK CLI commands related to manipulating External Userspace definitions, you will currently need a copy of QMK Firmware as well. +::: -!> Building locally has a much shorter turnaround time than waiting for GitHub Actions to complete. +::: warning +Building locally has a much shorter turnaround time than waiting for GitHub Actions to complete. +::: ## External Userspace Repository Setup (forked on GitHub) @@ -60,7 +68,9 @@ After creating your new keymap, building the keymap matches normal QMK usage: qmk compile -kb -km ``` -!> The `qmk config user.overlay_dir=...` command must have been run when cloning the External Userspace repository for this to work correctly. +::: warning +The `qmk config user.overlay_dir=...` command must have been run when cloning the External Userspace repository for this to work correctly. +::: ## Adding the keymap to External Userspace build targets diff --git a/docs/newbs_flashing.md b/docs/newbs_flashing.md index c5ba897e17..eaa8032961 100644 --- a/docs/newbs_flashing.md +++ b/docs/newbs_flashing.md @@ -31,7 +31,9 @@ The simplest way to flash your keyboard will be with the [QMK Toolbox](https://g However, the Toolbox is currently only available for Windows and macOS. If you're using Linux (or just wish to flash the firmware from the command line), skip to the [Flash your Keyboard from the Command Line](#flash-your-keyboard-from-the-command-line) section. -?> QMK Toolbox is not necessary for flashing [RP2040 devices](https://docs.qmk.fm/#/flashing?id=raspberry-pi-rp2040-uf2). +::: tip +QMK Toolbox is not necessary for flashing [RP2040 devices](flashing#raspberry-pi-rp2040-uf2). +::: ### Load the File into QMK Toolbox @@ -39,21 +41,21 @@ Begin by opening the QMK Toolbox application. You'll want to locate the firmware If you are on Windows or macOS, there are commands you can use to easily open the current folder in Explorer or Finder. - +::::tabs -#### ** Windows ** +=== Windows ``` start . ``` -#### ** macOS ** +=== macOS ``` open . ``` - +:::: The firmware file always follows this naming format: @@ -98,7 +100,7 @@ This has been made pretty simple compared to what it used to be. When you are re qmk flash -If you did not configure your keyboard/keymap name in the CLI according to the [Configure your build environment](newbs_getting_started.md) section, or you have multiple keyboards, you can specify the keyboard and keymap: +If you did not configure your keyboard/keymap name in the CLI according to the [Configure your build environment](newbs_getting_started) section, or you have multiple keyboards, you can specify the keyboard and keymap: qmk flash -kb -km @@ -108,9 +110,11 @@ However, this does rely on the bootloader being set by the keyboard. If this inf WARNING: This board's bootloader is not specified or is not supported by the ":flash" target at this time. -In this case, you'll have to fall back on specifying the bootloader. See the [Flashing Firmware](flashing.md) Guide for more details. +In this case, you'll have to fall back on specifying the bootloader. See the [Flashing Firmware](flashing) Guide for more details. -!> If your bootloader is not detected by `qmk flash`, try running `qmk doctor` for suggestions on how to fix common problems. +::: warning +If your bootloader is not detected by `qmk flash`, try running `qmk doctor` for suggestions on how to fix common problems. +::: ## Test It Out! diff --git a/docs/newbs_getting_started.md b/docs/newbs_getting_started.md index 68e37679b8..3a901ad7ad 100644 --- a/docs/newbs_getting_started.md +++ b/docs/newbs_getting_started.md @@ -6,20 +6,22 @@ Before you can build keymaps, you need to install some software and set up your There are a few pieces of software you'll need to get started. -* [Text editor](newbs_learn_more_resources.md#text-editor-resources) +* [Text editor](newbs_learn_more_resources#text-editor-resources) * You’ll need a program that can edit and save plain text files. The default editor that comes with many OS's does not save plain text files, so you'll need to make sure that whatever editor you chose does. * [Toolbox (optional)](https://github.com/qmk/qmk_toolbox) * A graphical program for Windows and macOS that allows you to both program and debug your custom keyboard -?> If you haven't worked with the Linux/Unix command line before, there are a few basic concepts and commands you should learn. [These resources](newbs_learn_more_resources.md#command-line-resources) will teach you enough to be able to work with QMK. +::: tip +If you haven't worked with the Linux/Unix command line before, there are a few basic concepts and commands you should learn. [These resources](newbs_learn_more_resources#command-line-resources) will teach you enough to be able to work with QMK. +::: -## 2. Prepare Your Build Environment :id=set-up-your-environment +## 2. Prepare Your Build Environment {#set-up-your-environment} We've tried to make QMK as easy to set up as possible. You only have to prepare your Linux or Unix environment, then let QMK install the rest. - +:::::tabs -### ** Windows ** +==== Windows QMK maintains a Bundle of MSYS2, the CLI and all necessary dependencies. It also provides a handy `QMK MSYS` terminal shortcut to boot you directly into the correct environment. @@ -27,10 +29,11 @@ QMK maintains a Bundle of MSYS2, the CLI and all necessary dependencies. It also You will need to install [QMK MSYS](https://msys.qmk.fm/). The latest release is available [here](https://github.com/qmk/qmk_distro_msys/releases/latest). -
- Advanced Users +:::: details Advanced Users -!> This process is not recommended for new users. +::: danger +This process is not recommended for new users. +::: If you'd like to manually install MSYS2, the following sections will walk you through the process. @@ -38,17 +41,21 @@ If you'd like to manually install MSYS2, the following sections will walk you th You will need to install [MSYS2](https://www.msys2.org). Once installed, close any open MSYS terminals (purple icon) and open a new MinGW 64-bit terminal (blue icon) from the Start Menu. -!> **NOTE:** The MinGW 64-bit terminal is *not* the same as the MSYS terminal that opens when installation is completed. Your prompt should say "MINGW64" in purple text, rather than "MSYS". See [this page](https://www.msys2.org/wiki/MSYS2-introduction/#subsystems) for more information on the differences. +::: warning +**NOTE:** The MinGW 64-bit terminal is *not* the same as the MSYS terminal that opens when installation is completed. Your prompt should say "MINGW64" in purple text, rather than "MSYS". See [this page](https://www.msys2.org/wiki/MSYS2-introduction/#subsystems) for more information on the differences. +::: #### Installation Install the QMK CLI by running: - pacman --needed --noconfirm --disable-download-timeout -S git mingw-w64-x86_64-python-qmk +```sh +pacman --needed --noconfirm --disable-download-timeout -S git mingw-w64-x86_64-python-qmk +``` -
+:::: -### ** macOS ** +==== macOS QMK maintains a Homebrew tap and formula which will automatically install the CLI and all necessary dependencies. @@ -56,17 +63,23 @@ QMK maintains a Homebrew tap and formula which will automatically install the CL You will need to install Homebrew. Follow the instructions on https://brew.sh. -?> If you are using an Apple Silicon machine, the installation process will take significantly longer because GitHub actions do not have native runners to build binary packages for the ARM and AVR toolchains. +::: tip +If you are using an Apple Silicon machine, the installation process will take significantly longer because GitHub actions do not have native runners to build binary packages for the ARM and AVR toolchains. +::: #### Installation Install the QMK CLI by running: - brew install qmk/qmk/qmk - -### ** Linux/WSL ** +```sh +brew install qmk/qmk/qmk +``` -?> **Note for WSL users**: By default, the installation process will clone the QMK repository into your WSL home directory, but if you have cloned manually, ensure that it is located inside the WSL instance instead of the Windows filesystem (ie. not in `/mnt`), as accessing it is currently [extremely slow](https://github.com/microsoft/WSL/issues/4197). +==== Linux/WSL + +::: tip +**Note for WSL users**: By default, the installation process will clone the QMK repository into your WSL home directory, but if you have cloned manually, ensure that it is located inside the WSL instance instead of the Windows filesystem (ie. not in `/mnt`), as accessing it is currently [extremely slow](https://github.com/microsoft/WSL/issues/4197). +::: #### Prerequisites @@ -84,7 +97,9 @@ You will need to install Git and Python. It's very likely that you already have Install the QMK CLI by running: - python3 -m pip install --user qmk +```sh +python3 -m pip install --user qmk +``` #### Community Packages @@ -92,71 +107,90 @@ These packages are maintained by community members, so may not be up to date or On Arch-based distros you can install the CLI from the official repositories (NOTE: at the time of writing this package marks some dependencies as optional that should not be): - sudo pacman -S qmk +```sh +sudo pacman -S qmk +``` You can also try the `qmk-git` package from AUR: - yay -S qmk-git +```sh +yay -S qmk-git +``` -### ** FreeBSD ** +==== FreeBSD #### Installation Install the FreeBSD package for QMK CLI by running: - pkg install -g "py*-qmk" +```sh +pkg install -g "py*-qmk" +``` NOTE: remember to follow the instructions printed at the end of installation (use `pkg info -Dg "py*-qmk"` to show them again). - +::::: -## 3. Run QMK Setup :id=set-up-qmk +## 3. Run QMK Setup {#set-up-qmk} - +::::tabs -### ** Windows ** +=== Windows Open QMK MSYS and run the following command: - qmk setup +```sh +qmk setup +``` In most situations you will want to answer `y` to all of the prompts. -### ** macOS ** +=== macOS Open Terminal and run the following command: - qmk setup +```sh +qmk setup +``` In most situations you will want to answer `y` to all of the prompts. -### ** Linux/WSL ** +=== Linux/WSL Open your preferred terminal app and run the following command: - qmk setup +```sh +qmk setup +``` In most situations you will want to answer `y` to all of the prompts. -?>**Note on Debian, Ubuntu and their derivatives**: +::: info Note on Debian, Ubuntu and their derivatives: It's possible, that you will get an error saying something like: `bash: qmk: command not found`. This is due to a [bug](https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=839155) Debian introduced with their Bash 4.4 release, which removed `$HOME/.local/bin` from the PATH. This bug was later fixed on Debian and Ubuntu. Sadly, Ubuntu reintroduced this bug and is [yet to fix it](https://bugs.launchpad.net/ubuntu/+source/bash/+bug/1588562). Luckily, the fix is easy. Run this as your user: `echo 'PATH="$HOME/.local/bin:$PATH"' >> $HOME/.bashrc && source $HOME/.bashrc` +::: -### ** FreeBSD ** +=== FreeBSD Open your preferred terminal app and run the following command: - qmk setup +```sh +qmk setup +``` In most situations you will want to answer `y` to all of the prompts. - +:::: -?> The qmk home folder can be specified at setup with `qmk setup -H `, and modified afterwards using the [cli configuration](cli_configuration.md?id=single-key-example) and the variable `user.qmk_home`. For all available options run `qmk setup --help`. +::: tip +The qmk home folder can be specified at setup with `qmk setup -H `, and modified afterwards using the [cli configuration](cli_configuration#single-key-example) and the variable `user.qmk_home`. For all available options run `qmk setup --help`. +::: -?> If you already know how to use GitHub, [we recommend that you follow these instructions](getting_started_github.md) and use `qmk setup /qmk_firmware` to clone your personal fork. If you don't know what that means you can safely ignore this message. +::: tip +If you already know how to use GitHub, [we recommend that you follow these instructions](getting_started_github) and use `qmk setup /qmk_firmware` to clone your personal fork. If you don't know what that means you can safely ignore this message. +::: ## 4. Test Your Build Environment @@ -168,7 +202,9 @@ For example, to build a firmware for a Clueboard 66% you would use: qmk compile -kb clueboard/66/rev3 -km default -?> The keyboard option is the path relative to the keyboard directory, the above example would be found in `qmk_firmware/keyboards/clueboard/66/rev3`. If you're unsure you can view a full list of supported keyboards with `qmk list-keyboards`. +::: tip +The keyboard option is the path relative to the keyboard directory, the above example would be found in `qmk_firmware/keyboards/clueboard/66/rev3`. If you're unsure you can view a full list of supported keyboards with `qmk list-keyboards`. +::: When it is done you should have a lot of output that ends similar to this: @@ -182,4 +218,4 @@ Checking file size of clueboard_66_rev3_default.hex # Creating Your Keymap -You are now ready to create your own personal keymap! Move on to [Building Your First Firmware](newbs_building_firmware.md) for that. +You are now ready to create your own personal keymap! Move on to [Building Your First Firmware](newbs_building_firmware) for that. diff --git a/docs/newbs_git_best_practices.md b/docs/newbs_git_best_practices.md index c0cb3a2944..31ccfc8d67 100644 --- a/docs/newbs_git_best_practices.md +++ b/docs/newbs_git_best_practices.md @@ -6,11 +6,11 @@ This section aims to instruct novices in the best ways to have a smooth experien 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). +1. You have a GitHub account, and have [forked the qmk_firmware repository](getting_started_github) to your account. +2. You've set up both [your build environment](newbs_getting_started#set-up-your-environment) and [QMK](newbs_getting_started#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) +- Part 1: [Your Fork's Master: Update Often, Commit Never](newbs_git_using_your_master_branch) +- Part 2: [Resolving Merge Conflicts](newbs_git_resolving_merge_conflicts) +- Part 3: [Resynchronizing an Out-of-Sync Git Branch](newbs_git_resynchronize_a_branch) diff --git a/docs/newbs_git_resolving_merge_conflicts.md b/docs/newbs_git_resolving_merge_conflicts.md index 467c13abba..b94bc07942 100644 --- a/docs/newbs_git_resolving_merge_conflicts.md +++ b/docs/newbs_git_resolving_merge_conflicts.md @@ -2,7 +2,9 @@ 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. +::: tip +This document builds upon the concepts detailed in [Your Fork's Master: Update Often, Commit Never](newbs_git_using_your_master_branch). If you are not familiar with that document, please read it first, then return here. +::: ## Rebasing Your Changes diff --git a/docs/newbs_git_resynchronize_a_branch.md b/docs/newbs_git_resynchronize_a_branch.md index b15c6cf7a8..4182cf6056 100644 --- a/docs/newbs_git_resynchronize_a_branch.md +++ b/docs/newbs_git_resynchronize_a_branch.md @@ -2,7 +2,9 @@ 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 branch 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. +::: tip +This document builds upon the concepts detailed in [Your Fork's Master: Update Often, Commit Never](newbs_git_using_your_master_branch). 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) @@ -66,6 +68,8 @@ These steps will update the repository on your computer, but your GitHub fork wi git push --recurse-submodules=on-demand --force-with-lease ``` -!> **DO NOT** run `git push --recurse-submodules=on-demand --force-with-lease` on a fork to which other users post commits. This will erase their commits. +::: warning +**DO NOT** run `git push --recurse-submodules=on-demand --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. +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#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 index c27323f551..da9aeed03c 100644 --- a/docs/newbs_git_using_your_master_branch.md +++ b/docs/newbs_git_using_your_master_branch.md @@ -12,7 +12,9 @@ To keep your `master` branch updated, it is recommended to add the QMK Firmware 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 `, `` 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. +::: tip +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 `, `` 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: @@ -37,7 +39,7 @@ 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 :id=making-changes +## Making Changes {#making-changes} To make changes, create a new branch by entering: @@ -48,7 +50,9 @@ 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`. +::: tip +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. @@ -67,7 +71,9 @@ 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. +::: tip +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 diff --git a/docs/newbs_testing_debugging.md b/docs/newbs_testing_debugging.md index c3550489e5..aa81bdd568 100644 --- a/docs/newbs_testing_debugging.md +++ b/docs/newbs_testing_debugging.md @@ -2,8 +2,8 @@ ## Testing -[Moved here](faq_misc.md#testing) +[Moved here](faq_misc#testing) -## Debugging :id=debugging +## Debugging {#debugging} -[Moved here](faq_debug.md#debugging) +[Moved here](faq_debug#debugging) diff --git a/docs/one_shot_keys.md b/docs/one_shot_keys.md index 515830ea32..140c8de475 100644 --- a/docs/one_shot_keys.md +++ b/docs/one_shot_keys.md @@ -15,7 +15,7 @@ You can control the behavior of one shot keys by defining these in `config.h`: #define ONESHOT_TIMEOUT 5000 /* Time (in ms) before the one shot key is released */ ``` -* `OSM(mod)` - Momentarily hold down *mod*. You must use the `MOD_*` keycodes as shown in [Mod Tap](mod_tap.md), not the `KC_*` codes. +* `OSM(mod)` - Momentarily hold down *mod*. You must use the `MOD_*` keycodes as shown in [Mod Tap](mod_tap), not the `KC_*` codes. * `OSL(layer)` - momentary switch to *layer*. * `OS_ON` - Turns on One Shot keys. * `OS_OFF` - Turns off One Shot keys. OSM act as regular mod keys, OSL act like `MO`. @@ -27,7 +27,9 @@ For one shot layers, you need to call `set_oneshot_layer(LAYER, ONESHOT_START)` For one shot mods, you need to call `set_oneshot_mods(MOD_BIT(KC_*))` to set it, or `clear_oneshot_mods()` to cancel it. -!> If you're having issues with OSM translating over Remote Desktop Connection, this can be fixed by opening the settings, going to the "Local Resources" tab, and in the keyboard section, change the drop down to "On this Computer". This will fix the issue and allow OSM to function properly over Remote Desktop. +::: warning +If you're having issues with OSM translating over Remote Desktop Connection, this can be fixed by opening the settings, going to the "Local Resources" tab, and in the keyboard section, change the drop down to "On this Computer". This will fix the issue and allow OSM to function properly over Remote Desktop. +::: ## Callbacks diff --git a/docs/other_eclipse.md b/docs/other_eclipse.md index de8cdf9b8c..5a0228efce 100644 --- a/docs/other_eclipse.md +++ b/docs/other_eclipse.md @@ -17,7 +17,7 @@ Note that this set-up has been tested on Ubuntu 16.04 only for the moment. # Prerequisites ## Build Environment -Before starting, you must have followed the [Getting Started](newbs_getting_started.md) section of the Tutorial. In particular, you must have been able to build the firmware with [the `qmk compile` command](newbs_building_firmware.md#build-your-firmware). +Before starting, you must have followed the [Getting Started](newbs_getting_started) section of the Tutorial. In particular, you must have been able to build the firmware with [the `qmk compile` command](newbs_building_firmware#build-your-firmware). ## Java Eclipse is a Java application, so you will need to install Java 8 or more recent to be able to run it. You may choose between the JRE or the JDK, the latter being useful if you intend to do Java development. diff --git a/docs/other_vscode.md b/docs/other_vscode.md index 4c71a0eb1c..31208d8f3b 100644 --- a/docs/other_vscode.md +++ b/docs/other_vscode.md @@ -15,7 +15,7 @@ The purpose of this page is to document how to set up VS Code for developing QMK This guide covers how to configure everything needed on Windows and Ubuntu 18.04 # Set up VS Code -Before starting, you will want to make sure that you have all of the build tools set up, and QMK Firmware cloned. Head to the [Newbs Getting Started Guide](newbs_getting_started.md) to get things set up, if you haven't already. +Before starting, you will want to make sure that you have all of the build tools set up, and QMK Firmware cloned. Head to the [Newbs Getting Started Guide](newbs_getting_started) to get things set up, if you haven't already. ## Windows @@ -73,7 +73,9 @@ Now, we will set up the MSYS2 window to show up in VSCode as the integrated term If there are settings here already, then just add everything between the first and last curly brackets and separate the existing settings with a comma from the newly added ones. -?> If you installed MSYS2 to a different folder, then you'll need to change the path for `terminal.integrated.shell.windows` to the correct path for your system. +::: tip +If you installed MSYS2 to a different folder, then you'll need to change the path for `terminal.integrated.shell.windows` to the correct path for your system. +::: 4. Hit Ctrl-` (Grave) to bring up the terminal or go to View > Terminal (command `workbench.action.terminal.toggleTerminal`). A new terminal will be opened if there isn‘t one already. @@ -171,7 +173,9 @@ You'll need to perform some modifications to the file above in order to target y * `"device"`: The name of the MCU, which matches the `` tag at the top of the downloaded `svd` file. * `"armToolchainPath"`: _[Optional]_ The path to the ARM toolchain installation location on Windows -- under normal circumstances Linux/macOS will auto-detect this correctly and will not need to be specified. -!> Windows builds of QMK Firmware are generally compiled using QMK MSYS, and the path to gdb's location (`C:\\QMK_MSYS\\mingw64\\bin`) needs to be specified under `armToolchainPath` for it to be detected. You may also need to change the GDB path to point at `C:\\QMK_MSYS\\mingw64\\bin\\gdb-multiarch.exe` in the VSCode Cortex-Debug user settings: ![VSCode Settings](https://i.imgur.com/EGrPM1L.png) +::: warning +Windows builds of QMK Firmware are generally compiled using QMK MSYS, and the path to gdb's location (`C:\\QMK_MSYS\\mingw64\\bin`) needs to be specified under `armToolchainPath` for it to be detected. You may also need to change the GDB path to point at `C:\\QMK_MSYS\\mingw64\\bin\\gdb-multiarch.exe` in the VSCode Cortex-Debug user settings: ![VSCode Settings](https://i.imgur.com/EGrPM1L.png) +::: Optionally, the following modifications should also be made to the keyboard's `rules.mk` file to disable optimisations -- not strictly required but will ensure breakpoints and variable viewing works correctly: ```makefile diff --git a/docs/platformdev_chibios_earlyinit.md b/docs/platformdev_chibios_earlyinit.md index bc49247222..66b8ee4655 100644 --- a/docs/platformdev_chibios_earlyinit.md +++ b/docs/platformdev_chibios_earlyinit.md @@ -1,4 +1,4 @@ -# Arm/ChibiOS Early Initialization :id=chibios-early-init +# Arm/ChibiOS Early Initialization {#chibios-early-init} This page describes a part of QMK that is a somewhat advanced concept, and is only relevant to keyboard designers. @@ -6,7 +6,7 @@ QMK uses ChibiOS as the underlying layer to support a multitude of Arm-based dev Older QMK revisions required duplication of these board definitions inside your keyboard's directory in order to override such early initialization points; this is now abstracted into the following APIs, and allows usage of the board definitions supplied with ChibiOS itself. Check `/lib/chibios/os/hal/boards` for the list of official definitions. If your keyboard needs extra initialization at a very early stage, consider providing keyboard-level overrides of the following APIs instead of duplicating the board definitions: -## `early_hardware_init_pre()` :id=early-hardware-init-pre +## `early_hardware_init_pre()` {#early-hardware-init-pre} The function `early_hardware_init_pre` is the earliest possible code that can be executed by a keyboard firmware. This is intended as a replacement for the ChibiOS board definition's `__early_init` function, and is the equivalent of executing at the start of the function. @@ -32,7 +32,7 @@ void early_hardware_init_pre(void) { } ``` -## `early_hardware_init_post()` :id=early-hardware-init-post +## `early_hardware_init_post()` {#early-hardware-init-post} The function `early_hardware_init_post` is the next earliest possible code that can be executed by a keyboard firmware. This is executed after RAM has been cleared, and clocks and GPIOs are configured. This is intended as a replacement for the ChibiOS board definition's `__early_init` function, and is the equivalent of executing at the end of the function. @@ -48,7 +48,7 @@ void early_hardware_init_post(void) { } ``` -## `board_init()` :id=board-init +## `board_init()` {#board-init} The function `board_init` is executed directly after the ChibiOS initialization routines have completed. At this stage, all normal low-level functionality should be available for use (including timers and delays), with the restriction that USB is not yet connected. This is intended as a replacement for the ChibiOS board definition's `boardInit` function. diff --git a/docs/platformdev_rp2040.md b/docs/platformdev_rp2040.md index 593a8198eb..f0b006cf6e 100644 --- a/docs/platformdev_rp2040.md +++ b/docs/platformdev_rp2040.md @@ -4,23 +4,25 @@ The following table shows the current driver status for peripherals on RP2040 MC | System | Support | | ---------------------------------------------------------------- | ---------------------------------------------- | -| [ADC driver](adc_driver.md) | :heavy_check_mark: | -| [Audio](audio_driver.md#pwm-hardware) | :heavy_check_mark: | -| [Backlight](feature_backlight.md) | :heavy_check_mark: | -| [I2C driver](i2c_driver.md) | :heavy_check_mark: | -| [SPI driver](spi_driver.md) | :heavy_check_mark: | -| [WS2812 driver](ws2812_driver.md) | :heavy_check_mark: using `PIO` driver | -| [External EEPROMs](eeprom_driver.md) | :heavy_check_mark: using `I2C` or `SPI` driver | -| [EEPROM emulation](eeprom_driver.md#wear_leveling-configuration) | :heavy_check_mark: | -| [serial driver](serial_driver.md) | :heavy_check_mark: using `SIO` or `PIO` driver | -| [UART driver](uart_driver.md) | :heavy_check_mark: using `SIO` driver | +| [ADC driver](adc_driver) | :heavy_check_mark: | +| [Audio](audio_driver#pwm-hardware) | :heavy_check_mark: | +| [Backlight](feature_backlight) | :heavy_check_mark: | +| [I2C driver](i2c_driver) | :heavy_check_mark: | +| [SPI driver](spi_driver) | :heavy_check_mark: | +| [WS2812 driver](ws2812_driver) | :heavy_check_mark: using `PIO` driver | +| [External EEPROMs](eeprom_driver) | :heavy_check_mark: using `I2C` or `SPI` driver | +| [EEPROM emulation](eeprom_driver#wear_leveling-configuration) | :heavy_check_mark: | +| [serial driver](serial_driver) | :heavy_check_mark: using `SIO` or `PIO` driver | +| [UART driver](uart_driver) | :heavy_check_mark: using `SIO` driver | ## GPIO Raspberry Pi Pico pinout Sparkfun RP2040 Pro Micro pinout -!> The GPIO pins of the RP2040 are not 5V tolerant! +::: warning +The GPIO pins of the RP2040 are not 5V tolerant! +::: ### Pin nomenclature @@ -41,7 +43,7 @@ QMK RP2040 support builds upon ChibiOS and thus follows their convention for act | `I2C0` | `RP_I2C_USE_I2C0` | `I2CD0` | | `I2C1` | `RP_I2C_USE_I2C1` | `I2CD1` | -To configure the I2C driver please read the [ChibiOS/ARM](i2c_driver.md#arm-configuration) section. +To configure the I2C driver please read the [ChibiOS/ARM](i2c_driver#arm-configuration) section. ### SPI Driver @@ -50,7 +52,7 @@ To configure the I2C driver please read the [ChibiOS/ARM](i2c_driver.md#arm-conf | `SPI0` | `RP_SPI_USE_SPI0` | `SPID0` | | `SPI1` | `RP_SPI_USE_SPI1` | `SPID1` | -To configure the SPI driver please read the [ChibiOS/ARM](spi_driver.md#chibiosarm-configuration) section. +To configure the SPI driver please read the [ChibiOS/ARM](spi_driver#chibiosarm-configuration) section. ### UART Driver @@ -59,7 +61,7 @@ To configure the SPI driver please read the [ChibiOS/ARM](spi_driver.md#chibiosa | `UART0` | `RP_SIO_USE_UART0` | `SIOD0` | | `UART1` | `RP_SIO_USE_UART1` | `SIOD1` | -## Double-tap reset boot-loader entry :id=double-tap +## Double-tap reset boot-loader entry {#double-tap} The double-tap reset mechanism is an alternate way in QMK to enter the embedded mass storage UF2 boot-loader of the RP2040. It enables bootloader entry by a fast double-tap of the reset pin on start up, which is similar to the behavior of AVR Pro Micros. This feature activated by default for the Pro Micro RP2040 board, but has to be configured for other boards. To activate it, add the following options to your keyboards `config.h` file: @@ -90,7 +92,7 @@ This is the default board that is chosen, unless any other RP2040 board is selec | `SPI_MISO_PIN` | `GP20` | | `SPI_MOSI_PIN` | `GP19` | | **Serial driver** | | -| `SERIAL_USART_DRIVER` ([SIO Driver](serial_driver.md#the-sio-driver) only) | `SIOD0` | +| `SERIAL_USART_DRIVER` ([SIO Driver](serial_driver#the-sio-driver) only) | `SIOD0` | | `SOFT_SERIAL_PIN` | undefined, use `SERIAL_USART_TX_PIN` | | `SERIAL_USART_TX_PIN` | `GP0` | | `SERIAL_USART_RX_PIN` | `GP1` | @@ -99,7 +101,9 @@ This is the default board that is chosen, unless any other RP2040 board is selec | `UART_TX_PIN` | `GP0` | | `UART_RX_PIN` | `GP1` | -?> The pin-outs of Adafruit's KB2040 and Boardsource's Blok both deviate from the Sparkfun Pro Micro RP2040. Lookup the pin-out of these boards and adjust your keyboards pin definition accordingly if you want to use these boards. +::: tip +The pin-outs of Adafruit's KB2040 and Boardsource's Blok both deviate from the Sparkfun Pro Micro RP2040. Lookup the pin-out of these boards and adjust your keyboards pin definition accordingly if you want to use these boards. +::: ### Generic RP2040 board @@ -111,9 +115,9 @@ BOARD = GENERIC_RP_RP2040 ## Split keyboard support -Split keyboards are fully supported using the [serial driver](serial_driver.md) in both full-duplex and half-duplex configurations. Two driver subsystems are supported by the RP2040, the hardware UART based `SIO` and the Programmable IO based `PIO` driver. +Split keyboards are fully supported using the [serial driver](serial_driver) in both full-duplex and half-duplex configurations. Two driver subsystems are supported by the RP2040, the hardware UART based `SIO` and the Programmable IO based `PIO` driver. -| Feature | [SIO Driver](serial_driver.md#the-sio-driver) | [PIO Driver](serial_driver.md#the-pio-driver) | +| Feature | [SIO Driver](serial_driver#the-sio-driver) | [PIO Driver](serial_driver#the-pio-driver) | | ----------------------------- | --------------------------------------------- | --------------------------------------------- | | Half-Duplex operation | | :heavy_check_mark: | | Full-Duplex operation | :heavy_check_mark: | :heavy_check_mark: | @@ -136,7 +140,7 @@ As the RP2040 does not have any internal flash memory it depends on an external | IS25LP080 | `#define RP2040_FLASH_IS25LP080` | | Generic 03H flash | `#define RP2040_FLASH_GENERIC_03H` | -## RP2040 Community Edition :id=rp2040_ce +## RP2040 Community Edition {#rp2040_ce} The "RP2040 Community Edition" standard is a pinout that was defined by a committee of designers on the BastardKB Discord server. diff --git a/docs/platformdev_selecting_arm_mcu.md b/docs/platformdev_selecting_arm_mcu.md index c115aa6e0f..95a88536ec 100644 --- a/docs/platformdev_selecting_arm_mcu.md +++ b/docs/platformdev_selecting_arm_mcu.md @@ -1,4 +1,4 @@ -# Choosing an Arm MCU :id=choose-arm-mcu +# Choosing an Arm MCU {#choose-arm-mcu} This page outlines the selection criteria to ensure compatibility with Arm/ChibiOS. @@ -8,7 +8,7 @@ Adding support for new MCU families must go through ChibiOS or ChibiOS-Contrib - To be clear: this also includes commercial boards -- unless agreed upon by all parties, QMK will not take over maintenance of a bespoke MCU support package. Even if MCU support is upstreamed into ChibiOS/ChibiOS-Contrib, QMK reserves the right to deprecate and/or remove keyboards utilising support packages that aren't kept up to date with upstream ChibiOS itself. -## Selecting an already-supported MCU :id=selecting-already-supported-mcu +## Selecting an already-supported MCU {#selecting-already-supported-mcu} ### STM32 families @@ -43,16 +43,16 @@ ChibiOS does have support for a handful of non-STM32 devices, and the list can b Do note that there are sometimes licensing restrictions with respect to redistribution. As an example, binaries built for nRF5 are not able to be redistributed via QMK Configurator, due to the licensing of their board support package. -## Adding support for a new STM32 MCU (for an existing family) :id=add-new-stm32-mcu +## Adding support for a new STM32 MCU (for an existing family) {#add-new-stm32-mcu} Usually, one can "masquerade" as an existing MCU of the same family, especially if the only difference is RAM or Flash size. As an example, some MCUs within the same family are virtually identical, with the exception of adding a cryptographic peripheral -- STM32L072 vs. STM32L082 for instance. Given the unlikely use of the cryptographic peripheral, L082 chips can actually run as if they're an L072, and can be targeted accordingly. Adding proper support for new MCUs within an existing STM32 family should ideally be upstreamed to ChibiOS. In general, this will require modifications of the `stm32_registry.h` file, providing correct responses for the same `#define`s provided for the other MCUs in that family. -## Adding support for a new STM32 Family :id=add-new-stm32-family +## Adding support for a new STM32 Family {#add-new-stm32-family} If this is a requirement, this needs to go through upstream ChibiOS before QMK would consider accepting boards targeting the new family. More information for porting should be sought by approaching ChibiOS directly, rather than through QMK. -## Adding support for a new MCU Family :id=add-new-mcu-family +## Adding support for a new MCU Family {#add-new-mcu-family} As stated earlier, in order for a new MCU family to be supported by QMK, it needs to be upstreamed into ChibiOS-Contrib before QMK will consider accepting boards using it. The same principle applies for development -- you're best approaching the ChibiOS-Contrib maintainers to get a bit more of an idea on what's involved with upstreaming your contribution. diff --git a/docs/porting_your_keyboard_to_qmk.md b/docs/porting_your_keyboard_to_qmk.md index b0213a6d70..c91e5ca31d 100644 --- a/docs/porting_your_keyboard_to_qmk.md +++ b/docs/porting_your_keyboard_to_qmk.md @@ -1,8 +1,8 @@ # Adding Your Keyboard to QMK -This page describes the support for [Compatible Microcontrollers](compatible_microcontrollers.md) in QMK. +This page describes the support for [Compatible Microcontrollers](compatible_microcontrollers) in QMK. -If you have not yet you should read the [Keyboard Guidelines](hardware_keyboard_guidelines.md) to get a sense of how keyboards fit into QMK. +If you have not yet you should read the [Keyboard Guidelines](hardware_keyboard_guidelines) to get a sense of how keyboards fit into QMK. QMK has a number of features to simplify working with keyboards. For most, you don't have to write a single line of code. To get started, run `qmk new-keyboard`: @@ -13,7 +13,7 @@ $ qmk new-keyboard Name Your Keyboard Project For more infomation, see: -https://docs.qmk.fm/#/hardware_keyboard_guidelines?id=naming-your-keyboardproject +https://docs.qmk.fm/hardware_keyboard_guidelines#naming-your-keyboardproject keyboard Name? mycoolkeeb @@ -56,11 +56,11 @@ This will create all the files needed to support your new keyboard, and populate ## `readme.md` -This is where you'll describe your keyboard. Please follow the [Keyboard Readme Template](documentation_templates.md#keyboard-readmemd-template) when writing your `readme.md`. You're encouraged to place an image at the top of your `readme.md`, please use an external service such as [Imgur](https://imgur.com) to host the images. +This is where you'll describe your keyboard. Please follow the [Keyboard Readme Template](documentation_templates#keyboard-readmemd-template) when writing your `readme.md`. You're encouraged to place an image at the top of your `readme.md`, please use an external service such as [Imgur](https://imgur.com) to host the images. ## `info.json` -The `info.json` file is where you configure the hardware and feature set for your keyboard. There are a lot of options that can be placed in that file, too many to list here. For a complete overview of available options see the [Data Driven Configuration Options](reference_info_json.md) page. +The `info.json` file is where you configure the hardware and feature set for your keyboard. There are a lot of options that can be placed in that file, too many to list here. For a complete overview of available options see the [Data Driven Configuration Options](reference_info_json) page. ### Hardware Configuration @@ -78,7 +78,9 @@ Do change the `manufacturer` and `keyboard_name` lines to accurately reflect you }, ``` -?> Windows and macOS will display the `manufacturer` and `keyboard_name` in the list of USB devices. `lsusb` on Linux instead prefers the values in the list maintained by the [USB ID Repository](http://www.linux-usb.org/usb-ids.html). By default, it will only use `manufacturer` and `keyboard_name` if the list does not contain that `usb.vid` / `usb.pid`. `sudo lsusb -v` will show the values reported by the device, and they are also present in kernel logs after plugging it in. +::: tip +Windows and macOS will display the `manufacturer` and `keyboard_name` in the list of USB devices. `lsusb` on Linux instead prefers the values in the list maintained by the [USB ID Repository](http://www.linux-usb.org/usb-ids.html). By default, it will only use `manufacturer` and `keyboard_name` if the list does not contain that `usb.vid` / `usb.pid`. `sudo lsusb -v` will show the values reported by the device, and they are also present in kernel logs after plugging it in. +::: ### Matrix Configuration @@ -147,18 +149,20 @@ Next is configuring Layout Macro(s). These define the physical arrangement of ke In the above example, * `LAYOUT_ortho_4x4` defines the name of the layout macro - * It must conform to the [layout guidelines](hardware_keyboard_guidelines.md#ltkeyboard_namehgt) + * It must conform to the [layout guidelines](hardware_keyboard_guidelines#ltkeyboard_namehgt) * `"matrix": [0, 0]` defines the electrical position -?> See also: [Split Keyboard Layout Macro](https://docs.qmk.fm/#/feature_split_keyboard?id=layout-macro) and [Matrix to Physical Layout](https://docs.qmk.fm/#/understanding_qmk?id=matrix-to-physical-layout-map). +::: tip +See also: [Split Keyboard Layout Macro](feature_split_keyboard#layout-macro) and [Matrix to Physical Layout](understanding_qmk#matrix-to-physical-layout-map). +::: ## Additional Configuration -There are a lot of features that can be turned on or off, configured or tuned. Some of these have yet to be migrated over to [Data Driven Configuration](data_driven_config.md). The following sections cover the process for when an `info.json` option is unavailable. +There are a lot of features that can be turned on or off, configured or tuned. Some of these have yet to be migrated over to [Data Driven Configuration](data_driven_config). The following sections cover the process for when an `info.json` option is unavailable. ### Configuration Options -For available options for `config.h`, you should see the [Config Options](config_options.md#the-configh-file) page for more details. +For available options for `config.h`, you should see the [Config Options](config_options#the-configh-file) page for more details. ### Build Options -For available options for `rules.mk`, see the [Config Options](config_options.md#feature-options) page for a detailed list and description. +For available options for `rules.mk`, see the [Config Options](config_options#feature-options) page for a detailed list and description. diff --git a/docs/pr_checklist.md b/docs/pr_checklist.md index 94ff7eed66..e5ed1d67b6 100644 --- a/docs/pr_checklist.md +++ b/docs/pr_checklist.md @@ -8,7 +8,7 @@ If there are any inconsistencies with these recommendations, you're best off [cr - PR should be submitted using a non-`master` branch on the source repository - this does not mean you target a different branch for your PR, rather that you're not working out of your own master branch - - if submitter _does_ use their own `master` branch, they'll be given a link to the ["how to git"](newbs_git_using_your_master_branch.md) page after merging -- (end of this document will contain the contents of the message) + - if submitter _does_ use their own `master` branch, they'll be given a link to the ["how to git"](newbs_git_using_your_master_branch) page after merging -- (end of this document will contain the contents of the message) - Note, frequently merging upstream with your branch is not needed and is discouraged. Valid reason for updating your branch may be resolving merge conflicts and pulling in new changes relevant to your PR. - PRs should contain the smallest amount of modifications required for a single change to the codebase - multiple keyboards at the same time is not acceptable @@ -40,7 +40,9 @@ If there are any inconsistencies with these recommendations, you're best off [cr ## Keymap PRs -!> Note that personal keymap submissions will no longer be accepted. This section applies to manufacturer-supported keymaps. Please see this [issue](https://github.com/qmk/qmk_firmware/issues/22724) for more information. +::: warning +Note that personal keymap submissions will no longer be accepted. This section applies to manufacturer-supported keymaps. Please see this [issue](https://github.com/qmk/qmk_firmware/issues/22724) for more information. +::: - PRs for vendor specific keymaps will be permitted. The naming convention for these should be `default_${vendor}`, `via_${vendor}` i.e. `via_clueboard`. - vendor specific keymaps do not necessarily need to be "vanilla" and can be more richly featured than `default` or `via` stock keymaps. @@ -59,7 +61,7 @@ https://github.com/qmk/qmk_firmware/pulls?q=is%3Apr+is%3Aclosed+label%3Akeyboard - keyboard updates and refactors (eg. to data driven) *must* go through `develop` to reduce `master` -> `develop` merge conflicts - PR submissions from a `kbfirmware` export (or equivalent) will not be accepted unless converted to new QMK standards -- try `qmk import-kbfirmware` first - `info.json` - - With the move to [data driven](https://docs.qmk.fm/#/data_driven_config) keyboard configuration, we encourage contributors to utilise as many features as possible of the info.json [schema](https://github.com/qmk/qmk_firmware/blob/master/data/schemas/keyboard.jsonschema). + - With the move to [data driven](data_driven_config) keyboard configuration, we encourage contributors to utilise as many features as possible of the info.json [schema](https://github.com/qmk/qmk_firmware/blob/master/data/schemas/keyboard.jsonschema). - the mandatory elements for a minimally complete `info.json` at present are: - valid URL - valid maintainer @@ -86,7 +88,7 @@ https://github.com/qmk/qmk_firmware/pulls?q=is%3Apr+is%3Aclosed+label%3Akeyboard - RGB Matrix Configuration - Run `qmk format-json` on this file before submitting your PR. Be sure to append the `-i` flag to directly modify the file, or paste the outputted code into the file. - `readme.md` - - must follow the [template](https://github.com/qmk/qmk_firmware/blob/master/data/templates/keyboard/readme.md) + - must follow the [template](https://github.com/qmk/qmk_firmware/blob/master/data/templates/keyboard/readme) - flash command is present, and has `:flash` at end - valid hardware availability link (unless handwired) -- private groupbuys are okay, but one-off prototypes will be questioned. If open-source, a link to files should be provided. - clear instructions on how to reset the board into bootloader mode @@ -122,9 +124,9 @@ https://github.com/qmk/qmk_firmware/pulls?q=is%3Apr+is%3Aclosed+label%3Akeyboard - `.c` - empty `xxxx_xxxx_kb()`, `xxxx_xxxx_user()`, or other weak-defined default implemented functions removed - commented-out functions removed too - - `matrix_init_board()` etc. migrated to `keyboard_pre_init_kb()`, see: [keyboard_pre_init*](custom_quantum_functions.md?id=keyboard_pre_init_-function-documentation) - - prefer `CUSTOM_MATRIX = lite` if custom matrix used, allows for standard debounce, see [custom matrix 'lite'](custom_matrix.md?id=lite) - - prefer LED indicator [Configuration Options](feature_led_indicators.md?id=configuration-options) to custom `led_update_*()` implementations where possible + - `matrix_init_board()` etc. migrated to `keyboard_pre_init_kb()`, see: [keyboard_pre_init*](custom_quantum_functions#keyboard_pre_init_-function-documentation) + - prefer `CUSTOM_MATRIX = lite` if custom matrix used, allows for standard debounce, see [custom matrix 'lite'](custom_matrix#lite) + - prefer LED indicator [Configuration Options](feature_led_indicators#configuration-options) to custom `led_update_*()` implementations where possible - hardware that's enabled at the keyboard level and requires configuration such as OLED displays or encoders should have basic functionality implemented here - `.h` - `#include "quantum.h"` appears at the top @@ -133,12 +135,12 @@ https://github.com/qmk/qmk_firmware/pulls?q=is%3Apr+is%3Aclosed+label%3Akeyboard - no duplication of `rules.mk` or `config.h` from keyboard - `keymaps/default/keymap.c` - `QMKBEST`/`QMKURL` example macros removed - - if using `MO(1)` and `MO(2)` keycodes together to access a third layer, the [Tri Layer](https://docs.qmk.fm/#/feature_tri_layer) feature should be used, rather than manually implementing this using `layer_on/off()` and `update_tri_layer()` functions in the keymap's `process_record_user()`. + - if using `MO(1)` and `MO(2)` keycodes together to access a third layer, the [Tri Layer](feature_tri_layer) feature should be used, rather than manually implementing this using `layer_on/off()` and `update_tri_layer()` functions in the keymap's `process_record_user()`. - default (and via) keymaps should be "pristine" - bare minimum to be used as a "clean slate" for another user to develop their own user-specific keymap - what does pristine mean? no custom keycodes. no advanced features like tap dance or macros. basic mod taps and home row mods would be acceptable where their use is necessary - standard layouts preferred in these keymaps, if possible - - should use [encoder map feature](https://docs.qmk.fm/#/feature_encoders?id=encoder-map), rather than `encoder_update_user()` + - should use [encoder map feature](feature_encoders#encoder-map), rather than `encoder_update_user()` - default keymap should not enable VIA -- the VIA integration documentation requires a keymap called `via` - submitters can add an example (or bells-and-whistles) keymap showcasing capabilities in the same PR but it shouldn't be embedded in the 'default' keymap - submitters can also have a "manufacturer-matching" keymap that mirrors existing functionality of the commercial product, if porting an existing board @@ -163,11 +165,11 @@ Also, specific to ChibiOS: - New board definitions must not be embedded in a keyboard PR - See [Core PRs](#core-pr) below for the procedure for adding a new board to QMK - if a board definition is unavoidable, `board.c` must have a standard `__early_init()` (as per normal ChibiOS board defs) and an empty `boardInit()`: - - see Arm/ChibiOS [early initialization](platformdev_chibios_earlyinit.md?id=board-init) + - see Arm/ChibiOS [early initialization](platformdev_chibios_earlyinit#board-init) - `__early_init()` should be replaced by either `early_hardware_init_pre()` or `early_hardware_init_post()` as appropriate - `boardInit()` should be migrated to `board_init()` -## Core PRs :id=core-pr +## Core PRs {#core-pr} - all core PRs must now target `develop` branch, which will subsequently be merged back to `master` on the breaking changes timeline - as indicated above, the smallest set of changes to core components should be included in each PR @@ -197,9 +199,9 @@ For future reference, we recommend against committing to your `master` branch as There are instructions on how to keep your fork updated here: -[**Best Practices: Your Fork's Master: Update Often, Commit Never**](https://docs.qmk.fm/#/newbs_git_using_your_master_branch) +[**Best Practices: Your Fork's Master: Update Often, Commit Never**](newbs_git_using_your_master_branch) -[Fixing Your Branch](https://docs.qmk.fm/#/newbs_git_resynchronize_a_branch) will walk you through fixing up your `master` branch moving forward. If you need any help with this just ask. +[Fixing Your Branch](newbs_git_resynchronize_a_branch) will walk you through fixing up your `master` branch moving forward. If you need any help with this just ask. Thanks for contributing! ``` diff --git a/docs/public/badge-community-dark.svg b/docs/public/badge-community-dark.svg new file mode 100644 index 0000000000..dba561dda1 --- /dev/null +++ b/docs/public/badge-community-dark.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/docs/public/badge-community-light.svg b/docs/public/badge-community-light.svg new file mode 100644 index 0000000000..de4e0cf149 --- /dev/null +++ b/docs/public/badge-community-light.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/docs/qmk.css b/docs/qmk.css deleted file mode 100644 index 543cd7f28d..0000000000 --- a/docs/qmk.css +++ /dev/null @@ -1,862 +0,0 @@ -* { - -webkit-font-smoothing: antialiased; - -webkit-overflow-scrolling: touch; - -webkit-tap-highlight-color: rgba(0,0,0,0); - -webkit-text-size-adjust: none; - -webkit-touch-callout: none; - -webkit-box-sizing: border-box; - box-sizing: border-box; -} -body:not(.ready) { - overflow: hidden; -} -body:not(.ready) [data-cloak], -body:not(.ready) .app-nav, -body:not(.ready) > nav { - display: none; -} -div#app { - font-size: 30px; - font-weight: lighter; - margin: 40vh auto; - text-align: center; -} -div#app:empty::before { - content: 'Loading...'; -} -.emoji { - height: 1.2rem; - vertical-align: middle; -} -.progress { - background-color: var(--theme-color, #ea6f5a); - height: 2px; - left: 0px; - position: fixed; - right: 0px; - top: 0px; - -webkit-transition: width 0.2s, opacity 0.4s; - transition: width 0.2s, opacity 0.4s; - width: 0%; - z-index: 999999; -} -.search a:hover { - color: var(--theme-color, #ea6f5a); -} -.search .search-keyword { - color: var(--theme-color, #ea6f5a); - font-style: normal; - font-weight: bold; -} -html, -body { - height: 100%; -} -body { - -moz-osx-font-smoothing: grayscale; - -webkit-font-smoothing: antialiased; - color: #efefef; - font-family: 'Source Sans Pro', 'Helvetica Neue', Arial, sans-serif; - font-size: 15px; - letter-spacing: 0; - margin: 0; - overflow-x: hidden; -} -img { - max-width: 100%; -} -a[disabled] { - cursor: not-allowed; - opacity: 0.6; -} -kbd { - border: solid 1px #ccc; - border-radius: 3px; - display: inline-block; - font-size: 12px !important; - line-height: 12px; - margin-bottom: 3px; - padding: 3px 5px; - vertical-align: middle; -} -.task-list-item { - list-style-type: none; -} -li input[type='checkbox'] { - margin: 0 0.2em 0.25em -1.6em; - vertical-align: middle; -} -.app-nav { - margin: 25px 60px 0 0; - position: absolute; - right: 0; - text-align: right; - z-index: 10; -/* navbar dropdown */ -} -.app-nav.no-badge { - margin-right: 25px; -} -.app-nav p { - margin: 0; -} -.app-nav > a { - margin: 0 1rem; - padding: 5px 0; -} -.app-nav ul, -.app-nav li { - display: inline-block; - list-style: none; - margin: 0; -} -.app-nav a { - color: inherit; - font-size: 16px; - text-decoration: none; - -webkit-transition: color 0.3s; - transition: color 0.3s; -} -.app-nav a:hover { - color: var(--theme-color, #ea6f5a); -} -.app-nav a.active { - border-bottom: 2px solid var(--theme-color, #ea6f5a); - color: var(--theme-color, #ea6f5a); -} -.app-nav li { - display: inline-block; - margin: 0 1rem; - padding: 5px 0; - position: relative; -} -.app-nav li ul { - background-color: #fff; - border: 1px solid #ddd; - border-bottom-color: #ccc; - border-radius: 4px; - -webkit-box-sizing: border-box; - box-sizing: border-box; - display: none; - max-height: calc(100vh - 61px); - overflow-y: auto; - padding: 10px 0; - position: absolute; - right: -15px; - text-align: left; - top: 100%; - white-space: nowrap; -} -.app-nav li ul li { - display: block; - font-size: 14px; - line-height: 1rem; - margin: 0; - margin: 8px 14px; - white-space: nowrap; -} -.app-nav li ul a { - display: block; - font-size: inherit; - margin: 0; - padding: 0; -} -.app-nav li ul a.active { - border-bottom: 0; -} -.app-nav li:hover ul { - display: block; -} -.github-corner { - border-bottom: 0; - position: fixed; - right: 0; - text-decoration: none; - top: 0; - z-index: 1; -} -.github-corner:hover .octo-arm { - -webkit-animation: octocat-wave 560ms ease-in-out; - animation: octocat-wave 560ms ease-in-out; -} -.github-corner svg { - color: #3f3f3f; - fill: var(--theme-color, #ea6f5a); - height: 80px; - width: 80px; -} -main { - display: block; - position: relative; - width: 100vw; - height: 100%; - z-index: 0; -} -main.hidden { - display: none; -} -.anchor { - display: inline-block; - text-decoration: none; - -webkit-transition: all 0.3s; - transition: all 0.3s; -} -.anchor span { - color: #c8c8c8; -} -.anchor:hover { - text-decoration: underline; -} -.sidebar { - border-right: 1px solid rgba(0,0,0,0.07); - overflow-y: auto; - padding: 40px 0 0; - position: absolute; - top: 0; - bottom: 0; - left: 0; - -webkit-transition: -webkit-transform 250ms ease-out; - transition: -webkit-transform 250ms ease-out; - transition: transform 250ms ease-out; - transition: transform 250ms ease-out, -webkit-transform 250ms ease-out; - width: 300px; - z-index: 20; -} -.sidebar > h1 { - margin: 0 auto 1rem; - font-size: 1.5rem; - font-weight: 300; - text-align: center; -} -.sidebar > h1 a { - color: inherit; - text-decoration: none; -} -.sidebar > h1 .app-nav { - display: block; - position: static; -} -.sidebar .sidebar-nav { - line-height: 2em; - padding-bottom: 40px; -} -.sidebar li.collapse .app-sub-sidebar { - display: none; -} -.sidebar ul { - margin: 0; - padding: 0; -} -.sidebar li > p { - font-weight: 700; - margin: 0; -} -.sidebar ul, -.sidebar ul li { - list-style: none; -} -.sidebar ul li a { - border-bottom: none; - display: block; -} -.sidebar ul li ul { - padding-left: 20px; -} -.sidebar::-webkit-scrollbar { - width: 4px; -} -.sidebar::-webkit-scrollbar-thumb { - background: transparent; - border-radius: 4px; -} -.sidebar:hover::-webkit-scrollbar-thumb { - background: rgba(136,136,136,0.4); -} -.sidebar:hover::-webkit-scrollbar-track { - background: rgba(136,136,136,0.1); -} -.sidebar-toggle { - background-color: transparent; - background-color: rgba(63,63,63,0.8); - border: 0; - outline: none; - padding: 10px; - position: absolute; - bottom: 0; - left: 0; - text-align: center; - -webkit-transition: opacity 0.3s; - transition: opacity 0.3s; - width: 284px; - z-index: 30; -} -.sidebar-toggle .sidebar-toggle-button:hover { - opacity: 0.4; -} -.sidebar-toggle span { - background-color: var(--theme-color, #ea6f5a); - display: block; - margin-bottom: 4px; - width: 16px; - height: 2px; -} -body.sticky .sidebar, -body.sticky .sidebar-toggle { - position: fixed; -} -.content { - padding-top: 60px; - position: absolute; - top: 0; - right: 0; - bottom: 0; - left: 300px; - -webkit-transition: left 250ms ease; - transition: left 250ms ease; -} -.markdown-section { - margin: 0 auto; - max-width: 800px; - padding: 30px 15px 40px 15px; - position: relative; -} -.markdown-section > * { - -webkit-box-sizing: border-box; - box-sizing: border-box; - font-size: inherit; -} -.markdown-section > :first-child { - margin-top: 0 !important; -} -.markdown-section hr { - border: none; - border-bottom: 1px solid #eee; - margin: 2em 0; -} -.markdown-section iframe { - border: 1px solid #eee; -} -.markdown-section table { - border-collapse: collapse; - border-spacing: 0; - display: block; - margin-bottom: 1rem; - overflow: auto; - width: 100%; -} -.markdown-section th { - border: 1px solid #ddd; - font-weight: bold; - padding: 6px 13px; -} -.markdown-section td { - border: 1px solid #ddd; - padding: 6px 13px; -} -.markdown-section tr { - border-top: 1px solid #ccc; -} -.markdown-section tr:nth-child(2n) { - background-color: #555555; -} -.markdown-section p.tip { - background-color: #555555; - border-bottom-right-radius: 2px; - border-left: 4px solid #f66; - border-top-right-radius: 2px; - margin: 2em 0; - padding: 12px 24px 12px 30px; - position: relative; -} -.markdown-section p.tip:before { - background-color: #f66; - border-radius: 100%; - color: #3f3f3f; - content: '!'; - font-family: 'Dosis', 'Source Sans Pro', 'Helvetica Neue', Arial, sans-serif; - font-size: 14px; - font-weight: bold; - left: -12px; - line-height: 20px; - position: absolute; - height: 20px; - width: 20px; - text-align: center; - top: 14px; -} -.markdown-section p.tip code { - background-color: #efefef; -} -.markdown-section p.tip em { - color: #c8c8c8; -} -.markdown-section p.warn { - background: rgba(234,111,90,0.1); - border-radius: 2px; - padding: 1rem; -} -body.close .sidebar { - -webkit-transform: translateX(-300px); - transform: translateX(-300px); -} -body.close .sidebar-toggle { - width: auto; -} -body.close .content { - left: 0; -} -@media print { - .github-corner, - .sidebar-toggle, - .sidebar, - .app-nav { - display: none; - } -} -@media screen and (max-width: 768px) { - .github-corner, - .sidebar-toggle, - .sidebar { - position: fixed; - } - .app-nav { - margin-top: 16px; - } - .app-nav li ul { - top: 30px; - } - main { - height: auto; - overflow-x: hidden; - } - .sidebar { - left: -300px; - -webkit-transition: -webkit-transform 250ms ease-out; - transition: -webkit-transform 250ms ease-out; - transition: transform 250ms ease-out; - transition: transform 250ms ease-out, -webkit-transform 250ms ease-out; - } - .content { - left: 0; - max-width: 100vw; - position: static; - padding-top: 20px; - -webkit-transition: -webkit-transform 250ms ease; - transition: -webkit-transform 250ms ease; - transition: transform 250ms ease; - transition: transform 250ms ease, -webkit-transform 250ms ease; - } - .app-nav, - .github-corner { - -webkit-transition: -webkit-transform 250ms ease-out; - transition: -webkit-transform 250ms ease-out; - transition: transform 250ms ease-out; - transition: transform 250ms ease-out, -webkit-transform 250ms ease-out; - } - .sidebar-toggle { - background-color: transparent; - width: auto; - padding: 30px 30px 10px 10px; - } - body.close .sidebar { - -webkit-transform: translateX(300px); - transform: translateX(300px); - } - body.close .sidebar-toggle { - background-color: rgba(63,63,63,0.8); - -webkit-transition: 1s background-color; - transition: 1s background-color; - width: 284px; - padding: 10px; - } - body.close .content { - -webkit-transform: translateX(300px); - transform: translateX(300px); - } - body.close .app-nav, - body.close .github-corner { - display: none; - } - .github-corner:hover .octo-arm { - -webkit-animation: none; - animation: none; - } - .github-corner .octo-arm { - -webkit-animation: octocat-wave 560ms ease-in-out; - animation: octocat-wave 560ms ease-in-out; - } -} -@-webkit-keyframes octocat-wave { - 0%, 100% { - -webkit-transform: rotate(0); - transform: rotate(0); - } - 20%, 60% { - -webkit-transform: rotate(-25deg); - transform: rotate(-25deg); - } - 40%, 80% { - -webkit-transform: rotate(10deg); - transform: rotate(10deg); - } -} -@keyframes octocat-wave { - 0%, 100% { - -webkit-transform: rotate(0); - transform: rotate(0); - } - 20%, 60% { - -webkit-transform: rotate(-25deg); - transform: rotate(-25deg); - } - 40%, 80% { - -webkit-transform: rotate(10deg); - transform: rotate(10deg); - } -} -section.cover { - -webkit-box-align: center; - -ms-flex-align: center; - align-items: center; - background-position: center center; - background-repeat: no-repeat; - background-size: cover; - height: 100vh; - display: none; -} -section.cover.show { - display: -webkit-box; - display: -ms-flexbox; - display: flex; -} -section.cover.has-mask .mask { - background-color: #3f3f3f; - opacity: 0.8; - position: absolute; - top: 0; - height: 100%; - width: 100%; -} -section.cover .cover-main { - -webkit-box-flex: 1; - -ms-flex: 1; - flex: 1; - margin: -20px 16px 0; - text-align: center; - z-index: 1; -} -section.cover a { - color: inherit; - text-decoration: none; -} -section.cover a:hover { - text-decoration: none; -} -section.cover p { - line-height: 1.5rem; - margin: 1em 0; -} -section.cover h1 { - color: inherit; - font-size: 2.5rem; - font-weight: 300; - margin: 0.625rem 0 2.5rem; - position: relative; - text-align: center; -} -section.cover h1 a { - display: block; -} -section.cover h1 small { - bottom: -0.4375rem; - font-size: 1rem; - position: absolute; -} -section.cover blockquote { - font-size: 1.5rem; - text-align: center; -} -section.cover ul { - line-height: 1.8; - list-style-type: none; - margin: 1em auto; - max-width: 500px; - padding: 0; -} -section.cover .cover-main > p:last-child a { - border-color: var(--theme-color, #ea6f5a); - border-radius: 2rem; - border-style: solid; - border-width: 1px; - -webkit-box-sizing: border-box; - box-sizing: border-box; - color: var(--theme-color, #ea6f5a); - display: inline-block; - font-size: 1.05rem; - letter-spacing: 0.1rem; - margin: 0.5rem 1rem; - padding: 0.75em 2rem; - text-decoration: none; - -webkit-transition: all 0.15s ease; - transition: all 0.15s ease; -} -section.cover .cover-main > p:last-child a:last-child { - background-color: var(--theme-color, #ea6f5a); - color: #fff; -} -section.cover .cover-main > p:last-child a:last-child:hover { - color: inherit; - opacity: 0.8; -} -section.cover .cover-main > p:last-child a:hover { - color: inherit; -} -section.cover blockquote > p > a { - border-bottom: 2px solid var(--theme-color, #ea6f5a); - -webkit-transition: color 0.3s; - transition: color 0.3s; -} -section.cover blockquote > p > a:hover { - color: var(--theme-color, #ea6f5a); -} -body { - background-color: #3f3f3f; -} -/* sidebar */ -.sidebar { - background-color: #3f3f3f; - color: #c8c8c8; -} -.sidebar li { - margin: 6px 15px; -} -.sidebar ul li a { - color: #c8c8c8; - font-size: 14px; - overflow: hidden; - text-decoration: none; - text-overflow: ellipsis; - white-space: nowrap; -} -.sidebar ul li a:hover { - text-decoration: underline; -} -.sidebar ul li ul { - padding: 0; -} -.sidebar ul li.active > a { - color: var(--theme-color, #ea6f5a); - font-weight: 600; -} -/* markdown content found on pages */ -.markdown-section h1, -.markdown-section h2, -.markdown-section h3, -.markdown-section h4, -.markdown-section strong { - color: #657b83; - font-weight: 600; -} -.markdown-section a { - color: var(--theme-color, #ea6f5a); - font-weight: 600; -} -.markdown-section h1 { - font-size: 2rem; - margin: 0 0 1rem; -} -.markdown-section h2 { - font-size: 1.75rem; - margin: 45px 0 0.8rem; -} -.markdown-section h3 { - font-size: 1.5rem; - margin: 40px 0 0.6rem; -} -.markdown-section h4 { - font-size: 1.25rem; -} -.markdown-section h5 { - font-size: 1rem; -} -.markdown-section h6 { - color: #777; - font-size: 1rem; -} -.markdown-section figure, -.markdown-section p, -.markdown-section ul, -.markdown-section ol { - margin: 1.2em 0; -} -.markdown-section p, -.markdown-section ul, -.markdown-section ol { - line-height: 1.6rem; - word-spacing: 0.05rem; -} -.markdown-section ul, -.markdown-section ol { - padding-left: 1.5rem; -} -.markdown-section blockquote { - border-left: 4px solid var(--theme-color, #ea6f5a); - color: #858585; - margin: 2em 0; - padding-left: 20px; -} -.markdown-section blockquote p { - font-weight: 600; - margin-left: 0; -} -.markdown-section iframe { - margin: 1em 0; -} -.markdown-section em { - color: #7f8c8d; -} -.markdown-section code { - background-color: #282828; - border-radius: 2px; - color: #aaaaaa; - font-family: 'Roboto Mono', Monaco, courier, monospace; - font-size: 0.8rem; - margin: 0 2px; - padding: 3px 5px; - white-space: pre-wrap; -} -.markdown-section pre { - -moz-osx-font-smoothing: initial; - -webkit-font-smoothing: initial; - background-color: #282828; - font-family: 'Roboto Mono', Monaco, courier, monospace; - line-height: 1.5rem; - margin: 1.2em 0; - overflow: auto; - padding: 0 1.4rem; - position: relative; - word-wrap: normal; -} -/* code highlight */ -.token.comment, -.token.prolog, -.token.doctype, -.token.cdata { - color: #8e908c; -} -.token.namespace { - opacity: 0.7; -} -.token.boolean, -.token.number { - color: #c76b29; -} -.token.punctuation { - color: #525252; -} -.token.property { - color: #c08b30; -} -.token.tag { - color: #2973b7; -} -.token.string { - color: var(--theme-color, #ea6f5a); -} -.token.selector { - color: #6679cc; -} -.token.attr-name { - color: #2973b7; -} -.token.entity, -.token.url, -.language-css .token.string, -.style .token.string { - color: #22a2c9; -} -.token.attr-value, -.token.control, -.token.directive, -.token.unit { - color: var(--theme-color, #ea6f5a); -} -.token.keyword { - color: #e96900; -} -.token.statement, -.token.regex, -.token.atrule { - color: #22a2c9; -} -.token.placeholder, -.token.variable { - color: #3d8fd1; -} -.token.deleted { - text-decoration: line-through; -} -.token.inserted { - border-bottom: 1px dotted #202746; - text-decoration: none; -} -.token.italic { - font-style: italic; -} -.token.important, -.token.bold { - font-weight: bold; -} -.token.important { - color: #c94922; -} -.token.entity { - cursor: help; -} -.markdown-section pre > code { - -moz-osx-font-smoothing: initial; - -webkit-font-smoothing: initial; - background-color: #282828; - border-radius: 2px; - color: #657b83; - display: block; - font-family: 'Roboto Mono', Monaco, courier, monospace; - font-size: 0.8rem; - line-height: inherit; - margin: 0 2px; - max-width: inherit; - overflow: inherit; - padding: 2.2em 5px; - white-space: inherit; -} -.markdown-section code::after, -.markdown-section code::before { - letter-spacing: 0.05rem; -} -code .token { - -moz-osx-font-smoothing: initial; - -webkit-font-smoothing: initial; - min-height: 1.5rem; -} -pre::after { - color: #ccc; - content: attr(data-lang); - font-size: 0.6rem; - font-weight: 600; - height: 15px; - line-height: 15px; - padding: 5px 10px 0; - position: absolute; - right: 0; - text-align: right; - top: 0; -} -.markdown-section p.tip { - background-color: #282828; - color: #657b83; -} -input[type='search'] { - background: #4f4f4f; - border-color: #4f4f4f; - color: #c8c8c8; -} diff --git a/docs/qmk_custom_dark.css b/docs/qmk_custom_dark.css deleted file mode 100644 index ffa5539922..0000000000 --- a/docs/qmk_custom_dark.css +++ /dev/null @@ -1,45 +0,0 @@ -.sidebar li.active { - background-color: #555; -} - -.markdown-section tr:nth-child(2n) { - background-color:#444; -} - -.markdown-section p.tip { - background-color:#555; - color:#FFF; -} - -.markdown-section tr { - border-top: 1px solid #555; -} - -.markdown-section td, .markdown-section th { - border: 1px solid #555; -} - -.markdown-section p.tip code { - background-color: #333; - color: #fff; -} - -.page_toc code { - background-color: #555; -} - -.markdown-section hr, .search { - border-bottom: 1px solid #777 !important; -} - -.markdown-section p.warn > strong { - color: #c8c8c8; -} - -:root { - --docsifytabs-border-color: #555; - --docsifytabs-tab-highlight-color: var(--theme-color,#ea6f5a); - - --docsifytabs-tab-background: #444; - --docsifytabs-tab-background-active: #3f3f3f; -} diff --git a/docs/qmk_custom_light.css b/docs/qmk_custom_light.css deleted file mode 100644 index c65e54396d..0000000000 --- a/docs/qmk_custom_light.css +++ /dev/null @@ -1,58 +0,0 @@ -.sidebar-toggle { - position: absolute; - top: 0; - bottom: auto; - left: 0; -} - -.search { - margin-top: 40px; -} - -.markdown-section h2 { - padding-top: 0.25rem; -} - -.markdown-section h3 { - margin-top: 0.25rem; -} - -.sidebar, .sidebar-nav { - line-height: 1.5em !important; -} - -.markdown-section ul ul { - margin: 0; -} - -.markdown-section pre { - padding: 0; -} - -@media only screen and (min-width: 768px) { - .flex-container { - display:flex; - flex-flow:row; - } - .flex-container > p { - flex-basis: 100%; - flex: 1; - margin: 1em 2em 1em 2em; - } -} - -.docsify-tabs__tab:focus { - outline: none !important; -} - -.docsify-tabs__content .anchor { - transition: none; -} - -:root { - --docsifytabs-border-color: #ddd; - --docsifytabs-tab-highlight-color: var(--theme-color, #0074d9); - - --docsifytabs-tab-background: #f8f8f8; - --docsifytabs-tab-background-active: transparent; -} diff --git a/docs/quantum_keycodes.md b/docs/quantum_keycodes.md index a41681ac85..faad159fcb 100644 --- a/docs/quantum_keycodes.md +++ b/docs/quantum_keycodes.md @@ -6,7 +6,7 @@ All keycodes within quantum are numbers between `0x0000` and `0xFFFF`. Within yo On this page we have documented keycodes between `0x00FF` and `0xFFFF` which are used to implement advanced quantum features. If you define your own custom keycodes they will be put into this range as well. -## QMK Keycodes :id=qmk-keycodes +## QMK Keycodes {#qmk-keycodes} |Key |Aliases |Description | |-----------------|---------|-------------------------------------------------------------------------------------------------------------------------------------------------| @@ -16,4 +16,6 @@ On this page we have documented keycodes between `0x00FF` and `0xFFFF` which are |`QK_MAKE` | |Sends `qmk compile -kb (keyboard) -km (keymap)`, or `qmk flash` if shift is held. Puts keyboard into bootloader mode if shift & control are held | |`QK_REBOOT` |`QK_RBT` |Resets the keyboard. Does not load the bootloader | -!> Note: `QK_MAKE` requires `#define ENABLE_COMPILE_KEYCODE` in your config.h to function. +::: warning +Note: `QK_MAKE` requires `#define ENABLE_COMPILE_KEYCODE` in your config.h to function. +::: diff --git a/docs/quantum_painter.md b/docs/quantum_painter.md index 7f524b07ee..1d844d0f94 100644 --- a/docs/quantum_painter.md +++ b/docs/quantum_painter.md @@ -1,4 +1,4 @@ -# Quantum Painter :id=quantum-painter +# Quantum Painter {#quantum-painter} Quantum Painter is the standardised API for graphical displays. It currently includes support for basic drawing primitives, as well as custom images, animations, and fonts. @@ -13,7 +13,9 @@ QUANTUM_PAINTER_DRIVERS += ...... You will also likely need to select an appropriate driver in `rules.mk`, which is listed below. -!> Quantum Painter is not currently integrated with system-level operations such as when the keyboard goes into suspend. Users will need to handle this manually at the current time. +::: warning +Quantum Painter is not currently integrated with system-level operations such as when the keyboard goes into suspend. Users will need to handle this manually at the current time. +::: The QMK CLI can be used to convert from normal images such as PNG files or animated GIFs, as well as fonts from TTF files. @@ -35,7 +37,7 @@ Supported devices: | SSD1306 (I2C) | Monochrome OLED | 128x32 | I2C | `QUANTUM_PAINTER_DRIVERS += sh1106_i2c` | | Surface | Virtual | User-defined | None | `QUANTUM_PAINTER_DRIVERS += surface` | -## Quantum Painter Configuration :id=quantum-painter-config +## Quantum Painter Configuration {#quantum-painter-config} | Option | Default | Purpose | |---------------------------------------------------|---------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| @@ -54,11 +56,11 @@ Supported devices: Drivers have their own set of configurable options, and are described in their respective sections. -## Quantum Painter CLI Commands :id=quantum-painter-cli +## Quantum Painter CLI Commands {#quantum-painter-cli} - +:::::tabs -### ** `qmk painter-convert-graphics` ** +==== `qmk painter-convert-graphics` This command converts images to a format usable by QMK, i.e. the QGF File Format. @@ -109,7 +111,7 @@ Writing /home/qmk/qmk_firmware/keyboards/my_keeb/generated/my_image.qgf.h... Writing /home/qmk/qmk_firmware/keyboards/my_keeb/generated/my_image.qgf.c... ``` -### ** `qmk painter-make-font-image` ** +==== `qmk painter-make-font-image` This command converts a TTF font to an intermediate format for editing, before converting to the QFF File Format. @@ -142,7 +144,7 @@ The `UNICODE_GLYPHS` argument allows for specifying extra unicode glyphs to gene $ qmk painter-make-font-image --font NotoSans-ExtraCondensedBold.ttf --size 11 -o noto11.png --unicode-glyphs "ĄȽɂɻɣɈʣ" ``` -### ** `qmk painter-convert-font-image` ** +==== `qmk painter-convert-font-image` This command converts an intermediate font image to the QFF File Format. @@ -187,14 +189,13 @@ Writing /home/qmk/qmk_firmware/keyboards/my_keeb/generated/noto11.qff.h... Writing /home/qmk/qmk_firmware/keyboards/my_keeb/generated/noto11.qff.c... ``` - +::::: -## Quantum Painter Display Drivers :id=quantum-painter-drivers +## Quantum Painter Display Drivers {#quantum-painter-drivers} - +::::::tabs - -### ** LCD ** +===== LCD Most TFT display panels use a 5-pin interface -- SPI SCK, SPI MOSI, SPI CS, D/C, and RST pins. @@ -202,9 +203,9 @@ For these displays, QMK's `spi_master` must already be correctly configured for The pin assignments for SPI CS, D/C, and RST are specified during device construction. - +:::::tabs -#### ** GC9A01 ** +==== GC9A01 Enabling support for the GC9A01 in Quantum Painter is done by adding the following to `rules.mk`: @@ -230,7 +231,7 @@ The maximum number of displays can be configured by changing the following in yo Native color format rgb565 is compatible with GC9A01 -#### ** ILI9163 ** +==== ILI9163 Enabling support for the ILI9163 in Quantum Painter is done by adding the following to `rules.mk`: @@ -256,7 +257,7 @@ The maximum number of displays can be configured by changing the following in yo Native color format rgb565 is compatible with ILI9163 -#### ** ILI9341 ** +==== ILI9341 Enabling support for the ILI9341 in Quantum Painter is done by adding the following to `rules.mk`: @@ -282,7 +283,7 @@ The maximum number of displays can be configured by changing the following in yo Native color format rgb565 is compatible with ILI9341 -#### ** ILI9486 ** +==== ILI9486 Enabling support for the ILI9486 in Quantum Painter is done by adding the following to `rules.mk`: @@ -315,7 +316,7 @@ The maximum number of displays can be configured by changing the following in yo Native color format rgb888 is compatible with ILI9486 Native color format rgb565 is compatible with ILI9486 Waveshare -#### ** ILI9488 ** +==== ILI9488 Enabling support for the ILI9488 in Quantum Painter is done by adding the following to `rules.mk`: @@ -341,7 +342,7 @@ The maximum number of displays can be configured by changing the following in yo Native color format rgb888 is compatible with ILI9488 -#### ** ST7735 ** +==== ST7735 Enabling support for the ST7735 in Quantum Painter is done by adding the following to `rules.mk`: @@ -367,9 +368,11 @@ The maximum number of displays can be configured by changing the following in yo Native color format rgb565 is compatible with ST7735 -!> Some ST7735 devices are known to have different drawing offsets -- despite being a 132x162 pixel display controller internally, some display panels are only 80x160, or smaller. These may require an offset to be applied; see `qp_set_viewport_offsets` above for information on how to override the offsets if they aren't correctly rendered. +::: warning +Some ST7735 devices are known to have different drawing offsets -- despite being a 132x162 pixel display controller internally, some display panels are only 80x160, or smaller. These may require an offset to be applied; see `qp_set_viewport_offsets` above for information on how to override the offsets if they aren't correctly rendered. +::: -#### ** ST7789 ** +==== ST7789 Enabling support for the ST7789 in Quantum Painter is done by adding the following to `rules.mk`: @@ -395,11 +398,13 @@ The maximum number of displays can be configured by changing the following in yo Native color format rgb565 is compatible with ST7789 -!> Some ST7789 devices are known to have different drawing offsets -- despite being a 240x320 pixel display controller internally, some display panels are only 240x240, or smaller. These may require an offset to be applied; see `qp_set_viewport_offsets` above for information on how to override the offsets if they aren't correctly rendered. +::: warning +Some ST7789 devices are known to have different drawing offsets -- despite being a 240x320 pixel display controller internally, some display panels are only 240x240, or smaller. These may require an offset to be applied; see `qp_set_viewport_offsets` above for information on how to override the offsets if they aren't correctly rendered. +::: - +::::: -### ** OLED ** +===== OLED OLED displays tend to use 5-pin SPI when at larger resolutions, or when using color -- SPI SCK, SPI MOSI, SPI CS, D/C, and RST pins. Smaller OLEDs may use I2C instead. @@ -407,9 +412,9 @@ When using these displays, either `spi_master` or `i2c_master` must already be c For SPI, the pin assignments for SPI CS, D/C, and RST are specified during device construction -- for I2C the panel's address is specified instead. - +:::::tabs -#### ** SSD1351 ** +==== SSD1351 Enabling support for the SSD1351 in Quantum Painter is done by adding the following to `rules.mk`: @@ -435,7 +440,7 @@ The maximum number of displays can be configured by changing the following in yo Native color format rgb565 is compatible with SSD1351 -#### ** SH1106 ** +==== SH1106 Enabling support for the SH1106 in Quantum Painter is done by adding the following to `rules.mk`: @@ -469,17 +474,19 @@ The maximum number of displays of each type can be configured by changing the fo Native color format mono2 is compatible with SH1106 -#### ** SSD1306 ** +==== SSD1306 SSD1306 and SH1106 are almost entirely identical, to the point of being indisinguishable by Quantum Painter. Enable SH1106 support in Quantum Painter and create SH1106 devices in firmware to perform drawing operations on SSD1306 displays. - +::::: -### ** Surface ** +===== Surface Quantum Painter has a surface driver which is able to target a buffer in RAM. In general, surfaces keep track of the "dirty" region -- the area that has been drawn to since the last flush -- so that when transferring to the display they can transfer the minimal amount of data to achieve the end result. -!> These generally require significant amounts of RAM, so at large sizes and/or higher bit depths, they may not be usable on all MCUs. +::: warning +These generally require significant amounts of RAM, so at large sizes and/or higher bit depths, they may not be usable on all MCUs. +::: Enabling support for surfaces in Quantum Painter is done by adding the following to `rules.mk`: @@ -533,13 +540,17 @@ bool qp_surface_draw(painter_device_t surface, painter_device_t display, uint16_ The `surface` is the surface to copy out from. The `display` is the target display to draw into. `x` and `y` are the target location to draw the surface pixel data. Under normal circumstances, the location should be consistent, as the dirty region is calculated with respect to the `x` and `y` coordinates -- changing those will result in partial, overlapping draws. `entire_surface` whether the entire surface should be drawn, instead of just the dirty region. -!> The surface and display panel must have the same native pixel format. +::: warning +The surface and display panel must have the same native pixel format. +::: -?> Calling `qp_flush()` on the surface resets its dirty region. Copying the surface contents to the display also automatically resets the dirty region. +::: tip +Calling `qp_flush()` on the surface resets its dirty region. Copying the surface contents to the display also automatically resets the dirty region. +::: - +:::::: -## Quantum Painter Drawing API :id=quantum-painter-api +## Quantum Painter Drawing API {#quantum-painter-api} All APIs require a `painter_device_t` object as their first parameter -- this object comes from the specific device initialisation, and instructions on creating it can be found in each driver's respective section. @@ -548,13 +559,15 @@ To use any of the APIs, you need to include `qp.h`: #include ``` - +::::::tabs -### ** General Notes ** +===== General Notes The coordinate system used in Quantum Painter generally accepts `left`, `top`, `right`, and `bottom` instead of x/y/width/height, and each coordinate is inclusive of where pixels should be drawn. This is required as some datatypes used by display panels have a maximum value of `255` -- for any value or geometry extent that matches `256`, this would be represented as a `0`, instead. -?> Drawing a horizontal line 8 pixels long, starting from 4 pixels inside the left side of the display, will need `left=4`, `right=11`. +::: tip +Drawing a horizontal line 8 pixels long, starting from 4 pixels inside the left side of the display, will need `left=4`, `right=11`. +::: All color data matches the standard QMK HSV triplet definitions: @@ -562,13 +575,15 @@ All color data matches the standard QMK HSV triplet definitions: * Saturation is of the range `0...255` and is internally mapped to 0...100% saturation. * Value is of the range `0...255` and is internally mapped to 0...100% brightness. -?> Colors used in Quantum Painter are not subject to the RGB lighting CIE curve, if it is enabled. +::: tip +Colors used in Quantum Painter are not subject to the RGB lighting CIE curve, if it is enabled. +::: -### ** Device Control ** +===== Device Control - +:::::tabs -#### ** Display Initialisation ** +==== Display Initialisation ```c bool qp_init(painter_device_t device, painter_rotation_t rotation); @@ -584,7 +599,7 @@ void keyboard_post_init_kb(void) { } ``` -#### ** Display Power ** +==== Display Power ```c bool qp_power(painter_device_t device, bool power_on); @@ -592,7 +607,9 @@ bool qp_power(painter_device_t device, bool power_on); The `qp_power` function instructs the display whether or not the display panel should be on or off. -!> If there is a separate backlight controlled through the normal QMK backlight API, this is not controlled by the `qp_power` function and needs to be manually handled elsewhere. +::: warning +If there is a separate backlight controlled through the normal QMK backlight API, this is not controlled by the `qp_power` function and needs to be manually handled elsewhere. +::: ```c static uint8_t last_backlight = 255; @@ -615,7 +632,7 @@ void suspend_wakeup_init_user(void) { } ``` -#### ** Display Clear ** +==== Display Clear ```c bool qp_clear(painter_device_t device); @@ -623,7 +640,7 @@ bool qp_clear(painter_device_t device); The `qp_clear` function clears the display's screen. -#### ** Display Flush ** +==== Display Flush ```c bool qp_flush(painter_device_t device); @@ -631,7 +648,9 @@ bool qp_flush(painter_device_t device); The `qp_flush` function ensures that all drawing operations are "pushed" to the display. This should be done as the last operation whenever a sequence of draws occur, and guarantees that any changes are applied. -!> Some display panels may seem to work even without a call to `qp_flush` -- this may be because the driver cannot queue drawing operations and needs to display them immediately when invoked. In general, calling `qp_flush` at the end is still considered "best practice". +::: warning +Some display panels may seem to work even without a call to `qp_flush` -- this may be because the driver cannot queue drawing operations and needs to display them immediately when invoked. In general, calling `qp_flush` at the end is still considered "best practice". +::: ```c void housekeeping_task_user(void) { @@ -645,13 +664,13 @@ void housekeeping_task_user(void) { } ``` - +::::: -### ** Drawing Primitives ** +===== Drawing Primitives - +:::::tabs -#### ** Set Pixel ** +==== Set Pixel ```c bool qp_setpixel(painter_device_t device, uint16_t x, uint16_t y, uint8_t hue, uint8_t sat, uint8_t val); @@ -659,7 +678,9 @@ bool qp_setpixel(painter_device_t device, uint16_t x, uint16_t y, uint8_t hue, u The `qp_setpixel` can be used to set a specific pixel on the screen to the supplied color. -?> Using `qp_setpixel` for large amounts of drawing operations is inefficient and should be avoided unless they cannot be achieved with other drawing APIs. +::: tip +Using `qp_setpixel` for large amounts of drawing operations is inefficient and should be avoided unless they cannot be achieved with other drawing APIs. +::: ```c void housekeeping_task_user(void) { @@ -675,7 +696,7 @@ void housekeeping_task_user(void) { } ``` -#### ** Draw Line ** +==== Draw Line ```c bool qp_line(painter_device_t device, uint16_t x0, uint16_t y0, uint16_t x1, uint16_t y1, uint8_t hue, uint8_t sat, uint8_t val); @@ -697,7 +718,7 @@ void housekeeping_task_user(void) { } ``` -#### ** Draw Rect ** +==== Draw Rect ```c bool qp_rect(painter_device_t device, uint16_t left, uint16_t top, uint16_t right, uint16_t bottom, uint8_t hue, uint8_t sat, uint8_t val, bool filled); @@ -719,7 +740,7 @@ void housekeeping_task_user(void) { } ``` -#### ** Draw Circle ** +==== Draw Circle ```c bool qp_circle(painter_device_t device, uint16_t x, uint16_t y, uint16_t radius, uint8_t hue, uint8_t sat, uint8_t val, bool filled); @@ -741,7 +762,7 @@ void housekeeping_task_user(void) { } ``` -#### ** Draw Ellipse ** +==== Draw Ellipse ```c bool qp_ellipse(painter_device_t device, uint16_t x, uint16_t y, uint16_t sizex, uint16_t sizey, uint8_t hue, uint8_t sat, uint8_t val, bool filled); @@ -763,9 +784,9 @@ void housekeeping_task_user(void) { } ``` - +::::: -### ** Image Functions ** +===== Image Functions Making an image available for use requires compiling it into your firmware. To do so, assuming you've created `my_image.qgf.c` and `my_image.qgf.h` as per the CLI examples above, you'd add the following to your `rules.mk`: @@ -778,9 +799,9 @@ SRC += my_image.qgf.c #include "my_image.qgf.h" ``` - +:::::tabs -#### ** Load Image ** +==== Load Image ```c painter_image_handle_t qp_load_image_mem(const void *buffer); @@ -790,9 +811,11 @@ The `qp_load_image_mem` function loads a QGF image from memory or flash. `qp_load_image_mem` returns a handle to the loaded image, which can then be used to draw to the screen using `qp_drawimage`, `qp_drawimage_recolor`, `qp_animate`, or `qp_animate_recolor`. If an image is no longer required, it can be unloaded by calling `qp_close_image` below. -See the [CLI Commands](quantum_painter.md?id=quantum-painter-cli) for instructions on how to convert images to [QGF](quantum_painter_qgf.md). +See the [CLI Commands](quantum_painter#quantum-painter-cli) for instructions on how to convert images to [QGF](quantum_painter_qgf). -?> The total number of images available to load at any one time is controlled by the configurable option `QUANTUM_PAINTER_NUM_IMAGES` in the table above. If more images are required, the number should be increased in `config.h`. +::: tip +The total number of images available to load at any one time is controlled by the configurable option `QUANTUM_PAINTER_NUM_IMAGES` in the table above. If more images are required, the number should be increased in `config.h`. +::: Image information is available through accessing the handle: @@ -802,7 +825,7 @@ Image information is available through accessing the handle: | Height | `image->height` | | Frame Count | `image->frame_count` | -#### ** Unload Image ** +==== Unload Image ```c bool qp_close_image(painter_image_handle_t image); @@ -810,7 +833,7 @@ bool qp_close_image(painter_image_handle_t image); The `qp_close_image` function releases resources related to the loading of the supplied image. -#### ** Draw image ** +==== Draw image ```c bool qp_drawimage(painter_device_t device, uint16_t x, uint16_t y, painter_image_handle_t image); @@ -830,7 +853,7 @@ void keyboard_post_init_kb(void) { } ``` -#### ** Animate Image ** +==== Animate Image ```c deferred_token qp_animate(painter_device_t device, uint16_t x, uint16_t y, painter_image_handle_t image); @@ -855,7 +878,7 @@ void keyboard_post_init_kb(void) { } ``` -#### ** Stop Animation ** +==== Stop Animation ```c void qp_stop_animation(deferred_token anim_token); @@ -870,9 +893,9 @@ void housekeeping_task_user(void) { } ``` - +::::: -### ** Font Functions ** +===== Font Functions Making a font available for use requires compiling it into your firmware. To do so, assuming you've created `my_font.qff.c` and `my_font.qff.h` as per the CLI examples above, you'd add the following to your `rules.mk`: @@ -885,9 +908,9 @@ SRC += noto11.qff.c #include "noto11.qff.h" ``` - +:::::tabs -#### ** Load Font ** +==== Load Font ```c painter_font_handle_t qp_load_font_mem(const void *buffer); @@ -897,9 +920,11 @@ The `qp_load_font_mem` function loads a QFF font from memory or flash. `qp_load_font_mem` returns a handle to the loaded font, which can then be measured using `qp_textwidth`, or drawn to the screen using `qp_drawtext`, or `qp_drawtext_recolor`. If a font is no longer required, it can be unloaded by calling `qp_close_font` below. -See the [CLI Commands](quantum_painter.md?id=quantum-painter-cli) for instructions on how to convert TTF fonts to [QFF](quantum_painter_qff.md). +See the [CLI Commands](quantum_painter#quantum-painter-cli) for instructions on how to convert TTF fonts to [QFF](quantum_painter_qff). -?> The total number of fonts available to load at any one time is controlled by the configurable option `QUANTUM_PAINTER_NUM_FONTS` in the table above. If more fonts are required, the number should be increased in `config.h`. +::: tip +The total number of fonts available to load at any one time is controlled by the configurable option `QUANTUM_PAINTER_NUM_FONTS` in the table above. If more fonts are required, the number should be increased in `config.h`. +::: Font information is available through accessing the handle: @@ -907,7 +932,7 @@ Font information is available through accessing the handle: |-------------|----------------------| | Line Height | `image->line_height` | -#### ** Unload Font ** +==== Unload Font ```c bool qp_close_font(painter_font_handle_t font); @@ -915,7 +940,7 @@ bool qp_close_font(painter_font_handle_t font); The `qp_close_font` function releases resources related to the loading of the supplied font. -#### ** Measure Text ** +==== Measure Text ```c int16_t qp_textwidth(painter_font_handle_t font, const char *str); @@ -923,7 +948,7 @@ int16_t qp_textwidth(painter_font_handle_t font, const char *str); The `qp_textwidth` function allows measurement of how many pixels wide the supplied string would result in, for the given font. -#### ** Draw Text ** +==== Draw Text ```c int16_t qp_drawtext(painter_device_t device, uint16_t x, uint16_t y, painter_font_handle_t font, const char *str); @@ -945,49 +970,49 @@ void keyboard_post_init_kb(void) { } ``` - +::::: -### ** Advanced Functions ** +===== Advanced Functions - +:::::tabs -#### ** Gettters ** +==== Getters These functions allow external code to retrieve the current width, height, rotation, and drawing offsets. - +::::tabs -#### ** Width ** +=== Width ```c uint16_t qp_get_width(painter_device_t device); ``` -#### ** Height ** +=== Height ```c uint16_t qp_get_height(painter_device_t device); ``` -#### ** Rotation ** +=== Rotation ```c painter_rotation_t qp_get_rotation(painter_device_t device); ``` -#### ** Offset X ** +=== Offset X ```c uint16_t qp_get_offset_x(painter_device_t device); ``` -#### ** Offset Y ** +=== Offset Y ```c uint16_t qp_get_offset_y(painter_device_t device); ``` -##### ** Everything ** +=== Everything Convenience function to call all the previous ones at once. Note: You can pass `NULL` for the values you are not interested in. @@ -996,9 +1021,9 @@ Note: You can pass `NULL` for the values you are not interested in. void qp_get_geometry(painter_device_t device, uint16_t *width, uint16_t *height, painter_rotation_t *rotation, uint16_t *offset_x, uint16_t *offset_y); ``` - +:::: -#### ** Set Viewport Offsets ** +==== Set Viewport Offsets ```c void qp_set_viewport_offsets(painter_device_t device, uint16_t offset_x, uint16_t offset_y); @@ -1006,7 +1031,7 @@ void qp_set_viewport_offsets(painter_device_t device, uint16_t offset_x, uint16_ The `qp_set_viewport_offsets` function can be used to offset all subsequent drawing operations. For example, if a display controller is internally 240x320, but the display panel is 240x240 and has a Y offset of 80 pixels, you could invoke `qp_set_viewport_offsets(display, 0, 80);` and the drawing positioning would be corrected. -#### ** Set Viewport ** +==== Set Viewport ```c bool qp_viewport(painter_device_t device, uint16_t left, uint16_t top, uint16_t right, uint16_t bottom); @@ -1014,7 +1039,7 @@ bool qp_viewport(painter_device_t device, uint16_t left, uint16_t top, uint16_t The `qp_viewport` function controls where raw pixel data is written to. -#### ** Stream Pixel Data ** +==== Stream Pixel Data ```c bool qp_pixdata(painter_device_t device, const void *pixel_data, uint32_t native_pixel_count); @@ -1022,8 +1047,10 @@ bool qp_pixdata(painter_device_t device, const void *pixel_data, uint32_t native The `qp_pixdata` function allows raw pixel data to be streamed to the display. It requires a native pixel count rather than the number of bytes to transfer, to ensure display panel data alignment is respected. E.g. for display panels using RGB565 internal format, sending 10 pixels will result in 20 bytes of transfer. -!> Under normal circumstances, users will not need to manually call either `qp_viewport` or `qp_pixdata`. These allow for writing of raw pixel information, in the display panel's native format, to the area defined by the viewport. +::: warning +Under normal circumstances, users will not need to manually call either `qp_viewport` or `qp_pixdata`. These allow for writing of raw pixel information, in the display panel's native format, to the area defined by the viewport. +::: - +::::: - +:::::: diff --git a/docs/quantum_painter_lvgl.md b/docs/quantum_painter_lvgl.md index b4f31ad4af..40b3c3b2f1 100644 --- a/docs/quantum_painter_lvgl.md +++ b/docs/quantum_painter_lvgl.md @@ -1,14 +1,16 @@ -# Quantum Painter LVGL Integration :id=lvgl +# Quantum Painter LVGL Integration {#lvgl} LVGL (Light and Versatile Graphics Library) is an open-source graphics library providing everything you need to create an embedded GUI for your board with easy-to-use graphical elements. -LVGL integrates with [Quantum Painter's](quantum_painter.md) API and drivers to render to the display, the hardware supported by Quantum Painter is also supported by LVGL. +LVGL integrates with [Quantum Painter's](quantum_painter) API and drivers to render to the display, the hardware supported by Quantum Painter is also supported by LVGL. -?> Keep in mind that enabling the LVGL integration has a big impact in firmware size, it is recommeded to use a supported MCU with >256 kB of flash space. +::: tip +Keep in mind that enabling the LVGL integration has a big impact in firmware size, it is recommeded to use a supported MCU with >256 kB of flash space. +::: To learn more about LVGL and how to use it please take a look at their [official documentation](https://docs.lvgl.io/8.2/intro/) -## Enabling LVGL :id=lvgl-enabling +## Enabling LVGL {#lvgl-enabling} To enable LVGL to be built into your firmware, add the following to `rules.mk`: ```make @@ -16,11 +18,11 @@ QUANTUM_PAINTER_ENABLE = yes QUANTUM_PAINTER_DRIVERS = ...... QUANTUM_PAINTER_LVGL_INTEGRATION = yes ``` -To configure the Quantum Painter Display Drivers please read the [Quantum Painter Display Drivers](quantum_painter.md#quantum-painter-drivers) section. +To configure the Quantum Painter Display Drivers please read the [Quantum Painter Display Drivers](quantum_painter#quantum-painter-drivers) section. -## Quantum Painter LVGL API :id=lvgl-api +## Quantum Painter LVGL API {#lvgl-api} -### Quantum Painter LVGL Attach :id=lvgl-api-init +### Quantum Painter LVGL Attach {#lvgl-api-init} ```c bool qp_lvgl_attach(painter_device_t device); @@ -39,10 +41,13 @@ void keyboard_post_init_kb(void) { } } ``` -To init. the display please read the [Display Initialisation](quantum_painter.md#quantum-painter-api-init) section. +To init. the display please read the [Display Initialisation](quantum_painter#quantum-painter-api-init) section. -!> Attaching LVGL to a display means LVGL subsequently "owns" the display. Using standard Quantum Painter drawing operations with the display after LVGL attachment will likely result in display artifacts. -### Quantum Painter LVGL Detach :id=lvgl-api-init +::: warning +Attaching LVGL to a display means LVGL subsequently "owns" the display. Using standard Quantum Painter drawing operations with the display after LVGL attachment will likely result in display artifacts. +::: + +### Quantum Painter LVGL Detach {#lvgl-api-detach} ```c void qp_lvgl_detach(void) @@ -50,7 +55,7 @@ void qp_lvgl_detach(void) The `qp_lvgl_detach` function stops the internal LVGL ticks and releases resources related to it. -## Enabling/Disabling LVGL features :id=lvgl-configuring +## Enabling/Disabling LVGL features {#lvgl-configuring} You can overwrite LVGL specific features in your `lv_conf.h` file. diff --git a/docs/quantum_painter_qff.md b/docs/quantum_painter_qff.md index f62d59bdcb..3695be2c5b 100644 --- a/docs/quantum_painter_qff.md +++ b/docs/quantum_painter_qff.md @@ -1,4 +1,4 @@ -# QMK Font Format :id=qmk-font-format +# QMK Font Format {#qmk-font-format} QMK uses a font format _("Quantum Font Format" - QFF)_ specifically for resource-constrained systems. @@ -16,11 +16,11 @@ The general structure of the file is: * _Font palette block_ (optional, depending on frame format) * _Font data block_ -## Block Header :id=qff-block-header +## Block Header {#qff-block-header} -The block header is identical to [QGF's block header](quantum_painter_qgf.md#qgf-block-header), and is present for all blocks, including the font descriptor. +The block header is identical to [QGF's block header](quantum_painter_qgf#qgf-block-header), and is present for all blocks, including the font descriptor. -## Font descriptor block :id=qff-font-descriptor +## Font descriptor block {#qff-font-descriptor} * _typeid_ = 0x00 * _length_ = 20 @@ -47,9 +47,9 @@ typedef struct __attribute__((packed)) qff_font_descriptor_v1_t { // _Static_assert(sizeof(qff_font_descriptor_v1_t) == (sizeof(qgf_block_header_v1_t) + 20), "qff_font_descriptor_v1_t must be 25 bytes in v1 of QFF"); ``` -The values for `format`, `flags`, `compression_scheme`, and `transparency_index` match [QGF's frame descriptor block](quantum_painter_qgf.md#qgf-frame-descriptor), with the exception that the `delta` flag is ignored by QFF. +The values for `format`, `flags`, `compression_scheme`, and `transparency_index` match [QGF's frame descriptor block](quantum_painter_qgf#qgf-frame-descriptor), with the exception that the `delta` flag is ignored by QFF. -## ASCII glyph table :id=qff-ascii-table +## ASCII glyph table {#qff-ascii-table} * _typeid_ = 0x01 * _length_ = 290 @@ -69,7 +69,7 @@ typedef struct __attribute__((packed)) qff_ascii_glyph_table_v1_t { // _Static_assert(sizeof(qff_ascii_glyph_table_v1_t) == (sizeof(qgf_block_header_v1_t) + 285), "qff_ascii_glyph_table_v1_t must be 290 bytes in v1 of QFF"); ``` -## Unicode glyph table :id=qff-unicode-table +## Unicode glyph table {#qff-unicode-table} * _typeid_ = 0x02 * _length_ = variable @@ -86,18 +86,18 @@ typedef struct __attribute__((packed)) qff_unicode_glyph_table_v1_t { } qff_unicode_glyph_table_v1_t; ``` -## Font palette block :id=qff-palette-descriptor +## Font palette block {#qff-palette-descriptor} * _typeid_ = 0x03 * _length_ = variable -The _font palette block_ is identical to [QGF's frame palette block](quantum_painter_qgf.md#qgf-frame-palette-descriptor), retaining the same _typeid_ of 0x03. +The _font palette block_ is identical to [QGF's frame palette block](quantum_painter_qgf#qgf-frame-palette-descriptor), retaining the same _typeid_ of 0x03. It is only specified in the QFF if the font is palette-based, and follows the _unicode glyph block_ if the font contains any Unicode glyphs, or the _ASCII glyph block_ if the font contains only ASCII glyphs. -## Font data block :id=qff-data-descriptor +## Font data block {#qff-data-descriptor} * _typeid_ = 0x04 * _length_ = variable -The _font data block_ is the last block in the file and is identical to [QGF's frame data block](quantum_painter_qgf.md#qgf-frame-data-descriptor), however has a different _typeid_ of 0x04 in QFF. +The _font data block_ is the last block in the file and is identical to [QGF's frame data block](quantum_painter_qgf#qgf-frame-data-descriptor), however has a different _typeid_ of 0x04 in QFF. diff --git a/docs/quantum_painter_qgf.md b/docs/quantum_painter_qgf.md index caf6731e65..700b78d105 100644 --- a/docs/quantum_painter_qgf.md +++ b/docs/quantum_painter_qgf.md @@ -1,4 +1,4 @@ -# QMK Graphics Format :id=qmk-graphics-format +# QMK Graphics Format {#qmk-graphics-format} QMK uses a graphics format _("Quantum Graphics Format" - QGF)_ specifically for resource-constrained systems. @@ -20,7 +20,7 @@ The general structure of the file is: Different frames within the file should be considered "isolated" and may have their own image format and/or palette. -## Block Header :id=qgf-block-header +## Block Header {#qgf-block-header} This block header is present for all blocks, including the graphics descriptor. @@ -36,7 +36,7 @@ typedef struct __attribute__((packed)) qgf_block_header_v1_t { ``` The _length_ describes the number of octets in the data following the block header -- a block header may specify a _length_ of `0` if no blob is specified. -## Graphics descriptor block :id=qgf-graphics-descriptor +## Graphics descriptor block {#qgf-graphics-descriptor} * _typeid_ = 0x00 * _length_ = 18 @@ -59,7 +59,7 @@ typedef struct __attribute__((packed)) qgf_graphics_descriptor_v1_t { // _Static_assert(sizeof(qgf_graphics_descriptor_v1_t) == (sizeof(qgf_block_header_v1_t) + 18), "qgf_graphics_descriptor_v1_t must be 23 bytes in v1 of QGF"); ``` -## Frame offset block :id=qgf-frame-offset-descriptor +## Frame offset block {#qgf-frame-offset-descriptor} * _typeid_ = 0x01 * _length_ = variable @@ -77,7 +77,7 @@ typedef struct __attribute__((packed)) qgf_frame_offsets_v1_t { } qgf_frame_offsets_v1_t; ``` -## Frame descriptor block :id=qgf-frame-descriptor +## Frame descriptor block {#qgf-frame-descriptor} * _typeid_ = 0x02 * _length_ = 5 @@ -125,9 +125,9 @@ Frame flags is a bitmask with the following format: Compression scheme possible values: * `0x00`: No compression -* `0x01`: [QMK RLE](quantum_painter_rle.md) +* `0x01`: [QMK RLE](quantum_painter_rle) -## Frame palette block :id=qgf-frame-palette-descriptor +## Frame palette block {#qgf-frame-palette-descriptor} * _typeid_ = 0x03 * _length_ = variable @@ -145,7 +145,7 @@ typedef struct __attribute__((packed)) qgf_palette_v1_t { } qgf_palette_v1_t; ``` -## Frame delta block :id=qgf-frame-delta-descriptor +## Frame delta block {#qgf-frame-delta-descriptor} * _typeid_ = 0x04 * _length_ = 8 @@ -163,7 +163,7 @@ typedef struct __attribute__((packed)) qgf_delta_v1_t { // _Static_assert(sizeof(qgf_delta_v1_t) == 13, "qgf_delta_v1_t must be 13 bytes in v1 of QGF"); ``` -## Frame data block :id=qgf-frame-data-descriptor +## Frame data block {#qgf-frame-data-descriptor} * _typeid_ = 0x05 * _length_ = variable diff --git a/docs/quantum_painter_rle.md b/docs/quantum_painter_rle.md index dcb9a1e1a7..9c13ad6ada 100644 --- a/docs/quantum_painter_rle.md +++ b/docs/quantum_painter_rle.md @@ -1,6 +1,6 @@ -# QMK QGF/QFF RLE data schema :id=qmk-qp-rle-schema +# QMK QGF/QFF RLE data schema {#qmk-qp-rle-schema} -There are two "modes" to the RLE algorithm used in both [QGF](quantum_painter_qgf.md)/[QFF](quantum_painter_qff.md): +There are two "modes" to the RLE algorithm used in both [QGF](quantum_painter_qgf)/[QFF](quantum_painter_qff): * Non-repeating sections of octets, with associated length of up to `128` octets * `length` = `marker - 128` diff --git a/docs/redirects.json b/docs/redirects.json deleted file mode 100644 index 651148c2c1..0000000000 --- a/docs/redirects.json +++ /dev/null @@ -1,52 +0,0 @@ -{ - "redirects": [ - { - "from": "adding_a_keyboard_to_qmk.html", - "to": "hardware_keyboard_guidelines.html" - }, - { - "from": "build_environment_setup.html", - "to": "getting_started_build_tools.html" - }, - { - "from": "dynamic_macros.html", - "to": "feature_dynamic_macros.html" - }, - { - "from": "feature_common_shortcuts.html", - "to": "feature_advanced_keycodes.html" - }, - { - "from": "glossary.html", - "to": "reference_glossary.html" - }, - { - "from": "key_lock.html", - "to": "feature_key_lock.html" - }, - { - "from": "make_instructions.html", - "to": "getting_started_make_guide.html" - }, - { - "from": "porting_your_keyboard_to_qmk.html", - "to": "hardware_avr.html" - }, - { - "from": "space_cadet_shift.html", - "to": "feature_space_cadet_shift.html" - }, - { - "from": "tap_dance.html", - "to": "feature_tap_dance.html" - }, - { - "from": "unicode.html", - "to": "feature_unicode.html" - }, - { - "from": "python_development.html", - "to": "cli_development.html" - } - ] -} diff --git a/docs/ref_functions.md b/docs/ref_functions.md index c82c5747c2..156c9ed20b 100644 --- a/docs/ref_functions.md +++ b/docs/ref_functions.md @@ -2,7 +2,7 @@ There are a lot of hidden functions in QMK that are incredibly useful, or may add a bit of functionality that you've been wanting. Functions that are specific to certain features are not included here, as those will be on their respective feature page. -## (OLKB) Tri Layers :id=olkb-tri-layers +## (OLKB) Tri Layers {#olkb-tri-layers} There are actually separate functions that you can use there, depending on what you're after. @@ -41,7 +41,7 @@ bool process_record_user(uint16_t keycode, keyrecord_t *record) { ``` ### `update_tri_layer_state(state, x, y, z)` -The other function is `update_tri_layer_state(state, x, y, z)`. This function is meant to be called from the [`layer_state_set_*` functions](custom_quantum_functions.md#layer-change-code). This means that any time that you use a keycode to change the layer, this will be checked. So you could use `LT(layer, kc)` to change the layer and it will trigger the same layer check. +The other function is `update_tri_layer_state(state, x, y, z)`. This function is meant to be called from the [`layer_state_set_*` functions](custom_quantum_functions#layer-change-code). This means that any time that you use a keycode to change the layer, this will be checked. So you could use `LT(layer, kc)` to change the layer and it will trigger the same layer check. There are a couple of caveats to this method: 1. You cannot access the `z` layer without having `x` and `y` layers on, since if you try to activate just layer `z`, it will run this code and turn off layer `z` before you could use it. @@ -71,7 +71,7 @@ Do you want to set the default layer, so that it's retained even after you unplu To use this, you would use `set_single_persistent_default_layer(layer)`. If you have a name defined for your layer, you can use that instead (such as _QWERTY, _DVORAK or _COLEMAK). -This will set the default layer, update the persistent settings, and play a tune if you have [Audio](feature_audio.md) enabled on your board, and the default layer sounds set. +This will set the default layer, update the persistent settings, and play a tune if you have [Audio](feature_audio) enabled on your board, and the default layer sounds set. To configure the default layer sounds, you would want to define this in your `config.h` file, like this: @@ -83,7 +83,9 @@ To configure the default layer sounds, you would want to define this in your `co ``` -?> There are a large number of predefined songs in [quantum/audio/song_list.h](https://github.com/qmk/qmk_firmware/blob/master/quantum/audio/song_list.h) that you can use. +::: tip +There are a large number of predefined songs in [quantum/audio/song_list.h](https://github.com/qmk/qmk_firmware/blob/master/quantum/audio/song_list.h) that you can use. +::: ## Resetting the keyboard @@ -97,7 +99,7 @@ To reset to the bootloader use `QK_BOOTLOADER` or `QK_BOOT` keycode or `reset_ke ## Wiping the EEPROM (Persistent Storage) -If you're having issues with Audio, RGB Underglow, backlighting or keys acting weird, then you can reset the EEPROM (persistent setting storage). To force an EEPROM reset, use the [`EE_CLR` keycode](quantum_keycodes.md) or [Bootmagic Lite](feature_bootmagic.md) functionality. If neither of those are an option, then you can use a custom macro to do so. +If you're having issues with Audio, RGB Underglow, backlighting or keys acting weird, then you can reset the EEPROM (persistent setting storage). To force an EEPROM reset, use the [`EE_CLR` keycode](quantum_keycodes) or [Bootmagic Lite](feature_bootmagic) functionality. If neither of those are an option, then you can use a custom macro to do so. To wipe the EEPROM, run `eeconfig_init()` from your function or macro to reset most of the settings to default. @@ -105,7 +107,9 @@ To wipe the EEPROM, run `eeconfig_init()` from your function or macro to reset m If you want to send a random character to the host computer, you can use the `tap_random_base64()` function. This [pseudorandomly](https://en.wikipedia.org/wiki/Pseudorandom_number_generator) selects a number between 0 and 63, and then sends a key press based on that selection. (0–25 is `A`–`Z`, 26–51 is `a`–`z`, 52–61 is `0`–`9`, 62 is `+` and 63 is `/`). -?> Needless to say, but this is _not_ a cryptographically secure method of generating random Base64 keys or passwords. +::: tip +Needless to say, but this is _not_ a cryptographically secure method of generating random Base64 keys or passwords. +::: ## Software Timers diff --git a/docs/reference_configurator_support.md b/docs/reference_configurator_support.md index db6cd80a20..dffed5c0c3 100644 --- a/docs/reference_configurator_support.md +++ b/docs/reference_configurator_support.md @@ -21,7 +21,9 @@ To understand how the Configurator understands keyboards, first one must underst |---------------| ``` -?> For more on layout macros, see [Understanding QMK: Matrix Scanning](understanding_qmk.md?id=matrix-scanning) and [Understanding QMK: Matrix to Physical Layout Map](understanding_qmk.md?id=matrix-to-physical-layout-map). +::: tip +For more on layout macros, see [Understanding QMK: Matrix Scanning](understanding_qmk#matrix-scanning) and [Understanding QMK: Matrix to Physical Layout Map](understanding_qmk#matrix-to-physical-layout-map). +::: The Configurator's API reads the keyboard's `.h` file from `qmk_firmware/keyboards//.h`. For our numpad, this file would be `qmk_firmware/keyboards/numpad/numpad.h`: @@ -65,9 +67,13 @@ QMK uses `KC_NO` to designate places in the switch matrix where there is no swit } ``` -!> This usage differs from that of keymap macros, which almost always use `XXXXXXX` (seven capital X's) for `KC_NO` and `_______` (seven underscores) for `KC_TRNS`. +::: warning +This usage differs from that of keymap macros, which almost always use `XXXXXXX` (seven capital X's) for `KC_NO` and `_______` (seven underscores) for `KC_TRNS`. +::: -!> To prevent user confusion, using `KC_NO` is preferred. +::: warning +To prevent user confusion, using `KC_NO` is preferred. +::: The layout macro tells the Configurator that our keyboard has 17 keys, arranged in five rows of four columns each. Our switch positions are named `k`, counting from 0. The names themselves actually don't matter, as long as they match between the top section, which receives the keycodes from the keymap, and the bottom half which designates where each key is in the matrix. @@ -141,7 +147,9 @@ The `layouts` object contains the data that represents the physical layout of th Some objects will also have `"w"` and `"h"` keys, which represent a key's width and height, respectively. -?> For more on the `info.json` files, see [`info.json` Format](reference_info_json.md). +::: tip +For more on the `info.json` files, see [`info.json` Format](reference_info_json). +::: ## How the Configurator Programs Keys diff --git a/docs/reference_glossary.md b/docs/reference_glossary.md index 31855606be..cf8c8f0d75 100644 --- a/docs/reference_glossary.md +++ b/docs/reference_glossary.md @@ -36,12 +36,12 @@ An alternative keyboard layout developed by Dr. August Dvorak in the 1930's. A s ## Dynamic Macro A macro which has been recorded on the keyboard and which will be lost when the keyboard is unplugged or the computer rebooted. -* [Dynamic Macro Documentation](feature_dynamic_macros.md) +* [Dynamic Macro Documentation](feature_dynamic_macros) ## Eclipse An IDE that is popular with many C developers. -* [Eclipse Setup Instructions](other_eclipse.md) +* [Eclipse Setup Instructions](other_eclipse) ## Firmware The software that controls your MCU. @@ -59,7 +59,7 @@ In-system programming, a method of programming an AVR chip using external hardwa An interface for receiving debugging messages from your keyboard. You can view these messages using [QMK Flasher](https://github.com/qmk/qmk_flasher) or [PJRC's hid_listen](https://www.pjrc.com/teensy/hid_listen.html) ## Keycode -A 2-byte number that represents a particular key. `0x00`-`0xFF` are used for [Basic Keycodes](keycodes_basic.md) while `0x100`-`0xFFFF` are used for [Quantum Keycodes](quantum_keycodes.md). +A 2-byte number that represents a particular key. `0x00`-`0xFF` are used for [Basic Keycodes](keycodes_basic) while `0x100`-`0xFFFF` are used for [Quantum Keycodes](quantum_keycodes). ## Key Down An event that happens when a key is pressed down, but is completed before a key is released. @@ -76,7 +76,7 @@ An abstraction used to allow a key to serve multiple purposes. The highest activ ## Leader Key A feature that allows you to tap the leader key followed by a sequence of 1, 2, or 3 keys to activate key presses or other quantum features. -* [Leader Key Documentation](feature_leader_key.md) +* [Leader Key Documentation](feature_leader_key) ## LED Light Emitting Diode, the most common device used for indicators on a keyboard. @@ -90,7 +90,7 @@ A wiring pattern of columns and rows that enables the MCU to detect keypresses w ## Macro A feature that lets you send multiple keypress events (hid reports) after having pressed only a single key. -* [Macro Documentation](feature_macros.md) +* [Macro Documentation](feature_macros) ## MCU Microcontrol Unit, the processor that powers your keyboard. @@ -101,7 +101,7 @@ A key that is held down while typing another key to modify the action of that ke ## Mousekeys A feature that lets you control your mouse cursor and click from your keyboard. -* [Mousekeys Documentation](feature_mouse_keys.md) +* [Mousekeys Documentation](feature_mouse_keys) ## N-Key Rollover (NKRO) A term that applies to keyboards that are capable of reporting any number of key-presses at once. @@ -130,7 +130,7 @@ A 1 byte number that is sent as part of a HID report over USB that represents a ## Space Cadet Shift A special set of shift keys which allow you to type various types of braces by tapping the left or right shift one or more times. -* [Space Cadet Shift Documentation](feature_space_cadet.md) +* [Space Cadet Shift Documentation](feature_space_cadet) ## Tap Pressing and releasing a key. In some situations you will need to distinguish between a key down and a key up event, and Tap always refers to both at once. @@ -138,7 +138,7 @@ Pressing and releasing a key. In some situations you will need to distinguish be ## Tap Dance A feature that lets you assign multiple keycodes to the same key based on how many times you press it. -* [Tap Dance Documentation](feature_tap_dance.md) +* [Tap Dance Documentation](feature_tap_dance) ## Teensy A low-cost AVR development board that is commonly used for hand-wired builds. A teensy is often chosen despite costing a few dollars more due to its halfkay bootloader, which makes flashing very simple. @@ -149,12 +149,12 @@ A generic term for LEDs that light the underside of the board. These LEDs typica ## Unicode In the larger computer world Unicode is a set of encoding schemes for representing characters in any language. As it relates to QMK it means using various OS schemes to send unicode codepoints instead of scancodes. -* [Unicode Documentation](feature_unicode.md) +* [Unicode Documentation](feature_unicode) ## Unit Testing A framework for running automated tests against QMK. Unit testing helps us be confident that our changes do not break anything. -* [Unit Testing Documentation](unit_testing.md) +* [Unit Testing Documentation](unit_testing) ## USB Universal Serial Bus, the most common wired interface for a keyboard. diff --git a/docs/reference_info_json.md b/docs/reference_info_json.md index 8a2ded95f7..25d2e9d1d8 100644 --- a/docs/reference_info_json.md +++ b/docs/reference_info_json.md @@ -1,10 +1,10 @@ -# `info.json` Reference :id=info-json-reference +# `info.json` Reference {#info-json-reference} -The information contained in `info.json` is combined with the `config.h` and `rules.mk` files, dynamically generating the necessary configuration for your keyboard at compile time. It is also used by the [QMK API](https://github.com/qmk/qmk_api), and contains the information [QMK Configurator](https://config.qmk.fm/) needs to display a representation of your keyboard. Its key/value pairs are ruled by the [`data/schemas/keyboard.jsonschema`](https://github.com/qmk/qmk_firmware/blob/master/data/schemas/keyboard.jsonschema) file. To learn more about the why and how of the schema file see the [Data Driven Configuration](https://docs.qmk.fm/#/data_driven_config) page. +The information contained in `info.json` is combined with the `config.h` and `rules.mk` files, dynamically generating the necessary configuration for your keyboard at compile time. It is also used by the [QMK API](https://github.com/qmk/qmk_api), and contains the information [QMK Configurator](https://config.qmk.fm/) needs to display a representation of your keyboard. Its key/value pairs are ruled by the [`data/schemas/keyboard.jsonschema`](https://github.com/qmk/qmk_firmware/blob/master/data/schemas/keyboard.jsonschema) file. To learn more about the why and how of the schema file see the [Data Driven Configuration](data_driven_config) page. You can create `info.json` files at every level under `qmk_firmware/keyboards/`. These files are combined, with more specific files overriding keys in less specific files. This means you do not need to duplicate your metadata information. For example, `qmk_firmware/keyboards/clueboard/info.json` specifies information common to all Clueboard products, such as `manufacturer` and `maintainer`, while `qmk_firmware/keyboards/clueboard/66/info.json` contains more specific information about Clueboard 66%. -## General Metadata :id=general-metadata +## General Metadata {#general-metadata} * `keyboard_name` (Required) * A free-form text string describing the keyboard. This will be used as the USB product string. Can include Unicode characters, escaped to ASCII eg. `\u03A8` (Ψ). @@ -25,7 +25,7 @@ You can create `info.json` files at every level under `qmk_firmware/keyboards/ Serial in this context should be read as **sending information one bit at a time**, rather than implementing UART/USART/RS485/RS232 standards. +::: tip +Serial in this context should be read as **sending information one bit at a time**, rather than implementing UART/USART/RS485/RS232 standards. +:::
@@ -16,7 +18,9 @@ The Serial driver powers the [Split Keyboard](feature_split_keyboard.md) feature This is the Default driver, absence of configuration assumes this driver. It works by [bit banging](https://en.wikipedia.org/wiki/Bit_banging) a GPIO pin using the CPU. It is therefore not as efficient as a dedicated hardware peripheral, which the Half-duplex and Full-duplex drivers use. -!> On ARM platforms the bitbang driver causes connection issues when using it together with the bitbang WS2812 driver. Choosing alternate drivers for both serial and WS2812 (instead of bitbang) is strongly recommended. +::: warning +On ARM platforms the bitbang driver causes connection issues when using it together with the bitbang WS2812 driver. Choosing alternate drivers for both serial and WS2812 (instead of bitbang) is strongly recommended. +::: ### Pin configuration @@ -76,7 +80,9 @@ Targeting ARM boards based on ChibiOS, where communication is offloaded to a USA Only one GPIO pin is needed for the Half-duplex driver, as only one wire is used for receiving and transmitting data. This pin is referred to as the `SERIAL_USART_TX_PIN` in the configuration. Ensure that the pin chosen for split communication can operate as the TX pin of the contoller's USART peripheral. A TRS or USB cable provides enough conductors for this driver to function. As the split connection is configured to operate in open-drain mode, an **external pull-up resistor is needed to keep the line high**. Resistor values of 1.5kΩ to 8.2kΩ are known to work. -!> ***Note:*** A pull-up resistor isn't required for RP2040 controllers configured with PIO subsystem. +::: warning +***Note:*** A pull-up resistor isn't required for RP2040 controllers configured with PIO subsystem. +::: ### Setup @@ -102,7 +108,7 @@ SERIAL_DRIVER = vendor #define SERIAL_USART_TX_PIN B6 // The GPIO pin that is used split communication. ``` -For STM32 MCUs several GPIO configuration options can be changed as well. See the section ["Alternate Functions for selected STM32 MCUs"](alternate-functions-for-selected-stm32-mcus). +For STM32 MCUs several GPIO configuration options can be changed as well. See the section ["Alternate Functions for selected STM32 MCUs"](#alternate-functions-for-selected-stm32-mcus). ```c #define USART1_REMAP // Remap USART TX and RX pins on STM32F103 MCUs, see table below. @@ -163,7 +169,7 @@ SERIAL_DRIVER = vendor #define SERIAL_USART_RX_PIN B7 // USART RX pin ``` -For STM32 MCUs several GPIO configuration options, including the ability for `TX` to `RX` pin swapping, can be changed as well. See the section ["Alternate Functions for selected STM32 MCUs"](alternate-functions-for-selected-stm32-mcus). +For STM32 MCUs several GPIO configuration options, including the ability for `TX` to `RX` pin swapping, can be changed as well. See the section ["Alternate Functions for selected STM32 MCUs"](#alternate-functions-for-selected-stm32-mcus). ```c #define SERIAL_USART_PIN_SWAP // Swap TX and RX pins if keyboard is master halve. (Only available on some MCUs) @@ -291,7 +297,9 @@ If you're having issues withe serial communication, you can enable debug message #define SERIAL_DEBUG ``` -?> The messages will be printed out to the `CONSOLE` output. For additional information, refer to [Debugging/Troubleshooting QMK](faq_debug.md). +::: tip +The messages will be printed out to the `CONSOLE` output. For additional information, refer to [Debugging/Troubleshooting QMK](faq_debug). +::: ## Alternate Functions for selected STM32 MCUs diff --git a/docs/spi_driver.md b/docs/spi_driver.md index 569a19f1db..b77e2dbb46 100644 --- a/docs/spi_driver.md +++ b/docs/spi_driver.md @@ -1,10 +1,10 @@ -# SPI Master Driver :id=spi-master-driver +# SPI Master Driver {#spi-master-driver} The SPI Master drivers used in QMK have a set of common functions to allow portability between MCUs. -## Usage :id=usage +## Usage {#usage} -In most cases, the SPI Master driver code is automatically included if you are using a feature or driver which requires it, such as [OLED](feature_oled_driver.md). +In most cases, the SPI Master driver code is automatically included if you are using a feature or driver which requires it, such as [OLED](feature_oled_driver). However, if you need to use the driver standalone, add the following to your `rules.mk`: @@ -14,7 +14,7 @@ SPI_DRIVER_REQUIRED = yes You can then call the SPI API by including `spi_master.h` in your code. -## AVR Configuration :id=avr-configuration +## AVR Configuration {#avr-configuration} No special setup is required - just connect the `SS`, `SCK`, `MOSI` and `MISO` pins of your SPI devices to the matching pins on the MCU: @@ -28,7 +28,7 @@ No special setup is required - just connect the `SS`, `SCK`, `MOSI` and `MISO` p You may use more than one slave select pin, not just the `SS` pin. This is useful when you have multiple devices connected and need to communicate with them individually. `SPI_SS_PIN` can be passed to `spi_start()` to refer to `SS`. -## ChibiOS/ARM Configuration :id=arm-configuration +## ChibiOS/ARM Configuration {#arm-configuration} You'll need to determine which pins can be used for SPI -- as an example, STM32 parts generally have multiple SPI peripherals, labeled SPI1, SPI2, SPI3 etc. @@ -66,19 +66,19 @@ If a complete SPI interface is not required, then the following can be done to d - in `config.h`: `#define SPI_MOSI_PIN NO_PIN` - in `mcuconf.h`: `#define SPI_SELECT_MODE SPI_SELECT_MODE_NONE`, in this case the `slavePin` argument passed to `spi_start()` may be `NO_PIN` if the slave select pin is not used. -## API :id=api +## API {#api} -### `void spi_init(void)` :id=api-spi-init +### `void spi_init(void)` {#api-spi-init} Initialize the SPI driver. This function must be called only once, before any of the below functions can be called. --- -### `bool spi_start(pin_t slavePin, bool lsbFirst, uint8_t mode, uint16_t divisor)` :id=api-spi-start +### `bool spi_start(pin_t slavePin, bool lsbFirst, uint8_t mode, uint16_t divisor)` {#api-spi-start} Start an SPI transaction. -#### Arguments :id=api-spi-start-arguments +#### Arguments {#api-spi-start-arguments} - `pin_t slavePin` The QMK pin to assert as the slave select pin, eg. `B4`. @@ -97,71 +97,71 @@ Start an SPI transaction. - `uint16_t divisor` The SPI clock divisor, will be rounded up to the nearest power of two. This number can be calculated by dividing the MCU's clock speed by the desired SPI clock speed. For example, an MCU running at 8 MHz wanting to talk to an SPI device at 4 MHz would set the divisor to `2`. -#### Return Value :id=api-spi-start-return +#### Return Value {#api-spi-start-return} `false` if the supplied parameters are invalid or the SPI peripheral is already in use, or `true`. --- -### `spi_status_t spi_write(uint8_t data)` :id=api-spi-write +### `spi_status_t spi_write(uint8_t data)` {#api-spi-write} Write a byte to the selected SPI device. -#### Arguments :id=api-spi-write-arguments +#### Arguments {#api-spi-write-arguments} - `uint8_t data` The byte to write. -#### Return Value :id=api-spi-write-return +#### Return Value {#api-spi-write-return} `SPI_STATUS_TIMEOUT` if the timeout period elapses, or `SPI_STATUS_SUCCESS`. --- -### `spi_status_t spi_read(void)` :id=api-spi-read +### `spi_status_t spi_read(void)` {#api-spi-read} Read a byte from the selected SPI device. -#### Return Value :id=api-spi-read-return +#### Return Value {#api-spi-read-return} `SPI_STATUS_TIMEOUT` if the timeout period elapses, or the byte read from the device. --- -### `spi_status_t spi_transmit(const uint8_t *data, uint16_t length)` :id=api-spi-transmit +### `spi_status_t spi_transmit(const uint8_t *data, uint16_t length)` {#api-spi-transmit} Send multiple bytes to the selected SPI device. -#### Arguments :id=api-spi-transmit-arguments +#### Arguments {#api-spi-transmit-arguments} - `const uint8_t *data` A pointer to the data to write from. - `uint16_t length` The number of bytes to write. Take care not to overrun the length of `data`. -#### Return Value :id=api-spi-transmit-return +#### Return Value {#api-spi-transmit-return} `SPI_STATUS_TIMEOUT` if the timeout period elapses, `SPI_STATUS_ERROR` if some other error occurs, otherwise `SPI_STATUS_SUCCESS`. --- -### `spi_status_t spi_receive(uint8_t *data, uint16_t length)` :id=api-spi-receive +### `spi_status_t spi_receive(uint8_t *data, uint16_t length)` {#api-spi-receive} Receive multiple bytes from the selected SPI device. -#### Arguments :id=api-spi-receive-arguments +#### Arguments {#api-spi-receive-arguments} - `uint8_t *data` A pointer to the buffer to read into. - `uint16_t length` The number of bytes to read. Take care not to overrun the length of `data`. -#### Return Value :id=api-spi-receive-return +#### Return Value {#api-spi-receive-return} `SPI_STATUS_TIMEOUT` if the timeout period elapses, `SPI_STATUS_ERROR` if some other error occurs, otherwise `SPI_STATUS_SUCCESS`. --- -### `void spi_stop(void)` :id=api-spi-stop +### `void spi_stop(void)` {#api-spi-stop} End the current SPI transaction. This will deassert the slave select pin and reset the endianness, mode and divisor configured by `spi_start()`. diff --git a/docs/squeezing_avr.md b/docs/squeezing_avr.md index 3f014cafb7..c3f3d3c6e1 100644 --- a/docs/squeezing_avr.md +++ b/docs/squeezing_avr.md @@ -27,7 +27,7 @@ SPACE_CADET_ENABLE = no GRAVE_ESC_ENABLE = no MAGIC_ENABLE = no ``` -These features are enabled by default, but they may not be needed. Double check to make sure. The [Magic Keycodes](keycodes_magic.md) are the largest and control things like NKRO toggling, GUI and ALT/CTRL swapping, etc. Disabling them will disable those functions. See [Magic Functions](#magic-functions) for disabling related functions. +These features are enabled by default, but they may not be needed. Double check to make sure. The [Magic Keycodes](keycodes_magic) are the largest and control things like NKRO toggling, GUI and ALT/CTRL swapping, etc. Disabling them will disable those functions. See [Magic Functions](#magic-functions) for disabling related functions. If you use `sprintf` or `snprintf` functions you can save around ~400 Bytes by enabling this option. ```make diff --git a/docs/support_deprecation_policy.md b/docs/support_deprecation_policy.md index f7107dfc89..450a578e2e 100644 --- a/docs/support_deprecation_policy.md +++ b/docs/support_deprecation_policy.md @@ -6,7 +6,9 @@ In general, feature development is encouraged to support as many hardware config The most frequently-hit constraint is the amount of code that can be flashed onto an ATmega32U4 -- users almost always need to pick and choose included functionality due to the size constraints. -!> [Squeezing AVR](https://docs.qmk.fm/#/squeezing_avr) has some steps that users can take in order to minimise the overall firmware size, which in some cases enables the ability for users to include other desired features. +::: warning +[Squeezing AVR](squeezing_avr) has some steps that users can take in order to minimise the overall firmware size, which in some cases enables the ability for users to include other desired features. +::: ## Deprecation & Removal Policy @@ -27,7 +29,9 @@ There may be several motivations behind the deprecation or removal of functional When a feature is selected for deprecation, future changes to that area will cease to be developed by the QMK team, and Pull Requests submitted against those areas will be declined. -?> As QMK does not gather metrics from its users, the only way the QMK team can gauge the level of usage is to refer to the main QMK Firmware repository -- searching through forks is not practical due to the sheer number of them. +::: tip +As QMK does not gather metrics from its users, the only way the QMK team can gauge the level of usage is to refer to the main QMK Firmware repository -- searching through forks is not practical due to the sheer number of them. +::: ### How much advance notice will be given? diff --git a/docs/sw.js b/docs/sw.js deleted file mode 100644 index 1e4aaeb762..0000000000 --- a/docs/sw.js +++ /dev/null @@ -1,83 +0,0 @@ -/* =========================================================== - * docsify sw.js - * =========================================================== - * Copyright 2016 @huxpro - * Licensed under Apache 2.0 - * Register service worker. - * ========================================================== */ - -const RUNTIME = 'docsify' -const HOSTNAME_WHITELIST = [ - self.location.hostname, - 'fonts.gstatic.com', - 'fonts.googleapis.com', - 'unpkg.com' -] - -// The Util Function to hack URLs of intercepted requests -const getFixedUrl = (req) => { - var now = Date.now() - var url = new URL(req.url) - - // 1. fixed http URL - // Just keep syncing with location.protocol - // fetch(httpURL) belongs to active mixed content. - // And fetch(httpRequest) is not supported yet. - url.protocol = self.location.protocol - - // 2. add query for caching-busting. - // Github Pages served with Cache-Control: max-age=600 - // max-age on mutable content is error-prone, with SW life of bugs can even extend. - // Until cache mode of Fetch API landed, we have to workaround cache-busting with query string. - // Cache-Control-Bug: https://bugs.chromium.org/p/chromium/issues/detail?id=453190 - if (url.hostname === self.location.hostname) { - url.search += (url.search ? '&' : '?') + 'cache-bust=' + now - } - return url.href -} - -/** - * @Lifecycle Activate - * New one activated when old isnt being used. - * - * waitUntil(): activating ====> activated - */ -self.addEventListener('activate', event => { - event.waitUntil(self.clients.claim()) -}) - -/** - * @Functional Fetch - * All network requests are being intercepted here. - * - * void respondWith(Promise r) - */ -self.addEventListener('fetch', event => { - // Skip some of cross-origin requests, like those for Google Analytics. - if (HOSTNAME_WHITELIST.indexOf(new URL(event.request.url).hostname) > -1) { - // Stale-while-revalidate - // similar to HTTP's stale-while-revalidate: https://www.mnot.net/blog/2007/12/12/stale - // Upgrade from Jake's to Surma's: https://gist.github.com/surma/eb441223daaedf880801ad80006389f1 - const cached = caches.match(event.request) - const fixedUrl = getFixedUrl(event.request) - const fetched = fetch(fixedUrl, { cache: 'no-store' }) - const fetchedCopy = fetched.then(resp => resp.clone()) - - // Call respondWith() with whatever we get first. - // If the fetch fails (e.g disconnected), wait for the cache. - // If there’s nothing in cache, wait for the fetch. - // If neither yields a response, return offline pages. - event.respondWith( - Promise.race([fetched.catch(_ => cached), cached]) - .then(resp => resp || fetched) - .catch(_ => { /* eat any errors */ }) - ) - - // Update the cache with the version we fetched (only for ok status) - event.waitUntil( - Promise.all([fetchedCopy, caches.open(RUNTIME)]) - .then(([response, cache]) => response.ok && cache.put(event.request, response)) - .catch(_ => { /* eat any errors */ }) - ) - } -}) diff --git a/docs/syllabus.md b/docs/syllabus.md index f5cdea2182..82b6110c80 100644 --- a/docs/syllabus.md +++ b/docs/syllabus.md @@ -4,19 +4,19 @@ This page helps you build up your QMK knowledge by introducing the basics first # Beginning Topics -If you read nothing else you should read the documents in this section. After reading the [Tutorial](newbs.md) you should be able to create a basic keymap, compile it, and flash it to your keyboard. The remaining documents will flesh out your knowledge of these basics. +If you read nothing else you should read the documents in this section. After reading the [Tutorial](newbs) you should be able to create a basic keymap, compile it, and flash it to your keyboard. The remaining documents will flesh out your knowledge of these basics. * **Learn How To Use QMK Tools** - * [Tutorial](newbs.md) - * [CLI](cli.md) - * [GIT](newbs_git_best_practices.md) + * [Tutorial](newbs) + * [CLI](cli) + * [GIT](newbs_git_best_practices) * **Learn About Keymaps** - * [Layers](feature_layers.md) - * [Keycodes](keycodes.md) + * [Layers](feature_layers) + * [Keycodes](keycodes) * The full list of keycodes you can use. Note that some may require knowledge found in the Intermediate or Advanced Topics. * **Configuring IDEs** - Optional - * [Eclipse](other_eclipse.md) - * [VS Code](other_vscode.md) + * [Eclipse](other_eclipse) + * [VS Code](other_vscode) # Intermediate Topics @@ -24,49 +24,49 @@ These topics start to dig into some of the features that QMK supports. You don't * **Learn How To Configure Features** - * [Audio](feature_audio.md) + * [Audio](feature_audio) * Lighting - * [Backlight](feature_backlight.md) - * [LED Matrix](feature_led_matrix.md) - * [RGB Lighting](feature_rgblight.md) - * [RGB Matrix](feature_rgb_matrix.md) - * [Tap-Hold Configuration](tap_hold.md) - * [Squeezing Space from AVR](squeezing_avr.md) + * [Backlight](feature_backlight) + * [LED Matrix](feature_led_matrix) + * [RGB Lighting](feature_rgblight) + * [RGB Matrix](feature_rgb_matrix) + * [Tap-Hold Configuration](tap_hold) + * [Squeezing Space from AVR](squeezing_avr) * **Learn More About Keymaps** - * [Keymaps](keymap.md) - * [Custom Functions and Keycodes](custom_quantum_functions.md) + * [Keymaps](keymap) + * [Custom Functions and Keycodes](custom_quantum_functions) * Macros - * [Dynamic Macros](feature_dynamic_macros.md) - * [Compiled Macros](feature_macros.md) - * [Tap Dance](feature_tap_dance.md) - * [Combos](feature_combo.md) - * [Userspace](feature_userspace.md) - * [Key Overrides](feature_key_overrides.md) + * [Dynamic Macros](feature_dynamic_macros) + * [Compiled Macros](feature_macros) + * [Tap Dance](feature_tap_dance) + * [Combos](feature_combo) + * [Userspace](feature_userspace) + * [Key Overrides](feature_key_overrides) # Advanced Topics Everything below here requires a lot of foundational knowledge. Besides being able to create keymaps using advanced features you should be familiar with using both `config.h` and `rules.mk` to configure options for your keyboard. * **Maintaining Keyboards Within QMK** - * [Handwiring a Keyboard](hand_wire.md) - * [Keyboard Guidelines](hardware_keyboard_guidelines.md) - * [info.json Reference](reference_info_json.md) - * [Debounce API](feature_debounce_type.md) + * [Handwiring a Keyboard](hand_wire) + * [Keyboard Guidelines](hardware_keyboard_guidelines) + * [info.json Reference](reference_info_json) + * [Debounce API](feature_debounce_type) * **Advanced Features** - * [Unicode](feature_unicode.md) - * [API](api_overview.md) - * [Bootmagic Lite](feature_bootmagic.md) + * [Unicode](feature_unicode) + * [API](api_overview) + * [Bootmagic Lite](feature_bootmagic) * **Hardware** - * [How Keyboards Work](how_keyboards_work.md) - * [How A Keyboard Matrix Works](how_a_matrix_works.md) - * [Split Keyboards](feature_split_keyboard.md) - * [Stenography](feature_stenography.md) - * [Pointing Devices](feature_pointing_device.md) + * [How Keyboards Work](how_keyboards_work) + * [How A Keyboard Matrix Works](how_a_matrix_works) + * [Split Keyboards](feature_split_keyboard) + * [Stenography](feature_stenography) + * [Pointing Devices](feature_pointing_device) * **Core Development** - * [Coding Conventions](coding_conventions_c.md) - * [Compatible Microcontrollers](compatible_microcontrollers.md) - * [Custom Matrix](custom_matrix.md) - * [Understanding QMK](understanding_qmk.md) + * [Coding Conventions](coding_conventions_c) + * [Compatible Microcontrollers](compatible_microcontrollers) + * [Custom Matrix](custom_matrix) + * [Understanding QMK](understanding_qmk) * **CLI Development** - * [Coding Conventions](coding_conventions_python.md) - * [CLI Development Overview](cli_development.md) + * [Coding Conventions](coding_conventions_python) + * [CLI Development Overview](cli_development) diff --git a/docs/tap_hold.md b/docs/tap_hold.md index 18c90c6932..fe862894b4 100644 --- a/docs/tap_hold.md +++ b/docs/tap_hold.md @@ -8,7 +8,9 @@ These options let you modify the behavior of the Tap-Hold keys. The crux of all of the following features is the tapping term setting. This determines what is a tap and what is a hold. The exact timing for this to feel natural can vary from keyboard to keyboard, from switch to switch, and from key to key. -?> `DYNAMIC_TAPPING_TERM_ENABLE` enables three special keys that can help you quickly find a comfortable tapping term for you. See "Dynamic Tapping Term" for more details. +::: tip +`DYNAMIC_TAPPING_TERM_ENABLE` enables three special keys that can help you quickly find a comfortable tapping term for you. See "Dynamic Tapping Term" for more details. +::: You can set the global time for this by adding the following setting to your `config.h`: @@ -38,7 +40,7 @@ uint16_t get_tapping_term(uint16_t keycode, keyrecord_t *record) { } ``` -### Dynamic Tapping Term :id=dynamic-tapping-term +### Dynamic Tapping Term {#dynamic-tapping-term} `DYNAMIC_TAPPING_TERM_ENABLE` is a feature you can enable in `rules.mk` that lets you use three special keys in your keymap to configure the tapping term on the fly. @@ -126,13 +128,13 @@ The code which decides between the tap and hold actions of dual-role keys suppor Note that until the tap-or-hold decision completes (which happens when either the dual-role key is released, or the tapping term has expired, or the extra condition for the selected decision mode is satisfied), key events are delayed and not transmitted to the host immediately. The default mode gives the most delay (if the dual-role key is held down, this mode always waits for the whole tapping term), and the other modes may give less delay when other keys are pressed, because the hold action may be selected earlier. -### Comparison :id=comparison +### Comparison {#comparison} To better illustrate the tap-or-hold decision modes, let us compare the expected output of each decision mode in a handful of tapping scenarios involving a mod-tap key (`LSFT_T(KC_A)`) and a regular key (`KC_B`) with the `TAPPING_TERM` set to 200ms. Note: "`kc` held" in the "Physical key event" column means that the key wasn't physically released yet at this point in time. -#### Distinct taps (AABB) :id=distinct-taps +#### Distinct taps (AABB) {#distinct-taps} | Time | Physical key event | Default | `PERMISSIVE_HOLD` | `HOLD_ON_OTHER_KEY_PRESS` | |------|--------------------|----------------|-------------------|----------------------------| @@ -149,7 +151,7 @@ Note: "`kc` held" in the "Physical key event" column means that the key wasn't p | 205 | `KC_B` down | b | b | b | | 210 | `KC_B` up | b | b | b | -#### Nested tap (ABBA) :id=nested-tap +#### Nested tap (ABBA) {#nested-tap} | Time | Physical key event | Default | `PERMISSIVE_HOLD` | `HOLD_ON_OTHER_KEY_PRESS` | |------|--------------------|----------------|-------------------|----------------------------| @@ -174,7 +176,7 @@ Note: "`kc` held" in the "Physical key event" column means that the key wasn't p | 210 | `KC_B` up | B | B | B | | 220 | `LSFT_T(KC_A)` up | B | B | B | -#### Rolling keys (ABAB) :id=rolling-keys +#### Rolling keys (ABAB) {#rolling-keys} | Time | Physical key event | Default | `PERMISSIVE_HOLD` | `HOLD_ON_OTHER_KEY_PRESS` | |------|--------------------|----------------|-------------------|----------------------------| @@ -296,7 +298,9 @@ However, this slightly different sequence will not be affected by the “permiss In the sequence above the dual-role key is released before the other key is released, and if that happens within the tapping term, the “permissive hold” mode will still choose the tap action for the dual-role key, and the sequence will be registered as `al` by the host. We could describe this as a “rolling press” (the two keys' key down and key up events behave as if you were rolling a ball across the two keys, first pressing each key down in sequence and then releasing them in the same order). -?> The `PERMISSIVE_HOLD` option is not noticeable if you also enable `HOLD_ON_OTHER_KEY_PRESS` because the latter option considers both the “nested tap” and “rolling press” sequences like shown above as a hold action, not the tap action. `HOLD_ON_OTHER_KEY_PRESS` makes the Tap-Or-Hold decision earlier in the chain of key events, thus taking a precedence over `PERMISSIVE_HOLD`. +::: tip +The `PERMISSIVE_HOLD` option is not noticeable if you also enable `HOLD_ON_OTHER_KEY_PRESS` because the latter option considers both the “nested tap” and “rolling press” sequences like shown above as a hold action, not the tap action. `HOLD_ON_OTHER_KEY_PRESS` makes the Tap-Or-Hold decision earlier in the chain of key events, thus taking a precedence over `PERMISSIVE_HOLD`. +::: For more granular control of this feature, you can add the following to your `config.h`: @@ -394,7 +398,9 @@ With default settings, `a` will be sent on the first release, then `a` will be s With `QUICK_TAP_TERM` configured, the timing between `SFT_T(KC_A)` up and `SFT_T(KC_A)` down must be within `QUICK_TAP_TERM` to trigger auto repeat. Otherwise the second press will be sent as a Shift. If `QUICK_TAP_TERM` is set to `0`, the second press will always be sent as a Shift, effectively disabling auto-repeat. -!> `QUICK_TAP_TERM` timing will also impact anything that uses tapping toggles (Such as the `TT` layer keycode, and the One Shot Tap Toggle). +::: warning +`QUICK_TAP_TERM` timing will also impact anything that uses tapping toggles (Such as the `TT` layer keycode, and the One Shot Tap Toggle). +::: For more granular control of this feature, you can add the following to your `config.h`: @@ -415,7 +421,9 @@ uint16_t get_quick_tap_term(uint16_t keycode, keyrecord_t *record) { } ``` -?> If `QUICK_TAP_TERM` is set higher than `TAPPING_TERM`, it will default to `TAPPING_TERM`. +::: tip +If `QUICK_TAP_TERM` is set higher than `TAPPING_TERM`, it will default to `TAPPING_TERM`. +::: ## Retro Tapping @@ -483,11 +491,13 @@ Examples: #define MODS_TO_NEUTRALIZE { MOD_BIT(KC_LEFT_ALT), MOD_BIT(KC_LEFT_GUI), MOD_BIT(KC_RIGHT_GUI), MOD_BIT(KC_LEFT_CTRL)|MOD_BIT(KC_LEFT_SHIFT) } ``` -!> Do not use `MOD_xxx` constants like `MOD_LSFT` or `MOD_RALT`, since they're 5-bit packed bit-arrays while `MODS_TO_NEUTRALIZE` expects a list of 8-bit packed bit-arrays. Use `MOD_BIT()` or `MOD_MASK_xxx` instead. +::: warning +Do not use `MOD_xxx` constants like `MOD_LSFT` or `MOD_RALT`, since they're 5-bit packed bit-arrays while `MODS_TO_NEUTRALIZE` expects a list of 8-bit packed bit-arrays. Use `MOD_BIT()` or `MOD_MASK_xxx` instead. +::: ### Retro Shift -[Auto Shift,](feature_auto_shift.md) has its own version of `retro tapping` called `retro shift`. It is extremely similar to `retro tapping`, but holding the key past `AUTO_SHIFT_TIMEOUT` results in the value it sends being shifted. Other configurations also affect it differently; see [here](feature_auto_shift.md#retro-shift) for more information. +[Auto Shift,](feature_auto_shift) has its own version of `retro tapping` called `retro shift`. It is extremely similar to `retro tapping`, but holding the key past `AUTO_SHIFT_TIMEOUT` results in the value it sends being shifted. Other configurations also affect it differently; see [here](feature_auto_shift#retro-shift) for more information. ## Why do we include the key record for the per key functions? diff --git a/docs/translating.md b/docs/translating.md deleted file mode 100644 index 4365817590..0000000000 --- a/docs/translating.md +++ /dev/null @@ -1,55 +0,0 @@ -# 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: - -```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 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: - - ```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/', - ``` - - And make sure to add the language folder in the `fallbackLanguages` list, so it will properly fall back to English instead of 404ing: - - ```js - fallbackLanguages: [ - // ... - 'zh-cn', - // ... - ], - ``` - -## Previewing the Translations - -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/uart_driver.md b/docs/uart_driver.md index 9b0a92d23d..23f5b3d6e4 100644 --- a/docs/uart_driver.md +++ b/docs/uart_driver.md @@ -1,10 +1,10 @@ -# UART Driver :id=uart-driver +# UART Driver {#uart-driver} The UART drivers used in QMK have a set of common functions to allow portability between MCUs. Currently, this driver does not support enabling hardware flow control (the `RTS` and `CTS` pins) if available, but may do so in future. -## Usage :id=usage +## Usage {#usage} In most cases, the UART driver code is automatically included if you are using a feature or driver which requires it. @@ -16,7 +16,7 @@ UART_DRIVER_REQUIRED = yes You can then call the UART API by including `uart.h` in your code. -## AVR Configuration :id=avr-configuration +## AVR Configuration {#avr-configuration} No special setup is required - just connect the `RX` and `TX` pins of your UART device to the opposite pins on the MCU: @@ -28,7 +28,7 @@ No special setup is required - just connect the `RX` and `TX` pins of your UART |ATmega32A |`D1`|`D0`|*n/a*|*n/a*| |ATmega328/P |`D1`|`D0`|*n/a*|*n/a*| -## ChibiOS/ARM Configuration :id=arm-configuration +## ChibiOS/ARM Configuration {#arm-configuration} You'll need to determine which pins can be used for UART -- as an example, STM32 parts generally have multiple UART peripherals, labeled USART1, USART2, USART3 etc. @@ -53,45 +53,45 @@ Configuration-wise, you'll need to set up the peripheral as per your MCU's datas | `#define UART_RTS_PIN` | The pin to use for RTS | `A12` | | `#define UART_RTS_PAL_MODE` | The alternate function mode for RTS | `7` | -## API :id=api +## API {#api} -### `void uart_init(uint32_t baud)` :id=api-uart-init +### `void uart_init(uint32_t baud)` {#api-uart-init} Initialize the UART driver. This function must be called only once, before any of the below functions can be called. -#### Arguments :id=api-uart-init-arguments +#### Arguments {#api-uart-init-arguments} - `uint32_t baud` The baud rate to transmit and receive at. This may depend on the device you are communicating with. Common values are 1200, 2400, 4800, 9600, 19200, 38400, 57600, and 115200. --- -### `void uart_write(uint8_t data)` :id=api-uart-write +### `void uart_write(uint8_t data)` {#api-uart-write} Transmit a single byte. -#### Arguments :id=api-uart-write-arguments +#### Arguments {#api-uart-write-arguments} - `uint8_t data` The byte to write. --- -### `uint8_t uart_read(void)` :id=api-uart-read +### `uint8_t uart_read(void)` {#api-uart-read} Receive a single byte. -#### Return Value :id=api-uart-read-return +#### Return Value {#api-uart-read-return} The byte read from the receive buffer. This function will block if the buffer is empty (ie. no data to read). --- -### `void uart_transmit(const uint8_t *data, uint16_t length)` :id=api-uart-transmit +### `void uart_transmit(const uint8_t *data, uint16_t length)` {#api-uart-transmit} Transmit multiple bytes. -#### Arguments :id=api-uart-transmit-arguments +#### Arguments {#api-uart-transmit-arguments} - `const uint8_t *data` A pointer to the data to write from. @@ -100,11 +100,11 @@ Transmit multiple bytes. --- -### `void uart_receive(char *data, uint16_t length)` :id=api-uart-receive +### `void uart_receive(char *data, uint16_t length)` {#api-uart-receive} Receive multiple bytes. -#### Arguments :id=api-uart-receive-arguments +#### Arguments {#api-uart-receive-arguments} - `uint8_t *data` A pointer to the buffer to read into. @@ -113,10 +113,10 @@ Receive multiple bytes. --- -### `bool uart_available(void)` :id=api-uart-available +### `bool uart_available(void)` {#api-uart-available} Return whether the receive buffer contains data. Call this function to determine if `uart_read()` will return data immediately. -#### Return Value :id=api-uart-available-return +#### Return Value {#api-uart-available-return} `true` if the receive buffer length is non-zero. diff --git a/docs/understanding_qmk.md b/docs/understanding_qmk.md index 7cb46bd8cf..ad5afdc56a 100644 --- a/docs/understanding_qmk.md +++ b/docs/understanding_qmk.md @@ -2,9 +2,9 @@ This document attempts to explain how the QMK firmware works from a very high level. It assumes you understand basic programming concepts but does not (except where needed to demonstrate) assume familiarity with C. It assumes that you have a basic understanding of the following documents: -* [Introduction](getting_started_introduction.md) -* [How Keyboards Work](how_keyboards_work.md) -* [FAQ](faq_general.md) +* [Introduction](getting_started_introduction) +* [How Keyboards Work](how_keyboards_work) +* [FAQ](faq_general) ## Startup diff --git a/docs/unit_testing.md b/docs/unit_testing.md index 60787fdffc..3e4c914bf1 100644 --- a/docs/unit_testing.md +++ b/docs/unit_testing.md @@ -44,7 +44,7 @@ Note that the tests are always compiled with the native compiler of your platfor If there are problems with the tests, you can find the executable in the `./build/test` folder. You should be able to run those with GDB or a similar debugger. -To forward any [debug messages](unit_testing.md#debug-api) to `stderr`, the tests can run with `DEBUG=1`. For example +To forward any [debug messages](unit_testing#debug-api) to `stderr`, the tests can run with `DEBUG=1`. For example ``` make test:all DEBUG=1 @@ -58,7 +58,7 @@ It's not yet possible to do a full integration test, where you would compile the In that model you would emulate the input, and expect a certain output from the emulated keyboard. -# Tracing Variables :id=tracing-variables +# Tracing Variables {#tracing-variables} Sometimes you might wonder why a variable gets changed and where, and this can be quite tricky to track down without having a debugger. It's of course possible to manually add print statements to track it, but you can also enable the variable trace feature. This works for both variables that are changed by the code, and when the variable is changed by some memory corruption. diff --git a/docs/ws2812_driver.md b/docs/ws2812_driver.md index 8851c042f0..c445e2dbf6 100644 --- a/docs/ws2812_driver.md +++ b/docs/ws2812_driver.md @@ -1,4 +1,4 @@ -# WS2812 Driver :id=ws2812-driver +# WS2812 Driver {#ws2812-driver} This driver provides support for WorldSemi addressable RGB(W) LEDs, and compatible equivalents: @@ -8,9 +8,9 @@ This driver provides support for WorldSemi addressable RGB(W) LEDs, and compatib These LEDs are often called "addressable" because instead of using a wire per color (and per LED), each LED contains a small microchip that understands a special protocol sent over a single wire. The LEDs can be chained together, and the remaining data is passed on to the next. In this way, you can easily control the color of many LEDs using a single GPIO. -## Usage :id=usage +## Usage {#usage} -In most cases, the WS2812 driver code is automatically included if you are using either the [RGBLight](feature_rgblight.md) or [RGB Matrix](feature_rgb_matrix.md) feature with the `ws2812` driver set, and you would use those APIs instead. +In most cases, the WS2812 driver code is automatically included if you are using either the [RGBLight](feature_rgblight) or [RGB Matrix](feature_rgb_matrix) feature with the `ws2812` driver set, and you would use those APIs instead. However, if you need to use the driver standalone, add the following to your `rules.mk`: @@ -20,7 +20,7 @@ WS2812_DRIVER_REQUIRED = yes You can then call the WS2812 API by including `ws2812.h` in your code. -## Basic Configuration :id=basic-configuration +## Basic Configuration {#basic-configuration} Add the following to your `config.h`: @@ -35,14 +35,14 @@ Add the following to your `config.h`: |`WS2812_BYTE_ORDER`|`WS2812_BYTE_ORDER_GRB`|The byte order of the RGB data | |`WS2812_RGBW` |*Not defined* |Enables RGBW support (except `i2c` driver) | -### Timing Adjustment :id=timing-adjustment +### Timing Adjustment {#timing-adjustment} The WS2812 LED communication protocol works by encoding a "1" bit with a long high pulse (T1H), and a "0" bit with a shorter pulse (T0H). The total cycle length of a bit is the same. The "reset" pulse (TRST) latches the sent RGB data to all of the LEDs and denotes a completed "frame". Some WS2812 variants have slightly different timing parameter requirements, which can be accounted for if necessary using the above `#define`s in your `config.h`. -### Byte Order :id=byte-order +### Byte Order {#byte-order} Some WS2812 variants may have their color components in a different physical or logical order. For example, the WS2812B-2020 has physically swapped red and green LEDs, which causes the wrong color to be displayed, because the default order of the bytes sent over the wire is defined as GRB. If you find your LED colors are consistently swapped, you may need to change the byte order by adding the following to your `config.h`: @@ -59,7 +59,7 @@ Where the byte order may be one of: |`RGB` |WS2812B-2020 | |`BGR` |TM1812 | -### RGBW Support :id=rgbw-support +### RGBW Support {#rgbw-support} Rendering the color white with RGB LEDs is typically inconsistent due to inherent variations between each individual LED die. However, some WS2812 variants (such as SK6812RGBW) also possess a white LED along with the red, green, and blue channels, which allows for a more accurate white to be displayed. @@ -80,11 +80,11 @@ To enable RGBW conversion, add the following to your `config.h`: #define WS2812_RGBW ``` -## Driver Configuration :id=driver-configuration +## Driver Configuration {#driver-configuration} Driver selection can be configured in `rules.mk` as `WS2812_DRIVER`, or in `info.json` as `ws2812.driver`. Valid values are `bitbang` (default), `i2c`, `spi`, `pwm`, `vendor`, or `custom`. See below for information on individual drivers. -### Bitbang Driver :id=bitbang-driver +### Bitbang Driver {#bitbang-driver} This is the default WS2812 driver. It operates by "bit-banging" ie. directly toggling the GPIO. @@ -94,7 +94,7 @@ Please note that on AVR devices, due to the tight timing requirements longer cha WS2812_DRIVER = bitbang ``` -### I2C Driver :id=i2c-driver +### I2C Driver {#i2c-driver} A specialized driver mainly used for PS2AVRGB (Bootmapper Client) boards, which possess an ATtiny85 that handles the WS2812 LEDs. @@ -109,7 +109,7 @@ The following `#define`s apply only to the `i2c` driver: |`WS2812_I2C_ADDRESS`|`0xB0` |The I2C address of the ATtiny85. | |`WS2812_I2C_TIMEOUT`|`100` |The I2C timeout, in milliseconds.| -### PIO Driver :id=pio-driver +### PIO Driver {#pio-driver} This driver is RP2040-only, and leverages the onboard PIO (programmable I/O) system and DMA to offload processing from the CPU. @@ -119,7 +119,7 @@ The WS2812 PIO program uses one state machine, six instructions and one DMA inte WS2812_DRIVER = vendor ``` -### PWM Driver :id=pwm-driver +### PWM Driver {#pwm-driver} This driver is ARM-only, and leverages the onboard PWM peripheral and DMA to offload processing from the CPU. @@ -127,7 +127,7 @@ This driver is ARM-only, and leverages the onboard PWM peripheral and DMA to off WS2812_DRIVER = pwm ``` -### SPI Driver :id=spi-driver +### SPI Driver {#spi-driver} This driver is ARM-only, and leverages the onboard SPI peripheral and DMA to offload processing from the CPU. The DI pin **must** be connected to the MOSI pin on the MCU, and all other SPI pins **must** be left unused. This is also very dependent on your MCU's SPI peripheral clock speed, and may or may not be possible depending on the MCU selected. @@ -135,7 +135,7 @@ This driver is ARM-only, and leverages the onboard SPI peripheral and DMA to off WS2812_DRIVER = spi ``` -## ChibiOS/ARM Configuration :id=arm-configuration +## ChibiOS/ARM Configuration {#arm-configuration} The following defines apply only to ARM devices: @@ -144,7 +144,7 @@ The following defines apply only to ARM devices: |`WS2812_T1L`|`(WS2812_TIMING - WS2812_T1H)`|The length of a "1" bit's low phase in nanoseconds (bitbang and PIO drivers only)| |`WS2812_T0L`|`(WS2812_TIMING - WS2812_T0H)`|The length of a "0" bit's low phase in nanoseconds (bitbang and PIO drivers only)| -### Push-Pull and Open Drain :id=push-pull-open-drain +### Push-Pull and Open Drain {#push-pull-open-drain} By default, the GPIO used for data transmission is configured as a *push-pull* output, meaning the pin is effectively always driven either to VCC or to ground. @@ -156,7 +156,7 @@ To configure the DI pin for open drain configuration, add the following to your #define WS2812_EXTERNAL_PULLUP ``` -### SPI Driver :id=arm-spi-driver +### SPI Driver {#arm-spi-driver} Depending on the ChibiOS board configuration, you may need to enable SPI at the keyboard level. For STM32, this would look like: @@ -181,7 +181,7 @@ The following `define`s apply only to the `spi` driver: |`WS2812_SPI_DIVISOR` |`16` |The divisor used to adjust the baudrate | |`WS2812_SPI_USE_CIRCULAR_BUFFER`|*Not defined*|Enable a circular buffer for improved rendering | -#### Setting the Baudrate :id=arm-spi-baudrate +#### Setting the Baudrate {#arm-spi-baudrate} To adjust the SPI baudrate, you will need to derive the target baudrate from the clock tree provided by STM32CubeMX, and add the following to your `config.h`: @@ -191,7 +191,7 @@ To adjust the SPI baudrate, you will need to derive the target baudrate from the Only divisors of 2, 4, 8, 16, 32, 64, 128 and 256 are supported on STM32 devices. Other MCUs may have similar constraints -- check the reference manual for your respective MCU for specifics. -#### Circular Buffer :id=arm-spi-circular-buffer +#### Circular Buffer {#arm-spi-circular-buffer} A circular buffer can be enabled if you experience flickering. @@ -201,7 +201,7 @@ To enable the circular buffer, add the following to your `config.h`: #define WS2812_SPI_USE_CIRCULAR_BUFFER ``` -### PIO Driver :id=arm-pio-driver +### PIO Driver {#arm-pio-driver} The following `#define`s apply only to the PIO driver: @@ -209,7 +209,7 @@ The following `#define`s apply only to the PIO driver: |---------------------|-------------|---------------------------------------| |`WS2812_PIO_USE_PIO1`|*Not defined*|Use the PIO1 peripheral instead of PIO0| -### PWM Driver :id=arm-pwm-driver +### PWM Driver {#arm-pwm-driver} Depending on the ChibiOS board configuration, you may need to enable PWM at the keyboard level. For STM32, this would look like: @@ -235,15 +235,17 @@ The following `#define`s apply only to the `pwm` driver: |`WS2812_PWM_DMAMUX_ID` |*Not defined* |The DMAMUX configuration for `TIMx_UP` - only required if your MCU has a DMAMUX peripheral| |`WS2812_PWM_COMPLEMENTARY_OUTPUT`|*Not defined* |Whether the PWM output is complementary (`TIMx_CHyN`) | -?> Using a complementary timer output (`TIMx_CHyN`) is possible only for advanced-control timers (1, 8 and 20 on STM32), and the `STM32_PWM_USE_ADVANCED` option in `mcuconf.h` must be set to `TRUE`. Complementary outputs of general-purpose timers are not supported due to ChibiOS limitations. +::: tip +Using a complementary timer output (`TIMx_CHyN`) is possible only for advanced-control timers (1, 8 and 20 on STM32), and the `STM32_PWM_USE_ADVANCED` option in `mcuconf.h` must be set to `TRUE`. Complementary outputs of general-purpose timers are not supported due to ChibiOS limitations. +::: -## API :id=api +## API {#api} -### `void ws2812_setleds(rgb_led_t *ledarray, uint16_t number_of_leds)` :id=api-ws2812-setleds +### `void ws2812_setleds(rgb_led_t *ledarray, uint16_t number_of_leds)` {#api-ws2812-setleds} Send RGB data to the WS2812 LED chain. -#### Arguments :id=api-ws2812-setleds-arguments +#### Arguments {#api-ws2812-setleds-arguments} - `rgb_led_t *ledarray` A pointer to the LED array. diff --git a/docs/zh-cn/README.md b/docs/zh-cn/README.md deleted file mode 100644 index 93dfbf1eef..0000000000 --- a/docs/zh-cn/README.md +++ /dev/null @@ -1,42 +0,0 @@ -# Quantum Mechanical Keyboard固件 - - - -## 什么是 QMK 固件? - -QMK (*Quantum Mechanical Keyboard*) 是一个社区维护的用于开发计算机输入设备的开源软件。社区专注像键盘，鼠标，MIDI设备的各种电子输入设备。社区内的核心小组成员维护[QMK固件](https://github.com/qmk/qmk_firmware)，[QMK配置器](https://config.qmk.fm)（QMK Configurator），[QMK工具箱](https://github.com/qmk/qmk_toolbox)（QMK Toolbox），[qmk.fm](https://qmk.fm)，并与各位社区成员维护这份文档。 - -## 如何入门 - -
- -?> **基础方式** [QMK配置器](zh-cn/newbs_building_firmware_configurator.md)
-用户友好的图形界面工具，无需具备编程知识基础。 - -?> **进阶方式** [基于源代码](zh-cn/newbs.md)
-功能更强大，但门槛较高。 - -
- -## 个性化定制 - -QMK提供了很多功能，对应着很多可供浏览的配套文档。大部分功能都是通过修改[键映射](zh-cn/keymap.md)及[键码](zh-cn/keycodes.md)实现的。 - -## 需要帮助？ - -请查阅[寻求帮助页面](zh-cn/support.md)以了解如何获取QMK使用方法的帮助。 - -## 回馈社区 - -有多种回馈社区的方法，最简单的方法是开始使用QMK并向你的朋友们推荐它。 - -* 可以在我们的论坛及聊天室进行互助： - * [/r/olkb](https://www.reddit.com/r/olkb/) - * [Discord服务器](https://discord.gg/Uq7gcHh) -* 点击页面下方的“Edit This Page”，可以对文档提供贡献。 -* [将这份文档翻译为你的语言](zh-cn/translating.md) -* [上报bug](https://github.com/qmk/qmk_firmware/issues/new/choose) -* [发起Pull Request](zh-cn/contributing.md) diff --git a/docs/zh-cn/_summary.md b/docs/zh-cn/_summary.md deleted file mode 100644 index a076f1a8c6..0000000000 --- a/docs/zh-cn/_summary.md +++ /dev/null @@ -1,191 +0,0 @@ - -* 新手教程 - * [介绍](zh-cn/newbs.md) - * [入门](zh-cn/newbs_getting_started.md) - * [构建第一个固件](zh-cn/newbs_building_firmware.md) - * [刷写固件](zh-cn/newbs_flashing.md) - * [寻求帮助](zh-cn/support.md) - * [其它资源](zh-cn/newbs_learn_more_resources.md) - * [QMK大纲](zh-cn/syllabus.md) - -* FAQ - * [常规FAQ](zh-cn/faq_general.md) - * [构建/编译QMK](zh-cn/faq_build.md) - * [QMK问题排查](zh-cn/faq_misc.md) - * [调试QMK](zh-cn/faq_debug.md) - * [键映射FAQ](zh-cn/faq_keymap.md) - * [充分利用AVR的存储空间](zh-cn/squeezing_avr.md) - * [术语表](zh-cn/reference_glossary.md) - -* 配置器(Configurator) - * [总览](zh-cn/newbs_building_firmware_configurator.md) - * [入门](zh-cn/configurator_step_by_step.md) - * [问题排查](zh-cn/configurator_troubleshooting.md) - * [框架](zh-cn/configurator_architecture.md) - * QMK API - * [总览](zh-cn/api_overview.md) - * [API文档](zh-cn/api_docs.md) - * [键盘支持](zh-cn/reference_configurator_support.md) - * [添加默认键映射](zh-cn/configurator_default_keymaps.md) - -* CLI - * [总览](zh-cn/cli.md) - * [配置](zh-cn/cli_configuration.md) - * [命令](zh-cn/cli_commands.md) - * [Tab补全](zh-cn/cli_tab_complete.md) - -* 使用QMK - * 导览 - * [功能定制](zh-cn/custom_quantum_functions.md) - * [利用Zadig安装驱动](zh-cn/driver_installation_zadig.md) - * [极简式制作](zh-cn/easy_maker.md) - * [键映射总览](zh-cn/keymap.md) - * 开发环境 - * [Docker指南](zh-cn/getting_started_docker.md) - * 刷写(Flashing) - * [刷写](zh-cn/flashing.md) - * [刷写ATmega32A (ps2avrgb)](zh-cn/flashing_bootloadhid.md) - * IDE - * [在Eclipse中使用QMK](zh-cn/other_eclipse.md) - * [在VSCode中使用QMK](zh-cn/other_vscode.md) - * Git最佳实践 - * [介绍](zh-cn/newbs_git_best_practices.md) - * [你自己的副本](zh-cn/newbs_git_using_your_master_branch.md) - * [冲突合并](zh-cn/newbs_git_resolving_merge_conflicts.md) - * [基于你的分支修复](zh-cn/newbs_git_resynchronize_a_branch.md) - * 键盘组装 - * [飞线指南](zh-cn/hand_wire.md) - * [ISP刷写指南](zh-cn/isp_flashing_guide.md) - - * 键码入门 - * [键码汇总](zh-cn/keycodes.md) - * [基础键码](zh-cn/keycodes_basic.md) - * [语言特定的键码](zh-cn/reference_keymap_extras.md) - * [修饰键](zh-cn/feature_advanced_keycodes.md) - * [原子键码](zh-cn/quantum_keycodes.md) - * [Magic键码](zh-cn/keycodes_magic.md) - - * 键码进阶 - * [指令](zh-cn/feature_command.md) - * [动态宏](zh-cn/feature_dynamic_macros.md) - * [Grave Escape](zh-cn/feature_grave_esc.md) - * [前导键](zh-cn/feature_leader_key.md) - * [Mod-Tap](zh-cn/mod_tap.md) - * [宏](zh-cn/feature_macros.md) - * [鼠标键](zh-cn/feature_mouse_keys.md) - * [Repeat Key](zh-cn/feature_repeat_key.md) - * [Space Cadet Shift](zh-cn/feature_space_cadet.md) - * [US ANSI上档键值](zh-cn/keycodes_us_ansi_shifted.md) - - * 软件特性 - * [自动Shift](zh-cn/feature_auto_shift.md) - * [组合键](zh-cn/feature_combo.md) - * [防抖API](zh-cn/feature_debounce_type.md) - * [按键锁定](zh-cn/feature_key_lock.md) - * [按键重定义](zh-cn/feature_key_overrides.md) - * [层](zh-cn/feature_layers.md) - * [粘滞键](zh-cn/one_shot_keys.md) - * [光标设备](zh-cn/feature_pointing_device.md) - * [原生HID](zh-cn/feature_rawhid.md) - * [Sequencer](zh-cn/feature_sequencer.md) - * [换手](zh-cn/feature_swap_hands.md) - * [一键多用](zh-cn/feature_tap_dance.md) - * [点按配置](zh-cn/tap_hold.md) - * [Unicode](zh-cn/feature_unicode.md) - * [用户空间](zh-cn/feature_userspace.md) - * [WPM计算](zh-cn/feature_wpm.md) - - * 硬件特性 - * 显示 - * [HD44780 LCD控制器](zh-cn/feature_hd44780.md) - * [ST7565 LCD驱动](zh-cn/feature_st7565.md) - * [OLED驱动](zh-cn/feature_oled_driver.md) - * 灯效 - * [背光](zh-cn/feature_backlight.md) - * [LED矩阵](zh-cn/feature_led_matrix.md) - * [RGB灯光](zh-cn/feature_rgblight.md) - * [RGB矩阵](zh-cn/feature_rgb_matrix.md) - * [音频](zh-cn/feature_audio.md) - * [蓝牙](zh-cn/feature_bluetooth.md) - * [Bootmagic Lite](zh-cn/feature_bootmagic.md) - * [自定义矩阵](zh-cn/custom_matrix.md) - * [Digitizer](zh-cn/feature_digitizer.md) - * [拨动开关（DIP Switch）](zh-cn/feature_dip_switch.md) - * [编码器（旋钮）](zh-cn/feature_encoders.md) - * [触摸反馈](zh-cn/feature_haptic_feedback.md) - * [摇杆](zh-cn/feature_joystick.md) - * [LED指示](zh-cn/feature_led_indicators.md) - * [MIDI](zh-cn/feature_midi.md) - * [Proton C转换](zh-cn/proton_c_conversion.md) - * [PS/2鼠标](zh-cn/feature_ps2_mouse.md) - * [分体式键盘](zh-cn/feature_split_keyboard.md) - * [速记](zh-cn/feature_stenography.md) - * [热敏打印机](zh-cn/feature_thermal_printer.md) - -* QMK开发 - * [PR Checklist](zh-cn/pr_checklist.md) - * 打破兼容的改动 - * [总览](zh-cn/breaking_changes.md) - * [我的PR已打上标记](zh-cn/breaking_changes_instructions.md) - * [近期的变更日志(Changelog)](zh-cn/ChangeLog/20210529.md "QMK v0.13.0 - 2021 May 29") - * [更早期的不兼容改动](zh-cn/breaking_changes_history.md) - - * C语言开发 - * [ARM调试指引](zh-cn/arm_debugging.md) - * [AVR处理器](zh-cn/hardware_avr.md) - * [C编码规范](zh-cn/coding_conventions_c.md) - * [兼容的微处理器](zh-cn/compatible_microcontrollers.md) - * [驱动](zh-cn/hardware_drivers.md) - * [ADC驱动](zh-cn/adc_driver.md) - * [Audio驱动](zh-cn/audio_driver.md) - * [I2C驱动](zh-cn/i2c_driver.md) - * [SPI驱动](zh-cn/spi_driver.md) - * [WS2812驱动](zh-cn/ws2812_driver.md) - * [EEPROM驱动](zh-cn/eeprom_driver.md) - * [串口驱动](zh-cn/serial_driver.md) - * [UART驱动](zh-cn/uart_driver.md) - * [操控GPIO](zh-cn/gpio_control.md) - * [键盘开发指引](zh-cn/hardware_keyboard_guidelines.md) - - * Python开发 - * [编码规范](zh-cn/coding_conventions_python.md) - * [QMK CLI开发](zh-cn/cli_development.md) - - * 配置器开发 - * QMK API - * [开发环境](zh-cn/api_development_environment.md) - * [架构总览](zh-cn/api_development_overview.md) - - * 硬件平台开发 - * Arm/ChibiOS - * [选择MCU](zh-cn/platformdev_selecting_arm_mcu.md) - * [启动引导](zh-cn/platformdev_chibios_earlyinit.md) - - * QMK参考信息 - * [参与到QMK](zh-cn/contributing.md) - * [翻译QMK文档](zh-cn/translating.md) - * [配置](zh-cn/config_options.md) - * [数据驱动配置](zh-cn/data_driven_config.md) - * [Make指引](zh-cn/getting_started_make_guide.md) - * [编写文档的最佳实践](zh-cn/documentation_best_practices.md) - * [文档模板](zh-cn/documentation_templates.md) - * [贡献配列到社区](zh-cn/feature_layouts.md) - * [单元测试](zh-cn/unit_testing.md) - * [常用函数](zh-cn/ref_functions.md) - * [info.json参考资料](zh-cn/reference_info_json.md) - - * 深入了解 - * [键盘工作原理](zh-cn/how_keyboards_work.md) - * [键盘矩阵原理](zh-cn/how_a_matrix_works.md) - * [了解QMK](zh-cn/understanding_qmk.md) - - * QMK内部细节 (编辑中) - * [定义](zh-cn/internals/defines.md) - * [输入回调的注册](zh-cn/internals/input_callback_reg.md) - * [Midi设备](zh-cn/internals/midi_device.md) - * [Midi设备驱动流程](zh-cn/internals/midi_device_setup_process.md) - * [Midi辅助功能](zh-cn/internals/midi_util.md) - * [发送函数](zh-cn/internals/send_functions.md) - * [Sysex工具](zh-cn/internals/sysex_tools.md) - - diff --git a/docs/zh-cn/api_docs.md b/docs/zh-cn/api_docs.md deleted file mode 100644 index 03ee6ab13e..0000000000 --- a/docs/zh-cn/api_docs.md +++ /dev/null @@ -1,73 +0,0 @@ -# QMK API - - - -本章节详述了QMK API的使用方法，若您是应用开发者，使用这套API可以实现[QMK](https://qmk.fm)键盘固件的编译支持。 - -## 总览 - -本服务提供了一套用于编译自定义键映射的异步API，通过POST方式发送JSON参数到API，定期检查执行状态，待固件编译完成后，即可下载生成的固件文件和固件的源文件（如果需要的话）。 - -#### 荷载JSON参数示例： - -```json -{ - "keyboard": "clueboard/66/rev2", - "keymap": "my_awesome_keymap", - "layout": "LAYOUT_all", - "layers": [ - ["KC_GRV","KC_1","KC_2","KC_3","KC_4","KC_5","KC_6","KC_7","KC_8","KC_9","KC_0","KC_MINS","KC_EQL","KC_GRV","KC_BSPC","KC_PGUP","KC_TAB","KC_Q","KC_W","KC_E","KC_R","KC_T","KC_Y","KC_U","KC_I","KC_O","KC_P","KC_LBRC","KC_RBRC","KC_BSLS","KC_PGDN","KC_CAPS","KC_A","KC_S","KC_D","KC_F","KC_G","KC_H","KC_J","KC_K","KC_L","KC_SCLN","KC_QUOT","KC_NUHS","KC_ENT","KC_LSFT","KC_NUBS","KC_Z","KC_X","KC_C","KC_V","KC_B","KC_N","KC_M","KC_COMM","KC_DOT","KC_SLSH","KC_RO","KC_RSFT","KC_UP","KC_LCTL","KC_LGUI","KC_LALT","KC_MHEN","KC_SPC","KC_SPC","KC_HENK","KC_RALT","KC_RCTL","MO(1)","KC_LEFT","KC_DOWN","KC_RIGHT"], - ["KC_ESC","KC_F1","KC_F2","KC_F3","KC_F4","KC_F5","KC_F6","KC_F7","KC_F8","KC_F9","KC_F10","KC_F11","KC_F12","KC_TRNS","KC_DEL","BL_STEP","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","_______","KC_TRNS","KC_PSCR","KC_SCRL","KC_PAUS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","MO(2)","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_PGUP","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","MO(1)","KC_LEFT","KC_PGDN","KC_RGHT"], - ["KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","QK_BOOT","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","MO(2)","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","MO(1)","KC_TRNS","KC_TRNS","KC_TRNS"] - ] -} -``` - -如上可见，荷载参数里有用于生成固件文件的所有键盘信息。每一个层定义都包含了与键盘 `LAYOUT` 宏定义一致的QMK键码列表数据，若该键盘有多个支持的 `LAYOUT` 宏定义，也可以指定使用的是哪一个。 - -## 提交一个编译job - -若要将键映射配置编译成固件文件，仅需将JSON参数通过POST发送至 `/v1/compile` 节点。下面的示例中我们假设JSON荷载参数已存放在 `json_data` 文件中。 - -``` -$ curl -H "Content-Type: application/json" -X POST -d "$(< json_data)" https://api.qmk.fm/v1/compile -{ - "enqueued": true, - "job_id": "ea1514b3-bdfc-4a7b-9b5c-08752684f7f6" -} -``` - -## 检查状态 - -键映射配置提交后，可以简单地通过 HTTP GET 请求来查询job状态： - -``` -$ curl https://api.qmk.fm/v1/compile/ea1514b3-bdfc-4a7b-9b5c-08752684f7f6 -{ - "created_at": "Sat, 19 Aug 2017 21:39:12 GMT", - "enqueued_at": "Sat, 19 Aug 2017 21:39:12 GMT", - "id": "f5f9b992-73b4-479b-8236-df1deb37c163", - "status": "running", - "result": null -} -``` - -这份信息告诉我们编译job已经提交到队列中且正在执行。job的状态有5种： - -* **failed（失败）**: 编译服务出现问题。 -* **finished（完成）**: 编译已完成，`result` 字段中保存了编译结果。 -* **queued（排队中）**: 键映射job在等待可用的编译服务器。 -* **running（执行中）**: 编译进行中，应当很快就会结束。 -* **unknown（未知）**: 出现了较严重的错误，请给我们[提交一个bug](https://github.com/qmk/qmk_compiler/issues). - -## 确认编译产出 - -编译job完成后请查看 `result` 字段，该字段下保存了如下信息项的哈希表数据： - -* `firmware_binary_url`: 用于刷写的固件文件URL列表 -* `firmware_keymap_url`: `keymap.c` 文件URL列表 -* `firmware_source_url`: 完整的固件源代码URL列表 -* `output`: 编译job的stdout及stderr输出信息，所有错误信息都会在这里。 diff --git a/docs/zh-cn/api_overview.md b/docs/zh-cn/api_overview.md deleted file mode 100644 index a07cfb7427..0000000000 --- a/docs/zh-cn/api_overview.md +++ /dev/null @@ -1,20 +0,0 @@ -# QMK API - - - -QMK API提供了一套可用于Web及GUI工具可用的异步API，用于实现将任何[QMK](https://qmk.fm/)支持的键盘的键映射方案进行编译。已有的键映射模板支持所有的QMK键码并且不需要额外的C代码需求。键盘的维护团队可以提供新的模板来启用更多功能的支持。 - -## App开发者 - -若您是一位意愿将这套API引入您的程序中的移动端App开发者，请参阅[API使用指引](zh-cn/api_docs.md)。 - -## 键盘维护团队 - -若您希望强化您维护的键盘方案在QMK编译API中的支持，请参阅[键盘支持](zh-cn/reference_configurator_support.md)。 - -## 后端开发者 - -若您对这套API系统本身感兴趣，请参阅[开发环境](zh-cn/api_development_environment.md)搭建环境并继续深入探索[架构总览](zh-cn/api_development_overview.md)。 diff --git a/docs/zh-cn/cli.md b/docs/zh-cn/cli.md deleted file mode 100644 index 22c2db92c8..0000000000 --- a/docs/zh-cn/cli.md +++ /dev/null @@ -1,43 +0,0 @@ -# QMK CLI :id=qmk-cli - - - -## 总览 :id=overview - -QMK CLI可以让构建QMK键盘的过程更轻松一些，我们已提供的一批指令可用于简化及流式化地处理一些常见工作，如获取并编译QMK固件，创建新的键映射等。 - -### 依赖项 :id=requirements - -QMK依赖Python 3.6或更高版本。我们已经尽力缩减依赖项，但在[`requirements.txt`](https://github.com/qmk/qmk_firmware/blob/master/requirements.txt)中的依赖项是需安装的包。在安装QMK CLI时这些依赖项也会自动完成安装。 - -### 通过 Homebrew 安装(macOS 及部分 Linux) :id=install-using-homebrew - -若已安装[Homebrew](https://brew.sh)，可以按如下方法安装QMK: - -``` -brew install qmk/qmk/qmk -export QMK_HOME='~/qmk_firmware' # 可选，指定 `qmk_firmware` 的路径 -qmk setup # 拉取 `qmk/qmk_firmware` 并选择性地配置构建环境 -``` - -### 通过 pip 安装 :id=install-using-easy_install-or-pip - -未在以上列出的操作系统可以手动安装QMK。首先确认已安装Python 3.6（或更高版本）及 pip，然后通过如下指令安装QMK： - -``` -python3 -m pip install qmk -export QMK_HOME='~/qmk_firmware' # 可选，指定 `qmk_firmware` 的路径 -qmk setup # 拉取 `qmk/qmk_firmware` 并选择性地配置构建环境 -``` - -### 其它操作系统的安装包 :id=packaging-for-other-operating-systems - -我们正在寻求可以制作维护更多操作系统下可用的 `qmk` 安装包的开发者，若您愿意为您的操作系统制作安装包，请遵循如下指引： - -* 当该系统下的最佳实践与本指引冲突时，请遵循系统的最佳实践方案 - * 但请在注释中列明此处违反这份指引的原因 -* 在 virtualenv 下安装 -* 指引用户去设置 `QMK_HOME` 环境变量，使得固件源文件拉取路径不再是默认的 `~/qmk_firmware` diff --git a/docs/zh-cn/cli_commands.md b/docs/zh-cn/cli_commands.md deleted file mode 100644 index ed36ed975b..0000000000 --- a/docs/zh-cn/cli_commands.md +++ /dev/null @@ -1,503 +0,0 @@ -# QMK CLI 命令 - - - -# 用户命令 - -## `qmk compile` - -该命令用于在指定目录下编译固件，可用于构建导出的JSON数据，代码库中的键映射，或是当前目录下的键盘。 - -该命令会尝试感知目录路径，当你在键盘或键映射目录下执行时，KEYBOARD及KEYMAP参数将被自动填入。 - -**用于配置器导出的数据时**： - -``` -qmk compile [-c] -``` - -**用于键映射时**： - -``` -qmk compile [-c] [-e =] [-j ] -kb -km -``` - -**在键盘目录下时**： - -须在存在默认键映射的键盘目录下执行，或是在键盘的键映射子目录下，否则须指定参数 `--keymap ` -``` -qmk compile -``` - -**构建所有支持该键映射的键盘时**： - -``` -qmk compile -kb all -km -``` - -**示例**： -``` -$ qmk config compile.keymap=default -$ cd ~/qmk_firmware/keyboards/planck/rev6 -$ qmk compile -Ψ Compiling keymap with make planck/rev6:default -... -``` -指定键映射参数时 - -``` -$ cd ~/qmk_firmware/keyboards/clueboard/66/rev4 -$ qmk compile -km 66_iso -Ψ Compiling keymap with make clueboard/66/rev4:66_iso -... -``` -位于键盘目录下时 - -``` -$ cd ~/qmk_firmware/keyboards/gh60/satan/keymaps/colemak -$ qmk compile -Ψ Compiling keymap with make gh60/satan:colemak -... -``` - -**在配列目录下时**： - -必须是在 `qmk_firmware/layouts/` 下的键映射目录下。 -``` -qmk compile -kb -``` - -**示例**： -``` -$ cd ~/qmk_firmware/layouts/community/60_ansi/mechmerlin-ansi -$ qmk compile -kb dz60 -Ψ Compiling keymap with make dz60:mechmerlin-ansi -... -``` - -**并行编译**： - -在编译时添加 `-j`/`--parallel` 开关可能有助于加快编译速度。 -``` -qmk compile -j -kb -``` -`num_jobs` 用于指定并行的job上限，将其设置为0可以实现无限制的并行编译。 -``` -qmk compile -j 0 -kb -``` - -## `qmk flash` :id=qmk-flash - -该命令与 `qmk compile` 类似，但额外地可以指定bootloader。bootloader参数是可选的，默认会指定为 `:flash`。可通过 `-bl ` 来指定bootloader。请查阅[刷写固件](zh-cn/flashing.md)指引以深入了解可用的bootloader信息。 - -该命令会尝试感知目录路径，当你在键盘或键映射目录下执行时，KEYBOARD及KEYMAP参数将被自动填入。 - -**用于配置器导出的数据时**： - -``` -qmk flash [-bl ] [-c] [-e =] [-j ] -``` - -**用于键映射时**： - -``` -qmk flash -kb -km [-bl ] [-c] [-e =] [-j ] -``` - -**列出所有bootloader** - -``` -qmk flash -b -``` - -## `qmk config` - -该命令用于配置QMK功能，完整的 `qmk config` 文档参见[CLI配置](zh-cn/cli_configuration.md)。 - -**使用方法**： - -``` -qmk config [-ro] [config_token1] [config_token2] [...] [config_tokenN] -``` - -## `qmk cd` - -该命令会启动一个新的 shell 会话并定位到 `qmk_firmware` 所在目录。 - -须留意如果你已经位于 `QMK_HOME` 下的某个位置（比如 `keyboards/` 目录中），该指令不会生效。 - -若要退回到原来的 shell 会话，只需要执行 `exit`。 - -**使用方法**: - -``` -qmk cd -``` - -## `qmk console` - -该命令用于连接键盘终端并展示调试信息。仅当键盘固件通过 `CONSOLE_ENABLE=yes` 编译时有效。 - -**用法**： - -``` -qmk console [-d :[:]] [-l] [-n] [-t] [-w ] -``` - -**示例**： - -连接到所有可用的键盘并输出终端信息： - -``` -qmk console -``` - -列出所有设备： - -``` -qmk console -l -``` - -仅输出 clueboard/66/rev3 键盘的信息: - -``` -qmk console -d C1ED:2370 -``` - -仅输出第二把 clueboard/66/rev3 键盘的信息: - -``` -qmk console -d C1ED:2370:2 -``` - -输出时间戳及VID:PID以替代键盘名： - -``` -qmk console -n -t -``` - -屏蔽bootloader的消息： - -``` -qmk console --no-bootloaders -``` - -## `qmk doctor` - -该命令用以检查你的开发环境并对发现的潜在的构建及刷写问题进行提醒，如果您乐意，它也可以修复其中大部分问题。 - -**用法**： - -``` -qmk doctor [-y] [-n] -``` - -**示例**： - -检查开发环境中的问题并提示是否修复： - - qmk doctor - -检查开发环境中的问题并自动进行修复： - - qmk doctor -y - -检查开发环境中的问题，仅生成报告： - - qmk doctor -n - -## `qmk format-json` - -将JSON文件格式化为（尽量）便于阅读的形式。会自动分辨JSON结构类型（info.json还是keymap.json），必要时也可以通过 `--format` 指定。 - -**用法**： - -``` -qmk format-json [-f FORMAT] -``` - -## `qmk info` - -展示QMK中的键盘及键映射信息，该命令用来获取键盘信息，输出配列，展示底层按键矩阵，及格式化地输出键映射JSON数据。 - -**用法**： - -``` -qmk info [-f FORMAT] [-m] [-l] [-km KEYMAP] [-kb KEYBOARD] -``` - -该命令会尝试感知目录路径，当你在键盘或键映射目录下执行时，KEYBOARD及KEYMAP参数将被自动填入。 - -**示例**： - -输出键盘的基础信息： - - qmk info -kb planck/rev5 - -输出键盘的矩阵信息： - - qmk info -kb ergodox_ez -m - -输出键盘的键映射JSON数据： - - qmk info -kb clueboard/california -km default - -## `qmk json2c` - -从QMK配置器导出的数据中生成 keymap.c 文件 -Creates a keymap.c from a QMK Configurator export. - -**用法**： - -``` -qmk json2c [-o OUTPUT] filename -``` - -## `qmk c2json` - -从 keymap.c 文件中生成 keymap.json -**注意：** 解析C代码文件并不容易，该命令有可能无法对你的键映射文件生效，不使用C预处理代码有时可以解决问题。 - -**用法**： - -``` -qmk c2json -km KEYMAP -kb KEYBOARD [-q] [--no-cpp] [-o OUTPUT] filename -``` - -## `qmk lint` - -检查键盘及键映射数据并提示出常见错误与问题，以及不符合模板规范的地方。 - -**用法**： - -``` -qmk lint [-km KEYMAP] [-kb KEYBOARD] [--strict] -``` - -该命令会尝试感知目录路径，当你在键盘或键映射目录下执行时，KEYBOARD及KEYMAP参数将被自动填入。 - -**示例**： - -基本的lint检查： - - qmk lint -kb rominronin/katana60/rev2 - -## `qmk list-keyboards` - -该命令可以列出 `qmk_firmware` 中所有的键盘 - -**用法**： - -``` -qmk list-keyboards -``` - -## `qmk list-keymaps` - -该命令可以列出指定键盘（及指定版本）下的所有键映射。 - -该命令会尝试感知目录路径，当你在键盘或键映射目录下执行时，KEYBOARD及KEYMAP参数将被自动填入。 - -**用法**： - -``` -qmk list-keymaps -kb planck/ez -``` - -## `qmk new-keyboard` - -该命令可基于现有模板创建出新的键盘定义。 - -对于未给出的参数，会提示你输入，若未传入 `-u` 参数且 .gitconfig 中设置了 `user.name`，则会提示你使用该值作为默认用户名。 - -**用法**： - -``` -qmk new-keyboard [-kb KEYBOARD] [-t {avr,ps2avrgb}] -u USERNAME -``` - -## `qmk new-keymap` - -该命令可基于键盘已有的默认键映射创建新的键映射。 - -该命令会尝试感知目录路径，当你在键盘或键映射目录下执行时，KEYBOARD及KEYMAP参数将被自动填入。 - -**用法**： - -``` -qmk new-keymap [-kb KEYBOARD] [-km KEYMAP] -``` - -## `qmk clean` - -该命令会清理 `.build` 目录，若传入 `--all` 开关，在 `qmk_firmware` 下的所有.hex及.bin文件也会一并删除。 - -**用法**： - -``` -qmk clean [-a] -``` - ---- - -# 面向开发者的命令 - -## `qmk format-text` - -该命令会重新格式化并统一文件的换行符。 - -代码库下所有的文件须使用Unix换行符（LF）。 -若你在**Windows**下进行开发，必须确保文件中的换行符是正确的，才能让你的PR被允许合入。 - -``` -qmk format-text -``` - -## `qmk format-c` - -该命令会使用clang-format来格式化C代码。 - -不带参数地执行该命令以用来格式化核心代码相关的改动，默认会通过 `git diff` 来检查 `origin/master`， 可以通过 `-b <分支名>` 来改变检查的分支。 - -带着 `-a` 开关执行命令会格式化所有的核心代码，也可以在命令行中传入文件名来指定格式化某个文件。 - -**用以处理指定文件时**： - -``` -qmk format-c [file1] [file2] [...] [fileN] -``` - -**用以处理所有的核心代码时**： - -``` -qmk format-c -a -``` - -**用以处理 origin/master 下的所有改动时**： - -``` -qmk format-c -``` - -**用以处理指定分支下的所有改动时**： - -``` -qmk format-c -b branch_name -``` - -## `qmk generate-compilation-database` - -**用法**: - -``` -qmk generate-compilation-database [-kb KEYBOARD] [-km KEYMAP] -``` - -创建新 `compile_commands.json` 文件。 - -你的IDE/编辑器是否使用了“编程语言本地服务器”（language server）且 _总是_ 无法找到全部的包含文件（include files）？是不是很讨厌红色的波浪线？想不想让你的编辑器看得懂 `#include QMK_KEYBOARD_H`？你需要的是一个[编译数据库](https://clang.llvm.org/docs/JSONCompilationDatabase.html)！而 QMK 可以帮助你构建出一个。 - -该命令需要知道你在构建的是哪个键盘及键映射，它使用与 `qmk compile` 命令一样的选项：参数、当前目录以及配置文件。 - -**示例：** - -``` -$ cd ~/qmk_firmware/keyboards/gh60/satan/keymaps/colemak -$ qmk generate-compilation-database -Ψ Making clean -Ψ Gathering build instructions from make -n gh60/satan:colemak -Ψ Found 50 compile commands -Ψ Writing build database to /Users/you/src/qmk_firmware/compile_commands.json -``` - -现在可以打开你的开发环境并享受没有波浪线的日子了。 - -## `qmk docs` - -该命令会在本地启动一个HTTP服务，从而你可以浏览及改进文档，默认端口号为8936，使用 `-b`/`--browser` 开关可以让该命令自动通过默认浏览器打开链接地址。 - -**用法**： - -``` -qmk docs [-b] [-p PORT] -``` - -## `qmk generate-docs` - -该命令可以在本地生成QMK文档，用以文档的常规浏览使用，或进行文档改进工作。可以使用类似[serve](https://www.npmjs.com/package/serve)这样的工具来浏览生成的文档文件。 - -**用法**： - -``` -qmk generate-docs -``` - -## `qmk generate-rgb-breathe-table` - -该命令可以生成用于[RGB灯光](zh-cn/feature_rgblight.md)的呼吸效果的查询表（LUT）头文件。将该文件命名为 `rgblight_breathe_table.h` 并放入键盘或键映射目录下，可以覆盖替换 `quantum/rgblight/` 下的默认LUT。 - -**用法**： - -``` -qmk generate-rgb-breathe-table [-q] [-o OUTPUT] [-m MAX] [-c CENTER] -``` - -## `qmk kle2json` - -该命令可以将KLE原始数据转换成QMK配置器的JSON数据，可接受的输入可以是文件绝对路径，或当前目录下的文件名。若 `info.json` 文件存在，默认不会进行覆盖，通过指定 `-f` 或 `--force` 开关可以允许覆盖。 - -**用法**： - -``` -qmk kle2json [-f] -``` - -**示例**： - -``` -$ 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 format-python` - -该命令可以对 `qmk_firmware` 下的python代码进行格式化。 - -**用法**： - -``` -qmk format-python -``` - -## `qmk pytest` - -该命令会执行python测试框架，在你更改了python代码后，应确保该命令可以成功执行。 - -**用法**： - -``` -qmk pytest -``` - -**示例**: - -执行全部的测试套件： - - qmk pytest - -执行指定的测试用例组： - - qmk pytest -t qmk.tests.test_cli_commands - -执行单个测试用例： - - qmk pytest -t qmk.tests.test_cli_commands.test_c2json - qmk pytest -t qmk.tests.test_qmk_path diff --git a/docs/zh-cn/cli_configuration.md b/docs/zh-cn/cli_configuration.md deleted file mode 100644 index d3bca4a338..0000000000 --- a/docs/zh-cn/cli_configuration.md +++ /dev/null @@ -1,126 +0,0 @@ -# QMK CLI 配置 - - - -本文详述了 `qmk config` 功能及作用。 - -# 介绍 - -QMK CLI的配置系统是一套键/值（key/value）数据系统，每个键由一个子指令和一个参数名组成，通过点号（英文句号）分隔。这使得配置项可以简单直接地映射到命令行参数上。 - -## 简单示例 - -作为一个示例，对于指令 `qmk compile --keyboard clueboard/66/rev4 --keymap default` - -其存在两个命令行参数，可以通过如下方式从配置中读取： - -* `compile.keyboard` -* `compile.keymap` - -可以这样设置： - -``` -$ qmk config compile.keyboard=clueboard/66/rev4 compile.keymap=default -compile.keyboard: None -> clueboard/66/rev4 -compile.keymap: None -> default -Ψ Wrote configuration to '/Users/example/Library/Application Support/qmk/qmk.ini' -``` - -现在每次执行 `qmk compile` 时都不需要指定键盘及键映射参数了。 - -## 设置用户级的默认配置 - -当你需要在多个命令中使用一致的配置项时，比如很多命令都需要的 `--keyboard` 参数，相比于每次执行命令都去指定该参数值，你可以直接设置用户级的配置值，即可将该配置用于所有的命令。 - -示例： - -``` -$ qmk config user.keyboard=clueboard/66/rev4 user.keymap=default -user.keyboard: None -> clueboard/66/rev4 -user.keymap: None -> default -Ψ Wrote configuration to '/Users/example/Library/Application Support/qmk/qmk.ini' -``` - -# CLI文档 (`qmk config`) - -`qmk config` 命令可以管理配置数据。当不带额外参数执行时，会输出所有已有配置。存在参数时这些参数将被视为配置项参数，其格式须满足如下形式且无空格分隔： - - [.][=] - -## 设置配置值 - -在配置项的键后加 = 号进行值的设置，配置项的键必须是 `
.` 的完整形式。 - -举例： - -``` -$ qmk config default.keymap=default -default.keymap: None -> default -Ψ Wrote configuration to '/Users/example/Library/Application Support/qmk/qmk.ini' -``` - -## 读取配置值 - -可以读取整个配置文件、单独配置键或是一整个配置系列，也可以同时指定读取多个配置项。 - -### 全量配置读取示例 - - qmk config - -### 单系列配置读取示例 - - qmk config compile - -### 单配置项读取示例 - - qmk config compile.keyboard - -### 多配置项读取示例 - - qmk config user compile.keyboard compile.keymap - -## 删除配置值 - -将配置值设置为 `None` 即可删除该配置值。 - -示例： - -``` -$ qmk config default.keymap=None -default.keymap: default -> None -Ψ Wrote configuration to '/Users/example/Library/Application Support/qmk/qmk.ini' -``` - -## 批量操作 - -一个指令中可以合并执行多个读写操作，将依序进行执行输出： - -``` -$ qmk config compile default.keymap=default compile.keymap=None -compile.keymap=skully -compile.keyboard=clueboard/66_hotswap/gen1 -default.keymap: None -> default -compile.keymap: skully -> None -Ψ Wrote configuration to '/Users/example/Library/Application Support/qmk/qmk.ini' -``` - -# 用户配置相关的配置项 - -| 配置项 | 默认值 | 描述 | -|-------|-------|------| -| user.keyboard | None | 键盘路径（举例：`clueboard/66/rev4`） | -| user.keymap | None | 键盘名称（举例：`default`） | -| user.name | None | 用户的Github用户名 | - -# 所有配置项 - -| 配置项 | 默认值 | 描述 | -|-------|-------|------| -| compile.keyboard | None | 键盘路径（举例：`clueboard/66/rev4`） | -| compile.keymap | None | 键盘名称（举例：`default`） | -| hello.name | None | 执行时展示的欢迎信息 | -| new_keyboard.keyboard | None | 键盘路径（举例：`clueboard/66/rev4`） | -| new_keyboard.keymap | None | 键盘名称（举例：`default`） | diff --git a/docs/zh-cn/cli_tab_complete.md b/docs/zh-cn/cli_tab_complete.md deleted file mode 100644 index 7a16e9766c..0000000000 --- a/docs/zh-cn/cli_tab_complete.md +++ /dev/null @@ -1,32 +0,0 @@ -# QMK Tab补全 - - - -在使用Bash 4.2及更高版本、Zsh或FiSH时，可以启用QMK CLI的Tab补全功能，可以实现对 `qmk` 参数中的开关、键盘、文件等参数的自动补全。 - -## 设置 - -有以下几种启用Tab补全的方法。 - -### 仅当前用户生效 - -将以下内容添加到文件 `.profile` 或 `.bashrc` 的末尾: - - source ~/qmk_firmware/util/qmk_tab_complete.sh - -若你的 `qmk_firmware` 存放在其它路径，以上路径也需要调整。 - -### 系统级的符号关联 - -若想让所有本地用户都可以实现Tab补全，可以按如下方法添加符号连接到 `qmk_tab_complete.sh` 脚本： - - `ln -s ~/qmk_firmware/util/qmk_tab_complete.sh /etc/profile.d/qmk_tab_complete.sh` - -### 系统级的脚本拷贝 - -有时符号连接的方案无效，可以改用拷贝文件到指定位置的方案。但须留意该Tab补全脚本可能会不定时更新，你需要定期重新拷贝一次该脚本。 - - cp util/qmk_tab_complete.sh /etc/profile.d diff --git a/docs/zh-cn/configurator_architecture.md b/docs/zh-cn/configurator_architecture.md deleted file mode 100644 index 386ebd6899..0000000000 --- a/docs/zh-cn/configurator_architecture.md +++ /dev/null @@ -1,66 +0,0 @@ -# QMK配置器框架 - - - -本章节提供了QMK配置器前端技术框架信息，若你对QMK配置器前端工程本身感兴趣，可以从[QMK配置器](https://github.com/qmk/qmk_configurator)代码库开始。 - -# 总览 - -![QMK配置器技术框架图](./../configurator_diagram.svg) - -# 详述 - -QMK配置器基于[单页面框架](https://en.wikipedia.org/wiki/Single-page_application)实现，供使用者创建兼容QMK键盘的自定义键映射方案。键映射方案可以导出为JSON格式的数据，也可以编译出可通过[QMK工具箱](https://github.com/qmk/qmk_toolbox)刷写到键盘中的固件文件。 - -配置器从“键盘元数据仓库（Keyboard Metadata store）”获取键盘元数据，编译请求通过QMK API提交，编译产出放在S3兼容的数据仓库[Digital Ocean空间](https://www.digitalocean.com/products/spaces/)中。 - -## 配置器前端 - -地址： - -[配置器前端](https://config.qmk.fm)会编译并产出一些静态文件并通过Github Pages托管，每当[QMK配置器 `master`](https://github.com/qmk/qmk_configurator)分支收到推送的提交时都会触发。可以通过[QMK配置器 actions页面](https://github.com/qmk/qmk_configurator/actions/workflows/build.yml)查看这些job的状态。 - -## 键盘元数据 - -地址： - -每当[qmk_firmware](https://github.com/qmk/qmk_firmware)仓库中的键盘定义变化时，会生成JSON格式的键盘元数据，并上传到指定空间用于配置器生成每种键盘的UI展现。可以在[QMK固件 actions页面](https://github.com/qmk/qmk_firmware/actions/workflows/api.yml)查看相关job的状态。如果你是QMK开发团队成员（Collaborator），可以使用 `workflow_dispatch` 事件触发器来手动执行该job。 - -## QMK API - -地址： - -QMK API接受 `keymap.json` 文件输入并进行编译，这和你在 `qmk compile` 和 `qmk flash` 中使用的文件一样。当 `keymap.json` 文件被提交后，浏览器中的页面将定时查看job状态（每2秒一次，有时更久一些）直到job完成。最终产出的JSON描述信息里包含了键映射方案的源文件，及编译出的二进制的可下载链接地址。 - -为遵循GPL协议，QMK API会确保源文件及编译产出总是同时提供的。 - -API有3种非异常的回应状态- - -1. 编译job排队中 -2. 编译job执行中 -3. 编译job已完成 - -### 编译job排队中 - -此状态表明[QMK编译器](#QMK编译器)节点还未选中该job，在配置器页面此时会显示“等待一个可用的烤炉（Waiting for an oven）”。 - -### 编译job执行中 - -此状态说明编译job已经在执行中，配置器页面会显示为“烤制中”(Baking)。 - -### 编译job已完成 - -此状态说明编译job已经执行完毕，输出的JSON格式的状态信息里有源文件及编译产出的二进制文件的下载链接项。 - -## Redis/RQ - -QMK API通过Redis队列分发job到可用的[QMK编译器](#QMK编译器)节点。接收到的 `keymap.json` 文件先送到RQ队列，而 `qmk_compiler` 节点则从中拉取执行。 - -## QMK编译器 - -[QMK编译器](https://github.com/qmk/qmk_compiler)负责执行 `keymap.json` 文件的实际编译工作。它的工作逻辑是先拉取有请求的 `qmk_firmware` 分支代码，执行 `qmk compile keymap.json`，最后上传源文件及二进制产出到Digital Ocean空间中。 - -当用户需要下载源代码/二进制文件时，API会给出重定向后的已鉴权地址链接。 diff --git a/docs/zh-cn/configurator_default_keymaps.md b/docs/zh-cn/configurator_default_keymaps.md deleted file mode 100644 index 9f990286f2..0000000000 --- a/docs/zh-cn/configurator_default_keymaps.md +++ /dev/null @@ -1,198 +0,0 @@ -# 向QMK配置器中添加默认键映射 :id=adding-default-keymaps - - - -本章节描述了如何向QMK配置器中添加一款键盘的默认键映射 - - -## 技术信息 :id=technical-information - -QMK配置器使用JSON作为键映射的本地文件格式。我们尽力确保其行为与在 `qmk_firmware` 中 执行 `make :default` 时一致。 - -该目录下的键映射需要定义四个键值对： - -* `keyboard` (字符串) - * 键盘名称，与执行 `make` 进行编译时使用的一致（如 `make 1upkeyboards/1up60rgb:default`）。 -* `keymap` (字符串) - * 应设置为 `default`. -* `layout` (字符串) - * 默认键映射应使用的配列宏定义。 -* `layers` (数组) - * 键映射数据。此键下的每行元素对应一个层定义，层定义中包含该层的键码组成信息。 - -额外地，大部分键映射中还有一个 `commit` 项，该项并不是QMK配置器后端服务API所需，而是用于告知配置器维护者这份JSON键映射数据来源于代码库中的哪个版本的键映射。该值为 `qmk_firmware` 代码库中最后一次修改键盘默认 `keymap.c` 文件提交的commit的SHA标记。该SHA值的获取方式是拉取[`qmk/qmk_firmware` 库的 `master`分支](https://github.com/qmk/qmk_firmware/tree/master/)后，执行 `git log -1 --pretty=oneline -- keyboards//keymaps/default/keymap.c`（若键盘有什么问题且存在 `keymap.json` 文件，则用之作为替代），执行结果应类似于： - -``` -f14629ed1cd7c7ec9089604d64f29a99981558e8 Remove/migrate action_get_macro()s from default keymaps (#5625) -``` - -本例中，`f14629ed1cd7c7ec9089604d64f29a99981558e8` 即应为 `commit` 的值。 - - -## 示例 :id=example - -若某人想添加H87a Hineybush键盘的默认键映射方案，应到 `qmk_firmware` 下H87a的默认键映射下执行上述 `git log` 命令： - -``` -user ~/qmk_firmware (master) -$ git log -1 --pretty=oneline master -- keyboards/hineybush/h87a/keymaps/default/keymap.c -ef8878fba5d3786e3f9c66436da63a560cd36ac9 Hineybush h87a lock indicators (#8237) -``` - -在我们获取了commit哈希值后，还需要键映射定义（为加强可读性进行了编辑处理）： - -```c -... -#include QMK_KEYBOARD_H - -const uint16_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] = { - - [0] = LAYOUT_all( - KC_ESC, KC_F1, KC_F2, KC_F3, KC_F4, KC_F5, KC_F6, KC_F7, KC_F8, KC_F9, KC_F10, KC_F11, KC_F12, KC_PSCR, KC_SCRL, KC_PAUS, - KC_GRV, KC_1, KC_2, KC_3, KC_4, KC_5, KC_6, KC_7, KC_8, KC_9, KC_0, KC_MINS, KC_EQL, KC_BSPC, KC_BSPC, KC_INS, KC_HOME, KC_PGUP, - KC_TAB, KC_Q, KC_W, KC_E, KC_R, KC_T, KC_Y, KC_U, KC_I, KC_O, KC_P, KC_LBRC, KC_RBRC, KC_BSLS, KC_DEL, KC_END, KC_PGDN, - KC_CAPS, KC_A, KC_S, KC_D, KC_F, KC_G, KC_H, KC_J, KC_K, KC_L, KC_SCLN, KC_QUOT, KC_NUHS, KC_ENT, - KC_LSFT, KC_NUBS, KC_Z, KC_X, KC_C, KC_V, KC_B, KC_N, KC_M, KC_COMM, KC_DOT, KC_SLSH, KC_RSFT, KC_TRNS, KC_UP, - KC_LCTL, KC_LGUI, KC_LALT, KC_SPC, KC_RALT, MO(1), KC_RGUI, KC_RCTL, KC_LEFT, KC_DOWN, KC_RGHT), - - [1] = LAYOUT_all( - KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, RGB_TOG, RGB_MOD, RGB_HUD, RGB_HUI, RGB_SAD, RGB_SAI, RGB_VAD, RGB_VAI, BL_TOGG, BL_DEC, BL_INC, - KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_VOLU, - KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, QK_BOOT, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_MPLY, KC_MNXT, KC_VOLD, - KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, - KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, - KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS), - -}; -``` - -默认键映射使用了 `LAYOUT_all` 宏，最后其会成为 `layout` 项的值。编译为QMK配置器的JSON键映射数据后，输出文件应为： - -```json -{ - "keyboard": "hineybush/h87a", - "keymap": "default", - "commit": "ef8878fba5d3786e3f9c66436da63a560cd36ac9", - "layout": "LAYOUT_all", - "layers": [ - [ - "KC_ESC", "KC_F1", "KC_F2", "KC_F3", "KC_F4", "KC_F5", "KC_F6", "KC_F7", "KC_F8", "KC_F9", "KC_F10", "KC_F11", "KC_F12", "KC_PSCR", "KC_SCRL", "KC_PAUS", - "KC_GRV", "KC_1", "KC_2", "KC_3", "KC_4", "KC_5", "KC_6", "KC_7", "KC_8", "KC_9", "KC_0", "KC_MINS", "KC_EQL", "KC_BSPC", "KC_BSPC", "KC_INS", "KC_HOME", "KC_PGUP", - "KC_TAB", "KC_Q", "KC_W", "KC_E", "KC_R", "KC_T", "KC_Y", "KC_U", "KC_I", "KC_O", "KC_P", "KC_LBRC", "KC_RBRC", "KC_BSLS", "KC_DEL", "KC_END", "KC_PGDN", - "KC_CAPS", "KC_A", "KC_S", "KC_D", "KC_F", "KC_G", "KC_H", "KC_J", "KC_K", "KC_L", "KC_SCLN", "KC_QUOT", "KC_NUHS", "KC_ENT", - "KC_LSFT", "KC_NUBS", "KC_Z", "KC_X", "KC_C", "KC_V", "KC_B", "KC_N", "KC_M", "KC_COMM", "KC_DOT", "KC_SLSH", "KC_RSFT", "KC_TRNS", "KC_UP", - "KC_LCTL", "KC_LGUI", "KC_LALT", "KC_SPC", "KC_RALT", "MO(1)", "KC_RGUI", "KC_RCTL", "KC_LEFT", "KC_DOWN", "KC_RGHT" - ], - [ - "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "RGB_TOG", "RGB_MOD", "RGB_HUD", "RGB_HUI", "RGB_SAD", "RGB_SAI", "RGB_VAD", "RGB_VAI", "BL_TOGG", "BL_DEC", "BL_INC", - "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_VOLU", - "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "QK_BOOT", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_MPLY", "KC_MNXT", "KC_VOLD", - "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", - "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", - "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS" - ] - ] -} -``` - -`layers` 数组中的空白区域不影响键映射功能，仅为了方便阅读。 - - -## 附加说明 :id=caveats - -### 层定义只能通过序号进行引用 :id=layer-references - -QMK中常见的一种做法是通过一系列 `#define` 或 `enum` 类型声明来对层定义进行命名： - -```c -enum layer_names { - _BASE, - _MEDIA, - _FN -}; -``` - -对于C代码来讲可行，但对于配置器来讲，你*必须*使用层序号 - 上例中的`MO(_FN)` 应使用 `MO(2)`。 - -### 不支持任何形式的定制化代码 :id=custom-code - -需要在 keymap.c 文件中添加函数代码的功能，如Tap Dance或是Unicode，都*完全*无法在配置器中构建。即便是在 `qmk_firmware` 代码库中在键盘定义中设置了 `TAP_DANCE_ENABLE = yes`，也只会导致*任何*固件构建在配置器中行不通。这是由API及JSON格式的键映射数据同时造成的限制。 - -### 对自定义键码的不完全支持 :id=custom-keycodes - -仅有一个方案可以支持自定义键码：若自定义键码的逻辑实现是在 qmk_firmware 下的键盘定义中完成的，而非在键映射中，那么这个键码*可以*在配置器中使用且*可以*编译运行。（因此，）相对于在 `keymap.c` 中使用如下代码段： - -```c -enum custom_keycodes { - CUSTOM_1 = SAFE_RANGE, - CUSTOM_2, - CUSTOM_3 -}; -... -bool process_record_user(uint16_t keycode, keyrecord_t *record) { - switch(keycode) { - case CUSTOM_1: - if (record->event.pressed) { - SEND_STRING("This is custom keycode #1."); - } - return false; - case CUSTOM_2: - if (record->event.pressed) { - SEND_STRING("This is custom keycode #2."); - } - return false; - case CUSTOM_3: - if (record->event.pressed) { - SEND_STRING("This is custom keycode #3."); - } - return false; - } - return true; -}; -``` - -... 请将键码的 `enum` 定义块添加到键盘的头文件（``）中，例如（留意 `enum` 在这里命名为 `keyboard_keycodes`）： - -```c -enum keyboard_keycodes { - CUSTOM_1 = SAFE_RANGE, - CUSTOM_2, - CUSTOM_3, - NEW_SAFE_RANGE // 重要! -}; -``` - -... 之后在 `.c` 中的 `process_record_kb()` 代码逻辑应为： - -```c -bool process_record_kb(uint16_t keycode, keyrecord_t *record) { - switch(keycode) { - case CUSTOM_1: - if (record->event.pressed) { - SEND_STRING("This is custom keycode #1."); - } - return false; - case CUSTOM_2: - if (record->event.pressed) { - SEND_STRING("This is custom keycode #2."); - } - return false; - case CUSTOM_3: - if (record->event.pressed) { - SEND_STRING("This is custom keycode #3."); - } - return false; - } - return process_record_user(keycode, record); -}; -``` - -注意最后的 `process_record_user()` 调用，若用户需要添加自定义键码到键映射中，须使用 `NEW_SAFE_RANGE` 替代 `SAFE_RANGE`，而其定义来自于上面键盘层定义中。 - - -## 更多资料 :id=additional-reading - -为了让QMK配置器支持你的键盘，你的键盘定义必须存在于 `qmk_firmware` 代码库的 `master` 分支中。相关操作指引，请参见[在QMK配置器中支持你的键盘](zh-cn/reference_configurator_support.md). diff --git a/docs/zh-cn/configurator_step_by_step.md b/docs/zh-cn/configurator_step_by_step.md deleted file mode 100644 index bbfb71d5a6..0000000000 --- a/docs/zh-cn/configurator_step_by_step.md +++ /dev/null @@ -1,63 +0,0 @@ -# QMK 配置器: 入门 - - - -本章节描述了如何使用QMK配置器构建出固件文件的过程。 - -## 第一步：选择键盘 - -从下拉列表中选择一款用于创建键映射的键盘。 - -?> 当键盘有多个版本可选择时，请确保选择正确。 - -因为很重要，这里我再次说一遍： - -!> **请选择正确的版本！** - -如果你的键盘声称是基于QMK的但未在列表中，可能是开发者还未提交给我们，或者提交还未被合并进来。若在[Pull Request](https://github.com/qmk/qmk_firmware/pulls?q=is%3Aopen+is%3Apr+label%3Akeyboard)中没有找到请求支持该键盘的issue，请到[QMK固件](https://github.com/qmk/qmk_firmware/issues)提交一个issue。也有一些基于QMK的键盘是由制造商自己的GitHub账号在维护着，请也确认一下。 - -## 第二部：选择键盘配列 - -选择最适合你要创建的键映射的配列，一些键盘的配列不完整或有问题，后续会逐渐支持。 - -!> 有时会遇到没有特别适合的配列的情况，请选择 `LAYOUT_all`。 - -## 第三步：命名你的键映射 - -如何起名完全取决于你。 - -?> 如果编译时遇到了问题，可能是因为QMK固件代码库中已经有了同名项，可以尝试改一下名字。 - -## 第四步：设计你的键映射 - -以下三种方法可以添加键码： - -1. 拖拽 -2. 点击布局上的空白项，再点击所需的键码 -3. 点击布局上的空白项, 再点击你物理键盘上的按键 - -?> 鼠标在键上悬停时会有一个键码值的提示出现，详细描述信息请参见: - -* [基础键码资料](zh-cn/keycodes_basic.md) -* [进阶键码资料](zh-cn/feature_advanced_keycodes.md) - -!> 如果你选择的配列与物理实机有出入，请将不需要的按键留空。如果不清楚应该用哪个键，例如，你只需要一个退格键，但 `LAYOUT_all` 中有两个退格键，须将两个键都放上一样的键码。 - -## 第五步：保存键映射留待后续修订 - -当你调整完毕键映射方案，或打算以后继续编辑，点击 `导出Keymap JSON文件（Download this QMK Keymap JSON File）` 按钮，当前键映射方案将保存到你的计算机中，之后可以点击 `导入Keymap JSON文件(Upload a QMK Keymap JSON File)` 按钮导入后继续编辑。 - -!> **注意：** 导出的.json文件与 kbfirmware.com 和其它工具软件生成的并不兼容，如果你将导出的数据放到那些工具中，或尝试导入那些工具生成的.json文件，是不可行的。 - -## 第六步：编译固件 - -点击绿色的 `编译（Compile）` 按钮。 - -编译完成后，可以点击绿色的 `固件（Download Firmware）` 下载固件文件。 - -## 下一步：刷写到键盘中 - -参见[刷写固件](zh-cn/newbs_flashing.md). diff --git a/docs/zh-cn/configurator_troubleshooting.md b/docs/zh-cn/configurator_troubleshooting.md deleted file mode 100644 index a48ad1dd72..0000000000 --- a/docs/zh-cn/configurator_troubleshooting.md +++ /dev/null @@ -1,31 +0,0 @@ -# 配置器问题排查 - - - -## 我的 .json 文件不可用 - -如果该 .json 文件确实是QMK配置器中导出的，恭喜你遇到bug了，请在[QMK配置器](https://github.com/qmk/qmk_configurator/issues)库中提交一个issue。 - -如果不是……那么页面顶部加大加粗的提示让你不要使用其它 .json 文件，你是怎么错过的？ - -## 我的配列中有好多空格键，我应该怎么处理？ - -如果你是说有三个空格键栏，最好的做法是都放上空格键。这个处理方案也适用于退格键和Shift键。 - -## 用于...的键码是什么？ - -参见： - -* [基础键码资料](zh-cn/keycodes_basic.md) -* [进阶键码资料](zh-cn/feature_advanced_keycodes.md) - -## 无法编译 - -请检查键映射中所有的层，确保没有随机（random）键。 - -## Bug及其它问题 - -我们很乐意倾听你的需求及bug报告，请到[QMK配置器](https://github.com/qmk/qmk_configurator/issues)代码库中提交吧。 diff --git a/docs/zh-cn/contributing.md b/docs/zh-cn/contributing.md deleted file mode 100644 index 03d3ea916a..0000000000 --- a/docs/zh-cn/contributing.md +++ /dev/null @@ -1,175 +0,0 @@ -# 如何做贡献 - - - -👍🎉 首先感谢各位百忙之中抽空阅读本文档，并为我们无私奉献。给您点赞啦！ 🎉👍 - -第三方的帮助让QMK获得了成长与进步。我们希望提供一套对贡献者和维护者都感到简便实用的PR（pull request）及贡献流程，因此我们整理出了一些准则，以免你的PR在被接纳前需要大改一番。 - -* [项目概况](#project-overview) -* [代码规范](#coding-conventions) -* [一般教程](#general-guidelines) -* [行为守则对于我来说有何意义？](#what-does-the-code-of-conduct-mean-for-me) - -## 这文章巨长无比不想读啊! 我就想问个问题而已! - -您要是有关于QMK的问题，请在[OLKB Subreddit](https://reddit.com/r/olkb)或者是[Discord](https://discord.gg/Uq7gcHh)上进行提问。 - -请记住: - -* 你的问题也许要过几个小时才会有人回复，请耐心一些。 -* 参与到QMK中的成员都是在无偿地贡献着自己的时间和精力，我们没有受雇于开发QMK或是专职回答你的疑问。 -* 您可以看看下面的教程，可以让您的问题浅显易懂，更容易回答： - * https://opensource.com/life/16/10/how-ask-technical-questions - * http://www.catb.org/esr/faqs/smart-questions.html - -# 项目概况 :id=project-overview - -QMK很大一部分是C语言编写的，小部分特性是C++的。QMK的设计目标是在键盘上的嵌入式处理器中工作，如AVR([LUFA](https://www.fourwalledcubicle.com/LUFA.php))和ARM ([ChibiOS](https://www.chibios.org))。如果您对Arduino很熟悉的话，会发现优缺点也基本是相似的。但无论你之前是否有Arduino使用经验，都不会影响你参与到QMK贡献中来。 - - - -# 我到哪里寻求帮助？ - -您要是有问题的话可以 [提出一个issue](https://github.com/qmk/qmk_firmware/issues) 或 [在Discord上交流一下](https://discord.gg/Uq7gcHh). - -# 我怎样才能做出贡献？ - -您以前是否没有参与贡献过开源社区，而又想知道如何对QMK提供帮助？这里有一份快速指引！ -*译注：对于没有基本编程经验的人，请谨慎考虑这套操作流程，可参考，照着做很容易出问题，社区的语言障碍也会阻碍你对这些步骤的细节进行咨询* - -0. 先注册一个 [GitHub](https://github.com) 账户。 -1. 完整整理出来你要贡献的键映射，或是 [找一个你想解决的问题](https://github.com/qmk/qmk_firmware/issues)，或者 [找一个你想添加的特性](https://github.com/qmk/qmk_firmware/issues?q=is%3Aopen+is%3Aissue+label%3Afeature)。 -2. 把关联着问题的仓库fork到你的仓库。这样在`你的GitHub用户名/qmk_firmware` 下就有一个副本啦。 -3. 使用 `git clone https://github.com/你的GitHub用户名/仓库名.git` 命令把仓库同步到你的电脑中。 -4. 您要是想开发一个新特性的话可以先创建一个issue和QMK的维护者讨论一下您要做什么。 -5. 使用 `git checkout -b 此处写分支名字（别用汉字）` 命令来创建一个新分支（branch）用于开发。 -6. 对要解决的问题或要添加的特性进行适当的更改。 -7. 使用 `git add 把改变的文件的目录写这里` 可以添加改变的文件内容到git用于管理工程状态的索引（快照）里。 -8. 使用 `git commit -m "这里写修改的相关信息"` 来描述你做出了什么修改。 -9. 使用 `git push origin 此处写分支名字`来把你的更改同步到GitHub库里（反正不是打篮球那个库里）。 -10. 提交一个[QMK 固件的pull request](https://github.com/qmk/qmk_firmware/pull/new/master)。 -11. 给你的pull request拟一个标题，包括简短的描述和问题或错误代码。比如, 你可以起一个这样的"Added more log outputting to resolve #4352"（最好用英语，毕竟QMK的维护团队成员都是英语语系，有可能会看不懂中文）。 -12. 在描述（description）里面写你做了哪些更改，你的代码里还存在什么问题, 或者你想对QMK维护着询问的问题。你的pull request有点小问题无伤大雅（没有完美的pull request）, QMK维护团队会尽力帮您改进的！ -13. 维护人员审查代码可能需要一些时间。 -14. 维护人员会通知您要更改什么地方，然后您就按照建议改一改。 -15. 你的pull request合并成功了，恭喜！ - -# 代码规范 :id=coding-conventions - -我们的编码风格很容易掌握，如果你有C语言或Python编码经验，跟随我们的编码风格不会有什么困难。 - -* [编码规范 - C](zh-cn/coding_conventions_c.md) -* [编码规范 - Python](zh-cn/coding_conventions_python.md) - -# 基本准则 :id=general-guidelines - -在QMK中存在多种类型的修改需求，因此也会有审查严格性上的差异。请在做出任何修改时留意，你的改动隶属于什么类型。 - -* 将PR（pull request）分成一个个的逻辑单元。 比如，不要一次将两个新特性PR出去。要添加的特性排好队，一个一个来。 -* 提交之前使用 `git diff --check` 做以下检查，不要提交多余的空格 -* 确定你的代码能通过编译 - * 键映射: 确定`make keyboard:your_new_keymap` 不返回错误 - * 键盘: 确定 `make keyboard:all` 不返回错误 - * 核心代码: 确定 `make all` 不返回错误 -* 提交的信息尽量明确。第一行写点简短介绍(每行不多于70个英文字母), 第二行空着,第三行和后面就要写些必要的细节了。最好用英文写，比如: - -``` -Adjust the fronzlebop for the kerpleplork - -The kerpleplork was intermittently failing with error code 23. The root cause was the fronzlebop setting, which causes the kerpleplork to activate every N iterations. - -Limited experimentation on the devices I have available shows that 7 is high enough to avoid confusing the kerpleplork, but I'd like to get some feedback from people with ARM devices to be sure. -``` - -!> **特别留意：** 若你要对其它QMK使用者提交的代码进行功能修改或尝试修复bug，例如非默认的键映射、用户空间和配列部分，须在PR中标记出代码的原始提交者。很多QMK使用者都会对自己提交的代码在不知晓的情况下产生了改动感到困惑和沮丧，无论他的Git及Github经验丰富与否。 - -## 文档 - -对文档进行修正是最简单的参与贡献的一个办法，找到错误放置的文档或是修复不完备的部分很容易！我们也急需能修订文档的贡献者参与进来，所以如果你具备这样的能力但不清楚如何开始，请[看这里](#我怎样才能做出贡献？)！ - -文档位于 `qmk_firmware/docs` 目录下，如果你习惯于在web页面中完成工作目标，可以在 https://docs.qmk.fm/ 各文档页面下方点击“Edit this page”在线进行编辑。 - -在文档中附代码案例时, 先观察文档其他地方的命名规范。比如, 将enum类型的定义命名为 `my_layers` 或 `my_keycodes` 的形式可以保持前后一致性： - -```c -enum my_layers { - _FIRST_LAYER, - _SECOND_LAYER -}; - -enum my_keycodes { - FIRST_LAYER = SAFE_RANGE, - SECOND_LAYER -}; -``` - -### 预览文档 :id=previewing-the-documentation - -在发起pull request前，请通过文档预览来检查你的本地更改。可以在 `qmk_firmware/` 目录下执行以下命令来配置文档开发环境： - - qmk docs - -或者，如果你有安装Python 3，可以尝试： - - python3 -m http.server 8936 --directory docs - -然后在本地浏览器打开 `http://localhost:8936/`. - -## 键映射 - -大多数QMK新手都从创建一个自己的键映射 -开始。我们尽力保证键映射规范宽松 (毕竟键映射体现的是个人喜好) 不过我们仍要求须遵守以下准则，以便他人更好地发现并理解你的键映射代码。 - -* 使用这份 [模板](zh-cn/documentation_templates.md) 写一份 `readme.md`。 -* 所有的键映射PR都会被压缩处理（squashed，参见[Github文档](https://docs.github.com/cn/github/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/about-pull-request-merges)），如果你对commit被压缩很介意，请自行处理 -* 不要把新特性和键映射放在一个PR中。先提交新特性，再通过PR提交键映射 -* 键映射文件夹中不要提交 `Makefile` 文件（已不再使用） -* 更新头文件中的copyrights信息(看 `%YOUR_NAME%` 部分) - -## 键盘 - -QMK的最终归宿是键盘。有些键盘是社区维护的，有一些是制作这些键盘的人维护的。`readme.md` 会告诉你是谁维护了这个键盘，如果你对某个键盘有疑问，可以 [创建一个Issue](https://github.com/qmk/qmk_firmware/issues) 来问一问维护者。 - -我们建议你按下面的来操作: - -* 基于[模板](zh-cn/documentation_templates.md)编写 `readme.md`。 -* commit数量尽量合理，否则你的PR可能会被我们压缩。 -* 不要把新特性和新键盘定义放在一个PR中。先提交新特性，再通过PR提交新键盘定义 -* 用最近一级的父文件夹的名字命名 `.c`/`.h` 文件, 比如 `/keyboards///.[ch]` -* 键盘文件夹就不要放`Makefile`了，这个操作都过时啦 -* 更新文件头部的copyrights(看`%YOUR_NAME%`那) - -## Quantum/TMK 核心 - -在你投入大量精力到新功能开发中之前，请先确保使用了最佳的实现方案。通过阅读[了解QMK](zh-cn/understanding_qmk.md)可以获得对QMK的基本认知，这个文档将带你领略QMK的程序流程，然后你可以和维护团队探讨一下实现你想法的最佳方法的思路，以下渠道都可以： - -* [在Discord中交流](https://discord.gg/Uq7gcHh) -* [建立一个Issue](https://github.com/qmk/qmk_firmware/issues/new) - -新特性和BUG的修复影响所有键盘，开发组也在翻修QMK。所以，在实施重大改动之前一定要讨论一下。如果你在没有事先与维护团队沟通的情况下提交了一个PR，而且你的选择与维护团队的计划方向不符，那你可能要面临大改了。 - -修复BUG或者开发新特性之前看看这个： - -* **默认不启用** - QMK运行的芯片多数内存有限，首要考虑的应是已有的键映射不要被破坏，因此你的功能应当是“可以**启用**”的，而不是“可以禁用”的。如果你觉得该特性应该默认开启或者你能帮助缩减代码，请先和我们沟通一下。 -* **提交之前在本地编译** - 这个简直就是家喻户晓了，但是也确实需要编译啊！ 在你发起PR前，请确保任何改动都通过了编译验证。 -* **注意版本和芯片平台兼容性** - 有那么几个键盘有支持不同配置甚至是不同芯片的版本。请确保你开发的特性同时支持AVR和ARM两个平台，或者在不支持的平台自动禁用。 -* **解释你的新特性** - 在`docs/`写个文档, 你可以创建新文档或者写到现有文档中。如果你不把它记录下来，其他人就无法从你的努力中获益。 - -也可以看看以下建议： - -* commit数量尽量合理，否则你的PR可能会被我们压缩。 -* 不要把新键盘定义或新键映射与关键改动放在一个PR中。先提交关键改动。 -* 给你的特性编写[单元测试](zh-cn/unit_testing.md)。 -* 你编辑的文件风格要一致，如果风格不明确或者是混搭风的，请先阅读上方的[代码规范](#coding-conventions)。 - -## 重构 - -为了保持QMK脉络清晰，QMK的深度重构工作已在规划中，并会通过合作者进行相应的修改。如果你有重构的思路或建议请[创建一个issue](https://github.com/qmk/qmk_firmware/issues), 我们很乐意讨论一下QMK可以如何改进。 - -# 行为守则对于我来说有何意义？ :id=what-does-the-code-of-conduct-mean-for-me - -我们的[行为守则](https://qmk.fm/coc/) 指出您有责任尊重并礼貌地对待项目中的每个人，无论他们的身份如何。如果你是我们行为守则所描述的不当行为的受害者，我们将站在你这边，尽最大努力对施暴者进行谴责。 diff --git a/docs/zh-cn/custom_quantum_functions.md b/docs/zh-cn/custom_quantum_functions.md deleted file mode 100644 index dba9e7e7c0..0000000000 --- a/docs/zh-cn/custom_quantum_functions.md +++ /dev/null @@ -1,476 +0,0 @@ -# 如何定制化键盘功能 - - - -对于很多人来说对客制化键盘的诉求不只是向电脑输入按下的键。你肯定想实现比简单按键和宏更复杂的功能。QMK支持基于注入点的代码注入，功能重写，另外还可以自定义键盘在不同情况下的行为。 - -本页不要求任何额外的QMK知识基础，但阅读[理解QMK](zh-cn/understanding_qmk.md)将会在更基础的层面帮你理解发生了什么。 - -## 核心/键盘/键映射的概念 :id=a-word-on-core-vs-keyboards-vs-keymap - -QMK基于如下层级组成： - -* Core (`_quantum`) - * Keyboard/Revision (`_kb`) - * Keymap (`_user`) - -该文后续部分所提及的函数在定义时皆可添加 `_kb()` 或 `_user()` 后缀，我们建议在键盘及其子版本中使用 `_kb()` 后缀，而在键映射中使用 `_user()` 后缀。 - -在键盘及其子版本中定义函数时，一个重要的点是在 `_kb()` 函数执行任何逻辑前，应先调用 `_user()` 函数，否则这些键映射中的函数将没有机会被执行。 -# 自定义键码 - -到目前为止，最常见的任务是更改现有键码的行为或创建新的键码。从代码角度来看这些操作都很相似。 - -## 定义一个新键码 - -创建键码的第一步，是先定义其枚举值，也就是给键码起个名字并分配一个唯一值。QMK没有直接限制最大可用的键码值，而是提供了一个 `SAFE_RANGE` 宏。你可以在定义枚举时用 `SAFE_RANGE` 来保证你取得了唯一的键码值。 - - -这有定义两个键码的枚举值的例子。添加以下代码块至 `keymap.c` 后你就可以在布局中使用 `FOO` 和 `BAR` 了。 - -```c -enum my_keycodes { - FOO = SAFE_RANGE, - BAR -}; -``` - -## 编程设计你的键码的行为 :id=programming-the-behavior-of-any-keycode - -当你覆盖一个已存在按键的行为时，或是给新按键设计功能时，请使用 `process_record_kb()` 和 `process_record_user()` 函数。QMK会在响应并处理按键事件前调用这些函数，如果这些函数返回值为 `true`，QMK将继续用常规的方式处理键码，这样可以很方便的扩展键码的功能而不需要替换代码实现。如果函数返回`false` QMK会跳过常规的键处理逻辑，需要发送的按键按下或抬起事件则需交由你负责完成。 - -任意按键在按下或抬起时，每次都会调用这些函数。 - -### process_record_user()` 实现示例 - -这个例子做了两个事。自定义了一个叫做 `FOO` 的键码的行为，并提供了在按下回车时播放音符的功能。 - -```c -bool process_record_user(uint16_t keycode, keyrecord_t *record) { - switch (keycode) { - case FOO: - if (record->event.pressed) { - // 按下时做些什么 - } else { - // 抬起时做些什么 - } - return false; // 跳过此键的所有进一步处理 - case KC_ENTER: - // 当按下回车时播放音符 - if (record->event.pressed) { - PLAY_SONG(tone_qwerty); - } - return true; // 让QMK响应回车按下/抬起事件 - default: - return true; // 正常响应其他键码 - } -} -``` - -### `process_record_*` 实现示例 - -* 键盘/各子版本：`bool process_record_kb(uint16_t keycode, keyrecord_t *record)` -* 键映射：`bool process_record_user(uint16_t keycode, keyrecord_t *record)` - -`keycode` 参数为键映射中形如 `MO(1)`，`KC_L` 等定义的键值项。 应使用 `switch...case` 代码块来处理这些事件。 - -`record` 参数含有按键的真实状态信息： - -```c -keyrecord_t record { - keyevent_t event { - keypos_t key { - uint8_t col - uint8_t row - } - bool pressed - uint16_t time - } -} -``` - -# 键盘初始化代码 - -键盘初始化过程须经过几个步骤，而你的目的决定了你需要关注哪些函数。 - -有三个主要初始化函数，按调用顺序列出。 - -* `keyboard_pre_init_*` - 会在大多数其他功能运行前执行。适用于那些需要尽早执行的硬件初始化工作。 -* `matrix_init_*` - 在固件启动过程中被调用。此时硬件已初始化，但部分功能还不可用。 -* `keyboard_post_init_*` - 在固件启动过程的最后被调用。大多数情况下，你的“客制化”代码都可以放在这里。 - -!> 对于大多数人来说 `keyboard_post_init_user` 是你想要关注的函数。例如, 你可以在这里启动RGB背光灯。 - -## 键盘预初始化代码 - -这部分代码执行的非常早，甚至是在USB通信功能启动之前。 - -在这之后不久即会完成矩阵的初始化。 - -对于大多数用户来说不应在此处进行修改，因为它主要用于硬件初始化。 - -但如果你有硬件须初始化的话放在这里再好不过了（比如初始化LED引脚）. - -### `keyboard_pre_init_user()` 实现示例 - -本例中，在键盘层将 B0, B1, B2, B3, 和 B4 引脚设置为LED引脚。 - -```c -void keyboard_pre_init_user(void) { - // 调用键盘预初始化代码 - - // 设置LED引脚为输出模式 - setPinOutput(B0); - setPinOutput(B1); - setPinOutput(B2); - setPinOutput(B3); - setPinOutput(B4); -} -``` - -### `keyboard_pre_init_*` 函数文档 - -* 键盘/各子版本：`void keyboard_pre_init_kb(void)` -* 键映射：`void keyboard_pre_init_user(void)` - -## 矩阵初始化代码 - -在矩阵初始化后被调用。此时一部分硬件已设置完成，但一些功能尚未完成初始化。 - -此处可以用来设置一些与硬件无关，且对初始化位置没有特殊要求的功能。 - - -### `matrix_init_*` 函数文档 - -* 键盘/各子版本：`void matrix_init_kb(void)` -* 键映射：`void matrix_init_user(void)` - -### 低级矩阵函数的重写 :id=low-level-matrix-overrides - -* GPIO引脚初始化：`void matrix_init_pins(void)` - * 此处须完成低级行列引脚的初始化。默认实现中，这里会参考可选的键盘设置项 `ROW2COL`，`COL2ROW` 及 `DIRECT_PINS` 来初始化所有 `MATRIX_ROW_PINS` 及 `MATRIX_COL_PINS` 中定义的GPIO引脚的输入/输出状态。当键盘设计者重写该函数后，QMK本身不会进行任何引脚的初始化，只会听从重写的函数的实现逻辑。 -* `COL2ROW`-从行中读: `void matrix_read_cols_on_row(matrix_row_t current_matrix[], uint8_t current_row)` -* `ROW2COL`-从列中读: `void matrix_read_rows_on_col(matrix_row_t current_matrix[], uint8_t current_col)` -* `DIRECT_PINS`-直读: `void matrix_read_cols_on_row(matrix_row_t current_matrix[], uint8_t current_row)` - * 以上三个函数须参考矩阵类别，从底层矩阵的相关引脚状态中获取输入信息，并且应该只需要实现三者之一。默认情况下，在遍历 `MATRIX_ROW_PINS` and `MATRIX_COL_PINS` 时，会根据是否设置了 `ROW2COL`，`COL2ROW` 或 `DIRECT_PINS` 来配置输入输出方式。当键盘设计者重写该函数后，QMK本身不会进行任何矩阵GPIO引脚状态的变更，只会听从重写的函数的实现逻辑。 - -## 键盘后初始化代码 - -这是键盘初始化过程中的最后一个任务。此时您可以配置并调整某些特性，因为此时这些特性已初始化完毕。 - -### `keyboard_post_init_user()` 实现示例 - -本示例在所有初始化完成后运行，配置RGB背光。 - -```c -void keyboard_post_init_user(void) { - // 调用后初始化代码 - rgblight_enable_noeeprom(); // 使能Rgb，不保存设置 - rgblight_sethsv_noeeprom(180, 255, 255); // 将颜色设置到蓝绿色(青色)，不保存设置 - rgblight_mode_noeeprom(RGBLIGHT_MODE_BREATHING + 3); // 设置快速呼吸模式，不保存设置 -} -``` - -### `keyboard_post_init_*` 函数文档 - -* 键盘/各子版本：`void keyboard_post_init_kb(void)` -* 布局: `void keyboard_post_init_user(void)` - -# 矩阵扫描码 - -应尽量使用 `process_record_*()` 实现所需的键盘自定义以及事件监听，以确保这些代码不会对键盘性能产生负面的影响。然而，在极少数情况下需要在矩阵扫描中添加监听，此时需要极端留意这些函数代码的性能表现，因为这些函数每秒可能被执行十数次。 - -### `matrix_scan_*` 实现示例 - -这个例子被故意省略了。在监听处理这样一个对性能及其敏感的部分之前，您应该足够了解qmk的内部结构，才可以在没有示例的情况下编写。如果你需要帮助，请[新建一个issue](https://github.com/qmk/qmk_firmware/issues/new)或[在Discord上与我们交流](https://discord.gg/Uq7gcHh). - -### `matrix_scan_*` 函数文档 - -* 键盘/各子版本：`void matrix_scan_kb(void)` -* 布局: `void matrix_scan_user(void)` - -该函数在每次矩阵扫描时被调用，这基本与MCU处理能力上限相同。在这里写代码要谨慎，因为它会运行很多次。 - -在需要自定义矩阵扫描代码时可以使用该函数。这也可以用作自定义状态输出(比如LED灯或者屏幕)或者其他即便用户没有输入时你也想定期运行的功能。 - -# Keyboard housekeeping - -* 键盘/各子版本：`void housekeeping_task_kb(void)` -* 键映射：`void housekeeping_task_user(void)` - -该函数在所有QMK处理工作完毕后，下一轮开始执行前被执行。可以放心地假设此时QMK已对最新的矩阵扫描结果完成了所有的处理工作 -- 更新层状态，发送USB事件，更新LED状态，刷新显示屏。 - -与 `matrix_scan_*` 类似，这些函数会频繁调用直至MCU处理能力上限。为了确保键盘的响应能力，建议在这些函数中尽量做最少的事情，在你确实需要在这里实现特别的功能时，可能会影响到其它功能的表现。 - -# 键盘 空闲/唤醒 代码 - -在主控板支持情况下，暂停大部分功能可以实现“空闲”状态，例如RGB灯光和背光。既可以节省电量消耗，也可能增强键盘的表现。 - -这由两个函数控制: `suspend_power_down_*` 和 `suspend_wakeup_init_*`，分别在主控板空闲和唤醒时被调用。 - - -### suspend_power_down_user() 和 suspend_wakeup_init_user() 的实现示例 - - -```c -void suspend_power_down_user(void) { - // 当键盘挂起时会被多次调用的代码 -} - -void suspend_wakeup_init_user(void) { - // 键盘唤醒时被调用的代码 -} -``` - -### 键盘 挂起/唤醒 函数文档 - -* 键盘/各子版本：`void suspend_power_down_kb(void)` 和 `void suspend_wakeup_init_user(void)` -* 键映射：`void suspend_power_down_kb(void)` 和 `void suspend_wakeup_init_user(void)` - -# 层切换代码 :id=layer-change-code - -每当层发生切换时被执行，可用于感知层切换事件，或自定义层处理逻辑。 - -### `layer_state_set_*` 实现示例 - -本例中，通过Planck键盘示范了如何将[RGB背光灯](zh-cn/feature_rgblight.md)设置为与层同步。 - -```c -layer_state_t layer_state_set_user(layer_state_t state) { - switch (get_highest_layer(state)) { - case _RAISE: - rgblight_setrgb (0x00, 0x00, 0xFF); - break; - case _LOWER: - rgblight_setrgb (0xFF, 0x00, 0x00); - break; - case _PLOVER: - rgblight_setrgb (0x00, 0xFF, 0x00); - break; - case _ADJUST: - rgblight_setrgb (0x7A, 0x00, 0xFF); - break; - default: // 默认层及其它层 - rgblight_setrgb (0x00, 0xFF, 0xFF); - break; - } - return state; -} -``` - -可以通过 `IS_LAYER_ON_STATE(state, layer)` 和 `IS_LAYER_OFF_STATE(state, layer)` 宏来确认常规层的状态。 - -如果不在 `layer_state_set_*` 函数中，可以通过 `IS_LAYER_ON(layer)` 和 `IS_LAYER_OFF(layer)` 宏来确认全局的层状态。 - -### `layer_state_set_*` 函数文档 - -* 键盘/各子版本：`layer_state_t layer_state_set_kb(layer_state_t state)` -* 布局: `layer_state_t layer_state_set_user(layer_state_t state)` - - -此处的 `state` 为当前活跃层的位掩码, 详见[键映射概述](zh-cn/keymap.md#keymap-layer-status) - - -# 配置的持久存储（EEPROM） - -该功能可以让键盘的配置持久存储下来。这些配置存储在控制器的EEPROM中，即便掉电后依旧可以留存下来。可以通过 `eeconfig_read_kb` 和 `eeconfig_read_user` 来读取，通过 `eeconfig_update_kb` and `eeconfig_update_user` 来进行保存。该功能常用于保存一些开关状态（比如rgb层指示灯）。此外，可以通过 `eeconfig_init_kb` 和 `eeconfig_init_user` 来设置EEPROM的默认配置值。 - -复杂的地方是，有很多方法可以存储和访问EEPROM数据，并且没有哪种方法是“正确”的。但是，每个功能只有一个双字(四字节)空间可用。 - -记住EEPROM是有写入寿命的。尽管写入寿命很高，但是并不是只有这些配置信息会写到EEPROM中。如果你写入过于频繁，你的MCU寿命将会急速减少。 - -* 如果您不理解这个例子，那么您可以不使用这个特性，因为它相当复杂。 - -### 实现示例 - -本例讲解了如何添加并读写设置项。本例使用用户键映射来实现。这是一个复杂的函数，有很多事情要做。实际上，它使用了很多前述的函数来工作！ -（译注：该示例由于英文行文，可能会觉得看得稀里糊涂。实现的功能很简单，即开启了层指示功能（RGB_LYR）时，rgb背光灯会展示当前层的特定颜色用以指示层状态，而触发任何改变rgb背光颜色的键码时，rgb背光灯将回归普通的背光灯角色，不再作为层指示器） - -在你的keymap.c文件中，将以下代码添加至顶部: -```c -typedef union { - uint32_t raw; - struct { - bool rgb_layer_change :1; - }; -} user_config_t; - -user_config_t user_config; -``` - -以上代码建立了一个32位的结构体，用于在内存及EEPROM中存储配置项。此时不再需要再单独声明变量，因为都已经在该结构体中定义了。须记住 `bool`（布尔）值占用1位，`uint8_t` 占用8位，`uint16_t` 占用16位。你可以混合搭配使用，但改变这些顺序会因为错误的读写而招致问题。 - -我们在 `layer_state_set_*` 函数中会使用 `rgb_layer_change`。通过 `keyboard_post_init_user` 和 `process_record_user` 来配置所需的一切。 - -在编写 `keyboard_post_init_user` 时，你需要使用 `eeconfig_read_user()` 来计算并填充你刚刚创建的结构体。然后即可以使用结构体数据来控制键映射中的功能。就像这样： -```c -void keyboard_post_init_user(void) { - // 调用键映射级别的矩阵初始化 - - // 从EEPROM读用户配置 - user_config.raw = eeconfig_read_user(); - - // 如使能，设置默认层 - if (user_config.rgb_layer_change) { - rgblight_enable_noeeprom(); - rgblight_sethsv_noeeprom_cyan(); - rgblight_mode_noeeprom(1); - } -} -``` -以上函数会在读EEPROM配置后立即设置默认层的RGB颜色。"raw"值将被转换为上述创建的实际使用的"union"结构体。 - -```c -layer_state_t layer_state_set_user(layer_state_t state) { - switch (get_highest_layer(state)) { - case _RAISE: - if (user_config.rgb_layer_change) { rgblight_sethsv_noeeprom_magenta(); rgblight_mode_noeeprom(1); } - break; - case _LOWER: - if (user_config.rgb_layer_change) { rgblight_sethsv_noeeprom_red(); rgblight_mode_noeeprom(1); } - break; - case _PLOVER: - if (user_config.rgb_layer_change) { rgblight_sethsv_noeeprom_green(); rgblight_mode_noeeprom(1); } - break; - case _ADJUST: - if (user_config.rgb_layer_change) { rgblight_sethsv_noeeprom_white(); rgblight_mode_noeeprom(1); } - break; - default: // 针对其他层或默认层 - if (user_config.rgb_layer_change) { rgblight_sethsv_noeeprom_cyan(); rgblight_mode_noeeprom(1); } - break; - } - return state; -} -``` -这样仅在相关值使能时才会改变RGB背光灯。若要配置该值, 为 `process_record_user` 创建一个新键码 `RGB_LYR`。此时我们想实现的是，如果触发了常规的RGB码，以上示例中的逻辑都将不生效，形如： -```c - -bool process_record_user(uint16_t keycode, keyrecord_t *record) { - switch (keycode) { - case FOO: - if (record->event.pressed) { - // 按下时做点什么 - } else { - // 抬起时做点什么 - } - return false; // 跳过此键的进一步处理 - case KC_ENTER: - // 在按下回车时播放音符 - if (record->event.pressed) { - PLAY_SONG(tone_qwerty); - } - return true; // 让QMK产生回车按下/抬起事件 - case RGB_LYR: // 这允许我们将背光灯作为层指示，或正常用途 - if (record->event.pressed) { - user_config.rgb_layer_change ^= 1; // 切换状态 - eeconfig_update_user(user_config.raw); // 向EEPROM写入新状态 - if (user_config.rgb_layer_change) { // 如果层指示功能被使能 - layer_state_set(layer_state); // 那么立刻更新层颜色 - } - } - return false; - case RGB_MODE_FORWARD ... RGB_MODE_GRADIENT: // 对于所有的RGB代码 (参考 quantum_keycodes.h, 400 行处) - if (record->event.pressed) { // 本句失能层指示功能，假设你现在要调整该功能…你要把它禁用 - if (user_config.rgb_layer_change) { // 仅当使能时 - user_config.rgb_layer_change = false; // 失能，然后 - eeconfig_update_user(user_config.raw); // 向EEPROM写入设置 - } - } - return true; break; - default: - return true; // 其他键码正常处理 - } -} -``` -最后，须添加 `eeconfig_init_user` 函数，从而当EEPROM重置时，可以指定默认值, 甚至自定义操作。若想强制重置EEPROM，请用 `EEP_RST` 键码或[Bootmagic](zh-cn/feature_bootmagic.md) 功能。比如，在你想重置RGB层指示配置，并保存默认值时。 - -```c -void eeconfig_init_user(void) { // EEPROM被重置 - user_config.raw = 0; - user_config.rgb_layer_change = true; // 我们想要默认使能 - eeconfig_update_user(user_config.raw); // 向EEPROM写入默认值 - - // 通过使用非'noeeprom'版本的函数，可以同时写入这些配置到EEPROM中。 - rgblight_enable(); // 默认使能RGB - rgblight_sethsv_cyan(); // 默认设置青色 - rgblight_mode(1); // 默认设置长亮 -} -``` - -一切已就绪，RGB层指示将在需要时生效。这个设置会持久存储，即便是拔下键盘。如果你使用其他RGB码，层指示将失效，从而可以停留在期望的模式及颜色下。 - -### 'EECONFIG' 函数文档 - -* 键盘/各子版本：`void eeconfig_init_kb(void)`, `uint32_t eeconfig_read_kb(void)` 和 `void eeconfig_update_kb(uint32_t val)` -* 键映射：`void eeconfig_init_user(void)`, `uint32_t eeconfig_read_user(void)` 和 `void eeconfig_update_user(uint32_t val)` - -`val` 是你想写入EEPROM的值，`eeconfig_read_*`函数会从EEPROM返回一个32位(双字)的值。 - -### 定时执行 :id=deferred-execution - -QMK支持在特定时间间隔后执行回调，以代替手动的计时器管理。 - -#### 定时回调函数 - -所有的 _定时回调函数_ 使用同样的函数签名，如下： - -```c -uint32_t my_callback(uint32_t trigger_time, void *cb_arg) { - /* 处理了一些工作 */ - bool repeat = my_deferred_functionality(); - return repeat ? 500 : 0; -} -``` - -第一个参数 `trigger_time` 为预期的执行时间，如果因为其它事情造成了延迟未能在准确的时间点执行，可以利用这个参数“追赶”或者跳过这次间隔，取决于你的目的是什么。 - -第二个参数 `cb_arg` 为下述的 `defer_exec()` 传入的参数，由此可以获取调用时的状态信息。 - -返回值为该函数下一次期望被回调的时间间隔毫秒数 -- 若返回 `0` 则会自动被注销掉。上例中，通过执行假想的 `my_deferred_functionality()` 函数来决策回调是否继续下去 -- 若是，则给出一个 `500` 毫秒的延迟计划，否则，返回 `0` 来告知定时处理后台任务该计划已执行完毕。 - -?> 须留意返回的延时时间是相对原定的触发时间点的，而不是回调执行完的时间点。这样可以防止偶发的执行延迟影响稳定的定时事件计划。 - -#### 注册定时回调 - -在定义好回调后，通过如下API进行定时回调注册： - -```c -deferred_token my_token = defer_exec(1500, my_callback, NULL); -``` - -第一个参数为执行 `my_callback` 的毫秒时间延迟 -- 上例中为 `1500` 毫秒，即 1.5 秒。 - -第三个参数为回调执行时传入的 `cb_arg` 参数。须确保该值在回调时依旧有效 -- 局部函数内的变量会在回调执行前就被释放掉因此不能用。如果并不需要这个参数，可以传入 `NULL`。 - -返回值 `deferred_token` 可被用于在回调执行前取消该定时计划。如果该函数调用失败，会返回 `INVALID_DEFERRED_TOKEN`，一般错误原因是延时值被设置为 `0` 或回调函数参数为 `NULL`，还有一种可能是已有过量的回调在等待被处理 -- 可以按照下述方法修改这个阈值。 - -#### 延长定时回调时间 - -由 `defer_exec()` 返回的 `deferred_token` 可以用来修改回调执行所需等待的时延值： -```c -// 重新调整 my_token 后续的执行计划为当前时间起800ms后 -extend_deferred_exec(my_token, 800); -``` - -#### 取消定时回调 - -由 `defer_exec()` 返回的 `deferred_token` 可以用来取消掉后续的执行计划： -```c -// 取消 my_token 的后续回调 -cancel_deferred_exec(my_token); -``` - -一旦 token 被取消了，即视为不再可用。重新使用该 token 是不支持的。 - -#### 定时回调的限制 - -可安排的定时回调计划数量是有限的，由 `MAX_DEFERRED_EXECUTORS` 定义的值确定。 - -如果定时回调注册失败了，可以在对应的键盘或键映射下的 `config.h` 文件中修改该值，比如将默认的 8 改为 16： - -```c -#define MAX_DEFERRED_EXECUTORS 16 -``` diff --git a/docs/zh-cn/driver_installation_zadig.md b/docs/zh-cn/driver_installation_zadig.md deleted file mode 100644 index db9bb9a3fd..0000000000 --- a/docs/zh-cn/driver_installation_zadig.md +++ /dev/null @@ -1,102 +0,0 @@ -# 利用Zadig安装Bootloader驱动 - - - -QMK在主机侧会展现为一台HID键盘设备，因此不需要额外的驱动。但若要在Windows下刷写键盘固件，重置主控板时出现的bootloader设备则通常需要一些驱动程序。 - -已知的特例有两个：常见于Pro Micro的Caterina bootloader，以及PJRC Teensys上的HalfKay bootloader, 会同时提供一个串行端口设备及一个HID设备，因此不需要额外的驱动。 - -这里我们推荐使用[Zadig](https://zadig.akeo.ie/)工具软件。若你在MSYS2中配置了开发环境，`qmk_install.sh` 脚本已经替你安装了相关驱动。 - -## 安装 - -将键盘重置为bootloader模式，点击 `RESET` 键码（可能在别的层中），或按一下通常在主控板背面上的重置开关，如果你的键盘上没有前两者，尝试在按住Esc键或空格+`B`键时插上键盘（更多信息参见[Bootmagic](zh-cn/feature_bootmagic.md)）。有些键盘使用[指令](zh-cn/feature_command.md)功能来代替Bootmagic，这种情况下，可以在键盘插入状态下点击 左Shift+右Shift+`B` 或 左Shift+右Shift+Esc组合键来进入bootloader模式。 -也有一些键盘需要特别的操作才能进入bootloader状态。例如，[Bootmagic](zh-cn/feature_bootmagic.md)键（默认为：Esc键）在其它键上，比如左Control；或是指令组合键（默认为：左Shift+右Shift）为其它组合，如左Control+右Control。当不确定的时候，可以查阅一下主控板的README文件。 - -若要将USBaspLoader设备置为bootloader模式，请在按住 `BOOT` 按钮时点击 `RESET` 按钮，或是在按住 `BOOT` 按钮时插入USB线缆。 - -Zadig可以自动检测到bootloader设备，但有时你需要在 **Options（选项） → List All Devices（列出所有设备）** 的下拉列表中选择正确的设备。 - -!> 如果Zadig中列出的一个或多个设备为 `HidUsb` 驱动的，那么你的键盘应该没有进入bootloader模式，此时箭头会标记成橙色并会询问你确认是否要修改系统驱动，此时**不要**允许该操作。 - -如果箭头呈现绿色，选择所需的驱动，点击**Install Driver（安装驱动）**。如何选择正确的驱动进行安装请参见[已知驱动列表](#list-of-known-bootloaders)。 - -![在Zadig中安装了正确的bootloader驱动](https://i.imgur.com/b8VgXzx.png) - -最后，重新拔插一次键盘，确认驱动可以正常加载。如果你在使用QMK工具箱进行刷写，记得也重启一下，因为有时它不会检测到驱动的变化。 - -## 从错误的驱动安装中恢复 - -如果你发现键盘无法输入了，应当是因为错误地替换了键盘本身的驱动，而不是bootloader的驱动，你的键盘没有进入bootloader模式就进行安装时就会遇到这个问题。在Zadig中很容易看出这个问题 - 正常的键盘在其所有的接口上都应该有 `HidUsb` 驱动： - -![在Zadig中的一个正常的键盘](https://i.imgur.com/Hx0E5kC.png) - -打开Device Manager（设备管理器），选择**View（查看） → Devices by container（依类型排序设备）**，并定位到你键盘名所在的节点。 - -![在设备管理器中安装了错误的驱动的主控板](https://i.imgur.com/o7WLvBl.png) - -在这些节点上右键，选择**Uninstall device（卸载）**。如果出现了**Delete the driver software for this device（同时卸载该设备驱动文件）**也请勾选上。 - -![设备卸载确认对话框，选中了“删除驱动文件”](https://i.imgur.com/aEs2RuA.png) - -点击 **Action（操作） → Scan for hardware changes（扫描检测硬件改动）**。此时，键盘应该恢复可用状态了。再确认一下Zadig中键盘是否在使用 `HidUsb` 驱动，如果是，键盘即完全恢复可用状态了，如果不是，重复这一步直到Zadig中报告了正确的驱动。 - -?> 在这一步有时需要重启电脑，以便Windows可以选用新驱动文件。 - -## 卸载 - -卸载bootloadeer设备要比安装过程复杂一些。 - -打开设备管理器，选择**查看 → 依类型排序设备**，并找到bootloader设备，寻找USB VID和PID与Zadig的[该表格](#list-of-known-bootloaders)中一致的项。 - -在设备属性的详细信息tab中，找到 `Inf name（INF名称）` 值，通常该值类似于 `oemXX.inf`： - -![设备属性中的INF名称值](https://i.imgur.com/Bu4mk9m.png) - -之后使用管理员权限打开一个命令行窗口（在开始菜单处输出 `cmd` 并点击Ctrl+Shift+回车）。执行 `pnputil /enum-drivers` 并找到 `INF名称` 与 `Published Name（发布名称）` 一致的项： - -![对pnputil输出中匹配驱动项进行高亮展示](https://i.imgur.com/3RrSjzW.png) - -执行 `pnputil /delete-driver oemXX.inf /uninstall`，之后该驱动会被删除，相关设备也不再使用该驱动，但设备是不会被移除的。 - -与上一节相似，本流程也可能需要执行多次，因为一个设备可能会有多个可用的驱动。 - -!> **警告：** 操作过程中*务必非常小心*！以免不小心卸载掉其它关键驱动。如果你对操作不是很确定，多次检查 `/enum-drivers`的输出信息，也可以考虑执行 `/delete-driver` 时不添加 `/uninstall` 开关\。 - -## 已知驱动列表 :id=list-of-known-bootloaders - -该表列出了已知的bootloader设备及其USB VID（厂商ID）和PID（产品ID），以及可用于QMK刷写固件的驱动。留意usbser及HidUsb驱动是随Windows附带的，无法通过Zadig安装 - 如果你的设备驱动不符，请参照上节来卸载这些驱动。 - -此处列出的设备名应与Zadig中的一致，但不一定与设备管理器及QMK工具箱展示的一致。 - -|Bootloader |设备名 |VID/PID |驱动 | -|--------------|------------------------------|--------------|-------| -|`atmel-dfu` |ATmega16u2 DFU |`03EB:2FEF` |libusb0| -|`atmel-dfu` |ATmega32U2 DFU |`03EB:2FF0` |libusb0| -|`atmel-dfu` |ATm16U4 DFU V1.0.2 |`03EB:2FF3` |libusb0| -|`atmel-dfu` |ATm32U4DFU |`03EB:2FF4` |libusb0| -|`atmel-dfu` |*none* (AT90USB64) |`03EB:2FF9` |libusb0| -|`atmel-dfu` |AT90USB128 DFU |`03EB:2FFB` |libusb0| -|`qmk-dfu` |(键盘名) Bootloader |同`atmel-dfu` |libusb0| -|`halfkay` |*none* |`16C0:0478` |HidUsb | -|`caterina` |Pro Micro 3.3V |`1B4F:9203` |usbser | -|`caterina` |Pro Micro 5V |`1B4F:9205` |usbser | -|`caterina` |LilyPadUSB |`1B4F:9207` |usbser | -|`caterina` |Pololu A-Star 32U4 Bootloader |`1FFB:0101` |usbser | -|`caterina` |Arduino Leonardo |`2341:0036` |usbser | -|`caterina` |Arduino Micro |`2341:0037` |usbser | -|`caterina` |Adafruit Feather 32u4 |`239A:000C` |usbser | -|`caterina` |Adafruit ItsyBitsy 32u4 3V |`239A:000D` |usbser | -|`caterina` |Adafruit ItsyBitsy 32u4 5V |`239A:000E` |usbser | -|`caterina` |Arduino Leonardo |`2A03:0036` |usbser | -|`caterina` |Arduino Micro |`2A03:0037` |usbser | -|`bootloadhid` |HIDBoot |`16C0:05DF` |HidUsb | -|`usbasploader`|USBasp |`16C0:05DC` |libusbK| -|`apm32-dfu` |APM32 DFU ISP Mode |`314B:0106` |WinUSB | -|`stm32-dfu` |STM32 BOOTLOADER |`0483:DF11` |WinUSB | -|`kiibohd` |Kiibohd DFU Bootloader |`1C11:B007` |WinUSB | -|`stm32duino` |Maple 003 |`1EAF:0003` |WinUSB | -|`qmk-hid` |(键盘名) Bootloader |`03EB:2067` |HidUsb | diff --git a/docs/zh-cn/easy_maker.md b/docs/zh-cn/easy_maker.md deleted file mode 100644 index 420c77d3af..0000000000 --- a/docs/zh-cn/easy_maker.md +++ /dev/null @@ -1,37 +0,0 @@ -# 极简式制作 - 通过配置器进行一次性的工程构建 - - - -你是否需要一种极简的控制器编程方案，类似Proton C或Teensy 2.0，以进行一次性的工程构建？QMK提供了极简制作器，通过QMK配置器可以在几分钟内制作一个固件。 - -有几种极简制作器，取决于你需要什么样的： - -* [引脚直连](https://config.qmk.fm/#/?filter=ez_maker/direct) - 将每个开关独立直连到一个引脚 -* 引脚直连 + 背光 (即将可用) - 类似引脚直连，单独加一个引脚连接到[背光](zh-cn/feature_backlight.md)控制器上 -* 引脚直连 + 小键盘锁 (即将可用) - 类似引脚直连，单独加一个引脚连接到Numlock LED上 -* 引脚直连 + 大写锁 (即将可用) - 类似引脚直连， 单独加一个引脚连接到Capslock LED上 -* 引脚直连 + 编码器 (即将可用) - 类似引脚直连， 再加两个引脚用于连接一个旋钮编码器 - -## 快速指引 - -最简单的情况是使用一个引脚直连的主控板，将每个引脚连接到一个开关，另一端再接地即可，从以下键盘列表中可以选择一款支持的MCU： - -* - -更多信息请参见[引脚直连](#direct-pin)一节。 - -# 引脚直连 :id=direct-pin - -与其名字表意相同，它的原理是一个引脚连接一个开关，每个开关的另一端接地（VSS或GND），不需要额外的部件，通常MCU内部自带上拉电阻，因此可以感知开关动作。 - - -这里有一个示意图，展示了如何将一个按钮连接到ProMicro的A3引脚上： - -![该示意图中的ProMicro的A3引脚导出一根线，连接到了开关的左边，另一根线从开关右边引出并接地。](https://i.imgur.com/JcDhZll.png) - -在开关连接到各自的引脚后，在键盘下拉列表中选择所使用的MCU，将键码指定到对应的引脚上即可构建出固件。以下链接仅展示支持引脚直连的极简式制作： - -* diff --git a/docs/zh-cn/faq_build.md b/docs/zh-cn/faq_build.md deleted file mode 100644 index 84cd3c6a4e..0000000000 --- a/docs/zh-cn/faq_build.md +++ /dev/null @@ -1,73 +0,0 @@ -# 常被问及的编译问题 - - - -本页涉及所有编译QMK的问题，如果你还没有试过，请先阅读[编译环境配置](zh-cn/getting_started_build_tools.md)及[Make指引](zh-cn/getting_started_make_guide.md)。 - -## 无法在Linux下编程 -操作设备需要足够的权限，对于Linux用户，请参阅下方有关 `udev` 的规则说明。如果你对 `udev` 有困惑，可以先试试 `sudo` 命令，如果你对这个命令不熟悉，可以通过 `man sudo` 或 [这个web页面](https://linux.die.net/man/8/sudo)进行了解。 - -一个使用 `sudo` 的示例，这里假设你的控制器是ATMega32u4: - - $ sudo dfu-programmer atmega32u4 erase --force - $ sudo dfu-programmer atmega32u4 flash your.hex - $ sudo dfu-programmer atmega32u4 reset - -或者只是: - - $ sudo make ::flash - -但请留意，用 `sudo` 来执行 `make` 通常***不是***一个好主意，请尽量考虑使用上面的办法。 - -### Linux `udev` 规则 :id=linux-udev-rules - -在linux下，需要足够的权限才能读写bootloader设备，可以使用 `sudo` 来刷写固件（不推荐），也可以将[这个文件](https://github.com/qmk/qmk_firmware/tree/master/util/udev/50-qmk.rules) 放到 `/etc/udev/rules.d/` 目录下。 - -放好后，执行： - -``` -sudo udevadm control --reload-rules -sudo udevadm trigger -``` - -**注意：**在旧版ModeManager（<1.12）中，过滤功能仅在严格模式（strict mode）下可用，可以调整一下配置： - -``` -printf '[Service]\nExecStart=\nExecStart=/usr/sbin/ModemManager --filter-policy=default' | sudo tee /etc/systemd/system/ModemManager.service.d/policy.conf -sudo systemctl daemon-reload -sudo systemctl restart ModemManager -``` - -### 在Linux下无法检测到bootloader模式下的串口设备 -确认一下你的内核版本是否已配置为支持该设备。如果你的设备使用USB ACM，如Pro Micro（Atmega32u4），确认内核 配置中包含 `CONFIG_USB_ACM=y`，其它类型的设备可能需要 `USB_SERIAL` 及相关子配置的支持。 - -## DFU Bootloader显示为未知设备 - -在Windows下刷写键盘固件时很常见的一个问题。主要原因是安装了错误的驱动，或者压根没有装驱动。 - -要修复这个问题，可以尝试重新执行QMK安装脚本(位于MSYS2或WSL中的 `qmk_firmware` 目录下的 `./util/qmk_install.sh`)或重新安装QMK工具箱。此外，也可以尝试下载安装[QMK驱动安装包 `qmk_driver_installer`](https://github.com/qmk/qmk_driver_installer)来修复。 - -如果问题依旧，可能是需要下载安装Zadig，具体请参考[通过Zadig安装bootloader驱动](zh-cn/driver_installation_zadig.md)。 - -## USB VID 和 PID -通过编辑 `config.h` 你可以自由指定ID，随便选一个看起来不常用的ID一般不会有什么问题，冲突的概率很低。 - -大部分QMK设备都选用 `0xFEED` 作为VID，选取PID前请先看一下其它键盘的情况再决定。 - -同时请阅读这个issue： -https://github.com/tmk/tmk_keyboard/issues/150 - -你可以在以下地址购买唯一的VID:PID，但我觉得个人使用情况下没有必要。 -- https://www.obdev.at/products/vusb/license.html -- https://www.mcselec.com/index.php?page=shop.product_details&flypage=shop.flypage&product_id=92&option=com_phpshop&Itemid=1 - -### 在我刷写完键盘后就没响应了/点了没动静了 -- 设备是arm的（rev6 planck, clueboard 60, hs60v2等）(2019年2月) -因为ARM平台下EEPROM特殊的工作模式，已保存的配置可能会失效。主要影响的是默认层，有概率在特定情况下会导致键盘不可用，我们还没有搞明白原因。这个问题可以在重置EEPROM后恢复。 - -[Planck rev6 上重置 EEPROM](https://cdn.discordapp.com/attachments/473506116718952450/539284620861243409/planck_rev6_default.bin) 可以用于强制重置EEPROM。刷入这个文件后，再次刷入正常固件，会将键盘恢复到_正常_工作状态。 -[Preonic rev3 上重置 EEPROM](https://cdn.discordapp.com/attachments/473506116718952450/537849497313738762/preonic_rev3_default.bin) - -也可以考虑使用bootmagic，只要它可以用。（参见[Bootmagic文档](zh-cn/feature_bootmagic.md)并结合键盘情况来了解如何操作） diff --git a/docs/zh-cn/faq_debug.md b/docs/zh-cn/faq_debug.md deleted file mode 100644 index 63d688ed9e..0000000000 --- a/docs/zh-cn/faq_debug.md +++ /dev/null @@ -1,136 +0,0 @@ -# 调试 FAQ - - - -此页面详细介绍了人们对键盘故障排除的各种常见问题。 - -## 调试 :id=debugging - -如果你在 `rules.mk` 中配置了 `CONSOLE_ENABLE = yes`，你的键盘将会输出调试信息。默认情况下输出很有限，可以启用调试模式来增加调试输出的丰富度。使用你的键映射方案中的 `DEBUG` 键码，或使用[指令](zh-cn/feature_command.md)功能来启动调试模式，或者将下面这段代码放到你的键映射中： - -```c -void keyboard_post_init_user(void) { - // 通过调整这些值可以改变其表现 - debug_enable=true; - debug_matrix=true; - //debug_keyboard=true; - //debug_mouse=true; -} -``` - -## 调试工具 - -有多种可用于调试的工具。 - -### 使用QMK工具箱调试 - -在兼容的平台上，[QMK工具箱](https://github.com/qmk/qmk_toolbox)可以展示你的键盘的调试输出。 - -### 使用 QMK CLI 进行调试 - -倾向于在终端进行调试？使用 [QMK CLI 命令行](zh-cn/cli_commands.md#qmk-console)可以展示键盘输出的调试信息。 - -### 使用hid_listen调试 - -更喜欢使用终端的方案？PJRC提供的[hid_listen](https://www.pjrc.com/teensy/hid_listen.html)也可以用来展示调试信息，已有Windows、Linux及MacOS下预编译好的可执行文件。 - -## 发送自定义调试信息 :id=debug-api - -有时在[自定义代码](zh-cn/custom_quantum_functions.md)中输出调试信息非常有用，要做到这个功能也很简单，在代码文件头部包含 `print.h` 文件： - -```c -#include "print.h" -``` - -然后可以使用以下输出函数： - -* `print("string")`: 字符串输出 -* `uprintf("%s string", var)`: 格式化字符串输出 -* `dprint("string")` 仅调试模式下，字符串输出 -* `dprintf("%s string", var)`: 仅调试模式下，格式化字符串输出 - -## 调试示例 - -以下列出了一些实际出现过的调试范例，更多资料参见[调试/定位QMK问题](zh-cn/faq_debug.md)。 - -### 当前按下的键的矩阵坐标是什么？ - -在移植或尝试诊断PCB问题时，确认按下的键被正确扫描到是很有用的排查步骤。要启用该场景的日志输出，请在 `keymap.c` 中添加： - -```c -bool process_record_user(uint16_t keycode, keyrecord_t *record) { - // If console is enabled, it will print the matrix position and status of each key pressed -#ifdef CONSOLE_ENABLE - uprintf("KL: kc: 0x%04X, col: %u, row: %u, pressed: %b, time: %u, interrupt: %b, count: %u\n", keycode, record->event.key.col, record->event.key.row, record->event.pressed, record->event.time, record->tap.interrupted, record->tap.count); -#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 -``` - -## `hid_listen` 无法识别到设备 - -如果设备没有就绪，在命令行下调试会看到如下输出： - -``` -Waiting for device:......... -``` - -当设备插入后，*hid_listen*可以发现设备，会有如下输出： - -``` -Waiting for new device:......................... -Listening: -``` - -若无法出现'Listening:'消息，尝试在[Makefile]中添加 `CONSOLE_ENABLE=yes` - -在类Linux系统下，访问设备可能需要一定权限，尝试使用 `sudo hid_listen`。 - -此外，很多Linux发行版可以通过创建如下内容的文件 `/etc/udev/rules.d/70-hid-listen.rules` 来避免通过root权限执行hid_listen： - -``` -SUBSYSTEM=="hidraw", ATTRS{idVendor}=="abcd", ATTRS{idProduct}=="def1", TAG+="uaccess", RUN{builtin}+="uaccess" -``` - -使用设备的真实VID和PID替换上面的abcd和def1，留意必须全小写。其中 `RUN{builtin}+="uaccess"` 仅在较老的发行版中需要使用。 - -## 命令行无法成功输出消息 -请检查: -- *hid_listen*确实找到了设备，如前文所述。 -- 通过**Magic**+d命令启用调试模式，参见[Magic Commands](https://github.com/tmk/tmk_keyboard#magic-commands). -- 配置`debug_enable=true`. 参见[调试](#debugging) -- 尝试用 `print` 替代 `dprint`， 参见**common/print.h**. -- 拔出其它可能影响命令行的设备，参见[Issue #97](https://github.com/tmk/tmk_keyboard/issues/97). diff --git a/docs/zh-cn/faq_general.md b/docs/zh-cn/faq_general.md deleted file mode 100644 index cc8ef3d19a..0000000000 --- a/docs/zh-cn/faq_general.md +++ /dev/null @@ -1,58 +0,0 @@ -# 常见问题（FAQ） - - - -## QMK是什么? - -[QMK](https://github.com/qmk), 是量子机械键盘（Quantum Mechanical Keyboard）的缩写, 是制作自定义键盘工具的人组成的组织。 一切始于[QMK固件](https://github.com/qmk/qmk_firmware)项目, 可以认为是[TMK](https://github.com/tmk/tmk_keyboard)的改进版本. - -## 不知道从哪开始搞！ - -这样的话建议从[新手指引](zh-cn/newbs.md)开始。那里有你需要的高质量的入门信息。 - -如果还是搞不懂的话，直接跳到[QMK配置器](https://config.qmk.fm)吧，你核心需要的东西都在那里。 - -## 我的固件如何刷写到硬件上？ - -先参考[编译/刷写固件FAQ](zh-cn/faq_build.md)，里面有充足的资料，常见的问题也给出了足够多的解决办法。 - -## 我的问题这里找不到相关信息怎么办？ - -没有关系，请到[GitHub上发issue](https://github.com/qmk/qmk_firmware/issues)看看是否有人遇到了相同的问题（留意一定是相同的问题，而不是相似的）。 - -如果还是找不到解决办法，请[新建issue](https://github.com/qmk/qmk_firmware/issues/new)！ - -## 我好像找到了bug？ - -那么新建一个[issue](https://github.com/qmk/qmk_firmware/issues/new)吧，如果你还知道怎么修，带着修复方案发个Pull Request吧。 - -## 但是 `git` 和 `GitHub` 我实在是玩不转！ - -别担心，这里有很好的[入门指引](zh-cn/newbs_git_best_practices.md)可以教你怎么轻松快乐地使用 `git` 和GitHub进行开发。 - -更多的 `git` 和GitHub知识，参考[这里](zh-cn/newbs_learn_more_resources.md)。 - -## 我可以添加一个支持的键盘 - -太棒啦！请发Pull Request吧，在代码审阅后，我们会合并进去！ - -### 我可以打上 `QMK` 的标吗? - -很好啊！我们甚至乐意帮你这么做！ - -我们有[一整页](https://qmk.fm/powered/)的资料旨在帮你在页面和键盘上打上QMK的标，里面有QMK官方提供的所有支援（信息及图片）。 - -如果你有任何疑问，可以发issue或通过[Discord](https://discord.gg/Uq7gcHh)联系我们。 - -## QMK和TMK区别是什么？ - -TMK原先是由[Jun Wako](https://github.com/tmk)设计实现的，QMK来源于[Jack Humbert](https://github.com/jackhumbert)的Planck的TMK fork。一段时间后，Jack的这个fork与TMK渐行渐远，到2015年时，Jack决定将这份fork重命名为QMK。 - -技术上讲QMK等同于基于TMK增加了一些新功能，最显著的是在扩充了可用键码后，实现了很多诸如 `S()`, `LCTL()` 及 `MO()` 这样的高级功能，所有这些键码可以参见[键码](zh-cn/keycodes.md)页。 - -从工程项目及社区维护角度来看，TMK维护了一份官方支持的键盘及很少量的社区贡献，社区中各自维护着各自的fork，且因为默认键映射很少，TMK的使用者基本不会共享键映射。QMK通过统一的集约式仓库（repo）管理来鼓励分享键盘及键映射，任何符合质量基线的pull request都会被采纳，因此绝大部分贡献都来源于社区，QMK小组会在必要时提供支援。 - -两种模式各有利弊，并且TMK和QMK之间也会有合乎理法的代码交流。 diff --git a/docs/zh-cn/faq_keymap.md b/docs/zh-cn/faq_keymap.md deleted file mode 100644 index 0e1e5a20e8..0000000000 --- a/docs/zh-cn/faq_keymap.md +++ /dev/null @@ -1,157 +0,0 @@ -# 键映射FAQ - - - -本页包含人们经常遇到的关于键映射的问题，如果你还没阅读过[键映射概览](zh-cn/keymap.md)，请先阅读一下。 - -## 我能使用的键码有哪些? -所有可用键码收录在[键码](zh-cn/keycodes.md)页，在有更详尽的文档时，我们会更新这个链接。 - -所有键码实际定义在[quantum/keycode.h](https://github.com/qmk/qmk_firmware/blob/master/quantum/keycode.h). - -## 默认键码是什么? - -广为使用的键盘配列有三种——ANSI，ISO及JIS。北美主要使用ANSI，欧洲及非洲主要使用ISO，日本主要使用JIS，其它区域多为ANSI或ISO。这三种配列的键码可查阅： - - -![键盘配列示意图](https://i.imgur.com/5wsh5wM.png) - -## 如何对复杂的键码指定自定义的名称？ - -使用更容易理解的自定义的名字去指代一些键码有时很实用，通常我们使用 `#define` 来实现： - -```c -#define FN_CAPS LT(_FL, KC_CAPSLOCK) -#define ALT_TAB LALT(KC_TAB) -``` - -这样键映射代码中就可以使用 `FN_CAPS` 和 `ALT_TAB` 了，可读性好得多。 - -## 一些按键发生了交换，或是不能用了 - -QMK有两个功能系列，Bootmagic及指令，都可以让键盘随时变得灵活多变，功能包含但不限于交换Ctrl/Caps、锁定Gui键、交换Alt/Gui、交换Backspace/Backslash、禁用所有按键等。 - -快速恢复的办法是插入键盘时按住空格+`Backspace`键，这样会重置键盘内存储的设置信息，键盘就会恢复常态。如果问题依旧存在，请参考： - -* [Bootmagic](zh-cn/feature_bootmagic.md) -* [指令](zh-cn/feature_command.md) - -## 菜单键（Menu）不可用 - -现代键盘上，位于 `KC_RGUI` 及 `KC_RCTL` 间的按键实际上叫做 `KC_APP`。原因是该键被发明时，相关标准中已经有了 `菜单（MENU）` 键，因此微软将该键命名为 `APP` 键。 - -## `KC_SYSREQ` 不可用 -请使用截图键码（`KC_PSCREEN` 及 `KC_PSCR`）替代 `KC_SYSREQ`，组合键’Alt + Print Screen‘实际上会被识别为’System request‘。 - -具体参见[issue #168](https://github.com/tmk/tmk_keyboard/issues/168)以及 -* https://en.wikipedia.org/wiki/Magic_SysRq_key -* https://en.wikipedia.org/wiki/System_request - -## 电源键不工作 - -QMK有两个容易让人迷惑的“电源键”键码：HID键盘页的 `KC_POWER`，及用户页的 `KC_SYSTEM_POWER`（或 `KC_PWR`）。 - -前者只有macOS支持，后者连同 `KC_SLEP` 及 `KC_WAKE` 在所有主流操作系统上都支持，因此使用后者是推荐的做法。在Windows下，按下按键即刻就会生效，而macOS下必须按住直到系统弹出一个对话框。 - -## 单发修饰键 -用来解决我自己的’the‘麻烦，我总是会将’The‘错输入为’the‘或’THe‘，单发Shift键缓解了我的这个麻烦。 -https://github.com/tmk/tmk_keyboard/issues/67 - -## 修饰键/层 卡住了 -层切换功能只有在正确配置的情况下，才不会出现卡住修饰键和层的问题。 -对于修饰键和层切换操作来讲，必须确保 `KC_TRANS` 在切换到目标layer时正确置位，才能让修饰键正确释放。或者在释放动作中确保返回到了之前的层。 - -* https://github.com/tmk/tmk_core/blob/master/doc/keymap.md#31-momentary-switching -* https://geekhack.org/index.php?topic=57008.msg1492604#msg1492604 -* https://github.com/tmk/tmk_keyboard/issues/248 - - -## 机械锁定式开关支持 - -该功能支持形如[Alps这款](https://deskthority.net/wiki/Alps_SKCL_Lock)的*机械锁定式开关*，启用该功能须在 `config.h` 中添加如下定义： - -``` -#define LOCKING_SUPPORT_ENABLE -#define LOCKING_RESYNC_ENABLE -``` - -启用该功能后，在你的键映射中须改为使用 `KC_LCAP`，`KC_LNUM` 和 `KC_LSCR`。 - -旧式复古风（vintage style）键盘偶尔能见到锁定式开关，但在现代键盘中见不到了。***因此你基本不会需要这个功能的，直接使用 `KC_CAPS`，`KC_NUM` 和 `KC_SCRL` 就好*** - -## 输入形如法语中软音'Ç'这样的非ASCII字符 - -参见[Unicode](zh-cn/feature_unicode.md)功能. - -## macOS系统下的 `Fn` - -和其它键盘不同，Apple键盘上的Fn有自己的键码...在某种程度上。其占用了基础6KRO HID事件上报中的第六个键码 —— 因此Apple键盘实际上只是5KRO（5键无冲）的。 - -技术上讲QMK确实能发送这种键码，但这么做需要修改上报事件中Fn键状态的格式。更麻烦的是，只有你的键盘的VID及PID与Apple键盘一致时才会生效。QMK对此提供官方支持可能会有法律风险，换句话说，我们不太可能去这么做的。 - -具体信息请参见[这个issue](https://github.com/qmk/qmk_firmware/issues/2179)。 - -## Mac OSX下支持的键有哪些？ -你可以通过查阅以下代码确认OSX下支持的键码。 - -`usb_2_adb_keymap` 数组实现了从 Keyboard/Keypad 页到 ADB 扫描码（OSX内部使用的键码）的转换。 - -https://opensource.apple.com/source/IOHIDFamily/IOHIDFamily-606.1.7/IOHIDFamily/Cosmo_USB2ADB.c - -以及 `IOHIDConsumer::dispatchConsumerEvent` 负责处理用户页部分。 - -https://opensource.apple.com/source/IOHIDFamily/IOHIDFamily-606.1.7/IOHIDFamily/IOHIDConsumer.cpp - - -## Mac OSX下的JIS键 -日语体系的JIS键盘有些特殊键码：`無変換(Muhenkan)`, `変換(Henkan)`, `ひらがな(hiragana)` 在OSX下无法被识别，可以尝试通过以下配置借助 **Seil** 来启用这些键。 - -* 在PC键盘中启用NFER键 -* 在PC键盘中启用XFER键 -* 在PC键盘中启用KATAKANA键 - -https://pqrs.org/osx/karabiner/seil.html - - -## RN-42蓝牙模块与Karabiner的兼容性问题 -Karabiner - Mac OSX系统下的键映射工具 - 默认会忽略RN-42模块的输入事件。须在Karabiner开启相关选项来支持你的键盘。 -https://github.com/tekezo/Karabiner/issues/403#issuecomment-102559230 -这个问题的其它详细信息参见 -https://github.com/tmk/tmk_keyboard/issues/213 -https://github.com/tekezo/Karabiner/issues/403 - - -## Esc和`位于同一个键位 - -参见[Grave Escape](zh-cn/feature_grave_esc.md)功能. - -## Mac OSX下的弹出功能 -`KC_EJCT` 在OSX下可用。 https://github.com/tmk/tmk_keyboard/issues/250 -Windows 10应该是忽略了这个键码，Linux/Xorg能识别到，但默认没有映射处理。 - -目前尚不清楚Apple键盘上弹出键到底是啥，HHKB在Mac模式下使用 `F20` 来作为弹出键（`Fn+f`），但应该和Apple的弹出键码不是一回事儿。 - -## 在 `action_util.c` 中的 `weak_mods` 和 `real_mods` 是什么东西？ -___待完善的内容___ - -real_mods保存的是现实的/物理上的修饰键状态，而weak_mods保存的是虚拟的或临时的修饰键状态，且不应该影响到真实的修饰键的状态。 - -例如你按住了物理键盘上的左shift键，又输入了 ACTION_MODS_KEY(LSHIFT, KC_A)， - -在weak_mods下, -* (1) 按住左shift: real_mods |= MOD_BIT(LSHIFT) -* (2) 按下 ACTION_MODS_KEY(LSHIFT, KC_A): weak_mods |= MOD_BIT(LSHIFT) -* (3) 松开 ACTION_MODS_KEY(LSHIFT, KC_A): weak_mods &= ~MOD_BIT(LSHIFT) -real_mods依然保留着修饰键的状态值。 - -非weak_mods时, -* (1) 按住左shift: real_mods |= MOD_BIT(LSHIFT) -* (2) 按下 ACTION_MODS_KEY(LSHIFT, KC_A): real_mods |= MOD_BIT(LSHIFT) -* (3) 松开 ACTION_MODS_KEY(LSHIFT, KC_A): real_mods &= ~MOD_BIT(LSHIFT) -这时real_mods失去了‘物理键左shift’的状态值。 - -在键盘事件发送时，weak_mods会与real_mods求逻辑或。 -https://github.com/tmk/tmk_core/blob/master/common/action_util.c#L57 diff --git a/docs/zh-cn/faq_misc.md b/docs/zh-cn/faq_misc.md deleted file mode 100644 index d01caba3be..0000000000 --- a/docs/zh-cn/faq_misc.md +++ /dev/null @@ -1,108 +0,0 @@ -# 其它 FAQ - - - -## 怎么对键盘进行测试？ :id=testing - -测试键盘就简单直接，把每个按键按一遍后确认发送的是正确的就行。也可以使用[QMK配置器](https://config.qmk.fm/#/test/)的测试模式检查键盘，即便这键盘没有运行着QMK。 - -## 安全措施 - -你应该不想见到键盘变砖，变得不能再刷写固件。这里给出了一些非常危险（或相反不太危险）的因素。 - -- 如果你的键盘没有RESET键，在你需要进入DFU模式时，不得不需要用螺丝刀打开后盖去按PCB上的RESET键。 -- 把 tmk_core/common 下的文件搞乱的话，容易导致键盘无法使用 -- .hex文件太大的话也会引起问题。`make dfu` 会先擦除存储块，再检查固件大小（哎呀，顺序错了），此时发现错误进而导致刷写失败，键盘停留在DFU模式下。 - - 因此，请留意.hex文件尺寸有大小限制，例如在Planck上是十六进制7000（十进制的28672） - -``` -Linking: .build/planck_rev4_cbbrowne.elf [OK] -Creating load file for Flash: .build/planck_rev4_cbbrowne.hex [OK] - -Size after: - text data bss dec hex filename - 0 22396 0 22396 577c planck_rev4_cbbrowne.hex -``` - - - 上面的文件大小是22396/577ch, 小于28672/7000h - - 任何合适的其它.hex文件，都可以尝试加载 - - 在键盘的Makefile中你添加的一些配置也会额外占用空间，在使用BOOTMAGIC_ENABLE, - MOUSEKEY_ENABLE, EXTRAKEY_ENABLE, CONSOLE_ENABLE, API_SYSEX_ENABLE - 时请留意 -- DFU工具/不会/允许bootloader被覆写（除非你往DFU工具上塞自己的东西），这个风险不大。 -- EEPROM的写循环一般是 100000（100k）次，不应不停地持续重复地刷写固件，不然很快就烧毁了。 - -## NKRO 不好使 -首先请确保在编译固件时有在**Makefile**中启用 `NKRO_ENABLE` - -如果依旧不行，尝试一下 `Magic` **N** 指令（默认是左Shift+右Shift+N），这个指令可以让键盘在**NKRO**和**6KRO**模式间临时切换。有的场景下**NKRO**无法工作必须切换到**6KRO**模式，比如在BIOS中操作时。 - -如果你的固件编译时指定了 `BOOTMAGIC_ENABLE` ，则需要使用 `BootMagic`**N** 指令（默认是空格+N）。这个配置保存在EEPROM中，断电也会留存。 - -https://github.com/tmk/tmk_keyboard#boot-magic-configuration---virtual-dip-switch - - -## 轨迹球需要复位电路 (PS/2鼠标支持) -缺失复位电路的情况下，由于不正确的硬件初始化，可能会导致设备不稳定，具体请参阅TPM754的电路原理图： - -- https://geekhack.org/index.php?topic=50176.msg1127447#msg1127447 -- https://www.mikrocontroller.net/attachment/52583/tpm754.pdf - - -## 无法读到大于16的矩阵列 -当列数大于16时，在 [matrix.h] 中的 `read_cols()` 中请用 `1UL<<16` 替代 `1<<16`。 - -在C语言中，对于AVR上的 `1`，会被视作一种[16位]的[整形(int)]类型，因此无法左移超过15位。因此 `1<<16` 的计算结果会错误地变成0。解决办法就是将类型改为[无符号长整形(unsigned long)]类型的 `1UL`。 - -https://deskthority.net/workshop-f7/rebuilding-and-redesigning-a-classic-thinkpad-keyboard-t6181-60.html#p146279 - -## 有些额外的按键不好使（系统，音频控制键） -在QMK的 `rules.mk` 中须定义 `EXTRAKEY_ENABLE` - -``` -EXTRAKEY_ENABLE = yes # 音频及系统控制 -``` - -## 无法从休眠唤醒 - -在Windows的**电源管理**的**设备管理**中，检查 `允许该设备唤醒计算机` 选项，同时检查一下BIOS中的相关设置，任意一个按键都应该能将计算机从休眠状态唤醒。 - -## 在使用Arduino? - -**注意Arduino的引脚编号与芯片的引脚编号是不同的**。例如，Arduino的 `D0` 引脚并不是 `PD0`，请对照其电路图检查电路。 - -- https://arduino.cc/en/uploads/Main/arduino-leonardo-schematic_3b.pdf -- https://arduino.cc/en/uploads/Main/arduino-micro-schematic.pdf - -Arduino Leonardo 以及 micro 使用的是**ATMega32U4**因此可以用TMK，但bootloader可能会是个麻烦的问题。 - -## 启用JTAG - -默认情况下，键盘启动后JTAG调试接口就被禁用了。支持JTAG的MCU出场时会带着 `JTAGEN` 保险丝，而键盘因为需要这部分MCU的引脚去控制开关矩阵、LED等功能。 - -如果你希望启用JTAG，在 `config.h` 中添加定义： - -```c -#define NO_JTAG_DISABLE -``` - -## USB 3兼容性问题 -将设备从USB 3.x端口改插到USB 2.0端口能解决一些问题。 - - -## Mac相关兼容性问题 -### OS X 10.11 和 Hub -参见: https://geekhack.org/index.php?topic=14290.msg1884034#msg1884034 - - -## BIOS (UEFI) 配置/恢复 (休眠 & 唤醒)/电源循环 -有人反馈过他们的键盘在BIOS下或是从休眠状态唤醒后会不可用。 - -目前这个问题的原因还不清楚，但一些编译选项应该和这个问题有关，你可以在Makefile中禁用 `CONSOLE_ENABLE`, `NKRO_ENABLE`, `SLEEP_LED_ENABLE` 或其他的试一试。 - -更多信息： -- https://github.com/tmk/tmk_keyboard/issues/266 -- https://geekhack.org/index.php?topic=41989.msg1967778#msg1967778 diff --git a/docs/zh-cn/feature_grave_esc.md b/docs/zh-cn/feature_grave_esc.md deleted file mode 100644 index 1795a508ef..0000000000 --- a/docs/zh-cn/feature_grave_esc.md +++ /dev/null @@ -1,39 +0,0 @@ -# Grave Escape - - - -*译注：Grave键即标准键盘中Tab键上方的 ` 键，该符号用于英法语等西语体系，辅助调整发音，中文中没有对应概念；Escape即Esc键* - -若你使用60%或其它没有Fn键配列的键盘，会留意到没有独立的Escape键。Grave Escape功能可以让Grave键(`及`~`)与Escape共享一个按键 - -## 使用方法 - -在配列中使用 `QK_GESC` 替换 `KC_GRAVE` （一般都在`1`键左边）。默认点击会输出 `KC_ESC`，按下Shift或GUI键时，点击会输出 `KC_GRV` - -## 操作系统视角 - -假如翠花按下GESC键，系统接收到的是KC_ESC字符。若翠花按住Shift再按下GESC，将输出 `~` 或是反引号。若翠花按住GUI/CMD/Win键，将仅输出`字符 - -## 键码 - -|键 |别名 |描述 | -|---------|-----------|------------------------------------------------------------------| -|`QK_GESC`|`GRAVE_ESC`|单击输出Escape, 按住Shift或GUI时输出` | - -### 须留意 - -在macOS上 Command+`默认行为是“移动焦点到下一个窗口”，因此不会输出反引号。另外，即便在键盘配置中更改过快捷键，终端程序(Terminal)也通常会将这个操作视为循环切换窗口 - -## 配置 - -有几种键组合可以变更这种行为，如Windows下的Control+Shift+Escape、macOS下的Command+Option+Escape。若要调整，可以在 `config.h` 中通过 `#define` 配置 - -|定义 |描述 | -|--------------------------|-----------------------------------------| -|`GRAVE_ESC_ALT_OVERRIDE` |按住Alt时输出Escape | -|`GRAVE_ESC_CTRL_OVERRIDE` |按住Control时输出Escape | -|`GRAVE_ESC_GUI_OVERRIDE` |按住GUI时输出Escape | -|`GRAVE_ESC_SHIFT_OVERRIDE`|按住Shift时输出Escape | diff --git a/docs/zh-cn/feature_space_cadet.md b/docs/zh-cn/feature_space_cadet.md deleted file mode 100644 index e3dab9c727..0000000000 --- a/docs/zh-cn/feature_space_cadet.md +++ /dev/null @@ -1,70 +0,0 @@ -# Space Cadet: The Future, Built In - - - - -*译注：Space Cadet来源于(在西方早期程序员中)著名的键盘Space Cadet Keyboard，具体信息参见下面的链接或[维基百科](https://en.wikipedia.org/wiki/Space-cadet_keyboard)* - -Steve Losh 在 [Space Cadet Shift](https://stevelosh.com/blog/2012/10/a-modern-space-cadet/) 详细地描述了该功能. 简而言之，点击左Shift时，会输出左括号；点击右Shift时，会输出右括号。如果按住Shift键，常规的Shift将正常工作。这功能实际上和听起来的一样爽，更爽的是现在连Control和Alt也支持！ - -## 使用指南 - -首先，在你的配列中完成以下任一项： -- 替换左Shift为 `KC_LSPO`（左Shift，左括号），替换右Shift为 `KC_RSPC`（右Shift，右括号）。 -- 替换左Control为 `KC_LCPO`（左Control，左括号），替换右Control为 `KC_RCPC`（右Control，右括号）。 -- 替换左Alt为 `KC_LAPO`（左Alt，左括号），替换右Alt为 `KC_RAPC`（右Alt，右括号）。 -- 替换任意一个Shift为 `KC_SFTENT`（右Shift，回车）。 - -## 键码 - -|键码 |描述 | -|-----------|-----------------------------| -|`KC_LSPO` |按住时左Shift，点击时 `(` | -|`KC_RSPC` |按住时右Shift，点击时 `)` | -|`KC_LCPO` |按住时左Control，点击时 `(` | -|`KC_RCPC` |按住时右Control，点击时 `)` | -|`KC_LAPO` |按住时左Alt，点击时 `(` | -|`KC_RAPC` |按住时右Alt，点击时 `)` | -|`KC_SFTENT`|按住时右Shift，点击时回车 | - -## 须留意 - -同时按下两边的Shift键时会与Space Cadet功能冲突。请参见[指令功能](zh-cn/feature_command.md)以了解如何解决，也可以在 `rules.mk` 中禁用指令： - -```make -COMMAND_ENABLE = no -``` - -## 配置 - -默认情况下Space Cadet假设键盘布局为US ANSI，如果你的布局使用不同的括号符，可以在 `config.h` 中重定义。可以修改修饰键点击时发送的字符，亦或阻止修饰键工作。这个新的配置项依次绑定了三个键码：按住或组合其它键使用时的修饰键；点击时发送的修饰键点击（`Tap Modifier`）（在 `KC_TRNS` 中没有修饰键时）；最后是点击时发送的键码。请记住，例如'KC_RSFT'按住时点击 `KC_KSPO` 及 `KC_TRNS` 时，修饰键依旧会对键码生效，即属于修饰键点击。 - -|定义 |默认值 |描述 | -|----------------|-------------------------------|----------------------------------------------------------------| -|`LSPO_KEYS` |`KC_LSFT, LSPO_MOD, LSPO_KEY` |按住时发送`KC_LSFT`，点击时发送 `LSPO_MOD` 及 `LSPO_KEY` 定义的键码. | -|`RSPC_KEYS` |`KC_RSFT, RSPC_MOD, RSPC_KEY` |按住时发送`KC_RSFT`，点击时发送 `RSPC_MOD` 及 `RSPC_KEY` 定义的键码. | -|`LCPO_KEYS` |`KC_LCTL, KC_LSFT, KC_9` |按住时发送`KC_LCTL`，点击时发送 `KC_LSFT` 及 `KC_9`. | -|`RCPC_KEYS` |`KC_RCTL, KC_RSFT, KC_0` |按住时发送`KC_RCTL`，点击时发送 `KC_RSFT` 及 `KC_0`. | -|`LAPO_KEYS` |`KC_LALT, KC_LSFT, KC_9` |按住时发送`KC_LALT`，点击时发送 `KC_LSFT` 及 `KC_9`. | -|`RAPC_KEYS` |`KC_RALT, KC_RSFT, KC_0` |按住时发送`KC_RALT`，点击时发送 `KC_RSFT` 及 `KC_0`. | -|`SFTENT_KEYS` |`KC_RSFT, KC_TRNS, SFTENT_KEY` |按住时发送`KC_RSFT`，点击时发送 `SFTENT_KEY`. | -|`SPACE_CADET_MODIFIER_CARRYOVER` |*未定义* |在尝试触发其它修饰键的修饰键点击前，暂存目前的修饰键。这在尝试触发Space Cadet前频繁发生修饰键提前松开时会有用。(译注[^1]) | - - -## 过时的配置项 - -以下是一些内部用于向后兼容的定义，目前仍可以使用，但上面的定义适用性要强得多。例如，若你点击 `KC_LSPO` 时不想按住修饰键，在旧定义中只有一个办法，使用 `DISABLE_SPACE_CADET_MODIFIER`。但现在可以定义为：`#define LSPO_KEYS KC_LSFT, KC_TRNS, KC_9`，效果是在按住按键时触发左Shift，点击则发送 `KC_9`。 - -|定义 |默认值 |描述 | -|------------------------------|-------------|-------------------------------------| -|`LSPO_KEY` |`KC_9` |点击左Shift时发送的键码 | -|`RSPC_KEY` |`KC_0` |点击右Shift时发送的键码 | -|`LSPO_MOD` |`KC_LSFT` |应用在 `LSPO_KEY` 上的修饰键 | -|`RSPC_MOD` |`KC_RSFT` |应用在 `RSPC_KEY` 上的修饰键 | -|`SFTENT_KEY` |`KC_ENT` |点击Shift时发送的键码 | -|`DISABLE_SPACE_CADET_MODIFIER`|*未定义* |定义时将阻止修饰键应用在Space Cadet上 | - -[^1]这句实在是绕，不能确保翻译到位，请参考英文文档 diff --git a/docs/zh-cn/flashing.md b/docs/zh-cn/flashing.md deleted file mode 100644 index 559b8742d0..0000000000 --- a/docs/zh-cn/flashing.md +++ /dev/null @@ -1,329 +0,0 @@ -# 刷写指引及Bootloader资料 - - - -用于键盘的bootloader有很多种，几乎每一种都在使用私有的刷写协议及工具。幸运的是，形如[QMK工具箱](https://github.com/qmk/qmk_toolbox/releases)这样的工程目标就是尽量支持这些工具，本文会探讨各种bootloader的差异，以及可用的刷写方案。 - -针对基于AVR的键盘，QMK会自动检查所要刷写的 `.hex` 文件大小是否与在 `rules.mk` 中设置的 `BOOTLOADER` 值所匹配，同时会输出字节大小信息（及最大限制）。 - -同时也可以使用CLI工具刷写键盘，执行： -``` -$ qmk flash -kb -km -``` -更多信息参见文档[`qmk flash`](zh-cn/cli_commands.md#qmk-flash)。 - -## Atmel DFU - -Atmel系列的DFU bootloader默认配备在所有USB AVR系列上（16/32U4RC除外），广泛用于一些PCB上具备私有集成电路模块（IC）的键盘上（老款OLKB、Clueboards等）。有些使用的是LUFA实现的DFU bootloader，或是QMK的分支版本（新款OLKB），后者对硬件功能进行了扩充加强。 - -为保证对DFU bootloader的兼容性，请确保在 `rules.mk` 中存在如下部分内容（可选的值还有 `lufa-dfu` 或 `qmk-dfu`）： - -```make -# 选择Bootloader -BOOTLOADER = atmel-dfu -``` - -兼容的刷写工具： - -* [QMK工具箱](https://github.com/qmk/qmk_toolbox/releases)（推荐的图形化工具） -* [dfu-programmer](https://github.com/dfu-programmer/dfu-programmer) / QMK中将构建目标设为 `:dfu`（推荐的命令行工具） - -刷写过程： - -1. 使用如下任一方式进入bootloader模式： - * 点击 `QK_BOOT` 键码 - * 如果PCB上有 `RESET` 键，点击之 - * 快速短接一下RST到GND -2. 等待操作系统识别到设备 -3. 清空flash存储数据（如果使用QMK工具箱或CLI的 `make`会自动进行） -4. 将.hex文件刷写进去 -5. 重置设备进入应用模式（如上，会自动进行） - -### QMK DFU - -QMK维护了[一个LUFA DFU bootloader的分支版本](https://github.com/qmk/lufa/tree/master/Bootloaders/DFU)，其可以进行一次矩阵扫描来退出bootloader进入应用模式，同时会让LED闪烁或蜂鸣器响一声。若要启用该功能，将以下定义添加到 `config.h`： - -```c -#define QMK_ESC_OUTPUT F1 // COL pin if COL2ROW -#define QMK_ESC_INPUT D5 // ROW pin if COL2ROW -// 可选: -//#define QMK_LED E6 -//#define QMK_SPEAKER C6 -``` -目前来讲不推荐将 `QMK_ESC` 键设置成与[Bootmagic](zh-cn/feature_bootmagic.md)同一个键，否则按下该键时只会让MCU在bootloader模式上反复进出。 - -制造商及型号字符串自动从 `config.h` 中获取，并会在型号后追加 " Bootloader"。 - -要生成该bootloader，需指定 `bootloader` 构建目标，即 `make planck/rev4:default:bootloader`。要生成可部署到正式产品的.hex文件（同时包含QMK及bootloader），使用 `production` 构建目标，即 `make planck/rev4:default:production`。 - -### `make` 构建目标 - -* `:dfu`: 每5秒检测一次直到发现可用的DFU设备，然后进行固件刷写。 -* `:dfu-split-left` 和 `:dfu-split-right`: 同 `:dfu` 一样会刷写固件，但额外地会设置手性设置到EEPROM中，对于基于Elite-C的分体式键盘这是理想的方法。 - -## Caterina - -Arduino及其仿制板使用[Caterina bootloader](https://github.com/arduino/ArduinoCore-avr/tree/master/bootloaders/caterina)或某种变体（使用Pro Micro或其仿制芯片、Pololu A-Star等构建的所有键盘），并基于虚拟串口使用AVR109协议进行通信。 - -为确保对Caterina bootloader的兼容性，请添加如下代码块至 `rules.mk`： - -```make -# 选择Bootloader -BOOTLOADER = caterina -``` - -兼容的刷写工具： - -* [QMK工具箱](https://github.com/qmk/qmk_toolbox/releases) （推荐的图形化工具） -* [avrdude](https://www.nongnu.org/avrdude/) QMK中须基于 `avr109` 编程器 / `:avrdude` 构建目标 （推荐的命令行工具） -* [AVRDUDESS](https://github.com/zkemble/AVRDUDESS) - -刷写过程： - -1. 使用如下任一方式进入bootloader模式（进入该模式后只有7秒时间可以刷写；一些型号需要你在750ms内重置两次）： - * 点击 `QK_BOOT` 键码 - * 如果PCB上有 `RESET` 键，点击之 - * 快速短接一下RST到GND -2. 等待操作系统识别到设备 -3. 将.hex文件刷写进去 -4. 等待设备自动重置 - -### `make` 构建目标 - -* `:avrdude`: 每5秒检测一次直到发现可用的Caterina设备（通过检测新COM端口），然后进行固件刷写。 -* `:avrdude-loop`: 同 `:avrdude` 一样刷写固件，但会在一个设备刷写完后再次尝试刷写。主要用于批量刷写设备。按 Ctrl+C 以终止循环检测。 -* `:avrdude-split-left` 和 `:avrdude-split-right`: 同 `:avrdude` 一样会刷写固件，但额外地会设置手性设置到EEPROM中，对于基于Pro Micro的分体式键盘这是理想的方法。 - -## HalfKay - -HalfKay是一款由PJRC开发的超精简的bootloader，且呈现为HID设备（因此不需要额外的驱动），在所有的Teensys，即"the 2.0"，上已经预刷写过。该bootloader目前是闭源的，因此一旦覆写（即通过ISP刷入其它bootloader）掉，就无法复原了。 - -为确保对Halfkay bootloader的兼容性，请添加如下代码块至 `rules.mk`： - -```make -# 选择Bootloader -BOOTLOADER = halfkay -``` - -兼容的刷写工具： - -* [QMK工具箱](https://github.com/qmk/qmk_toolbox/releases)（推荐的图形化工具） -* [Teensy Loader Command Line](https://www.pjrc.com/teensy/loader_cli.html) / QMK中将构建目标设为 `:teensy`（推荐的命令行工具） -* [Teensy Loader](https://www.pjrc.com/teensy/loader.html) - -刷写过程： - -1. 使用如下任一方式进入bootloader模式（进入该模式后只有7秒时间可以刷写）： - * 点击 `QK_BOOT` 键码 - * 如果Teensy上或PCB上有 `RESET` 键，点击之 - * 快速短接一下RST到GND -2. 等待操作系统识别到设备 -3. 将.hex文件刷写进去 -4. 重置设备进入应用模式（可能会自动进行） - -## USBasploader - -USBasploader是一款来源于[Objective Development](https://www.obdev.at/products/vusb/usbasploader.html)的bootloader。它通过模拟出一个USBasp ISP编程器来运行V-USB以用于一些形如ATmega328P这样的“非USB AVR芯片”。 - -为确保对USBasploader bootloader的兼容性，请添加如下代码块至 `rules.mk`： - -```make -# 选择Bootloader -BOOTLOADER = usbasploader -``` - -兼容的刷写工具： - -* [QMK工具箱](https://github.com/qmk/qmk_toolbox/releases)（推荐的图形化工具） -* [avrdude](https://www.nongnu.org/avrdude/) QMK中须基于 `usbasp` 编程器 / `:usbasp` 构建目标（推荐的命令行工具） -* [AVRDUDESS](https://github.com/zkemble/AVRDUDESS) - -刷写过程： - -1. 使用如下任一方式进入bootloader模式： - * 点击 `QK_BOOT` 键码 - * 在按住 `BOOT` 按钮时，快速点击一下PCB上的 `RESET` -2. 等待操作系统识别到设备 -3. 将.hex文件刷写进去 -4. 点击PCB上的 `RESET` 按钮或将RST短接至GND一下。 - -## BootloadHID - -BootloadHID是一款用于AVR微控制器的bootloader，其呈现为HID输入设备，和HalkKay很像，因此在Windows下也无需安装驱动。 - -为确保对bootloadHID bootloader的兼容性，请添加如下代码块至 `rules.mk`： - -```make -# 选择Bootloader -BOOTLOADER = bootloadhid -``` - -兼容的刷写工具： - -* [QMK工具箱](https://github.com/qmk/qmk_toolbox/releases)（推荐的图形化工具） -* [bootloadHID CLI](https://www.obdev.at/products/vusb/bootloadhid.html) / QMK中将构建目标设为 `:bootloadhid`（推荐的命令行工具） -* [HIDBootFlash](http://vusb.wikidot.com/project:hidbootflash) - - -刷写过程： - -1. 使用如下任一方式进入bootloader模式： - * 点击 `QK_BOOT` 键码 - * 在按住“盐键”（salt key）时插入键盘 - 在PS2AVRGB板上，通常在MCU的A0及B0引脚上有这个按键，否则请查看键盘的使用说明。 -2. 等待操作系统识别到设备 -3. 将.hex文件刷写进去 -4. 重置设备到应用模式（可能会自动进行） - -### QMK HID - -QMK维护了[一个LUFA HID bootloader的分支版本](https://github.com/qmk/lufa/tree/master/Bootloaders/HID)，通过USB HID节点设备进行刷写，工作模式类似于PJRC的Teensy Loader刷写器以及HalfKay bootloader。其可以进行一次矩阵扫描来退出bootloader进入应用模式，同时会让LED闪烁或蜂鸣器响一声。 - -为确保对QMK HID bootloader的兼容性，请添加如下代码块至 `rules.mk`： - -```make -# 选择Bootloader -BOOTLOADER = qmk-hid -``` - -要启用额外的功能支持，请添加如下定义至 `config.h`： - -```c -#define QMK_ESC_OUTPUT F1 // COL pin if COL2ROW -#define QMK_ESC_INPUT D5 // ROW pin if COL2ROW -// 可选: -//#define QMK_LED E6 -//#define QMK_SPEAKER C6 -``` - -目前来讲不推荐将 `QMK_ESC` 键设置成与[Bootmagic Lite](zh-cn/feature_bootmagic.md)同一个键，否则按下该键时只会让MCU在bootloader模式上反复进出。 - -制造商及型号字符串自动从 `config.h` 中获取，并会在型号后追加 " Bootloader"。 - -要生成该bootloader，需指定 `bootloader` 构建目标，即 `make planck/rev4:default:bootloader`。要生成可部署到正式产品的.hex文件（同时包含QMK及bootloader），使用 `production` 构建目标，即 `make planck/rev4:default:production`。 - -兼容的刷写工具： - -* TBD - * 目前只能选择使用该 [Python脚本](https://github.com/qmk/lufa/tree/master/Bootloaders/HID/HostLoaderApp_python), 或从LUFA仓库中构建[`hid_bootloader_cli`](https://github.com/qmk/lufa/tree/master/Bootloaders/HID/HostLoaderApp)。Homebrew也许（即将）能直接支持（通过 `brew install qmk/qmk/hid_bootloader_cli`）。 - -刷写过程： - -1. 使用如下任一方式进入bootloader模式： - * 点击 `QK_BOOT` 键码 - * 如果PCB上有 `RESET` 键，点击之 - * 快速短接一下RST到GND -2. 等待操作系统识别到设备 -4. 将.hex文件刷写进去 -5. 重置设备进入应用模式（可能会自动进行） - -### `make` 构建目标 - -* `:qmk-hid`: 每5秒检测一次直到发现可用的DFU设备，然后进行固件刷写。 - -## STM32/APM32 DFU - -所有的STM32及APM32 MCU系列，除F103型号外（参见[STM32duino小节](#stm32duino)）都在出场时预装了bootloader且无法修改或删除。 - -为确保对STM32-DFU bootloader的兼容性，请添加如下代码块至 `rules.mk`（可选替代项为 `apm32-dfu`）： - -```make -# 选择Bootloader -BOOTLOADER = stm32-dfu -``` - -兼容的刷写工具： - -* [QMK工具箱](https://github.com/qmk/qmk_toolbox/releases) （推荐的图形化工具） -* [dfu-util](https://dfu-util.sourceforge.net/) / QMK中将构建目标设为 `:dfu-util`（推荐的命令行工具） - -刷写过程： - -1. 使用如下任一方式进入bootloader模式（进入该模式后只有7秒时间可以刷写）： - * 点击 `QK_BOOT` 键码（对STM32F042设备可能无效） - * 如果有重置电路，点击PCB上的 `RESET` 键；有些主控板上可能会有一个开关需要先打开 - * 否则，你需要将 `BOOT0` 接线到VCC（通过 `BOOT0` 按钮或跳线），短接 `RESET` 至GND（通过 `RESET` 按钮或条线），然后断开 `BOOT0` 的接线。 -2. 等待操作系统识别到设备 -3. 将.bin文件刷写进去 -4. 重置设备进入应用模式（可能会自动进行） - -### `make` 构建目标 - -* `:dfu-util`: 每5秒检测一次直到发现可用的STM32 bootloader设备，然后进行固件刷写。 -* `:dfu-util-split-left` 和 `:dfu-util-split-right`: 同 `:dfu-util` 一样会刷写固件，但额外地会设置手性设置到EEPROM中，对于基于Proton-C的分体式键盘这是理想的方法。 -* `:st-link-cli`: 通过ST-Link CLI工具集而非dfu-util进行刷写，需要有ST-Link电子狗。 -* `:st-flash`: 通过[STLink工具](https://github.com/stlink-org/stlink)内的 `st-flash` 工具而非dfu-util进行刷写，需要有ST-Link电子狗。 - -## STM32duino :id=stm32duino - -该bootloader几乎是STM32F103板专用，该型号出厂不带USB DFU bootloader。其源代码及预编译好的二进制文件[在这里](https://github.com/rogerclarkmelbourne/STM32duino-bootloader)。 - -为确保对STM32duino bootloader的兼容性，请添加如下代码块至 `rules.mk`： - -```make -# 选择Bootloader -BOOTLOADER = stm32duino -``` - -兼容的刷写工具： - -* [QMK工具箱](https://github.com/qmk/qmk_toolbox/releases) （推荐的图形化工具） -* [dfu-util](https://dfu-util.sourceforge.net/) / QMK中将构建目标设为 `:dfu-util`（推荐的命令行工具） - -刷写过程： - -1. 使用如下任一方式进入bootloader模式（进入该模式后只有7秒时间可以刷写）： - * 点击 `QK_BOOT` 键码（对STM32F042设备可能无效） - * 如果有重置电路，点击PCB上的 `RESET` 键；有些主控板上可能会有一个开关需要先打开 - * 否则，你需要将 `BOOT0` 接线到VCC（通过 `BOOT0` 按钮或跳线），短接 `RESET` 至GND（通过 `RESET` 按钮或条线），然后断开 `BOOT0` 的接线。 -2. 等待操作系统识别到设备 -3. 将.bin文件刷写进去 -4. 重置设备进入应用模式（可能会自动进行） - -## Kiibohd DFU - -Input Club出品的键盘使用NXP Kinetis微控制器而非STM32，并使用了独有的[自制bootloader](https://github.com/kiibohd/controller/tree/master/Bootloader)，然而处理器 及协议上两者大部分是一致的。 - -在 `rules.mk` 中该bootloader的设置项为 `kiibohd`，但既然该bootloader仅用在Input Club主控板上，就不必要设置到键映射或是用户级了。 - -兼容的刷写工具： - -* [QMK工具箱](https://github.com/qmk/qmk_toolbox/releases)（推荐的图形化工具） -* [dfu-util](https://dfu-util.sourceforge.net/) / QMK中将构建目标设为 `:dfu-util`（推荐的命令行工具） - -刷写过程： - -1. 使用如下任一方式进入bootloader模式： - * 点击 `QK_BOOT` 键码（有可能只能进入到“安全”bootloader模式，参见[这里](https://github.com/qmk/qmk_firmware/issues/6112)） - * 如果PCB上有 `RESET` 键，点击之 -2. 等待操作系统识别到设备 -3. 将.bin文件刷写进去 -4. 重置设备进入应用模式（可能会自动进行） - -## tinyuf2 - -键盘可以考虑支持tinyuf2 bootloader，目前唯一支持的设备是F401/F411 blackpill。 - -在 `rules.mk` 中该bootloader的设置项为 `tinyuf2`，也可指定到键映射及用户级中。 - -为确保对tinyuf2 bootloader的兼容性，请添加如下代码块至 `rules.mk`： - -```make -# 选择Bootloader -BOOTLOADER = tinyuf2 -``` - -兼容的刷写工具： - -* 任何具备文件拷贝能力的程序，如 _macOS Finder_ 或 _Windows Explorer_ *。 - -刷写过程： - -1. 使用如下任一方式进入bootloader模式： - * 点击 `QK_BOOT` 键码 - * 双击PCB上的 `nRST` 键 -2. 等待操作系统识别到设备 -3. 将.uf2文件拷贝到新出现的USB存储设备上 -4. 等待设备恢复可用状态 diff --git a/docs/zh-cn/flashing_bootloadhid.md b/docs/zh-cn/flashing_bootloadhid.md deleted file mode 100644 index c5e944f947..0000000000 --- a/docs/zh-cn/flashing_bootloadhid.md +++ /dev/null @@ -1,75 +0,0 @@ -# BootloadHID刷写指引及资料 - - - -ps2avr(GB)基于一片ATmega32A微控制器及特殊的bootloader，无法使用常规的QMK方法进行刷写。 - -常规刷写过程： - -1. 使用如下任一方式进入bootloader模式： - * 点击 `QK_BOOT` 键码（一些设备上不管用） - * 在按住“盐键”（salt key）时插入键盘（该键一般会在键盘使用说明上写明） -2. 等待操作系统识别到设备 -3. 将.hex文件刷写进去 -4. 重置设备到应用模式（可能会自动进行） - -## 用于bootloadHID刷写的构建目标 - -?> 使用QMK安装脚本，具体[参见这里](zh-cn/newbs_getting_started.md)，所需的bootloadHID工具应自动被安装上。 - -若希望通过命令行进行刷写，通过如下命令指定 `:bootloadhid` 构建目标： - - make ::bootloadhid - -## 基于图形化界面的刷写方法 - -### Windows -1. 下载[HIDBootFlash](http://vusb.wikidot.com/project:hidbootflash) -2. 重置键盘 -3. 确认VID为 `16c0` 且PID为 `05df` -4. 点击 `查找设备（Find Device）` 并确认目标键盘可见 -5. 点击 `打开.hex文件（Open .hex File）` 并定位到你创建的.hex文件 -6. 点击 `刷写设备（Flash Device）` 并等待刷写完毕 - -## 在命令行中进行刷写 - -1. 重置键盘 -2. 通过输入 `bootloadHID -r` 并追加 `.hex` 文件的路径进行主控板的刷写 - -### Windows系统上手动安装 -针对MSYS2: -1. 下载BootloadHID固件包：https://www.obdev.at/downloads/vusb/bootloadHID.2012-12-08.tar.gz -2. 使用合适的工具解压，如7-Zip -3. 将解压出的 `commandline/bootloadHID.exe` 拷贝至MSYS目录下，一般是 `C:\msys64\usr\bin` - -针对Windows本地环境刷写，`bootloadHID.exe` 可以直接在非MSYS2环境下执行。 - -### Linux系统上手动安装 -1. 安装libusb开发依赖项： - ```bash - # 该操作具体取决于系统 - Debian下可以这样 - sudo apt-get install libusb-dev - ``` -2. 下载BootloadHID固件包： - ``` - wget https://www.obdev.at/downloads/vusb/bootloadHID.2012-12-08.tar.gz -O - | tar -xz -C /tmp - ``` -3. 构建bootloadHID可执行程序： - ``` - cd /tmp/bootloadHID.2012-12-08/commandline/ - make - sudo cp bootloadHID /usr/local/bin - ``` - -### MacOS系统上手动安装 -1. 执行以下命令安装Homebrew： - ``` - /usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)" - ``` -2. 安装以下包： - ``` - brew install --HEAD https://raw.githubusercontent.com/robertgzr/homebrew-tap/master/bootloadhid.rb - ``` diff --git a/docs/zh-cn/getting_started_docker.md b/docs/zh-cn/getting_started_docker.md deleted file mode 100644 index 038f17f9ac..0000000000 --- a/docs/zh-cn/getting_started_docker.md +++ /dev/null @@ -1,59 +0,0 @@ -# Docker快速上手指引 - - - -本工程包含了一套Docker工作流，可以方便地在不更改你主系统环境情况下完成新固件文件的构建工作。这同时也保证了在你拉取该工程代码后的编译环境与其他人以及QMK开发者的一致。当你需要其他人协助你排查遇到的问题时会方便很多。 - -## 需求 - -核心需求是一个已安装的可用的 `docker` 或 `podman`。 -* [Docker CE](https://docs.docker.com/install/#supported-platforms) -* [Podman](https://podman.io/getting-started/installation) - -## 用法 - -拉取QMK仓库到本地（包括所有的子模块）： - -```bash -git clone --recurse-submodules https://github.com/qmk/qmk_firmware.git -cd qmk_firmware -``` - -执行以下命令构建键映射： -```bash -util/docker_build.sh : -# 例: util/docker_build.sh planck/rev6:default -``` - -如上可以构建所需的键盘/键映射，可用于刷写的 `.hex` 及 `.bin` 输出文件存放在QMK目录下。如果省略了 `:keymap` 参数，所有的键映射都会被编译。留意编译参数格式与 `make` 构建时的一致。 - -同时也支持直接从Docker中编译和刷写，只需要指定 `target`： - -```bash -util/docker_build.sh keyboard:keymap:target -# 例: util/docker_build.sh planck/rev6:default:flash -``` - -可以不带参数地执行该脚本，其会依次要求你输入这些参数，也许你会觉得这样更好用： - -```bash -util/docker_build.sh -# 从输入中读取参数 (留空则构建所有的键盘/键映射) -``` - -可以通过设置环境变量 `RUNTIME` 为想使用的容器运行时的名称或路径来指定运行时，默认其会检测并自动选取docker或podman，相比于podman会更倾向于用docker。 - -```bash -RUNTIME="podman" util/docker_build.sh keyboard:keymap:target -``` - -## FAQ - -### 为什么我无法在我的Windows/macOS下刷写固件 - -在Windows及macOS上，需要有[Docker Machine](http://gw.tnode.com/docker/docker-machine-with-usb-support-on-windows-macos/)运行着，配置过程很繁琐，因此我们没有做推荐。请考虑使用[QMK工具箱](https://github.com/qmk/qmk_toolbox)。 - -!> Windows下需要启用[Hyper-V](https://docs.microsoft.com/en-us/virtualization/hyper-v-on-windows/quick-start/enable-hyper-v)才能运行Docker，这也意味着它无法运行在没有Hyper-V的Windows版本下，如Windows 7，Windows 8及**Windows 10家庭版**。 diff --git a/docs/zh-cn/getting_started_github.md b/docs/zh-cn/getting_started_github.md deleted file mode 100644 index 2a5ec8ca4f..0000000000 --- a/docs/zh-cn/getting_started_github.md +++ /dev/null @@ -1,69 +0,0 @@ -# 如何在QMK中使用GitHub - - - -对不熟悉 GitHub 的人来说，使用GitHub 可能会有些难度。此教程会教您 fork 和 clone QMK，以及向 QMK 提交 pull request 。 - -?> 本教程假设您已安装GitHub，并且您喜欢使用命令行工作。 - -首先 [GitHub上的QMK页面](https://github.com/qmk/qmk_firmware), 您能看到右上方有个按钮写着"Fork": - -![从GitHub上分叉](https://i.imgur.com/8Toomz4.jpg) - -如果你是某组织成员，你将需要选择分叉到哪个账户。一般情况下, 你是想要分叉到你的私人账户下。当你完成分叉 (有时需要等一会), 点击"Clone or Download" 按钮: - -!从GitHub下载](https://i.imgur.com/N1NYcSz.jpg) - -你要选择 "HTTPS", 然后选择链接复制: - -![HTTPS链接](https://i.imgur.com/eGO0ohO.jpg) - -然后，在命令行输入`git clone --recurse-submodules `，然后粘贴你的链接: - -``` -user@computer:~$ git clone --recurse-submodules https://github.com/whoeveryouare/qmk_firmware.git -Cloning into 'qmk_firmware'... -remote: Enumerating objects: 9, done. -remote: Counting objects: 100% (9/9), done. -remote: Compressing objects: 100% (5/5), done. -remote: Total 183883 (delta 5), reused 4 (delta 4), pack-reused 183874 -Receiving objects: 100% (183883/183883), 132.90 MiB | 9.57 MiB/s, done. -Resolving deltas: 100% (119972/119972), done. -... -Submodule path 'lib/chibios': checked out '587968d6cbc2b0e1c7147540872f2a67e59ca18b' -Submodule path 'lib/chibios-contrib': checked out 'ede48346eee4b8d6847c19bc01420bee76a5e486' -Submodule path 'lib/googletest': checked out 'ec44c6c1675c25b9827aacd08c02433cccde7780' -Submodule path 'lib/lufa': checked out 'ce10f7642b0459e409839b23cc91498945119b4d' -``` - -现在你本地计算机有QMK的分叉了,你可以添加你的布局了, 为你的键盘编译并刷新固件吧。如果你觉得你的修改很不错, 你可以添加,提交,然后想你的分叉推出（pull）你的改变，像这样: - -``` -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/你的GitHub账户名/qmk_firmware`) ,你可以点击下方所示按钮创建 "New Pull Request": - -![新的 Pull Request](https://i.imgur.com/DxMHpJ8.jpg) - -现在你可以看到你所做的一切 - 如果看起来不错, 就可以点击 "Create Pull Request"定稿了: - -![创建Pull Request](https://i.imgur.com/Ojydlaj.jpg) - -提交后,我们会开跟你说你的改动,要求您进行更改, 并最终接受您的更改!感谢您为QMK做的贡献 :) diff --git a/docs/zh-cn/getting_started_introduction.md b/docs/zh-cn/getting_started_introduction.md deleted file mode 100644 index 82d50355eb..0000000000 --- a/docs/zh-cn/getting_started_introduction.md +++ /dev/null @@ -1,59 +0,0 @@ -# 介绍 - - - -本页解释了使用QMK项目所需的基本信息。它假定您能熟练使用Unix shell，但您不熟悉C语言也不熟悉使用make编译。 - -## 基本QMK结构 - -QMK是[Jun Wako](https://github.com/tmk)的[tmk_keyboard](https://github.com/tmk/tmk_keyboard)工程的一个分叉。经过更改的TMK原始代码放在`tmk_core` 文件夹中。 QMK增加的新东西可以在 `quantum` 文件夹中找到。 键盘项目可以在 `handwired`（手动飞线） 和 `keyboard`（PCB键盘）这两个文件夹找到。 - -### 用户空间结构 - -在`users`文件夹里面的目录是每个用户的目录。这个文件夹里面放的是用户们在不同键盘都能用到的代码。详见[用户空间特性](zh-cn/feature_userspace.md) - -### 键盘项目结构 - -在`keyboards`文件夹和他的子文件夹`handwired`中就是各个键盘的项目了，比如`qmk_firmware/keyboards/clueboard`。内部结构与如下: - -* `keymaps/`: 可以构建的不同布局 -* `rules.mk`: 用来设置 "make" 命令默认选项的文件。别直接编辑这个文件,你应该使用具体某个布局的 `rules.mk`. -* `config.h`: 用于设置默认编译选项的文件。别直接编辑这个文件, 你应该使用具体某个布局的 `config.h`. - -### 布局结构 - -在各个布局的文件夹，你能找到以下文件。只有 `keymap.c` 是必要的, 如果其他文件找不到就会直接选择默认选项。 - -* `config.h`: 配置布局的选项 -* `keymap.c`: 布局的全部代码, 必要文件 -* `rules.mk`: 使能的QMK特性 -* `readme.md`:介绍你的布局,告诉别人怎么使用，附上功能说明。请将图片上传到imgur等图床（译注：imgur可能已被墙，为了方便国人访问，建议使用国内可以直接访问的图床）。 - -# `config.h` 文件 - -有三个重要的`config.h` 位置: - -* 键盘 (`/keyboards//config.h`) -* 用户空间 (`/users//config.h`) -* 布局 (`/keyboards//keymaps//config.h`) - -构建系统按照上述顺序自动获取配置文件。如果要覆盖由上一个 `config.h` 所做的设置，您需要首先为要更改的设置包含一些样板代码。 - -``` -#pragma once -``` - -要覆盖上一个 `config.h` 所做的设置，你要先 `#undef` 然后再 `#define` 这个设置. - -样板代码和设置看起来像这样： - -``` -#pragma once - -// 像下面那样覆盖设置（MY_SETTING指的是你要覆盖的设置项）! -#undef MY_SETTING -#define MY_SETTING 4 -``` diff --git a/docs/zh-cn/hand_wire.md b/docs/zh-cn/hand_wire.md deleted file mode 100644 index 97e80251fe..0000000000 --- a/docs/zh-cn/hand_wire.md +++ /dev/null @@ -1,255 +0,0 @@ -# 手工搭建指南 - - - -## 模块清单 - -你需要的模块有：（*x*为你设计的键盘的键数） - -* QMK所兼容的主控板（Teensy, Pro-Micro, QMK Proton C 等） -* *x* 个键轴 （MX, Matias, Gateron 等） -* *x* 个通孔二极管（译注：即普通的直插二极管） -* 定位板及卫星轴 -* 电线 -* 电烙铁 -* 松香/焊油 -* 通风的环境/风扇通风 -* 剪线钳 - -可选地但比较有用的： - -* 剥线钳/一把锋利的剪刀 -* 镊子及小尖嘴钳 -* 焊台/一位助手 - -## 前期工作 - -组装PCB矩阵的方法多种多样，这份指引会描述一些基础信息并给出一些推荐方案。 - -既然我们要进行手工飞线搭建，这里就假设你已经有了定位板。如果你想构建完全定制化的配列，有 [ai03 Plate Generator](https://kbplate.ai03.me/) 以及 [Swillkb Plate & Case Builder](http://builder.swillkb.com/) 这样的工具可以助你设计出一个新的。 - -首先从安装键轴及卫星轴开始，考虑厚度及材质的影响，可能需要热熔胶来固定。 - -## 设计矩阵 :id=planning-the-matrix - -如果你在参考已有的手工搭建指南（比如[自制键盘固件目录](https://github.com/qmk/qmk_firmware/tree/master/keyboards/handwired)下的键盘），可以跳过该步骤，确保是按照文中的矩阵方案连线即可。 - -如果你的方案是将每个开关的一个引脚与两边的开关相连（行方向），另一个引脚与上下的开关相连（列方向），并串联一个二极管到一端，最常用的方案是二极管背对着连接到行方向的引脚（列向行）。即让远离二极管黑线一端连接到开关上（电流只能从一个方向通过二极管）。 - -可以很容易地设计出正交连接的键盘（如Planck）。 -（译注：这里的“正交”意思是行列方向连接规整） - -![Planck矩阵示例图](https://i.imgur.com/FRShcLD.png) -[作者：RoastPotatoe "如何手工搭建Planck键盘"](https://blog.roastpotatoes.co/guide/2015/11/04/how-to-handwire-a-planck/) （英文）内的图例 - -键盘配列越大，功能越丰富，则矩阵也会更复杂。[Keyboard Firmware Builder](https://kbfirmware.com/) 可以帮助你设计矩阵配列（下图为通过 [Keyboard Layout Editor](https://www.keyboard-layout-editor.com) 导出的全尺寸ISO键盘）。 - -![ISO键盘矩阵示例图](https://i.imgur.com/UlJ4ZDP.png) - -必须时刻留意矩阵的行列数总和不能超出控制器的IO引脚数，因此上图的方案可以使用 Proton C 或 Teensy++ 控制器，但常规 Teensy 或 Pro Micro 不行。 - -### 常见微控制器板 :id=common-microcontroller-boards - -| 控制器板 | 控制器方案 | # I/O引脚数 | 引脚图 | -| :------------ |:-------------:| ------:| ------ | -| Pro Micro* | ATmega32u4 | 20 | [链接](https://learn.sparkfun.com/tutorials/pro-micro--fio-v3-hookup-guide/hardware-overview-pro-micro#Teensy++_2.0) | -| Teensy 2.0 | ATmega32u4 | 25 | [链接](https://www.pjrc.com/teensy/pinout.html) | -| [QMK Proton C](https://qmk.fm/proton-c/) | STM32F303xC | 36 | [链接 1](https://i.imgur.com/RhtrAlc.png), [2](https://deskthority.net/wiki/QMK_Proton_C) | -| Teensy++ 2.0 | AT90USB1286 | 46 | [链接](https://www.pjrc.com/teensy/pinout.html#Teensy_2.0) | - -*Elite C 与 Pro Micro 除将 Micro USB 替换为 USB-C 外其余无差别。 - -一些主控板专门为手工接线设计，除可直接连接少量开关外还有额外的引脚，但这些通常会更贵一些，也更难掌控。 - -实装的 Postage mini 主控板 - -| 控制器板 | 控制器方案 | # I/O引脚数 | -| :------------ |:-------------:| ------:| -| [Swiss helper](https://www.reddit.com/r/MechanicalKeyboards/comments/8jg5d6/hand_wiring_this_might_help/) | ATmega32u4 | 20 | -| [Postage 主控板](https://github.com/LifeIsOnTheWire/Postage-Board/)| ATmega32u4| 25 | -| [Postage mini 主控板](https://geekhack.org/index.php?topic=101460.0)| ATmega32u4| 25 | - -## 矩阵布线 - -布线方案不是唯一的，要达成的效果是可以正确连接所有的焊点并不会出现预期外的短路。 - -公开的材料和技术方案： - -（译注：链接文章及标题恕不翻译） - -| 技术方案 | 示例 | 优点 | 缺点 | 图片 -| :-----------| :------- | :------ | :--- | :--- -| 间断开口的线缆 | [Sasha Solomon's Dactyl](https://medium.com/@sachee/building-my-first-keyboard-and-you-can-too-512c0f8a4c5f) 以及 [Cribbit's modern hand wire](https://geekhack.org/index.php?topic=87689.0) | 整洁 | 线缆开口的操作会有些困难 | ![开口的线缆](https://i.imgur.com/0GNIYY0.jpg) -| 适宜长度的线缆 | [u/xicolinguada's ortho build](https://www.reddit.com/r/MechanicalKeyboards/comments/c39k4f/my_first_hand_wired_keyboard_its_not_perfect_but/) | 剥线容易 | 较难固定位置 | ![适宜长度的线缆](https://i.imgur.com/mBe5vkL.jpg) -| 漆包线 | [fknraiden's custom board](https://geekhack.org/index.php?topic=74223.0) | 可以直接焊接（烧掉绝缘层） | 外观差？ | ![漆包线](https://i.imgur.com/b4b7KDb.jpg) -| 弯折二极管引脚作为行方向连线 | [Matt3o's Brownfox](https://deskthority.net/viewtopic.php?f=7&t=6050) | 焊点更少 | 绝缘性差 | ![弯折了的二极管引脚](https://i.imgur.com/aTnG8TV.jpg) -| 硬线（如铜管） | [u/d_stilgar's invisible hardline](https://www.reddit.com/r/MechanicalKeyboards/comments/8aw5j2/invisible_hardline_keyboard_progress_update_april/) 以及 [u/jonasfasler's first attempt](https://www.reddit.com/r/MechanicalKeyboards/comments/de1jyv/my_first_attempt_at_handwiring_a_keyboard/) | 非常漂亮 | 难度高，没有物理绝缘 | ![手工连接的硬线](https://i.imgur.com/CnASmPo.jpg) -| 用绝缘胶带（如高温胶带*）隔离开的裸线 | [Matt3o's 65% on his website](https://matt3o.com/hand-wiring-a-custom-keyboard/) | 简单（不用剥线） | 丑拒 | ![裸线](https://i.imgur.com/AvXZShD.jpg) -| 铜箔胶带 | [ManuForm Dactyl](https://github.com/tshort/dactyl-keyboard) | 非常简单 | 只适用于定位板/外壳与开关底部平齐的情况 | ![铜箔胶带](https://i.imgur.com/RFyNMlL.jpg) - -（*译注：原文是聚酰亚胺胶带，在中国通常叫高温胶带） - - -以上方案可以结合使用，在焊接前请准备好各种长度的线缆。 - - -### 分体键盘的注意事项 - -如果你想制作的是分体键盘（如Dactyl），每一半边都需要一个控制器以及连通两方的通信用线（如TRRS或硬连接线）。更多资料参见[QMK分体键盘文档](zh-cn/feature_split_keyboard.md)。 -（译注：TRRS即一种常用的4线耳机线插口，具体信息请查阅维基百科或[这份知乎文章](https://zhuanlan.zhihu.com/p/144233538)） - - -### 焊接 - -你可以找到很多焊接指导及技巧，这里列出了最相关及最关键的部分： - -要想焊接的牢固需要确保焊料与焊接两端的金属面充分地接触，一个好办法（也不是必须）是上锡前先（将线缆）在针脚上绕一圈或先拧在一起。 - -杆上绕圈 绕环的二极管引脚 - -如果二极管还在包装条上且需要弯折（作为绕圈的起点处或用于连接到邻接处），一个简便的办法是找一个盒子、桌子或尺子的直边上进行弯折。由于弯折统一在二极管一侧，也有助于区分二极管的方向。 - -弯折二极管引脚 - -如果你的电烙铁有温控功能，将其设置在 315ºC（600ºF）。 - -热起来后，给电烙铁上锡 - 即融化一部分锡料到烙铁头上然后立刻用湿海绵或烙铁头海绵擦掉，这样烙铁头上会有一层光滑明亮的焊料，以防止氧化且有助于焊料的焊接操作。 - -接下来进行焊接，先将烙铁头在焊接面上接触一会儿进行加热，然后上焊料焊接两侧。加热焊接面的目的是为了确保焊料可以粘附且不会过早冷却下来。 - -不能让焊料/焊点加热过度，热量会通过接触面烧毁原件（融毁开关外壳等）。并且，由于焊锡中有帮助[“浸润”](https://en.m.wikipedia.org/wiki/Wetting)（即上锡）的助焊剂，加热的越久助焊剂蒸发掉的越多，最终导致焊接点虚焊，除了看起来糟糕外，还有导致电路短路的风险。 - -#### 焊接二极管 - -从左上角的那个开关开始，将二极管放到开关上（用镊子，如果有的话）并纵向放直，有黑线的一端朝向你。让二极管间并联（二极管的阴极不应连接到其它二极管的阳极），二极管的阳极应连接到开关的左引脚上，而弯曲的阴极应朝向右边放置，如图： - -![soldering-diodes-01.png](https://raw.githubusercontent.com/noroadsleft/qmk_images/master/docs/hand_wire/soldering-diodes-01.png) - -在放稳二极管后，拿起焊锡，将其与左轴脚同时接触到电烙铁上 - 在松香的帮助下焊锡会很容易地覆盖在二极管及轴脚上。二极管可能会有些位移，此时你可以抓住二极管另外一端弯折过的引脚，小心地放回到位置上 - 但请留意另一端是会迅速变得烫手的。如果二极管容易乱跑，可以使用尖嘴钳之类的东西在焊接时辅助保持稳固。 - -松香加热时升起的烟有害，注意保护口鼻，不要熏到眼睛或皮肤。 - -焊接到位时，可以将焊点升起的烟吹走以免熏脸，也能帮助焊点快速降温。焊点在冷却后会形成沙哑状（无光泽）的表面，但请注意此时它依旧非常烫，需要几分钟时间的冷却才可以触摸，多吹吹有助于快速冷却。 - -在第一个二极管焊接完毕后，第二个二极管需要焊接轴脚以及上一个二极管弯折的那一端，看起来像这样： - -![soldering-diodes-02.png](https://raw.githubusercontent.com/noroadsleft/qmk_images/master/docs/hand_wire/soldering-diodes-02.png) - -在焊接完毕一整行后，用剪线钳剪掉二极管上方（绕轴脚后多出的部分），以及这一行最后侧多出来的引脚部分。在每一行焊接完毕后都要记得这一步。 - -在你完成了所有的二极管的焊接工作后，最好是逐一测试一下以确保焊接牢固稳定 - 再往后不是不能回头修正，但会越来越困难。 - -#### 纵向上的焊接 - -这一步你有几个可选项需考虑 - 给横向电缆进行绝缘处理是个好主意（毕竟二极管没有绝缘层），但如果你足够小心，横向电缆裸露着也行 - 但仍旧不建议这么做。如果你用的是单芯线，先将外皮整个褪下来再酌情装回去可能是最好的办法，但会因尺寸及材质原因造成操作困难，你可以将线缆上需要焊接到开关轴的部分裸露出来。 - -如果你使用多股线/铜绞线，可能最简单的方案就是用不固定长度的小段电线来纵向连接开关。通过融化掉焊接点的外皮的方式来用一整根线不是不可以，但这里不推荐这样做，这种操作会产生更多的有害烟尘，也会毁掉你的电烙铁。 - -在进行焊接操作前，先预弯折好线缆（如果是单芯线），或至少心中已经规划好焊接路线顺序（特别是你要做的设计是错列的时）。实际上焊接顺序不是特别重要，因为我们是通过焊接方案来确定键映射定义的 - 只要确保一行上的所有按键都有独自的列，且从左到右依次排列。 - -如果你不做任何的绝缘处理，可以将纵向的线升高一些，焊接在轴脚尖端上 - 如果线缆本身足够稳固，不会短路到连接着二极管的横线线缆上。 - -## 连接控制器 - -在矩阵焊接完成后，可以将其焊接到微控制器板上了。 - -将微控制器放在预期的位置上，同时要考虑到安装及外壳对齐问题。须记得USB槽的位置是可以与微控制器分开的，只需使用一小段公对母线接驳下即可。 - -找到微控制器板的引脚定义/文档（[链接](#common-microcontroller-boards)）并将所有的I/O引脚标出来（留意像teensy这种的控制器，模拟I/O引脚可能是数字I/O引脚的两倍），将线缆连接到这些引脚上。 - ----- - -### 针对 Teensy 2.0 的特殊说明 - -Teensy 上的部分引脚有点特殊，像 D6（片上LED），及一些 UART、SPI、I2C或PWM通道，不过只是在你计划着在键盘上还有其它功能设计时才需避免使用。如果你还不是很确定以后会不会增加什么功能上去，引脚应该还是足够充足到可以剩一部分出来的。 - -那些无论在什么控制器上都不应去使用的引脚，有：GND、VCC、AREF以及RST - 其它所有引脚都是可以用且也能在固件中访问的到的。 - ----- - - -将电线切割为控制器到各行/列上某一点距离的长度。可以焊到各行的任意位置上，只需要确保是在二极管之后 - 焊接到二极管前面（轴脚侧）的话该行将无法正常使用。 - -这里用排线的话会显得非常整洁，你也可以考虑如何排布线缆以连接到各行/列的近处。 - -排线 - -在往控制器上焊接电线时，请记住各引脚连接的是哪一行/列，在后续制作固件时我们需要用到这些信息来定义矩阵。 - -在你往下继续以前，请确保控制器已装配到位 - 切掉线缆再重新焊接非常麻烦！ - - -## 一些基础的固件配置 - -至此，在你构建好固件后，键盘就应该能正常工作了。 - -通过 [Keyboard Firmware Builder](https://kbfirmware.com/) 网站可以轻松地创建一个简单的固件。通过 [Keyboard Layout Editor](https://www.keyboard-layout-editor.com) 可以自己制作配列数据，之后就可以导入进来并重新构建矩阵信息（如果你没有在先前的 [设计矩阵](#planning-the-matrix) 完成的话）。 - -继续完成剩下的步骤，在逐一配置完所有的按键后就可以编译下载固件了。其中 .hex 文件可以用来直接刷写到键盘上，而 .zip 包中的源代码可以用来添加高级功能并通过 [构建第一个固件](zh-cn/newbs_building_firmware?id=build-your-firmware) 中详述的方法进行本地构建。 - -Keyboard Firmware Builder提供的源代码是QMK的，但版本是2017年初的。如果要用现今版本的QMK来构建 .zip 中的源代码，需要在打开 .zip 后遵循以下几步： - -1. 解压 `kb` 目录到 `qmk_firmware/keyboards/handwired/`。 -2. 进入解压的 `kb` 目录，转到 `keymaps/default/` 目录下，打开 `keymap.c`。 -3. 找到并删除 `action_get_macro` 代码段： - ``` - const macro_t *action_get_macro(keyrecord_t *record, uint8_t id, uint8_t opt) { - ... - return MACRO_NONE; - } - ``` -4. 保存并关闭 `keymap.c`。 - -## 刷写固件 - -安装 [QMK Toolbox](https://github.com/qmk/qmk_toolbox). - -![QMK Toolbox](https://raw.githubusercontent.com/noroadsleft/qmk_images/master/docs/hand_wire/qmk_toolbox.png "QMK Toolbox 0.0.16 on Windows 8.1") - -在 “Local File” 栏处定位到你新创建的 .hex 文件，在 “MicroController” 中选择你的控制器板（常见型号[这里](#common-microcontroller-boards)有）。 - -插上你的键盘后在QMK Toolbox中点击reset（重置）按钮（如果没有重置按钮，短接一下Reset和接地引脚）再点击“Flash”（刷写）按钮。 - - -## 测试固件 - -可以用 [QMK配置器的键盘测试器](https://config.qmk.fm/#/test)、[Keyboard Tester](https://www.keyboardtester.com/tester.html) 或 [Keyboard Checker](https://keyboardchecker.com/) 进行测试，也可以打开一个文本编辑器并试着输入 - 你应该能成功输入键映射方案中的所有字符。对每个按键进行测试，并记录下不能正常工作的按键。对这些不能正常工作的按键，这里有一个快速排查指引： - -1. 将键盘翻过来，用一段金属物短接一下轴脚 - 这么做可以排除掉需要更换掉的坏轴的可能性。 -2. 检查轴脚上的焊点 - 应该是饱满且完整覆盖的。如果你稍加用力就能将其弄下来，那么就是焊接不到位。 -3. 检查二极管的焊点 - 如果二极管虚焊了，部分行可以使用，但其它的可能就不行了。 -4. 检查连接到各行的焊点 - 如果这里虚焊了，这些行就无法正常使用。 -5. 检查 Teensy 两侧的进/出线的焊点 - 两侧的线缆都必须确保已被良好地焊接。 -6. 检查 `.h` 文件中是否有错误或不当的 `KC_NO` - 如果不确定在哪里，用已有的 k*xy* 变量替换一下。 -7. 检查固件文件确实经过编译且正确刷写到Teensy上了。除非你在终端看到了错误消息，或是刷写时出现了弹框，否则一切应该是正常的。 -8. 使用万用表实测一下，触发开关时是否成功闭合（按下时可以连通电路）。 - -如果你完成了上述所有检查，应当留意有时可能是多种因素共同造成了开关的异常，因此最后将其短路掉来排查问题并没有什么害处。 - -## 即将完成 - -在确认键盘可以正常使用后，如果你用的是独立的控制器模块（非手工构建用），须将其固定好。办法有很多，比如热熔胶、双面胶带、3D打印的盒子、电工胶带等。 - -如果你觉得成就感满满，可以试着增加一些额外的功能，比如 [轴内LED](https://geekhack.org/index.php?topic=94258.0)，[轴内RGB](https://www.reddit.com/r/MechanicalKeyboards/comments/5s1l5u/photoskeyboard_science_i_made_a_handwired_rgb/)，[RGB背光](https://medium.com/@DavidNZ/hand-wired-custom-keyboard-cdd14429c7b3#.7a1ovebsk) 甚至可以是 [OLED显示屏！](https://www.reddit.com/r/olkb/comments/5zy7og/adding_ssd1306_oled_display_to_your_build/) - -固件的潜力非常大 - 阅览 [docs.qmk.fm](https://docs.qmk.fm) 可以看到全部功能的列表，也能深入了解人们是如何使用那些五花八门的键盘的。随时欢迎到 [OLKB subreddit](https://reddit.com/r/olkb) 或 [QMK Discord](https://discord.gg/Uq7gcHh) 上寻求帮助！ - -## 其它指引链接 - -- [matt3o 的分步指引 (BrownFox build)](https://deskthority.net/viewtopic.php?f=7&t=6050) 以及他的 [个人站点](https://matt3o.com/hand-wiring-a-custom-keyboard/) 和 [指导视频](https://www.youtube.com/watch?v=LVzpsjFWPP4) -- [Cribbit：“现代化的手工搭建指南 - 强大，简洁，友好”](https://geekhack.org/index.php?topic=87689.0) -- [Sasha Solomon：“打造我的第一把键盘”](https://medium.com/@sachee/building-my-first-keyboard-and-you-can-too-512c0f8a4c5f) -- [RoastPotatoe： “如何手工搭建Planck键盘”](https://blog.roastpotatoes.co/guide/2015/11/04/how-to-handwire-a-planck/) -- [Masterzen：“手工搭建键盘记录”](https://www.masterzen.fr/2018/12/16/handwired-keyboard-build-log-part-1/) - - -# 遗留内容 - -以前本页内还有其它内容，现在我们已经将他们单独分离出去了。以下的内容是一些重定向链接，以供那些从老链接地址过来的人能找到自己要找的内容。 - -## 序: 键盘矩阵是如何工作的（以及为什么需要二极管） :id=preamble-how-a-keyboard-matrix-works-and-why-we-need-diodes - -* [键盘矩阵是如何工作的](zh-cn/how_a_matrix_works.md) diff --git a/docs/zh-cn/keymap.md b/docs/zh-cn/keymap.md deleted file mode 100644 index 91a5ac0c66..0000000000 --- a/docs/zh-cn/keymap.md +++ /dev/null @@ -1,211 +0,0 @@ -# 键映射总览 - - - -QMK键映射定义在C源文件中，其数据结构上是一个容纳了数组的数组。外层数组容纳了各个层，内层各数组则为层内的键列表。基本所有键盘都通过定义 `LAYOUT()` 宏来创建该两级数组。 - - -## 键映射与配列 :id=keymap-and-layers -在QMK中, **`const uint16_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS]`** 容纳了多个 **层**， 每个**层**下包含了由**16位**的**动作码**所组成的键映射信息。 最多可以定义**32个层**。 - -对于常规键的定义，其**动作码**的高8位皆为0，低8位保存了USB HID中使用的各个键对应的**键码**。 - -不同的层可以同时生效，层的编号从0至31，编号越高的层优先级越高。 -（译注：由于是ascii图，掺杂中文会导致排版错乱，各翻译标注在图下方。下同） - - Keymap: 32 Layers Layer: action code matrix - ----------------- --------------------- - stack of layers array_of_action_code[row][column] - ____________ precedence _______________________ - / / | high / ESC / F1 / F2 / F3 .... - 31 /___________// | /-----/-----/-----/----- - 30 /___________// | / TAB / Q / W / E .... - 29 /___________/ | /-----/-----/-----/----- - : _:_:_:_:_:__ | : /LCtrl/ A / S / D .... - : / : : : : : / | : / : : : : - 2 /___________// | 2 `-------------------------- - 1 /___________// | 1 `-------------------------- - 0 /___________/ V low 0 `-------------------------- -翻译： - -|原文 |译文 | -|--------------------------|-------------| -|Keymap: 32 Layers | 键映射：32个层| -|stack of layers | 层堆栈 | -|precedence | 优先级 | -|high/low | 高/低 | -|layer: action code matrix | 层：动作码矩阵| -|row/column | 行/列 | - -有时，键映射中存储的动作码在一些文档中也被称作键码，主要是由TMK沿袭而来的习惯。 - -### 键映射的层状态 :id=keymap-layer-status - -键映射的层状态由两个32位参数决定： - -* **`default_layer_state`** 指向一个总是可用的键映射层（0-31）（即默认层）。 -* **`layer_state`** 每一位标记对应层的启用/停用状态。 - -通常键映射中的'0'层为 `default_layer（默认层）`，其它层在启动时会被固件置为停用状态，不过这些可以通过 `config.h` 进行配置。当你换了一个按键布局时可用于更改 `default_layer`，比如从Qwerty布局切换到了Colemak布局。 - - Initial state of Keymap Change base layout - ----------------------- ------------------ - - 31 31 - 30 30 - 29 29 - : : - : : ____________ - 2 ____________ 2 / / - 1 / / ,->1 /___________/ - ,->0 /___________/ | 0 - | | - `--- default_layer = 0 `--- default_layer = 1 - layer_state = 0x00000001 layer_state = 0x00000002 -翻译： - -|原文 |译文 | -|-----------------------|-------------| -|Initial state of Keymap| 键映射原始状态| -|Change base layout | 更改了基础层 | - -另外，可以通过修改 `layer_state` 做到其他层对基础层的覆盖，以实现诸如导航键、功能键（F1-F12）、多媒体键等特殊动作。 - - Overlay feature layer - --------------------- bit|status - ____________ ---+------ - 31 / / 31 | 0 - 30 /___________// -----> 30 | 1 - 29 /___________/ -----> 29 | 1 - : : | : - : ____________ : | : - 2 / / 2 | 0 - ,->1 /___________/ -----> 1 | 1 - | 0 0 | 0 - | + - `--- default_layer = 1 | - layer_state = 0x60000002 <-' - - - -### 层优先级及穿透 -须记住**层堆栈中更高的层有着更高的优先级**。固件会从最高的活跃层开始向下找键码，一旦固件在活跃层上找到了一个非 `KC_TRNS`（穿透）键码，就会停止查找，再往下的层级不会被查看。 - - ____________ - / / <--- 较高的层 - / KC_TRNS // - /___________// <--- 较低的层 (KC_A) - /___________/ - - 这个场景中，较高层级中的非穿透键是可用的，如果定义为 `KC_TRNS`（及同等效果的），较低层级的键码 `KC_A` 将被采纳。 - -**注意：** 在层中定义合法的穿透键的方法有： -* `KC_TRANSPARENT` -* `KC_TRNS`（别名） -* `_______`（别名） - -这些键码允许在搜索非穿透键码时可以穿透当前层下落到更低层去。 - -## `keymap.c` 文件解析 - -本例中我们将深入到[Clueboard 66%的一款旧版的默认键映射](https://github.com/qmk/qmk_firmware/blob/ca01d94005f67ec4fa9528353481faa622d949ae/keyboards/clueboard/keymaps/default/keymap.c)方案中去。将该文件在另一个浏览器窗口中打开，以便对照本文进行同步阅览。 - -在一个 `keymap.c` 文件中会有三个你可能会关心的部分： - -* [预定义](#definitions) -* [层/键映射数据结构](#layers-and-keymaps) -* [自定义函数](#custom-functions)，若有的话 - -### 预定义 - -文件头部可以看到： - - #include QMK_KEYBOARD_H - - // Helpful defines - // 译：便捷性的宏定义 - #define GRAVE_MODS (MOD_BIT(KC_LSHIFT)|MOD_BIT(KC_RSHIFT)|MOD_BIT(KC_LGUI)|MOD_BIT(KC_RGUI)|MOD_BIT(KC_LALT)|MOD_BIT(KC_RALT)) - - /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * - * You can use _______ in place for KC_TRNS (transparent) * - * Or you can use XXXXXXX for KC_NO (NOOP) * - * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ - // 译：可以用 _______ 替代 KC_TRNS（穿透），用 XXXXXXX 替代 KC_NO (空操作) - - // Each layer gets a name for readability. - // The underscores don't mean anything - you can - // have a layer called STUFF or any other name. - // Layer names don't all need to be of the same - // length, and you can also skip them entirely - // and just use numbers. - // 译：每一层为了便于识别可以起一个名字，下划线没有实际意义 - 叫STUFF之类的也行的， - // 译：层名不需要都一样长，甚至不定义这些直接用层号也是可以的 - enum layer_names { - _BL, - _FL, - _CL, - }; - -以上是一些便于编写键映射及自定义函数时可用的预定义，`GRAVE_MODS` 后续会用在自定义函数中，之后的 `_BL`, `_FL` 及 `_CL` 便于我们在代码中引用这些层。 - -注：在一些更早的键映射文件中，你可能会发现一些形如 `_______` 或 `XXXXXXX` 的定义，这些可以分别代替 `KC_TRNS` 及 `KC_NO`，这样可以更清楚地分辨出各层中定义了哪些键的键值。现在这些定义是不需要的，因为我们默认已经提供了这些定义。 - -### 层和键映射 - -这个文件中最主要的部分是 `keymaps[]` 定义，这里须列出你的层以及层中的内容。这一部分应该以如下定义起始： - - const uint16_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] = { - -之后是一个LAYOUT()宏组成的列表，一个LAYOUT()下定义了一个层中的键列表，一般你需要至少一个“基础层”（如QWERTY、Dvorak或Colemak），之后是在其之上的多个“功能”层。受限于对层的处理顺序，较低的层无法覆盖在较高的层上。 - -QMK在 `keymaps[][MATRIX_ROWS][MATRIX_COLS]` 中保存着16位的动作码（有些时候也被称作键码），对于与常规键一致的键码，其高字节为0，低字节为USB HID 键盘所使用的键码值。 - -> QMK的前身TMK中使用 `const uint8_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS]` 来存储8位的键码，一些键码被保留用于引用执行 `fn_actions[]` 数组中的特定功能。 - -#### 基础层 - -以下示例是Clueboard的基础层定义： - - /* Keymap _BL: Base Layer (Default Layer) - */ - [_BL] = LAYOUT( - F(0), KC_1, KC_2, KC_3, KC_4, KC_5, KC_6, KC_7, KC_8, KC_9, KC_0, KC_MINS, KC_EQL, KC_GRV, KC_BSPC, KC_PGUP, \ - KC_TAB, KC_Q, KC_W, KC_E, KC_R, KC_T, KC_Y, KC_U, KC_I, KC_O, KC_P, KC_LBRC, KC_RBRC, KC_BSLS, KC_PGDN, \ - KC_CAPS, KC_A, KC_S, KC_D, KC_F, KC_G, KC_H, KC_J, KC_K, KC_L, KC_SCLN, KC_QUOT, KC_NUHS, KC_ENT, \ - KC_LSFT, KC_NUBS, KC_Z, KC_X, KC_C, KC_V, KC_B, KC_N, KC_M, KC_COMM, KC_DOT, KC_SLSH, KC_RO, KC_RSFT, KC_UP, \ - KC_LCTL, KC_LGUI, KC_LALT, KC_MHEN, KC_SPC,KC_SPC, KC_HENK, KC_RALT, KC_RCTL, MO(_FL), KC_LEFT, KC_DOWN, KC_RGHT), - -这里有一些值得留意的地方： - -* 站在C语言源代码的角度看，这只是一个数组，但我们掺杂了大量括号使得每个键可以在视觉上与物理设备对齐。 -* 常规的键盘扫描码以KC_起始，而那些“特殊”键则不是。 -* 最左上的键可以触发自定义函数0（`F(0)`） -* "Fn"键定义为 `MO(_FL)`，当按住该键时会切换到 `_FL` 层。 - -#### 功能覆盖层 - -对于功能层，从代码角度讲与基础层没有任何区别。但在概念上讲，应该将其作为覆盖层而非替代层来定义。对大部分人来讲这个区别不重要，但当你构建越来越复杂的层结构时，其重要性会越来越凸显。 - - [_FL] = LAYOUT( - KC_GRV, KC_F1, KC_F2, KC_F3, KC_F4, KC_F5, KC_F6, KC_F7, KC_F8, KC_F9, KC_F10, KC_F11, KC_F12, _______, KC_DEL, BL_STEP, \ - _______, _______, _______,_______,_______,_______,_______,_______,KC_PSCR,KC_SCRL, KC_PAUS, _______, _______, _______, _______, \ - _______, _______, MO(_CL),_______,_______,_______,_______,_______,_______,_______, _______, _______, _______, _______, \ - _______, _______, _______,_______,_______,_______,_______,_______,_______,_______, _______, _______, _______, _______, KC_PGUP, \ - _______, _______, _______, _______, _______,_______, _______, _______, _______, MO(_FL), KC_HOME, KC_PGDN, KC_END), - -这里值得留意的有： - -* 我们使用 `_______` 定义来替代 `KC_TRNS`， 以便凸显在该层中有变化的那些键。 -* 对于这一层来讲，如果点击的是一个 `_______` 键，实际生效的将是其下的活跃层中的键。 - -# 核心细节 - -在阅读完本节后，你应该掌握了构建自己的键映射的基础能力，更多的资料请参见： - -* [键码](zh-cn/keycodes.md) -* [键映射FAQ](zh-cn/faq_keymap.md) - -我们仍在优化这份文档，如果你有更好的优化建议，请[提交一份issue](https://github.com/qmk/qmk_firmware/issues/new)！ diff --git a/docs/zh-cn/mod_tap.md b/docs/zh-cn/mod_tap.md deleted file mode 100644 index 9dc59bfb79..0000000000 --- a/docs/zh-cn/mod_tap.md +++ /dev/null @@ -1,141 +0,0 @@ -# Mod-Tap - - - -Mod-Tap键 `MT(mod, kc)` 在按住时功能为修饰键，在点击时则是常规键码。举例来讲，可以设计出一个按键，当点击时发送Escape，按下时则作为Control或Shift - -修饰键码及`OSM()`将会被缀以`MOD_`前缀，而非`KC_` - -|修饰键码 |描述 | -|----------|------------------------------------------| -|`MOD_LCTL`|左Control | -|`MOD_LSFT`|左Shift | -|`MOD_LALT`|左Alt | -|`MOD_LGUI`|左GUI (Windows/Command/Meta键) | -|`MOD_RCTL`|右Control | -|`MOD_RSFT`|右Shift | -|`MOD_RALT`|右Alt (AltGr) | -|`MOD_RGUI`|右GUI (Windows/Command/Meta键) | -|`MOD_HYPR`|Hyper (左Control, Shift, Alt 及 GUI同时按下)| -|`MOD_MEH` |Meh (左Control, Shift, 及 Alt同时按下) | - -可以通过逻辑或进行组合： - -```c -MT(MOD_LCTL | MOD_LSFT, KC_ESC) -``` - -此时按住该键将触发左Control及左Shift，点击将发送Escape。 - -为了方便配列，QMK已包含一些常见的Mod-Tap： - -|键 |别名 |描述 | -|------------|-----------------------------------------------------------------|---------------------------------------------| -|`LCTL_T(kc)`|`CTL_T(kc)` |按住时为左Control，点击时为 `kc` | -|`LSFT_T(kc)`|`SFT_T(kc)` |按住时为左Shift，点击时为 `kc` | -|`LALT_T(kc)`|`LOPT_T(kc)`, `ALT_T(kc)`, `OPT_T(kc)` |按住时为左Alt，点击时为 `kc` | -|`LGUI_T(kc)`|`LCMD_T(kc)`, `LWIN_T(kc)`, `GUI_T(kc)`, `CMD_T(kc)`, `WIN_T(kc)`|按住时为左GUI，点击时为 `kc` | -|`RCTL_T(kc)`| |按住时为右 Control，点击时为 `kc` | -|`RSFT_T(kc)`| |按住时为右 Shift，点击时为 `kc` | -|`RALT_T(kc)`|`ROPT_T(kc)`, `ALGR_T(kc)` |按住时为右 Alt，点击时为 `kc` | -|`RGUI_T(kc)`|`RCMD_T(kc)`, `RWIN_T(kc)` |按住时为右 GUI，点击时为 `kc` | -|`LSG_T(kc)` |`SGUI_T(kc)`, `SCMD_T(kc)`, `SWIN_T(kc)` |按住时为左Shift及GUI，点击时为 `kc` | -|`LAG_T(kc)` | |按住时为左Alt及GUI，点击时为 `kc` | -|`RSG_T(kc)` | |按住时为右 Shift及GUI，点击时为 `kc` | -|`RAG_T(kc)` | |按住时为右 Alt及GUI，点击时为 `kc` | -|`LCA_T(kc)` | |按住时为左Control及Alt，点击时为 `kc` | -|`LSA_T(kc)` | |按住时为左Shift及Alt，点击时为 `kc` | -|`RSA_T(kc)` |`SAGR_T(kc)` |按住时为右 Shift及右 Alt (AltGr)，点击时为 `kc` | -|`RCS_T(kc)` | |按住时为右 Control及右 Shift，点击时为 `kc` | -|`LCAG_T(kc)`| |按住时为左Control，Alt及GUI，点击时为 `kc` | -|`RCAG_T(kc)`| |按住时为右 Control，Alt及GUI，点击时为 `kc` | -|`C_S_T(kc)` | |按住时为左Control及Shift，点击时为 `kc` | -|`MEH_T(kc)` | |按住时为左Control，Shift及Alt，点击时为 `kc` | -|`HYPR_T(kc)`|`ALL_T(kc)` |按住时为左Control，Shift，Alt及GUI，点击时为 `kc` - 更多[参见这里](https://brettterpstra.com/2012/12/08/a-useful-caps-lock-key/)| - -## 注意 - -目前 `MT()` 的 `kc`参数限制在[基础键码集](zh-cn/keycodes_basic.md)中，因此不能使用 `LCTL()`，`KC_TILD` 及其它大于 `0xFF` 的键码。原因是，QMK使用16位的键码，其中3位是功能标记，1位标记左右修饰键，4位存储修饰键码，仅剩8位存储键码。当一次Mod-Tap触发时，只要有一个右修饰键被激发，其它的修饰键也都被视为右修饰键，因此无法混搭形如左Control+右Shift的形式，会被视为右Control+右Shift - -若展开讲就比较复杂了。迁移到32位的键码可以很大程度解决这个问题，但同时会招致配列矩阵大小翻倍，也可能会有其它未知问题。若是想用修饰键配合按键，可以考虑使用[Tap Dance/多击键](zh-cn/feature_tap_dance.md#example-5-using-tap-dance-for-advanced-mod-tap-and-layer-tap-keys) - -在使用Windows远程桌面时你可能会发现有些问题，这是因为远程桌面对键码响应过快。若要修复，可以打开远程桌面的“配置”，在“本地资源”页中的键盘属性，调整为“本地计算器”，此时功能即可恢复正常。另一个办法是加大[`TAP_CODE_DELAY`](zh-cn/config_options.md#behaviors-that-can-be-configured)。 - -## 截获Mod-Taps - -### 改变点击功能 - -若要在Mod-Tap中突破基础键码的限制，可以在 `process_record_user` 中实现。如，上档键码 `KC_DQUO` 无法与 `MT()` 共用，因为它实际上是 `LSFT(KC_QUOT)` 的别名，`KC_DQUO` 上的修饰键码会被 `MT()` 覆盖。但可以使用如下代码截获点击，手动发送 `KC_DQUO`： - -```c -bool process_record_user(uint16_t keycode, keyrecord_t *record) { - switch (keycode) { - case LCTL_T(KC_DQUO): - if (record->tap.count && record->event.pressed) { - tap_code16(KC_DQUO); // 点击时发送 KC_DQUO - return false; // 通过返回false阻止对该键的其它处理 - } - break; - } - return true; -} -``` - -### 改变按住功能 - -类似地，同样可以使用这段自定义代码改变按住功能。下面的例子会在 `LT(0, kc)` （layer-tap键无实际意义，因为layer 0默认被激活）按住时对X，C和V键附加剪切，复制和粘贴功能： - -```c -bool process_record_user(uint16_t keycode, keyrecord_t *record) { - switch (keycode) { - case LT(0,KC_X): - if (record->tap.count && record->event.pressed) { - return true; // 返回true来发送常规键码 - } else if (record->event.pressed) { - tap_code16(C(KC_X)); // 截获按住功能来发送Ctrl-X - } - return false; - case LT(0,KC_C): - if (record->tap.count && record->event.pressed) { - return true; // 返回true来发送常规键码 - } else if (record->event.pressed) { - tap_code16(C(KC_C)); // 截获按住功能来发送Ctrl-C - } - return false; - case LT(0,KC_V): - if (record->tap.count && record->event.pressed) { - return true; // 返回true来发送常规键码 - } else if (record->event.pressed) { - tap_code16(C(KC_V)); // 截获按住功能来发送Ctrl-V - } - return false; - } - return true; -} -``` - -### 同时改变点击和按住功能 - -最后一个例子通过 `LT(0,KC_NO)` 实现了点击复制，按住粘贴的功能： - -```c -bool process_record_user(uint16_t keycode, keyrecord_t *record) { - switch (keycode) { - case LT(0,KC_NO): - if (record->tap.count && record->event.pressed) { - tap_code16(C(KC_C)); // 截获点击来发送Ctrl-C - } else if (record->event.pressed) { - tap_code16(C(KC_V)); // 截获按住功能来发送Ctrl-V - } - return false; - } - return true; -} -``` - -## 其它信息 - -在[点按配置](zh-cn/tap_hold.md)中描述了影响Mod-Tap行为的标记。 diff --git a/docs/zh-cn/newbs.md b/docs/zh-cn/newbs.md deleted file mode 100644 index 3be4626211..0000000000 --- a/docs/zh-cn/newbs.md +++ /dev/null @@ -1,29 +0,0 @@ -# QMK入门教程 - - - -就像计算机一样，每把键盘里也有一个处理器，它的职责是在你点击键盘时，检测到这个动作并反馈给计算机。QMK固件即是为了这个目的而设计的一种"软件"，负责检测点击，反馈给电脑。当你构建出一个自定义键映射时，就是在创建一个新的键盘"软件"。 - -QMK的愿景是提供强有力的功能，让不可能的事情变得可能，简单的事情依旧简单。即便是不会编程也可以创建强大的键映射方案。 - -想知道你的键盘是否能运行QMK？如果这个键盘是你自己组建的，那么很可能是可以的。我们[已经支持很多键盘](https://qmk.fm/keyboards/)，所以即便你的键盘不能运行QMK，你也很容易能买到满足要求的键盘。 - -?> **这份指南适合于我吗？**
-编程对你是个困难的话，可以看看我们的[在线GUI页面](zh-cn/newbs_building_firmware_configurator.md)。 - -## 总览 - -这份指南适用于想通过源代码编译出键盘固件的需求。对于程序员，全过程都会感觉很熟悉。教程主要分3部分： - -1. [环境配置](zh-cn/newbs_getting_started.md) -2. [构建第一个固件](zh-cn/newbs_building_firmware.md) -3. [刷写固件](zh-cn/newbs_flashing.md) - -该指南的目的是帮助那些从未编译过软件的人，很多取舍及建议都是基于这个考量。完成一个目标可能有多种方案，我们尽量都去支持，如果你搞不明白你的目标如何实现，可以[向我们寻求帮助](zh-cn/support.md)。 - -## 更多资料 - -这份指南之外，也有一些其它能帮助你学习QMK的资料。我们归纳整理在[大纲](zh-cn/syllabus.md)页面和[学习资料](zh-cn/newbs_learn_more_resources.md)页面 diff --git a/docs/zh-cn/newbs_building_firmware.md b/docs/zh-cn/newbs_building_firmware.md deleted file mode 100644 index 681c7ba8f6..0000000000 --- a/docs/zh-cn/newbs_building_firmware.md +++ /dev/null @@ -1,68 +0,0 @@ -# 构建第一个固件 - - - -现在您已经准备好了构建环境，就可以开始构建自定义固件了。在这节指南中，我们将在3个程序中开展工作——文件管理器、文本编辑器和终端。在做出心满意足的固件前，请不要关闭它们。 -## 新建键映射 - -也许你会考虑从默认键映射复制一份来开始，如果你遵循编译环境配置指南到了最后，那么使用QMK命令行可以简单地做到： - - qmk new-keymap - -如果你的环境没有那样配置，或者你有多个键盘要做，可以指定键盘名： - - qmk new-keymap -kb - -检查命令行输出，应该类似于： - - Ψ keymap directory created in: /home/me/qmk_firmware/keyboards/clueboard/66/rev3/keymaps/ - -上面就是创建出的新 `keymap.c` 文件的路径。 - -## 使用趁手的编辑器打开 `keymap.c` - -在编辑器中打开 `keymap.c`，可以看到控制键盘所有功能的关键结构。`keymap.c` 文件头部的一些define和enum定义能让代码容易阅读一些，继续往下会找到这么一行： - - const uint16_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] = { - -这行是所有层定义的起点，往下能看到有 `LAYOUT` 的行，都是一个层定义的起始，其下方为该层的组成定义。 - -!> 编辑时请非常留意不要错误增加/删除了逗号分隔符，否则很可能无法编译固件，且很难排查是哪里的逗号不对。 - -## 按照个人喜好设计层级 - -这一步的目标完全取决于你，既可以去修复一个你不爽的问题，也可以完全重写一个新的。你可以删除不需要的层，或是增加层到32个的上限，QMK功能丰富，可以在左边的导航栏中寻找“使用QMK”一节，浏览完整的功能信息，也可以看看这些比较简单的： - -* [基础键码](zh-cn/keycodes_basic.md) -* [量子键码](zh-cn/quantum_keycodes.md) -* [Grave/Escape](zh-cn/feature_grave_esc.md) -* [鼠标键](zh-cn/feature_mouse_keys.md) - -?> 你大概理解了键映射如何工作的话，留心尽量少去做改动，改动越多出了问题越难排查。 - -## 构建固件 :id=build-your-firmware - -对键映射做完修改后，该编译固件了。回到终端中使用编译命令： - - qmk compile - -如果没有完整地配置环境，或你有多个目标键盘，可以指定键盘及键映射： - - qmk compile -kb -km - -编译完成后，会输出详尽的编译产出文件信息，其末尾应该看起来像这样： - -``` -Linking: .build/planck_rev5_default.elf [OK] -Creating load file for flashing: .build/planck_rev5_default.hex [OK] -Copying planck_rev5_default.hex to qmk_firmware folder [OK] -Checking file size of planck_rev5_default.hex [OK] - * The firmware size is fine - 27312/28672 (95%, 1360 bytes free) -``` - -## 刷写固件 - -参阅[刷写固件](zh-cn/newbs_flashing.md)以了解如何将固件写入键盘主控。 diff --git a/docs/zh-cn/newbs_building_firmware_configurator.md b/docs/zh-cn/newbs_building_firmware_configurator.md deleted file mode 100644 index c4cd114318..0000000000 --- a/docs/zh-cn/newbs_building_firmware_configurator.md +++ /dev/null @@ -1,18 +0,0 @@ -# QMK配置器 - - - -[![QMK配置器截图](https://i.imgur.com/anw9cOL.png)](https://config.qmk.fm/) - -[QMK配置器](https://config.qmk.fm)是一个可用于生成`.hex`和`.bin`格式的QMK固件文件的在线交互页面。 - -这里有[视频教程](https://www.youtube.com/watch?v=-imgglzDMdY). 很多人给我们反馈该视频包含了足够多的知识可以用来开始编写自己的键盘程序。 - -QMK配置器在Chrome及Firefox中工作良好。 - -!> **来自于第三方工具的文件数据无法保证与QMK兼容，如Keyboard Layout Editor(KLE)或kbfirmware，请不要加载或导入这些文件。QMK配置器是一个独立的工具。** - -更多信息请参见[QMK配置器: 入门](zh-cn/configurator_step_by_step.md)。 diff --git a/docs/zh-cn/newbs_flashing.md b/docs/zh-cn/newbs_flashing.md deleted file mode 100644 index 9ffb792793..0000000000 --- a/docs/zh-cn/newbs_flashing.md +++ /dev/null @@ -1,124 +0,0 @@ -# 刷写键盘固件 - - - -在自定义的固件文件构建出来后，可以刷写到键盘中了。 - -## 将键盘调至DFU（Bootloader）模式 - -在你将自定义固件刷写到键盘前，键盘必须处于特有的刷写模式下。此时，键盘会处于不会响应点击等常规操作的状态，并且一定留意不要打断刷写工作，刷写固件过程中不可以把键盘拔下来。 - -不同的键盘进入刷写模式的方法都是不同的，如果你的键盘运行的是QMK、TMK或PS2AVRGB(Bootmapper客户端)且没有写明特别的操作说明的话，可以依次尝试以下操作： - -* 按住两边的Shift键，点击Pause -* 按住两边的Shift键，点击B -* 拔出键盘，同时按住“空格”键及B键，再插上键盘，等两秒后松开 -* 拔出键盘，按住键盘左上或左下的按键（一般来讲是Escape或左Control），在插上键盘 -* 按重置按键（Reset），一般在PCB背面 -* 在PCB上寻找导出的 `RESET` 和 `GND` 引脚，在插电的情况下短接一下 - -如果上面的方法没有用，且键盘主板上的芯片是 `STM32` 系列，情况要复杂一些。通常在[Discord](https://discord.gg/Uq7gcHh)上寻求帮助是最好的办法，并且很可能需要你提供一些键盘主板的照片 —— 所以如果你能提前准备好，我们沟通起来会快得多。 - -如果没有遇到什么问题，你会在QMK工具箱的输出信息里找到类似下面的黄色文字的信息： - -``` -*** DFU device connected: Atmel Corp. ATmega32U4 (03EB:2FF4:0000) -``` - -已进入bootloader状态的设备也可以在设备管理器、系统信息或 `lsusb` 中看到。 - -## 使用QMK工具箱刷写固件 - -使用[QMK工具箱](https://github.com/qmk/qmk_toolbox/releases)刷写固件是最简单的方案。 - -然而该工具箱仅支持Windows及macOS，如果你在使用Linux环境（或是希望用命令行刷写固件），请参阅[在命令行中刷写固件](#使用命令行刷写固件)一节。 - -### 加载固件到QMK工具箱 - -打开QMK工具箱，在Finder或文件管理器中找到固件文件。键盘固件文件名后缀通常是 `.hex` 或 `.bin`，QMK工具箱会尝试将正确的文件拷贝到qmk根目录 `qmk_firmware` 中。 - -在Windows或macOS上，使用下面的指令可以快速打开当前目录。 - - - -#### ** Windows ** - -``` -start . -``` - -#### ** macOS ** - -``` -open . -``` - - - -固件文件的文件名格式为： - -``` -_.{bin,hex} -<键盘名>_<键映射名>.{bin,hex} -``` - -例如， `planck/rev5` 的 `default` 键映射对应的文件名是： - -``` -planck_rev5_default.hex -``` - -找到固件文件后，将其拖拽至QMK工具箱的"Local file"框，或点击“Open”并定位至固件文件。 - -### 刷写到键盘 - -点击QMK工具箱的`Flash`，将看到如下输出信息： - -``` -*** DFU device connected: Atmel Corp. ATmega32U4 (03EB:2FF4:0000) -*** Attempting to flash, please don't remove device ->>> dfu-programmer.exe atmega32u4 erase --force - Erasing flash... Success - Checking memory from 0x0 to 0x6FFF... Empty. ->>> dfu-programmer.exe atmega32u4 flash "D:\Git\qmk_firmware\gh60_satan_default.hex" - Checking memory from 0x0 to 0x3F7F... Empty. - 0% 100% Programming 0x3F80 bytes... - [>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>] Success - 0% 100% Reading 0x7000 bytes... - [>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>] Success - Validating... Success - 0x3F80 bytes written into 0x7000 bytes memory (56.70%). ->>> dfu-programmer.exe atmega32u4 reset - -*** DFU device disconnected: Atmel Corp: ATmega32U4 (03EB:2FF4:0000) -``` - -## 使用命令行刷写固件 - -现在已经没有以前那样繁琐了，在编译固件后需要刷写时，打开终端输入如下刷写指令： - - qmk flash - -如果未通过命令行工具配置过键盘/键映射名，或有多个目标键盘，可以指定目标键盘和键映射： - - qmk flash -kb <键盘名> -km <键映射名> - -QMK将核查键盘配置，并尝试使用合适的bootloader进行刷写。也就是说，你不用关注应该使用什么bootloader，这些重活儿让qmk指令去承担就好。 - -但是，先决条件是键盘配置中已经设置了bootloader，如果未配置，或你的键盘板子不支持配置的刷写方式，你会看到这些错误信息： - - WARNING: This board's bootloader is not specified or is not supported by the ":flash" target at this time. - -此时，只能退回到需要指定bootloader的方法，具体参见[刷写固件](zh-cn/flashing.md)指引。 - -## 上手试试键盘吧！ - -恭喜你，你的自定义固件成功刷写到键盘中了，快去试试吧！ - -运气不差的话一切都会是正常工作的，如果不幸遇到了些问题，有一些参考方案可以帮助你排查问题原因。 -键盘测试就简单直接了，依次按一下各按键，检查它是不是发送了正确的输入。可以使用[QMK配置器](https://config.qmk.fm/#/test/)中的测试模式进行测试，即便你的键盘并不运行QMK。 - -还是不行吗？参阅一下FAQ或[通过Discord和我们聊聊](https://discord.gg/Uq7gcHh)吧。 diff --git a/docs/zh-cn/newbs_getting_started.md b/docs/zh-cn/newbs_getting_started.md deleted file mode 100644 index 7ca9871aa7..0000000000 --- a/docs/zh-cn/newbs_getting_started.md +++ /dev/null @@ -1,208 +0,0 @@ -# 配置环境 - - - -构建键映射前，有一些必须安装配置的构建工具，但无论你要编译多少个固件，这一步只需要做一次。 - -## 1. 必备工具 - -首先需要确保一些基本的软件配备。 - -* [文本编辑器](zh-cn/newbs_learn_more_resources.md#text-editor-resources) - * 你需要至少一个能编辑常规文本的软件。系统自带的编辑器通常不会如实保存（会做一些额外的处理，如回车），所以选择编辑器时需要留意。 -* [QMK工具箱(可选)](https://github.com/qmk/qmk_toolbox) - * 在Windows及macOS上可用的图形程序，用于编辑及调试你的键盘 - -?> 如果你没有Linux/Unix命令行使用经验，有些基本概念需要先学习一下。[这些资料](zh-cn/newbs_learn_more_resources.md#command-line-resources)是个使用QMK很好的参考。 - -## 2. 准备构建环境 :id=set-up-your-environment - -我们已经尽力让QMK易于配置了，你只要准备好Linux或Unix环境，剩余的交给QMK来安装。 - - - -### ** Windows ** - -QMK有维护一套基于MSYS2的软件包，所有命令行程序和依赖都是齐备的。通过 `QMK MSYS` 快捷命令可以快速启动开发环境。 - -#### 依赖项 - -需安装[QMK MSYS](https://msys.qmk.fm/)，最新版在[这里](https://github.com/qmk/qmk_distro_msys/releases/latest)。 - -此外，如果想自行安装MSYS2环境，下面给出了具体的步骤。 - -
- 自行安装 - -?> 若决定使用 `QMK MSYS`，请跳过此节. - -#### 依赖项 - -遵循 https://www.msys2.org 上的指引，安装MSYS2、Git和Python。 - -在MSYS2安装完毕后，关闭所有的MSYS终端，启动新的MinGW 64-bit终端。 - -!> **注意:** MinGW 64-bit 终端*不同于*安装包最后打开的MSYS终端，窗口标题应当是紫色的"MINGW64"而不是"MSYS"。具体的差异可以[参考这里](https://www.msys2.org/wiki/MSYS2-introduction/#subsystems)。 - -执行如下命令： - - pacman --needed --noconfirm --disable-download-timeout -S git mingw-w64-x86_64-toolchain mingw-w64-x86_64-python3-pip - -#### 安装 - -安装QMK命令行程序: - - python3 -m pip install qmk - -
- -### ** macOS ** - -QMK维护了一套Homebrew tap和formula以用于自动安装命令行程序及依赖项。 - -#### 依赖项 - -须先安装Homebrew，可以参考 https://brew.sh - -#### 安装 - -安装QMK命令行程序： - - brew install qmk/qmk/qmk - -### ** Linux/WSL ** - -?> **WSL用户注意**: 默认情况下，QMK仓库会被clone到home目录下，如果想指定其它目录，务必留意要放在WSL文件系统中（即，非 `/mnt` 目录下），否则文件读写会[非常慢](https://github.com/microsoft/WSL/issues/4197). - -#### 依赖项 - -须安装Git及Python，通常你肯定已经有了，如果确实没有，请使用下面的方法尝试安装： - -* Debian / Ubuntu / Devuan: `sudo apt install -y git python3-pip` -* Fedora / Red Hat / CentOS: `sudo yum -y install git python3-pip` -* Arch / Manjaro: `sudo pacman --needed --noconfirm -S git python-pip libffi` -* Void: `sudo xbps-install -y git python3-pip` -* Solus: `sudo eopkg -y install git python3` -* Sabayon: `sudo equo install dev-vcs/git dev-python/pip` -* Gentoo: `sudo emerge dev-vcs/git dev-python/pip` - -#### 安装 - -安装QMK命令行程序： - - python3 -m pip install --user qmk - -#### 社区提供的包 - -有一些社区成员提供的包，可能版本会有落后或是功能不全的问题，如果你遇到了什么问题，请联系维护它的社区成员。 - -Arch系环境下可以使用官方源安装命令行程序（在写这份文档时，有些依赖项被标记为可选的，其实不是）： - - sudo pacman -S qmk - -也可以尝试AUR的 `qmk-git`： - - yay -S qmk-git - -### ** FreeBSD ** - -#### 安装 - -使用FreeBSD包安装QMK命令行程序： - - pkg install -g "py*-qmk" - -请遵循安装后输出的指引操作进行配置（使用 `pkg info -Dg "py*-qmk"` 可以显示这份指引）。 - - - -## 3. 执行QMK配置 :id=set-up-qmk -*译注：由于setup过程中需要从github clone依赖项，请先确保科学上网* - - - -### ** Windows ** - -安装QMK后，执行： - - qmk setup - -通常所有的询问回复 `y` 就行了。 - -### ** macOS ** - -安装QMK后，执行： - - qmk setup - -通常所有的询问回复 `y` 就行了。 - -### ** Linux/WSL ** - -安装QMK后，执行： - - qmk setup - -通常所有的询问回复 `y` 就行了。 - -?>**Debian及Ubuntu系环境须留意**: -也许你会遇到 `bash: qmk: command not found` 错误，主要是因为Debian上的Bash 4.4版本引入的一个[bug](https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=839155)，`$HOME/.local/bin` 被从PATH环境变量中删除了，后续版本中这个问题已被修复。 -然而Ubuntu很挫地再次引入了这个bug[且没有修复](https://bugs.launchpad.net/ubuntu/+source/bash/+bug/1588562)。 -不过修复也很容易，在当前账户中执行：`echo 'PATH="$HOME/.local/bin:$PATH"' >> $HOME/.bashrc && source $HOME/.bashrc` - -### ** FreeBSD ** - -安装QMK后，执行： - - qmk setup - -通常所有的询问回复 `y` 就行了。 - - - -?> QMK的home目录可以在安装时通过 `qmk setup -H ` 来指定，安装后也可以通过[命令行程序来配置](zh-cn/cli_configuration.md?id=single-key-example)`user.qmk_home`变量，可以通过 `qmk setup --help` 查看所有可用配置。 - -?> 若你熟悉GitHub，[推荐阅读这份指引](zh-cn/getting_started_github.md)通过 `qmk setup /qmk_firmware` 来clone你自己的fork。如果你看不懂这一段啥意思，忽略就是了。 - -## 4. 测试你的构建环境 - -QMK构建环境搭建完成，可以尝试构建一个键盘固件。使用以下指令格式，先试试编译默认提供的键映射： - - qmk compile -kb -km default - -例如，要构建一个Clueboard 66%，就这样执行： - - qmk compile -kb clueboard/66/rev3 -km 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) -``` - -## 5. 配置你的构建环境 (可选的) - -通过对默认配置的简单调整，QMK用起来会更有趣一些，我们来试试！ - -大部分QMK新手手头只有一把键盘，可以通过 `qmk config` 命令将它设置为默认键盘，例如你想将 `clueboard/66/rev4` 设置为默认，可以这样： - - qmk config user.keyboard=clueboard/66/rev4 - -也可以调整默认的键映射名称。社区上大家常用自己的GitHub用户名，这也是我们推荐的做法。 - - qmk config user.keymap= - -完成后，这些配置就不用管了，编译键盘固件就可以直接这样执行： - - qmk compile - -# 制作你自己的键映射 - -万事俱备啦！请继续阅读[构建第一个固件](zh-cn/newbs_building_firmware.md). diff --git a/docs/zh-cn/newbs_git_best_practices.md b/docs/zh-cn/newbs_git_best_practices.md deleted file mode 100644 index af3359dfc5..0000000000 --- a/docs/zh-cn/newbs_git_best_practices.md +++ /dev/null @@ -1,23 +0,0 @@ -# QMK所采用的Git最佳实践 - - - -*译者注：对于git相关的部分，除广为接受的名词外，会尽量保留git命令及各种术语的英文版本，部分名词及关键部分会附带中文翻译* - -## 或者讲，"怎么才能不害怕并喜欢上Git" - -本节旨在以最佳方式指导新手在为QMK做贡献时获得流畅的体验。我们将进行一次完整的QMK贡献操作流程，并在部分环节中详细讲述几种便捷的方法，之后我们会故意搞砸一些东西，并教导你如何回到正轨。 - -该章节做了如下假设： - -1. 你已有Github账号且已[fork了qmk_firmware仓库](zh-cn/getting_started_github.md)到你的账号下。 -2. 已完成了[构建环境](zh-cn/newbs_getting_started.md#set-up-your-environment)及[QMK](zh-cn/newbs_getting_started.md#set-up-qmk)配置。 - ---- - -- 第一节：[在你Fork的主干上：频繁更新，不要提交](zh-cn/newbs_git_using_your_master_branch.md) -- 第二节：[解决合并冲突](zh-cn/newbs_git_resolving_merge_conflicts.md) -- 第三节：[重新同步一个脱离同步状态的Git分支](zh-cn/newbs_git_resynchronize_a_branch.md) diff --git a/docs/zh-cn/newbs_git_resolving_merge_conflicts.md b/docs/zh-cn/newbs_git_resolving_merge_conflicts.md deleted file mode 100644 index bd9702a488..0000000000 --- a/docs/zh-cn/newbs_git_resolving_merge_conflicts.md +++ /dev/null @@ -1,86 +0,0 @@ -# 解决合并冲突 - - - -有时在你致力于一个较长周期才能完成的分支时，其它人提交的变更会与你提交的pull request中的变更发生冲突。我们将这种多个人编辑同一个模块同一个文件时产生的场景叫做 *合并冲突* - -?> 本文中的场景基于[在你Fork的主干上：频繁更新，不要提交](zh-cn/newbs_git_using_your_master_branch.md)一文。如果你对那篇文章不熟悉，请先阅读它，再回来继续。 - -## 变基/衍合（rebase） - - -Git的*变基*操作会将提交历史中的提交节点摘除并回滚，然后统一提交到一个新节点上。在解决合并冲突时，可以通过对当前分支进行变基，来获取从分支拉取到当前时刻的所有变更。 - -从执行如下命令开始： - -``` -git fetch upstream -git rev-list --left-right --count HEAD...upstram/master -``` - -此处输入的 `git rev-list` 命令可以得到当前分支与QMK主干分支间的提交数量差。而先执行 `git fetch` 是为了确保我们有上游仓库（upstream repo）的最新状态。`git rev-list` 命令会返回两个数字： - -``` -$ git rev-list --left-right --count HEAD...upstream/master -7 35 -``` - -第一个数字为当前分支自创建后新增的提交数量。第二个数字为当前分支创建后在 `upstream/master` 上的提交数量，而这部分就是我们当前分支上缺失的提交记录。 - -在我们了解了当前分支以及上游仓库的状态后，可以发起变基操作了： - -``` -git rebase upstream/master -``` - -这样可以让Git回滚该分支的提交，然后基于QMK的主干版本重新应用这些提交。 - -*译注：以下内容在中文Git下大同小异，且仅作为示例，不进行翻译* -``` -$ 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 ", 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". -``` - -以上内容是在告诉我们有合并冲突存在，并给出了冲突所在的文件名。在编辑器中打开该文件，可以在某处发现类似如下形式的内容： - -``` -<<<<<<< HEAD -

For help with any issues, email us at support@webhost.us.

-======= -

Need help? Email support@webhost.us.

->>>>>>> Commit #1 -``` - -`<<<<<<< HEAD` 标记了合并冲突的起始行，直至 `>>>>>>> Commit #1` 标记的结束行，中间通过 `=======` 分隔开冲突双方。其中 `HEAD` 部分为QMK主干上的版本，标记了提交日志的部分为当前分支的本地提交。 - -由于Git存储的是*文件差异部分*而非整个文件，所以当Git无法在文件中找到一个变更发生前的内容时，就无法知道如何去进行文件变更，重新编辑一下可以解决问题。在更改完成后，保存文件。 - -``` -

Need help? Email support@webhost.us.

-``` - -之后，执行： - -``` -git add conflicting_file_1.txt -git rebase --continue -``` - -Git即会记录对文件冲突做出的变更，并继续处理剩余的提交，直至全部完成。 diff --git a/docs/zh-cn/newbs_git_resynchronize_a_branch.md b/docs/zh-cn/newbs_git_resynchronize_a_branch.md deleted file mode 100644 index 3f38138f69..0000000000 --- a/docs/zh-cn/newbs_git_resynchronize_a_branch.md +++ /dev/null @@ -1,76 +0,0 @@ -# 重新同步已失去同步状态的Git分支 - - - -假设你在自己的 `master` 分支之上有提交，并且想和QMK仓库进行同步，可以通过 `git pull` 拉取QMK的 `master` 分支到你的库，但同时Github也会提醒你当前分支相比 `qmk:master` 有几个领先的提交，会在你向QMK发起pr时造成麻烦。 - -?> 本文中的场景基于[在你Fork的主干上：频繁更新，不要提交](zh-cn/newbs_git_using_your_master_branch.md)一文。如果你对那篇文章不熟悉，请先阅读它，再回来继续。 - -## 备份你在自己的主干分支上的所有变更（可选） - -不会有人想把有用的成果弄丢的。如果你想将你的 `master` 分支上的变更另存一份，简便的方法是直接创建一个当前“脏” `master` 分支的副本： - -``` -git branch old_master master -``` - -现在 `master` 分支拥有了一个副本分支 `old_master`。 - -## 重新同步分支 - -现在可以重新同步 `master` 分支了，这里，我们将QMK仓库设置为Git的远程仓库。通过执行 `git remote -v` 可以确认远程仓库配置，输出信息应类似于： - -``` -QMKuser ~/qmk_firmware (master) -$ git remote -v -origin https://github.com//qmk_firmware.git (fetch) -origin https://github.com//qmk_firmware.git (push) -upstream https://github.com/qmk/qmk_firmware.git (fetch) -upstream https://github.com/qmk/qmk_firmware.git (push) -``` - -如果你只能看到一个仓库： - -``` -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) -``` - -通过如下命令添加新的远程仓库： - -``` -git remote add upstream https://github.com/qmk/qmk_firmware.git -``` - -然后，重新将 `origin` 远程仓库设置为自己的fork： - -``` -git remote set-url origin https://github.com//qmk_firmware.git -``` - -在两个远程仓库配置完毕后，需要从QMK的 upstream 仓库中获取到更新，执行： - -``` -git fetch upstream -``` - -此时，重新同步你的分支到QMK的版本： - -``` -git reset --hard upstream/master -``` - -以上操作会更新你的本地仓库，而你的Github远程仓库仍然处于未同步状态，通过推送，可以让其进入已同步状态。可以通过如下命令来指引Git强行覆盖掉那些仅在你远程仓库中存在的提交： - -``` -git push --force-with-lease -``` - -!> **不要**在其它使用者也会提交的分支上执行 `git push --force-with-lease`，否则会覆盖掉他人的提交。 - -此时你的Github fork，本地文件副本，以及QMK仓库就是一致的了。之后再进行变更（[在分支上！](zh-cn/newbs_git_using_your_master_branch.md#making-changes)）和提交。 diff --git a/docs/zh-cn/newbs_git_using_your_master_branch.md b/docs/zh-cn/newbs_git_using_your_master_branch.md deleted file mode 100644 index 2a83fc2139..0000000000 --- a/docs/zh-cn/newbs_git_using_your_master_branch.md +++ /dev/null @@ -1,79 +0,0 @@ -# 在你Fork的主干上：频繁更新，不要提交 - - - -我们强烈推荐所有QMK开发者，无论在哪里做什么改动，频繁更新你的 `master` 分支，但***不要***在其上提交。相对地，将你所有的改动提交到开发分支上并提交一个pull request。 - -为了减少冲突 — 多人同时编辑同一个文件 — 保持你的 `master` 分支更新到最新，并在新创建的分支上进行开发。 - -## 更新master分支 - -为了保持 `master` 更新到最新，推荐将QMK固件仓库（"repo"）设置为git远程仓库。打开Git命令行界面并键入： - -``` -git remote add upstream https://github.com/qmk/qmk_firmware.git -``` - -?> 名称 `upstream` 部分可以任意，这里给的是常用的；你可以将QMK远程仓库名称改成你想要的。Git的 `remote` 命令语法为 `git remote add `, `` 是远程仓库的简写名称，这个名称可以在很多Git命令中使用，包括但不限于 `fetch`，`pull` 及 `push`，以指定目标远程仓库。 - -要验证是否添加成功，可以执行 `git remote -v`，输出应该类似于： - -``` -$ git remote -v -origin https://github.com//qmk_firmware.git (fetch) -origin https://github.com//qmk_firmware.git (push) -upstream https://github.com/qmk/qmk_firmware.git (fetch) -upstream https://github.com/qmk/qmk_firmware.git (push) -``` - -在以上操作完成后，可以通过执行 `git fetch upstream` 来检查仓库是否有更新。该命令从QMK仓库拉取的分支（branches）及标签（tags） — 统称为“refs（引用）” —现在也被称作 `upstream`（上游）。此时我们可以比对自己fork版本的 `origin` 与QMK维护的分支的差异了。 - -要更新你的fork的master分支，执行以下指令，每一行结束都需要按回车： - -``` -git checkout master -git fetch upstream -git pull upstream master -git push origin master -``` - -以上操作会切换到 `master` 分支，从QMK仓库拉取refs，下载QMK `master` 分支的当前版本，并上传至你的fork中。 - -## 进行编辑 :id=making-changes - -要进行编辑，通过如下命令创建一个新分支： - -``` -git checkout -b dev_branch -git push --set-upstream origin dev_branch -``` - -以上操作会创建 `dev_branch` 新分支，检出（check out）并保存到你的fork中。`--set-upstream` 参数用于告知git使用你的fork仓库来处理 `dev_branch` 分支下的 `git push` 及 `git pull` 命令，且仅需要在第一次执行push命令时指定，之后再次执行 `git push` 或是 `git pull` 都无需加入该参数了。 - -?> 在 `git push` 时，可以使用 `-u` 替代 `--set-upstram` — `-u` 为 `--set-upsream` 参数的别名。 - -你可以任意命名该分支，但仍建议对分支起一个可以描述将在该分支下要做的工作的名称。 - -默认情况下 `git checkout -b` 会基于你当前检出的分支作为新分支的基准。可以在后面追加已存在但未检出的分支名来指定新分支的基准： - -``` -git checkout -b dev_branch master -``` - -此时你便有了一个开发用分支，可以打开编辑器并进行你期望的变更了。通常推荐提交大量的小规模提交（commit），这样在需要时会更容易地定位并回滚造成问题的提交。若要提交更改，编辑并保存要更新的文件，并将其添加到*暂存区（staged area）*，然后提交到分支中： - -``` -git add path/to/updated_file -git commit -m "My commit message." -``` - -`git add` 会将更改后的文件放到Git的*暂存区*，也称作Git的“装载区”。这里留存着即将通过 `git commit` 所提交并保存到仓库中的变更。请使用确切的描述来填写提交日志，以便于快速了解改动内容。 - -?> 如果更改了多个文件，可以通过 `git add -- path/to/file1 path/to/file2 ...` 来添加所有项目。 - -## 发布变更 - -最后一步为上传你的变更到你的fork中。通过执行 `git push`，Git将发布 `dev_branch` 分支的所有变更至你的fork中。 diff --git a/docs/zh-cn/newbs_learn_more_resources.md b/docs/zh-cn/newbs_learn_more_resources.md deleted file mode 100644 index 20fed1f358..0000000000 --- a/docs/zh-cn/newbs_learn_more_resources.md +++ /dev/null @@ -1,35 +0,0 @@ -# 学习资源 - - - -这些资源旨在让QMK社区的新成员更了解新手教程中的基础知识。 - -*译注：以下资料超出了QMK核心概念范畴，恕不另行翻译* - -### QMK参考资料 - -* [Thomas Baart's QMK Basics Blog](https://thomasbaart.nl/category/mechanical-keyboards/firmware/qmk/qmk-basics/) – 一个站在新人视角，探讨如何使用QMK固件的个人博客。 - -### 命令行操作参考资料 :id=command-line-resources - -* [Good General Tutorial on Command Line](https://www.codecademy.com/learn/learn-the-command-line) -* [Must Know Linux Commands](https://www.guru99.com/must-know-linux-commands.html)
-* [Some Basic Unix Commands](https://www.tjhsst.edu/~dhyatt/superap/unixcmd.html) - -### 文本编辑器相关参考资料 :id=text-editor-resources - -对文本编辑器有选择困难？ -* [a great introduction to the subject](https://learntocodewith.me/programming/basics/text-editors/) - -更适用于编程的文本编辑器： -* [Sublime Text](https://www.sublimetext.com/) -* [VS Code](https://code.visualstudio.com/) - -### Git参考资料 - -* [Great General Tutorial](https://www.codecademy.com/learn/learn-git) -* [Flight Rules For Git](https://github.com/k88hudson/git-flight-rules) -* [Git Game To Learn From Examples](https://learngitbranching.js.org/) diff --git a/docs/zh-cn/newbs_testing_debugging.md b/docs/zh-cn/newbs_testing_debugging.md deleted file mode 100644 index 0016d3b816..0000000000 --- a/docs/zh-cn/newbs_testing_debugging.md +++ /dev/null @@ -1,14 +0,0 @@ -# 测试和调试 - - -## 测试 - -[已移到这里](zh-cn/faq_misc.md#testing) - -## 调试 :id=debugging - -[已移到这里](zh-cn/faq_debug.md#debugging) - diff --git a/docs/zh-cn/other_eclipse.md b/docs/zh-cn/other_eclipse.md deleted file mode 100644 index d0783c2070..0000000000 --- a/docs/zh-cn/other_eclipse.md +++ /dev/null @@ -1,90 +0,0 @@ -# 在Eclipse中设置QMK开发环境 - - - - -[Eclipse][1]是一款广泛用于Java开发的[集成开发环境](https://en.wikipedia.org/wiki/Integrated_development_environment)（IDE），但有着强大的插件体系允许自定义开发其它语言及用途。 - -相对于使用普通的文本编辑器，使用形如Eclipse这样的IDE有着诸多好处，例如： -* 智能代码补全 -* 快速代码跳转 -* 重构工具 -* 构建自动化（无需使用命令行） -* 图形化交互的GIT -* 静态代码分析 -* 以及大量其它工具，如调试器，代码格式化，显示调用链等。 - -本文专注于阐述如何将Eclipse配置为AVR软件开发环境，并用于基于QMK代码的开发工作。 - -注意，在本文编写时，仅在Ubuntu 16.04环境中进行过验证。 - -# 需求 -## 构建环境 -在开始之前，你需要确保遵循了新手教程中的[新手指引](zh-cn/newbs_getting_started.md)一节。通常，此时你应该具备了[通过 `qmk complile` 命令](zh-cn/newbs_building_firmware.md#build-your-firmware)构建固件文件的能力。 - -## Java -Eclipse为Java程序，因此需要安装Java 8或更高版本才能运行。你可以选择JRE或JDK，后者在进行Java开发时需要用到。 - -# 安装Eclipse及插件 -Eclipse有[多种可选安装方式](https://www.eclipse.org/downloads/eclipse-packages/)，取决于你的使用目标。目前没有完备的AVR开发栈安装包，所以我们需要从Eclipse CDT（C/C++ 开发工具环境）开始并安装对应的插件。 - -## 下载安装Eclipse CDT -如果系统中已安装了Eclipse CDT，可以跳过本步骤。同时，为了确保版本支持情况，我们推荐保持其更新至最新版。 - -如果你已安装了Eclipse包，通常也可以[在上面再安装CDT插件](https://eclipse.org/cdt/downloads.php)。但是可能更好的方案是重新全新安装一下，以确保环境轻量，以及防止已安装的工具对后续的工程开发工作产生干扰。 - -安装很简单：遵循[Eclipse安装5步走](https://eclipse.org/downloads/eclipse-packages/?show_instructions=TRUE)，并在第三步选择 **用于C/C++开发者的Eclipse IDE（Eclipse IDE for C/C++ Developers）**。 - -此外，也可以选择直接[下载 用于C/C++开发者的Eclipse IDE](https://www.eclipse.org/downloads/eclipse-packages/)（[最新版直达链接](https://www.eclipse.org/downloads/packages/eclipse-ide-cc-developers/neonr)）并解压至任意目录下（会生成 `eclipse` 目录）。 - -## 首次运行 -在安装完毕后，点击运行按钮。（如果是手动解压的，请在安装目录下双击 `eclipse` 可执行程序 - -在提示你选择工作区目录时，选择一个可用于存储Eclipse元数据及工程的目录。**不要选择 `qmk_firmware` 目录**，这是你的项目目录。可以使用其父目录，或其它（最好是空）目录（默认目标目录如果未作他用亦可使用）。 - -启动后，点击右上角的工作台（Workbench）按钮切换到工作台视图（启动时的欢迎页最下方有个确认框可以在下次启动时不再展示欢迎页）。 - -## 安装必要的插件 -注意：无需在每个插件安装完成时重启Eclipse，全部安装完毕后重启一次即可。 - -### [AVR插件](https://avr-eclipse.sourceforge.net/) -这是最重要的一个插件，可以帮助Eclipse理解AVR下的C语言代码。参照执行[更新网址使用指引](https://avr-eclipse.sourceforge.net/wiki/index.php/Plugin_Download#Update_Site)，并允许那些未签名内容产生的警告。 - -### [ANSI Escape in Console（命令行下的ANSI转义符）](https://marketplace.eclipse.org/content/ansi-escape-console) -该插件可以允许QMK makefile产生的具有颜色标记的构建输出信息能够正确显示。 - -1. 打开帮助 > Eclipse插件市场… -2. 搜索_ANSI Escape in Console_ -3. 点击插件的安装按钮 -4. 跟随安装指引并再次允许那些未签名的内容产生的警告。 - -在插件皆安装完毕后，依照提示重启Eclipse。 - -# 配置Eclipse QMK环境 -## 导入工程 -1. 点击文件 > 新建 > 现有的Makefile工程代码 -2. 在之后这一页中： - * 选择仓库所克隆到的目录位置作为 _现有代码位置_； - * （可选地）指定一个不同的工程名，如 _QMK_ 或 _Quantum_ ； - * 选择 _AVR-GCC Toolchain_; - * 其它选项保留不动，点击完成 - - ![Importing QMK in Eclipse](https://i.imgur.com/oHYR1yW.png) - -3. 工程即完成加载及分析，其下的文件可以方便地在左侧的 _Project Explorer_ 中查看了。 - -¹ 导入工程时若自定义名称有时会遇到些问题，如果行不通，保留默认的工程名（即目录名，通常是 `qmk_firmware`）再试一次。 - -## 构建你的键盘 - -我们将默认构建目标从 `all` 调整到我们期望构建的键盘及键映射组合上，即 `kinesis/kint36:stapelberg`。此时，形如清理、构建等工程级别的操作可以很快地执行完毕，而不至于耗费大量时间且导致Eclipse卡住。 - -1. 焦点置于工程下的任一编辑器tab中 -2. 打开`工程` > `属性`窗口， 选择 `C/C++构建` 菜单项并切至 `Behavior` 标签。 -3. 将 `Make build target`选项中的全量构建 `all` 改为 `kinesis/kint41:stapelberg`。 -4. 点击 `工程` > `清理...` 以确认配置正确。 - - [1]: https://en.wikipedia.org/wiki/Eclipse_(software) diff --git a/docs/zh-cn/other_vscode.md b/docs/zh-cn/other_vscode.md deleted file mode 100644 index 5f66eb6592..0000000000 --- a/docs/zh-cn/other_vscode.md +++ /dev/null @@ -1,120 +0,0 @@ -# 在Visual Studio Code中设置QMK开发环境 - - - -[Visual Studio Code](https://code.visualstudio.com/) (VS Code) 是一款支援非常多种不同编程语言的开源编辑器。 - -相比于使用简陋的文本编辑器，形如VS Code这样的多功能编辑器有诸多优势，比如： -* 智能的代码补全 -* 便捷的代码导航 -* 重构工具 -* 自动化构建支持（不再需要命令行操作） -* 图形化的GIT界面 -* 调试器、代码格式化、显示调用层级等多种工具 - -本章节旨在阐述如何配置VS Code以在其上进行QMK固件开发。 - -这份指引提供了在Windows及Ubuntu 18.04下所有的配置方法。 - -# 配置VS Code -一开始，你需要首先确认所有的构建工具已经安装配置完成，且QMK Firmware仓库已拷贝至本地。前往参阅[新人指引](zh-cn/newbs_getting_started.md)确保已完成初始配置。 - -## Windows - -### 依赖项 - -* [Git for Windows](https://git-scm.com/download/win) (该链接会自动提示你保存或运行安装包) - - 1. 除 `Git LFS (Large File Support)（大文件支援）` 及 `Check daily for Git for Windows updates（每天检查更新）` 外取消所有可选项。 - 2. 将默认编辑器改为 `Use Visual Studio Code as Git's default editor（将VS Code作为默认编辑器）` - 3. 选择 `Use Git from Git Bash only（仅在Git Bash中使用Git）`，这是应使用的方案。 - 4. 在 `Choosing HTTPS transport backend（选择HTTPS传输服务）` 选项上，皆可。 - 5. 选择 `Checkout as-is, commit Unix-style line endings（检出不作更改，提交时使用Unix风格换行符）`，QMK仓库使用的是Unix style提交。 - 6. 在额外选项页，保持默认选择即可。 - - 该软件是VS Code支持Git的所需项目，是有可能不去使用它，但直接用它会省很多事。 - -* [Git Credential Manager for Windows（Windows版Git凭据管理器）](https://github.com/Microsoft/Git-Credential-Manager-for-Windows/releases) （可选） - - 该软件提供了更好的git 凭据加密存储、多因素身份认证（MFA）及私有访问token生成器。 - - 这个不是严格必须的，但我们依旧推荐使用。 - - -### 安装VS Code - -1. 到[VS Code](https://code.visualstudio.com/)下载安装包 -2. 运行安装包 - -很简单的操作。然而，仍有一些配置我们需要确保是设置正确的。 - -### VS Code设置 - -首先来配置IntelliSense，虽不是严格必要的，但能让你后续使用便捷**很多**。首先，在QMK Firmware目录下创建文件 `.vscode/c_cpp_properties.json`，之后的操作可以手动完成，但我已经完成了大部分。 - -获取[这份文件](https://gist.github.com/drashna/48e2c49ce877be592a1650f91f8473e8)，如果你的MSYS2没有安装在默认路径，或在用WSL/LxSS，你可能需要做一下编辑修改。 - -在保存妥当后，如果你有已打开的VS Code，你需要reload一下。 - -?> 在 `.vscode` 目录下你应该还能看到 `extensions.json` 和 `settings.json` 文件。 - -现在，我们配置MSYS2作为VSCode的集成终端。这么做有很多好处，最主要的是可以通过按住control点击错误消息直接跳转到文件，调试起来会简单得多，另外的好处是，你不用在窗口间切换。 - -1. 点击 文件 > 首选项 > > 设置 -2. 点击上方右侧的 {} 按钮，打开 `settings.json` 文件。 -3. 将文件改为： - - ```json - { - "terminal.integrated.profiles.windows": { - "QMK_MSYS": { - "path": "C:/QMK_MSYS/usr/bin/bash.exe", - "env": { - "MSYSTEM": "MINGW64", - "CHERE_INVOKING": "1" - }, - "args": ["--login"] - } - }, - - "terminal.integrated.cursorStyle": "line" - } - ``` - - 如果该文件内已经有一些配置项，将上面的内容粘贴在最外层的花括号内，并用一个逗号将新旧内容分隔开。 - -?> 如果你的MSYS2安装在不同的目录下，你需要将 `terminal.integrated.shell.windows` 更改为你系统中正确的目录。 - -4. 点击Ctrl-` (Grave) 或在 视图 > 终端 可以打开终端界面 (`workbench.action.terminal.toggleTerminal` 命令)。如果没有终端它会自动打开一个。 - - 终端应启动于工程目录中（即 `qmk_firmware` 目录），之后你可以构建键盘了。 - - -## 其它系统 - -1. 到[VS Code](https://code.visualstudio.com/)下载安装包 -2. 运行安装包 -3. 搞定 - -是的，确实是搞定了。安装的时候所有所需的路径配置都会被包含进来，在检查当前工程文件并进行IntelliSense解析上表现也会更好。 - -## 插件 - -有一些你可能感兴趣的扩展可以安装： - -* [Git Extension Pack](https://marketplace.visualstudio.com/items?itemName=donjayamanne.git-extension-pack) - 提供了一系列的Git工具可以让你在QMK Firmware中使用Git便捷一些。 -* [EditorConfig for VS Code](https://marketplace.visualstudio.com/items?itemName=EditorConfig.EditorConfig) - _[可选]_ - 可以让你的代码更符合QMK规范。 -* [GitHub Markdown Preview](https://marketplace.visualstudio.com/items?itemName=bierner.github-markdown-preview) - _[可选]_ - 使得VS Code下的markdown预览更符合Github的效果。 -* [VS Live Share Extension Pack](https://marketplace.visualstudio.com/items?itemName=MS-vsliveshare.vsliveshare-pack) - _[可选]_ - 这个扩展允许他人访问你的工作区（或反之）进行协作，在你遇到问题需要他人帮助时挺有用。 - -安装扩展后需要重启VS Code。 - -# 配置VS Code下的QMK -1. 点击 文件 > 打开目录 -2. 打开你从Github克隆的QMK固件仓库所在目录。 -3. 点击 文件 > 保存工作区为... - -此时你已完成了在VS Code下编写QMK固件的准备工作。 diff --git a/docs/zh-cn/reference_configurator_support.md b/docs/zh-cn/reference_configurator_support.md deleted file mode 100644 index bd842871a0..0000000000 --- a/docs/zh-cn/reference_configurator_support.md +++ /dev/null @@ -1,200 +0,0 @@ -# 在QMK配置器中支持您的键盘 - - - -本章节详述了如何在[QMK配置器](https://config.qmk.fm/)中对键盘进行支持。 - - -## 配置器如何理解键盘 - -若要了解配置器如何理解键盘，须先理解配列的宏定义。这里有一份练习，假设这里有一个17键的小键盘PCB方案，就叫做 `numpad`。 - -``` -|---------------| -|NLk| / | * | - | -|---+---+---+---| -|7 |8 |9 | + | -|---+---+---| | -|4 |5 |6 | | -|---+---+---+---| -|1 |2 |3 |Ent| -|-------+---| | -|0 | . | | -|---------------| -``` - -?> 配列宏定义的更多资料，参见[理解QMK：矩阵扫描](zh-cn/understanding_qmk.md?id=matrix-scanning)及[理解QMK：矩阵到物理配列的映射](zh-cn/understanding_qmk.md?id=matrix-to-physical-layout-map)。 - -配置器的API会从 `qmk_firmware/keyboards//.h` 中读取键盘定义的 `.h` 文件。在上面的小键盘示例中，对应文件应为 `qmk_firmware/keyboards/numpad/numpad.h`： - -```c -#pragma once - -#define LAYOUT( \ - k00, k01, k02, k03, \ - k10, k11, k12, k13, \ - k20, k21, k22, \ - k30, k31, k32, k33, \ - k40, k42 \ - ) { \ - { k00, k01, k02, k03 }, \ - { k10, k11, k12, k13 }, \ - { k20, k21, k22, KC_NO }, \ - { k30, k31, k32, k33 }, \ - { k40, KC_NO, k42, KC_NO } \ -} -``` - -QMK使用 `KC_NO` 去标记开关矩阵中的空位。有时也会因方便或调试用途而使用 `XXX`，`___` 或 `____` 来替代。通产定义写在 `.h` 文件起始位置附近： - -```c -#pragma once - -#define XXX KC_NO - -#define LAYOUT( \ - k00, k01, k02, k03, \ - k10, k11, k12, k13, \ - k20, k21, k22, \ - k30, k31, k32, k33, \ - k40, k42 \ - ) { \ - { k00, k01, k02, k03 }, \ - { k10, k11, k12, k13 }, \ - { k20, k21, k22, XXX }, \ - { k30, k31, k32, k33 }, \ - { k40, XXX, k42, XXX } \ -} -``` - -!> 注意这里的使用模式与键映射中的宏完全不同，后者几乎都在用 `XXXXXXX`（7个大写X）替代 `KC_NO`，用 `_______`（7个下划线）替代 `KC_TRNS`。 - -!> 为避免混淆，推荐使用 `KC_NO`。 - -配列宏定义描述该键盘有17个按键，分布在五行四列。我们将这些开关命名为 `k<行号><列号>`，从0计起。命名成什么不太重要，但须确保负责从键映射中接收键码的上半段，与描述矩阵中按键位置的下半段定义匹配一致。 - -为了能够重现键盘的物理组成样式，须构建并提供一份用于描述按键物理位置和尺寸与开关矩阵绑定关系的JSON文件，以告知配置器程序这些信息。 - -## 构建JSON文件 - -构建该JSON描述文件最简便的办法是使用[Keyboard Layout Editor](https://www.keyboard-layout-editor.com/) ("KLE"), 从中获取的原始数据（Raw Data）可以经QMK工具转换为配置器可用的JSON格式数据。由于KLE默认打开显示的是一个小键盘配列，请移除新手引导部分，从剩余部分开始使用。 - -在配列编辑完毕后，从KLE的原始数据（Raw Data tab）页中拷贝类似如下的内容： - -``` -["Num Lock","/","*","-"], -["7\nHome","8\n↑","9\nPgUp",{h:2},"+"], -["4\n←","5","6\n→"], -["1\nEnd","2\n↓","3\nPgDn",{h:2},"Enter"], -[{w:2},"0\nIns",".\nDel"] -``` - -要将这份数据转换为我们可用的JSON格式，请跳转至[QMK KLE-JSON转换工具](https://qmk.fm/converter/)页面并粘贴到输入框，点击转换按钮。稍后输出框中即可看到所需的JSON数据。将输出数据拷贝到文本文档中，并命名为 `info.json`，保存到 `numpad.h` 所在目录。 - -可以通过 `keyboard_name` 元素来指定键盘名称。这里为了演示，会将每个按键独立分行，以更方便于阅读，这不影响配置器的功能。 - -```json -{ - "keyboard_name": "Numpad", - "url": "", - "maintainer": "qmk", - "tags": { - "form_factor": "numpad" - }, - "layouts": { - "LAYOUT": { - "layout": [ - {"label":"Num Lock", "x":0, "y":0}, - {"label":"/", "x":1, "y":0}, - {"label":"*", "x":2, "y":0}, - {"label":"-", "x":3, "y":0}, - {"label":"7", "x":0, "y":1}, - {"label":"8", "x":1, "y":1}, - {"label":"9", "x":2, "y":1}, - {"label":"+", "x":3, "y":1, "h":2}, - {"label":"4", "x":0, "y":2}, - {"label":"5", "x":1, "y":2}, - {"label":"6", "x":2, "y":2}, - {"label":"1", "x":0, "y":3}, - {"label":"2", "x":1, "y":3}, - {"label":"3", "x":2, "y":3}, - {"label":"Enter", "x":3, "y":3, "h":2}, - {"label":"0", "x":0, "y":4, "w":2}, - {"label":".", "x":2, "y":4} - ] - } - } -} -``` - -`layouts` 对象描述了键盘的物理配列信息，其下的 `LAYOUT` 对象命名须与 `numpad.h` 中的一致，而 `LAYOUT` 下的 `layout` 对象，其下每个JSON对象描述了各物理按键，格式如下： - -``` - 按键名，不会在配置器中展现。 - | - | 按键的X坐标，从键盘左侧开始数。 - | | - | | - | | 按键的Y坐标，从键盘上侧（后视角）开始数。 - | | | - ↓ ↓ ↓ -{"label":"Num Lock", "x":0, "y":0}, -``` - -部分对象包含 `"w"` 和 `"h"` 字段，用以描述按键的宽高值。 - -?> 关于 `info.json` 文件的详细信息，参见[`info.json` 文件格式](zh-cn/reference_info_json.md)。 - - -## 配置器如何配置按键 - -配置器API基于配列宏定义及JSON描述文件创建出键盘的可视化展现，并将每个可视化元素依序绑定到指定的按键： - -配列宏定义中的键 | 所使用的JSON对象 -:---: | :---- -k00 | {"label":"Num Lock", "x":0, "y":0} -k01 | {"label":"/", "x":1, "y":0} -k02 | {"label":"*", "x":2, "y":0} -k03 | {"label":"-", "x":3, "y":0} -k10 | {"label":"7", "x":0, "y":1} -k11 | {"label":"8", "x":1, "y":1} -k12 | {"label":"9", "x":2, "y":1} -k13 | {"label":"+", "x":3, "y":1, "h":2} -k20 | {"label":"4", "x":0, "y":2} -k21 | {"label":"5", "x":1, "y":2} -k22 | {"label":"6", "x":2, "y":2} -k30 | {"label":"1", "x":0, "y":3} -k31 | {"label":"2", "x":1, "y":3} -k32 | {"label":"3", "x":2, "y":3} -k33 | {"label":"Enter", "x":3, "y":3, "h":2} -k40 | {"label":"0", "x":0, "y":4, "w":2} -k42 | {"label":".", "x":2, "y":4} - -当用户在配置器中选中左上角的按键，并赋予数字区锁定键（NumLock）时，配置器会将 `KC_NUM` 作为第一个按键进行键映射文件的构建工作，其它按键逻辑类似。其中 `label` 键值未被用到，其用于用户在调试 `info.json` 文件时，可以参考辨认出各按键。 - - -## 问题及副作用 - -目前配置器还不支持按键偏转及类似ISO回车键这种非矩形按键。另外，对于纵向上偏离其行的按键 — 特别是像[TKC1800](https://github.com/qmk/qmk_firmware/tree/4ac48a61a66206beaf2fdd5f2939d8bbedd0004c/keyboards/tkc1800/)这种1800配列的键盘中的方向键 — 如果 `info.json` 文件的贡献者没有做出修正，KLE转JSON数据工具将会不知如何处理。 - -### 解决方案 - -#### 非矩阵形状的按键 - -针对ISO回车键的情况，QMK会将其定制化显示成一个矩形键，宽1.25u高2u，按键矩阵的右边与字母区的右边对齐。 - -![](https://i.imgur.com/JKngtTw.png) -*一款60% ISO配列的键盘, 在QMK配置器中的渲染样式。* - -#### 纵向偏移的按键 - -对于纵向偏移的按键，将其视作未偏移的样子放入KLE，最后在转换后的JSON文件中，按需编辑其Y偏移值。 - -![](https://i.imgur.com/fmDvDzR.png) -*一款1800配列键盘在KLE中的渲染样式，方向键未进行纵向偏移移动。* - -![](https://i.imgur.com/8beYMBR.png) -*这份Unix差异文件，展示了我们需要在JSON文件中进行的纵向偏移改动。* diff --git a/docs/zh-cn/reference_glossary.md b/docs/zh-cn/reference_glossary.md deleted file mode 100644 index e1dfccddd2..0000000000 --- a/docs/zh-cn/reference_glossary.md +++ /dev/null @@ -1,198 +0,0 @@ -# QMK术语表 - - - -## ARM -多家公司生产的32位单片机系列，例如Atmel, Cypress, Kinetis, NXP, ST, 和 TI等公司。 - -## AVR -[Atmel](https://www.microchip.com/)公司的单片机系列。 AVR是TMK的初始支持平台。 - -## AZERTY -Français （法语）标准键盘布局。用键盘的前六个字母命名。 - -## Backlight(背光) -键盘上照明的通称。背光通常是一组LED灯，穿过键帽或者轴体发光，但也不总是这样。 - -## Bluetooth(蓝牙) -一种短距离点对点无线传输协议。许多无线键盘使用此协议。 - -## Bootloader(引导加载程序) -一种写到你单片机保护区的特殊程序，该程序可以使单片机升级自己的固件，通常是通过USB来升级。 - -## Bootmagic(热改键) -允许各种键盘行为动态变化的功能，如交换或禁用常用键。 - -## C -一种适用于系统代码的低级编程语言。大多数qmk代码是用C编写的。 - -## Colemak -一种流行的键盘布局。 - -## Compile(编译) -把人可读的代码转换成你的单片机可以运行的机器代码的过程。 - -## Dvorak -一个由August Dvorak博士在20世纪30年代创建的布局。Dvorak简化键盘(Dvorak Simplified Keyboard)的缩写。 - -## Dynamic Macro(动态宏) -一种记录在键盘上的宏，当键盘拔出或计算机重新启动时，宏将丢失。 - -* [动态宏文档](zh-cn/feature_dynamic_macros.md) - -## Eclipse -是一种受C语言开发者追捧的集成开发环境(IDE)。 - -* [Eclipse安装说明](zh-cn/other_eclipse.md) - -## Firmware(固件) -用来控制单片机的软件。 - -## git -命令行版本控制软件 - -## GitHub -负责大多数QMK项目的网站。它是Git、问题跟踪和其他帮助我们运行qmk的功能的集成平台。 - -## ISP(在线系统编程) -在线系统编程(In-system programming), 使用外部硬件和JTAG管脚对AVR芯片进行编程的一种方法。 - -## hid_listen -从键盘接收调试消息的接口。 您可以使用[QMK Flasher](https://github.com/qmk/qmk_flasher)或[PJRC's hid_listen](https://www.pjrc.com/teensy/hid_listen.html)查看这些消息 - -## Keycode(键码) -表示特定键的2字节数据。`0x00`-`0xFF`用于[基本键码](zh-cn/keycodes_basic.md)而`0x100`-`0xFFFF`用于[量子键码](zh-cn/quantum_keycodes.md). - -## Key Down -一个键按下尚未抬起时触发的事件。 - -## Key Up -一个键抬起时触发的事件。 - -## Keymap(键映射) -映射到物理键盘布局的一组键码，在按键和按键释放时进行处理。有时翻译为布局，意为软件上表示的布局，即映射。 - -## Layer(层) -为了让一个键实现多个功能的抽象结构。可用层数有上限。 - -## Leader Key(前导键、设置菜单键) -本功能允许您点击前导键，然后按顺序按1-3个键子来激活按键或其他量子功能。 - -* [前导键文档](zh-cn/feature_leader_key.md) - -## LED -发光二极管，键盘上最常用的指示灯装置。 - -## Make -用于编译所有源文件的软件包。可以使用`make`命令和其他参数来编译你的固件。 - -## Matrix(矩阵) -一种由列和行组成的接线模式，使单片机能够用较少的引脚检测按键。矩阵通常包含二极管，以达到全键无冲。 - -## Macro(宏) -本功能可以在敲击单个键后发送多个按键事件(hid报告)。 - -* [宏文档](zh-cn/feature_macros.md) - -## MCU(单片机、微控制单元) -微控制单元，键盘的处理器。 - -## Modifier(修饰键、修改键、功能键) -按住该键将会改变其他键的功能，修饰键包括 Ctrl, Alt, 和 Shift。 - -## Mousekeys(鼠标键) -本功能在您敲击键盘时会控制鼠标光标。 - -* [鼠标键文档](zh-cn/feature_mouse_keys.md) - -## N-Key Rollover (NKRO、全键无冲) -一种术语，适用于能够同时报告任意数量按键的键盘。 - -## Oneshot Modifier(粘滞键) -一种能让你的功能键一直保持按下，直到你按下其他键的功能。它叫做粘滞键或叫做粘连键，该功能由软件实现而非机械结构。 - -## ProMicro -一种低成本AVR开发板。这种板子很容易在购物网站找到(价格不到20RMB)，但是据说刷写pro micro有点令人抓狂。 - -## Pull Request(拉请求、PR) -向QMK请求提交代码。我们鼓励所有用户提交你们自己的键盘的代码。 - -## QWERTY -标准英文键盘，通常也用于其他语言，例如中文。是用键盘前6个字母命名的。 - -## QWERTZ -标准Deutsche(德语)键盘布局。使用前6个字母明名。 - -## Rollover(允许翻转、无冲形式) -该术语表示在一个键已按下时按下另一个键。形式包括2KRO(双键无冲),6KRO(6键无冲),和NKRO(全键无冲)，无冲表示可同时按下而不产生冲突的键的数量。 - -## Scancode(扫描码) -HID报告中的一个1字节的数字，表示一个键子。这些数字在下列文档中[HID Usage Tables](https://www.usb.org/sites/default/files/documents/hut1_12v2.pdf)该文档发布于[USB-IF](https://www.usb.org/)。 - -## Space Cadet键盘的shift键 -一种特殊的shift设置，能让你通过敲击左或右shift一次或多次键入不同的括号。 - -* [Space Cadet键盘文档](zh-cn/feature_space_cadet.md) - -## Tap(敲击、单击) -按下并抬起一个键。在某些情况下您需要区分键按下和键抬起，但是单击把两个事件都包括了。 - -## Tap Dance(多击键) -本功能允许向同一个键子分配多个键码，并根据按键次数区分。 - -* [多击键文档](zh-cn/feature_tap_dance.md) - -## Teensy -一种低成本AVR开发板，通常用于手工连线键盘。这个teensy是有点小贵但是halfkay bootloader会让它刷写十分简单，所以也很常用。 - -## Underlight(背光) -用于照亮电路板底面的LED的总称。这些LED通常从印刷电路板的底部向键盘所在的表面发光。 - -## Unicode -在广阔的计算机世界中，Unicode是一组编码方案，用于表示任何语言中的字符。 与qmk相关的是，它意味着使用各种操作系统方案来发送Unicode码点，而不是扫描码。 - -* [Unicode文档](zh-cn/feature_unicode.md) - -## Unit Testing(单元测试) -针对qmk的自动测试框架。单元测试帮助我们确信我们的更改不会破坏任何东西。 - -* [单元测试文档](zh-cn/unit_testing.md) - -## USB -通用串行总线，键盘最常见的有线接口。 - -## USB 主机 (简称主机) -USB主机就是你的电脑，或者你的键盘所插的任何设备。 - -# 并没有找到你想找到的术语? - -[新建一个issue](https://github.com/qmk/qmk_firmware/issues) ，想好你的问题，或许你所问的术语就会添加到这里。创建一个PR帮我们添加需要添加的术语当然坠吼了:) - -## 中文翻译术语特别说明（terms of Chinese translation）:id=terms-of-zh-cn-translate -!>如果你对QMK文档翻译中的细节不关心，请跳过该节 - -由于语言及文化差异，QMK英文文档中的部分内容，很难在**保持原句结构**的情况下，完美地翻译为中文，而保持翻译前后的语句结构一致对于开源代码的文档翻译来讲十分重要，这样才能确保不同的文档贡献者不会*夹带私货*，防止不同的翻译风格、不同的翻译水准、不同的理解与润色最终产生糟糕的混合。 -因此，这里会对一些词组的的翻译进行规范化，并希望阅读者及后续文档翻译维护者，维持这种统一的范式。 - -### keyboard（键盘）及keymap（键映射） -QMK文档中使用最多的两个术语是keyboard及keymap -* 键盘：在中文语境下，我们提及键盘，基本是在指物理键盘，而在QMK文档中到处可见的“键盘”一词，多对应的是代码中 `keyboards\` 目录下的键盘定义，其更接近于我们讲的“配列”的概念，主要描述了键盘的大体结构，物理键数量及排列。 -* 键映射：keymap的作用是定义物理键盘到实际输出键值(keycode)的映射关系，也是QMK最重要、涉及最多的概念。QMK很多功能就是为了能够在不改变键盘物理排列/电路组成/芯片程序的情况下，动态地改变物理按键输出的键值。如，通过层切换，将原先的wasd键，切换到可以上下左右的模式，或是一键切换CapsLock和Control，实现这些功能的核心工作就是一套动态的keymap，即键映射逻辑。这里不使用“布局”一词作为keymap的翻译，是因为该词过于宽泛。键映射即便是不好听，至少解释了意思且语境中不容易误解。 - -### mod-tap -倾向于不翻译，直接使用原词。因为找不到合适的译法 - -### dead key -直译为死键，西语体系下使用的特殊符号，中文中无对应概念。 - -### flashing（firmware） -使用“刷写”而非容易迷惑的“刷新” - -### option/configuration/setting -根据上下文灵活考虑。对于组件化配置的概念，如一个功能支持与否，使用“配置”一词；对于客观上一定存在的某项设置值，使用“设置”一词。 - -### commit/push/pull等Git术语 -倾向于不翻译。这些词语的对应中文词语过于宽泛或词性不明，非常容易混淆上下文。 diff --git a/docs/zh-cn/support.md b/docs/zh-cn/support.md deleted file mode 100644 index e636d29c97..0000000000 --- a/docs/zh-cn/support.md +++ /dev/null @@ -1,22 +0,0 @@ -# 寻求帮助 - - - -你可以从很多渠道获取QMK帮助。 - -在你前往社区进行沟通前，请先阅览我们的社区[行为守则](https://qmk.fm/coc/) - -## 实时沟通 - -在你需要帮助时，最便捷的办法是通过我们的[Discord服务器](https://discord.gg/Uq7gcHh)进行沟通，通常会有人在线，也有很多乐于助人的人。 - -## OLKB Subreddit - -QMK的官方论坛是[reddit.com](https://reddit.com)上的[/r/olkb](https://reddit.com/r/olkb). - -## GitHub Issues - -你可以在[Github上发Issue](https://github.com/qmk/qmk_firmware/issues)，对于需要深入讨论或需要调试的问题，会方便得多。 diff --git a/docs/zh-cn/syllabus.md b/docs/zh-cn/syllabus.md deleted file mode 100644 index d0b861530a..0000000000 --- a/docs/zh-cn/syllabus.md +++ /dev/null @@ -1,77 +0,0 @@ -# QMK大纲 - - - -这一页旨在帮你建立关于QMK的相关基础知识，并提供能引导你成为QMK大师所需的所有概念。 - -# 基本概念 - -如果你还没有看其它部分，先阅读这一节吧。在阅读了[介绍](zh-cn/newbs.md)之后，你可以制作、编译、刷写一个简单的键映射了，以下文档可以助你充实各系列的知识。 - -* **了解如何使用QMK** - * [介绍](zh-cn/newbs.md) - * [CLI](zh-cn/cli.md) - * [GIT](zh-cn/newbs_git_best_practices.md) -* **了解键映射** - * [层](zh-cn/feature_layers.md) - * [键码](zh-cn/keycodes.md) - * 含所有可用键码，一些会涉及进阶或高级的话题。 -* **配置IDE** - 可选的 - * [Eclipse](zh-cn/other_eclipse.md) - * [VS Code](zh-cn/other_vscode.md) - -# 进阶话题 - -包含窥探QMK主要功能内部原理的话题。你可以不用阅读这些，然而，跳过这些话题的话，去看高级话题的时候会让你很迷惑。 - -* **各功能的配置** - - * [音频](zh-cn/feature_audio.md) - * 灯光 - * [背光](zh-cn/feature_backlight.md) - * [LED矩阵](zh-cn/feature_led_matrix.md) - * [RGB灯光](zh-cn/feature_rgblight.md) - * [RGB矩阵](zh-cn/feature_rgb_matrix.md) - * [点按配置](zh-cn/tap_hold.md) - * [充分利用AVR的存储空间](zh-cn/squeezing_avr.md) -* **深入键映射** - * [键映射](zh-cn/keymap.md) - * [键码与自定义函数](zh-cn/custom_quantum_functions.md) - * 宏 - * [动态宏](zh-cn/feature_dynamic_macros.md) - * [宏](zh-cn/feature_macros.md) - * [Tap Dance](zh-cn/feature_tap_dance.md) - * [组合键](zh-cn/feature_combo.md) - * [用户空间](zh-cn/feature_userspace.md) - * [按键重定义](zh-cn/feature_key_overrides.md) - -# 高级话题 - -这些话题需要较多基础知识，使用这些高级功能前，你应该对如何通过 `config.h` 和 `rules.mk` 来配置键盘选项非常熟悉。 - -* **维护QMK键盘** - * [飞线指南](zh-cn/hand_wire.md) - * [键盘开发指引](zh-cn/hardware_keyboard_guidelines.md) - * [info.json参考资料](zh-cn/reference_info_json.md) - * [防抖API](zh-cn/feature_debounce_type.md) -* **高级功能** - * [Unicode](zh-cn/feature_unicode.md) - * [API](zh-cn/api_overview.md) - * [Bootmagic Lite](zh-cn/feature_bootmagic.md) -* **硬件相关** - * [键盘工作原理](zh-cn/how_keyboards_work.md) - * [键盘矩阵原理](zh-cn/how_a_matrix_works.md) - * [分体键盘](zh-cn/feature_split_keyboard.md) - * [速记](zh-cn/feature_stenography.md) - * [光标设备](zh-cn/feature_pointing_device.md) -* **开发核心知识** - * [C编码规范](zh-cn/coding_conventions_c.md) - * [兼容的微处理器](zh-cn/compatible_microcontrollers.md) - * [自定义矩阵](zh-cn/custom_matrix.md) - * [理解QMK](zh-cn/understanding_qmk.md) -* **CLI开发** - * [编码规范](zh-cn/coding_conventions_python.md) - * [CLI开发总览](zh-cn/cli_development.md) diff --git a/docs/zh-cn/translating.md b/docs/zh-cn/translating.md deleted file mode 100644 index fa80ffd7f8..0000000000 --- a/docs/zh-cn/translating.md +++ /dev/null @@ -1,60 +0,0 @@ -# 翻译QMK文档 - - - -根目录下（`docs/`）的所有文件应当是英语的 - 其它语言应使用 ISO 639-1 中定义的语言编码建立子目录，后跟随一个 `-` 以及必要的国家编码。[常见的语言编码可见这里](https://www.andiamo.co.uk/resources/iso-language-codes/)。如果此目录不存在，可以新建。每个翻译过的文件的文件名，都应保持与英语版本的一致，以确保超链接的退化兼容性。 - -文件夹下的 `_summary.md` 文件中，有链接向其它文件的地址，在翻译过的名称后，跟随的链接前应添加该语言的目录名： - -```markdown - * [QMK简介](zh-cn/getting_started_introduction.md) -``` - -所有导向其它文档页面的链接也必须有语言目录名前缀，若还指向了页面指定位置（即特定的标题），必须使用标题的英文ID，如： - -```markdown -[建立你的环境](zh-cn/newbs-getting-started.md#set-up-your-environment) - -## 建立你的环境 :id=set-up-your-environment -``` - -在翻译后，以下文件也需要进行修改： - -* [`docs/_langs.md`](https://github.com/qmk/qmk_firmware/blob/master/docs/_langs.md) - 中的每一行应包含该语言国家国旗的[GitHub emoji编码](https://github.com/ikatyang/emoji-cheat-sheet/blob/master/README.md#country-flag)标志： - - ```markdown - - [:cn: 中文](/zh-cn/) - ``` - -* [`docs/index.html`](https://github.com/qmk/qmk_firmware/blob/master/docs/index.html) - `placeholder` 及 `noData` 对象应有一个指向对应语言的入口项： - - ```js - '/zh-cn/': '没有结果!', - ``` - - 用于 "QMK固件" 边栏标题链接的 `nameLink` 同样需要添加对应配置： - - ```js - '/zh-cn/': '/#/zh-cn/', - ``` - - 最后确保在 `fallbackLanguages` 列表中添加该语言项，这样未翻译的文档链接将回退到英文版，而不是出现404页面： - - ```js - fallbackLanguages: [ - // ... - 'zh-cn', - // ... - ], - ``` - -## 预览你的翻译成果 - -请阅读[文档预览](zh-cn/contributing.md#previewing-the-documentation)来设置文档的本地预览 - 在页面右上角的 "Translations" 菜单中应当可以看到你翻译的语言的入口。 - -当你觉得一切就绪了，请发起pull request给我们吧！ diff --git a/docs/zh-cn/zh_cn_doc_status.sh b/docs/zh-cn/zh_cn_doc_status.sh deleted file mode 100644 index 84693e5461..0000000000 --- a/docs/zh-cn/zh_cn_doc_status.sh +++ /dev/null @@ -1,35 +0,0 @@ -#! /bin/sh -# -# Script to display Simplified Chinese translation status of documents -# Copied from the japanese one -# -if [ ! -d docs/zh-cn ]; then - echo "'docs/zh-cn' not found." - echo "do:" - echo " cd \$(QMK_TOP)" - echo " ./docs/zh-cn/zh-cn_doc_status.sh" - exit 1 -fi - -en_docs=`cd docs;ls -1 [a-z]*.md` -zh_cn_docs=`cd docs/zh-cn;ls -1 [a-z]*.md` -en_count=`echo $en_docs | wc -w` -zh_cn_count=`echo $zh_cn_docs | wc -w` -echo "English documents $en_count files." -echo "Simplified Chinese documents $zh_cn_count files." - -echo "Files that have not been translated yet:" -for docfile in $en_docs -do - if [ ! -f docs/zh-cn/$docfile ]; then - wc docs/$docfile - fi -done | sort -echo "Files that have not been updated yet:" -grep --no-filename "^[ ]*git diff" docs/zh-cn/*.md | while read cmd -do - cline=`echo $cmd | sh | wc -l` - if [ $cline -gt 0 ]; then - echo "$cline $cmd" - fi -done | sort diff --git a/lib/python/qmk/cli/docs.py b/lib/python/qmk/cli/docs.py index c24b914bc1..d28dddf194 100644 --- a/lib/python/qmk/cli/docs.py +++ b/lib/python/qmk/cli/docs.py @@ -1,44 +1,27 @@ """Serve QMK documentation locally """ -import http.server -import os import shutil -import webbrowser +from qmk.docs import prepare_docs_build_area, run_docs_command from milc import cli -@cli.argument('-p', '--port', default=8936, type=int, help='Port number to use.') -@cli.argument('-b', '--browser', action='store_true', help='Open the docs in the default browser.') @cli.subcommand('Run a local webserver for QMK documentation.', hidden=False if cli.config.user.developer else True) def docs(cli): """Spin up a local HTTP server for the QMK docs. """ - os.chdir('docs') - # If docsify-cli is installed, run that instead so we get live reload - if shutil.which('docsify'): - command = ['docsify', 'serve', '--port', f'{cli.config.docs.port}', '--open' if cli.config.docs.browser else ''] + if not shutil.which('doxygen'): + cli.log.error('doxygen is not installed. Please install it and try again.') + return - cli.log.info(f"Running {{fg_cyan}}{str.join(' ', command)}{{fg_reset}}") - cli.log.info("Press Control+C to exit.") + if not shutil.which('yarn'): + cli.log.error('yarn is not installed. Please install it and try again.') + return - try: - cli.run(command, capture_output=False) - except KeyboardInterrupt: - cli.log.info("Stopping HTTP server...") - else: - # Fall back to Python HTTPServer - with http.server.HTTPServer(('', cli.config.docs.port), http.server.SimpleHTTPRequestHandler) as httpd: - cli.log.info(f"Serving QMK docs at http://localhost:{cli.config.docs.port}/") - cli.log.info("Press Control+C to exit.") + if not prepare_docs_build_area(is_production=False): + return False - if cli.config.docs.browser: - webbrowser.open(f'http://localhost:{cli.config.docs.port}') - - try: - httpd.serve_forever() - except KeyboardInterrupt: - cli.log.info("Stopping HTTP server...") - finally: - httpd.shutdown() + if not cli.config.general.verbose: + cli.log.info('Serving docs at http://localhost:5173/ (Ctrl+C to stop)') + run_docs_command('run', 'docs:dev') diff --git a/lib/python/qmk/cli/generate/docs.py b/lib/python/qmk/cli/generate/docs.py index eb3099e138..5821d43b86 100644 --- a/lib/python/qmk/cli/generate/docs.py +++ b/lib/python/qmk/cli/generate/docs.py @@ -1,18 +1,12 @@ """Build QMK documentation locally """ import shutil -from pathlib import Path -from subprocess import DEVNULL +from qmk.docs import prepare_docs_build_area, run_docs_command, BUILD_DOCS_PATH from milc import cli -DOCS_PATH = Path('docs/') -BUILD_PATH = Path('.build/') -BUILD_DOCS_PATH = BUILD_PATH / 'docs' -DOXYGEN_PATH = BUILD_PATH / 'doxygen' -MOXYGEN_PATH = BUILD_DOCS_PATH / 'internals' - +@cli.argument('-s', '--serve', arg_only=True, action='store_true', help="Serves the generated docs once built.") @cli.subcommand('Build QMK documentation.', hidden=False if cli.config.user.developer else True) def generate_docs(cli): """Invoke the docs generation process @@ -21,24 +15,22 @@ def generate_docs(cli): * [ ] Add a real build step... something static docs """ - if BUILD_DOCS_PATH.exists(): - shutil.rmtree(BUILD_DOCS_PATH) - if DOXYGEN_PATH.exists(): - shutil.rmtree(DOXYGEN_PATH) + if not shutil.which('doxygen'): + cli.log.error('doxygen is not installed. Please install it and try again.') + return - shutil.copytree(DOCS_PATH, BUILD_DOCS_PATH) + if not shutil.which('yarn'): + cli.log.error('yarn is not installed. Please install it and try again.') + return - # When not verbose we want to hide all output - args = { - 'capture_output': False if cli.config.general.verbose else True, - 'check': True, - 'stdin': DEVNULL, - } - - cli.log.info('Generating docs...') - - # Generate internal docs - cli.run(['doxygen', 'Doxyfile'], **args) - cli.run(['moxygen', '-q', '-g', '-o', MOXYGEN_PATH / '%s.md', DOXYGEN_PATH / 'xml'], **args) + if not prepare_docs_build_area(is_production=True): + return False + cli.log.info('Building vitepress docs') + run_docs_command('run', 'docs:build') cli.log.info('Successfully generated docs to %s.', BUILD_DOCS_PATH) + + if cli.args.serve: + if not cli.config.general.verbose: + cli.log.info('Serving docs at http://localhost:4173/ (Ctrl+C to stop)') + run_docs_command('run', 'docs:preview') diff --git a/lib/python/qmk/cli/new/keyboard.py b/lib/python/qmk/cli/new/keyboard.py index 37bf2923d6..56bd05e1e3 100644 --- a/lib/python/qmk/cli/new/keyboard.py +++ b/lib/python/qmk/cli/new/keyboard.py @@ -133,7 +133,7 @@ def _question(*args, **kwargs): def prompt_keyboard(): prompt = """{fg_yellow}Name Your Keyboard Project{style_reset_all} For more infomation, see: -https://docs.qmk.fm/#/hardware_keyboard_guidelines?id=naming-your-keyboardproject +https://docs.qmk.fm/hardware_keyboard_guidelines#naming-your-keyboard-project Keyboard Name? """ diff --git a/lib/python/qmk/docs.py b/lib/python/qmk/docs.py new file mode 100644 index 0000000000..56694cf6ae --- /dev/null +++ b/lib/python/qmk/docs.py @@ -0,0 +1,61 @@ +"""Handlers for the QMK documentation generator (docusaurus). +""" +import shutil +from pathlib import Path +from subprocess import DEVNULL +from os import chdir, environ, makedirs, pathsep +from milc import cli + +from qmk.constants import QMK_FIRMWARE + +DOCS_PATH = QMK_FIRMWARE / 'docs' +BUILDDEFS_PATH = QMK_FIRMWARE / 'builddefs' / 'docsgen' +BUILD_PATH = QMK_FIRMWARE / '.build' +CACHE_PATH = BUILD_PATH / 'cache' +NODE_MODULES_PATH = BUILD_PATH / 'node_modules' +BUILD_DOCS_PATH = BUILD_PATH / 'docs' +DOXYGEN_PATH = BUILD_DOCS_PATH / 'static' / 'doxygen' + + +def run_docs_command(verb, cmd=None): + environ['PATH'] += pathsep + str(NODE_MODULES_PATH / '.bin') + + args = {'capture_output': False if cli.config.general.verbose else True, 'check': True, 'stdin': DEVNULL} + docs_env = environ.copy() + if cli.config.general.verbose: + docs_env['DEBUG'] = 'vitepress:*,vite:*' + args['env'] = docs_env + + arg_list = ['yarn', verb] + if cmd: + arg_list.append(cmd) + + chdir(BUILDDEFS_PATH) + cli.run(arg_list, **args) + + +def prepare_docs_build_area(is_production): + if is_production: + # Set up a symlink for docs to be inside builddefs -- vitepress can't handle source files in parent directories + try: + docs_link = Path(BUILDDEFS_PATH / 'docs') + if not docs_link.exists(): + docs_link.symlink_to(DOCS_PATH) + except NotImplementedError: + cli.log.error('Symlinks are not supported on this platform.') + return False + + if BUILD_DOCS_PATH.exists(): + shutil.rmtree(BUILD_DOCS_PATH) + + # When not verbose we want to hide all output + args = {'capture_output': False if cli.config.general.verbose else True, 'check': True, 'stdin': DEVNULL} + + makedirs(DOXYGEN_PATH) + cli.log.info('Generating doxygen docs at %s', DOXYGEN_PATH) + cli.run(['doxygen', 'Doxyfile'], **args) + + cli.log.info('Installing vitepress dependencies') + run_docs_command('install') + + return True