`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

adafruit_hid.keyboard.Keyboard

adafruit_hid.keycode.Keycode

adafruit_hid.keyboard_layout_us.KeyboardLayoutUS

adafruit_hid.keyboard_layout_base.KeyboardLayoutBase

adafruit_hid.mouse.Mouse

adafruit_hid.consumer_control.ConsumerControl

adafruit_hid.consumer_control_code.ConsumerControlCode

`adafruit_hid.keyboard.Keyboard`

`adafruit_hid.keycode.Keycode`

`adafruit_hid.keyboard_layout_us.KeyboardLayoutUS`

`adafruit_hid.keyboard_layout_base.KeyboardLayoutBase`

`adafruit_hid.mouse.Mouse`

`adafruit_hid.consumer_control.ConsumerControl`

`adafruit_hid.consumer_control_code.ConsumerControlCode`