Giter VIP home page Giter VIP logo

esp32-ble-mouse's Introduction

ESP32 BLE Mouse library

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.

You might also be interested in:

Features

  • Left click
  • Right click
  • Middle click
  • Back/Forwards click
  • Move mouse pointer left/right
  • Move mouse pointer up/down
  • Scroll up/down
  • Scroll left/right
  • Report optional battery level to host (basically works, but it doesn't show up in Android's status bar)
  • Customize Bluetooth device name/manufacturer
  • Compatible with Android
  • Compatible with Windows
  • Compatible with Linux
  • Compatible with MacOS X (not stable, some people have issues, doesn't work with old devices)
  • Compatible with iOS (not stable, some people have issues, doesn't work with old devices)

Installation

Example

/**
 * This example turns the ESP32 into a Bluetooth LE mouse that scrolls down every 2 seconds.
 */
#include <BleMouse.h>

BleMouse bleMouse;

void setup() {
  Serial.begin(115200);
  Serial.println("Starting BLE work!");
  bleMouse.begin();
}

void loop() {
  if(bleMouse.isConnected()) {
    Serial.println("Scroll Down");
    bleMouse.move(0,0,-1);
  }
  delay(2000);
}

API docs

The BleMouse interface is almost identical to the Mouse Interface, so you can use documentation right here: https://www.arduino.cc/reference/en/language/functions/usb/mouse/

Just remember that you have to use bleMouse instead of just Mouse and you need these two lines at the top of your script:

#include <BleMouse.h>
BleMouse bleMouse;

This library supports a few additional features that the Mouse library does not support at the time of writing:

  • Scrolling left/right E.g.: bleMouse.move(0,0,0,1) (Scroll left) and bleMouse.move(0,0,0,-1) (Scroll right)
  • Using the back and forward buttons E.g.: bleMouse.click(MOUSE_BACK) and bleMouse.click(MOUSE_FORWARD)

There is also Bluetooth specific information that you can use (optional):

Instead of BleMouse bleMouse; you can do BleMouse bleMouse("Bluetooth Device Name", "Bluetooth Device Manufacturer", 100);. 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%). By default the battery level will be set to 100%, the device name will be ESP32 Bluetooth Mouse and the manufacturer will be Espressif.

Credits

Credits to chegewara as this library is based on this piece of code that he provided.

esp32-ble-mouse's People

Contributors

dvv avatar grafmar avatar ricalvrod avatar sobrinho avatar t-vk avatar

Stargazers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

Watchers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

esp32-ble-mouse's Issues

[Question] Can I use this with BLE-Keyboard?

Is there any way i can use this with BLE-Keyboard Project, without the need reconnect?

Basically i have a rotary encoder and want to use it to send VOLUME UP/DOWN commands & when switching the mode by pressing the button of the rotary encoder, switch into horizontal scroll mode.

If i understand correctly, i would need to disconnect and reconnect as the other device, or would there be a more comfortable way to do so?

So far i used HID-Project library via USB on a Arduino Micro, but want to move to an ESP32 and Bluetooth

Also i saw some issues about disconnecting and reconnecting not working and they have to soft reboot. So i guess my project is not possible that straight forward?

Implementation, with respect to a line of code within BleMouse.cpp

Hello,

I noticed that, within BleMouse.cpp, xTaskCreate() was being called. I have a few questions regarding this.

  1. The example code(specifically ScrollAndMouseMove), that is included with this library, doesnt seem to implement an RTOS structure. How are you able to implement a task, while also being able to use a main-loop coding structure?
  2. What library are you using to call xTaskCreate()? I am having trouble finding it and I would like to reference it, in order to understand your code better.

Accelerometer gesture sense that doesn't require tensorflow or other remote AI?

ESP32-BLE-Mouse is so easy to use! Thank you x 100! I'd like to extend it to support accelerometer-based gestures. I'm working on my wrist watch project (https://github.com/frankcohen/ReflectionsOS). It has an ESP32-S3, accelerometer, compass, and GPS, no touch screen, no buttons. It's all open-source. I am searching for code to interpret accelerometer data for gestures. Like making a big circle would register as a gesture, or shaking left and right a few inches would register as a gesture. I can't depend on the Internet being available while this is in operation. I could use a Tensor flow or other approach for training while networking is available. What have you seen? Pointers please. Thanks! -Frank

Connecting to PlayStation 4 console

Hello sir!

I am using an esp32 with your code and it works great on any bt device except the PlayStation 4, I can see how the ps4 finds the device but there is no way to pair it...

Could you tell me what could be happening?

Thanks in advance!!

Good suggestion for developers use wifi

Wi-Fi is faster than Bluetooth, the response time in Bluetooth is 60ms, but Wi-Fi is 20ms, 3 times faster
If wifi is supported then the library can be used more widely with other chips, like esp8266, which is cheaper than esp32, but it doesn't have bluetooth.

Forwarding input from USB host

I am trying to forward the input from Logitech USB keyboard and Logitech USB mouse using this library. The keyboard is working aside from the media keys.

The mouse is sending an 8 byte input report and I don't understand entirely which byte is representing what.

Example:
0x2 always the same
0x0 buttons
0x0 always 0x0
0xFF x axes
0xF y axes, but also changes when x is negative
0x0 changes when y is negative
0x0 scrolling wheel x
0x0 maybe scrolling wheel y but with my mouse I cannot scroll horizontally

I've seen only examples with 5 byte input reports. I updated the report descriptor with the input device's descriptor but still not working. I think the issue is still the device descriptor but I don't have the knowledge to debug it. The descriptor is 177 bytes whereas in the example code it's much smaller. I don't know if there is a limitation.

Analog input fails

Mouse library works fine on iphone7 after removing line 28 in BleMouse.cpp
However, I can't get any analog readings from my ESP32 (Dev kit or Wemos). As soon as "bleMouse.begin();" command is given then analog reads stop.
Is it just me? Can someone please try the simple sketch below. Without any connections it produces random numbers as expected.
Than remove the '//' in front of 'bleMouse.begin()' and run again. All I get is zeros.

#include <BleMouse.h>
BleMouse bleMouse;
void setup() {
Serial.begin(115200);
Serial.println("Testing Analog read");
// bleMouse.begin();
}
void loop() {
Serial.println(analogRead(33));
}

Thanks

License info

Is this open source? No license was specified

Absmouse for windows

Can it work like as abs mouse on windows which move on pixels provided like:

AbsMouse.init(1920, 1080);

AbsMouse.move(Xcordinate, Ycordinate);

Doesn't appear to work on windows 7

I've uploaded an example, I can pair using two different windows 10 laptops and my android phone. However, I tested on two other windows 7 machines and they cannot see the Bluetooth device at all.

Scroll down/up smoothly on Android?

Hi, thank you for publish good tools.
I want to use this BLE mouse on Android.
Now scroll down and up is not smooth.

Is it possible to scroll smoothly?

List of supported / unsupported Apple devices (iPhones, iPads, Macs etc.)

I would like to maintain a list of Apple devices here that work or don't work with this library.
If you have tested a device that is not listed with the same OS version yet, please add a comment and tell me which device and operating system (i.e. iOS version or Mac OS version).
If you tested a device that is already listed, but you had different results (e.g. list says it doesn't work, but for you it does work), please add a comment as well. (And don't forget to mention your device name and OS version.)

Devices that work

  • iPhone XS | iOS 14 | Reported by consciouspnm
  • iPhone SE 2nd Generation | iOS 13.4 | Reported by DareDareHub
  • iPad 7th Generation | iOS 14.0.1 | Reported by DareDareHub
  • iPad Pro 10.5 | iOS 13.7 | Reported by DareDareHub
  • iPad Pro 10.5 | iOS 10.3.2 | Reported by DareDareHub (Slower cursor speed than on iOS 13.7)
  • iPad Air | iOS 14 | Reported by consciouspnm
  • iPad Air 2 | iOS 13.5.1 | Reported by consciouspnm
  • iPad Pro 10.5 | iOS13.7 | Reported by xcarcelle | (Some reconnect issues)
  • MacBook Pro (Unknown year) | MacOS 10.14.6 | Reported by 00ghost

Devices that don't work

  • 3rd generation iPad (2012) AND ALL DEVICES OLDER THAN THAT (because they don't support Bluetooth LE)
  • iPhone 4s AND ALL DEVICES OLDER THAN THAT (because they don't support Bluetooth LE)
  • MacBook Air 2011 AND ALL DEVICES OLDER THAN THAT (because they don't support Bluetooth LE)
  • MacBook Pro 2012 AND ALL DEVICES OLDER THAN THAT (because they don't support Bluetooth LE)
  • MacMini 2011 AND ALL DEVICES OLDER THAN THAT (because they don't support Bluetooth LE)
  • iMac 2012 AND ALL DEVICES OLDER THAN THAT (because they don't support Bluetooth LE)
  • iPhone 7 | iOS 13.1.2 | Reported by 00ghost
  • iPad 6th Gen | iOS 13 | Reported by lawleo

Got an error with "BleMouse.cpp"

I got an error when I try to write examples on Arduino.

I fixed this with rewriting ln164 in "BleMouse.cpp"
from
bleKeyboardInstance->onStarted(pServer);
to
bleMouseInstance->onStarted(pServer);

Keep mouse cursor at screen center

Thanks for your great project!

I connected esp32 to an android phone, how can I move mouse cursor to the center of screen whatever the mouse had been moved to any position.

Windows 10 connection problems (solved)

To make it connect on Windows 10, I had to do the following:

replace the first line below by the next 3
//pSecurity->setAuthenticationMode(ESP_LE_AUTH_BOND);
pSecurity->setAuthenticationMode(ESP_LE_AUTH_REQ_SC_ONLY);
pSecurity->setCapability(ESP_IO_CAP_OUT);
pSecurity->setInitEncryptionKey(ESP_BLE_ENC_KEY_MASK | ESP_BLE_ID_KEY_MASK);

I am not knowledgeable on BLE, I cannot make a properly documented pull request.

ESP32-S3 Support / Mac OS support

I haven't been able to make my ESP32-s3 work with MacBook Pro M1 as well as Intel chip, It shows the device in Bluetooth devices list, pairing, In verbose mode, it logged following
E (15363) BT_GATT: GATT_INSUF_AUTHENTICATION
On intel chip in addition to ablove it showed following

E (57040) BT_BTM: BTM_GetSecurityFlags false

E (57070) BT_BTM: BTM_GetSecurityFlags false

E (57100) BT_BTM: BTM_GetSecurityFlags false

The connection seem to be broken, Laptop stops showing the device, the ESP32-s3 keeps getting TRUE for bleMouse.isConnected()
The thing I am not sure about is if ESP32-S3 is even supported yet.

the actual move offset does not match ipad resolution pixel

I tested on ipad mini 5. The resolution is 2048*1536.
1、When I set initial x to 0 and call move to increment x by 10 every time. I found that x incremented by about 1300 totally when the cursor reaches the edge of screen in landscape view. That's far away from 2048.
2、When changing increment step from 10 to 50. The final movement along x axis is only about 660.
3、When calling simpleMove(0,0) #19 and then moveTo(0, 100, 1.0, 0, 0, 0) the cursor moves along y by y1. When calling simpleMove(0,0) and followed by moveTo(100, 100, 1.0, 0, 0,0) the cursor moves along y by y2. I found that y1 is larger than y2.

I don't understand why the above experiments happen. Is there any explaination?
Thanks in advance.

conflict with wifi

I think this library might conflict with wifi.
I put the wifi stuff and BLE stuff in two separate functions. When I comment out any one of them the program running ok. But if not, the program will upload, but the esp32 will reset halfway through starting. In my program wifi starts before BLE. The wifi starts ok, then before any of the BLE mouse libraries been used the chip is crashed.
I think it is because BLE and wifi share the same antenna.
any chance you can modify the library, so before "begin()" were called, the library will not use any BLE hardware, please?

Does the setBatteryLevel function actually work

Hi

Can anyone confirm that the setBatteryLevel function actually works?

On Windows, it doesn't seem to work

In the code below for example, I set the battery level to 90% when the device is started, and it shows up in Windows fine, but then I try to reduce the battery level by 1% every 30 seconds, but the information is not updated in Windows.

Any idea on how to get it working?

Thanks

#include <BleMouse.h>

int batteryLevel = 90;

BleMouse bleMouse("BLE Mouse", "lemmingDev", batteryLevel);

void setup() {
  Serial.begin(115200);
  Serial.println("Starting BLE work!");
  bleMouse.begin();
}

void loop() {
  if(bleMouse.isConnected()) {
    Serial.print("Battery Level: ");
    Serial.println(batteryLevel);
    bleMouse.setBatteryLevel(batteryLevel);
    delay(30000);
    batteryLevel--;
  }
}

Add sendReport

I added a sendReport so it can be used with a USB to BLE mouse pass through.

USBMouseReport *report;

bleMouse.sendReport(report->buttons, report->x, report-y, report->wheel);

If interested I can push a PR.

how to merge the keypad and mouse

i need use ble mouse and ble keypad ,how can i use then both ,i merged the HID Report Descriptor in keypad and create a new [BLECharacteristic *inputMouse; ] but not work

Button

I want to make a push button that simulates the left click of a mouse How can I do it?

IoS 13 compatibility?

Hi,

I would like to use the new feature in IoS 13 to use an external mouse and tried your lib. However, it seems that ESP32-BLE-Mouse does not work for me to an iPhone 7 with IoS 13.1.2. I e, the ESP connects to the phone but then nothing. Same library work fine to a MacBookPro with MacOS 10.14.6. The ESP32-BLE-Keyboard library works fine (but only a few keys tested) with both these devices. Accessibility settings on the phone seem to be correct. ESP used is a Sparkfun ESP32 Thing.
Anything I can test or try?

Göran

feature request: Absolute mode

Is there any possibility that there will be an absolute mode? That would be more useful and intuitive since otherwise I don't see a way around resetting the mouse position if it has accidentally 'run against a border', if that makes sense!

Also, sorry, I'm new to this field

Compiles, but is not working as expected.

Hi,

I followed your work already at th ESP-BLE-Snippets.
The basic Arduino code from chegewara is sending the text.
Now I tried your library but can't get it to work.
Here is my test code:

#include <BleMouse.h>

BleMouse bleMouse;

void setup() {
  Serial.begin(115200);
  Serial.println("Starting BLE work!");
  bleMouse.begin();
  pinMode(12, INPUT_PULLUP);
  attachInterrupt(digitalPinToInterrupt(12), clickNumLock, FALLING);   // Num Lock
}

void loop() {
}

IRAM_ATTR void clickNumLock(){
  if(bleMouse.isConnected()) {
    bleMouse.click(MOUSE_BACK);
    Serial.println("Buttonpressed");
  }
} 

It compiles with no errors, Win10 and Android are able to connect, but under Win10 nothing happens, with Android the mouse pointer appears and moves a little to the right after each keystroke, no matter which command is sent (MOUSE_LEFT, RIGHT or BACK). Am I doing it all wrong?

btw. do you think, you can include 3 more functions in your library. My goal is to make a simple media controll button with a rotary encoder and with following functions: "play/pause", "Volume up", "Volume down" (eventually "next song"). But I am not able to send these keystrokes over BLE with my ESP32, my coding skills are by far not enough ;).

best regards
Daniel

Why xTaskCreate() is used?

Hi.
I have slightly understood the purposes of task processing of Arduino.
I wonder ESP32-BLE-Mouse works well without xTaskCreate().
Does skipping(bypassing) this xTaskCreate() invites some troubles?
I believe that skipping may invite some delaying.
However ESP32-BLE-Keyboard does not use xTaskCreate(), doesn't it?

BLE won't reconnect after bluetooth is stopped and restarted.

Board: ESP32-C3

If I use the code template below I am unable to reconnect to the board with my PC. The board auto-connects fine with the first instance of bleMouse.begin() but does not reconnect after bluetooth is stopped and restarted. If I use deep sleep or reset the board it will reconnect without issues. The mouse commands are still sent and bleMouse.isConnected returns true after bluetooth is restarted, but there is no connection shown on my PC and it does not receive the mouse commands. I also receive the error message shown below after bluetooth is restarted.

Code template:

bleMouse.begin();
while(bleMouse.isConnected) {
  // send mouse commands
}
bleMouse.end();
btStop();
// do something else
btStart();
bleMouse.begin();
while(bleMouse.isConnected) {
  // send mouse commands
}

Error message:
E (80831) BT_HCI: command_timed_out hci layer timeout waiting for response to a command. opcode: 0x2008

Mac OS X Pair Workaround

In case it is relevant for anyone else, I was able to work around Mac OS X not pairing by not sending any commands for 5-10 seconds after it connected. This could likely be tuned lower, but is good for my use case.

Example:

unsigned long connectedMillis = 0; // delay actions until after connected for 10 seconds, because apple is dumb
// ...
BleMouse bleMouse;


void setup()
{
  // ...
}

void loop()
{
  // Start, apple is dumb.
  if(bleMouse.isConnected()) {
    if (connectedMillis == 0) {
      connectedMillis = millis();
    }
    
  }
  
  if (millis() < connectedMillis + (10 * 1000)) {
    return;
  }
  // End, apple is dumb.
  
  // ... 
}

Regards,
Dan

Connection fail after IOS restore

Not sure this is BLE mouse library issue.
Seem like ESP32 core bug.

I am using same ESP32 board with 3 three IOS device with no problem.
After I restore IOS device A, ESP32 cannot connect anymore. However, device B and C still working.

Then, I use "pio run --target erase" the clear the ESP32 and re-upload the program.
Device A start working again.

Seem like ESP32 core library cannot register new key (this key change after IOS restore), if the device address have registered already.

Any though on how to solve this issue?
How can I clear the registered bond data OR limit the max bond device to 1 (auto de-bond every time).

does it work in ipadOS ?

sorry this is not a issue..

I am curious it,

does it work in ipadOS ?

I read it

Customize Bluetooth device name/manufacturer
Compatible with Android
Compatible with Windows
Compatible with Linux
Compatible with MacOS X (not stable, some people have issues, doesn't work with old devices)
Compatible with iOS (not stable, some people have issues, doesn't work with old devices)

Only Ipad was excluded from the list.

Landscape orientation issue with Android absolute mouse mode

Hi there,
after running this code esp32-ble-mouse-abs-android.ino.txt with Android 8/9, it enables correctly the absolute mode when moveTo(x, y) goes directly to the target position on Android devices. However this works in portrait mode but in landscape mode, we observed that the virtual enabled zone is still in portrait mode and the mouse cannot go beyond the width of the portrait mode.
It seems difficult to determine if it is due to Android in rotation mode to landscape or some other issue with the HID descriptor and send report ? Have you guys experienced such an issue with Android device in absolute mode ?
Devices tested : tablets (Lenovo and Huawey models along with some android phones) in Android 8.0/9.0.
Cheers.

ESP32-BLE-Gamepad

Thanks heaps for making ESP32-BLE-Mouse and ESP32-BLE-Keyboard
It will make it much easier to use that functionality now

Am hoping you may consider creating ESP32-BLE-Gamepad

A ton of possibilities....

how to reconnect the ble-mouse when device restarted?

when one device connected the ble-mouse successfully,if i restart the device,it can not reconnect again and can not find the ble-mouse by using any other device at the same time, except restart the ble-mouse,3q!

sdkconfig.h

[build] C:/BleMouse/BleMouse.h:3:10: fatal error: sdkconfig.h: No such file or directory
[build]     3 | #include "sdkconfig.h"
[build]       |          ^~~~~~~~~~~~~

where should sdkconfig.h be and whats inside?

The iPhone doesn't work

Hello author, I use your library to use ios to connect to the Bluetooth esp32 it automatically disconnected, what error did not report, but Android and Windows can be used normally this is what caused the reason.

Dose not connect with Android

It connected with pc (win10) just fine, but in phone when I click the esp32 device esp32 thinks all ready connected but phone is not still connected and I gives a error in phone invalid pin (pass key) entered how to fix this help?? or else can I put a pass key so only I can use the device too

Thank you

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. 📊📈🎉

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google ❤️ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.