BLEDuck

KO | EN

gitlite — search

#javascript #python #hacktoberfest #react #ai #typescript #android #deep-learning #nodejs #cli #awesome-list #vue #ios #openai

(★ 30)

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

BLEDuck 최신버젼 다운로드

최종 버전 다운로드 (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# 🦆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](https://circuitpython.org/downloads).
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](https://adafruit.github.io/Adafruit_WebSerial_ESPTool/).
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](https://github.com/user-attachments/assets/3dd86d85-df80-4d58-aba5-e078dc30212c)
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](https://circuitpython.org/downloads).
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](https://circuitpython.org/libraries).
   - 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 using Serial Bluetooth Terminal
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](https://play.google.com/store/apps/details?id=de.kai_morich.serial_bluetooth_terminal).
5. Open `Serial Bluetooth Terminal` app.
8. Click on `☰`.
9. Click on `Devices`.
10. Click on `Bluetooth LE`.
11. Click on `Scan`.
    - It ask for permission, then click on `Allow`.
    - There is a device named `BLEDuck` show in it.
12. Click on it.
13. After that, when it show `Connected` it means ready to execute payloads using BLE.
14. Just type the number and click on Send button.
    - The payload of that number executes immediately.

# 🏃🏻‍♂Run BLEDuck using BLEDuck App
1. Download BLEDuck App from [here](https://github.com/wirebits/BLEDuck/releases/download/v1.0/BLEDuck.apk).
2. Simply install it.
3. Turn on your mobile bluetooth.
4. Open the app.
5. Click on `Grant Permissions`.
6. Choose `Allow` to find, connect and determine nearby devices.
7. Click on `Scan BLE Devices` button.
   - Wait for sometimes and show `BLEDuck`.
8. Click on `Connect Device`.
9. Click on `Enter Payload Number`.
10. Enter your payload number.
11. Click on `Run` 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
```

BLEDuck

BLEDuck 최신버젼 다운로드

오늘의 추천 프로젝트

Was this content helpful?

Recent Feedback

BLEDuck

BLEDuck 최신버젼 다운로드

오늘의 추천 프로젝트

Was this content helpful?

Recent Feedback

Download README