🦆BLEDuck

A BLE-controlled USB Rubber Ducky clone built with ESP32-S3 boards.

✨Features

• Minimal Setup.
• Simply controlled by Serial Bluetooth Terminal App.
• Execute payloads by just sending numbers.
• Store payloads in folder for better management.
• Hide / Unhide mass storage device to work in stealth.
• Manual control for advertisment of device.

📋List of ESP32S3 boards

• These boards supports native BLE and HID.
• It also supports combined.bin file to make board into CircuitPython board.

1. YD-ESP32-S3 N16R8 By VCC-GND Studio
2. MatrixPortal S3 By Adafruit
3. ESP32-S3-DevKitC-1-N8 By Espressif
4. Waveshare ESP32-S3-Zero By Waveshare
5. ESP32-S3 Reverse TFT Feather By Adafruit
6. Feather ESP32-S3 4MB Flash 2MB PSRAM By Adafruit
7. Seeed Studio XIAO ESP32S3 Sense By Seeed Studio
8. Adafruit QT Py ESP32-S3 4MB Flash/2MB PSRAM By Adafruit
9. M5Stack CardPuter - M5StampS3 powered mini computer By M5Stack
10. T-Dongle S3 By LILYGO
11. ESP32-S3-DevKitC-1-N16 By Espressif
12. Adafruit QT Py ESP32-S3 8MB Flash No PSRAM By Adafruit
13. Qualia ESP32-S3 for TTL RGB-666 Displays By Adafruit
14. Feather ESP32-S3 TFT PSRAM By Adafruit
15. Feather ESP32-S3 8MB Flash No PSRAM By Adafruit
16. T-Display S3 By LILYGO
17. ESP32S3-TOUCH-LCD-2 By Waveshare
18. ESP32-S3-DevKitC-1-N8R8 By Espressif
19. ESP32-S3-DevKitC-1-N8R2 By Espressif
20. ESP32-S3-Matrix Development Board By Waveshare
21. MEMENTO - Python Programmable DIY Camera By Adafruit
22. T-Deck (Plus) By LILYGO
23. ESP32-S3-GEEK By Waveshare
24. T-Embed By LILYGO
25. Unexpected Maker FeatherS3 By Unexpected Maker
26. AtomS3 Dev Kit w/ 0.85-inch Screen By M5Stack
27. T-Watch S3 By LILYGO
28. Nano ESP32 By Arduino
29. Metro ESP32-S3 By Adafruit
30. ESP32-S3-DevKitM-1-N8 By Espressif
31. Unexpected Maker TinyS3 By Unexpected Maker
32. Unexpected Maker ProS3 By Unexpected Maker
33. ESP32-S3-Tiny By Waveshare
34. ESP32-S3-Pico By Waveshare
35. ESP32-S3-EYE By Espressif
36. AtomS3 Lite ESP32S3 Dev Kit By M5Stack
37. ESP32-S3-USB-OTG-N8 By Espressif
38. ESP32-S3 ETH Development Board By Waveshare
39. Dial - Smart Rotary Knob with Touch Screen By M5Stack
40. ESP32-S3-DevKitC-1-N32R8 By Espressif
41. YD-ESP32-S3 N8R8 By VCC-GND Studio
42. BPI-PicoW-S3 By Banana Pi
43. Vision Master E290 By Heltec Automation
44. Bee Data Logger By Smart Bee Designs
45. M5Stamp S3 By M5Stack
46. LOLIN S3 Pro By Wemos
47. ESP32-S3 LCD Evaluation Kit By Espressif
48. ThingPulse Pendrive S3 By ThingPulse
49. LOLIN S3 By Wemos
50. ESP32-S3 LCD Evaluation Kit v1.5 By Espressif
51. LOLIN S3 MINI By Wemos
52. T-Display S3 Pro By LILYGO
53. Unexpected Maker TinyWATCH S3 By Unexpected Maker
54. LOLIN S3 MINI PRO By Wemos
55. Nano ESP32 with inverted Status LED By Arduino
56. CoreS3 ESP32 IoT By M5Stack
57. Unexpected Maker RGBTouch Mini By Unexpected Maker
58. BrainBoardz Neuron By BrainBoardz Inc.
59. MaTouch ESP32-S3 Parallel TFT with Touch 7“ By Makerfabs
60. Unexpected Maker OMGS3 By Unexpected Maker
61. Unexpected Maker Blizzard S3 By Unexpected Maker
62. Maker Feather AIoT S3 By Cytron Technologies
63. TQ-T Pro (with PSRAM) By LILYGO
64. FireBeetle 2 ESP32-S3 By DFRobot
65. ESP32-S3 Box Lite By Espressif
66. MagiClick S3 By MakerM0
67. Deneyap Kart 1A v2 By Turkish Technology Team Foundation
68. ESP32-S3 1.47inch Display Development Board By Waveshare
69. Unexpected Maker FeatherS3 Neo By Unexpected Maker
70. WiFi LoRa 32 V3 By Heltec Automation
71. Unexpected Maker NanoS3 By Unexpected Maker
72. ESP32-S3 Box By Espressif
73. AtomS3U ESP32S3 Dev Kit By M5Stack
74. TQ-T Pro (No PSRAM) By LILYGO
75. Bee Motion S3 By Smart Bee Designs
76. BPI-Leaf-S3 By Banana Pi
77. Sunton ESP32-8048S070 By Sunton
78. CircuitArt ESP32S3 Zero By CircuitArt
79. Barduino By Fablab Barcelona
80. ESP32-S3 HackTablet By Kevin Matocha
81. Unexpected Maker Bling By Unexpected Maker
82. Bee S3 By Smart Bee Designs
83. ESP32S3-LCD-1.28 By Waveshare
84. Sunton ESP32-8048S050 By Sunton
85. Elecrow CrowPanel 4.2 By Elecrow
86. Heltec Wireless Paper By Heltec Automation
87. M5Stack CardPuter - M5StampS3 powered mini computer (MicroROS) By M5Stack
88. ESP32-S3-DevKitC-1-N8R2 (MicroROS) By Espressif
89. Unexpected Maker EdgeS3[D] By Unexpected Maker
90. AI-On-The-Edge-Cam By Prokyber
91. M5Stack Din Meter w/ M5StampS3 By M5Stack
92. ESP32S3-TOUCH-LCD-2.8 By Waveshare
93. ESP32-S3-Touch-LCD-1.47 By Waveshare
94. Seeed Studio XIAO ESP32S3 By Seeed Studio

👍Recommended

• Use those ESP32-S3 boards which has at least 8MB flash memory.

📦Requirements

• 1 ESP32-S3 Board
• 1 Micro-B USB / Type-C USB Cable with data transfer support

⚙️Setup ESP32-S3 boards for CircuitPython

1. Open Official CircuitPython download link from here.
2. Search ESP32-S3 according to the board you have.
3. Select your board and click on it.
4. At the end of the page, there is button named DOWNLOAD BOOTLOADER combined.bin.
5. Click on it to download.
   • There is a file named tinyuf2-<NAME-OF-BOARD>-0.35.0-combined.bin.
6. Open Adafruit ESP Web Flasher from here.
7. Connect ESP32-S3 with a USB cable and then to the PC/Laptop.
8. Press and hold the BOOT button.
9. Press and release the RST button.
10. Release the BOOT button.
11. Set the Baud Rate to 460800 Baud.
12. Click on Connect button.
13. Select your Device COM Port in the Pop-Up Window.
14. Click on Connect button in the Pop-Up Window.

• When connected successfully, then it show this

15. Click on Erase button.
16. Wait for sometimes to successfully erased.
17. Click on first one Choose a file....
18. Select the tinyuf2-<NAME-OF-BOARD>-0.35.0-combined.bin file.
19. Click on Program button.
20. Wait for sometimes and after successfully flashed, press and release the RST or RESET button.
21. Plug-out and then plug-in the USB cable in PC/Laptop.

• When it connects, then ESP32-S3 board as a removable storage device S3DKC1BOOT.

22. Done! Now, ESP32-S3 Board is ready to flash CircuitPython .uf2 file.

⚙️Setup CircuitPython

1. Open Official CircuitPython download link from here.
2. Search ESP32-S3 according to the board you have.
3. Select your board and click on it.
4. Download latest stable release CircuitPython .uf2 file and noted its version.
   • It is like X.Y.Z.
   • Latest stable release is 9.2.8 but it can be changed in future so keep eye on it.
5. Copy the .uf2 file into the S3DKC1BOOT.
   • When it is copied, then it disconnects automatically and reconnect as CIRCUITPY.
   • Means CircuitPython is successfully flashed in the ESP32-S3 board.
6. Done! Now, ESP32-S3 Board is flashed with CircuitPython .uf2 file.

⚙️Setup Essential Files for BLEDuck

1. Download or Clone the Repository.
2. Open the folder.
   • Make sure that your ESP32-S3 board is connected to your PC/Laptop.
3. Copy code.py in the CIRCUITPY.
   • It ask for replacement of code.py file, then replace it.
   • It will overwrite in the code.py file.
4. Copy boot.py in the CIRCUITPY.
5. Download latest Adafruit CircuitPython Bundle from here.
   • There are 2 variants of libraries : Bundles and The Community Bundle.
   • In Bundles variant, download latest stable Adafruit CircuitPython Bundle as noted version of .uf2 file.
   • Latest stable release is adafruit-circuitpython-bundle-9.x-mpy-20250829.zip but it can be changed in future so keep eye on it.
6. Extarct the ZIP file.
7. Go to the lib folder in the extracted ZIP file.
8. Copy adafruit_ble and adafruit_hid folders in the lib folder of CIRCUITPY.
   • After 2-3 minutes, an BLE device named BLEDuck is discovered.
9. Create a folder named payloads in CIRCUITPY.
10. Done! Now, ESP32-S3 board is ready to use as a BLEDuck.

🔧Tweaks in boot.py

• boot.py helps to hide / unhide mass storage device to work in stealth.
• In boot.py, replace X with any pin number available on the board in LOC 7.
• By default, the mass storage is hidden when boot.py is in CIRCUITPY.
• To show mass storage, put jumper wire between that pin number mentioned in boot.py and GND and press and release the RST or RESET button.
• To hide mass storage, just remove jumper wire between them and press and release the RST or RESET button.

📄Payload Files

1. Open Notepad or any other text editor.
2. Write your payload in it.
3. When saving the file, select CIRCUITPY.
4. Then go to the payloads folder.
5. Name the payload as payload-1, payload-2 etc.
   • It is saved by default as .txt files.

🧩CIRCUITPY Directory Structure

• CIRCUITPY/
  • lib/
    • adafruit_ble
    • adafruit_hid
  • code.py
  • boot.py
  • payloads/
    • payload-X.txt
  • where X is a number like 1,2,3,4 etc.

🏃🏻‍♂Run BLEDuck

1. Turn on your mobile bluetooth.
2. Scan the bluetooth and it show BLEDuck.
3. Connect and pair with it.
4. Download Serial Bluetooth Terminal app from here.
5. Open Serial Bluetooth Terminal app.
6. Click on ☰.
7. Click on Devices.
8. Click on Bluetooth LE.
9. Click on Scan.
   • It ask for permission, then click on Allow.
   • There is a device named BLEDuck show in it.
10. Click on it.
11. After that, when it show Connected it means ready to execute payloads using BLE.
12. Just type the number and click on Send button.
    • The payload of that number executes immediately.

💡Mnemonic Table

Mnemonics	Description	Example
WAIT	It add time in the code. Time is in milliseconds. 1000 ms = 1 second.	WAIT 1000
TYPE	It add text want to type in the code.	TYPE Hello World!
LOOP	It runs commands for a certain number of times. Synatx is LOOP number-of-times commands	LOOP 3 TYPE Hello World! EXIT LOOP 4 TAB EXIT LOOP 1 CTRL S EXIT LOOP 1 CTRL SHIFT N EXIT
INF	It run commans infinitely. Syntax is INF commands	INF TYPE Hello World! EXIT INF TAB EXIT

🔡Special Symbols

1. -

• It is used to put the cursor in the next line.
• It is only used with TYPE.
• Example : TYPE Hello World!-
• If TYPE contain any command and then - then it run automatically without ENTER key.

📝Supported Mnemonics

Alphabet Keys

A B C D E F G H I J K L M N O P Q R S T U V W X Y Z

Function Keys

F1 F2 F3 F4 F5 F6 F7 F8 F9 F10 F11 F12

Navigation Keys

LEFT UP RIGHT DOWN TAB HOME END PGUP PGDN

Lock Keys

CAPS NUM SCROLL

System and GUI Keys

GUI ESC PRTSCR PAUSE

Editing Keys

INSERT DEL BKSP ENTER

Modifier Keys

CTRL SHIFT ALT

ASCII Characters

` ! @ # $ % ^ & * ( ) - = [ ] \ ; ' , . / SPACE ~ _ + { } | : " < > ? 0 1 2 3 4 5 6 7 8 9

📖Examples

Open notepad and type Hello World!

WAIT 1000
GUI R
WAIT 1000
TYPE notepad
WAIT 1000
ENTER
WAIT 1000
TYPE Hello World!

Open CMD as Administrator Mode

WAIT 1000
GUI R
WAIT 1000
TYPE cmd
WAIT 1000
CTRL SHIFT ENTER
WAIT 1300
ALT Y

Create A New Folder

WAIT 1000
CTRL SHIFT N
WAIT 1200
TYPE hello
WAIT 1100
ENTER

Open notepad and type Hello World! 6 times in different lines

WAIT 1000
GUI R
WAIT 1000
TYPE notepad
WAIT 1000
ENTER
WAIT 1000
LOOP 6
TYPE Hello World!-
EXIT