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
 5
 6import board
 7import digitalio
 8import usb_hid
 9
10from adafruit_hid.mouse import Mouse
11
12mouse = Mouse(usb_hid.devices)
13
14# define buttons. these can be any physical switches/buttons, but the values
15# here work out-of-the-box with a CircuitPlayground Express' A and B buttons.
16up = digitalio.DigitalInOut(board.D4)
17up.direction = digitalio.Direction.INPUT
18up.pull = digitalio.Pull.DOWN
19
20down = digitalio.DigitalInOut(board.D5)
21down.direction = digitalio.Direction.INPUT
22down.pull = digitalio.Pull.DOWN
23
24while True:
25    # scroll up one unit (varies with host/OS)
26    if up.value:
27        mouse.move(wheel=1)
28
29    # scroll down one unit (varies with host/OS)
30    elif down.value:
31        mouse.move(wheel=-1)
32
33    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
 5
 6import board
 7import digitalio
 8import usb_hid
 9
10from adafruit_hid.keyboard import Keyboard
11from adafruit_hid.keycode import Keycode
12
13kbd = Keyboard(usb_hid.devices)
14
15# define buttons. these can be any physical switches/buttons, but the values
16# here work out-of-the-box with a CircuitPlayground Express' A and B buttons.
17swap = digitalio.DigitalInOut(board.D4)
18swap.direction = digitalio.Direction.INPUT
19swap.pull = digitalio.Pull.DOWN
20
21search = digitalio.DigitalInOut(board.D5)
22search.direction = digitalio.Direction.INPUT
23search.pull = digitalio.Pull.DOWN
24
25while True:
26    # press ALT+TAB to swap windows
27    if swap.value:
28        kbd.send(Keycode.ALT, Keycode.TAB)
29
30    # press CTRL+K, which in a web browser will open the search dialog
31    elif search.value:
32        kbd.send(Keycode.CONTROL, Keycode.K)
33
34    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
 5
 6import board
 7import digitalio
 8import usb_hid
 9
10from adafruit_hid.keyboard import Keyboard
11from adafruit_hid.keyboard_layout_us import KeyboardLayoutUS
12
13keyboard = Keyboard(usb_hid.devices)
14layout = KeyboardLayoutUS(keyboard)
15
16
17# define buttons. these can be any physical switches/buttons, but the values
18# here work out-of-the-box with a CircuitPlayground Express' A and B buttons.
19slow_write = digitalio.DigitalInOut(board.D4)
20slow_write.direction = digitalio.Direction.INPUT
21slow_write.pull = digitalio.Pull.DOWN
22
23fast_write = digitalio.DigitalInOut(board.D5)
24fast_write.direction = digitalio.Direction.INPUT
25fast_write.pull = digitalio.Pull.DOWN
26
27while True:
28    # Write `Hello World!` slowly
29    if slow_write.value:
30        layout.write("Hello World!", delay=0.2)
31
32    # Write `Hello World!` normally
33    elif fast_write.value:
34        layout.write("Hello World!")
35
36    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 analogio
10import board
11import digitalio
12import usb_hid
13from hid_gamepad import Gamepad
14
15gp = Gamepad(usb_hid.devices)
16
17# Create some buttons. The physical buttons are connected
18# to ground on one side and these and these pins on the other.
19button_pins = (board.D2, board.D3, board.D4, board.D5)
20
21# Map the buttons to button numbers on the Gamepad.
22# gamepad_buttons[i] will send that button number when buttons[i]
23# is pushed.
24gamepad_buttons = (1, 2, 8, 15)
25
26buttons = [digitalio.DigitalInOut(pin) for pin in button_pins]
27for button in buttons:
28    button.direction = digitalio.Direction.INPUT
29    button.pull = digitalio.Pull.UP
30
31# Connect an analog two-axis joystick to A4 and A5.
32ax = analogio.AnalogIn(board.A4)
33ay = analogio.AnalogIn(board.A5)
34
35
36# Equivalent of Arduino's map() function.
37def range_map(x, in_min, in_max, out_min, out_max):
38    return (x - in_min) * (out_max - out_min) // (in_max - in_min) + out_min
39
40
41while True:
42    # Buttons are grounded when pressed (.value = False).
43    for i, button in enumerate(buttons):
44        gamepad_button_num = gamepad_buttons[i]
45        if button.value:
46            gp.release_buttons(gamepad_button_num)
47            print(" release", gamepad_button_num, end="")
48        else:
49            gp.press_buttons(gamepad_button_num)
50            print(" press", gamepad_button_num, end="")
51
52    # Convert range[0, 65535] to -127 to 127
53    gp.move_joysticks(
54        x=range_map(ax.value, 0, 65535, -127, 127),
55        y=range_map(ay.value, 0, 65535, -127, 127),
56    )
57    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
17import usb_hid
18from adafruit_seesaw.seesaw import Seesaw
19from hid_gamepad import Gamepad
20from micropython import const
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
 5
 6import board
 7import digitalio
 8import usb_hid
 9
10from adafruit_hid.consumer_control import ConsumerControl
11from adafruit_hid.consumer_control_code import ConsumerControlCode
12
13cc = ConsumerControl(usb_hid.devices)
14
15# define buttons. these can be any physical switches/buttons, but the values
16# here work out-of-the-box with a FunHouse UP and DOWN buttons.
17button_up = digitalio.DigitalInOut(board.BUTTON_UP)
18button_up.switch_to_input(pull=digitalio.Pull.DOWN)
19
20button_down = digitalio.DigitalInOut(board.BUTTON_DOWN)
21button_down.switch_to_input(pull=digitalio.Pull.DOWN)
22
23while True:
24    if button_up.value:
25        print("Button up pressed!")
26        # send brightness up button press
27        cc.send(ConsumerControlCode.BRIGHTNESS_INCREMENT)
28
29    if button_down.value:
30        print("Button down pressed!")
31        # send brightness down button press
32        cc.send(ConsumerControlCode.BRIGHTNESS_DECREMENT)
33
34    time.sleep(0.1)