BLEDuck icon indicating copy to clipboard operation
BLEDuck copied to clipboard

Published 2 months ago • verified publisher icon wirebits
→

Metadata

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

BLEDuck

🦆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 image
  1. Click on Erase button.
  2. Wait for sometimes to successfully erased.
  3. Click on first one Choose a file....
  4. Select the tinyuf2-<NAME-OF-BOARD>-0.35.0-combined.bin file.
  5. Click on Program button.
  6. Wait for sometimes and after successfully flashed, press and release the RST or RESET button.
  7. 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.
  1. 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

← Metadata

18
Stars
7
Forks
18
Watchers

Owner

verified publisher icon wirebits

Metadata

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

Back