Simple test

Ensure your device works with this simple test.

examples/hid_simpletest.py
 1# SPDX-FileCopyrightText: 2021 ladyada for Adafruit Industries
 2# SPDX-License-Identifier: MIT
 3
 4import time
 5import board
 6import digitalio
 7import usb_hid
 8from adafruit_hid.mouse import Mouse
 9
10mouse = Mouse(usb_hid.devices)
11
12# define buttons. these can be any physical switches/buttons, but the values
13# here work out-of-the-box with a CircuitPlayground Express' A and B buttons.
14up = digitalio.DigitalInOut(board.D4)
15up.direction = digitalio.Direction.INPUT
16up.pull = digitalio.Pull.DOWN
17
18down = digitalio.DigitalInOut(board.D5)
19down.direction = digitalio.Direction.INPUT
20down.pull = digitalio.Pull.DOWN
21
22while True:
23    # scroll up one unit (varies with host/OS)
24    if up.value:
25        mouse.move(wheel=1)
26
27    # scroll down one unit (varies with host/OS)
28    elif down.value:
29        mouse.move(wheel=-1)
30
31    time.sleep(0.1)

Keyboard Shortcuts

Send ALT+Tab for swapping windows, and CTRL+K for searching in a browser.

examples/hid_keyboard_shortcuts.py
 1# SPDX-FileCopyrightText: 2021 ladyada for Adafruit Industries
 2# SPDX-License-Identifier: MIT
 3
 4import time
 5import board
 6import digitalio
 7import usb_hid
 8from adafruit_hid.keyboard import Keyboard
 9from adafruit_hid.keycode import Keycode
10
11kbd = Keyboard(usb_hid.devices)
12
13# define buttons. these can be any physical switches/buttons, but the values
14# here work out-of-the-box with a CircuitPlayground Express' A and B buttons.
15swap = digitalio.DigitalInOut(board.D4)
16swap.direction = digitalio.Direction.INPUT
17swap.pull = digitalio.Pull.DOWN
18
19search = digitalio.DigitalInOut(board.D5)
20search.direction = digitalio.Direction.INPUT
21search.pull = digitalio.Pull.DOWN
22
23while True:
24    # press ALT+TAB to swap windows
25    if swap.value:
26        kbd.send(Keycode.ALT, Keycode.TAB)
27
28    # press CTRL+K, which in a web browser will open the search dialog
29    elif search.value:
30        kbd.send(Keycode.CONTROL, Keycode.K)
31
32    time.sleep(0.1)

Keyboard Layout

While the Keyboard class itself provides easy way for sending key shortcuts, for writing more complex text you may want to use a KeyboardLayout and a .write() method.

It is also possible to adjust the typing speed by specifying delay between key presses.

examples/hid_keyboard_layout.py
 1# SPDX-FileCopyrightText: 2021 ladyada for Adafruit Industries
 2# SPDX-License-Identifier: MIT
 3
 4import time
 5import board
 6import digitalio
 7import usb_hid
 8
 9from adafruit_hid.keyboard import Keyboard
10from adafruit_hid.keyboard_layout_us import KeyboardLayoutUS
11
12keyboard = Keyboard(usb_hid.devices)
13layout = KeyboardLayoutUS(keyboard)
14
15
16# define buttons. these can be any physical switches/buttons, but the values
17# here work out-of-the-box with a CircuitPlayground Express' A and B buttons.
18slow_write = digitalio.DigitalInOut(board.D4)
19slow_write.direction = digitalio.Direction.INPUT
20slow_write.pull = digitalio.Pull.DOWN
21
22fast_write = digitalio.DigitalInOut(board.D5)
23fast_write.direction = digitalio.Direction.INPUT
24fast_write.pull = digitalio.Pull.DOWN
25
26while True:
27    # Write `Hello World!` slowly
28    if slow_write.value:
29        layout.write("Hello World!", delay=0.2)
30
31    # Write `Hello World!` normally
32    elif fast_write.value:
33        layout.write("Hello World!")
34
35    time.sleep(0.1)

Simple Gamepad

Send gamepad buttons and joystick to the host.

examples/hid_simple_gamepad.py
 1# SPDX-FileCopyrightText: 2021 ladyada for Adafruit Industries
 2# SPDX-License-Identifier: MIT
 3
 4# You must add a gamepad HID device inside your boot.py file
 5# in order to use this example.
 6# See this Learn Guide for details:
 7# https://learn.adafruit.com/customizing-usb-devices-in-circuitpython/hid-devices#custom-hid-devices-3096614-9
 8
 9import board
10import digitalio
11import analogio
12import usb_hid
13
14from hid_gamepad import Gamepad
15
16gp = Gamepad(usb_hid.devices)
17
18# Create some buttons. The physical buttons are connected
19# to ground on one side and these and these pins on the other.
20button_pins = (board.D2, board.D3, board.D4, board.D5)
21
22# Map the buttons to button numbers on the Gamepad.
23# gamepad_buttons[i] will send that button number when buttons[i]
24# is pushed.
25gamepad_buttons = (1, 2, 8, 15)
26
27buttons = [digitalio.DigitalInOut(pin) for pin in button_pins]
28for button in buttons:
29    button.direction = digitalio.Direction.INPUT
30    button.pull = digitalio.Pull.UP
31
32# Connect an analog two-axis joystick to A4 and A5.
33ax = analogio.AnalogIn(board.A4)
34ay = analogio.AnalogIn(board.A5)
35
36
37# Equivalent of Arduino's map() function.
38def range_map(x, in_min, in_max, out_min, out_max):
39    return (x - in_min) * (out_max - out_min) // (in_max - in_min) + out_min
40
41
42while True:
43    # Buttons are grounded when pressed (.value = False).
44    for i, button in enumerate(buttons):
45        gamepad_button_num = gamepad_buttons[i]
46        if button.value:
47            gp.release_buttons(gamepad_button_num)
48            print(" release", gamepad_button_num, end="")
49        else:
50            gp.press_buttons(gamepad_button_num)
51            print(" press", gamepad_button_num, end="")
52
53    # Convert range[0, 65535] to -127 to 127
54    gp.move_joysticks(
55        x=range_map(ax.value, 0, 65535, -127, 127),
56        y=range_map(ay.value, 0, 65535, -127, 127),
57    )
58    print(" x", ax.value, "y", ay.value)

HID Joywing

Use Joy FeatherWing to drive Gamepad.

examples/hid_joywing_gamepad.py
 1# SPDX-FileCopyrightText: 2021 ladyada for Adafruit Industries
 2# SPDX-License-Identifier: MIT
 3
 4# Use Joy FeatherWing to drive Gamepad.
 5# https://www.adafruit.com/product/3632
 6# https://learn.adafruit.com/joy-featherwing
 7
 8# You must add a gamepad HID device inside your boot.py file
 9# in order to use this example.
10# See this Learn Guide for details:
11# https://learn.adafruit.com/customizing-usb-devices-in-circuitpython/hid-devices#custom-hid-devices-3096614-9
12
13import time
14
15import board
16import busio
17from micropython import const
18from adafruit_seesaw.seesaw import Seesaw
19import usb_hid
20from hid_gamepad import Gamepad
21
22
23def range_map(value, in_min, in_max, out_min, out_max):
24    return (value - in_min) * (out_max - out_min) // (in_max - in_min) + out_min
25
26
27BUTTON_RIGHT = const(6)
28BUTTON_DOWN = const(7)
29BUTTON_LEFT = const(9)
30BUTTON_UP = const(10)
31BUTTON_SEL = const(14)
32button_mask = const(
33    (1 << BUTTON_RIGHT)
34    | (1 << BUTTON_DOWN)
35    | (1 << BUTTON_LEFT)
36    | (1 << BUTTON_UP)
37    | (1 << BUTTON_SEL)
38)
39
40i2c = busio.I2C(board.SCL, board.SDA)
41
42ss = Seesaw(i2c)
43
44ss.pin_mode_bulk(button_mask, ss.INPUT_PULLUP)
45
46last_game_x = 0
47last_game_y = 0
48
49g = Gamepad(usb_hid.devices)
50
51while True:
52    x = ss.analog_read(2)
53    y = ss.analog_read(3)
54
55    game_x = range_map(x, 0, 1023, -127, 127)
56    game_y = range_map(y, 0, 1023, -127, 127)
57    if last_game_x != game_x or last_game_y != game_y:
58        last_game_x = game_x
59        last_game_y = game_y
60        print(game_x, game_y)
61        g.move_joysticks(x=game_x, y=game_y)
62
63    buttons = (BUTTON_RIGHT, BUTTON_DOWN, BUTTON_LEFT, BUTTON_UP, BUTTON_SEL)
64    button_state = [False] * len(buttons)
65    for i, button in enumerate(buttons):
66        buttons = ss.digital_read_bulk(button_mask)
67        if not (buttons & (1 << button) and not button_state[i]):
68            g.press_buttons(i + 1)
69            print("Press", i + 1)
70            button_state[i] = True
71        elif button_state[i]:
72            g.release_buttons(i + 1)
73            print("Release", i + 1)
74            button_state[i] = False
75
76    time.sleep(0.01)

Consumer Control Brightness

Send brightness up and down consumer codes to the host.

examples/hid_consumer_control_brightness.py
 1# SPDX-FileCopyrightText: 2021 Tim C for Adafruit Industries
 2# SPDX-License-Identifier: MIT
 3
 4import time
 5import board
 6import digitalio
 7import usb_hid
 8from adafruit_hid.consumer_control import ConsumerControl
 9from adafruit_hid.consumer_control_code import ConsumerControlCode
10
11cc = ConsumerControl(usb_hid.devices)
12
13# define buttons. these can be any physical switches/buttons, but the values
14# here work out-of-the-box with a FunHouse UP and DOWN buttons.
15button_up = digitalio.DigitalInOut(board.BUTTON_UP)
16button_up.switch_to_input(pull=digitalio.Pull.DOWN)
17
18button_down = digitalio.DigitalInOut(board.BUTTON_DOWN)
19button_down.switch_to_input(pull=digitalio.Pull.DOWN)
20
21while True:
22    if button_up.value:
23        print("Button up pressed!")
24        # send brightness up button press
25        cc.send(ConsumerControlCode.BRIGHTNESS_INCREMENT)
26
27    if button_down.value:
28        print("Button down pressed!")
29        # send brightness down button press
30        cc.send(ConsumerControlCode.BRIGHTNESS_DECREMENT)
31
32    time.sleep(0.1)