10 files changed, 126 insertions, 3 deletions

diff --git a/docs/modules/ROOT/pages/faq.adoc b/docs/modules/ROOT/pages/faq.adoc
index 0944127a5..6cb7233c1 100644
--- a/docs/modules/ROOT/pages/faq.adoc
+++ b/docs/modules/ROOT/pages/faq.adoc
@@ -232,6 +232,26 @@ Look for the `MEMORY` section and try to determine the FLASH and RAM sizes and s
 
 If you find a case where the memory.x is wrong, please report it on [this Github issue](https://github.com/embassy-rs/stm32-data/issues/301) so other users are not caught by surprise.
 
+== The USB examples are not working on my board, is there anything else I need to configure?
+
+If you are trying out the USB examples and your device doesn not connect, the most common issues are listed below.
+
+=== Incorrect RCC config
+
+Check your board and crystal/oscillator, in particular make sure that `HSE` is set to the correct value, e.g. `8_000_000` Hertz if your board does indeed run on a 8 MHz oscillator.
+
+=== VBUS detection on STM32 platform
+
+The USB specification requires that all USB devices monitor the bus for detection of plugging/unplugging actions. The devices must pull-up the D+ or D- lane as soon as the host supplies VBUS.
+
+See the docs, for example at link:https://docs.embassy.dev/embassy-stm32/git/stm32f401vc/usb/struct.Config.html[`usb/struct.Config.html`] for information on how to enable/disable `vbus_detection`.
+
+When the device is powered only from the USB bus that simultaneously serves as the data connection, this is optional. (If there's no power in VBUS the device would be off anyway, so it's safe to always assume there's power in VBUS, i.e. the USB cable is always plugged in). If your device doesn't have the required connections in place to allow VBUS sensing (see below), then this option needs to be set to `false` to work.
+
+When the device is powered from another power source and therefore can stay powered through USB cable plug/unplug events, then this must be implemented and `vbus_detection` MUST be set to `true`.
+
+If your board is powered from the USB and you are unsure whether it supports `vbus_detection`, consult the schematics of your board to see if VBUS is connected to PA9 for USB Full Speed or PB13 for USB High Speed, vice versa, possibly with a voltage divider. When designing your own hardware, see ST application note AN4879 (in particular section 2.6) and the reference manual of your specific chip for more details.
+
 == Known issues (details and/or mitigations)
 
 These are issues that are commonly reported. Help wanted fixing them, or improving the UX when possible!
diff --git a/embassy-stm32/src/usb/otg.rs b/embassy-stm32/src/usb/otg.rs
index b386c6977..29572d3c6 100644
--- a/embassy-stm32/src/usb/otg.rs
+++ b/embassy-stm32/src/usb/otg.rs
@@ -281,10 +281,10 @@ pub struct Config {
     /// Enable VBUS detection.
     ///
     /// The USB spec requires USB devices monitor for USB cable plug/unplug and react accordingly.
-    /// This is done by checkihg whether there is 5V on the VBUS pin or not.
+    /// This is done by checking whether there is 5V on the VBUS pin or not.
     ///
     /// If your device is bus-powered (powers itself from the USB host via VBUS), then this is optional.
-    /// (if there's no power in VBUS your device would be off anyway, so it's fine to always assume
+    /// (If there's no power in VBUS your device would be off anyway, so it's fine to always assume
     /// there's power in VBUS, i.e. the USB cable is always plugged in.)
     ///
     /// If your device is self-powered (i.e. it gets power from a source other than the USB cable, and
diff --git a/examples/stm32f4/src/bin/usb_ethernet.rs b/examples/stm32f4/src/bin/usb_ethernet.rs
index d2cbeea1b..34e58f282 100644
--- a/examples/stm32f4/src/bin/usb_ethernet.rs
+++ b/examples/stm32f4/src/bin/usb_ethernet.rs
@@ -40,6 +40,11 @@ bind_interrupts!(struct Irqs {
     HASH_RNG => rng::InterruptHandler<peripherals::RNG>;
 });
 
+// If you are trying this and your USB device doesn't connect, the most
+// common issues are the RCC config and vbus_detection
+//
+// See https://embassy.dev/book/dev/faq.html#_the_usb_examples_are_not_working_on_my_board_is_there_anything_else_i_need_to_configure
+// for more information.
 #[embassy_executor::main]
 async fn main(spawner: Spawner) {
     info!("Hello World!");
@@ -71,7 +76,15 @@ async fn main(spawner: Spawner) {
     static OUTPUT_BUFFER: StaticCell<[u8; 256]> = StaticCell::new();
     let ep_out_buffer = &mut OUTPUT_BUFFER.init([0; 256])[..];
     let mut config = embassy_stm32::usb::Config::default();
+
+    // Enable vbus_detection
+    // Note: some boards don't have this wired up and might not require it,
+    // as they are powered through usb!
+    // If you hang on boot, try setting this to "false"!
+    // See https://embassy.dev/book/dev/faq.html#_the_usb_examples_are_not_working_on_my_board_is_there_anything_else_i_need_to_configure
+    // for more information
     config.vbus_detection = true;
+
     let driver = Driver::new_fs(p.USB_OTG_FS, Irqs, p.PA12, p.PA11, ep_out_buffer, config);
 
     // Create embassy-usb Config
diff --git a/examples/stm32f4/src/bin/usb_hid_keyboard.rs b/examples/stm32f4/src/bin/usb_hid_keyboard.rs
index d6e0be5ea..7067d15a3 100644
--- a/examples/stm32f4/src/bin/usb_hid_keyboard.rs
+++ b/examples/stm32f4/src/bin/usb_hid_keyboard.rs
@@ -21,6 +21,11 @@ bind_interrupts!(struct Irqs {
     OTG_FS => usb::InterruptHandler<peripherals::USB_OTG_FS>;
 });
 
+// If you are trying this and your USB device doesn't connect, the most
+// common issues are the RCC config and vbus_detection
+//
+// See https://embassy.dev/book/dev/faq.html#_the_usb_examples_are_not_working_on_my_board_is_there_anything_else_i_need_to_configure
+// for more information.
 #[embassy_executor::main]
 async fn main(_spawner: Spawner) {
     let mut config = Config::default();
@@ -49,8 +54,15 @@ async fn main(_spawner: Spawner) {
     // Create the driver, from the HAL.
     let mut ep_out_buffer = [0u8; 256];
     let mut config = embassy_stm32::usb::Config::default();
-    // If the board you’re using doesn’t have the VBUS pin wired up correctly for detecting the USB bus voltage (e.g. on the f4 blackpill board), set this to false
+
+    // Enable vbus_detection
+    // Note: some boards don't have this wired up and might not require it,
+    // as they are powered through usb!
+    // If you hang on boot, try setting this to "false"!
+    // See https://embassy.dev/book/dev/faq.html#_the_usb_examples_are_not_working_on_my_board_is_there_anything_else_i_need_to_configure
+    // for more information
     config.vbus_detection = true;
+
     let driver = Driver::new_fs(p.USB_OTG_FS, Irqs, p.PA12, p.PA11, &mut ep_out_buffer, config);
 
     // Create embassy-usb Config
diff --git a/examples/stm32f4/src/bin/usb_hid_mouse.rs b/examples/stm32f4/src/bin/usb_hid_mouse.rs
index 0bc236119..0d04d2a9c 100644
--- a/examples/stm32f4/src/bin/usb_hid_mouse.rs
+++ b/examples/stm32f4/src/bin/usb_hid_mouse.rs
@@ -18,6 +18,11 @@ bind_interrupts!(struct Irqs {
     OTG_FS => usb::InterruptHandler<peripherals::USB_OTG_FS>;
 });
 
+// If you are trying this and your USB device doesn't connect, the most
+// common issues are the RCC config and vbus_detection
+//
+// See https://embassy.dev/book/dev/faq.html#_the_usb_examples_are_not_working_on_my_board_is_there_anything_else_i_need_to_configure
+// for more information.
 #[embassy_executor::main]
 async fn main(_spawner: Spawner) {
     let mut config = Config::default();
@@ -46,7 +51,15 @@ async fn main(_spawner: Spawner) {
     // Create the driver, from the HAL.
     let mut ep_out_buffer = [0u8; 256];
     let mut config = embassy_stm32::usb::Config::default();
+
+    // Enable vbus_detection
+    // Note: some boards don't have this wired up and might not require it,
+    // as they are powered through usb!
+    // If you hang on boot, try setting this to "false"!
+    // See https://embassy.dev/book/dev/faq.html#_the_usb_examples_are_not_working_on_my_board_is_there_anything_else_i_need_to_configure
+    // for more information
     config.vbus_detection = true;
+
     let driver = Driver::new_fs(p.USB_OTG_FS, Irqs, p.PA12, p.PA11, &mut ep_out_buffer, config);
 
     // Create embassy-usb Config
diff --git a/examples/stm32f4/src/bin/usb_raw.rs b/examples/stm32f4/src/bin/usb_raw.rs
index 4e583aeb8..d058abdd0 100644
--- a/examples/stm32f4/src/bin/usb_raw.rs
+++ b/examples/stm32f4/src/bin/usb_raw.rs
@@ -69,6 +69,11 @@ bind_interrupts!(struct Irqs {
     OTG_FS => usb::InterruptHandler<peripherals::USB_OTG_FS>;
 });
 
+// If you are trying this and your USB device doesn't connect, the most
+// common issues are the RCC config and vbus_detection
+//
+// See https://embassy.dev/book/dev/faq.html#_the_usb_examples_are_not_working_on_my_board_is_there_anything_else_i_need_to_configure
+// for more information.
 #[embassy_executor::main]
 async fn main(_spawner: Spawner) {
     info!("Hello World!");
@@ -99,7 +104,15 @@ async fn main(_spawner: Spawner) {
     // Create the driver, from the HAL.
     let mut ep_out_buffer = [0u8; 256];
     let mut config = embassy_stm32::usb::Config::default();
+
+    // Enable vbus_detection
+    // Note: some boards don't have this wired up and might not require it,
+    // as they are powered through usb!
+    // If you hang on boot, try setting this to "false"!
+    // See https://embassy.dev/book/dev/faq.html#_the_usb_examples_are_not_working_on_my_board_is_there_anything_else_i_need_to_configure
+    // for more information
     config.vbus_detection = true;
+
     let driver = Driver::new_fs(p.USB_OTG_FS, Irqs, p.PA12, p.PA11, &mut ep_out_buffer, config);
 
     // Create embassy-usb Config
diff --git a/examples/stm32f4/src/bin/usb_serial.rs b/examples/stm32f4/src/bin/usb_serial.rs
index f3a375d31..25806dd85 100644
--- a/examples/stm32f4/src/bin/usb_serial.rs
+++ b/examples/stm32f4/src/bin/usb_serial.rs
@@ -16,6 +16,11 @@ bind_interrupts!(struct Irqs {
     OTG_FS => usb::InterruptHandler<peripherals::USB_OTG_FS>;
 });
 
+// If you are trying this and your USB device doesn't connect, the most
+// common issues are the RCC config and vbus_detection
+//
+// See https://embassy.dev/book/dev/faq.html#_the_usb_examples_are_not_working_on_my_board_is_there_anything_else_i_need_to_configure
+// for more information.
 #[embassy_executor::main]
 async fn main(_spawner: Spawner) {
     info!("Hello World!");
@@ -46,7 +51,15 @@ async fn main(_spawner: Spawner) {
     // Create the driver, from the HAL.
     let mut ep_out_buffer = [0u8; 256];
     let mut config = embassy_stm32::usb::Config::default();
+
+    // Enable vbus_detection
+    // Note: some boards don't have this wired up and might not require it,
+    // as they are powered through usb!
+    // If you hang on boot, try setting this to "false"!
+    // See https://embassy.dev/book/dev/faq.html#_the_usb_examples_are_not_working_on_my_board_is_there_anything_else_i_need_to_configure
+    // for more information
     config.vbus_detection = true;
+
     let driver = Driver::new_fs(p.USB_OTG_FS, Irqs, p.PA12, p.PA11, &mut ep_out_buffer, config);
 
     // Create embassy-usb Config
diff --git a/examples/stm32f7/src/bin/usb_serial.rs b/examples/stm32f7/src/bin/usb_serial.rs
index 39a5512f4..2fee561c7 100644
--- a/examples/stm32f7/src/bin/usb_serial.rs
+++ b/examples/stm32f7/src/bin/usb_serial.rs
@@ -16,6 +16,11 @@ bind_interrupts!(struct Irqs {
     OTG_FS => usb::InterruptHandler<peripherals::USB_OTG_FS>;
 });
 
+// If you are trying this and your USB device doesn't connect, the most
+// common issues are the RCC config and vbus_detection
+//
+// See https://embassy.dev/book/dev/faq.html#_the_usb_examples_are_not_working_on_my_board_is_there_anything_else_i_need_to_configure
+// for more information.
 #[embassy_executor::main]
 async fn main(_spawner: Spawner) {
     info!("Hello World!");
@@ -46,7 +51,15 @@ async fn main(_spawner: Spawner) {
     // Create the driver, from the HAL.
     let mut ep_out_buffer = [0u8; 256];
     let mut config = embassy_stm32::usb::Config::default();
+
+    // Enable vbus_detection
+    // Note: some boards don't have this wired up and might not require it,
+    // as they are powered through usb!
+    // If you hang on boot, try setting this to "false"!
+    // See https://embassy.dev/book/dev/faq.html#_the_usb_examples_are_not_working_on_my_board_is_there_anything_else_i_need_to_configure
+    // for more information
     config.vbus_detection = true;
+
     let driver = Driver::new_fs(p.USB_OTG_FS, Irqs, p.PA12, p.PA11, &mut ep_out_buffer, config);
 
     // Create embassy-usb Config
diff --git a/examples/stm32h7/src/bin/usb_serial.rs b/examples/stm32h7/src/bin/usb_serial.rs
index 576506ad3..872ff815c 100644
--- a/examples/stm32h7/src/bin/usb_serial.rs
+++ b/examples/stm32h7/src/bin/usb_serial.rs
@@ -15,6 +15,11 @@ bind_interrupts!(struct Irqs {
     OTG_FS => usb::InterruptHandler<peripherals::USB_OTG_FS>;
 });
 
+// If you are trying this and your USB device doesn't connect, the most
+// common issues are the RCC config and vbus_detection
+//
+// See https://embassy.dev/book/dev/faq.html#_the_usb_examples_are_not_working_on_my_board_is_there_anything_else_i_need_to_configure
+// for more information.
 #[embassy_executor::main]
 async fn main(_spawner: Spawner) {
     info!("Hello World!");
@@ -47,7 +52,15 @@ async fn main(_spawner: Spawner) {
     // Create the driver, from the HAL.
     let mut ep_out_buffer = [0u8; 256];
     let mut config = embassy_stm32::usb::Config::default();
+
+    // Enable vbus_detection
+    // Note: some boards don't have this wired up and might not require it,
+    // as they are powered through usb!
+    // If you hang on boot, try setting this to "false"!
+    // See https://embassy.dev/book/dev/faq.html#_the_usb_examples_are_not_working_on_my_board_is_there_anything_else_i_need_to_configure
+    // for more information
     config.vbus_detection = true;
+
     let driver = Driver::new_fs(p.USB_OTG_FS, Irqs, p.PA12, p.PA11, &mut ep_out_buffer, config);
 
     // Create embassy-usb Config
diff --git a/examples/stm32l4/src/bin/usb_serial.rs b/examples/stm32l4/src/bin/usb_serial.rs
index 198504b59..b905fc66f 100644
--- a/examples/stm32l4/src/bin/usb_serial.rs
+++ b/examples/stm32l4/src/bin/usb_serial.rs
@@ -16,6 +16,11 @@ bind_interrupts!(struct Irqs {
     OTG_FS => usb::InterruptHandler<peripherals::USB_OTG_FS>;
 });
 
+// If you are trying this and your USB device doesn't connect, the most
+// common issues are the RCC config and vbus_detection
+//
+// See https://embassy.dev/book/dev/faq.html#_the_usb_examples_are_not_working_on_my_board_is_there_anything_else_i_need_to_configure
+// for more information.
 #[embassy_executor::main]
 async fn main(_spawner: Spawner) {
     info!("Hello World!");
@@ -41,7 +46,15 @@ async fn main(_spawner: Spawner) {
     // Create the driver, from the HAL.
     let mut ep_out_buffer = [0u8; 256];
     let mut config = embassy_stm32::usb::Config::default();
+
+    // Enable vbus_detection
+    // Note: some boards don't have this wired up and might not require it,
+    // as they are powered through usb!
+    // If you hang on boot, try setting this to "false"!
+    // See https://embassy.dev/book/dev/faq.html#_the_usb_examples_are_not_working_on_my_board_is_there_anything_else_i_need_to_configure
+    // for more information
     config.vbus_detection = true;
+
     let driver = Driver::new_fs(p.USB_OTG_FS, Irqs, p.PA12, p.PA11, &mut ep_out_buffer, config);
 
     // Create embassy-usb Config