| 1 | # ESP32 BLE Mouse library |
| 2 | |
| 3 | This library allows you to make the ESP32 act as a Bluetooth Mouse and control what it does. E.g. move the mouse, scroll, make a click etc. |
| 4 | |
| 5 | You might also be interested in: |
| 6 | - [ESP32-BLE-Keyboard](https://github.com/T-vK/ESP32-BLE-Keyboard) |
| 7 | - [ESP32-BLE-Gamepad](https://github.com/lemmingDev/ESP32-BLE-Gamepad) |
| 8 | |
| 9 | ## Features |
| 10 | |
| 11 | - [x] Left click |
| 12 | - [x] Right click |
| 13 | - [x] Middle click |
| 14 | - [x] Back/Forwards click |
| 15 | - [x] Move mouse pointer left/right |
| 16 | - [x] Move mouse pointer up/down |
| 17 | - [x] Scroll up/down |
| 18 | - [x] Scroll left/right |
| 19 | - [x] Report optional battery level to host (basically works, but it doesn't show up in Android's status bar) |
| 20 | - [x] Customize Bluetooth device name/manufacturer |
| 21 | - [x] Compatible with Android |
| 22 | - [x] Compatible with Windows |
| 23 | - [x] Compatible with Linux |
| 24 | - [x] Compatible with MacOS X (not stable, some people have issues, doesn't work with old devices) |
| 25 | - [x] Compatible with iOS (not stable, some people have issues, doesn't work with old devices) |
| 26 | |
| 27 | ## Installation |
| 28 | - (Make sure you can use the ESP32 with the Arduino IDE. [Instructions can be found here.](https://github.com/espressif/arduino-esp32#installation-instructions)) |
| 29 | - [Download the latest release of this library from the release page.](https://github.com/T-vK/ESP32-BLE-Mouse/releases) |
| 30 | - In the Arduino IDE go to "Sketch" -> "Include Library" -> "Add .ZIP Library..." and select the file you just downloaded. |
| 31 | - You can now go to "File" -> "Examples" -> "ESP32 BLE Mouse" and select any of the examples to get started. |
| 32 | |
| 33 | ## Example |
| 34 | |
| 35 | ``` C++ |
| 36 | /** |
| 37 | * This example turns the ESP32 into a Bluetooth LE mouse that scrolls down every 2 seconds. |
| 38 | */ |
| 39 | #include <BleMouse.h> |
| 40 | |
| 41 | BleMouse bleMouse; |
| 42 | |
| 43 | void setup() { |
| 44 | Serial.begin(115200); |
| 45 | Serial.println("Starting BLE work!"); |
| 46 | bleMouse.begin(); |
| 47 | } |
| 48 | |
| 49 | void loop() { |
| 50 | if(bleMouse.isConnected()) { |
| 51 | Serial.println("Scroll Down"); |
| 52 | bleMouse.move(0,0,-1); |
| 53 | } |
| 54 | delay(2000); |
| 55 | } |
| 56 | ``` |
| 57 | |
| 58 | ## API docs |
| 59 | The BleMouse interface is almost identical to the Mouse Interface, so you can use documentation right here: |
| 60 | https://www.arduino.cc/reference/en/language/functions/usb/mouse/ |
| 61 | |
| 62 | Just remember that you have to use `bleMouse` instead of just `Mouse` and you need these two lines at the top of your script: |
| 63 | ``` |
| 64 | #include <BleMouse.h> |
| 65 | BleMouse bleMouse; |
| 66 | ``` |
| 67 | |
| 68 | This library supports a few additional features that the Mouse library does not support at the time of writing: |
| 69 | |
| 70 | - Scrolling left/right E.g.: `bleMouse.move(0,0,0,1)` (Scroll left) and `bleMouse.move(0,0,0,-1)` (Scroll right) |
| 71 | - Using the back and forward buttons E.g.: `bleMouse.click(MOUSE_BACK)` and `bleMouse.click(MOUSE_FORWARD)` |
| 72 | |
| 73 | There is also Bluetooth specific information that you can use (optional): |
| 74 | |
| 75 | Instead of `BleMouse bleMouse;` you can do `BleMouse bleMouse("Bluetooth Device Name", "Bluetooth Device Manufacturer", 100);`. |
| 76 | The third parameter is the initial battery level of your device. To adjust the battery level later on you can simply call e.g. `bleMouse.setBatteryLevel(50)` (set battery level to 50%). |
| 77 | By default the battery level will be set to 100%, the device name will be `ESP32 Bluetooth Mouse` and the manufacturer will be `Espressif`. |
| 78 | |
| 79 | |
| 80 | ## Credits |
| 81 | |
| 82 | Credits to [chegewara](https://github.com/chegewara) as this library is based on [this piece of code](https://github.com/nkolban/esp32-snippets/issues/230#issuecomment-473135679) that he provided. |