feat(bluetooth): stream input over usb (2026.6.20.3-8A2E)

Route Bluetooth personas over local CDC for live controller input.

Add Bluetooth bundle reports and Pico BT state diagnostics.

Keep run-mode CDC ports out of setup recovery.

Author: RealWhyKnot

bridge/src/cdc.rs

@@ -19,8 +19,8 @@ use zeroize::Zeroize;
 
 use crate::firmware_version::FirmwareVersion;
 
-/// Pico setup-mode USB IDs. Distinct from the run-mode HID PID so Windows
-/// does not cache one driver binding across a descriptor change.
+/// CouchLink CDC USB IDs. Setup mode and Bluetooth run mode both use this
+/// identity; wired USB-output run personas use separate descriptors.
 pub const SETUP_VID: u16 = 0x2E8A;
 pub const SETUP_PID: u16 = 0xCAF0;
 
@@ -42,6 +42,8 @@ pub const CMD_SET_DEVICE_NAME: u8 = 0x08;
 pub const CMD_GET_UNIQUE_ID: u8 = 0x09;
 pub const CMD_GET_LOG_BUFFER: u8 = 0x0A;
 pub const CMD_REBOOT_TO_BOOTSEL: u8 = 0x0B;
+pub const CMD_BT_STATE: u8 = 0x0C;
+pub const CMD_BT_HEARTBEAT: u8 = 0x0D;
 
 // Response opcodes
 pub const RSP_HELLO: u8 = 0x81;
@@ -54,6 +56,8 @@ pub const RSP_SET_DEVICE_NAME: u8 = 0x88;
 pub const RSP_UNIQUE_ID: u8 = 0x89;
 pub const RSP_LOG_BUFFER: u8 = 0x8A;
 pub const RSP_REBOOT_TO_BOOTSEL: u8 = 0x8B;
+pub const RSP_BT_STATE: u8 = 0x8C;
+pub const RSP_BT_HEARTBEAT: u8 = 0x8D;
 pub const RSP_NACK: u8 = 0xFE;
 
 /// Short human label for a response opcode, used in the rare "unexpected
@@ -71,6 +75,8 @@ fn response_name(command: u8) -> &'static str {
         RSP_UNIQUE_ID => "UNIQUE_ID",
         RSP_LOG_BUFFER => "LOG_BUFFER",
         RSP_REBOOT_TO_BOOTSEL => "REBOOT_TO_BOOTSEL_ACK",
+        RSP_BT_STATE => "BT_STATE_ACK",
+        RSP_BT_HEARTBEAT => "BT_HEARTBEAT_ACK",
         RSP_NACK => "NACK",
         _ => "unknown",
     }
@@ -88,6 +94,11 @@ pub const ERR_AUTH_FAIL: u8 = 0x11;
 pub const ERR_NO_2G_NETWORK: u8 = 0x12;
 pub const ERR_INTERNAL: u8 = 0xFF;
 
+pub const HELLO_FLAG_CREDS_PRESENT: u8 = 0x01;
+pub const HELLO_FLAG_WIFI_JOINED: u8 = 0x02;
+pub const HELLO_FLAG_RUN_MODE_OK: u8 = 0x04;
+pub const HELLO_FLAG_RUN_MODE_ACTIVE: u8 = 0x08;
+
 pub fn err_name(code: u8) -> &'static str {
     match code {
         ERR_BAD_CRC => "bad CRC",
@@ -231,6 +242,15 @@ impl PicoSetup {
         Ok(resp)
     }
 
+    pub fn write_frame_no_response(&mut self, command: u8, seq: u8, payload: &[u8]) -> Result<()> {
+        let frame = encode(command, seq, payload);
+        self.port.write_all(&frame).context("writing CDC frame")?;
+        if let Err(e) = self.port.flush() {
+            tracing::debug!("cdc: flush after write returned {e:?}");
+        }
+        Ok(())
+    }
+
     // Like exchange() but produces a command-specific NACK error message.
     fn exchange_named(
         &mut self,
@@ -712,7 +732,11 @@ pub struct HelloAck {
 
 impl HelloAck {
     pub fn creds_present(&self) -> bool {
-        self.flags & 0x01 != 0
+        self.flags & HELLO_FLAG_CREDS_PRESENT != 0
+    }
+
+    pub fn run_mode_active(&self) -> bool {
+        self.flags & HELLO_FLAG_RUN_MODE_ACTIVE != 0
     }
 
     pub fn firmware_version(&self) -> FirmwareVersion {

bridge/src/cmd_bundle/manifest.rs

@@ -8,7 +8,7 @@ use crate::{config, logfile};
 
 use super::collect::BUNDLE_LOG_FILES_PER_PREFIX;
 
-pub(super) const BUNDLE_SCHEMA_VERSION: u8 = 22;
+pub(super) const BUNDLE_SCHEMA_VERSION: u8 = 23;
 
 #[derive(Clone, Debug, Serialize)]
 pub(super) struct ManifestPicoCapture {
@@ -24,6 +24,7 @@ pub(super) struct ManifestPicoCapture {
     pub pico_state_status: String,
     pub usb_packet_dump_status: String,
     pub usb_packet_dump_count: usize,
+    pub bluetooth_report_status: String,
     pub cached_state_included: bool,
 }
 
@@ -73,6 +74,10 @@ pub(super) struct Manifest {
     adapter_survey_path: &'static str,
     adapter_survey_json_included: bool,
     adapter_survey_json_path: &'static str,
+    bluetooth_report_included: bool,
+    bluetooth_report_path: &'static str,
+    bluetooth_report_json_included: bool,
+    bluetooth_report_json_path: &'static str,
     app_log_retention_count: usize,
     bundled_log_files_per_prefix: usize,
     debug_packet_log_retention_count: usize,
@@ -164,6 +169,10 @@ pub(super) async fn build_manifest(
         adapter_survey_path: "adapter-survey.txt",
         adapter_survey_json_included: true,
         adapter_survey_json_path: "adapter-survey.json",
+        bluetooth_report_included: true,
+        bluetooth_report_path: "bluetooth-report.txt",
+        bluetooth_report_json_included: true,
+        bluetooth_report_json_path: "bluetooth-report.json",
         app_log_retention_count: logfile::LOG_FILE_RETENTION,
         bundled_log_files_per_prefix: BUNDLE_LOG_FILES_PER_PREFIX,
         debug_packet_log_retention_count: crate::debug_packets::DEBUG_PACKET_FILE_RETENTION,
@@ -198,6 +207,8 @@ pub(super) async fn build_manifest(
             "initial-usb-capture.txt preserves USB packet lines harvested before bundle switches personas.",
             "adapter-survey.txt and adapter-survey.json record live persona checks for PS3, generic HID, PS4, keyboard, XInput, Xbox One, and Maple shapes without prompting, including expected, attempted, missing, failed, coverage_status, and stop_reason fields.",
             "Bundle restores the original persona after the adapter survey pass.",
+            "Bluetooth mode is captured separately in bluetooth-report.txt and bluetooth-report.json because the Pico stays plugged into the PC and receives live controller input over USB CDC.",
+            "Bluetooth mode does not use the USB adapter survey; its live controller packet path is PC USB CDC to Pico, then Bluetooth HID to the paired receiver.",
             "Debug input mode uses the XInput USB shape; debug evidence is not treated as proof that a HID persona works with an adapter.",
             "When a surveyed persona gets descriptor traffic but does not configure, bundle requests a one-shot USB packet capture boot for that same persona.",
             "If persona switching, USB diagnostic queries, packet capture, or persona restore cannot complete, bundle-capture.txt records the failed step, duration, and reason.",
@@ -266,6 +277,7 @@ mod tests {
             pico_state_status: "captured".to_string(),
             usb_packet_dump_status: "captured".to_string(),
             usb_packet_dump_count: 2,
+            bluetooth_report_status: "not_applicable".to_string(),
             cached_state_included: true,
         };
         let host = ManifestHostSnapshot {
@@ -324,6 +336,10 @@ mod tests {
         assert_eq!(json["adapter_survey_path"], "adapter-survey.txt");
         assert_eq!(json["adapter_survey_json_included"], true);
         assert_eq!(json["adapter_survey_json_path"], "adapter-survey.json");
+        assert_eq!(json["bluetooth_report_included"], true);
+        assert_eq!(json["bluetooth_report_path"], "bluetooth-report.txt");
+        assert_eq!(json["bluetooth_report_json_included"], true);
+        assert_eq!(json["bluetooth_report_json_path"], "bluetooth-report.json");
         assert_eq!(
             json["retained_debug_packet_logs"][0],
             "usb-packets-20260615-214000-02E22DA9.log"