Homer Woodpecker V2

Homer Woodpecker v2 is inspired by Homer Simpson's famous drinking bird: a USB HID device that emulates a mouse and helps keep a computer awake during long-running tasks such as CNC jobs, data acquisition, or automated tests. It is not intended to keep you online on Teams or to fake user presence.

The firmware is distributed only as a compiled binary. The configuration app and 3D models are included so that anyone can build their own device for personal, non-commercial use.

Responsible Use

Homer Woodpecker is intended for legitimate scenarios such as long machining jobs, automated tests, data acquisition, or other activities where you want to prevent the computer from sleeping while you are still using the system in an authorized way.

Although the device can technically generate mouse movement, it is not designed or distributed to bypass presence checks, evade company policies, or artificially keep the online or "green" status of applications such as Microsoft Teams when the user is not actually at the computer.

Using USB VID and PID values for which you do not have the required authorization can cause technical issues, policy violations, conflicts with other devices, and legal risks. Use only USB identifiers you are authorized to use, or keep the default values when appropriate.

The author accepts no responsibility for improper use of the device, violations of regulations, contracts, company policies, or applicable laws, nor for damage, lockouts, disputes, penalties, technical issues, or any other consequences resulting from use of this project.

1. Waveshare RP2040-Zero
2. A USB data cable, not a charge-only cable.
3. The 3D printed parts.
4. A macOS, Windows, or Linux computer for USB configuration.

1. Print `Stand_bottom.stl`, `Stand_top.stl`, and `Flat_Poly_Woodpecker.stl`.
2. Mount the RP2040-Zero in the stand.
3. Attach the printed woodpecker to the stand. If needed, use glue suitable for your printing material.

The `Flat_Poly_Woodpecker.stl` model is derived from "Woodpecker Low Poly" by Antoine5483 on Thingiverse: https://www.thingiverse.com/thing:3151202

1. Clone or copy repository files from https://github.com/ddinuzzo/homer-woodpecker-v2
2. Locate `firmware/homer_woodpecker_rp2040Zero_V1.0.0.uf2`.
3. Disconnect the RP2040-Zero from the computer.
4. Hold down the board's `BOOT`/`BOOTSEL` button.
5. While keeping the button pressed, connect the board to the computer via USB.
6. Release the button when a USB drive, usually named `RPI-RP2`, appears.
7. Copy the `.uf2` file to the `RPI-RP2` drive.
8. Wait for the board to reboot automatically.

After rebooting, the device exposes a USB CDC serial port at `115200` baud and a USB HID mouse interface. On startup, the firmware always enters the `STOPPED` state, so it does not start moving the pointer by itself.

MacOS Apple Silicon

Open the app from: app/MacOS-silicon/Homer Woodpecker Configurator.app

If macOS blocks the app because it is unsigned or not authorized, use `Ctrl` + click on the app, choose `Open`, then confirm.

Windows

The Windows release is available as a single executable file in: app/Windows/Homer Woodpecker Configurator.exe

No installation is required: download the repository, open the `app/Windows/` folder, and run `Homer Woodpecker Configurator.exe`.

If Windows Defender SmartScreen reports the executable as an unrecognized app, it is because the build is not signed with a commercial certificate. Run it only if you downloaded the file from this repository.

Running from Python Source

The app source code is available in `app/source/`.

On macOS and Linux:

On Windows PowerShell:

If PowerShell shows an error such as "running scripts is disabled on this system", you can enable scripts only for the current session and then activate the virtual environment:

Alternatively, you can avoid activating the virtual environment altogether by directly using the Python executable inside `.venv`:

To create a Windows executable, install the dependencies on the target platform and use PyInstaller through the dedicated `pyinstaller_entrypoint.py` entry point.

PyInstaller does not reliably cross-compile: you need Windows to build a Windows executable, macOS to build a macOS app, and so on.

1. Connect the RP2040-Zero to the computer with the firmware already installed.
2. Launch Homer Woodpecker Configurator.
3. Press `Refresh ports`.
4. Select the board's serial port:
5. macOS: usually `/dev/cu.usbmodem...`
6. Windows: usually `COM3`, `COM4`, `COM5`, or similar
7. Linux: usually `/dev/ttyACM0` or `/dev/ttyUSB0`
8. Leave the baud rate set to `115200`.
9. Press `Connect`.

When the connection opens, the app reads the device status, USB descriptors, and persistent configuration.

Starting and Stopping the Simulation

1. Press `START` to start mouse simulation.
2. Press `STOP` to stop it.

The default shortcuts are:

1. `Ctrl+Alt+S`: START
2. `Ctrl+Alt+X`: STOP

You can change them directly in the app. Shortcuts are active while the app is open.

USB Configuration

In the USB Configuration section, you can edit:

1. VID
2. PID
3. Manufacturer
4. Product
5. Serial

You should only change `VID` and `PID` if you have the required authorization to use those USB identifiers. Using identifiers assigned to other manufacturers or devices can create conflicts and legal risks.

After filling in the fields, press `Save USB configuration`. The app saves the new values to the device and shows `Reboot required`. Press `Reboot now` to apply the new USB descriptors.

Factory reset is available through `Reset configuration`; the board must also be rebooted afterward.

Advanced Panel

Press `Advanced` to open:

1. persistent configuration;
2. local presets;
3. console/log;
4. raw command sending.

The main serial commands are: