Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add embassy-usb-dfu crate, with related modifications to embassy-boot #2284

Merged
merged 14 commits into from
Dec 14, 2023

Conversation

Redrield
Copy link
Contributor

@Redrield Redrield commented Dec 13, 2023

embassy-usb-dfu provides an implementation of the USB DFU 1.1 protocol using embassy-boot. It has 2 components depending on which feature is enabled by the user.

  1. DFU protocol mode, enabled by the bootloader feature. This mode corresponds to the transfer phase DFU protocol described by the USB IF. It supports DFU_DNLOAD requests if marked by the user, and will automatically reset the chip once a DFU transaction has been completed. It also responds to DFU_GETSTATUS, DFU_GETSTATE, DFU_ABORT, and DFU_CLRSTATUS with no user intervention.
  2. DFU runtime mode, enabled by the application feature. This mode allows users to expose a DFU interface on their USB device, informing the host of the capability to DFU over USB, and allowing the host to reset the device into its bootloader to complete a DFU operation. Supports DFU_GETSTATUS and DFU_DETACH. When detach/reset is seen by the device as described by the standard, will write a new DFU magic number into the bootloader state in flash, and reset the system.

This PR also makes some modifications to embassy-boot, creating a third magic number used to signify that the device reset due to a DFU request from the host. This number will only be written to flash if the existing bootloader state is Booted, to avoid corrupting a rollback that may be required. The bootloader firmware must handle the creation of the USB device manually, and so the state of the bootloader has been exposed to the user to allow for this.

This DFU implementation has been tested with an STM32WB55RGVx

@lulf
Copy link
Member

lulf commented Dec 13, 2023

Thanks for the PR, and I like the way that you structured this implementation into a embassy-usb-dfu crate.

The general idea of embassy-boot usage is that the application is responsible for the DFU process, so that the bootloader itself only needs to do the swap. This way the bootloader can be kept as simple as possible with less bugs. However, exposing a third magic number is a nice extension point for those who wish to build DFU into their bootloader.

However, I'm not familiar with the USB DFU protocol so forgive me for stupid questions:

  • Is it possible to do the DFU protocol as part of the application instead? This way the application can function during the DFU so I think it would be good if that could be supported.
  • Could you provide an example bootloader/application app that show how it works?

@Redrield
Copy link
Contributor Author

  1. Yes, if the application is tolerant to exposing the full DFU interface without rebooting into its bootloader, that is absolutely possible. The crate can be added with the bootloader feature and the USB handler will write into the DFU partition and reset to allow it to be applied
  2. I'll push a minimum example into examples for you to take a loop at

Copy link
Member

@lulf lulf left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for the examples! Consider moving them to examples/boot/bootloader/stm32wb-usb-dfu and examples/boot/application/stm32wb-usb-dfu

I left some comments inline as well. I think the features should be renamed because it's really more flexible than what the names indicate (which is neat!).

embassy-boot/boot/src/lib.rs Outdated Show resolved Hide resolved
embassy-usb-dfu/src/application.rs Outdated Show resolved Hide resolved
embassy-usb-dfu/src/application.rs Outdated Show resolved Hide resolved
embassy-usb-dfu/src/application.rs Outdated Show resolved Hide resolved
embassy-usb-dfu/Cargo.toml Outdated Show resolved Hide resolved
embassy-usb-dfu/src/bootloader.rs Outdated Show resolved Hide resolved
@Redrield Redrield marked this pull request as ready for review December 14, 2023 14:53
@Dirbaio
Copy link
Member

Dirbaio commented Dec 14, 2023

please add the new examples to ci.sh so they get built in CI.

Copy link
Member

@lulf lulf left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looks good, awesome contribution 🚀

@lulf lulf added this pull request to the merge queue Dec 14, 2023
Merged via the queue into embassy-rs:main with commit 5ec2fbe Dec 14, 2023
4 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

None yet

4 participants