Merge #711

711: Add DeviceStateHandler, DeviceCommand channel, and remote wakeup support r=Dirbaio a=alexmoon

Apologies for the size of this PR. Once I started getting into the Vbus power management side of my device I found a couple of areas of functionality missing from embassy-usb. Specifically, I need the application to be able to respond to changes in the USB device state in order to properly control the amount of power I'm drawing from Vbus. I also wanted to enable remote wakeup support for my device.

In order to enable device state monitoring, I've created a `DeviceStateHandler` trait and made it possible to pass in an optional reference a handler implementing that trait when creating the `UsbDeviceBuilder`.

Remote wakeup required a way to send commands to the bus which is exclusively owned by the `UsbDevice::run` method. This is the same problem we were discussing for enabling/disabling the device on Vbus power events. My solution is to allow an optional `Channel` to be provided to the `UsbDeviceBuilder` (via `UsbDeviceBuilder::new_with_channel`), allowing the application to send commands into the `run` method. Right now it supports enable, disable and remote wakeup commands.

Since there's now a way to dynamically enable and disable the device, I also added `Config::start_enabled` to control whether or not the `UsbDevice` should start in the enabled state. That also allowed me to make `UsbDeviceBuilder::build` sync again and move enabling the bus into `UsbDevice::run`.

This led to a few driver changes:
1. `Driver::enable` became `Driver::into_bus`
2. `Bus::enable`, `Bus::disable`, and `Bus::remote_wakeup` were added
3. I removed `Bus::reset`, `Bus::suspend`, and `Bus::resume` because they were only ever called based on the result of `Bus::poll`. It made more sense to me to have `Bus::poll` handle the driver-specific state management itself.

I've updated the `usb_hid_keyboard` example to take advantage of all these additional features.

Let me know what you think.

Thanks!


Co-authored-by: alexmoon <alex.r.moon@gmail.com>

examples/nrf/src/bin/usb_hid_keyboard.rs

@@ -4,16 +4,20 @@
 #![feature(type_alias_impl_trait)]
 
 use core::mem;
+use core::sync::atomic::{AtomicBool, Ordering};
 use defmt::*;
+use embassy::channel::Signal;
 use embassy::executor::Spawner;
+use embassy::interrupt::InterruptExt;
 use embassy::time::Duration;
+use embassy::util::{select, select3, Either, Either3};
 use embassy_nrf::gpio::{Input, Pin, Pull};
 use embassy_nrf::interrupt;
 use embassy_nrf::pac;
 use embassy_nrf::usb::Driver;
 use embassy_nrf::Peripherals;
 use embassy_usb::control::OutResponse;
-use embassy_usb::{Config, UsbDeviceBuilder};
+use embassy_usb::{Config, DeviceStateHandler, UsbDeviceBuilder};
 use embassy_usb_hid::{HidClass, ReportId, RequestHandler, State};
 use futures::future::join;
 use usbd_hid::descriptor::{KeyboardReport, SerializedDescriptor};
@@ -21,6 +25,25 @@ use usbd_hid::descriptor::{KeyboardReport, SerializedDescriptor};
 use defmt_rtt as _; // global logger
 use panic_probe as _;
 
+static ENABLE_USB: Signal<bool> = Signal::new();
+static SUSPENDED: AtomicBool = AtomicBool::new(false);
+
+fn on_power_interrupt(_: *mut ()) {
+    let regs = unsafe { &*pac::POWER::ptr() };
+
+    if regs.events_usbdetected.read().bits() != 0 {
+        regs.events_usbdetected.reset();
+        info!("Vbus detected, enabling USB...");
+        ENABLE_USB.signal(true);
+    }
+
+    if regs.events_usbremoved.read().bits() != 0 {
+        regs.events_usbremoved.reset();
+        info!("Vbus removed, disabling USB...");
+        ENABLE_USB.signal(false);
+    }
+}
+
 #[embassy::main]
 async fn main(_spawner: Spawner, p: Peripherals) {
     let clock: pac::CLOCK = unsafe { mem::transmute(()) };
@@ -30,10 +53,6 @@ async fn main(_spawner: Spawner, p: Peripherals) {
     clock.tasks_hfclkstart.write(|w| unsafe { w.bits(1) });
     while clock.events_hfclkstarted.read().bits() != 1 {}
 
-    info!("Waiting for vbus...");
-    while !power.usbregstatus.read().vbusdetect().is_vbus_present() {}
-    info!("vbus OK");
-
     // Create the driver, from the HAL.
     let irq = interrupt::take!(USBD);
     let driver = Driver::new(p.USBD, irq);
@@ -45,6 +64,7 @@ async fn main(_spawner: Spawner, p: Peripherals) {
     config.serial_number = Some("12345678");
     config.max_power = 100;
     config.max_packet_size_0 = 64;
+    config.supports_remote_wakeup = true;
 
     // Create embassy-usb DeviceBuilder using the driver and config.
     // It needs some buffers for building the descriptors.
@@ -53,6 +73,7 @@ async fn main(_spawner: Spawner, p: Peripherals) {
     let mut bos_descriptor = [0; 256];
     let mut control_buf = [0; 16];
     let request_handler = MyRequestHandler {};
+    let device_state_handler = MyDeviceStateHandler::new();
 
     let mut state = State::<8, 1>::new();
 
@@ -63,6 +84,7 @@ async fn main(_spawner: Spawner, p: Peripherals) {
         &mut config_descriptor,
         &mut bos_descriptor,
         &mut control_buf,
+        Some(&device_state_handler),
     );
 
     // Create classes on the builder.
@@ -76,10 +98,40 @@ async fn main(_spawner: Spawner, p: Peripherals) {
     );
 
     // Build the builder.
-    let mut usb = builder.build().await;
+    let mut usb = builder.build();
+
+    let remote_wakeup = Signal::new();
 
     // Run the USB device.
-    let usb_fut = usb.run();
+    let usb_fut = async {
+        enable_command().await;
+        loop {
+            match select(usb.run_until_suspend(), ENABLE_USB.wait()).await {
+                Either::First(_) => {}
+                Either::Second(enable) => {
+                    if enable {
+                        warn!("Enable when already enabled!");
+                    } else {
+                        usb.disable().await;
+                        enable_command().await;
+                    }
+                }
+            }
+
+            match select3(usb.wait_resume(), ENABLE_USB.wait(), remote_wakeup.wait()).await {
+                Either3::First(_) => (),
+                Either3::Second(enable) => {
+                    if enable {
+                        warn!("Enable when already enabled!");
+                    } else {
+                        usb.disable().await;
+                        enable_command().await;
+                    }
+                }
+                Either3::Third(_) => unwrap!(usb.remote_wakeup().await),
+            }
+        }
+    };
 
     let mut button = Input::new(p.P0_11.degrade(), Pull::Up);
 
@@ -90,16 +142,22 @@ async fn main(_spawner: Spawner, p: Peripherals) {
         loop {
             button.wait_for_low().await;
             info!("PRESSED");
-            let report = KeyboardReport {
-                keycodes: [4, 0, 0, 0, 0, 0],
-                leds: 0,
-                modifier: 0,
-                reserved: 0,
-            };
-            match hid_in.serialize(&report).await {
-                Ok(()) => {}
-                Err(e) => warn!("Failed to send report: {:?}", e),
-            };
+
+            if SUSPENDED.load(Ordering::Acquire) {
+                info!("Triggering remote wakeup");
+                remote_wakeup.signal(());
+            } else {
+                let report = KeyboardReport {
+                    keycodes: [4, 0, 0, 0, 0, 0],
+                    leds: 0,
+                    modifier: 0,
+                    reserved: 0,
+                };
+                match hid_in.serialize(&report).await {
+                    Ok(()) => {}
+                    Err(e) => warn!("Failed to send report: {:?}", e),
+                };
+            }
 
             button.wait_for_high().await;
             info!("RELEASED");
@@ -119,11 +177,31 @@ async fn main(_spawner: Spawner, p: Peripherals) {
     let out_fut = async {
         hid_out.run(false, &request_handler).await;
     };
+
+    let power_irq = interrupt::take!(POWER_CLOCK);
+    power_irq.set_handler(on_power_interrupt);
+    power_irq.unpend();
+    power_irq.enable();
+
+    power
+        .intenset
+        .write(|w| w.usbdetected().set().usbremoved().set());
+
     // Run everything concurrently.
     // If we had made everything `'static` above instead, we could do this using separate tasks instead.
     join(usb_fut, join(in_fut, out_fut)).await;
 }
 
+async fn enable_command() {
+    loop {
+        if ENABLE_USB.wait().await {
+            break;
+        } else {
+            warn!("Received disable signal when already disabled!");
+        }
+    }
+}
+
 struct MyRequestHandler {}
 
 impl RequestHandler for MyRequestHandler {
@@ -146,3 +224,64 @@ impl RequestHandler for MyRequestHandler {
         None
     }
 }
+
+struct MyDeviceStateHandler {
+    configured: AtomicBool,
+}
+
+impl MyDeviceStateHandler {
+    fn new() -> Self {
+        MyDeviceStateHandler {
+            configured: AtomicBool::new(false),
+        }
+    }
+}
+
+impl DeviceStateHandler for MyDeviceStateHandler {
+    fn enabled(&self, enabled: bool) {
+        self.configured.store(false, Ordering::Relaxed);
+        SUSPENDED.store(false, Ordering::Release);
+        if enabled {
+            info!("Device enabled");
+        } else {
+            info!("Device disabled");
+        }
+    }
+
+    fn reset(&self) {
+        self.configured.store(false, Ordering::Relaxed);
+        info!("Bus reset, the Vbus current limit is 100mA");
+    }
+
+    fn addressed(&self, addr: u8) {
+        self.configured.store(false, Ordering::Relaxed);
+        info!("USB address set to: {}", addr);
+    }
+
+    fn configured(&self, configured: bool) {
+        self.configured.store(configured, Ordering::Relaxed);
+        if configured {
+            info!(
+                "Device configured, it may now draw up to the configured current limit from Vbus."
+            )
+        } else {
+            info!("Device is no longer configured, the Vbus current limit is 100mA.");
+        }
+    }
+
+    fn suspended(&self, suspended: bool) {
+        if suspended {
+            info!("Device suspended, the Vbus current limit is 500µA (or 2.5mA for high-power devices with remote wakeup enabled).");
+            SUSPENDED.store(true, Ordering::Release);
+        } else {
+            SUSPENDED.store(false, Ordering::Release);
+            if self.configured.load(Ordering::Relaxed) {
+                info!(
+                    "Device resumed, it may now draw up to the configured current limit from Vbus"
+                );
+            } else {
+                info!("Device resumed, the Vbus current limit is 100mA");
+            }
+        }
+    }
+}

examples/nrf/src/bin/usb_hid_mouse.rs

@@ -61,6 +61,7 @@ async fn main(_spawner: Spawner, p: Peripherals) {
         &mut config_descriptor,
         &mut bos_descriptor,
         &mut control_buf,
+        None,
     );
 
     // Create classes on the builder.
@@ -74,7 +75,7 @@ async fn main(_spawner: Spawner, p: Peripherals) {
     );
 
     // Build the builder.
-    let mut usb = builder.build().await;
+    let mut usb = builder.build();
 
     // Run the USB device.
     let usb_fut = usb.run();

examples/nrf/src/bin/usb_serial.rs

@@ -54,13 +54,14 @@ async fn main(_spawner: Spawner, p: Peripherals) {
         &mut config_descriptor,
         &mut bos_descriptor,
         &mut control_buf,
+        None,
     );
 
     // Create classes on the builder.
     let mut class = CdcAcmClass::new(&mut builder, &mut state, 64);
 
     // Build the builder.
-    let mut usb = builder.build().await;
+    let mut usb = builder.build();
 
     // Run the USB device.
     let usb_fut = usb.run();

examples/nrf/src/bin/usb_serial_multitask.rs

@@ -79,13 +79,14 @@ async fn main(spawner: Spawner, p: Peripherals) {
         &mut res.config_descriptor,
         &mut res.bos_descriptor,
         &mut res.control_buf,
+        None,
     );
 
     // Create classes on the builder.
     let class = CdcAcmClass::new(&mut builder, &mut res.serial_state, 64);
 
     // Build the builder.
-    let usb = builder.build().await;
+    let usb = builder.build();
 
     unwrap!(spawner.spawn(usb_task(usb)));
     unwrap!(spawner.spawn(echo_task(class)));