USBvalve for live USB filesystem and HID activity checks

What USBvalve observes between a drive and a USB host

USBvalve addresses a specific uncertainty: a USB drive is about to be inserted into an unknown computer, charger, kiosk, or other powered device, and there is no convenient way to see what that device attempts to do with it. The project positions an RP2040-based board between the storage device and the host computer. Its display reports whether a decoy filesystem implemented by the firmware is read, written, or accessed. That feedback is intended for questions such as whether files are being copied, whether an encryption-like sequence of writes is occurring, or whether the connected host is touching the filesystem at all.

This is an observation and detection design, not conventional drive encryption or a claim that every malicious action can be classified. The README specifically presents read, write, and general access indications on the screen. It also documents a BADUSB debugger available through the serial port and says that USB host support can identify HID devices.

The intended users include technically capable hobbyists, security trainers, and investigators who need a small display close to the connection point. USBvalve is less attractive to ordinary desktop users. It requires hardware assembly or flashing, an OLED connection, and enough knowledge to interpret what appears on the display or serial monitor. It also makes no claim in the documentation to provide protection from every USB attack. Its value is narrower: exposing selected activity as it happens.

RP2040 firmware architecture and the two monitoring paths

Based on the repository layout, USBvalve separates prebuilt firmware, source, board resources, documentation, utilities, and printable mechanical parts. The main source lives in `src`, display resources are under `data`, and ready-to-flash Raspberry Pi Pico builds are under `firmware`. The current project targets the Raspberry Pi Pico SDK rather than the Arduino IDE environment used by earlier releases. The README describes version 1.0.0 as a complete rewrite with fewer external library dependencies, although the hardware and broad functions remain similar.

The filesystem-monitoring path is implemented through a fake or decoy filesystem on the device. USBvalve exposes that filesystem to the computer and renders the resulting read, write, or access events on an SSD1306 display. This makes the activity visible without asking the operator to infer it from the target host.

The second path is USB host mode. Starting with firmware version 0.8.0, the project documents support for HID device detection, including devices described as BADUSB. A powered USB-A or Micro-B host port must be added to the hardware, with board version 1.2 available in A and Micro-B variants. The hardware is designed to watch a USB device while the Pico continues to face the computer through its own USB connection.

Version 1.0.0 removed polling of BOOTSEL because the README says it interfered with BADUSB detection. Reset and HID-event functions moved to a button wired between `GP0` and `GND`, or to the `r` and `h` serial-monitor commands. A separate BOOTSEL-enabled firmware remains available for users who value the old button behavior and accept reduced detection coverage.

Choosing a Pico, OLED, and USBvalve board revision

The documented bill of materials starts with a Raspberry Pi Pico 1 or 2, or another RP2040-based board. Output requires an I2C SSD1306 OLED measuring 128x64 or 128x32. The project also supports a Pi Pico Watch based on an RP2040 board with a 1.28-inch TFT display, including the Waveshare RP2040-LCD-1.28.

The custom PCB is optional. A breadboard can be used instead, while the `STL` directory contains enclosure models for several board and screen arrangements. The PCB directory includes Gerber files and a version 1.3 layout with mounting holes around pads 1 and 3 for the reset button. The custom board and printed enclosure are therefore production aids, not prerequisites for the firmware.

Choosing the wrong display or firmware combination is the first practical failure point. The repository provides builds for 32-line and 64-line OLEDs, Pico 1 and Pico 2, and the Pi Pico Watch. A firmware image selected only by RP2040 chip type may still assume the wrong display geometry.

The documented screen arrangement uses electrical tape or an optional 3D-printed spacer to isolate the OLED from the board. This is a physical clearance measure, not a software configuration. For a breadboard build, pin mapping and I2C wiring must match the source and the selected display. The README excerpt gives the start of the board-specific connections but does not provide a complete wiring table, so the linked build documentation and board files must be consulted before assembly.

First use with prebuilt Raspberry Pi Pico firmware

The repository's shortest documented route is to select a matching prebuilt firmware file from `firmware` and flash it onto a supported Raspberry Pi Pico. The README says these images can be used directly and identifies variants for different OLED sizes, Pico generations, and the Pi Pico Watch. It does not give a complete flashing command, board-selection procedure, or BOOTSEL button sequence in the available instructions, so no command can be reproduced responsibly here.

For the storage-monitoring path, assemble the supported OLED and optional PCB or breadboard, flash the image selected for that hardware, connect a USB storage device to the storage-facing connection, and connect USBvalve to the computer being inspected. The display is the expected output for filesystem activity. According to the project documentation, it should indicate access, reads, or writes to the fake filesystem.

For HID inspection, use hardware with the additional USB host port and flash the appropriate non-BOOTSEL firmware. The suspicious HID device belongs in the host-facing USB port, while USBvalve remains connected to the inspected computer. The serial monitor provides the documented `r` and `h` commands for reset and HID events.

This first-use sequence should be treated as a controlled hardware procedure. The README does not document rollback, automatic firmware restore, or a command that configures OLED type at runtime. Those choices are encoded in the firmware build.

Pi Pico Watch support and local event feedback

Pi Pico Watch support was added in version 0.15.0 and requires enabling a build-time choice rather than changing it through the serial interface. To build that target, uncomment `#define PIWATCH` near the beginning of the code, then build through the project's Pi Pico SDK source setup. The resulting hardware uses an RP2040-based watch board rather than the standard OLED arrangement.

This distinction matters when creating a reproducible build. The `#define PIWATCH` line changes the compile-time target, and the README also lists dedicated prebuilt firmware for the watch. Users who only intend to flash an image do not need to edit source, but users who modify display or board behavior need the correct target enabled before compilation.

The screen is intentionally local to the connection. That makes USBvalve useful when the inspected computer has no convenient logging window, although the project does not specify data export, filtering, or structured log format. The serial-port BADUSB debugger is a separate interface and should not be confused with the display's filesystem feedback.

The repository includes presentation material in `docs`, source in `src` and `data`, firmware images in `firmware`, PCB resources, utilities for creating a custom filesystem, and enclosure files in `STL`. This packaging supports both a ready-made device and a customized hardware build, but it also leaves important operational details to the individual files and linked documentation.

Limits of filesystem indicators and HID detection

The main limitation is the gap between visible events and a complete explanation of host behavior. The README says the screen shows access, reads, and writes to the fake filesystem. It does not state that USBvalve records filenames, reconstructs copied content, decrypts traffic, or identifies the process responsible on the inspected computer. Those outcomes should not be inferred from an activity display.

USB host support is also constrained by the hardware path. Version 1.2 adds a USB host port for HID detection, while older PCB version 1.1 instructions are for users who do not need BADUSB functions. The 1.0.0 rewrite changed BOOTSEL behavior to avoid interference with HID detection. The result is a documented trade-off: current standard firmware offers commands or an optional `GP0`-to-`GND` button, while the BOOTSEL-enabled image is described as having less detection coverage.

Device compatibility should be checked before use. The project specifically calls out low-speed devices such as ATTiny85 and EvilCrow, but the available documentation does not claim support for every USB class, speed, descriptor, or transfer pattern. The README also does not document automatic mitigation after detection. USBvalve should therefore be understood as a feedback device, not as a complete endpoint security system.

A conventional USB data blocker is the practical alternative for a different need. A blocker aims to prevent data transfer, while USBvalve accepts storage traffic, presents a fake filesystem, and reports selected operations on its display and through its documented HID interface. A full protocol analyzer would target bus-level capture rather than this fake-filesystem feedback, but no such analyzer is bundled or compared in the repository.

Maintenance, licensing, and upgrade state

USBvalve is not archived, and the last push was on 2026-08-19. The release history includes v1.0.1 on 2026-08-19, v1.0.0 on 2026-03-26, and v0.21.1 on 2025-05-31. This is a recent development record, but the documentation does not state a support policy for older hardware or a long-term compatibility promise.

The 1.0.0 migration is the main upgrade boundary to examine. It moves development from the Arduino IDE environment to the Pi Pico SDK, reduces external library dependencies, and changes BOOTSEL control. Users with custom source modifications or board wiring may therefore need to review more than the firmware image before moving from a 0.x release. The watch build also depends on the source-level `#define PIWATCH` setting.

The project is distributed under the MIT License. That is recorded in the repository's `LICENSE` file, but using the firmware, board files, utilities, and documentation still requires the reader to retain the applicable license notices and comply with the license text. The MIT identifier alone does not settle hardware compatibility, flashing procedures, or security claims.

Upgrade effort is therefore concentrated in hardware variants and firmware selection. The repository offers several board and display targets, but the README does not provide a universal in-app upgrade mechanism, changelog for every commit, or rollback command.

Editorial conclusion

USBvalve fits security-conscious users and training scenarios where a drive must be connected to unfamiliar hardware while its filesystem and HID behavior are watched directly. It is a poor choice for users who only want passive storage blocking, developers who need general-purpose USB bus analysis, or anyone who cannot interpret storage and HID events. Verify first that the selected firmware matches the board and OLED, that all required wiring is correct, and that the added USB host hardware is appropriate for the device under inspection. On supported hardware, version 1.0.0 or later combines an emulated filesystem display with serial control for reset and HID events.

Frequently asked questions

Official sources

1. cecio/USBvalve on GitHub
2. Issues
3. License: MIT
4. README
5. Releases