@@ -75,6 +75,16 @@ if(DEFINED PICO_BOARD)
         add_compile_definitions(PICO_CYW43_SUPPORTED=1)
     endif()
 
+    if(PICOFUSE_USB)
+        # Every RP2040/RP2350 board has the same on-chip dual-role USB
+        # controller (unlike CYW43 above, nothing board-specific to check).
+        # hw/pico/usb.c (compiled instead of the stub only when PICOFUSE_USB
+        # holds - see its own CMakeLists.txt) needs the TinyUSB host stack;
+        # tusb_config.h (include/runtime/pico) configures it for host-only,
+        # no interface class drivers - see that file's own doc.
+        list(APPEND _picosdk_targets tinyusb_host)
+    endif()
+
     # Generate the combined Pico SDK bundle
     set(_pico_clib_interface_dir ${PICO_SDK_PATH}/src/rp2_common/pico_clib_interface)
     set(_pico_runtime_dir ${PICO_SDK_PATH}/src/rp2_common/pico_runtime)
 
@@ -39,6 +39,7 @@ digraph modules {
   UART        [label="UART",                     URL="\ref UART"];
   DeviceIO    [label="Device I/O",               URL="\ref DeviceIO"];
   Watchdog    [label="Watchdog",                 URL="\ref Watchdog"];
+  USB         [label="USB",                      URL="\ref USB"];
   SPI         [label="SPI",                      URL="\ref SPI"];
   I2C         [label="I2C",                      URL="\ref I2C"];
   Device      [label="Device",                   URL="\ref Device"];
@@ -87,6 +88,7 @@ digraph modules {
   Hardware -> UART;
   Hardware -> DeviceIO;
   Hardware -> Watchdog;
+  Hardware -> USB;
   DeviceIO -> SPI;
   DeviceIO -> I2C;
   Device -> BME680;
 
@@ -71,6 +71,17 @@ typedef enum {
                                    ///< it from there. Has no effect when
                                    ///< the platform has no watchdog
                                    ///< backend.
+  app_flag_usb = (1 << 8),         ///< Initialize the USB host subsystem
+                                   ///< and register it with HID (see
+                                   ///< @ref app_usb and @ref app_hid) -
+                                   ///< hotplug activity flows in as
+                                   ///< hid_event_type_usb events
+                                   ///< automatically. Call
+                                   ///< hw_usb_set_callback() directly on
+                                   ///< the returned handle to replace that
+                                   ///< with your own callback instead. Has
+                                   ///< no effect when the platform has no
+                                   ///< USB host backend.
 } app_flag_t;
 
 /**
@@ -133,13 +144,15 @@ typedef void (*app_callback_event_t)(app_t *app, sys_event_t event,
  * internal temperature sensor as a HID metric source if
  * @ref app_flag_temperature is set, enables the watchdog if
  * @ref app_flag_watchdog is set and available (see @ref app_watchdog),
- * then runs the event loop across every available core if
- * @ref app_flag_multicore is set, or on the calling thread alone
- * otherwise. Every run loop tick calls `hw_poll()`, which feeds the
- * watchdog when enabled (see `hw_watchdog_enable()`). Blocks until
- * @ref app_shutdown is called from within a callback (or from another
- * thread), then tears down (`hid_deinit()`, `hw_led_deinit()`,
- * `hw_watchdog_deinit()`, `hw_exit()`, `sys_exit()`).
+ * initializes the USB host subsystem and registers it with HID if
+ * @ref app_flag_usb is set and available (see @ref app_usb and
+ * hw_usb_register_hid()), then runs the event loop across every
+ * available core if @ref app_flag_multicore is set, or on the calling
+ * thread alone otherwise. Every run loop tick calls `hw_poll()`, which
+ * feeds the watchdog when enabled (see `hw_watchdog_enable()`). Blocks
+ * until @ref app_shutdown is called from within a callback (or from
+ * another thread), then tears down (`hid_deinit()`, `hw_led_deinit()`,
+ * `hw_watchdog_deinit()`, `hw_usb_deinit()`, `hw_exit()`, `sys_exit()`).
  */
 int app_main(int argc, char *argv[], app_flag_t flags,
              app_callback_start_t on_start, app_callback_event_t on_event,
@@ -188,6 +201,20 @@ hw_led_t *app_led(const app_t *app);
  */
 hw_watchdog_t *app_watchdog(const app_t *app);
 
+/**
+ * @brief Get the USB host handle initialized for this app.
+ * @ingroup Application
+ * @param app Application instance.
+ * @return USB host handle, or NULL if @ref app_flag_usb was not passed to
+ * app_main(), or the platform has no USB host backend (see hw_usb_init()).
+ *
+ * Already registered with HID (see @ref app_hid) via hw_usb_register_hid()
+ * - hotplug activity flows in as hid_event_type_usb events. Call
+ * hw_usb_set_callback() directly on this handle to replace that with your
+ * own callback instead.
+ */
+hw_usb_t *app_usb(const app_t *app);
+
 /** @} */
 
 ///////////////////////////////////////////////////////////////////////////////
 
@@ -305,28 +305,6 @@ hid_device_t *hid_register_timer(hid_t *instance, uint32_t id,
  */
 hid_device_t *hid_register_signal(hid_t *instance, void *userdata);
 
-/**
- * @brief Register a USB host hotplug observer.
- * @ingroup HID
- * @param instance HID instance that owns the USB registration.
- * @return Registered HID device descriptor, or NULL on failure (for
- * example, if the platform has no USB host controller support built in).
- *
- * Initializes the USB host subsystem (see `hw_usb_init()`), which
- * enumerates already-attached devices through the same attach/detach
- * callback used for live hotplug. Only one USB registration is permitted
- * at a time, since `hw_usb_init()` is itself a process-wide singleton.
- *
- * Attach/detach activity is currently only logged via `sys_debugf()`; it
- * is not yet delivered as HID events.
- *
- * @todo Not implemented yet - always returns NULL. There is no
- * `hw_usb_init()`/`hw_usb_t` backend anywhere in this codebase yet (see
- * `src/picofuse/hid/usb.c`); this needs a real USB host module under
- * `picofuse/hw` before this can do anything.
- */
-hid_device_t *hid_register_usb(hid_t *instance);
-
 /**
  * @brief Register a Wi-Fi connection-state observer.
  * @ingroup HID
 
@@ -26,6 +26,7 @@
 #pragma once
 #include "device.h"
 #include "keycode.h"
+#include <picofuse/hw/usb.h>
 #include <picofuse/hw/wifi.h>
 #include <picofuse/pix/types.h>
 #include <picofuse/sys/date.h>
@@ -60,6 +61,7 @@ typedef enum {
   hid_event_type_wifi = 6,
   hid_event_type_iostream = 7,
   hid_event_type_time = 8,
+  hid_event_type_usb = 9,
 } hid_event_type_t;
 
 /**
@@ -126,6 +128,25 @@ typedef struct {
   bool has_network;          ///< True if network is populated.
 } hid_wifi_t;
 
+/**
+ * @brief USB-hotplug-oriented HID event payload.
+ * @ingroup HIDEvents
+ *
+ * @p device is copied by value into this event at the point it's queued -
+ * unlike hw_usb_callback_t's own @p device parameter (which some backends
+ * pass as a pointer to worker-thread-local storage, valid only for the
+ * duration of that callback), this is safe to read at any point up until
+ * hid_event_free(). @p has_device is false for the enumeration-complete
+ * marker (see hw_usb_init()'s own doc), in which case @p device itself is
+ * unspecified.
+ */
+typedef struct {
+  hw_usb_event_t event;   ///< USB hotplug event (see hw_usb_event_t).
+  hw_usb_device_t device; ///< Associated device - only valid if has_device
+                          ///< is true.
+  bool has_device;        ///< True if device is populated.
+} hid_usb_t;
+
 /**
  * @brief Stream-readiness-oriented HID event payload.
  * @ingroup HIDEvents
@@ -161,6 +182,7 @@ typedef struct {
     hid_wifi_t wifi;
     hid_iostream_t iostream;
     hid_time_t time;
+    hid_usb_t usb;
   } data; ///< Payload selected by type.
 } hid_event_t;
 
@@ -237,6 +259,19 @@ bool hid_event_queue_signal(hid_device_t *device, sys_env_signal_t signal);
 bool hid_event_queue_wifi(hid_device_t *device, hw_wifi_event_t event,
                           const hw_wifi_network_t *network);
 
+/**
+ * @brief Queue a USB hotplug HID event to the owning HID instance queue.
+ * @ingroup HIDEvents
+ * @param device HID device associated with the event.
+ * @param event USB hotplug event to publish (see hw_usb_event_t).
+ * @param usb_device Associated device, or NULL for the enumeration-complete
+ * marker. Copied by value into the queued event - see hid_usb_t.
+ * @retval true Event queued successfully.
+ * @retval false Queueing failed.
+ */
+bool hid_event_queue_usb(hid_device_t *device, hw_usb_event_t event,
+                         const hw_usb_device_t *usb_device);
+
 /**
  * @brief Queue a stream-readiness HID event to the owning HID instance
  * queue.
 
@@ -17,5 +17,6 @@
 #include "hw/pwm.h"
 #include "hw/spi.h"
 #include "hw/uart.h"
+#include "hw/usb.h"
 #include "hw/watchdog.h"
 #include "hw/wifi.h"