nordic-dev.net/embassy
2
0
Fork 0
mirror of https://github.com/embassy-rs/embassy.git synced 2024-11-21 22:32:29 +00:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #2849 from joelsa/add-vbus-faq

Browse Source 
Add information about vbus_detection to the FAQ and link it in all USB examples.
This commit is contained in:
Dario Nieuwenhuis 2024-04-22 13:29:38 +00:00 committed by GitHub
commit e581c9f027
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
10 changed files with 126 additions and 3 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

20
docs/modules/ROOT/pages/faq.adoc
View File

@ -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!

4
embassy-stm32/src/usb/otg.rs
View File

@ -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

13
examples/stm32f4/src/bin/usb_ethernet.rs
View File

@ -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

14
examples/stm32f4/src/bin/usb_hid_keyboard.rs
View File

@ -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

13
examples/stm32f4/src/bin/usb_hid_mouse.rs
View File

@ -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

13
examples/stm32f4/src/bin/usb_raw.rs
View File

@ -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

13
examples/stm32f4/src/bin/usb_serial.rs
View File

@ -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

13
examples/stm32f7/src/bin/usb_serial.rs
View File

@ -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

13
examples/stm32h7/src/bin/usb_serial.rs
View File

@ -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

13
examples/stm32l4/src/bin/usb_serial.rs
View File

@ -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