Implement TinyUSB host-mode BadUSB detection and add project documentation

[NotoriousArnav]

Summary

• Implement TinyUSB host-mode USB enumeration with real-time HID keystroke rate monitoring and three-level threat classification (SAFE/CAUTION/MALICIOUS) for BadUSB/Rubber Ducky detection
• Add comprehensive documentation suite: architecture, full API reference, hardware wiring diagrams, threat detection pipeline, build instructions, and troubleshooting guide

Summary by CodeRabbit

Release Notes

• New Features

  • Dual-mode OLED display now toggles between VID/PID and Manufacturer information modes via BOOTSEL button
  • Improved HID device classification distinguishing keyboards from mice for more accurate threat assessment
  • Enhanced keystroke rate monitoring using a 1-second sliding window for better anomaly detection

• Documentation

  • Added comprehensive API reference, architecture guide, hardware setup, threat detection model, and troubleshooting documentation

[coderabbitai]

Caution

Review failed

The pull request is closed.

📝 Walkthrough

Walkthrough

This PR refactors PlugSafe from GPIO-based USB device detection to a complete TinyUSB host stack integration. It introduces dynamic device enumeration with HID protocol classification, windowed keystroke-rate threat monitoring, OLED display mode toggling via BOOTSEL button, comprehensive project documentation, and optimized build configuration with UART stdio.

Changes

Cohort / File(s)	Summary
Documentation Restructuring BUILDING.md, README.md, docs/API_REFERENCE.md, docs/ARCHITECTURE.md, docs/BUILDING.md, docs/HARDWARE.md, docs/THREAT_DETECTION.md, docs/TROUBLESHOOTING.md	Removed legacy BUILDING.md; added comprehensive docs covering project architecture, API reference, hardware setup, threat detection model, building instructions, and troubleshooting guidance. Rewrote README with PlugSafe product description and quick-start information.
Build System Configuration CMakeLists.txt, tusb_config.h	Introduced PICO_TINYUSB_PATH variable; removed custom TinyUSB INTERFACE library. Updated usb_host and main target include paths and linked libraries. Enabled TinyUSB host stack with HID, hub, and HID endpoint buffer configuration; disabled CDC/MSC/VENDOR classes. Changed stdio from USB to UART; bumped CMake minimum to 3.13.
USB Host Core Implementation src/usb_host.c, include/usb_host.h	Replaced GPIO-based static device tracking with full TinyUSB integration via mount/unmount/HID callbacks. Added dynamic device table, DMA-aligned descriptor buffers, UTF-16LE-to-UTF-8 string parsing, and HID protocol detection (keyboard vs. mouse). Introduced instance, hid_protocol, descriptor_ready, and strings_ready fields to usb_device_info_t. Removed usb_register_gpio_device and usb_unregister_gpio_device APIs.
Threat Analysis System src/threat_analyzer.c, include/threat_analyzer.h	Integrated HID monitoring with protocol-based classification (mouse = SAFE, keyboard/unknown = potentially unsafe). Replaced all-time keystroke rate with 1-second windowed rate via hid_monitor. Added threat_update_device_info() API for refreshing device info and conditional threat escalation. Stricter device creation; no auto-creation on lookup.
Main Application UI main.c	Added display_mode_t enum for VID/PID vs. Manufacturer info modes; BOOTSEL button handling for mode toggling. Removed legacy usb_detector integration; replaced with device-count edge detection. Updated display rendering to branch on display mode; refined device-state-driven LED and UI behavior. Enhanced boot sequence and startup messaging.

Sequence Diagram(s)

sequenceDiagram
    participant USB Device
    participant TinyUSB Host Stack
    participant USB Host Manager
    participant HID Monitor
    participant Threat Analyzer
    participant Display

    USB Device->>TinyUSB Host Stack: Device plugged in
    TinyUSB Host Stack->>USB Host Manager: tuh_mount_cb(daddr)
    USB Host Manager->>USB Host Manager: Fetch device descriptor
    USB Host Manager->>Threat Analyzer: threat_add_device(dev_info)
    Threat Analyzer->>Threat Analyzer: Classify initial threat level
    Threat Analyzer->>Display: Update threat status

    alt HID Device Detected
        TinyUSB Host Stack->>USB Host Manager: tuh_hid_mount_cb(daddr, protocol)
        USB Host Manager->>HID Monitor: Register for keystroke monitoring
        USB Host Manager->>Threat Analyzer: threat_update_device_info(dev_info)
        
        rect rgba(0, 100, 200, 0.5)
            loop HID Activity
                USB Device->>TinyUSB Host Stack: Send HID report (keystroke)
                TinyUSB Host Stack->>USB Host Manager: tuh_hid_report_received_cb()
                USB Host Manager->>HID Monitor: Update keystroke rate (1-sec window)
                HID Monitor->>Threat Analyzer: threat_update_hid_activity()
                Threat Analyzer->>Threat Analyzer: Check windowed rate vs. threshold
                alt Rate Exceeds Threshold
                    Threat Analyzer->>Threat Analyzer: Escalate to MALICIOUS
                    Threat Analyzer->>Display: Update threat indicator
                end
            end
        end
    end

    USB Device->>TinyUSB Host Stack: Device unplugged
    TinyUSB Host Stack->>USB Host Manager: tuh_umount_cb(daddr)
    USB Host Manager->>Threat Analyzer: threat_remove_device()
    USB Host Manager->>HID Monitor: Unregister device
    USB Host Manager->>Display: Update device list

Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~60 minutes

Poem

🐰 A USB adventure unfolds so grand,
With TinyUSB hosting across the land,
Keystroke windows catch the sly attack,
Two display modes—flip with a tap-tap-tap,
PlugSafe now sees what hides from sight! 🛡️✨

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch arnav/tusb_host

Tip

Issue Planner is now in beta. Read the docs and try it out! Share your feedback on Discord.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}