diff options
author | Nick Brassel <[email protected]> | 2024-05-30 12:00:41 +1000 |
---|---|---|
committer | GitHub <[email protected]> | 2024-05-30 12:00:41 +1000 |
commit | 6ef97172889ccd5db376b2a9f8825489e24fdac4 (patch) | |
tree | 334e3bf41c8554d4bee73a140822f95f60eb64e9 /docs/zh-cn | |
parent | 395766657ff98a4b1fd0dcba5917557f8acbb9e4 (diff) | |
download | qmk_firmware-6ef97172889ccd5db376b2a9f8825489e24fdac4.tar.gz qmk_firmware-6ef97172889ccd5db376b2a9f8825489e24fdac4.zip |
Vitepress conversion of docs. (#23795)
Diffstat (limited to 'docs/zh-cn')
50 files changed, 0 insertions, 5579 deletions
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固件 - -<!--- - original document: 0.15.12:docs/README.md - git diff 0.15.12 HEAD -- docs/README.md | cat ---> - -## 什么是 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),并与各位社区成员维护这份文档。 - -## 如何入门 - -<div class="flex-container"> - -?> **基础方式** [QMK配置器](zh-cn/newbs_building_firmware_configurator.md) <br> -用户友好的图形界面工具,无需具备编程知识基础。 - -?> **进阶方式** [基于源代码](zh-cn/newbs.md) <br> -功能更强大,但门槛较高。 - -</div> - -## 个性化定制 - -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 @@ -<!--for translators, see first: zh-cn/reference_glossary.md#terms-of-zh-cn-translate --> -* 新手教程 - * [介绍](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)<!--but should we translate this? currently keep it fallback--> - * [配置](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) - -<!--fromen:20211014-12:00(GMT+8) commit 04cf161aa01fd433b5dae69d9fd31569ed5dca59--> 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 - -<!--- - original document: 0.15.12:docs/api_docs.md - git diff 0.15.12 HEAD -- docs/api_docs.md | cat ---> - -本章节详述了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 - -<!--- - original document: 0.15.12:docs/api_overview.md - git diff 0.15.12 HEAD -- docs/api_overview.md | cat ---> - -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 - -<!--- - original document: 0.15.12:docs/cli.md - git diff 0.15.12 HEAD -- docs/cli.md | cat ---> - -## 总览 :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 命令 - -<!--- - original document: 0.15.12:docs/cli_commands.md - git diff 0.15.12 HEAD -- docs/cli_commands.md | cat ---> - -# 用户命令 - -## `qmk compile` - -该命令用于在指定目录下编译固件,可用于构建<https://config.qmk.fm>导出的JSON数据,代码库中的键映射,或是当前目录下的键盘。 - -该命令会尝试感知目录路径,当你在键盘或键映射目录下执行时,KEYBOARD及KEYMAP参数将被自动填入。 - -**用于配置器导出的数据时**: - -``` -qmk compile [-c] <configuratorExport.json> -``` - -**用于键映射时**: - -``` -qmk compile [-c] [-e <var>=<value>] [-j <num_jobs>] -kb <keyboard_name> -km <keymap_name> -``` - -**在键盘目录下时**: - -须在存在默认键映射的键盘目录下执行,或是在键盘的键映射子目录下,否则须指定参数 `--keymap <keymap_name>` -``` -qmk compile -``` - -**构建所有支持该键映射的键盘时**: - -``` -qmk compile -kb all -km <keymap_name> -``` - -**示例**: -``` -$ 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 <keyboard_name> -``` - -**示例**: -``` -$ 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 <num_jobs> -kb <keyboard_name> -``` -`num_jobs` 用于指定并行的job上限,将其设置为0可以实现无限制的并行编译。 -``` -qmk compile -j 0 -kb <keyboard_name> -``` - -## `qmk flash` :id=qmk-flash - -该命令与 `qmk compile` 类似,但额外地可以指定bootloader。bootloader参数是可选的,默认会指定为 `:flash`。可通过 `-bl <bootloader>` 来指定bootloader。请查阅[刷写固件](zh-cn/flashing.md)指引以深入了解可用的bootloader信息。 - -该命令会尝试感知目录路径,当你在键盘或键映射目录下执行时,KEYBOARD及KEYMAP参数将被自动填入。 - -**用于配置器导出的数据时**: - -``` -qmk flash [-bl <bootloader>] [-c] [-e <var>=<value>] [-j <num_jobs>] <configuratorExport.json> -``` - -**用于键映射时**: - -``` -qmk flash -kb <keyboard_name> -km <keymap_name> [-bl <bootloader>] [-c] [-e <var>=<value>] [-j <num_jobs>] -``` - -**列出所有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 <pid>:<vid>[:<index>]] [-l] [-n] [-t] [-w <seconds>] -``` - -**示例**: - -连接到所有可用的键盘并输出终端信息: - -``` -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] <json_file> -``` - -## `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] <filename> -``` - -**示例**: - -``` -$ 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 配置 - -<!--- - original document: 0.15.12:docs/cli_configuration.md - git diff 0.15.12 HEAD -- docs/cli_configuration.md | cat ---> - -本文详述了 `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` 命令可以管理配置数据。当不带额外参数执行时,会输出所有已有配置。存在参数时这些参数将被视为配置项参数,其格式须满足如下形式且无空格分隔: - - <subcommand|general|default>[.<key>][=<value>] - -## 设置配置值 - -在配置项的键后加 = 号进行值的设置,配置项的键必须是 `<section>.<key>` 的完整形式。 - -举例: - -``` -$ 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补全 - -<!--- - original document: 0.15.12:docs/cli_tab_complete.md - git diff 0.15.12 HEAD -- docs/cli_tab_complete.md | cat ---> - -在使用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配置器框架 - -<!--- - original document: 0.15.12:docs/configurator_architecture.md - git diff 0.15.12 HEAD -- docs/configurator_architecture.md | cat ---> - -本章节提供了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> - -[配置器前端](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的状态。 - -## 键盘元数据 - -地址:<https://keyboards.qmk.fm> - -每当[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 - -地址:<http://api.qmk.fm> - -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 - -<!--- - original document: 0.15.12:docs/configurator_default_keymaps.md - git diff 0.15.12 HEAD -- docs/configurator_default_keymaps.md | cat ---> - -本章节描述了如何向QMK配置器中添加一款键盘的默认键映射 - - -## 技术信息 :id=technical-information - -QMK配置器使用JSON作为键映射的本地文件格式。我们尽力确保其行为与在 `qmk_firmware` 中 执行 `make <keyboard>: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/<keyboard>/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` 定义块添加到键盘的头文件(`<keyboard.h>`)中,例如(留意 `enum` 在这里命名为 `keyboard_keycodes`): - -```c -enum keyboard_keycodes { - CUSTOM_1 = SAFE_RANGE, - CUSTOM_2, - CUSTOM_3, - NEW_SAFE_RANGE // 重要! -}; -``` - -... 之后在 `<keyboard>.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 配置器: 入门 - -<!--- - original document: 0.15.12:docs/configurator_step_by_step.md - git diff 0.15.12 HEAD -- docs/configurator_step_by_step.md | cat ---> - -本章节描述了如何使用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账号在维护着,请也确认一下。 <!-- FIXME(skullydazed): This feels too wordy and I'm not sure we want to encourage these kinds of issues. Also, should we prompt them to bug the manufacutrer? --> - -## 第二部:选择键盘配列 - -选择最适合你要创建的键映射的配列,一些键盘的配列不完整或有问题,后续会逐渐支持。 - -!> 有时会遇到没有特别适合的配列的情况,请选择 `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 @@ -# 配置器问题排查 - -<!--- - original document: 0.15.12:docs/configurator_troubleshooting.md - git diff 0.15.12 HEAD -- docs/configurator_troubleshooting.md | cat ---> - -## 我的 .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 @@ -# 如何做贡献 - -<!--- - original document: 0.15.12:docs/contributing.md - git diff 0.15.12 HEAD -- docs/contributing.md | cat ---> - -👍🎉 首先感谢各位百忙之中抽空阅读本文档,并为我们无私奉献。给您点赞啦! 🎉👍 - -第三方的帮助让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贡献中来。 - -<!-- FIXME: 这里应当放些C语言的学习资源。 --> - -# 我到哪里寻求帮助? - -您要是有问题的话可以 [提出一个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/<kb1>/<kb2>/<kb2>.[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 @@ -# 如何定制化键盘功能 - -<!--- - original document: 0.15.12:docs/custom_quantum_functions.md - git diff 0.15.12 HEAD -- docs/custom_quantum_functions.md | cat ---> - -对于很多人来说对客制化键盘的诉求不只是向电脑输入按下的键。你肯定想实现比简单按键和宏更复杂的功能。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驱动 - -<!--- - original document: 0.15.12:docs/driver_installation_zadig.md - git diff 0.15.12 HEAD -- docs/driver_installation_zadig.md | cat ---> - -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 @@ -# 极简式制作 - 通过配置器进行一次性的工程构建 - -<!--- - original document: 0.15.12:docs/easy_maker.md - git diff 0.15.12 HEAD -- docs/easy_maker.md | cat ---> - -你是否需要一种极简的控制器编程方案,类似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: - -* <https://config.qmk.fm/#/?filter=ez_maker/direct> - -更多信息请参见[引脚直连](#direct-pin)一节。 - -# 引脚直连 :id=direct-pin - -与其名字表意相同,它的原理是一个引脚连接一个开关,每个开关的另一端接地(VSS或GND),不需要额外的部件,通常MCU内部自带上拉电阻,因此可以感知开关动作。 - - -这里有一个示意图,展示了如何将一个按钮连接到ProMicro的A3引脚上: - -![该示意图中的ProMicro的A3引脚导出一根线,连接到了开关的左边,另一根线从开关右边引出并接地。](https://i.imgur.com/JcDhZll.png) - -在开关连接到各自的引脚后,在键盘下拉列表中选择所使用的MCU,将键码指定到对应的引脚上即可构建出固件。以下链接仅展示支持引脚直连的极简式制作: - -* <https://config.qmk.fm/#/?filter=ez_maker/direct> 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 @@ -# 常被问及的编译问题 - -<!--- - original document: 0.15.12:docs/faq_build.md - git diff 0.15.12 HEAD -- docs/faq_build.md | cat ---> - -本页涉及所有编译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 <keyboard>:<keymap>: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 - -<!--- - original document: 0.15.12:docs/faq_debug.md - git diff 0.15.12 HEAD -- docs/faq_debug.md | cat ---> - -此页面详细介绍了人们对键盘故障排除的各种常见问题。 - -## 调试 :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) - -<!--- - original document: 0.15.12:docs/faq_general.md - git diff 0.15.12 HEAD -- docs/faq_general.md | cat ---> - -## 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 - -<!--- - original document: 0.15.12:docs/faq_keymap.md - git diff 0.15.12 HEAD -- docs/faq_keymap.md | cat ---> - -本页包含人们经常遇到的关于键映射的问题,如果你还没阅读过[键映射概览](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。这三种配列的键码可查阅: - -<!-- Source for this image: https://www.keyboard-layout-editor.com/#/gists/bf431647d1001cff5eff20ae55621e9a --> -![键盘配列示意图](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和<code>`</code>位于同一个键位 - -参见[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 - -<!--- - original document: 0.15.12:docs/faq_misc.md - git diff 0.15.12 HEAD -- docs/faq_misc.md | cat ---> - -## 怎么对键盘进行测试? :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 - -<!--- - original document: 0.15.12:docs/feature_grave_esc.md - git diff 0.15.12 HEAD -- docs/feature_grave_esc.md | cat ---> - -*译注:Grave键即标准键盘中Tab键上方的 <code>`</code> 键,该符号用于英法语等西语体系,辅助调整发音,中文中没有对应概念;Escape即Esc键* - -若你使用60%或其它没有Fn键配列的键盘,会留意到没有独立的Escape键。Grave Escape功能可以让Grave键(<code>`</code>及`~`)与Escape共享一个按键 - -## 使用方法 - -在配列中使用 `QK_GESC` 替换 `KC_GRAVE` (一般都在`1`键左边)。默认点击会输出 `KC_ESC`,按下Shift或GUI键时,点击会输出 `KC_GRV` - -## 操作系统视角 - -假如翠花按下GESC键,系统接收到的是KC_ESC字符。若翠花按住Shift再按下GESC,将输出 `~` 或是反引号。若翠花按住GUI/CMD/Win键,将仅输出<code>`</code>字符 - -## 键码 - -|键 |别名 |描述 | -|---------|-----------|------------------------------------------------------------------| -|`QK_GESC`|`GRAVE_ESC`|单击输出Escape, 按住Shift或GUI时输出<code>`</code> | - -### 须留意 - -在macOS上 Command+<code>`</code>默认行为是“移动焦点到下一个窗口”,因此不会输出反引号。另外,即便在键盘配置中更改过快捷键,终端程序(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 -<!-- Deliberately not translated, leave it to a suitable translation --> - -<!--- - original document: 0.15.12:docs/feature_space_cadet.md - git diff 0.15.12 HEAD -- docs/feature_space_cadet.md | cat ---> - -*译注: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资料 - -<!--- - original document: 0.15.12:docs/flashing.md - git diff 0.15.12 HEAD -- docs/flashing.md | cat ---> - -用于键盘的bootloader有很多种,几乎每一种都在使用私有的刷写协议及工具。幸运的是,形如[QMK工具箱](https://github.com/qmk/qmk_toolbox/releases)这样的工程目标就是尽量支持这些工具,本文会探讨各种bootloader的差异,以及可用的刷写方案。 - -针对基于AVR的键盘,QMK会自动检查所要刷写的 `.hex` 文件大小是否与在 `rules.mk` 中设置的 `BOOTLOADER` 值所匹配,同时会输出字节大小信息(及最大限制)。 - -同时也可以使用CLI工具刷写键盘,执行: -``` -$ qmk flash -kb <keyboard> -km <keymap> -``` -更多信息参见文档[`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主控板上,就不必要设置到键映射或是用户级<!--译:不清楚这里的“user level”是个啥……-->了。 - -兼容的刷写工具: - -* [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刷写指引及资料 - -<!--- - original document: 0.15.12:docs/flashing_bootloadhid.md - git diff 0.15.12 HEAD -- docs/flashing_bootloadhid.md | cat ---> - -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 <keyboard>:<keymap>: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快速上手指引 - -<!--- - original document: 0.15.12:docs/getting_started_docker.md - git diff 0.15.12 HEAD -- docs/getting_started_docker.md | cat ---> - -本工程包含了一套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 <keyboard>:<keymap> -# 例: 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 - -<!--- - original document: 0.15.12:docs/getting_started_github.md - git diff 0.15.12 HEAD -- docs/getting_started_github.md | cat ---> - -对不熟悉 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 @@ -# 介绍 - -<!--- - original document: 0.15.12:docs/getting_started_introduction.md - git diff 0.15.12 HEAD -- docs/getting_started_introduction.md | cat ---> - -本页解释了使用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/<keyboard>/config.h`) -* 用户空间 (`/users/<user>/config.h`) -* 布局 (`/keyboards/<keyboard>/keymaps/<keymap>/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 @@ -# 手工搭建指南 - -<!--- - original document: 0.15.17:docs/hand_wire.md - git diff 0.15.17 HEAD -- docs/hand_wire.md | cat ---> - -## 模块清单 - -你需要的模块有:(*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 外其余无差别。 - -一些主控板专门为手工接线设计,除可直接连接少量开关外还有额外的引脚,但这些通常会更贵一些,也更难掌控。 - -<img src="https://i.imgur.com/QiA3ta6.jpg" alt="实装的 Postage mini 主控板" width="500"/> - -| 控制器板 | 控制器方案 | # 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)) - - -### 焊接 - -你可以找到很多焊接指导及技巧,这里列出了最相关及最关键的部分: - -要想焊接的牢固需要确保焊料与焊接两端的金属面充分地接触,一个好办法(也不是必须)是上锡前先(将线缆)在针脚上绕一圈或先拧在一起。 - -<img src="https://i.imgur.com/eHJjmnU.jpg" alt="杆上绕圈" width="200"/> <img src="https://i.imgur.com/8nbxmmr.jpg?1" alt="绕环的二极管引脚" width="200"/> - -如果二极管还在包装条上且需要弯折(作为绕圈的起点处或用于连接到邻接处),一个简便的办法是找一个盒子、桌子或尺子的直边上进行弯折。由于弯折统一在二极管一侧,也有助于区分二极管的方向。 - -<img src="https://i.imgur.com/oITudbX.jpg" alt="弯折二极管引脚" width="200"/> - -如果你的电烙铁有温控功能,将其设置在 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 - 其它所有引脚都是可以用且也能在固件中访问的到的。 - ----- - - -将电线切割为控制器到各行/列上某一点距离的长度。可以焊到各行的任意位置上,只需要确保是在二极管之后 - 焊接到二极管前面(轴脚侧)的话该行将无法正常使用。 - -这里用排线的话会显得非常整洁,你也可以考虑如何排布线缆以连接到各行/列的近处。 - -<img src="https://i.imgur.com/z2QlKfB.jpg" alt="排线" width="350"/> - -在往控制器上焊接电线时,请记住各引脚连接的是哪一行/列,在后续制作固件时我们需要用到这些信息来定义矩阵。 - -在你往下继续以前,请确保控制器已装配到位 - 切掉线缆再重新焊接非常麻烦! - - -## 一些基础的固件配置 - -至此,在你构建好固件后,键盘就应该能正常工作了。 - -通过 [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. 检查 `<project_name>.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 @@ -# 键映射总览 - -<!--- - original document: 0.15.12:docs/keymap.md - git diff 0.15.12 HEAD -- docs/keymap.md | cat ---> - -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 - -<!--- - original document: 0.15.12:docs/mod_tap.md - git diff 0.15.12 HEAD -- docs/mod_tap.md | cat ---> - -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入门教程 - -<!--- - original document: 0.15.12:docs/newbs.md - git diff 0.15.12 HEAD -- docs/newbs.md | cat ---> - -就像计算机一样,每把键盘里也有一个处理器,它的职责是在你点击键盘时,检测到这个动作并反馈给计算机。QMK固件即是为了这个目的而设计的一种"软件",负责检测点击,反馈给电脑。当你构建出一个自定义键映射时,就是在创建一个新的键盘"软件"。 - -QMK的愿景是提供强有力的功能,让不可能的事情变得可能,简单的事情依旧简单。即便是不会编程也可以创建强大的键映射方案。 - -想知道你的键盘是否能运行QMK?如果这个键盘是你自己组建的,那么很可能是可以的。我们[已经支持很多键盘](https://qmk.fm/keyboards/),所以即便你的键盘不能运行QMK,你也很容易能买到满足要求的键盘。 - -?> **这份指南适合于我吗?**<br> -编程对你是个困难的话,可以看看我们的[在线GUI页面](zh-cn/newbs_building_firmware_configurator.md)。</div> - -## 总览 - -这份指南适用于想通过源代码编译出键盘固件的需求。对于程序员,全过程都会感觉很熟悉。教程主要分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 @@ -# 构建第一个固件 - -<!--- - original document: 0.15.12:docs/newbs_building_firmware.md - git diff 0.15.12 HEAD -- docs/newbs_building_firmware.md | cat ---> - -现在您已经准备好了构建环境,就可以开始构建自定义固件了。在这节指南中,我们将在3个程序中开展工作——文件管理器、文本编辑器和终端。在做出心满意足的固件前,请不要关闭它们。 -## 新建键映射 - -也许你会考虑从默认键映射复制一份来开始,如果你遵循编译环境配置指南到了最后,那么使用QMK命令行可以简单地做到: - - qmk new-keymap - -如果你的环境没有那样配置,或者你有多个键盘要做,可以指定键盘名: - - qmk new-keymap -kb <keyboard_name> - -检查命令行输出,应该类似于: - - Ψ <github_username> keymap directory created in: /home/me/qmk_firmware/keyboards/clueboard/66/rev3/keymaps/<github_username> - -上面就是创建出的新 `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 <keyboard> -km <keymap> - -编译完成后,会输出详尽的编译产出文件信息,其末尾应该看起来像这样: - -``` -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配置器 - -<!--- - original document: 0.15.12:docs/newbs_building_firmware_configurator.md - git diff 0.15.12 HEAD -- docs/newbs_building_firmware_configurator.md | cat ---> - -[![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 @@ -# 刷写键盘固件 - -<!--- - original document: 0.15.12:docs/newbs_flashing.md - git diff 0.15.12 HEAD -- docs/newbs_flashing.md | cat ---> - -在自定义的固件文件构建出来后,可以刷写到键盘中了。 - -## 将键盘调至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上,使用下面的指令可以快速打开当前目录。 - -<!-- tabs:start --> - -#### ** Windows ** - -``` -start . -``` - -#### ** macOS ** - -``` -open . -``` - -<!-- tabs:end --> - -固件文件的文件名格式为: - -``` -<keyboard_name>_<keymap_name>.{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 @@ -# 配置环境 - -<!--- - original document: 0.15.12:docs/newbs_getting_started.md - git diff 0.15.12 HEAD -- docs/newbs_getting_started.md | cat ---> - -构建键映射前,有一些必须安装配置的构建工具,但无论你要编译多少个固件,这一步只需要做一次。 - -## 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来安装。 - -<!-- tabs:start --> - -### ** Windows ** - -QMK有维护一套基于MSYS2的软件包,所有命令行程序和依赖都是齐备的。通过 `QMK MSYS` 快捷命令可以快速启动开发环境。 - -#### 依赖项 - -需安装[QMK MSYS](https://msys.qmk.fm/),最新版在[这里](https://github.com/qmk/qmk_distro_msys/releases/latest)。 - -此外,如果想自行安装MSYS2环境,下面给出了具体的步骤。 - -<details> - <summary>自行安装</summary> - -?> 若决定使用 `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 - -</details> - -### ** 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"` 可以显示这份指引)。 - -<!-- tabs:end --> - -## 3. 执行QMK配置 :id=set-up-qmk -*译注:由于setup过程中需要从github clone依赖项,请先确保科学上网* - -<!-- tabs:start --> - -### ** 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` 就行了。 - -<!-- tabs:end --> - -?> QMK的home目录可以在安装时通过 `qmk setup -H <path>` 来指定,安装后也可以通过[命令行程序来配置](zh-cn/cli_configuration.md?id=single-key-example)`user.qmk_home`变量,可以通过 `qmk setup --help` 查看所有可用配置。 - -?> 若你熟悉GitHub,[推荐阅读这份指引](zh-cn/getting_started_github.md)通过 `qmk setup <github_username>/qmk_firmware` 来clone你自己的fork。如果你看不懂这一段啥意思,忽略就是了。 - -## 4. 测试你的构建环境 - -QMK构建环境搭建完成,可以尝试构建一个键盘固件。使用以下指令格式,先试试编译默认提供的键映射: - - qmk compile -kb <keyboard> -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=<github_username> - -完成后,这些配置就不用管了,编译键盘固件就可以直接这样执行: - - 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最佳实践 - -<!--- - original document: 0.15.17:docs/newbs_git_best_practices.md - git diff 0.15.17 HEAD -- docs/newbs_git_best_practices.md | cat ---> - -*译者注:对于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 @@ -# 解决合并冲突 - -<!--- - original document: 0.15.17:docs/newbs_git_resolving_merge_conflicts.md - git diff 0.15.17 HEAD -- docs/newbs_git_resolving_merge_conflicts.md | cat ---> - -有时在你致力于一个较长周期才能完成的分支时,其它人提交的变更会与你提交的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 <conflicted_files>", then run "git rebase --continue". -You can instead skip this commit: run "git rebase --skip". -To abort and get back to the state before "git rebase", run "git rebase --abort". -``` - -以上内容是在告诉我们有合并冲突存在,并给出了冲突所在的文件名。在编辑器中打开该文件,可以在某处发现类似如下形式的内容: - -``` -<<<<<<< HEAD -<p>For help with any issues, email us at [email protected].</p> -======= -<p>Need help? Email [email protected].</p> ->>>>>>> Commit #1 -``` - -`<<<<<<< HEAD` 标记了合并冲突的起始行,直至 `>>>>>>> Commit #1` 标记的结束行,中间通过 `=======` 分隔开冲突双方。其中 `HEAD` 部分为QMK主干上的版本,标记了提交日志的部分为当前分支的本地提交。 - -由于Git存储的是*文件差异部分*而非整个文件,所以当Git无法在文件中找到一个变更发生前的内容时,就无法知道如何去进行文件变更,重新编辑一下可以解决问题。在更改完成后,保存文件。 - -``` -<p>Need help? Email [email protected].</p> -``` - -之后,执行: - -``` -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分支 - -<!--- - original document: 0.15.17:docs/newbs_git_resynchronize_a_branch.md - git diff 0.15.17 HEAD -- docs/newbs_git_resynchronize_a_branch.md | cat ---> - -假设你在自己的 `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/<your_username>/qmk_firmware.git (fetch) -origin https://github.com/<your_username>/qmk_firmware.git (push) -upstream https://github.com/qmk/qmk_firmware.git (fetch) -upstream https://github.com/qmk/qmk_firmware.git (push) -``` - -如果你只能看到一个仓库: - -``` -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/<your_username>/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的主干上:频繁更新,不要提交 - -<!--- - original document: 0.15.17:docs/newbs_git_using_your_master_branch.md - git diff 0.15.17 HEAD -- docs/newbs_git_using_your_master_branch.md | cat ---> - -我们强烈推荐所有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 <name> <url>`, `<name>` 是远程仓库的简写名称,这个名称可以在很多Git命令中使用,包括但不限于 `fetch`,`pull` 及 `push`,以指定目标远程仓库。 - -要验证是否添加成功,可以执行 `git remote -v`,输出应该类似于: - -``` -$ git remote -v -origin https://github.com/<your_username>/qmk_firmware.git (fetch) -origin https://github.com/<your_username>/qmk_firmware.git (push) -upstream https://github.com/qmk/qmk_firmware.git (fetch) -upstream https://github.com/qmk/qmk_firmware.git (push) -``` - -在以上操作完成后,可以通过执行 `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 @@ -# 学习资源 - -<!--- - original document: 0.15.12:docs/newbs_learn_more_resources.md - git diff 0.15.12 HEAD -- docs/newbs_learn_more_resources.md | cat ---> - -这些资源旨在让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)<br> -* [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 @@ -# 测试和调试 - -<!--- - original document: 0.15.12:docs/newbs_testing_debugging.md - git diff 0.15.12 HEAD -- docs/newbs_testing_debugging.md | cat ---> -## 测试 - -[已移到这里](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开发环境 - -<!--- - original document: 0.15.16:docs/other_eclipse.md - git diff 0.15.16 HEAD -- docs/other_eclipse.md | cat ---> - - -[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` 目录)。 - -## 首次运行 -在安装完毕后,点击<kbd>运行</kbd>按钮。(如果是手动解压的,请在安装目录下双击 `eclipse` 可执行程序 - -在提示你选择工作区目录时,选择一个可用于存储Eclipse元数据及工程的目录。**不要选择 `qmk_firmware` 目录**,这是你的项目目录。可以使用其父目录,或其它(最好是空)目录(默认目标目录如果未作他用亦可使用)。 - -启动后,点击右上角的<kbd>工作台(Workbench)</kbd>按钮切换到工作台视图(启动时的欢迎页最下方有个确认框可以在下次启动时不再展示欢迎页)。 - -## 安装必要的插件 -注意:无需在每个插件安装完成时重启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. 打开<kbd>帮助</kbd> > <kbd>Eclipse插件市场…</kbd> -2. 搜索_ANSI Escape in Console_ -3. 点击插件的<samp>安装</samp>按钮 -4. 跟随安装指引并再次允许那些未签名的内容产生的警告。 - -在插件皆安装完毕后,依照提示重启Eclipse。 - -# 配置Eclipse QMK环境 -## 导入工程 -1. 点击<kbd>文件</kbd> > <kbd>新建</kbd> > <kbd>现有的Makefile工程代码</kbd> -2. 在之后这一页中: - * 选择仓库所克隆到的目录位置作为 _现有代码位置_; - * (可选地)指定一个不同的工程名,如 _QMK_ 或 _Quantum_ ; - * 选择 _AVR-GCC Toolchain_; - * 其它选项保留不动,点击<kbd>完成</kbd> - - ![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开发环境 - -<!--- - original document: 0.15.12:docs/other_vscode.md - git diff 0.15.12 HEAD -- docs/other_vscode.md | cat ---> - -[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. 点击 <kbd><kbd>文件</kbd> > <kbd>首选项 ></kbd> > <kbd>设置</kbd> </kbd> -2. 点击上方右侧的 <kbd>{}</kbd> 按钮,打开 `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-<code>`</code> (Grave) 或在 <kbd><kbd>视图</kbd> > <kbd>终端</kbd></kbd> 可以打开终端界面 (`workbench.action.terminal.toggleTerminal` 命令)。如果没有终端它会自动打开一个。 - - 终端应启动于工程目录中(即 `qmk_firmware` 目录),之后你可以构建键盘了。 - - -## 其它系统 - -1. 到[VS Code](https://code.visualstudio.com/)下载安装包 -2. 运行安装包 -3. 搞定 - -是的,确实是搞定了。安装的时候所有所需的路径配置都会被包含进来,在检查当前工程文件并进行IntelliSense解析上表现也会更好。 - -## 插件 - -有一些你可能感兴趣的扩展可以安装:<!-- 老外自己也分不清plugin和extension啊-_-||| --> - -* [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. 点击 <kbd><kbd>文件</kbd> > <kbd>打开目录</kbd></kbd> -2. 打开你从Github克隆的QMK固件仓库所在目录。 -3. 点击 <kbd><kbd>文件</kbd> > <kbd>保存工作区为...</kbd></kbd> - -此时你已完成了在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配置器中支持您的键盘 - -<!--- - original document: 0.15.12:docs/reference_configurator_support.md - git diff 0.15.12 HEAD -- docs/reference_configurator_support.md | cat ---> - -本章节详述了如何在[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/<keyboard>/<keyboard>.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术语表 - -<!--- - original document: 0.15.12:docs/reference_glossary.md - git diff 0.15.12 HEAD -- docs/reference_glossary.md | cat ---> - -## 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 @@ -# 寻求帮助 - -<!--- - original document: 0.15.12:docs/support.md - git diff 0.15.12 HEAD -- docs/support.md | cat ---> - -你可以从很多渠道获取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大纲 - -<!--- - original document: 0.15.12:docs/syllabus.md - git diff 0.15.12 HEAD -- docs/syllabus.md | cat ---> - -这一页旨在帮你建立关于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主要功能内部原理的话题。你可以不用阅读这些,然而,跳过这些话题的话,去看高级话题的时候会让你很迷惑。 - -* **各功能的配置** - <!-- * Configuration Overview FIXME(skullydazed/anyone): write this document --> - * [音频](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文档 - -<!--- - original document: 0.15.12:docs/translating.md - git diff 0.15.12 HEAD -- docs/translating.md | cat ---> - -根目录下(`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 |