{"id":3817,"date":"2023-06-05T14:05:53","date_gmt":"2023-06-05T13:05:53","guid":{"rendered":"https:\/\/pmortensen.eu\/world2\/?p=3817"},"modified":"2026-06-15T17:25:20","modified_gmt":"2026-06-15T16:25:20","slug":"dfu-util-gotcha-always-use-a-0","status":"publish","type":"post","link":"https:\/\/pmortensen.eu\/world2\/2023\/06\/05\/dfu-util-gotcha-always-use-a-0\/","title":{"rendered":"Flash utility ‘dfu-util’ gotcha: Always use option ‘-a 0’"},"content":{"rendered":"

dfu-util<\/a> can be used to both read off and to flash (update) firmware on embedded devices, say for the firmware on a QMK<\/a>-based keyboard like the Keychron V5<\/a> (about 50 KB). But it is very poorly documented. In most cases, the option “-a 0” must be included.<\/p>\n

The problem<\/h2>\n

An unintrusive first try is to read off the firmware:<\/p>\n

\r\ndfu-util -U someKeychronV5firmwareVersion.bin\r\n<\/pre>\n
But this results in:<\/p>\n
\r\ndfu-util: More than one DFU capable USB device\r\nfound! Try `--list' and specify the serial\r\nnumber or disconnect all but one device\r\n<\/pre>\n
But this is a totally misleading error message<\/em><\/strong>… There is only one DFU device connected (and in DFU mode). This is confirmed by using the -l<\/em><\/strong> parameter to discover the DFU devices:<\/p>\n
\r\ndfu-util -l\r\n<\/pre>\n
Output:<\/p>\n
\r\ndfu-util 0.9\r\n\r\nFound DFU: [0483:df11] ver=2200, devnum=7, cfg=1, intf=0, path="3-1", alt=3, name="@Device Feature\/0xFFFF0000\/01*004 e", serial="205C32845242"\r\nFound DFU: [0483:df11] ver=2200, devnum=7, cfg=1, intf=0, path="3-1", alt=2, name="@OTP Memory \/0x1FFF7000\/01*0001Ke", serial="205C32845242"\r\nFound DFU: [0483:df11] ver=2200, devnum=7, cfg=1, intf=0, path="3-1", alt=1, name="@Option Bytes  \/0x1FFF7800\/01*040 e", serial="205C32845242"\r\nFound DFU: [0483:df11] ver=2200, devnum=7, cfg=1, intf=0, path="3-1", alt=0, name="@Internal Flash  \/0x08000000\/0128*0002Kg", serial="205C32845242"\r\n<\/pre>\n
The serial number, 205C32845242, is exactly the same for all four lines. The four are (directly from the output):<\/p>\n\n\n\n\n\n\n
Area<\/th>\nStart address<\/th>\nSize<\/th>\nAlt<\/th>\n<\/tr>\n
    <\/p>\n
Device Feature<\/td>\n0xFFFF0000<\/td>\n01*004 e<\/td>\nalt=3<\/td>\n<\/tr>\n
OTP Memory<\/td>\n0x1FFF7000<\/td>\n01*0001Ke<\/td>\nalt=2<\/td>\n<\/tr>\n
Option Bytes<\/td>\n0x1FFF7800<\/td>\n01*040 e<\/td>\nalt=1<\/td>\n<\/tr>\n
Internal Flash<\/td>\n0x08000000<\/td>\n0128*0002Kg<\/td>\nalt=0<\/td>\n<\/tr>\n
    <\/p>\n<\/table>\n
<\/p>\n
The size is in a cryptic format. In this case, it is known the microcontroller is STM32L432<\/a> and the flash size is 128 KB (output as “0128*0002Kg”).<\/p>\n
A distinguishing field is the “alt” field.<\/p>\n
The documentation is in the usual cryptic style: “Specify the altsetting of the DFU interface by name or by number.”<\/p>\n
The solution<\/h2>\n
It is not documented (or at least very indirectly and cryptically), but the “-a” option must be used. In this case, “-a 0” as the flash part has “alt=0” (the “alt” in the output correspond). <\/p>\n
For reading off the firmware:<\/p>\n
\r\ndfu-util -a 0 -s 0x08000000:0x20000 -U someKeychronV5firmwareVersion.bin\r\n<\/pre>\n
For flashing:<\/p>\n
\r\ndfu-util -a 0 --dfuse-address 0x08000000 -D keychron_v5_iso_encoder_keychron_standardMacros.bin\r\n<\/pre>\n
Output, respectively (note that “upload” is using the convention from embedded devices where it is seen from the device’s perspective – upload from the device to host (computer) for reading off the flash memory):<\/p>\n
\r\ndfu-util 0.9\r\n\r\nOpening DFU capable USB device...\r\nID 0483:df11\r\nRun-time device DFU version 011a\r\nClaiming USB DFU Interface...\r\nSetting Alternate Setting #0 ...\r\nDetermining device status: state = dfuERROR, status = 10\r\ndfuERROR, clearing status\r\nDetermining device status: state = dfuIDLE, status = 0\r\ndfuIDLE, continuing\r\nDFU mode device DFU version 011a\r\nDevice returned transfer size 2048\r\nLimiting default upload to 16384 bytes\r\nUpload\t[=========================] 100%        16384 bytes\r\nUpload done.\r\n<\/pre>\n
\r\ndfu-util 0.11\r\n\r\nMatch vendor ID from file: 0483\r\nMatch product ID from file: df11\r\nOpening DFU capable USB device...\r\nDevice ID 0483:df11\r\nDevice DFU version 011a\r\nClaiming USB DFU Interface...\r\nSetting Alternate Interface #0 ...\r\nDetermining device status...\r\nDFU state(10) = dfuERROR, status(10) = Device's firmware is corrupt. It cannot return to run-time (non-DFU) operations\r\nClearing status\r\nDetermining device status...\r\nDFU state(2) = dfuIDLE, status(0) = No error condition is present\r\nDFU mode device DFU version 011a\r\nDevice returned transfer size 2048\r\nDfuSe interface name: "Internal Flash  "\r\nDownloading element to address = 0x08000000, size = 48076\r\nErase   \t[=========================] 100%        48076 bytes\r\nErase    done.\r\nDownload\t[=========================] 100%        48076 bytes\r\nDownload done.\r\nFile downloaded successfully\r\n<\/pre>\n
A bonus: Relieve strain on the USB cables…<\/h2>\n
By default, dfu-util will leave the device in bootloader mode after flashing. To avoid having to power cycle the device, use modifier “:leave” in the argument for –dfuse-address:<\/p>\n
\r\ndfu-util -a 0 --dfuse-address 0x08000000:leave -D keychron_v5_iso_encoder_keychron_standardMacros.bin\r\n<\/pre>\n
Installing dfu-util<\/h2>\n
dfu-util has probably been installed as part of installing QMK (it is part of the dependencies for it<\/a>), but on a pristine system, it can installed by:<\/p>\n
<\/p>\n
\r\nsudo apt-get install dfu-util\r\n<\/pre>\n
It can also be installed from source<\/a> (near “without a dfu-util package”<\/em>).<\/p>\n
<\/p>\n","protected":false},"excerpt":{"rendered":"
dfu-util can be used to both read off and to flash (update) firmware on embedded devices, say for the firmware on a QMK-based keyboard like the Keychron V5 (about 50 KB). But it is very poorly documented. In most cases, the …<\/p>\n
  Flash utility ‘dfu-util’ gotcha: Always use option ‘-a 0’<\/span> Read More »<\/a><\/p>\n","protected":false},"author":1,"featured_media":0,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":[],"categories":[4,23,28,26,35,46],"tags":[],"_links":{"self":[{"href":"https:\/\/pmortensen.eu\/world2\/wp-json\/wp\/v2\/posts\/3817"}],"collection":[{"href":"https:\/\/pmortensen.eu\/world2\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/pmortensen.eu\/world2\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/pmortensen.eu\/world2\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/pmortensen.eu\/world2\/wp-json\/wp\/v2\/comments?post=3817"}],"version-history":[{"count":37,"href":"https:\/\/pmortensen.eu\/world2\/wp-json\/wp\/v2\/posts\/3817\/revisions"}],"predecessor-version":[{"id":4977,"href":"https:\/\/pmortensen.eu\/world2\/wp-json\/wp\/v2\/posts\/3817\/revisions\/4977"}],"wp:attachment":[{"href":"https:\/\/pmortensen.eu\/world2\/wp-json\/wp\/v2\/media?parent=3817"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/pmortensen.eu\/world2\/wp-json\/wp\/v2\/categories?post=3817"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/pmortensen.eu\/world2\/wp-json\/wp\/v2\/tags?post=3817"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}