From 3c73b497909ce5bacd16d23e54928a7f66544e09 Mon Sep 17 00:00:00 2001 From: Gerhard de Clercq <11624490+Gerharddc@users.noreply.github.com> Date: Mon, 12 May 2025 15:51:19 +0200 Subject: [embassy-usb-dfu] support function level WinUSB GUIDs This commit 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. --- examples/boot/application/stm32wb-dfu/src/main.rs | 26 +++++++++++++++++++++-- examples/boot/bootloader/stm32wb-dfu/src/main.rs | 15 +++++++++---- 2 files changed, 35 insertions(+), 6 deletions(-) (limited to 'examples/boot') diff --git a/examples/boot/application/stm32wb-dfu/src/main.rs b/examples/boot/application/stm32wb-dfu/src/main.rs index dda2b795b..68e9bc3f6 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,9 @@ bind_interrupts!(struct Irqs { USB_LP => usb::InterruptHandler; }); +// This is a randomly generated GUID to allow clients on Windows to find our 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 +57,26 @@ 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. + builder.msos_descriptor(msos::windows_version::WIN8_1, 2); + + // In the case of non-composite devices, it seems that feature headers need to be on the device level. + // (As is implemented here) + // + // For composite devices however, they should be on the function level instead. + // (This is achieved by passing a GUID to the "usb_dfu" function) + builder.msos_feature(msos::CompatibleIdFeatureDescriptor::new("WINUSB", "")); + builder.msos_feature(msos::RegistryPropertyFeatureDescriptor::new( + "DeviceInterfaceGUIDs", + msos::PropertyData::RegMultiSz(DEVICE_INTERFACE_GUIDS), + )); + + // For non-composite devices: + usb_dfu(&mut builder, &mut state, Duration::from_millis(2500), None); + + // Or for composite devices: + // usb_dfu(&mut builder, &mut state, Duration::from_millis(2500), Some(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 28216806e..2cd7f859d 100644 --- a/examples/boot/bootloader/stm32wb-dfu/src/main.rs +++ b/examples/boot/bootloader/stm32wb-dfu/src/main.rs @@ -67,17 +67,24 @@ 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. - // builder.msos_descriptor(msos::windows_version::WIN8_1, 2); + + // In the case of non-composite devices, it seems that feature headers need to be on the device level. + // (As is implemented here) + // + // For composite devices however, they should be on the function level instead. + // (This is achieved by passing a GUID to the "usb_dfu" function) builder.msos_feature(msos::CompatibleIdFeatureDescriptor::new("WINUSB", "")); builder.msos_feature(msos::RegistryPropertyFeatureDescriptor::new( "DeviceInterfaceGUIDs", msos::PropertyData::RegMultiSz(DEVICE_INTERFACE_GUIDS), )); - usb_dfu::<_, _, _, _, 4096>(&mut builder, &mut state); + // For non-composite devices: + usb_dfu::<_, _, _, _, 4096>(&mut builder, &mut state, None); + + // Or for composite devices: + // usb_dfu::<_, _, _, _, 4096>(&mut builder, &mut state, Some(DEVICE_INTERFACE_GUIDS)); let mut dev = builder.build(); embassy_futures::block_on(dev.run()); -- cgit From 46e25cbc5ff62e24f86574d7ae5d872aa0c2595d Mon Sep 17 00:00:00 2001 From: Gerhard de Clercq <11624490+Gerharddc@users.noreply.github.com> Date: Tue, 13 May 2025 15:09:53 +0200 Subject: [embassy-usb-dfu] correct comment about composite devices --- examples/boot/application/stm32wb-dfu/src/main.rs | 10 ++++------ examples/boot/bootloader/stm32wb-dfu/src/main.rs | 10 ++++------ 2 files changed, 8 insertions(+), 12 deletions(-) (limited to 'examples/boot') diff --git a/examples/boot/application/stm32wb-dfu/src/main.rs b/examples/boot/application/stm32wb-dfu/src/main.rs index 68e9bc3f6..6236dfe52 100644 --- a/examples/boot/application/stm32wb-dfu/src/main.rs +++ b/examples/boot/application/stm32wb-dfu/src/main.rs @@ -59,13 +59,11 @@ async fn main(_spawner: Spawner) { // 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. - builder.msos_descriptor(msos::windows_version::WIN8_1, 2); - - // In the case of non-composite devices, it seems that feature headers need to be on the device level. - // (As is implemented here) // - // For composite devices however, they should be on the function level instead. - // (This is achieved by passing a GUID to the "usb_dfu" function) + // 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", diff --git a/examples/boot/bootloader/stm32wb-dfu/src/main.rs b/examples/boot/bootloader/stm32wb-dfu/src/main.rs index 2cd7f859d..8cfd4daa7 100644 --- a/examples/boot/bootloader/stm32wb-dfu/src/main.rs +++ b/examples/boot/bootloader/stm32wb-dfu/src/main.rs @@ -67,13 +67,11 @@ 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. - builder.msos_descriptor(msos::windows_version::WIN8_1, 2); - - // In the case of non-composite devices, it seems that feature headers need to be on the device level. - // (As is implemented here) // - // For composite devices however, they should be on the function level instead. - // (This is achieved by passing a GUID to the "usb_dfu" function) + // 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", -- cgit From d4d10bad0bc2f2bbfbad116fb07e27eea4ac5af2 Mon Sep 17 00:00:00 2001 From: Gerhard de Clercq <11624490+Gerharddc@users.noreply.github.com> Date: Wed, 14 May 2025 09:52:46 +0200 Subject: [embassy-usb-dfu] accept closure to customise DFU function This provides a more generic interface for users to customise the DFU function instead of restricting customisation to DFU headers. --- examples/boot/application/stm32wb-dfu/src/main.rs | 14 +++++++++----- examples/boot/bootloader/stm32wb-dfu/src/main.rs | 14 +++++++++----- 2 files changed, 18 insertions(+), 10 deletions(-) (limited to 'examples/boot') diff --git a/examples/boot/application/stm32wb-dfu/src/main.rs b/examples/boot/application/stm32wb-dfu/src/main.rs index 6236dfe52..4d6556597 100644 --- a/examples/boot/application/stm32wb-dfu/src/main.rs +++ b/examples/boot/application/stm32wb-dfu/src/main.rs @@ -70,11 +70,15 @@ async fn main(_spawner: Spawner) { msos::PropertyData::RegMultiSz(DEVICE_INTERFACE_GUIDS), )); - // For non-composite devices: - usb_dfu(&mut builder, &mut state, Duration::from_millis(2500), None); - - // Or for composite devices: - // usb_dfu(&mut builder, &mut state, Duration::from_millis(2500), Some(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 8cfd4daa7..fea6f4a0d 100644 --- a/examples/boot/bootloader/stm32wb-dfu/src/main.rs +++ b/examples/boot/bootloader/stm32wb-dfu/src/main.rs @@ -78,11 +78,15 @@ fn main() -> ! { msos::PropertyData::RegMultiSz(DEVICE_INTERFACE_GUIDS), )); - // For non-composite devices: - usb_dfu::<_, _, _, _, 4096>(&mut builder, &mut state, None); - - // Or for composite devices: - // usb_dfu::<_, _, _, _, 4096>(&mut builder, &mut state, Some(DEVICE_INTERFACE_GUIDS)); + 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()); -- cgit From 2bbc2045a4a6cb1e489295d258ac0cdb6338f90a Mon Sep 17 00:00:00 2001 From: Gerhard de Clercq <11624490+Gerharddc@users.noreply.github.com> Date: Wed, 14 May 2025 09:56:28 +0200 Subject: [usb-dfu examples] Alert users to customise their WinUSB GUIDs --- examples/boot/application/stm32wb-dfu/src/main.rs | 4 +++- examples/boot/bootloader/stm32wb-dfu/src/main.rs | 4 +++- 2 files changed, 6 insertions(+), 2 deletions(-) (limited to 'examples/boot') diff --git a/examples/boot/application/stm32wb-dfu/src/main.rs b/examples/boot/application/stm32wb-dfu/src/main.rs index 4d6556597..5e7b71f5a 100644 --- a/examples/boot/application/stm32wb-dfu/src/main.rs +++ b/examples/boot/application/stm32wb-dfu/src/main.rs @@ -22,7 +22,9 @@ bind_interrupts!(struct Irqs { USB_LP => usb::InterruptHandler; }); -// 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}"]; #[embassy_executor::main] diff --git a/examples/boot/bootloader/stm32wb-dfu/src/main.rs b/examples/boot/bootloader/stm32wb-dfu/src/main.rs index fea6f4a0d..0b643079f 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; }); -// 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] -- cgit