Skip to main content
Introducing Bluefruit EZ-Key Sending Keys/Mouse Via Serial

Introducing Bluefruit EZ-Key

Image for user adafruit2
by lady ada
published September 27, 2013, last edited September 22, 2016
posted in Adafruit Products
Save Download
54
Intermediate
Project guide

Sending Keys/Mouse Via Serial

For advanced users, you may want to hook up your Bluefruit to a microcontroller and send characters or strings via Bluetooth.

You can do this with the UART port on the EZ-Key. The UART pins are labeled RX (data going into the module) and TX (debug data coming out of the module). You can get away with just connecting to RX. The RX pin is 5V compliant, you can send it 3V or 5V TTL logic levels. Use 9600 baud serial, all microcontrollers will support this.

You can also send raw HID Keyboard reports for complex key-stroke combinations and controls.

In version v1.1 (Oct 22, 2013 or later) HID Mouse reports are also supported, you can send mouse movement and clicks via the UART and microcontroller
In version v1.2 (Nov 2013 or later) HID consumer report keys are supported, there are a few supported 'multimedia keys' - see below for a list and how to send via the UART

Don't forget to also tie a ground pin from your microcontroller to the EZ-Key for the logic ground reference!

Printable character keymap


For printing ASCII characters, you can simply send those to the UART and they will be 'typed out'. See below for the list of printable ASCII characters, starting with 0x20 and ending with 0x7E

Thanks to Wikipedia for this nice chart!
Binary Oct Dec Hex Glyph
010 0000 040 32 20
010 0001 041 33 21 !
010 0010 042 34 22 "
010 0011 043 35 23 #
010 0100 044 36 24 $
010 0101 045 37 25 %
010 0110 046 38 26 &
010 0111 047 39 27 '
010 1000 050 40 28 (
010 1001 051 41 29 )
010 1010 052 42 2A *
010 1011 053 43 2B +
010 1100 054 44 2C ,
010 1101 055 45 2D -
010 1110 056 46 2E .
010 1111 057 47 2F /
011 0000 060 48 30 0
011 0001 061 49 31 1
011 0010 062 50 32 2
011 0011 063 51 33 3
011 0100 064 52 34 4
011 0101 065 53 35 5
011 0110 066 54 36 6
011 0111 067 55 37 7
011 1000 070 56 38 8
011 1001 071 57 39 9
011 1010 072 58 3A :
011 1011 073 59 3B ;
011 1100 074 60 3C <
011 1101 075 61 3D =
011 1110 076 62 3E >
011 1111 077 63 3F ?
Binary Oct Dec Hex Glyph
100 0000 100 64 40 @
100 0001 101 65 41 A
100 0010 102 66 42 B
100 0011 103 67 43 C
100 0100 104 68 44 D
100 0101 105 69 45 E
100 0110 106 70 46 F
100 0111 107 71 47 G
100 1000 110 72 48 H
100 1001 111 73 49 I
100 1010 112 74 4A J
100 1011 113 75 4B K
100 1100 114 76 4C L
100 1101 115 77 4D M
100 1110 116 78 4E N
100 1111 117 79 4F O
101 0000 120 80 50 P
101 0001 121 81 51 Q
101 0010 122 82 52 R
101 0011 123 83 53 S
101 0100 124 84 54 T
101 0101 125 85 55 U
101 0110 126 86 56 V
101 0111 127 87 57 W
101 1000 130 88 58 X
101 1001 131 89 59 Y
101 1010 132 90 5A Z
101 1011 133 91 5B [
101 1100 134 92 5C \
101 1101 135 93 5D ]
101 1110 136 94 5E ^
101 1111 137 95 5F _
Binary Oct Dec Hex Glyph
110 0000 140 96 60 `
110 0001 141 97 61 a
110 0010 142 98 62 b
110 0011 143 99 63 c
110 0100 144 100 64 d
110 0101 145 101 65 e
110 0110 146 102 66 f
110 0111 147 103 67 g
110 1000 150 104 68 h
110 1001 151 105 69 i
110 1010 152 106 6A j
110 1011 153 107 6B k
110 1100 154 108 6C l
110 1101 155 109 6D m
110 1110 156 110 6E n
110 1111 157 111 6F o
111 0000 160 112 70 p
111 0001 161 113 71 q
111 0010 162 114 72 r
111 0011 163 115 73 s
111 0100 164 116 74 t
111 0101 165 117 75 u
111 0110 166 118 76 v
111 0111 167 119 77 w
111 1000 170 120 78 x
111 1001 171 121 79 y
111 1010 172 122 7A z
111 1011 173 123 7B {
111 1100 174 124 7C |
111 1101 175 125 7D }
111 1110 176 126 7E ~

Non-printable Characters


There's a lot of other keycodes you may want to send, here is the mapping from the 8-bit byte to the keycode sent.


HEX Keyname
0x01 Insert
0x02 Home
0x03 Page Up
0x04 Delete
0x05 End
0x06 Page Down
0x07 Right Arrow
0x08 Backspace
0x09 Tab
0x0A Enter
0x0B Left Arrow
0x0C Down Arrow
0x0D Enter
0x0E Up Arrow
0x0F - 0x1A F1 - F12
0x1B Esc
0x1C Caps Lock
0x1D Scroll Lock
0x1E Break
0x1F Num Lock
0x20-0x7E Printable Ascii
0x7F Toggle iOS Keyboard
0xE0 Left Control
0xE1 Left Shift
0xE2 Left Alt
0xE3 Left GUI
0xE4 Right Control
0xE5 Right Shift
0xE6 Right Alt
0xE7 Right GUI

Raw HID Keyboard Reports


Bluefruit can send raw HID Keyboard reports. This allows sending any modifier keys + up to 6 keycodes at once. Its advanced but super useful for when you want to have fine-control of keypresses!

Raw HID reports start with 0xFD and have 8 bytes following. For keyboard, its
0xFD [modifiers] 0x00 [keycode1] [keycode2] [keycode3] [keycode4] [keycode5] [keycode6]
Raw USB HID keycodes are not the same as ASCII!
Here's a list of USB HID keycodes (its in java format but you get the idea), you can also get another list here http://www.freebsddiary.org/APC/usb_hid_usages.php under "7 Keyboard"
Download File
Copy Code 
// Bits in usbHidKeyboardInput.modifiers
final byte MODIFIER_NONE          =byte((0));
final byte MODIFIER_CONTROL_LEFT  =byte((1<<0));
final byte MODIFIER_SHIFT_LEFT    =byte((1<<1));
final byte MODIFIER_ALT_LEFT      =byte((1<<2));
final byte MODIFIER_GUI_LEFT      =byte((1<<3));
final byte MODIFIER_CONTROL_RIGHT =byte((1<<4));
final byte MODIFIER_SHIFT_RIGHT   =byte((1<<5));
final byte MODIFIER_ALT_RIGHT     =byte((1<<6));
final byte MODIFIER_GUI_RIGHT     =byte((1<<7));

// Values for usbHidKeyboardInput.keyCodes
// Only the key codes for common keys are defined here. See Hut1_12.pdf for a full list.
final byte KEY_NONE               =byte(0x00);
final byte KEY_A                  =byte(0x04);
final byte KEY_B                  =byte(0x05);
final byte KEY_C                  =byte(0x06);
final byte KEY_D                  =byte(0x07);
final byte KEY_E                  =byte(0x08);
final byte KEY_F                  =byte(0x09);
final byte KEY_G                  =byte(0x0A);
final byte KEY_H                  =byte(0x0B);
final byte KEY_I                  =byte(0x0C);
final byte KEY_J                  =byte(0x0D);
final byte KEY_K                  =byte(0x0E);
final byte KEY_L                  =byte(0x0F);
final byte KEY_M                  =byte(0x10);
final byte KEY_N                  =byte(0x11);
final byte KEY_O                  =byte(0x12);
final byte KEY_P                  =byte(0x13);
final byte KEY_Q                  =byte(0x14);
final byte KEY_R                  =byte(0x15);
final byte KEY_S                  =byte(0x16);
final byte KEY_T                  =byte(0x17);
final byte KEY_U                  =byte(0x18);
final byte KEY_V                  =byte(0x19);
final byte KEY_W                  =byte(0x1A);
final byte KEY_X                  =byte(0x1B);
final byte KEY_Y                  =byte(0x1C);
final byte KEY_Z                  =byte(0x1D);
final byte KEY_1                  =byte(0x1E);
final byte KEY_2                  =byte(0x1F);
final byte KEY_3                  =byte(0x20);
final byte KEY_4                  =byte(0x21);
final byte KEY_5                  =byte(0x22);
final byte KEY_6                  =byte(0x23);
final byte KEY_7                  =byte(0x24);
final byte KEY_8                  =byte(0x25);
final byte KEY_9                  =byte(0x26);
final byte KEY_0                  =byte(0x27);
final byte KEY_RETURN             =byte(0x28);
final byte KEY_ESCAPE             =byte(0x29);
final byte KEY_BACKSPACE          =byte(0x2A);
final byte KEY_TAB                =byte(0x2B);
final byte KEY_SPACE              =byte(0x2C);
final byte KEY_MINUS              =byte(0x2D);
final byte KEY_EQUAL              =byte(0x2E);
final byte KEY_BRACKET_LEFT       =byte(0x2F);
final byte KEY_BRACKET_RIGHT      =byte(0x30);
final byte KEY_BACKSLASH          =byte(0x31);
final byte KEY_EUROPE_1           =byte(0x32);
final byte KEY_SEMICOLON          =byte(0x33);
final byte KEY_APOSTROPHE         =byte(0x34);
final byte KEY_GRAVE              =byte(0x35);
final byte KEY_COMMA              =byte(0x36);
final byte KEY_PERIOD             =byte(0x37);
final byte KEY_SLASH              =byte(0x38);
final byte KEY_CAPS_LOCK          =byte(0x39);
final byte KEY_F1                 =byte(0x3A);
final byte KEY_F2                 =byte(0x3B);
final byte KEY_F3                 =byte(0x3C);
final byte KEY_F4                 =byte(0x3D);
final byte KEY_F5                 =byte(0x3E);
final byte KEY_F6                 =byte(0x3F);
final byte KEY_F7                 =byte(0x40);
final byte KEY_F8                 =byte(0x41);
final byte KEY_F9                 =byte(0x42);
final byte KEY_F10                =byte(0x43);
final byte KEY_F11                =byte(0x44);
final byte KEY_F12                =byte(0x45);
final byte KEY_PRINT_SCREEN       =byte(0x46);
final byte KEY_SCROLL_LOCK        =byte(0x47);
final byte KEY_PAUSE              =byte(0x48);
final byte KEY_INSERT             =byte(0x49);
final byte KEY_HOME               =byte(0x4A);
final byte KEY_PAGE_UP            =byte(0x4B);
final byte KEY_DELETE             =byte(0x4C);
final byte KEY_END                =byte(0x4D);
final byte KEY_PAGE_DOWN          =byte(0x4E);
final byte KEY_ARROW_RIGHT        =byte(0x4F);
final byte KEY_ARROW_LEFT         =byte(0x50);
final byte KEY_ARROW_DOWN         =byte(0x51);
final byte KEY_ARROW_UP           =byte(0x52);
final byte KEY_NUM_LOCK           =byte(0x53);
final byte KEY_KEYPAD_DIVIDE      =byte(0x54);
final byte KEY_KEYPAD_MULTIPLY    =byte(0x55);
final byte KEY_KEYPAD_SUBTRACT    =byte(0x56);
final byte KEY_KEYPAD_ADD         =byte(0x57);
final byte KEY_KEYPAD_ENTER       =byte(0x58);
final byte KEY_KEYPAD_1           =byte(0x59);
final byte KEY_KEYPAD_2           =byte(0x5A);
final byte KEY_KEYPAD_3           =byte(0x5B);
final byte KEY_KEYPAD_4           =byte(0x5C);
final byte KEY_KEYPAD_5           =byte(0x5D);
final byte KEY_KEYPAD_6           =byte(0x5E);
final byte KEY_KEYPAD_7           =byte(0x5F);
final byte KEY_KEYPAD_8           =byte(0x60);
final byte KEY_KEYPAD_9           =byte(0x61);
final byte KEY_KEYPAD_0           =byte(0x62);
final byte KEY_KEYPAD_DECIMAL     =byte(0x63);
final byte KEY_EUROPE_2           =byte(0x64);
final byte KEY_APPLICATION        =byte(0x65);
final byte KEY_POWER              =byte(0x66);
final byte KEY_KEYPAD_EQUAL       =byte(0x67);
final byte KEY_F13                =byte(0x68);
final byte KEY_F14                =byte(0x69);
final byte KEY_F15                =byte(0x6A);
final byte KEY_CONTROL_LEFT       =byte(0xE0);
final byte KEY_SHIFT_LEFT         =byte(0xE1);
final byte KEY_ALT_LEFT           =byte(0xE2);
final byte KEY_GUI_LEFT           =byte(0xE3);
final byte KEY_CONTROL_RIGHT      =byte(0xE4);
final byte KEY_SHIFT_RIGHT        =byte(0xE5);
final byte KEY_ALT_RIGHT          =byte(0xE6);
final byte KEY_GUI_RIGHT          =byte(0xE7);
Here is the Arduino function we use to send a raw keyCommand. For example, if you want to send the keystroke for the letter 'a' (no shift) you'll want to call
keyCommand(0, 4);
to press the keycode 4 ('a') followed by a release
keyCommand(0, 0);
if you want to send the keystroke for SHIFT 'a' you'll want to call
keyCommand(MODIFIER_SHIFT_LEFT, 4);
if you want to send the keystroke for CTRL-SHIFT 'a' you'll want to call
keyCommand(MODIFIER_SHIFT_LEFT | MODIFIER_CONTROL_LEFT, 4);
You can also send multiple keystrokes ('chords'). If you want to press 'a' and 'b' at the same time, send
keyCommand(0, 4, 5);
for keycodes 4 and 5 at the same time. You can send up to 6 consecutive keys at once, don't forget to send the release 'key up' command or the key will be 'stuck'!
Download File
Copy Code 
void keyCommand(uint8_t modifiers, uint8_t keycode1, uint8_t keycode2 = 0, uint8_t keycode3 = 0, 
                uint8_t keycode4 = 0, uint8_t keycode5 = 0, uint8_t keycode6 = 0) {
  BT.write(0xFD);       // our command
  BT.write(modifiers);  // modifier!
  BT.write((byte)0x00); // 0x00  
  BT.write(keycode1);   // key code #1
  BT.write(keycode2); // key code #2
  BT.write(keycode3); // key code #3
  BT.write(keycode4); // key code #4
  BT.write(keycode5); // key code #5
  BT.write(keycode6); // key code #6
}

Raw HID Mouse Reports


As of v1.1 (shipping Oct 22, 2013) Bluefruit can also send raw HID Mouse reports. This allows moving and clicking a virtual mouse! Mouse reports are relative movement. So you can send 'go left 4 units' but you cant send 'go to absolute location x, y'

Raw HID reports start with 0xFD and have 8 bytes following. For mouse, its
0xFD 0x00 0x03 [buttons] [left/right] [up/down] 0x0 0x0 0x0

For buttons, its a bitmask, left button (button 0) is 0x01 right button (button 1) is 0x02, etc so that button n is (1 << n) you can | these together

up/down/left/right are again, relative movements. You can move up to +127 up/left to -127 down/right units at a time.
Download File
Copy Code 
void mouseCommand(uint8_t buttons, uint8_t x, uint8_t y) {
  BT.write(0xFD);
  BT.write((byte)0x00);
  BT.write((byte)0x03);
  BT.write(buttons);
  BT.write(x);
  BT.write(y);
  BT.write((byte)0x00);
  BT.write((byte)0x00);
  BT.write((byte)0x00);
}
For example if we wanted to click the left button and drag the mouse down 50 units send
mouseCommand(0x1, 0, -50);

Raw HID Consumer Reports


As of v1.2, Bluefruit can send raw HID consumer reports. There are "Home", "KeyboardLayout", "Search", "Snapshot", "VolumeUp", "VolumeDown", "Play/Pause", "Fast Forward", "Rewind","Scan Next Track", "Scan Previous Track", "Random Play","Stop" keys you can use with a 2 bytes bitmask.

Raw HID consumer report start with 0xFD and have 8 bytes following. For consumer keys, its
0xFD 0x00 0x02 [bitmask] [bitmask] 0x0 0x0 0x0 0x0

"Home" is bit 0, the bitmask is 0x01 0x00
"Stop" is bit 12, the bitmask is 0x00 0x10

You can | these together like mouse report
Download File
Copy Code 
void consumerCommand(uint8_t mask0,uint8_t mask1) {
  BT.write(0xFD);
  BT.write((byte)0x00);
  BT.write((byte)0x02);
  BT.write(mask0);
  BT.write(mask1);
  BT.write((byte)0x00);
  BT.write((byte)0x00);
  BT.write((byte)0x00);
  BT.write((byte)0x00);
}
For example if we wanted to click the Play/Pause
consumerCommand(0x40,0x00);
Then release it
consumerCommand(0x00,0x00);

Testing Sketch (Arduino)

We use this code to generate/test the various UART-sendable characters, you can use it for reference to control via an Arduino or other microcontroller. Remember that some of these non-printing characters can really confuse your computer so use with care!
Download File
Copy Code 
// Adafruit test code for Bluefruit EZ-Key serial reports
// Uncomment tests as you wish, remember that this will
// send various keypresses to your computer which may really
// annoy it! We used
// http://www.cambiaresearch.com/articles/15/javascript-char-codes-key-codes
// to test the non-printing characters!
// Connect the RX pin on the EZ-Key to digital #2 on the UNO

#include <SoftwareSerial.h>

SoftwareSerial BT = SoftwareSerial(3, 2);

void printabletest() {
  Serial.println("Testing printable 0x20-0x7E...");
  for (char c = 0x20; c <= 0x7E; c++) {
    Serial.write(c);
    BT.write(c);
    delay(10);
  }
  
  BT.write('\n');
  delay(3000);
  Serial.read(); // eat one char
  Serial.println();
  
  for (uint16_t i=0; i<200; i++) {
    while (Serial.available()) 
      Serial.write(Serial.read());
    delay(10);
  }
}

void nonprinting() { 
  Serial.println("Insert");
  BT.write(1); delay(1000);
  Serial.println("Home");
  BT.write(2); delay(1000);
  Serial.println("Page Up");
  BT.write(3); delay(1000);
  Serial.println("Delete");
  BT.write(4); delay(1000);
  Serial.println("End");
  BT.write(5); delay(1000);
  Serial.println("Page Down");
  BT.write(6); delay(1000);
  Serial.println("Right Arrow");
  BT.write(7); delay(1000);
  Serial.println("Backspace");
  BT.write(8); delay(1000);
  Serial.println("Tab");
  BT.write(9); delay(1000);
  Serial.println("Enter");
  BT.write(10); delay(1000);
  Serial.println("Left Arrow");
  BT.write(11); delay(1000);
  Serial.println("Down Arrow");
  BT.write(12); delay(1000);
  Serial.println("Enter");
  BT.write(13); delay(1000);
  Serial.println("Up Arrow");
  BT.write(14); delay(1000);

  for (uint8_t i=15; i<27; i++) {
    Serial.print("F"); Serial.println(i-14, DEC);
     BT.write(i); delay(500);
  }
  Serial.println("ESC");
  BT.write(27); delay(1000);
  Serial.println("Capslock");
  BT.write(28); delay(1000);
  Serial.println("Scroll lock");
  BT.write(29); delay(1000);
  Serial.println("Break");
  BT.write(30); delay(1000);
  Serial.println("Numlock");
  BT.write(31); delay(500);
 
}
void altkeystest() {
  Serial.println("Left Control\n");
  BT.write(0xE0);
  delay(500);
  Serial.println("Left Shift\n");
  BT.write(0xE1);
  delay(500);
  Serial.println("Left Alt\n");
  BT.write(0xE2);
  delay(500);
  Serial.println("Left GUI\n");
  BT.write(0xE3);
  delay(500);
  Serial.println("Right Control\n");
  BT.write(0xE4);
  delay(500);
  Serial.println("Right Shift\n");
  BT.write(0xE5);
  delay(500);
  Serial.println("Right Alt\n");
  BT.write(0xE6);
  delay(500);
  Serial.println("Right GUI\n");
  BT.write(0xE7);
  delay(500); 
}

void iphonekeyboard() {
  while (1) {
    Serial.println("toggle keyboard");
    BT.write(0x7F);
    delay(1000);
  }
}

void keyCommand(uint8_t modifiers, uint8_t keycode1, uint8_t keycode2 = 0, uint8_t keycode3 = 0, 
                uint8_t keycode4 = 0, uint8_t keycode5 = 0, uint8_t keycode6 = 0) {
  BT.write(0xFD);       // our command
  BT.write(modifiers);  // modifier!
  BT.write((byte)0x00); // 0x00  
  BT.write(keycode1);   // key code #1
  BT.write(keycode2); // key code #2
  BT.write(keycode3); // key code #3
  BT.write(keycode4); // key code #4
  BT.write(keycode5); // key code #5
  BT.write(keycode6); // key code #6
}

void rawkeytest() {
  // test sending a single 'a' (keycode 4)
  keyCommand(0, 4);
  delay(100);
  keyCommand(0, 0);
} 

/************** Support added in v1.1 */

void rawmousetest() {
  Serial.println("Move mouse!");
  Serial.println("Right");
  mouseCommand(0, -100, 0);
  delay(200); 
  Serial.println("Down");
  mouseCommand(0, 0, -100);  
  delay(200); 
  Serial.println("Left");
  mouseCommand(0, 100, 0);  
  delay(200); 
  Serial.println("Up");
  mouseCommand(0, 0, 100);  
  delay(200); 
}

void mouseCommand(uint8_t buttons, uint8_t x, uint8_t y) {
  BT.write(0xFD);
  BT.write((byte)0x00);
  BT.write((byte)0x03);
  BT.write(buttons);
  BT.write(x);
  BT.write(y);
  BT.write((byte)0x00);
  BT.write((byte)0x00);
  BT.write((byte)0x00);
}

/************** Support added in v1.1 */

void setup() {
  Serial.begin(9600);
  BT.begin(9600);

  Serial.println("Softserial/BT test!\n\rPress any key+return to start");
  while (! Serial.available());

  printabletest(); delay(200);
  //altkeystest();
  //nonprinting();
  //iphonekeyboard();
  //rawkeytest();

  //Supported in v1.1
  //rawmousetest();
}

void loop() {
  
}

Page last edited September 25, 2013

Text editor powered by tinymce.

 User Manual Remapping the Buttons (Serial) 
Related Guides
Bootloading Basics
By Bill Earl
27
Beginner
FTDI Friend
By lady ada
48
Beginner
DC & USB Boarduino Kits
By lady ada
22
Beginner
Home Automation in the Cloud with the ESP8266 &...
By M. Schwartz
176
Beginner
Trinket / Gemma IR Control
By Anne Barela
41
Beginner
Adafruit HUZZAH32 – ESP32 Breakout Board
By Kattni Rembor
23
Beginner
How to Find Hidden COM Ports
By lady ada
19
Beginner
Internet of Things Printer
By Phillip Burgess
32
Intermediate
Adafruit USB Power Gauge Mini-Kit
By Bill Earl
7
Beginner
XBee Radios
By lady ada
55
Beginner
CircuitPython Libraries on Linux and ODROID C2
By M. LeBlanc-Williams
4
Intermediate
Adafruit MENTA Kit
By lady ada
19
Beginner
Adafruit HUZZAH ESP8266 breakout
By lady ada
236
Intermediate
Building and Running MicroPython on the ESP8266
By Tony DiCola
45
Intermediate
Trinket Powered Analog Meter Clock
By Anne Barela
43
Beginner
Search

Search

Categories