docs/zh-cn/newbs_flashing.md

   1 # 刷新你的键盘
   2
   3 现在您已经构建了一个自定义固件文件，那么您就需要刷新键盘了。
   4
   5 ## 用QMK工具箱刷新键盘
   6
   7 刷新键盘的最简单方法是使用[QMK 工具箱](https://github.com/qmk/qmk_toolbox/releases).
   8
   9 但是，QMK工具箱目前仅适用于Windows和MacOS。如果您使用的是Linux（或者只是希望从命令行刷新固件），则必须使用 [方法概述](newbs_flashing.md#flash-your-keyboard-from-the-command-line).
  10
  11 ### 将文件加载到QMK工具箱中
  12
  13 首先打开QMK工具箱应用程序。您将要在访达或资源管理器中找到固件文件。您的键盘固件可能是两种格式之一`.hex`或`.bin`。qmk会尝试将键盘的相应文件复制到“qmk_firmware”根目录中。
  14
  15 ?> 如果您在Windows或MacOS上，可以使用以下命令轻松地在资源管理器或访达中打开当前固件文件夹。
  16
  17 ?> Windows:
  18
  19     start .
  20
  21 ?> macOS:
  22
  23     open .
  24
  25 固件文件始终遵循此命名格式:
  26
  27     <keyboard_name>_<keymap_name>.{bin,hex}
  28
  29 例如，使用 `default` 布局的 `plank/rev5` 将使用以下名字：
  30
  31     planck_rev5_default.hex
  32
  33 找到固件文件后，将其拖到QMK工具箱中的“Local file”框中，或单击“Open”并导航到固件文件的存储位置。
  34
  35 ### 将键盘置于DFU（Bootloader）模式
  36
  37 要刷新自定义固件，您必须将键盘置于特殊的刷新模式。在此模式下，您将无法键入或使用键盘。在写入固件时，不要拔下键盘插头或以其他方式中断刷新过程，这一点非常重要。
  38
  39 不同的键盘有不同的方式进入这种特殊模式。如果您的键盘当前运行的是QMK或TMK，而您没有得到特定的指示，请按顺序尝试以下操作:
  40
  41 * 按住两个shift键并按 `Pause`
  42 * 按住两个shift键并按 `B`
  43 * 拔下键盘插头, 同时按住空格键和 `B` , 插上键盘然后等一会再放开按键
  44 * 按下PCB底部的 `RESET` 物理键
  45 * 找到PCB上标记有 `BOOT0` 或 `RESET`的金属点, 在插入PCB的同时短接它们
  46
  47 成功后，您将在QMK工具箱中看到类似以下内容的消息:
  48
  49 ```
  50 *** Clueboard - Clueboard 66% HotSwap disconnected -- 0xC1ED:0x2390
  51 *** DFU device connected
  52 ```
  53
  54 ### 刷新你的键盘
  55
  56 单击QMK工具箱中的 `Flash` 按钮。您将看到类似以下内容的输出:
  57
  58 ```
  59 *** Clueboard - Clueboard 66% HotSwap disconnected -- 0xC1ED:0x2390
  60 *** DFU device connected
  61 *** Attempting to flash, please don't remove device
  62 >>> dfu-programmer atmega32u4 erase --force
  63     Erasing flash...  Success
  64     Checking memory from 0x0 to 0x6FFF...  Empty.
  65 >>> dfu-programmer atmega32u4 flash /Users/skully/qmk_firmware/clueboard_66_hotswap_gen1_skully.hex
  66     Checking memory from 0x0 to 0x55FF...  Empty.
  67     0%                            100%  Programming 0x5600 bytes...
  68     [>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>]  Success
  69     0%                            100%  Reading 0x7000 bytes...
  70     [>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>]  Success
  71     Validating...  Success
  72     0x5600 bytes written into 0x7000 bytes memory (76.79%).
  73 >>> dfu-programmer atmega32u4 reset
  74
  75 *** DFU device disconnected
  76 *** Clueboard - Clueboard 66% HotSwap connected -- 0xC1ED:0x2390
  77 ```
  78
  79 ## 使用命令行刷新键盘
  80
  81 首先，您需要知道您的键盘使用的是哪个bootloader。通常是以下四个常见的bootloader。Pro-Micro 和 clones 使用 CATERINA, Teensy 使用 Halfkay, OLKB 键盘使用 QMK-DFU, 其他的atmega32u4芯片使用DFU。
  82
  83 您可以在以下文章中了解更多关于bootloader[刷新指令和Bootloader信息](flashing.md)。
  84
  85 如果您知道正在使用的bootloader是哪种，那么在编译固件时，可以向“make”命令里添加一些额外参数，以自动执行刷新过程。
  86
  87 ### DFU
  88
  89 对于DFU引导加载程序，当您准备好编译和刷新固件时，打开终端窗口并运行构建命令:
  90
  91     make <my_keyboard>:<my_keymap>:dfu
  92
  93 例如，如果您的布局名为“xyverz”，并且您正在为rev5 planck构建一个布局，那么您可以使用此命令：
  94
  95     make planck/rev5:xyverz:dfu
  96
  97 编译完成后，应输出以下内容：
  98
  99 ```
 100 Linking: .build/planck_rev5_xyverz.elf                                                              [OK]
 101 Creating load file for flashing: .build/planck_rev5_xyverz.hex                                      [OK]
 102 Copying planck_rev5_xyverz.hex to qmk_firmware folder                                               [OK]
 103 Checking file size of planck_rev5_xyverz.hex
 104  * File size is fine - 18574/28672
 105  ```
 106
 107 到了这个时候, 构建脚本将每隔5秒查找一次DFU。它将重复以下操作，直到找到设备或将其取消。
 108
 109     dfu-programmer: no device present.
 110     Error: Bootloader not found. Trying again in 5s.
 111
 112 一旦出现以上回显，您将需要重置控制器。然后，它应该显示与以下类似的输出：
 113
 114 ```
 115 *** Attempting to flash, please don't remove device
 116 >>> dfu-programmer atmega32u4 erase --force
 117     Erasing flash...  Success
 118     Checking memory from 0x0 to 0x6FFF...  Empty.
 119 >>> dfu-programmer atmega32u4 flash /Users/skully/qmk_firmware/clueboard_66_hotswap_gen1_skully.hex
 120     Checking memory from 0x0 to 0x55FF...  Empty.
 121     0%                            100%  Programming 0x5600 bytes...
 122     [>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>]  Success
 123     0%                            100%  Reading 0x7000 bytes...
 124     [>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>]  Success
 125     Validating...  Success
 126     0x5600 bytes written into 0x7000 bytes memory (76.79%).
 127 >>> dfu-programmer atmega32u4 reset
 128 ```
 129
 130 如果您对此有任何问题，您可能需要这样做：
 131
 132     sudo make <my_keyboard>:<my_keymap>:dfu
 133
 134 #### DFU命令
 135
 136 有许多DFU命令可用于将固件下载到DFU设备：
 137
 138 * `:dfu` - 这是正常选项，等待DFU设备可用，然后刷新固件。这将每隔5秒检查一次，以查看是否出现了DFU设备。
 139 * `:dfu-ee` - 这将刷新一个`eep`文件，而不是普通的十六进制文件。这很不常见。
 140 * `:dfu-split-left` - 这将刷新正常固件，就像默认选项 (`:dfu`)一样. 但是，这也会刷新“左侧”EEPROM文件，用于分割键盘。 _这是基于Elite C的键盘的推荐选择。_
 141 * `:dfu-split-right` - 这将刷新正常固件，就像默认选项(`:dfu`). 但是，这也会刷新“右侧”EEPROM文件，用于分割键盘。 _这是基于Elite C的键盘的推荐选择。_
 142
 143
 144 ### Caterina
 145
 146 对于Arduino板以及其克隆版来说(比如SparkFun和ProMicro), 准备好编译和刷新固件后，打开终端窗口并运行构建命令:
 147
 148     make <my_keyboard>:<my_keymap>:avrdude
 149
 150 比如, 你的布局叫"xyverz"你要创建一个rev2 Lets Split的布局,你要用以下命令:
 151
 152     make lets_split/rev2:xyverz:avrdude
 153
 154 固件完成编译后，它将输出类似以下的内容:
 155
 156 ```
 157 Linking: .build/lets_split_rev2_xyverz.elf                                                            [OK]
 158 Creating load file for flashing: .build/lets_split_rev2_xyverz.hex                                    [OK]
 159 Checking file size of lets_split_rev2_xyverz.hex                                                      [OK]
 160  * File size is fine - 27938/28672
 161 Detecting USB port, reset your controller now..............
 162 ```
 163
 164 此时，复位，然后脚本将检测bootloader，然后刷新固件。输出应该像这样:
 165
 166 ```
 167 Detected controller on USB port at /dev/ttyS15
 168
 169 Connecting to programmer: .
 170 Found programmer: Id = "CATERIN"; type = S
 171     Software Version = 1.0; No Hardware Version given.
 172 Programmer supports auto addr increment.
 173 Programmer supports buffered memory access with buffersize=128 bytes.
 174
 175 Programmer supports the following devices:
 176     Device code: 0x44
 177
 178 avrdude.exe: AVR device initialized and ready to accept instructions
 179
 180 Reading | ################################################## | 100% 0.00s
 181
 182 avrdude.exe: Device signature = 0x1e9587 (probably m32u4)
 183 avrdude.exe: NOTE: "flash" memory has been specified, an erase cycle will be performed
 184              To disable this feature, specify the -D option.
 185 avrdude.exe: erasing chip
 186 avrdude.exe: reading input file "./.build/lets_split_rev2_xyverz.hex"
 187 avrdude.exe: input file ./.build/lets_split_rev2_xyverz.hex auto detected as Intel Hex
 188 avrdude.exe: writing flash (27938 bytes):
 189
 190 Writing | ################################################## | 100% 2.40s
 191
 192 avrdude.exe: 27938 bytes of flash written
 193 avrdude.exe: verifying flash memory against ./.build/lets_split_rev2_xyverz.hex:
 194 avrdude.exe: load data flash data from input file ./.build/lets_split_rev2_xyverz.hex:
 195 avrdude.exe: input file ./.build/lets_split_rev2_xyverz.hex auto detected as Intel Hex
 196 avrdude.exe: input file ./.build/lets_split_rev2_xyverz.hex contains 27938 bytes
 197 avrdude.exe: reading on-chip flash data:
 198
 199 Reading | ################################################## | 100% 0.43s
 200
 201 avrdude.exe: verifying ...
 202 avrdude.exe: 27938 bytes of flash verified
 203
 204 avrdude.exe: safemode: Fuses OK (E:CB, H:D8, L:FF)
 205
 206 avrdude.exe done.  Thank you.
 207 ```
 208 如果您对此有任何问题，您可能需要这样做：
 209
 210     sudo make <my_keyboard>:<my_keymap>:avrdude
 211
 212
 213 此外，如果要刷新多个板，请使用以下命令：
 214
 215     make <keyboard>:<keymap>:avrdude-loop
 216
 217 当你完成了刷新后，你需要按下ctrl+c或者其他正确的按键来让你的操作系统终止循环。
 218
 219
 220 ## HalfKay
 221
 222 对于PJRC设备（Teensy），当您准备好编译和刷新固件时，打开终端窗口并运行构建命令:
 223
 224     make <my_keyboard>:<my_keymap>:teensy
 225
 226 比如, 如果你的布局叫做"xyverz"你想创建Ergodox or Ergodox EZ的布局,你要使用以下命令:
 227
 228     make erdogox_ez:xyverz:teensy
 229
 230 固件完成编译后，它将输出如下内容：
 231
 232 ```
 233 Linking: .build/ergodox_ez_xyverz.elf                                                               [OK]
 234 Creating load file for flashing: .build/ergodox_ez_xyverz.hex                                       [OK]
 235 Checking file size of ergodox_ez_xyverz.hex                                                         [OK]
 236  * File size is fine - 25584/32256
 237  Teensy Loader, Command Line, Version 2.1
 238 Read "./.build/ergodox_ez_xyverz.hex": 25584 bytes, 79.3% usage
 239 Waiting for Teensy device...
 240  (hint: press the reset button)
 241  ```
 242
 243 此时，复位键盘。完成后，您将看到如下输出：
 244
 245  ```
 246  Found HalfKay Bootloader
 247 Read "./.build/ergodox_ez_xyverz.hex": 28532 bytes, 88.5% usage
 248 Programming............................................................................................................................................................................
 249 ...................................................
 250 Booting
 251 ```
 252
 253 ## STM32 (ARM)
 254
 255 对于大多数ARM板（包括Proton C、Planck Rev 6和Preonic Rev 3），当您准备好编译和刷新固件时，打开终端窗口并运行构建命令：
 256
 257     make <my_keyboard>:<my_keymap>:dfu-util
 258
 259 例如，如果您的keymap被命名为“xyverz”，并且您正在为Planck Revision 6键盘构建一个布局，那么您需要使用以下命令，然后将键盘重新启动到bootloader（在完成编译之前）：
 260
 261     make planck/rev6:xyverz:dfu-util
 262
 263 固件完成编译后，它将输出如下内容：
 264
 265 ```
 266 Linking: .build/planck_rev6_xyverz.elf                                                             [OK]
 267 Creating binary load file for flashing: .build/planck_rev6_xyverz.bin                               [OK]
 268 Creating load file for flashing: .build/planck_rev6_xyverz.hex                                     [OK]
 269
 270 Size after:
 271    text    data     bss     dec     hex filename
 272       0   41820       0   41820    a35c .build/planck_rev6_xyverz.hex
 273
 274 Copying planck_rev6_xyverz.bin to qmk_firmware folder                                              [OK]
 275 dfu-util 0.9
 276
 277 Copyright 2005-2009 Weston Schmidt, Harald Welte and OpenMoko Inc.
 278 Copyright 2010-2016 Tormod Volden and Stefan Schmidt
 279 This program is Free Software and has ABSOLUTELY NO WARRANTY
 280 Please report bugs to http://sourceforge.net/p/dfu-util/tickets/
 281
 282 Invalid DFU suffix signature
 283 A valid DFU suffix will be required in a future dfu-util release!!!
 284 Opening DFU capable USB device...
 285 ID 0483:df11
 286 Run-time device DFU version 011a
 287 Claiming USB DFU Interface...
 288 Setting Alternate Setting #0 ...
 289 Determining device status: state = dfuERROR, status = 10
 290 dfuERROR, clearing status
 291 Determining device status: state = dfuIDLE, status = 0
 292 dfuIDLE, continuing
 293 DFU mode device DFU version 011a
 294 Device returned transfer size 2048
 295 DfuSe interface name: "Internal Flash  "
 296 Downloading to address = 0x08000000, size = 41824
 297 Download        [=========================] 100%        41824 bytes
 298 Download done.
 299 File downloaded successfully
 300 Transitioning to dfuMANIFEST state
 301 ```
 302
 303 ## 试一试吧!
 304
 305 恭喜您! 您的自定义固件已经刷写到您的键盘
 306
 307 试一试，确保一切按你想的方式进行。我们写了[测试和调试](newbs_testing_debugging.md)来完善新手引导。 因此，请前往那里了解如何排除自定义功能的故障。