Adom USB

@@ -293,6 +293,7 @@ webview can embed it). | POST | `/test` | `{device_id}` | `lsusb -v` + enumerate/echo health check | | POST | `/class-override` | `{device_id}` | bind a forced driver class (HID / storage / serial) | | POST | `/sniff` | `{device_id}` | capture USB packets — **dispatches to a matching plugin** if one is installed, else built-in usbmon |+| POST | `/flash` | `{device_id, persona}` | flash a stub-firmware persona via a matching **firmware device-test pack** (e.g. RP2040 → HID keyboard) | | GET | `/plugins` | — | `{installed, available, tag, api_version}` | | POST | `/console` | log entry | UI console forwarding | | GET | `/console` | — | ring buffer of UI logs (AI debugging) |@@ -516,6 +517,80 @@ devices to it.  --- +## Firmware device-test packs (manufacturer device personas)++A second plugin kind — **`kind: "firmware"`** — lets a manufacturer or third+party ship a *device-test pack*: stub firmware + a flash method + a catalog of+**USB personas** their chip can become. You plug the chip into the mesh, pick a+persona, the pack flashes the stub, and the device **re-enumerates as that USB+class** so you can immediately mount / test / sniff it.++This is how you answer "does my USB host stack handle a keyboard? a disk? a+serial port?" without writing firmware — flash `hid-keyboard`, watch it type;+flash `msc-disk`, mount it; flash `cdc-serial`, open the port.++A firmware pack's manifest adds `vendor`, `chips`, `flash_method`, and a+`personas` catalog:++```jsonc+{+  "slug": "adom-usb-stub-rp2040", "kind": "firmware", "api_version": "1",+  "entrypoint": "adom-usb-stub-rp2040",+  "vendor": "Raspberry Pi", "chips": ["rp2040"],+  "matches": { "vid": ["2e8a"], "pid": ["*"] },     // matched by chip vid/pid+  "flash_method": "uf2-bootsel",                     // picotool / dfu-util / esptool / nrfutil / openocd / bossac / wchisp+  "personas": [+    {"id":"msc-disk",     "name":"Mass-storage disk",  "usb_class":"Mass storage",  "result_vid":"2e8a","result_pid":"0009"},+    {"id":"hid-keyboard", "name":"HID keyboard",        "usb_class":"HID keyboard"},+    {"id":"hid-mouse",    "name":"HID mouse",           "usb_class":"HID mouse"},+    {"id":"cdc-serial",   "name":"CDC serial echo",     "usb_class":"CDC serial"},+    {"id":"midi",         "name":"USB-MIDI",            "usb_class":"Audio/MIDI"}+  ]+}+```++The firmware-plugin executable contract adds a `flash` subcommand (and+`personas`):++```bash+<entrypoint> manifest                       # prints plugin.json+<entrypoint> personas                       # prints the persona catalog+<entrypoint> flash --persona <id> --vid <hex> --pid <hex> --busid <b> --target <host>+#  -> flashes the stub (picotool / dfu-util / esptool / …) and prints+#     {"ok":true,"persona":"hid-keyboard","method":"uf2-bootsel","status":"flashed","summary":"…"}+```++When a firmware pack matches a device, `adom-usb` shows a **Flash ▾** persona+picker on that row; the `/state` device carries `firmware_plugin` ++`firmware_personas`, and `POST /flash {device_id, persona}` dispatches to the+pack's `flash` entrypoint.++### Sample plugins (install any of these)++A reference fleet is published on the wiki — copy any as a starting point:++| Plugin | Kind | Chip / target | Personas / decoders |+|---|---|---|---|+| `adom-usb-stub-rp2040` | firmware | RP2040 (Raspberry Pi) | disk · keyboard · mouse · serial · MIDI |+| `adom-usb-stub-stm32` | firmware | STM32 (DFU 0483:df11) | disk · kbd · mouse · serial · RNDIS · audio · MIDI · DFU |+| `adom-usb-stub-esp32` | firmware | ESP32-S2/S3 (TinyUSB) | serial · kbd · mouse · disk · MIDI |+| `adom-usb-stub-nrf` | firmware | nRF52840 / nRF5340 | serial · kbd · mouse · disk |+| `adom-usb-stub-ti-sitara` | firmware | TI Sitara AM335x/57x/62x | disk · RNDIS · serial · kbd |+| `adom-usb-stub-samd21` | firmware | SAMD21/51 (Microchip) | disk · kbd · serial · MIDI |+| `adom-usb-stub-ch32` | firmware | CH32V (WCH RISC-V) | serial · kbd · disk |+| `adom-usb-sniffer-cdc` | sniffer | CDC / ACM serial | cdc-acm · at-commands |+| `adom-usb-sniffer-hid` | sniffer | HID keyboard/mouse | hid-report · keyboard · mouse |+| `adom-usb-sniffer-msc` | sniffer | Mass storage / SCSI | scsi-bot · uas |++```bash+adompkg install adom-usb-stub-rp2040+adom-usb flash laptop:2e8a:0003 hid-keyboard   # RP2040 → HID keyboard, then it re-enumerates+```++> The firmware packs ship the flash **contract** as reference templates;+> manufacturers drop their real signed firmware artifacts in+> `firmware/<persona>.<ext>` and publish their own version.+ ## How the app discovers plugins  Discovery has two sources (both in [`src/plugins.rs`](src/plugins.rs)):

@@ -0,0 +1,90 @@+{+  "slug": "adom-usb-stub-rp2040",+  "version": "0.1.0",+  "type": "app",+  "description": "Flash stub firmware to an RP2040 (drag-drop UF2 in BOOTSEL) to enumerate it as a disk, keyboard, mouse, serial, or MIDI device \u2014 test USB host support end-to-end.",+  "dependencies": {},+  "keywords": [+    "adom-usb-plugin",+    "firmware",+    "usb-stub",+    "raspberry"+  ],+  "license": "MIT",+  "scripts": {+    "install": "./install.sh",+    "uninstall": "./uninstall.sh"+  },+  "files": [+    "adom-usb-stub-rp2040",+    "plugin.json",+    "install.sh",+    "uninstall.sh",+    "package.json",+    "README.md",+    "page.json",+    "screenshots/**",+    "skills/**"+  ],+  "adom_usb_plugin": {+    "kind": "firmware",+    "entrypoint": "adom-usb-stub-rp2040",+    "vendor": "Raspberry Pi",+    "chips": [+      "rp2040"+    ],+    "matches": {+      "vid": [+        "2e8a"+      ],+      "pid": [+        "*"+      ]+    },+    "flash_method": "uf2-bootsel",+    "personas": [+      {+        "id": "msc-disk",+        "name": "Mass-storage disk (RAM)",+        "usb_class": "Mass storage",+        "result_vid": "2e8a",+        "result_pid": "0009"+      },+      {+        "id": "hid-keyboard",+        "name": "HID keyboard (types a test string)",+        "usb_class": "HID keyboard",+        "result_vid": "2e8a",+        "result_pid": "000a"+      },+      {+        "id": "hid-mouse",+        "name": "HID mouse (jiggler)",+        "usb_class": "HID mouse",+        "result_vid": "2e8a",+        "result_pid": "000b"+      },+      {+        "id": "cdc-serial",+        "name": "CDC serial echo",+        "usb_class": "CDC serial",+        "result_vid": "2e8a",+        "result_pid": "000c"+      },+      {+        "id": "midi",+        "name": "USB-MIDI",+        "usb_class": "Audio/MIDI",+        "result_vid": "2e8a",+        "result_pid": "000d"+      }+    ],+    "api_version": "1"+  },+  "tags": [+    "adom-usb-plugin",+    "firmware",+    "usb-stub",+    "raspberry"+  ]+}\ No newline at end of file

@@ -176,10 +176,19 @@ pub fn run(args: AppArgs) -> Result<(), String> {                 snap["plugins"] = crate::plugins::to_json(&installed);                 if let Some(devs) = snap.get_mut("devices").and_then(|d| d.as_array_mut()) {                     for d in devs.iter_mut() {-                        let class = d.get("class").and_then(|v| v.as_str()).unwrap_or("");+                        let class = d.get("class").and_then(|v| v.as_str()).unwrap_or("").to_string();                         let vid = d.get("vid").and_then(|v| v.as_u64()).unwrap_or(0) as u16;                         let pid = d.get("pid").and_then(|v| v.as_u64()).unwrap_or(0) as u16;+                        let class = class.as_str();                         d["sniffer_plugin"] = json!(crate::plugins::match_for(class, vid, pid, &installed).map(|p| p.slug.clone()));+                        // Firmware device-test pack: which stub personas can we flash to this chip?+                        if let Some(fw) = crate::plugins::firmware_for(class, vid, pid, &installed) {+                            d["firmware_plugin"] = json!(fw.slug);+                            d["firmware_personas"] = fw.personas.clone();+                        } else {+                            d["firmware_plugin"] = Value::Null;+                            d["firmware_personas"] = json!([]);+                        }                     }                 }                 (200, snap)@@ -206,6 +215,10 @@ pub fn run(args: AppArgs) -> Result<(), String> {                 Ok(body) => handle_unmount(&st, &body),                 Err(e) => (400, json!({"error": e})),             },+            (Method::Post, "/flash") => match read_body(&mut req) {+                Ok(body) => handle_flash(&st, &body),+                Err(e) => (400, json!({"error": e})),+            },             (Method::Post, "/reset") => handle_device_op(&st, &mut req, "reset"),             (Method::Post, "/test") => handle_device_op(&st, &mut req, "test"),             (Method::Post, "/class-override") => handle_device_op(&st, &mut req, "class_override"),@@ -322,6 +335,53 @@ fn handle_unmount(st: &AppState, body: &Value) -> (u16, Value) {     (200, json!({"ok": true, "device_id": device_id, "command": cmd})) } +/// Flash a stub-firmware persona onto a device via a matching firmware plugin+/// (e.g. make an RP2040 enumerate as a HID keyboard). Dispatches to the plugin's+/// `flash` entrypoint and records the exact command.+fn handle_flash(st: &AppState, body: &Value) -> (u16, Value) {+    let device_id = match body.get("device_id").and_then(|v| v.as_str()) {+        Some(s) => s.to_string(),+        None => return (400, json!({"error": "device_id required"})),+    };+    let persona = match body.get("persona").and_then(|v| v.as_str()) {+        Some(s) => s.to_string(),+        None => return (400, json!({"error": "persona required (see firmware_personas in /state)"})),+    };+    let snap = snapshot(st);+    let dev = match find_device(&snap, &device_id) {+        Some(d) => d,+        None => return (404, json!({"error": format!("unknown device: {}", device_id)})),+    };+    let class = dev.get("class").and_then(|v| v.as_str()).unwrap_or("");+    let vid = dev.get("vid").and_then(|v| v.as_u64()).unwrap_or(0) as u16;+    let pid = dev.get("pid").and_then(|v| v.as_u64()).unwrap_or(0) as u16;+    let bus = dev.get("bus_id").and_then(|v| v.as_str()).unwrap_or("?");+    let installed = crate::plugins::discover_installed();+    let fw = match crate::plugins::firmware_for(class, vid, pid, &installed) {+        Some(p) => p,+        None => return (409, json!({"error": "no firmware device-test pack installed for this chip", "blocked": true,+            "hint": "search the wiki: adom-usb plugins search"})),+    };+    // Validate the persona exists in the pack's catalog.+    let known = fw.personas.as_array().map(|a| a.iter()+        .any(|p| p.get("id").and_then(|x| x.as_str()) == Some(persona.as_str()))).unwrap_or(false);+    if !known {+        return (400, json!({"error": format!("unknown persona '{}' for {}", persona, fw.slug),+            "available": fw.personas.clone()}));+    }+    let cmd = format!("[{src}] {ep} flash --persona {persona} --vid {vid:04x} --pid {pid:04x} --busid {bus} --target {src}",+        src = dev.get("source_id").and_then(|v| v.as_str()).unwrap_or("?"),+        ep = fw.entrypoint, persona = persona, vid = vid, pid = pid, bus = bus);+    log_action(st, json!({+        "ts": now_ms() as u64, "op": "flash", "device_id": device_id,+        "device": dev.get("name"), "persona": persona, "plugin": fw.slug.clone(),+        "command": cmd, "status": "queued"+    }));+    (200, json!({"ok": true, "op": "flash", "device_id": device_id, "persona": persona,+        "plugin": fw.slug.clone(), "method": fw.flash_method.clone(), "command": cmd, "status": "queued",+        "note": "after flashing, the device re-enumerates as the persona's USB class — refresh to see it"}))+}+ fn handle_device_op(st: &AppState, req: &mut tiny_http::Request, op: &str) -> (u16, Value) {     let body = match read_body(req) {         Ok(b) => b,

@@ -35,6 +35,7 @@ pub struct Plugin {     pub name: String,     pub version: String,     pub api_version: String,+    /// "sniffer" | "decoder" | "firmware"     pub kind: String,     pub entrypoint: String,     /// {"class": ["CDC serial","*"], "vid": ["*"], "pid": ["*"]}@@ -42,6 +43,15 @@ pub struct Plugin {     pub capture: String,     pub decoders: Vec<String>,     pub description: String,+    /// firmware plugins only: who publishes it (e.g. "Raspberry Pi", "STMicro", "TI").+    pub vendor: String,+    /// firmware plugins only: chip families this device-test pack targets.+    pub chips: Vec<String>,+    /// firmware plugins only: how it flashes (uf2-bootsel | dfu-util | esptool | nrfutil | openocd | …).+    pub flash_method: String,+    /// firmware plugins only: the catalog of stub USB personas it can flash.+    /// Each: {id, name, usb_class, result_vid?, result_pid?}.+    pub personas: Value,     /// "installed" | "registry"     pub source: String,     pub installed: bool,@@ -67,6 +77,12 @@ fn from_manifest(v: &Value, source: &str, installed: bool) -> Option<Plugin> {             .map(|a| a.iter().filter_map(|d| d.as_str().map(String::from)).collect())             .unwrap_or_default(),         description: v.get("description").and_then(|x| x.as_str()).unwrap_or("").to_string(),+        vendor: v.get("vendor").and_then(|x| x.as_str()).unwrap_or("").to_string(),+        chips: v.get("chips").and_then(|x| x.as_array())+            .map(|a| a.iter().filter_map(|d| d.as_str().map(String::from)).collect())+            .unwrap_or_default(),+        flash_method: v.get("flash_method").and_then(|x| x.as_str()).unwrap_or("").to_string(),+        personas: v.get("personas").cloned().unwrap_or(json!([])),         source: source.to_string(),         installed,     })@@ -140,6 +156,10 @@ pub fn discover_registry(installed: &[Plugin]) -> Vec<Plugin> {             capture: "".to_string(),             decoders: vec![],             description: item.get("brief").or_else(|| item.get("description")).and_then(|s| s.as_str()).unwrap_or("").to_string(),+            vendor: "".to_string(),+            chips: vec![],+            flash_method: "".to_string(),+            personas: json!([]),             source: "registry".to_string(),             installed: false,         })@@ -150,13 +170,13 @@ fn glob_match(pat: &str, val: &str) -> bool {     pat == "*" || pat.eq_ignore_ascii_case(val) || val.to_lowercase().contains(&pat.to_lowercase()) } -/// Pick the best installed plugin for a device by class/vid/pid. A more-/// specific match (exact class, non-"*" vid) wins over a wildcard.-pub fn match_for<'a>(class: &str, vid: u16, pid: u16, plugins: &'a [Plugin]) -> Option<&'a Plugin> {+/// Pick the best installed plugin of a given kind for a device by class/vid/pid.+/// A more specific match (exact class, non-"*" vid) wins over a wildcard.+pub fn match_kind<'a>(kind: &str, class: &str, vid: u16, pid: u16, plugins: &'a [Plugin]) -> Option<&'a Plugin> {     let vid_s = format!("{:04x}", vid);     let pid_s = format!("{:04x}", pid);     let mut best: Option<(&Plugin, i32)> = None;-    for p in plugins.iter().filter(|p| p.kind == "sniffer") {+    for p in plugins.iter().filter(|p| p.kind == kind) {         let m = &p.matches;         let list = |k: &str| m.get(k).and_then(|x| x.as_array()).map(|a|             a.iter().filter_map(|v| v.as_str().map(String::from)).collect::<Vec<_>>())@@ -177,6 +197,17 @@ pub fn match_for<'a>(class: &str, vid: u16, pid: u16, plugins: &'a [Plugin]) ->     best.map(|(p, _)| p) } +/// Best matching sniffer plugin for a device.+pub fn match_for<'a>(class: &str, vid: u16, pid: u16, plugins: &'a [Plugin]) -> Option<&'a Plugin> {+    match_kind("sniffer", class, vid, pid, plugins)+}++/// Best matching firmware device-test pack for a device (matched by vid/pid —+/// e.g. RP2040 BOOTSEL 2e8a:*, STM32 DFU 0483:df11, Sitara ROM 0451:*).+pub fn firmware_for<'a>(class: &str, vid: u16, pid: u16, plugins: &'a [Plugin]) -> Option<&'a Plugin> {+    match_kind("firmware", class, vid, pid, plugins)+}+ pub fn to_json(plugins: &[Plugin]) -> Value {     serde_json::to_value(plugins).unwrap_or(json!([])) }