DFU-PROGRAMMER(1)

📦
version 1.1.0 · 2 versions
, in arch rolling, nixos 26.05, nixpkgs unstable, opensuse-leap 16.0, ubuntu resolute, ubuntu stonking

👑 DFU-PROGRAMMER(1) 💅

okay bestie, sit DOWN, because this is the manual page for dfu-programmer, section 1 of the manual, and it's literally the group chat of USB firmware upgrading. no cap.

✨ NAME ✨

dfu-programmer — USB firmware upgrading for Atmel microcontrollers 🦋

🌸 SYNOPSIS 🌸

dfu-programmer target[:usb-bus,usb-addr] command [options] [parameters]
dfu-programmer --help
dfu-programmer --targets
dfu-programmer --version

💖 DESCRIPTION 💖

So dfu-programmer is a multi-platform command line Device Firmware Upgrade (DFU) based programmer for the flash memory on Atmel AVR, AVR32, XMEGA and 8051 based microcontrollers that ship with a USB boot loader. it's giving "I flash chips and I look cute doing it." ✨

It supports In System Programming (ISP) for developers and potentially product updates in the field. those boot loaders are patterned after the standard USB DFU 1.0 class specification, but they depend on extensions defined by Atmel — to the extent that standard DFU drivers will not work. periodt, don't even try it.

To use it, first connect the device you wanna program and make sure it comes up in DFU mode. the microcontrollers come up in that mode as shipped by Atmel; or they may reenter that mode after a special hardware reset. then invoke this program to issue one or more DFU commands. you will normally need to start by issuing the erase command — the default security policies prevent extracting firmware, to prevent reverse engineering of what is usually proprietary code. 🔒

🧚 SUPPORTED MICROCONTROLLERS 🧚

these chip names are what you drop in as the command line target parameter. iykyk.

8051 based controllers:

  • at89c51snd1c
  • at89c51snd2c
  • at89c5130
  • at89c5131
  • at89c5132

AVR based controllers:

  • at90usb1287
  • at90usb1286
  • at90usb1287-4k
  • at90usb1286-4k
  • at90usb647
  • at90usb646
  • at90usb162
  • at90usb82
  • atmega32u6
  • atmega32u4
  • atmega32u2
  • atmega16u4
  • atmega16u2
  • atmega8u2

AVR32 based controllers:

  • at32uc3a0128
  • at32uc3a1128
  • at32uc3a0256
  • at32uc3a1256
  • at32uc3a0512
  • at32uc3a1512
  • at32uc3a0512es
  • at32uc3a1512es
  • at32uc3a364
  • at32uc3a364s
  • at32uc3a3128
  • at32uc3a3128s
  • at32uc3a3256
  • at32uc3a3256s
  • at32uc3a4256s
  • at32uc3b064
  • at32uc3b164
  • at32uc3b0128
  • at32uc3b1128
  • at32uc3b0256
  • at32uc3b1256
  • at32uc3b0256es
  • at32uc3b1256es
  • at32uc3b0512
  • at32uc3b1512
  • at32uc3c064
  • at32uc3c0128
  • at32uc3c0256
  • at32uc3c0512
  • at32uc3c164
  • at32uc3c1128
  • at32uc3c1256
  • at32uc3c1512
  • at32uc3c264
  • at32uc3c2128
  • at32uc3c2256
  • at32uc3c2512

XMEGA based controllers:

  • atxmega64a1u
  • atxmega128a1u
  • atxmega64a3u
  • atxmega128a3u
  • atxmega192a3u
  • atxmega256a3u
  • atxmega16a4u
  • atxmega32a4u
  • atxmega64a4u
  • atxmega128a4u
  • atxmega256a3bu
  • atxmega64b1
  • atxmega128b1
  • atxmega64b3
  • atxmega128b3
  • atxmega64c3
  • atxmega128c3
  • atxmega256c3
  • atxmega384c3
  • atxmega16c4
  • atxmega32c4

STM32F4 controllers (experimental):

  • stm32f4_B
  • stm32f4_C
  • stm32f4_E
  • stm32f4_G

🌈 USAGE 🌈

There are no mechanisms to implement gang programming. by default, the first device that matches the id codes for the given target is selected. and here's the tea: many targets share the same id codes. so accordingly, you will usually avoid connecting more than one device of a given family (AVR, XMEGA, AVR32 or 8051) at a time. one at a time bestie, we're monogamous with our chips 💀

The target may be qualified with the USB bus and address number of the device you wish to program. this is how you program multiple devices of the same family at the same time. slay, polyamory unlocked 🫶

All of these commands support the "global options". unless you override it, commands which write to the microcontroller will perform a validation step that rereads the data which was written, compares it to the expected result, and reports any errors. it's giving self-check, we love a queen who double-checks her work ✨

Note that unlike Atmel's BatchISP program, dfu-programmer will only perform a single operation at a time. erasing and programming require separate commands. one thing at a time, we're not multitasking here 😭

  • configure register [--suppress-validation] data — bootloaders for 8051 based controllers support writing certain configuration bytes.
  • dump [--force] [--bin] [(flash)|--user|--eeprom] — reads the program memory in flash and outputs non-blank pages in ihex format to stdout. use --force to output the entire memory and --bin for binary output. user page and eeprom are selected using --user and --eeprom. 👑
  • erase [--force] — erases all the flash memory. for AT90 and ATmega type devices a chip erase must be performed before other commands become available. erase first checks if the memory is blank, unless the --force flag is set.
  • flash [--force] [(flash)|--user|--eeprom] [--suppress-validation] [--suppress-bootloader-mem] [--validate-first] [--ignore-outside] [--serial=hexbytes:offset] file or STDIN — writes flash memory. the input file (or stdin) must use the "ihex" file format convention for a memory image. --suppress-bootloader-mem ignores any data written to the bootloader memory space when flashing the device — this option is particularly useful for the AVR32 chips. the --force flag tells the program to ignore whether memory inside the program region is blank. user page and eeprom are selected using --user and --eeprom. the user space flash on AVR32 chips lies outside of the normal range of flash blocks and is designed to contain configuration parameters. bootloader configuration uses the last 4 to 8 bytes of the user page. if this data is corrupted, the device will restart into the bootloader until valid data is used (see atmel doc7745 or doc32166). --force is always required here.

--serial provides a way to inject a serial number or other unique sequence of bytes into the memory image programmed into the device. this allows using a single .ihex file to program multiple devices, and still give each device its own unique serial number. for example, --serial=ABCDEF01:0x6000 would program the byte at 0x6000 with the hex value AB, the byte at 0x6001 with the value CD, and so on. there must be an even number of hex digits, but the sequence can be any length. the offset is assumed to be given in hex if it starts with a "0x" prefix, octal if it begins with a "0", otherwise it is assumed to be decimal. 🍓

--validate-first adds a validate before writing the flash memory. if the validate succeeds (i.e. the firmware in the chip is the same as the one given as input), then no further operations are done, and the flash is reported as successful.

--ignore-outside changes the validate behavior to ignore any error outside the programming region. this can be useful for programming a single part of the chip (where errors outside the region are expected) without ignoring the validate result.

  • setsecure — sets the security bit on AVR32 chips. this prevents the content being read back from the chip, except in the same session in which it was programmed. when the security fuse is set, almost nothing will work without first executing the erase command. the only way to clear the security fuse once set is to use a JTAG chip erase, which will also erase the bootloader. be so serious about this one bestie 😭
  • get register — displays various product identifier bytes.
  • launch [--no-reset] — launch the application by resetting the device. the --no-reset flag can be used to launch the device without a reset (jump to the start address of the program). 🚀

💅 Global Options 💅

  • --quiet — minimizes the output. shhh 🤫
  • --debug level — enables verbose output at the specified level.

🎀 Configure Registers 🎀

The standard bootloader for 8051 based chips supports writing data bytes which are not relevant for the AVR based chips.

  • BSB — boot status byte
  • SBV — software boot vector
  • SSB — software security byte
  • EB — extra byte
  • HSB — hardware security byte

⭐ Get Register ⭐

  • bootloader-version — currently flashed bootloader version
  • ID1 — device boot identification 1
  • ID2 — device boot identification 2
  • manufacturer — the hardware manufacturer code
  • family — the product family code
  • product-name — the product name
  • product-revision — the product revision
  • HSB — same as the configure_register version
  • BSB — same as the configure_register version
  • SBV — same as the configure_register version
  • SSB — same as the configure_register version
  • EB — same as the configure_register version

💀 BUGS 💀

None known. (iconic behaviour, honestly. not a single one. we love a flawless queen ✨)

🙈 KNOWN ISSUES 🙈

The at90usb series chips do not make available any read/write protect flags, so the dump or flash command may fail with a less than helpful error message. it's giving cryptic text from a girl who won't communicate her feelings 😭

To remove any write or read protection from any chips, a full chip erasure is required. for AVR32 chips an erase operation over USB will remove protection until the device is rebooted. to remove the protection more permanently requires a JTAG erase (which will also erase the bootloader). so yeah, commit to it or don't, no half measures 💅

You may need to be a member of the uucp group in order to have access to the device without needing to be root. group chat membership = device access, no sudo required 🫶

💜 AUTHOR 💜

Weston Schmidt <weston_schmidt@alumni.purdue.edu>

🦋 SEE ALSO 🦋

nothing here bestie, the original left this section completely empty. a mysterious queen who says nothing and leaves. respect. 💅

okay and that's the whole page!! 🌸 no version, no date, no source line at the bottom to report — the original page just ends with that empty SEE ALSO and dips. so here's your cute sign-off instead: this was DFU-PROGRAMMER(1), flashing Atmel chips and serving looks, periodt. go erase before you flash, bestie, and stay hydrated 🎀✨💖

📦 where this page comes from