Documentation and tutorial are missing details on flashing

[WhyNotHugo]

Information

• None of the other issue templates apply

Description

I'm following the tutorial to flash a keyboard, and the instructions indicate I should use qmk flash -kb <my_keyboard> -km <my_keymap>.

I'm not entirely sure what these arguments should be:

$ qmk flash -kb moonlander -km ~/downloads/moonlander_moonlander_layout_moonlander_mine.bin
Ψ Compiling keymap with make --jobs=1 moonlander:/home/hugo/downloads/moonlander_moonlander_layout_moonlander_mine.bin:flash


QMK Firmware 0.14.31
Making moonlander with keymap default and target /home/hugo/downloads/moonlander_moonlander_layout_moonlander_mine.bin:flash [ERRORS]
make[1]: *** No rule to make target '/home/hugo/downloads/moonlander_moonlander_layout_moonlander_mine.bin:flash'.  Stop.
Making moonlander with keymap drashna and target /home/hugo/downloads/moonlander_moonlander_layout_moonlander_mine.bin:flash [ERRORS]
make[1]: *** No rule to make target '/home/hugo/downloads/moonlander_moonlander_layout_moonlander_mine.bin:flash'.  Stop.
Making moonlander with keymap jjerrell and target /home/hugo/downloads/moonlander_moonlander_layout_moonlander_mine.bin:flash [ERRORS]
make[1]: *** No rule to make target '/home/hugo/downloads/moonlander_moonlander_layout_moonlander_mine.bin:flash'.  Stop.
Making moonlander with keymap manna-harbour_miryoku and target /home/hugo/downloads/moonlander_moonlander_layout_moonlander_mine.bin:flash [ERRORS]
make[1]: *** No rule to make target '/home/hugo/downloads/moonlander_moonlander_layout_moonlander_mine.bin:flash'.  Stop.
Making moonlander with keymap shahn-neo and target /home/hugo/downloads/moonlander_moonlander_layout_moonlander_mine.bin:flash [ERRORS]
make[1]: *** No rule to make target '/home/hugo/downloads/moonlander_moonlander_layout_moonlander_mine.bin:flash'.  Stop.
Making moonlander with keymap via and target /home/hugo/downloads/moonlander_moonlander_layout_moonlander_mine.bin:flash [ERRORS]
make[1]: *** No rule to make target '/home/hugo/downloads/moonlander_moonlander_layout_moonlander_mine.bin:flash'.  Stop.
Make finished with errors
make: *** [Makefile:510: moonlander:/home/hugo/downloads/moonlander_moonlander_layout_moonlander_mine.bin:flash] Error 1

The help output doesn't say much, and there's no further documentation (e.g.: No man entry for qmk).

$ qmk help flash
usage: qmk [-h] [-V] [-v] [--datetime-fmt DATETIME_FMT] [--log-fmt LOG_FMT] [--log-file-fmt LOG_FILE_FMT]
           [--log-file-level {debug,info,warning,error,critical}] [--log-file LOG_FILE] [--color] [--no-color] [--unicode]
           [--no-unicode] [--interactive] [--config-file CONFIG_FILE]
           {config,clone,console,env,setup,c2json,cd,chibios-confmigrate,clean,compile,doctor,flash,generate-rgb-breathe-table,info,json2c,lint,list-keyboards,list-keymaps,list-layouts,new-keyboard,new-keymap}
           ...
qmk: error: argument {config,clone,console,env,setup,c2json,cd,chibios-confmigrate,clean,compile,doctor,flash,generate-rgb-breathe-table,info,json2c,lint,list-keyboards,list-keymaps,list-layouts,new-keyboard,new-keymap}: invalid choice: 'help' (choose from 'config', 'clone', 'console', 'env', 'setup', 'bux', 'c2json', 'cd', 'cformat', 'chibios-confmigrate', 'clean', 'compile', 'docs', 'doctor', 'fileformat', 'flash', 'format-c', 'format-json', 'format-python', 'format-text', 'generate-api', 'generate-config-h', 'generate-dfu-header', 'generate-docs', 'generate-info-json', 'generate-keyboard-h', 'generate-layouts', 'generate-rgb-breathe-table', 'generate-rules-mk', 'generate-version-h', 'hello', 'info', 'json2c', 'lint', 'list-keyboards', 'list-keymaps', 'list-layouts', 'kle2json', 'multibuild', 'new-keyboard', 'new-keymap', 'pyformat', 'pytest')

I tried looking through the source code, but there's no mentions of flash, and I got lost trying to follow how it all works.

I used qmk_configurator to create a layout and generated the moonlander_moonlander_layout_moonlander_mine.bin file mentioned above.

What parameters does the flash command take? I can try and write a PR with the missing details/steps on this so future newcomers don't get stuck on this too.

---

I tried compiling locally with qmk compile ~/downloads/moonlander_layout_moonlander_mine\(4\).json, and then running qmk flash --keyboard moonlander --keymap moonlander_layout_moonlander_mine (I copied these values from the json file), but that fails too:

$ qmk flash --keyboard moonlander --keymap moonlander_layout_moonlander_mine
Ψ Compiling keymap with make --jobs=1 moonlander:moonlander_layout_moonlander_mine:flash


QMK Firmware 0.14.31
Making moonlander with keymap default and target moonlander_layout_moonlander_mine:flash       [ERRORS]
make[1]: *** No rule to make target 'moonlander_layout_moonlander_mine:flash'.  Stop.
Making moonlander with keymap drashna and target moonlander_layout_moonlander_mine:flash       [ERRORS]
make[1]: *** No rule to make target 'moonlander_layout_moonlander_mine:flash'.  Stop.
Making moonlander with keymap jjerrell and target moonlander_layout_moonlander_mine:flash      [ERRORS]
make[1]: *** No rule to make target 'moonlander_layout_moonlander_mine:flash'.  Stop.
Making moonlander with keymap manna-harbour_miryoku and target moonlander_layout_moonlander_mine:flash [ERRORS]
make[1]: *** No rule to make target 'moonlander_layout_moonlander_mine:flash'.  Stop.
Making moonlander with keymap shahn-neo and target moonlander_layout_moonlander_mine:flash     [ERRORS]
make[1]: *** No rule to make target 'moonlander_layout_moonlander_mine:flash'.  Stop.
Making moonlander with keymap via and target moonlander_layout_moonlander_mine:flash           [ERRORS]
make[1]: *** No rule to make target 'moonlander_layout_moonlander_mine:flash'.  Stop.
Make finished with errors
make: *** [Makefile:510: moonlander:moonlander_layout_moonlander_mine:flash] Error 1

[WhyNotHugo]

Oh qmk flash --help had better output, my bad facepalm

This should work, but looks like I'm missing a step:

✘ qmk flash ~/downloads/moonlander_layout_moonlander_mine\(5\).json
Ψ Wrote keymap to /home/hugo/workspace/qmk/qmk_firmware/keyboards/moonlander/keymaps/moonlander_layout_moonlander_mine/keymap.c
Ψ Compiling keymap with make -s --jobs=1 -r -R -f build_keyboard.mk flash KEYBOARD=moonlander KEYMAP=moonlander_layout_moonlander_mine KEYBOARD_FILESAFE=moonlander TARGET=moonlander_moonlander_layout_moonlander_mine KEYBOARD_OUTPUT=.build/obj_moonlander KEYMAP_OUTPUT=.build/obj_moonlander_moonlander_layout_moonlander_mine MAIN_KEYMAP_PATH_1=.build/obj_moonlander_moonlander_layout_moonlander_mine MAIN_KEYMAP_PATH_2=.build/obj_moonlander_moonlander_layout_moonlander_mine MAIN_KEYMAP_PATH_3=.build/obj_moonlander_moonlander_layout_moonlander_mine MAIN_KEYMAP_PATH_4=.build/obj_moonlander_moonlander_layout_moonlander_mine MAIN_KEYMAP_PATH_5=.build/obj_moonlander_moonlander_layout_moonlander_mine KEYMAP_C=.build/obj_moonlander_moonlander_layout_moonlander_mine/src/keymap.c KEYMAP_PATH=.build/obj_moonlander_moonlander_layout_moonlander_mine/src VERBOSE=false COLOR=true SILENT=false QMK_BIN=qmk


arm-none-eabi-gcc (Arch Repository) 11.2.0
Copyright (C) 2021 Free Software Foundation, Inc.
This is free software; see the source for copying conditions.  There is NO
warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

Size before:
   text	   data	    bss	    dec	    hex	filename
      0	  62810	      0	  62810	   f55a	.build/moonlander_moonlander_layout_moonlander_mine.hex

Compiling: .build/obj_moonlander_moonlander_layout_moonlander_mine/src/keymap.c                     [OK]
Compiling: quantum/command.c                                                                        [OK]
Linking: .build/moonlander_moonlander_layout_moonlander_mine.elf                                    [OK]
Creating binary load file for flashing: .build/moonlander_moonlander_layout_moonlander_mine.bin     [OK]
Creating load file for flashing: .build/moonlander_moonlander_layout_moonlander_mine.hex            [OK]

Size after:
   text	   data	    bss	    dec	    hex	filename
      0	  62810	      0	  62810	   f55a	.build/moonlander_moonlander_layout_moonlander_mine.hex

Copying moonlander_moonlander_layout_moonlander_mine.bin to qmk_firmware folder                     [OK]
Bootloader not found. Trying again every 0.5s (Ctrl+C to cancel)..........................................^Cmake: *** [platforms/chibios/flash.mk:84: flash] Interrupt

[fauxpark]

qmk flash cannot flash arbitrary firmware files, it only accepts a keyboard and keymap name which exist in qmk_firmware/keyboards/ (or a Configurator export). You need to use the Toolbox or run the flashing commands directly.

[WhyNotHugo]

Ah, so it seems that using qmk flash ~/downloads/moonlander_layout_moonlander_mine\(5\).json did work.

The Bootloader not found. Trying again every 0.5s meant that my keyboard was not in DFU mode.

I'll try and write a short PR to clarify both items in case anyone else stumbles across this.

You need to use the Toolbox

AFAIK, that's only for Window and Mac, but I've no devices running either.

or run the flashing commands directly.

Isn't qmk flash the flashing command?

[fauxpark]

Isn't qmk flash the flashing command?

The Toolbox and qmk flash simply run the appropriate external flashing tool based on the connected bootloader device (for the former) or the bootloader specified for the keyboard/keymap being compiled (for the latter).

https://docs.qmk.fm/#/flashing

[WhyNotHugo]

I see the same file is present in two places:

https://github.com/qmk/qmk_firmware/blob/9dea6f772077dc5c09daf40378e45884d29ab2e2/docs/newbs_flashing.md?plain=1

https://github.com/qmk/qmk_mkdocs/blob/2f86c7e2639e459d3965a20bdb809d8df9869725/docs/en/docs/tutorial_flashing.md?plain=1

I'm not sure which one is current; which one should I update? I assume that one is deprecated, but can't figure out which one.

[stale]

This issue has been automatically marked as stale because it has not had activity in the last 90 days. It will be closed in the next 30 days unless it is tagged properly or other activity occurs.
For maintainers: Please label with bug, in progress, on hold, discussion or to do to prevent the issue from being re-flagged.

[github-actions]

This issue has been automatically closed because it has not had activity in the last 30 days. If this issue is still valid, re-open the issue and let us know.
// [stale-action-closed]

[Am3ra]

I'm also having issues with this, the documentation is somewhat sparse when it comes to using hex files through the cli