Repository: embassy-rs/embassy
Pull request #4188: [embassy-usb-dfu] support function level WinUSB GUIDs
Author: login: Gerharddc
Created: 2025-05-12T13:57:45Z | Merged: 2025-05-19T13:30:22Z

This PR makes it possible to provide function level msos GUIDs to usb_dfu. This helps to ensure that composite DFU devices automatically get assigned the WinUSB driver on Windows.


Diff:
diff --git a/embassy-usb-dfu/src/application.rs b/embassy-usb-dfu/src/application.rs
index 6ad07a78ca..4b7b72073c 100644
--- a/embassy-usb-dfu/src/application.rs
+++ b/embassy-usb-dfu/src/application.rs
@@ -2,7 +2,7 @@ use embassy_boot::BlockingFirmwareState;
 use embassy_time::{Duration, Instant};
 use embassy_usb::control::{InResponse, OutResponse, Recipient, RequestType};
 use embassy_usb::driver::Driver;
-use embassy_usb::{Builder, Handler};
+use embassy_usb::{Builder, FunctionBuilder, Handler};
 use embedded_storage::nor_flash::NorFlash;
 
 use crate::consts::{
@@ -130,8 +130,14 @@ pub fn usb_dfu<'d, D: Driver<'d>, MARK: DfuMarker, RST: Reset>(
     builder: &mut Builder<'d, D>,
     handler: &'d mut Control<MARK, RST>,
     timeout: Duration,
+    func_modifier: impl Fn(&mut FunctionBuilder<'_, 'd, D>),
 ) {
     let mut func = builder.function(0x00, 0x00, 0x00);
+
+    // Here we give users the opportunity to add their own function level MSOS headers for instance.
+    // This is useful when DFU functionality is part of a composite USB device.
+    func_modifier(&mut func);
+
     let mut iface = func.interface();
     let mut alt = iface.alt_setting(USB_CLASS_APPN_SPEC, APPN_SPEC_SUBCLASS_DFU, DFU_PROTOCOL_RT, None);
     let timeout = timeout.as_millis() as u16;
diff --git a/embassy-usb-dfu/src/dfu.rs b/embassy-usb-dfu/src/dfu.rs
index a98d6ab40e..0f39d906be 100644
--- a/embassy-usb-dfu/src/dfu.rs
+++ b/embassy-usb-dfu/src/dfu.rs
@@ -1,7 +1,7 @@
 use embassy_boot::{AlignedBuffer, BlockingFirmwareUpdater, FirmwareUpdaterError};
 use embassy_usb::control::{InResponse, OutResponse, Recipient, RequestType};
 use embassy_usb::driver::Driver;
-use embassy_usb::{Builder, Handler};
+use embassy_usb::{Builder, FunctionBuilder, Handler};
 use embedded_storage::nor_flash::{NorFlash, NorFlashErrorKind};
 
 use crate::consts::{
@@ -186,8 +186,14 @@ impl<'d, DFU: NorFlash, STATE: NorFlash, RST: Reset, const BLOCK_SIZE: usize> Ha
 pub fn usb_dfu<'d, D: Driver<'d>, DFU: NorFlash, STATE: NorFlash, RST: Reset, const BLOCK_SIZE: usize>(
     builder: &mut Builder<'d, D>,
     handler: &'d mut Control<'d, DFU, STATE, RST, BLOCK_SIZE>,
+    func_modifier: impl Fn(&mut FunctionBuilder<'_, 'd, D>),
 ) {
     let mut func = builder.function(USB_CLASS_APPN_SPEC, APPN_SPEC_SUBCLASS_DFU, DFU_PROTOCOL_DFU);
+
+    // Here we give users the opportunity to add their own function level MSOS headers for instance.
+    // This is useful when DFU functionality is part of a composite USB device.
+    func_modifier(&mut func);
+
     let mut iface = func.interface();
     let mut alt = iface.alt_setting(USB_CLASS_APPN_SPEC, APPN_SPEC_SUBCLASS_DFU, DFU_PROTOCOL_DFU, None);
     alt.descriptor(
diff --git a/examples/boot/application/stm32wb-dfu/src/main.rs b/examples/boot/application/stm32wb-dfu/src/main.rs
index dda2b795b1..5e7b71f5a5 100644
--- a/examples/boot/application/stm32wb-dfu/src/main.rs
+++ b/examples/boot/application/stm32wb-dfu/src/main.rs
@@ -13,7 +13,7 @@ use embassy_stm32::usb::{self, Driver};
 use embassy_stm32::{bind_interrupts, peripherals};
 use embassy_sync::blocking_mutex::Mutex;
 use embassy_time::Duration;
-use embassy_usb::Builder;
+use embassy_usb::{msos, Builder};
 use embassy_usb_dfu::consts::DfuAttributes;
 use embassy_usb_dfu::{usb_dfu, Control, ResetImmediate};
 use panic_reset as _;
@@ -22,6 +22,11 @@ bind_interrupts!(struct Irqs {
     USB_LP => usb::InterruptHandler<peripherals::USB>;
 });
 
+// This is a randomly generated GUID to allow clients on Windows to find your device.
+//
+// N.B. update to a custom GUID for your own device!
+const DEVICE_INTERFACE_GUIDS: &[&str] = &["{EAA9A5DC-30BA-44BC-9232-606CDC875321}"];
+
 #[embassy_executor::main]
 async fn main(_spawner: Spawner) {
     let mut config = embassy_stm32::Config::default();
@@ -54,7 +59,28 @@ async fn main(_spawner: Spawner) {
         &mut control_buf,
     );
 
-    usb_dfu(&mut builder, &mut state, Duration::from_millis(2500));
+    // We add MSOS headers so that the device automatically gets assigned the WinUSB driver on Windows.
+    // Otherwise users need to do this manually using a tool like Zadig.
+    //
+    // It seems these always need to be at added at the device level for this to work and for
+    // composite devices they also need to be added on the function level (as shown later).
+    //
+    builder.msos_descriptor(msos::windows_version::WIN8_1, 2);
+    builder.msos_feature(msos::CompatibleIdFeatureDescriptor::new("WINUSB", ""));
+    builder.msos_feature(msos::RegistryPropertyFeatureDescriptor::new(
+        "DeviceInterfaceGUIDs",
+        msos::PropertyData::RegMultiSz(DEVICE_INTERFACE_GUIDS),
+    ));
+
+    usb_dfu(&mut builder, &mut state, Duration::from_millis(2500), |func| {
+        // You likely don't have to add these function level headers if your USB device is not composite
+        // (i.e. if your device does not expose another interface in addition to DFU)
+        func.msos_feature(msos::CompatibleIdFeatureDescriptor::new("WINUSB", ""));
+        func.msos_feature(msos::RegistryPropertyFeatureDescriptor::new(
+            "DeviceInterfaceGUIDs",
+            msos::PropertyData::RegMultiSz(DEVICE_INTERFACE_GUIDS),
+        ));
+    });
 
     let mut dev = builder.build();
     dev.run().await
diff --git a/examples/boot/bootloader/stm32wb-dfu/src/main.rs b/examples/boot/bootloader/stm32wb-dfu/src/main.rs
index 28216806e9..0b643079f4 100644
--- a/examples/boot/bootloader/stm32wb-dfu/src/main.rs
+++ b/examples/boot/bootloader/stm32wb-dfu/src/main.rs
@@ -20,7 +20,9 @@ bind_interrupts!(struct Irqs {
     USB_LP => usb::InterruptHandler<peripherals::USB>;
 });
 
-// This is a randomly generated GUID to allow clients on Windows to find our device
+// This is a randomly generated GUID to allow clients on Windows to find your device.
+//
+// N.B. update to a custom GUID for your own device!
 const DEVICE_INTERFACE_GUIDS: &[&str] = &["{EAA9A5DC-30BA-44BC-9232-606CDC875321}"];
 
 #[entry]
@@ -68,7 +70,8 @@ fn main() -> ! {
         // We add MSOS headers so that the device automatically gets assigned the WinUSB driver on Windows.
         // Otherwise users need to do this manually using a tool like Zadig.
         //
-        // It seems it is important for the DFU class that these headers be on the Device level.
+        // It seems these always need to be at added at the device level for this to work and for
+        // composite devices they also need to be added on the function level (as shown later).
         //
         builder.msos_descriptor(msos::windows_version::WIN8_1, 2);
         builder.msos_feature(msos::CompatibleIdFeatureDescriptor::new("WINUSB", ""));
@@ -77,7 +80,15 @@ fn main() -> ! {
             msos::PropertyData::RegMultiSz(DEVICE_INTERFACE_GUIDS),
         ));
 
-        usb_dfu::<_, _, _, _, 4096>(&mut builder, &mut state);
+        usb_dfu::<_, _, _, _, 4096>(&mut builder, &mut state, |func| {
+            // You likely don't have to add these function level headers if your USB device is not composite
+            // (i.e. if your device does not expose another interface in addition to DFU)
+            func.msos_feature(msos::CompatibleIdFeatureDescriptor::new("WINUSB", ""));
+            func.msos_feature(msos::RegistryPropertyFeatureDescriptor::new(
+                "DeviceInterfaceGUIDs",
+                msos::PropertyData::RegMultiSz(DEVICE_INTERFACE_GUIDS),
+            ));
+        });
 
         let mut dev = builder.build();
         embassy_futures::block_on(dev.run());


Reviews:
user: login: lulf
state: COMMENTED
author_association: MEMBER
submitted_at: 2025-05-14T05:49:07Z
user: login: Gerharddc
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-05-14T06:56:13Z
user: login: Gerharddc
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-05-14T07:59:33Z
user: login: lulf
body: Thanks!
state: APPROVED
author_association: MEMBER
submitted_at: 2025-05-14T19:54:50Z

Review comments:
diff_hunk: @@ -130,8 +130,23 @@ pub fn usb_dfu<'d, D: Driver<'d>, MARK: DfuMarker, RST: Reset>(
     builder: &mut Builder<'d, D>,
     handler: &'d mut Control<MARK, RST>,
     timeout: Duration,
+    winusb_guids: Option<&'d [&str]>,
 ) {
     let mut func = builder.function(0x00, 0x00, 0x00);
+    if let Some(winusb_guids) = winusb_guids {
+        // We add MSOS headers so that the device automatically gets assigned the WinUSB driver on Windows.
+        // Otherwise users need to do this manually using a tool like Zadig.
+        //
+        // Adding them here on the function level appears to only be needed for compositive devices.
+        // In addition to being on the function level, they should also be added to the device level.
+        //
+        func.msos_feature(msos::CompatibleIdFeatureDescriptor::new("WINUSB", ""));
+        func.msos_feature(msos::RegistryPropertyFeatureDescriptor::new(
+            "DeviceInterfaceGUIDs",
+            msos::PropertyData::RegMultiSz(winusb_guids),
+        ));
+    }
+
path: embassy-usb-dfu/src/application.rs
user: login: lulf
body: Could this have been a closure that gets the func passed, instead of an option parameter that seems very specific to winusb?
created_at: 2025-05-14T05:49:04Z
author_association: MEMBER
diff_hunk: @@ -130,8 +130,23 @@ pub fn usb_dfu<'d, D: Driver<'d>, MARK: DfuMarker, RST: Reset>(
     builder: &mut Builder<'d, D>,
     handler: &'d mut Control<MARK, RST>,
     timeout: Duration,
+    winusb_guids: Option<&'d [&str]>,
 ) {
     let mut func = builder.function(0x00, 0x00, 0x00);
+    if let Some(winusb_guids) = winusb_guids {
+        // We add MSOS headers so that the device automatically gets assigned the WinUSB driver on Windows.
+        // Otherwise users need to do this manually using a tool like Zadig.
+        //
+        // Adding them here on the function level appears to only be needed for compositive devices.
+        // In addition to being on the function level, they should also be added to the device level.
+        //
+        func.msos_feature(msos::CompatibleIdFeatureDescriptor::new("WINUSB", ""));
+        func.msos_feature(msos::RegistryPropertyFeatureDescriptor::new(
+            "DeviceInterfaceGUIDs",
+            msos::PropertyData::RegMultiSz(winusb_guids),
+        ));
+    }
+
path: embassy-usb-dfu/src/application.rs
user: login: Gerharddc
body: Great suggestion, thanks! I can't see use-case for customizing `func` further right now, but it's definitely a more future proof approach. I'll give that approach a shot and see if it works out
created_at: 2025-05-14T06:56:13Z
author_association: CONTRIBUTOR
diff_hunk: @@ -130,8 +130,23 @@ pub fn usb_dfu<'d, D: Driver<'d>, MARK: DfuMarker, RST: Reset>(
     builder: &mut Builder<'d, D>,
     handler: &'d mut Control<MARK, RST>,
     timeout: Duration,
+    winusb_guids: Option<&'d [&str]>,
 ) {
     let mut func = builder.function(0x00, 0x00, 0x00);
+    if let Some(winusb_guids) = winusb_guids {
+        // We add MSOS headers so that the device automatically gets assigned the WinUSB driver on Windows.
+        // Otherwise users need to do this manually using a tool like Zadig.
+        //
+        // Adding them here on the function level appears to only be needed for compositive devices.
+        // In addition to being on the function level, they should also be added to the device level.
+        //
+        func.msos_feature(msos::CompatibleIdFeatureDescriptor::new("WINUSB", ""));
+        func.msos_feature(msos::RegistryPropertyFeatureDescriptor::new(
+            "DeviceInterfaceGUIDs",
+            msos::PropertyData::RegMultiSz(winusb_guids),
+        ));
+    }
+
path: embassy-usb-dfu/src/application.rs
user: login: Gerharddc
body: Ok, I have now updated this to use a closure instead. Unfortunately, I could not manage to put the closure inside an `Option` though since that results in all sorts of lifetime hell... 
created_at: 2025-05-14T07:59:33Z
author_association: CONTRIBUTOR

PR comments:
user: login: Gerharddc
created_at: 2025-05-13T13:16:28Z
body: This PR is ready for review now. After more extensive physical testing it turned out the comments I left were not entirely accurate, but that has been corrected now. 
author_association: CONTRIBUTOR
user: login: Gerharddc
created_at: 2025-05-19T06:27:00Z
body: @lulf thanks for approving! Are more changes needed before you will be able to merge?
author_association: CONTRIBUTOR