adafruit_hid.keyboard.Keyboard

  • Author(s): Scott Shawcroft, Dan Halbert

class adafruit_hid.keyboard.Keyboard(devices: Sequence[usb_hid.Device], timeout: int = None)

Send HID keyboard reports.

Create a Keyboard object that will send keyboard HID reports.

Parameters:

timeout – Time in seconds to wait for USB to become ready before timing out. Defaults to None to wait indefinitely.

Devices can be a sequence of devices that includes a keyboard device or a keyboard device itself. A device is any object that implements send_report(), usage_page and usage.

LED_CAPS_LOCK = 2

LED Usage ID for Caps Lock

LED_COMPOSE = 8

LED Usage ID for Compose

LED_NUM_LOCK = 1

LED Usage ID for Num Lock

LED_SCROLL_LOCK = 4

LED Usage ID for Scroll Lock

led_on(led_code: int) bool

Returns whether an LED is on based on the led code

Examples:

import usb_hid
from adafruit_hid.keyboard import Keyboard
from adafruit_hid.keycode import Keycode
import time

# Initialize Keyboard
kbd = Keyboard(usb_hid.devices)

# Press and release CapsLock.
kbd.press(Keycode.CAPS_LOCK)
time.sleep(.09)
kbd.release(Keycode.CAPS_LOCK)

# Check status of the LED_CAPS_LOCK
print(kbd.led_on(Keyboard.LED_CAPS_LOCK))
property led_status: bytes

Returns the last received report

press(*keycodes: int) None

Send a report indicating that the given keys have been pressed.

Parameters:

keycodes – Press these keycodes all at once.

Raises:

ValueError – if more than six regular keys are pressed.

Keycodes may be modifiers or regular keys. No more than six regular keys may be pressed simultaneously.

Examples:

from adafruit_hid.keycode import Keycode

# Press ctrl-x.
kbd.press(Keycode.LEFT_CONTROL, Keycode.X)

# Or, more conveniently, use the CONTROL alias for LEFT_CONTROL:
kbd.press(Keycode.CONTROL, Keycode.X)

# Press a, b, c keys all at once.
kbd.press(Keycode.A, Keycode.B, Keycode.C)
release(*keycodes: int) None

Send a USB HID report indicating that the given keys have been released.

Parameters:

keycodes – Release these keycodes all at once.

If a keycode to be released was not pressed, it is ignored.

Example:

# release SHIFT key
kbd.release(Keycode.SHIFT)
release_all() None

Release all pressed keys.

send(*keycodes: int) None

Press the given keycodes and then release all pressed keys.

Parameters:

keycodes – keycodes to send together

adafruit_hid.keycode.Keycode

  • Author(s): Scott Shawcroft, Dan Halbert

class adafruit_hid.keycode.Keycode

USB HID Keycode constants.

This list is modeled after the names for USB keycodes defined in https://usb.org/sites/default/files/hut1_21_0.pdf#page=83. This list does not include every single code, but does include all the keys on a regular PC or Mac keyboard.

Remember that keycodes are the names for key positions on a US keyboard, and may not correspond to the character that you mean to send if you want to emulate non-US keyboard. For instance, on a French keyboard (AZERTY instead of QWERTY), the keycode for ‘q’ is used to indicate an ‘a’. Likewise, ‘y’ represents ‘z’ on a German keyboard. This is historical: the idea was that the keycaps could be changed without changing the keycodes sent, so that different firmware was not needed for different variations of a keyboard.

A = 4

a and A

ALT = 226

Alias for LEFT_ALT; Alt is also known as Option (Mac)

APPLICATION = 101

also known as the Menu key (Windows)

Type:

Application

B = 5

b and B

BACKSLASH = 49

\ and |

BACKSPACE = 42

Delete backward (Backspace)

C = 6

c and C

CAPS_LOCK = 57

Caps Lock

COMMA = 54

, and <

COMMAND = 227

Labeled as Command on Mac keyboards, with a clover glyph

CONTROL = 224

Alias for LEFT_CONTROL

D = 7

d and D

DELETE = 76

Delete forward

DOWN_ARROW = 81

Move the cursor down

E = 8

e and E

EIGHT = 37

8 and *

END = 77

End (often moves to end of line)

ENTER = 40

Enter (Return)

EQUALS = 46

=` and ``+

ESCAPE = 41

Escape

F = 9

f and F

F1 = 58

Function key F1

F10 = 67

Function key F10

F11 = 68

Function key F11

F12 = 69

Function key F12

F13 = 104

Function key F13 (Mac)

F14 = 105

Function key F14 (Mac)

F15 = 106

Function key F15 (Mac)

F16 = 107

Function key F16 (Mac)

F17 = 108

Function key F17 (Mac)

F18 = 109

Function key F18 (Mac)

F19 = 110

Function key F19 (Mac)

F2 = 59

Function key F2

F20 = 111

Function key F20

F21 = 112

Function key F21

F22 = 113

Function key F22

F23 = 114

Function key F23

F24 = 115

Function key F24

F3 = 60

Function key F3

F4 = 61

Function key F4

F5 = 62

Function key F5

F6 = 63

Function key F6

F7 = 64

Function key F7

F8 = 65

Function key F8

F9 = 66

Function key F9

FIVE = 34

5 and %

FORWARD_SLASH = 56

/ and ?

FOUR = 33

4 and $

G = 10

g and G

GRAVE_ACCENT = 53

` and ~

GUI = 227

Alias for LEFT_GUI; GUI is also known as the Windows key, Command (Mac), or Meta

H = 11

h and H

HOME = 74

Home (often moves to beginning of line)

I = 12

i and I

INSERT = 73

Insert

J = 13

j and J

K = 14

k and K

KEYPAD_ASTERISK = 85

Keypad *

KEYPAD_BACKSLASH = 100

Keypad \ and | (Non-US)

KEYPAD_EIGHT = 96

Keypad 8 and Up Arrow

KEYPAD_ENTER = 88

Keypad Enter

KEYPAD_EQUALS = 103

Keypad = (Mac)

KEYPAD_FIVE = 93

Keypad 5

KEYPAD_FORWARD_SLASH = 84

Keypad /

KEYPAD_FOUR = 92

Keypad 4 and Left Arrow

KEYPAD_MINUS = 86

Keyapd -

KEYPAD_NINE = 97

Keypad 9 and PgUp

KEYPAD_NUMLOCK = 83

Num Lock (Clear on Mac)

KEYPAD_ONE = 89

Keypad 1 and End

KEYPAD_PERIOD = 99

Keypad . and Del

KEYPAD_PLUS = 87

Keypad +

KEYPAD_SEVEN = 95

Keypad 7 and Home

KEYPAD_SIX = 94

Keypad 6 and Right Arrow

KEYPAD_THREE = 91

Keypad 3 and PgDn

KEYPAD_TWO = 90

Keypad 2 and Down Arrow

KEYPAD_ZERO = 98

Keypad 0 and Ins

L = 15

l and L

LEFT_ALT = 226

Alt modifier left of the spacebar

LEFT_ARROW = 80

Move the cursor left

LEFT_BRACKET = 47

[ and {

LEFT_CONTROL = 224

Control modifier left of the spacebar

LEFT_GUI = 227

GUI modifier left of the spacebar

LEFT_SHIFT = 225

Shift modifier left of the spacebar

M = 16

m and M

MINUS = 45

-` and ``_

N = 17

n and N

NINE = 38

9 and (

O = 18

o and O

ONE = 30

1 and !

OPTION = 226

Labeled as Option on some Mac keyboards

P = 19

p and P

PAGE_DOWN = 78

Go forward one page

PAGE_UP = 75

Go back one page

PAUSE = 72

Pause (Break)

PERIOD = 55

. and >

POUND = 50

# and ~ (Non-US keyboard)

POWER = 102

Power (Mac)

PRINT_SCREEN = 70

Print Screen (SysRq)

Q = 20

q and Q

QUOTE = 52

' and "

R = 21

r and R

RETURN = 40

Alias for ENTER

RIGHT_ALT = 230

Alt modifier right of the spacebar

RIGHT_ARROW = 79

Move the cursor right

RIGHT_BRACKET = 48

] and }

RIGHT_CONTROL = 228

Control modifier right of the spacebar

RIGHT_GUI = 231

GUI modifier right of the spacebar

RIGHT_SHIFT = 229

Shift modifier right of the spacebar

S = 22

s and S

SCROLL_LOCK = 71

Scroll Lock

SEMICOLON = 51

; and :

SEVEN = 36

7 and &

SHIFT = 225

Alias for LEFT_SHIFT

SIX = 35

6 and ^

SPACE = 44

Alias for SPACEBAR

SPACEBAR = 44

Spacebar

T = 23

t and T

TAB = 43

Tab and Backtab

THREE = 32

3 and #

TWO = 31

2 and @

U = 24

u and U

UP_ARROW = 82

Move the cursor up

V = 25

v and V

W = 26

w and W

WINDOWS = 227

Labeled with a Windows logo on Windows keyboards

X = 27

x and X

Y = 28

y and Y

Z = 29

z and Z

ZERO = 39

0 and )

classmethod modifier_bit(keycode: int) int

Return the modifer bit to be set in an HID keycode report if this is a modifier key; otherwise return 0.

adafruit_hid.keyboard_layout_us.KeyboardLayoutUS

  • Author(s): Dan Halbert

adafruit_hid.keyboard_layout_us.KeyboardLayout

alias of KeyboardLayoutUS

class adafruit_hid.keyboard_layout_us.KeyboardLayoutUS(keyboard: Keyboard)

Map ASCII characters to appropriate keypresses on a standard US PC keyboard.

Non-ASCII characters and most control characters will raise an exception.

Specify the layout for the given keyboard.

Parameters:

keyboard – a Keyboard object. Write characters to this keyboard when requested.

Example:

kbd = Keyboard(usb_hid.devices)
layout = KeyboardLayout(kbd)
ALTGR_FLAG = 128

Bit set in the combined keys table if altgr is required for the first key.

ASCII_TO_KEYCODE = b'\x00\x00\x00\x00\x00\x00\x00\x00*+(\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00)\x00\x00\x00\x00,\x9e\xb4\xa0\xa1\xa2\xa44\xa6\xa7\xa5\xae6-78\'\x1e\x1f !"#$%&\xb33\xb6.\xb7\xb8\x9f\x84\x85\x86\x87\x88\x89\x8a\x8b\x8c\x8d\x8e\x8f\x90\x91\x92\x93\x94\x95\x96\x97\x98\x99\x9a\x9b\x9c\x9d/10\xa3\xad5\x04\x05\x06\x07\x08\t\n\x0b\x0c\r\x0e\x0f\x10\x11\x12\x13\x14\x15\x16\x17\x18\x19\x1a\x1b\x1c\x1d\xaf\xb1\xb0\xb5L'

Bytes string of keycodes for low ASCII characters, indexed by the ASCII value. Keycodes use the SHIFT_FLAG if needed. Dead keys are excluded by assigning the keycode 0.

COMBINED_KEYS = {}

Dictionary of characters (indexed by ord() value) that can be accessed by typing first a dead key followed by a regular key, like ñ as ~ + n. The value is a 2-bytes int: the high byte is the dead-key keycode (including SHIFT_FLAG), the low byte is the ascii code of the second character, with ALTGR_FLAG set if the dead key (the first key) needs ALTGR.

The combined-key codes bits are: 0b SDDD DDDD AKKK KKKK: S is the shift flag for the first key, DDD DDDD is the keycode for the first key, A is the altgr flag for the first key, KKK KKKK is the (low) ASCII code for the second character.

HIGHER_ASCII = {}

Dictionary that associates the ord() int value of high ascii and utf8 characters to their keycode. Keycodes use the SHIFT_FLAG if needed.

NEED_ALTGR = ''

Characters in ASCII_TO_KEYCODE and HIGHER_ASCII that need the ALTGR key pressed to type.

RIGHT_ALT_CODE = 230

The ALTGR keycode, to avoid dependency to the Keycode class.

SHIFT_CODE = 225

The SHIFT keycode, to avoid dependency to the Keycode class.

SHIFT_FLAG = 128

Bit set in any keycode byte if the shift key is required for the character.

keycodes(char: str) Tuple[int, ...]

Return a tuple of keycodes needed to type the given character.

Parameters:

char (str of length one.) – A single UTF8 character in a string.

Returns:

tuple of Keycode keycodes.

Raises:

ValueError – if there is no keycode for char.

Examples:

# Returns (Keycode.TAB,)
keycodes('  ')
# Returns (Keycode.A,)
keycode('a')
# Returns (Keycode.SHIFT, Keycode.A)
keycode('A')
# Raises ValueError with a US layout because it's an unknown character
keycode('é')
write(string: str, delay: float = None) None

Type the string by pressing and releasing keys on my keyboard.

Parameters:
  • string – A string of UTF-8 characters to convert to key presses and send.

  • delay (float) – Optional delay in seconds between key presses.

Raises:

ValueError – if any of the characters has no keycode (such as some control characters).

Example:

# Write abc followed by Enter to the keyboard
layout.write('abc\n')

adafruit_hid.keyboard_layout_base.KeyboardLayoutBase

  • Author(s): Dan Halbert, AngainorDev, Neradoc

class adafruit_hid.keyboard_layout_base.KeyboardLayoutBase(keyboard: Keyboard)

Base class for keyboard layouts. Uses the tables defined in the subclass to map UTF-8 characters to appropriate keypresses.

Non-supported characters and most control characters will raise an exception.

Specify the layout for the given keyboard.

Parameters:

keyboard – a Keyboard object. Write characters to this keyboard when requested.

Example:

kbd = Keyboard(usb_hid.devices)
layout = KeyboardLayout(kbd)
ALTGR_FLAG = 128

Bit set in the combined keys table if altgr is required for the first key.

ASCII_TO_KEYCODE = ()

Bytes string of keycodes for low ASCII characters, indexed by the ASCII value. Keycodes use the SHIFT_FLAG if needed. Dead keys are excluded by assigning the keycode 0.

COMBINED_KEYS = {}

Dictionary of characters (indexed by ord() value) that can be accessed by typing first a dead key followed by a regular key, like ñ as ~ + n. The value is a 2-bytes int: the high byte is the dead-key keycode (including SHIFT_FLAG), the low byte is the ascii code of the second character, with ALTGR_FLAG set if the dead key (the first key) needs ALTGR.

The combined-key codes bits are: 0b SDDD DDDD AKKK KKKK: S is the shift flag for the first key, DDD DDDD is the keycode for the first key, A is the altgr flag for the first key, KKK KKKK is the (low) ASCII code for the second character.

HIGHER_ASCII = {}

Dictionary that associates the ord() int value of high ascii and utf8 characters to their keycode. Keycodes use the SHIFT_FLAG if needed.

NEED_ALTGR = ''

Characters in ASCII_TO_KEYCODE and HIGHER_ASCII that need the ALTGR key pressed to type.

RIGHT_ALT_CODE = 230

The ALTGR keycode, to avoid dependency to the Keycode class.

SHIFT_CODE = 225

The SHIFT keycode, to avoid dependency to the Keycode class.

SHIFT_FLAG = 128

Bit set in any keycode byte if the shift key is required for the character.

keycodes(char: str) Tuple[int, ...]

Return a tuple of keycodes needed to type the given character.

Parameters:

char (str of length one.) – A single UTF8 character in a string.

Returns:

tuple of Keycode keycodes.

Raises:

ValueError – if there is no keycode for char.

Examples:

# Returns (Keycode.TAB,)
keycodes('  ')
# Returns (Keycode.A,)
keycode('a')
# Returns (Keycode.SHIFT, Keycode.A)
keycode('A')
# Raises ValueError with a US layout because it's an unknown character
keycode('é')
write(string: str, delay: float = None) None

Type the string by pressing and releasing keys on my keyboard.

Parameters:
  • string – A string of UTF-8 characters to convert to key presses and send.

  • delay (float) – Optional delay in seconds between key presses.

Raises:

ValueError – if any of the characters has no keycode (such as some control characters).

Example:

# Write abc followed by Enter to the keyboard
layout.write('abc\n')

adafruit_hid.mouse.Mouse

  • Author(s): Dan Halbert

class adafruit_hid.mouse.Mouse(devices: Sequence[usb_hid.Device], timeout: int = None)

Send USB HID mouse reports.

Create a Mouse object that will send USB mouse HID reports.

Parameters:

timeout – Time in seconds to wait for USB to become ready before timing out. Defaults to None to wait indefinitely.

Devices can be a sequence of devices that includes a keyboard device or a keyboard device itself. A device is any object that implements send_report(), usage_page and usage.

BACK_BUTTON = 8

Back mouse button.

FORWARD_BUTTON = 16

Forward mouse button.

LEFT_BUTTON = 1

Left mouse button.

MIDDLE_BUTTON = 4

Middle mouse button.

RIGHT_BUTTON = 2

Right mouse button.

click(buttons: int) None

Press and release the given mouse buttons.

Parameters:

buttons – a bitwise-or’d combination of LEFT_BUTTON, MIDDLE_BUTTON, and RIGHT_BUTTON.

Examples:

# Click the left button.
m.click(Mouse.LEFT_BUTTON)

# Double-click the left button.
m.click(Mouse.LEFT_BUTTON)
m.click(Mouse.LEFT_BUTTON)
move(x: int = 0, y: int = 0, wheel: int = 0) None

Move the mouse and turn the wheel as directed.

Parameters:
  • x – Move the mouse along the x axis. Negative is to the left, positive is to the right.

  • y – Move the mouse along the y axis. Negative is upwards on the display, positive is downwards.

  • wheel – Rotate the wheel this amount. Negative is toward the user, positive is away from the user. The scrolling effect depends on the host.

Examples:

# Move 100 to the left. Do not move up and down. Do not roll the scroll wheel.
m.move(-100, 0, 0)
# Same, with keyword arguments.
m.move(x=-100)

# Move diagonally to the upper right.
m.move(50, 20)
# Same.
m.move(x=50, y=-20)

# Roll the mouse wheel away from the user.
m.move(wheel=1)
press(buttons: int) None

Press the given mouse buttons.

Parameters:

buttons – a bitwise-or’d combination of LEFT_BUTTON, MIDDLE_BUTTON, and RIGHT_BUTTON.

Examples:

# Press the left button.
m.press(Mouse.LEFT_BUTTON)

# Press the left and right buttons simultaneously.
m.press(Mouse.LEFT_BUTTON | Mouse.RIGHT_BUTTON)
release(buttons: int) None

Release the given mouse buttons.

Parameters:

buttons – a bitwise-or’d combination of LEFT_BUTTON, MIDDLE_BUTTON, and RIGHT_BUTTON.

release_all() None

Release all the mouse buttons.

adafruit_hid.consumer_control.ConsumerControl

  • Author(s): Dan Halbert

class adafruit_hid.consumer_control.ConsumerControl(devices: Sequence[usb_hid.Device], timeout: int = None)

Send ConsumerControl code reports, used by multimedia keyboards, remote controls, etc.

Create a ConsumerControl object that will send Consumer Control Device HID reports.

Parameters:

timeout – Time in seconds to wait for USB to become ready before timing out. Defaults to None to wait indefinitely.

Devices can be a sequence of devices that includes a Consumer Control device or a CC device itself. A device is any object that implements send_report(), usage_page and usage.

press(consumer_code: int) None

Send a report to indicate that the given key has been pressed. Only one consumer control action can be pressed at a time, so any one that was previously pressed will be released.

Parameters:

consumer_code – a 16-bit consumer control code.

Examples:

from adafruit_hid.consumer_control_code import ConsumerControlCode

# Raise volume for 0.5 seconds
consumer_control.press(ConsumerControlCode.VOLUME_INCREMENT)
time.sleep(0.5)
consumer_control.release()
release() None

Send a report indicating that the consumer control key has been released. Only one consumer control key can be pressed at a time.

Examples:

from adafruit_hid.consumer_control_code import ConsumerControlCode

# Raise volume for 0.5 seconds
consumer_control.press(ConsumerControlCode.VOLUME_INCREMENT)
time.sleep(0.5)
consumer_control.release()
send(consumer_code: int) None

Send a report to do the specified consumer control action, and then stop the action (so it will not repeat).

Parameters:

consumer_code – a 16-bit consumer control code.

Examples:

from adafruit_hid.consumer_control_code import ConsumerControlCode

# Raise volume.
consumer_control.send(ConsumerControlCode.VOLUME_INCREMENT)

# Advance to next track (song).
consumer_control.send(ConsumerControlCode.SCAN_NEXT_TRACK)

adafruit_hid.consumer_control_code.ConsumerControlCode

  • Author(s): Dan Halbert

class adafruit_hid.consumer_control_code.ConsumerControlCode

USB HID Consumer Control Device constants.

This list includes a few common consumer control codes from https://www.usb.org/sites/default/files/hut1_21_0.pdf#page=118.

BRIGHTNESS_DECREMENT = 112

Decrease Brightness

BRIGHTNESS_INCREMENT = 111

Increase Brightness

EJECT = 184

Eject

FAST_FORWARD = 179

Fast Forward

MUTE = 226

Mute

PLAY_PAUSE = 205

Play/Pause toggle

RECORD = 178

Record

REWIND = 180

Rewind

SCAN_NEXT_TRACK = 181

Skip to next track

SCAN_PREVIOUS_TRACK = 182

Go back to previous track

STOP = 183

Stop

VOLUME_DECREMENT = 234

Decrease volume

VOLUME_INCREMENT = 233

Increase volume