BLE52 Mouse and Keyboard Usage

Understanding Bluetooth BLE HID

The other library we used in this tutorial relied on communication over a USB cable between your Arduino device that was emulating mouse or keyboard and your PC, tablet or other similar device. However many PCs, tablets and other devices allow you to connect a mouse or keyboard using Bluetooth Low Energy or BLE for short. Establishing a Bluetooth link between your board and another device is pretty complicated programming. This library attempts to not only translate the traditional Arduino Mouse and Keyboard API calls into a BLE call, it also isolates you from all of the overhead necessary to establish and maintain a Bluetooth link.

Currently this library is called BLE52_Mouse_and_Keyboard and has only been tested using boards based on nRF52840 processors. It may work on older Adafruit Bluefruit BLE devices but we have not yet had the opportunity to test it on those platforms. So for now we are assuming you're using a board that has a nRF52840 processor.

In this section, we will try running one of the sample programs and pairing it with your PC, phone, or other device capable of using Bluetooth mouse or keyboard. We will show you how to do this pairing on a Windows 10 computer but the process should be straightforward on other operating systems or platforms.

Using the BLE52 Mouse and Keyboard Library

As previously mentioned, the traditional way to control a mouse or keyboard is the following include files.

Download: file
#include <HID.h>
#include <Mouse.h>
#include <Keyboard.h>

You should erase those lines and replace them with

Download: file
#include <BLE52_Mouse_and_Keyboard.h>

Note that there is no way to separate Mouse and Keyboard inclusion in our system. It was much easier to implement both at once rather than implementing them separately. Your board will present itself over Bluetooth as a single Bluetooth device with both mouse and keyboard capabilities. It is possible that if you do not use Keyboard for example and only Mouse that the linking loader will eliminate the Keyboard code from your final compile and vice versa if you use keyboard and not mouse. However the nRF52840 has plenty of program memory and it shouldn't hurt if we have to waste a little bit on applications that use mouse or keyboard but not both.

If you have existing code that uses Mouse.h or Keyboard.h or both you should makes the changes noted above and give it a try.

WARNING: If you did not do a Mouse.begin() or Keyboard.begin() in your code, you MUST add that in your setup section. The original mouse and keyboard did not require it but we do.

There is one more modification you will have to add to your code. You need to test to make sure that your nRF52840 board has been properly paired over Bluetooth with your PC or whatever device to which you are connecting. To facilitate this we have added an extra method not available in the standard Mouse.h and Keyboard.h classes. We have added

Download: file
bool Mouse.isConnected(void);
bool Keyboard.isConnected(void);

Below is a code excerpt from the BLE52_Pairing_Test sample program available in the examples folder of the library. It illustrates how to use the isConnected() method.

Download: file
void setup() {
  Serial.begin(115200);
  while ( !Serial ) delay(10);   // for nrf52840 with native usb
  Serial.println("Bluefruit52 HID Mouse Example");
  Serial.println("Go to your phone's Bluetooth settings to pair your device");
  Serial.println("then open an application that accepts keyboard input");

  Mouse.begin();     //Unlike the standard Mouse.h you MUST use the "Mouse.begin();" method
  Serial.print("Attempting to connect");
  uint8_t i=0;
  while(! Mouse.isConnected()) { 
    Serial.print("."); delay(100);
    if((++i)>50) {
      i=0; Serial.println();
    }
  };
  delay(1000);//just in case
  Serial.println("\nConnection successful");

After printing out an opening message, we do a Mouse.begin(). This attempts to initialize a BLE connection with your device. We then go into a while loop in which we test to see if Mouse.isConnected(). It prints out a series of dots on your serial monitor until they connection is established. When the connection is finally established, we break out of the while statement and report the successful connection. We then continue with the rest of the program.

If we were using a keyboard example we would use the Keyboard.isConnected() method instead.

If your program uses both mouse and keyboard, you only need to check one or the other. Your nRF52840 appears to be a single device supporting both mouse and keyboard functions and so if one is connected, everything is connected.

Note if you are using mouse you must do a Mouse.begin() to initialize the connection and similarly Keyboard.begin() if you're using keyboard alone. If you are using both mouse and keyboard, technically you don't have to do begin for both but we suggest you do. At some point you might reuse this program for just one or the other function and forget to do the begin for the proper device. Internally we make sure that if you use both begins it only tries to initialize once.

Pairing to a Windows 10 PC

There is a sample program in the examples folder titled BLE52_Pairing_Test. The same code in this program is also at the top of all of the other BLE sample programs. Configure your IDE for your nRF52840 and the proper port for uploading. Open your serial monitor and compile and upload the program.

Then on your Windows 10 PC click on Start and then open your "Settings" page. Then click on "Devices. (Bluetooth, printers, mouse)" you will then see a page similar to this.

You should click on the + in front of "Add Bluetooth or other device". You will then see something like this.

Click on the Bluetooth option and after a few seconds you should see.

Your nRF52840 board will appear as "Bluefruit52". Later we will show you how you can use a different name. Click on it and then it should connect. When the pop-up closes you will now see the device listed among your available connected devices. Although it shows a mouse icon, it will have both mouse and keyboard capabilities.

Other Information About Pairing

While your attempt to pair the nRF52840 is in progress, you will see the following on your serial monitor.

Bluefruit52 HID Mouse Example
Go to your phone's Bluetooth settings to pair your device
then open an application that accepts keyboard input
Attempting to connect...................................................
...................................................
...................................................
...................................................
...................................................
...................................................
...................................................
...................................................
............................................
Connection successful

Once you have done this process one time, you probably will not need to pair your device again. You will probably only see 4 or 5 dots appear after the attempting to connect message and then you will successfully connect.

As mentioned before, the default name for your nRF52840 will be "Bluefruit52". However if you want to use a different more personal name to help identify your gadget you can specify the name in your begin method. For example

Mouse.begin("MyDevice");

Note that you cannot name the mouse and keyboard two different things because they appear as a single multipurpose device.

We suggest you now try all three of the other sample programs for Mouse, Keyboard, and a combination of Mouse and Keyboard.

This guide was first published on May 13, 2020. It was last updated on May 13, 2020.
This page (BLE52 Mouse and Keyboard Usage) was last updated on Jul 03, 2020.