whiskers

whiskers is a bad USB tool based on the RP2350 with SD card support for custom scripts, with a dual use as a USB mass storage device.

With a 1Khz polling rate, keys can be sent at a lighting fast speed! Scriptable with lua for customizable payloads and runtime application code.

DISCLAIMER

This device, whether as a prototype or finished device, including also it's firmware is for RESEARCH and EDUCATIONAL PURPOSES ONLY. No colaborator, designer, or manufacturer involved with this project's production, design, or logistics has any intention, whether explicit or implicit, to use this device beyond research and testing. This project is not intended to be used for crime and is to be designed and used in good faith. Any person or entity using this project's code, design, or any physical device to do any level of crime is not affiliated with V.L. Labs, this site or sister sites, or anyone also contributing to this project. The colaborators, designers, and manufacturers of this device DO NOT CONSPIRE OR DESIRE TO COMMIT ANY LEVEL OF CRIME and abide by the Computer Fraud and Abuse Act (Title 18 U.S. Code 1030).

This device, including both hardware designs and code, are not designed with the intent to sell or to be profited off of. Any individual following the license described in LICENSE.md is permitted to use any resources in this repository (whiskers) on this site (git.vllabs.net).

ANY entity contributing to or using this project must agree to the above disclaimer and the license described in LICENSE.md

Rev 1.1 (typo fix) - 8/24/2026 written by designer & contributor Zane Maples

Media

Compilation

To compile the RP2350 code you will need an arm cross compiler (gcc-arm-none-eabi or the newlib version: libnewlib-arm-none-eabi or arm-none-eabi-newlib). Then run make rp2350 which will setup all rp2350 code and dependencies. The output .uf2 file will be in rp2350_build

Note: the instructions above and below are for Linux (and similary BSD and MacOS). There are compilers and setups for Windows. For more information see the RPI Foundation's official docs.

Since this project uses TinyUSB over the native USB controller, all serial output (ie. logging) will have to be done over UART. The board provides a 4 pin UART serial interface that you can solder headers too if needed. This will require a TTL/USB converter, these can be found cheaply online. Here's one I recommend.

Using Lua

This project contains Lua 5.5.0 to be used as a scripting language. Both runtime application code and manual key sending can be written. The Lua code can also manipulate text files and send keystrokes from a file.

Note that Lua being a higher-level scripting language it does consume a lot of memory. For example, for a program that just launches the USB (does not access any data buffers or files) the dynamically allocated amount of memory is around 20kb. It does have a built-in garbage collector and you can print out the current memory consumption with print(collectgarbage("count")) inside your Lua code (prints in kilo-bytes used).

Note that for the v1.0 system (using the RP2350 and pico-sdk) the baseline static memory being using is around 33-34kb (this is primarily from the large buffer used by TinyUSB for MSC, which is configurable). This leaves quite a bit of room for the Lua code (v1.0 board has 512kb of ram) so you most likely will not run into any major problems.

As it stands only one file of Lua can be ran at one time, and a default filename will be configurable so that the system auto detects and runs the proper script. Obviously, the board must have a valid storage medium (SD card in this instance) in order to pull and run that file. Eventually support will be added to store Lua script(s) inside the flash memory of the device, with an estimated space for that being around 1mb total (to leave room for the code binary + any future expansions). If the Lua file for whatever reason crashes, there will be no attempt to retry the file (typically, one line errors are still recoverable by Lua, this only applies in the case of a fatal error).

Code Documentation

All official/formal docs are generated in docs/ via doxygen. The current (code version 0.4.0) docs can be found here.

Hardware Viewing/Editing

All the hardware files (schematics, PCB, production files, BOM, etc.) are all made and viewed through KiCad 10.0. All assembly files and BOMs are generated to be produced through JLC PCB's assembly service. This because they have competitive prices and easy access to parts and being easy to generates BOMs for them. There are a few imported footprints in the whiskers.pretty file alongside a matching symbols library. The only exception to that is the RP2350-A/B & RP2354-A/B symbols and footprints. These are imported seperately from this repo.

There is also a JLC PCB fabrication plugin used to generate the BOM and the pick and place positions file. This is available in the official plugin repository in KiCad.

This device uses the RP2354B. I would've rather used the smaller chip but they were out of stock/low avalability when I was designing the board and I am too impatient to wait for more. Since there is no current onboard flash chip in the design (or planned to be in the design) any revisions should use this chip or (requiring a redesign) the RP2354A. 2Mb of flash should be plenty for this project.

Known Issues

Hardware Issues

• For version(s) 1.0 of the board the SD card slot card-detect is unreliable and typically does not work. This is fixed in software via the SD card library having a built in feature to test for connections. Note that this issue is not really that important (as there isn't really a use case to hotplug the SD card anyways.)
• For version(s) 1.0 of the board using the RP2350 the max USB speed is 12mb/s or USB 1.1. This is more a design flaw itself (the RP2350's USB controller only supports 1.1) and does not affect the base HID (keyboard) functionality of the device. It only affects the exposed storage device (either straight SD passthrough or the fake disk) limiting it to only 12mb/s (usually way lower) speeds. This can also be limited by raw SD card speeds as well. (Note: speedups can be made in terms of transfer speeds at the cost of memory and processing resources on the chip.)

Current TODO

• Find documentation/figure out a way for OS fingerprinting via USB [2]
• Eventually add more custom features for USB (raw reports) [1]
• Write down list of things to take "inspiration" from the HAK5 rubber ducky [3]

lua TODO

• (0.4.x) Create payloads [1]

Credits

• Hardware Design: Zane
• Software Design: Zane