arduino-libraries / keyboard

Keyboard Library for Arduino

This library allows an Arduino board with USB capabilities to act as a keyboard.

For more information about this library please visit us at https://www.arduino.cc/reference/en/language/functions/usb/keyboard/

License

Copyright (c) Arduino LLC. All right reserved.

This library is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 2.1 of the License, or (at your option) any later version.

This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public License along with this library; if not, write to the Free Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA

keyboard's Issues

Adding support for getting numlock/capslock/scrolllock states

I would like to keep ESP32-BLE-Keyboard compatible with the Keyboard library and now we're about to add support for retrieving the numlock, capslock and scrolllock states.
So I would like to agree on a set of methods that we try to implement in both libraries.

Would you be okay with a method called setLedChangeCallBack that would allow providing a callback function?

Keyboard.setLedChangeCallBack(KbdLedCb);

E.g.

#include <Keyboard.h>

void onKeyboardLedChange(KbdLeds *kbls)
{
  if (kbls->bmNumLock == HIGH)
     Seriel.println("Numlock On!");
  else
     Seriel.println("Numlock Off!");

  if (kbls->bmCapsLock == HIGH)
     Seriel.println("CapsLock On!");
  else
     Seriel.println("CapsLock Off!");

  if (kbls->bmScrollLock == HIGH)
     Seriel.println("ScrollLock On!");
  else
     Seriel.println("ScrollLock Off!");
}

void setup()
{
  Serial.begin(9600);
  Keyboard.begin();
  Keyboard.setLedChangeCallBack(KbdLedCb);
}

void loop()
{
}

and 3 methods to retrieve the states of the lock keys manually without a callback:

Keyboard.GetNumLockState();
Keyboard.GetCapsLockState();
Keyboard.GetScrollLockState();

e.g.

#include <Keyboard.h>

void setup()
{
  Serial.begin(9600);
  Keyboard.begin();
}

void loop()
{
  bool numLockState = Keyboard.GetNumLockState();
  bool capsLockState = Keyboard.GetCapsLockState();
  bool scrollLockState = Keyboard.GetScrollLockState();
  if (numLockState == HIGH)
     Seriel.println("Numlock On!");
  else
     Seriel.println("Numlock Off!");

  if (capsLockState == HIGH)
     Seriel.println("CapsLock On!");
  else
     Seriel.println("CapsLock Off!");

  if (scrollLockState == HIGH)
     Seriel.println("ScrollLock On!");
  else
     Seriel.println("ScrollLock Off!");
  delay(1000);
}

Maybe it would make more sense to use true/false instead of HIGH/LOW?
Or different names for the methods?

Just to clarify: I'm not asking you to actually implement this, I will try to do it once I find the time.

Analog reading

Is there a way to send a command to the pc with a scale of values?

Example:
send the key "B" with 50% intensity, or the key "A" with 25% intensity, resulting in the character in a game goes at 25% speed instead of alswais 100%

Race Conditions and Garbled Keyboard Output

I've noticed an issue that occurs on multiple boards, and all seem to produce the same issue.

While using Keyboard.println(), and while even printing manually, the text will become mangled at some point until the device is unplugged and re-plugged into the PC.

Here's an example sample of output:

hello world hello world hello world
hello world hello world hello world
hello world hello world hello world
hello world hello world hello world
hello world hello world hlelo world
hello world hello wrold hello wrold
hello world hello world hello world
hello world helol world hello world
hlelo world hello world ehllo world

I have tried adding delays with code such as this (to no avail):

for(int i = 0; i < text.length(); i++) {
  Keyboard.write(text[i]);
  delay(2);
}
Keyboard.write(0xB0);

I've also tried setting the delay between keypresses to something absurdly high (50ms), and I've tried calling Keyboard.end() and then Keyboard.begin() before the next entry. Nothing seems to help.

The only way to fix the keyboard is to re-connect the device to the PC, which can get pretty annoying. I assumed it was a race condition at first, but now I'm not sure. I recently bought some more boards, and tested them, and the issue persists. It seems to be even worse now, and re-plugging the device does not restore functionality (nor does re-flashing, which is a little scary).

Here's a sketch - keep pressing the button and eventually the sequence of ab will break:

#include <Keyboard.h>
#include "OneButton.h"

const String text = "abababababababababababababababababababababababababababababababababababababababababababababababababababababababab"

OneButton button(PIN_INPUT, true);

void enterText(String value) {
  Keyboard.println(value);
}

void singleClick() {
  enterText(text);
}

void setup() {
  Keyboard.begin();
  button.attachClick(singleClick);
  delay(1000);
}

void loop() {
  button.tick();
}

Only available for qwerty

This is infact a very useful library but it only works for qwerty keyboards. If you e.g. work with a qwertzu keyboard it fails at the special characters.

Allow retrieving Caps/Num/Scroll Lock Status

This patch applies (mostly) cleanly to the sources included with Arduino 1.8.13 and seems to work well for the purpose, while sporting a simple interface.

I think it should really be considered for inclusion upstream.

Modifier keys are set incorrectly on ::press() when _keyReport.keys is full.

If Keyboard.press() is called with a key that implies a modifier, when _keyReport.keys[] is full, the modifier bit will still be set on _keyReport.modifiers, but sendReport() never gets called for that key, leaving the modifier pressed but not reported until the next possible ::press(), which may or may not be after a ::release() that clears the modifier.

Also, if you ::press() two capital letters and ::release() one, the modifier will be cleared even though the second key is still pressed. Maybe there should be some documentation discouraging the use of ::press() with shifted keys? You shouldn't need them outside of string printing, which you should be using ::write() for anyway.

I was hoping I would have a chance to fix it so it doesn't set the modifier unless the key can be pressed, but I may not have time for a little while.

Using analog A6, A7 on Nano

The specification says that A6, A7 on Arduino Nano can only be used for analog inputs. Indeed, when I (not reading thoroughly the ATMEL spec) used A6, A7 as rows in Keypad setup, the whole sketch stopped to work (even reading from read digital inputs).

However if the HW provides pull-up resistors, even A6, A7 can be used as rows in the keypad matrix input, at the cost of some ifs in pin_mode etc. I'll prepare subclass of Keypad to allow for processing analog inputs.

How to print win key, ctrl, alt keys

I don't know how can I print windows key, control key, and alternate key.

Pressing both SHIFT and ALT-GR at the same time to type specific characters on MAC

I read in KeyboardLayout.h that it was not possible to use both SHIFT and ALT_GR on the same character.
I was trying to emulate a Backslash on a French Mac keyboard (normally typed by pressing Option+Shift+colon) and tried to modify the KeyboardLayout_fr_FR.cpp file by adding:
0x37|SHIFT|ALT_GR, // bslash
but obviously didn't work.
Is there another way to do this?

are imposible print a "@"

Hello
Please, confirm how this is possible , I try different ways with bad result .
thanks and regards

Keyboard.println does not send carriage return

Moved from arduino/Arduino#7026 by @marcspeth

Yesterday I updated from version 1.6.5 to version 1.8.5 and my project that uses an Arduino Leonardo to send text via keyboard output no longer sends carriage returns at the end of a PRINTLN command. (yes, using version 1.8.5 I added #include keyboard.h and #include mouse.h)

I also tried expressly sending a Carriage Return with Keyboard.print(13); and that does not send a Carriage Return either.

I then took the project back to version 1.6.5 (and commented out the #include keyboard.h and #include mouse.h ) and it compiles and works correctly once again.

when I use Keyboard.h, could I press keycode instead of keyASCII？

It is generally accepted that when the header file Keyboard.h is used, some control keys can be sent through the Keyboard.press (key) function. But for keys without ASCII values, such as KEYCODE_VOLUME_UP and KEYCODE_VOLUME_DOWN, how should they be sent to the host through arduino?

Keyboard.print() and Keyboard.println() do not reliably ouput uppercase characters

This code:

Keyboard.println("abcdefghijklmnopqrstuvwxyz");

Gives the expected output:

abcdefghijklmnopqrstuvwxyz

This code:

Keyboard.println("ABCDEFGHIJKLOMNPQRSTUVWXYZ");

Gives an output with some characters lower case, such as:

abCdEFGHIjklOMNPQRStUvwXYZ

or

aBcdeFGHIjKLOMNPQrsTuVWXYz

Sketch

#include "Keyboard.h"

void setup() {
  Keyboard.begin();
}

void loop() {
  Keyboard.print("abcdefghijklmnopqrstuvwxyz");
  delay(2000);
  Keyboard.print("ABCDEFGHIJKLONOPQRSTUVWXYZ");
  delay(2000);
}

uppercase keys change to lowercase equivalent when used over Remote Desktop Client

Keyboard.write("A"); works as expected, on local system.
However, when key is send over a Remote Desktop Client, it appears as "a". This behavior is consistent for all keys which use shift modifier "B" => "b", "+" => "=".
I see the problem on Windows 10, RDC talking to Windows Server 2012 R2
It does not happen when linux, xfreerdp is talking to Windows Server 2016.

For now the workaround is to send LEFT_SHIFT_MODIFIER separately

Keyboard.press(KEY_LEFT_SHIFT)
Keyboard.press("a");
Keyboard.releaseAll();

withdrawed

Wrong text on library.properties

Hi!

In the fifth line of library.properties says this:

For Leonardo/Micro only

I think that this text is wrong because this may work in another platforms.

If this is an outdated text, please update it. Else please explain me why this text is correct.

Best regards.

Helio.

Consider issuing a new release

The Keyboard library was last released on 2021-11-04 as 1.0.3. Since then, a few user-visible features have landed on master:

• support for the Swedish keyboard layout (#58)
• support for the Danish keyboard layout (#60)
• new generic KEY_* macros, completing the support of a full-size PC keyboard (#57)
• new layout-specific KEY_* macros, such as KEY_E_GRAVE on fr_FR and it_IT (#67).

Most users, including all who rely on the library manager, will not benefit from these features until a new release is rolled out. Would you please consider making a release now?

International keyboard

Could we get support for international keyboards? Or atleast a refactor witch would make it possible for the community to create there own keyboard layouts with support for multicharacters/special characters?

How i can create my own layout for my keyboard?

This can help a lot of people and maybe the people will stop making issues for add new languages...

In Italian Layout < and \ are swapped

Hardware:
The Atmega32u4 inside the WHID https://github.com/whid-injector/WHID

Software:
Arduino IDE 1.8.19
Keyboard Library 1.0.4

Simple test program:

#include "Keyboard.h"

void setup() {
  Serial.begin(9600);
  Keyboard.begin(KeyboardLayout_it_IT);
}

void loop() {
  if (Serial.available() > 0) {
    char inChar = Serial.read();
    Serial.print("hai inviato: ");
    Serial.println(inChar);
    Keyboard.write(inChar);
  }
}

Issue:
the character < is replaced with \ and viceversa
also > is replaced with |and viceversa

Fix?
edit the file in Documents/Arduino/libraries/Keyboard/src/KeyboardLayout_it_IT.cpp
replacing 0x32 with 0x35 and viceversa

I don't have another hardware for testing, i don't know if the problem is in the library or in the WHID.

LED status (Capslock, Numlock, Scrollock)

I was wondering if it would be possible to get the state of these flags from the OS?

I found a patch on this forum post: http://forum.arduino.cc/index.php?topic=173583.msg1474558#msg1474558
Its outdated, and I cant figure out how to send the data from HID -> Keyboard now that they are separate.

I was wondering if you had any ideas on how best to bridge the gap?
Should I just #include "Keyboard.h" inside HID.cpp, or should there be some callback you can register in HID, then Keyboard reads the message and decodes the LED status from there.

How to update the installed library to this version?

I'm trying to get a sketch working that will allow the f13-f24 keys working, but I can't get the library manager to update to this version of the files, if I try to add the zip of these files via "manage libraries" I get the error; "A library named Keyboard-master already exists".

I can't manually replace the default ones the IDE uses because that folder is protected by windows.

So, can I get the library manager to read these files as a valid update, or somehow tell the IDE to ignore the default libraries and read these ones instead? Or do I just need to wait for the IDE to update to these versions?

Currently using "Arduino 1.8.5 (Windows Store 1.8.10.0)"

Add GitHub Action based CI

Keyboard types "2n" instead of an apostrophe

Like the title says, when I write an apostrophe it types "2n". I cannot figure this out and it happens on other operating systems other than Mac.

F13- F24 keys not working

It will press f13-f24 but windows will not receive it

Add GitHub Actions workflow to synchronise with shared repository labels

Nano33 IoT

Hi,

Should this library (and Mouse) work on Nano33 IoT? It compiles and links fine but the USB device does not work at least on Windows. What I get is weird broken composite device with two CDC (COM port) devices.

I bought this board based on few articles in the Webs that state native-USB HID support. Maybe this was false information?
Looking closer I believe Arduino never claimed anywhere to support USB HID core on this specific board but it states here https://www.arduino.cc/reference/en/language/functions/usb/keyboard/ that "The keyboard functions enable 32u4 or SAMD micro based boards to send keystrokes to an attached computer through their micro’s native USB port."

Thank you!

ES LAYOUT NOT WORKING

After trying for long time and trying all the ideas that came to my head I havent been able to make the layout work. The keycode are mixed even when I configure then manually.


g)

Multiple language layout support

Hello,

I modified this library to support other keyboard layouts, I think that would be good merge this version.

I uploaded to: https://github.com/ernesto-xload/arduino_keyboardlib

Best regads

[Feature Request] Support for boot protocol

By now the library does not support boot protocol for keyboard which makes it impossible to use it on certain devices like KVM switches or in older pc bios.

This request might require additional changes in the used hid or usb libraries

numlock's code

hello,

how can i get numlock code? because in the modifier keys of Keyboard.h there isn't code of numlock

thank you.

support for SAMD11 (Arduino Nano Every)

Any chance the SAMD11 will be supported?
I bought the Every on a quick decision, since it stated compatibility as a HID device. But now I feel a bit cheated?
Thank you so much for considering

How to print bslash

hi, i'm trying to print bslash ( \ )

i have try many syntax but it not work, do you know what to forget?

#include <Keyboard.h>

char altKey = KEY_RIGHT_ALT;

void setup() {
  Keyboard.begin();
}

void loop() {
  delay(5000);
  Keyboard.press(altKey);
  Keyboard.press(38);
  delay(100);
  Keyboard.press(0x26);
  Keyboard.releaseAll();
  Keyboard.print("005C");
  Keyboard.write(92);
  Keyboard.write(0x5C);
  Keyboard.write(38);
  Keyboard.write(49);
  // wait for new window to open:
  delay(1000);
}

How to print Ctrl + E used as hot key to close Expert Advisor on Metatrader 4 Platform

I have been trying to use a fingerprint scanner to print Ctrl+E, which is a hot key set on an Expert Advisor on the Metatrader 4 platform. The hot key shuts the Expert Advisor down. I am able to manually press the ctrl key on my laptop keyboard and use my fingerprint to print 'E', and it closes the Expert Advisor down. Does anyone know what I can do so the fingerprint will trigger the Ctrl+E combination. I have looked on the Arduino site for references and tutorials. They haven't worked.

#include <Adafruit_Fingerprint.h>
#include<Keyboard.h>

 #define mySerial Serial1



Adafruit_Fingerprint finger = Adafruit_Fingerprint(&mySerial);

void setup()  
{
  Serial.begin(9600);
  while (!Serial);  // For Yun/Leo/Micro/Zero/...
  delay(100);
  Serial.println("fingertest");
  pinMode(2, INPUT);

  // set the data rate for the sensor serial port
  finger.begin(57600);
  delay(5);
  if (finger.verifyPassword()) {
    Serial.println("Found fingerprint sensor!");
  } else {
    Serial.println("Did not find fingerprint sensor :(");
    while (1) { delay(1); }
  }

  finger.getTemplateCount();
  Serial.println("Waiting for valid finger...");
  Keyboard.begin();
}

void loop()                     // run over and over again
{
  getFingerprintIDez();
  delay(50);            //don't ned to run this at full speed.
  digitalWrite(2, LOW);  //set red led on from the start
  //digitalWrite(11, LOW);
}

uint8_t getFingerprintID() {
  uint8_t p = finger.getImage();
  switch (p) {
    case FINGERPRINT_OK:
      Serial.println("Image taken");
      break;
    case FINGERPRINT_NOFINGER:
      Serial.println("No finger detected");
      return p;
    case FINGERPRINT_PACKETRECIEVEERR:
      Serial.println("Communication error");
      return p;
    case FINGERPRINT_IMAGEFAIL:
      Serial.println("Imaging error");
      return p;
    default:
      Serial.println("Unknown error");
      return p;
  }

  // OK success!

  p = finger.image2Tz();
  switch (p) {
    case FINGERPRINT_OK:
      Serial.println("Image converted");
      break;
    case FINGERPRINT_IMAGEMESS:
      Serial.println("Image too messy");
      return p;
    case FINGERPRINT_PACKETRECIEVEERR:
      Serial.println("Communication error");
      return p;
    case FINGERPRINT_FEATUREFAIL:
      Serial.println("Could not find fingerprint features");
      return p;
    case FINGERPRINT_INVALIDIMAGE:
      Serial.println("Could not find fingerprint features");
      return p;
    default:
      Serial.println("Unknown error");
      return p;
  }
  
  // OK converted!
  p = finger.fingerFastSearch();
  if (p == FINGERPRINT_OK) {
    Serial.println("Found a print match!");
  } else if (p == FINGERPRINT_PACKETRECIEVEERR) {
    Serial.println("Communication error");
    return p;
  } else if (p == FINGERPRINT_NOTFOUND) {
    Serial.println("Did not find a match");
    return p;
  } else {
    Serial.println("Unknown error");
    return p;
  }   
  
  // found a match!

  Serial.print("Found ID #"); Serial.print(finger.fingerID); 
  Serial.print(" with confidence of "); Serial.println(finger.confidence); 

  return finger.fingerID;
}

// returns -1 if failed, otherwise returns ID #
  int getFingerprintIDez() {
  uint8_t p = finger.getImage();
  if (p != FINGERPRINT_OK)  return -1;

  p = finger.image2Tz();
  if (p != FINGERPRINT_OK)  return -1;

  p = finger.fingerFastSearch();
  if (p != FINGERPRINT_OK)  return -1;
  
  // found a match!
    digitalWrite(2, LOW);
      delay(500);
   Keyboard.press(KEY_LEFT_CTRL);
   
   Keyboard.press('E');
      delay(1000);
      Keyboard.releaseAll();
 
  return finger.fingerID; 
}

Keyboard with modifier keys not working as expected

I am trying to make four buttons to act as modifiers (I'm on a Mac, so those are command, alt, control and shift). In my work, most of the time I use my left hand only to press these buttons on the keyboard and my right hand to draw on a tablet, use the mouse and type a single character. For instance command-alt-forwardslah or command-'plus sign'. You get the picture.
Due to an operation I will not be able to use my left hand for a while so I thought if I can use my feet to press the modifiers, I can still work with only my right hand.
My code is 'sort of' working. If I press one of the buttons, functions in the OS are modified as expected. Like selecting multiple items (shift or command key), right mouse click (control) and copy drag files (alt).
But pressing one (or multiple) key and a key on the (real) keyboard does not work. And that is the whole point of these buttons.
Is it at all possible what I am trying to achieve or is my code simply faulty?

  #include <Keyboard.h>

  const int cmndPin = 4;         // input pin for command button
  const int altPin = 5;         // input pin for alt button
  const int cntrlPin = 6;         // input pin for control button
  const int shiftPin = 7;       // input pin for shoft button
  const int disablePin = 8;         // input pin for disable button, just to be sure the keyboard function does not interfere with   reprogramming
  bool cmnd = false;
  bool cntrl = false;
  bool alt = false;
  bool shift = false;

  void setup() {
    // make the pushButton pin an input:
    pinMode(cmndPin, INPUT_PULLUP);
    pinMode(cntrlPin, INPUT_PULLUP);
    pinMode(altPin, INPUT_PULLUP);
    pinMode(shiftPin, INPUT_PULLUP);
    pinMode(disablePin, INPUT_PULLUP);
    // initialize control over the keyboard:
    Keyboard.begin();
  }

  void loop() {
    //check if we are in programming or keyboard mode
    int disableState = digitalRead(disablePin);
    // read the pushbuttons:
    if (disableState) {
      int cmndState = digitalRead(cmndPin);
      int cntrlState = digitalRead(cntrlPin);
      int altState = digitalRead(altPin);
      int shiftState = digitalRead(shiftPin);

    //if the command button is pressed send keypress to computer (left and right to see
    //if this solves my problem, but it does not) and set a flag to prevent repeating key-presses
    if (!cmndState && !cmnd) {
      Keyboard.press(KEY_LEFT_GUI);
      Keyboard.press(KEY_RIGHT_GUI);
      cmnd = true;
    }

    //if the command button is released, release the key-press and reset the flag. 
    if (cmndState && cmnd) {
      Keyboard.release(KEY_LEFT_GUI);
      Keyboard.release(KEY_RIGHT_GUI);
      cmnd = false;
    }

    if (!altState && !alt) {
      Keyboard.press(KEY_LEFT_ALT);
      Keyboard.press(KEY_RIGHT_ALT);
     alt = true;
    }

    if (altState && alt) {
      Keyboard.release(KEY_LEFT_ALT);
      Keyboard.release(KEY_RIGHT_ALT);
      alt = false;
    }
    if (!cntrlState && !cntrl) {
      Keyboard.press(KEY_LEFT_CTRL);
      Keyboard.press(KEY_RIGHT_CTRL);
      cntrl = true;
    }

    if (cntrlState && cntrl) {
      Keyboard.release(KEY_LEFT_CTRL);
      Keyboard.release(KEY_RIGHT_CTRL);
      cntrl = false;
    }
    if (!shiftState && !shift) {
      Keyboard.press(0x81);
      Keyboard.press(0x85);
      shift = true;
    }

    if (shiftState && shift) {
      Keyboard.release(0x81);
      Keyboard.release(0x85);
      shift = false;
    }

  }

}

Support for Portuguese (pt_PT) keyboard layout

Is support for layouts for other languages coming ?

Wrong key with keyboard.print

Hello,

I was trying some code with my ATmega32U4 and the Keyboard.h librarie, by adding and was asking me why by adding this line :

Keyboard.print("This pipe character : | ");

I'm getting this output for the pipe : µ

Thanks in advance

Keyboard.println unexpected behaviour

Moved from arduino/Arduino#6922 by @sterretje

When using Keyboard.println, one expects the cursor to go to beginning of the next line in the active window. This does not happen,

The description in the reference section states the below and technically that is correct

Sends a keystroke to a connected computer, followed by a newline and carriage return.

A note on the reference page would be useful. Workaround is to use Keyboard.print{"Hallo") followed by Keyboard.write(KEY_RETURN).

A bugfix would even be better ;-)

In case relevant:
Windows 8 64 bit, IDE 1.6.6 (so you can determine library version), tested with Notepad and Notepad++.

"Keyboard not found, Does your sketch include the line #include <Keyboard.h>"

How do I resolve this error on Arduino IDE.

I installed the library and do find it in Arduino IDE.

I'm unable to compile it for Arduino Uno.
This is on Mac OS - High Sierra 10.13.6
I want to use it for testing IR receiver hardware.

Issues with the library

Basically, when i run this sketch into my arduino, he just write "=", he dont write "a".

I just already tried:

*Modify "a" in >KeyboardLayout.cpp using the key code given for me at https://keycode.info/, and the arduino continue writing "="
*I tried run it in a Windows 10 and Ubuntu 20.04 and i got the same issue
*I tried other default layout, es_ES, return a ")"

I use the ABNT 2 Keyboard Layout(brazilian layout...)

I just trying to make this work like 6 hours, i just dont know what i can do more...apreciate any response

#include <Keyboard.h>

void setup() {
  Serial.begin(9600);
  Keyboard.begin();
}

void loop() {
  Keyboard.write("a");
  delay(5000);
}

No volume media key

Hello it's possible to add these fallowing keys ?

KEY_VOLUME_DOWN
KEY_VOLUME_UP
KEY_MUTE

thanks

where is the key of "space"?

now, there is only key_backspace, however there is no space(null key or blank key)