usbd-dfu
Implements DFU protocol version 1.1a for a usb-device
device.
About
DFU protocol aims to provide a standard how USB device's firmware can be upgraded. Often, in this case firmware of the device consists of two parts: a large main firmware, and a smaller bootloader. When device is powered on, bootloader starts and either runs main firmware, or enters "firmware update" mode.
Protocol implementation tries to follows DFU 1.1a protocol as specified by AN3156 by STMicroelectronics and USB Device Firmware Upgrade Specification, Revision 1.1.
This library is a protocol implementation only, actual code that programs, erases, or reads memory or flash in not a of the library and is expected to be provided by library user.
Supported operations
- Read (device to host) - upload command
- Write (host to device) - download command
- Erase
- Erase All
Not supported operations
- Read Unprotect - erase everything and remove read protection.
Limitations
-
Maximum USB transfer size is limited to what
usb-device
supports for control enpoint transfers, which is128
bytes by default. -
iString field in
DFU_GETSTATUS
is always0
. Vendor-specific string error descriptions are not supported.
DFU utilities
There are many implementations of tools to flash USB device supporting DFU protocol, for example:
- dfu and dfu-flasher
- dfu-programmer
- dfu-util
- others
License
This project is licensed under MIT License (LICENSE).
Contribution
Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you shall be licensed as above, without any additional terms or conditions.
Example
The example below tries to focus on DFUClass
, parts related to a target
controller initialization and configuration (USB, interrupts, GPIO, etc.)
are not in the scope of the example.
Check examples for more information.
Also see documentation for usb-device
crate, crates that supports
target microcontroller and provide a corresponding HAL.
use *;
use *;
// DFUClass will use MyMem to actually read, erase or program the memory.
// Here, a set of constant parameters must be set. These parameters
// either change how DFUClass behaves, or define host's expectations.
let mut my_mem = MyMem ;
// Create USB device for a target device:
// let usb_bus_alloc = UsbBus::new(peripheral);
// let usb_dev = UsbDeviceBuilder::new().build();
// Create DFUClass
let mut dfu = new;
// usb_dev.poll() must be called periodically, usually from USB interrupt handlers.
// When USB input/output is done, handlers in MyMem may be called.
usb_dev.poll;
Example bootloader implementation
See usbd-dfu-example for a functioning example.