USB HID with CircuitPython

What in the world is USB HID?

USB HID stands for Universal Serial Bus Human Interface Device. It basically means that you can use a microcontroller to act as a keyboard and mouse. This is useful as you can make your own custom input devices, like if you don’t remember your password, you can make a project so a button can be pressed to type your password. The possibilities are endless!

How to use it

Prerequisites

· ESP32-S2/ESP32-S3 microcontroller
·SAMD21/SAMD51 (often called M0 or M4) microcontroller (Adafruit Feather/QT Py/ ItsyBitsy/Trinket/Metro/Circuit Playground Express)
·ATmega32u4 Microcontroller (Arduino Leonardo, Arduino Micro, etc.)
·RP2040 Microcontroller (Raspberry Pi Pico, Adafruit Feather RP2040, Arduino Nano RP2040 Connect)

Follow the instructions to set up CircuitPython on your device Here.

Lets Code!

We can use some simple code from the documentation

Simulating a Keyboard

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

keyboard = Keyboard(usb_hid.devices)

This code is some standard boilerplate code. Now, we can use the keyboard object to press keys for us. For example, we can press the a key by using the keyboard.press() method:

keyboard.press(Keycode.A)
keyboard.release(Keycode.A)

or more simply-

keyboard.send(Keycode.A)

For the full list of keycodes, see here

For a project, let’s make a button that types out the password “hello123”. For this, we will wire up a button on pin 2. Connect one side of the button to pin 2 on your board and the other side to ground. When the button is pressed, we will send the password letter by letter using the keyboard.send() method. To test this, open notepad/textedit and press the button. You should see the password typed out.

from time import sleep
import digitalio
import board
import usb_hid
from adafruit_hid.keyboard import Keyboard
from adafruit_hid.keycode import Keycode

keyboard = Keyboard(usb_hid.devices)
button = digitalio.DigitalInOut(board.D2)
button.direction = digitalio.Direction.INPUT
button.pull = digitalio.Pull.UP

while True:
    if not button.value:
        if keyboard.led_on(Keyboard.LED_CAPS_LOCK):
            keyboard.send(Keycode.CAPS_LOCK)
        keyboard.send(Keycode.H, Keycode.E, Keycode.L, Keycode.L, Keycode.O, Keycode.ONE, Keycode.TWO, Keycode.THREE)
        sleep(0.5)
        keyboard.send(Keycode.ENTER)

This code basically waits for a button press and then checks if caps lock is on, and if it is, it disables it before typing the password.
This is just a simple example. Feel free to modify it to suit your needs!

Simulating a mouse

To simulate a mouse we will stil need some simple boilerplate-

import usb_hid
from adafruit_hid.mouse import Mouse

mouse = Mouse(usb_hid.devices)

Then, we can move the scroll wheel by one unit using

mouse.move(wheel=1)

or

mouse.move(wheel=-1)

Next, we can move the cursor vertically by 10 units and horizontally by 5 units by the x and y properties using

mouse.move(x=5, y=10)

Finally, we can left-click or right-click using the mouse.click() method.

mouse.click(Mouse.RIGHT_BUTTON)

# Double-click the left button.
mouse.click(Mouse.LEFT_BUTTON)
mouse.click(Mouse.LEFT_BUTTON)

Let’s make a scroller using 2 buttons to scroll up and down.

import time,board,digitalio,usb_hid
from adafruit_hid.mouse import Mouse
mouse = Mouse(usb_hid.devices)

up = digitalio.DigitalInOut(board.D4)
up.direction = digitalio.Direction.INPUT
up.pull = digitalio.Pull.DOWN

down = digitalio.DigitalInOut(board.D5)
down.direction = digitalio.Direction.INPUT
down.pull = digitalio.Pull.DOWN

while True:
    if up.value:
        mouse.move(wheel=1)
    elif down.value:
        mouse.move(wheel=-1)
    time.sleep(0.1)

Wire pin 4 and 5 to one side of 2 buttons, and the other side to VCC.

I hoped you liked my blog and will experiment with this cool technology!