Skip to main content

CircuitPython helper library for simulating HID devices.

Project description

Introduction

Documentation Status Discord Build Status Code Style: Ruff

This driver simulates USB HID devices. Currently keyboard and mouse are implemented.

Dependencies

This driver depends on:

Please ensure all dependencies are available on the CircuitPython filesystem. This is easily achieved by downloading the Adafruit library and driver bundle.

Additional Layouts

This library has an en-US layout. Please check out and expand the library from Neradoc for additional layouts.

Usage Example

The Keyboard class sends keypress reports for a USB keyboard device to the host.

The Keycode class defines USB HID keycodes to send using Keyboard.

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

# Set up a keyboard device.
kbd = Keyboard(usb_hid.devices)

# Type lowercase 'a'. Presses the 'a' key and releases it.
kbd.send(Keycode.A)

# Type capital 'A'.
kbd.send(Keycode.SHIFT, Keycode.A)

# Type control-x.
kbd.send(Keycode.CONTROL, Keycode.X)

# You can also control press and release actions separately.
kbd.press(Keycode.CONTROL, Keycode.X)
kbd.release_all()

# Press and hold the shifted '1' key to get '!' (exclamation mark).
kbd.press(Keycode.SHIFT, Keycode.ONE)
# Release the ONE key and send another report.
kbd.release(Keycode.ONE)
# Press shifted '2' to get '@'.
kbd.press(Keycode.TWO)
# Release all keys.
kbd.release_all()

The KeyboardLayoutUS sends ASCII characters using keypresses. It assumes the host is set to accept keypresses from a US keyboard.

If the host is expecting a non-US keyboard, the character to key mapping provided by KeyboardLayoutUS will not always be correct. Different keypresses will be needed in some cases. For instance, to type an 'A' on a French keyboard (AZERTY instead of QWERTY), Keycode.Q should be pressed.

Currently this package provides only KeyboardLayoutUS. More KeyboardLayout classes could be added to handle non-US keyboards and the different input methods provided by various operating systems.

import usb_hid
from adafruit_hid.keyboard import Keyboard
from adafruit_hid.keyboard_layout_us import KeyboardLayoutUS

kbd = Keyboard(usb_hid.devices)
layout = KeyboardLayoutUS(kbd)

# Type 'abc' followed by Enter (a newline).
layout.write('abc\n')

# Get the keycodes needed to type a '$'.
# The method will return (Keycode.SHIFT, Keycode.FOUR).
keycodes = layout.keycodes('$')

The Mouse class simulates a three-button mouse with a scroll wheel.

import usb_hid
from adafruit_hid.mouse import Mouse

m = Mouse(usb_hid.devices)

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

# Move the mouse diagonally to the upper left.
m.move(-100, -100, 0)

# Roll the mouse wheel away from the user one unit.
# Amount scrolled depends on the host.
m.move(0, 0, -1)

# Keyword arguments may also be used. Omitted arguments default to 0.
m.move(x=-100, y=-100)
m.move(wheel=-1)

# Move the mouse while holding down the left button. (click-drag).
m.press(Mouse.LEFT_BUTTON)
m.move(x=50, y=20)
m.release_all()       # or m.release(Mouse.LEFT_BUTTON)

The ConsumerControl class emulates consumer control devices such as remote controls, or the multimedia keys on certain keyboards.

import usb_hid
from adafruit_hid.consumer_control import ConsumerControl
from adafruit_hid.consumer_control_code import ConsumerControlCode

cc = ConsumerControl(usb_hid.devices)

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

# Pause or resume playback.
cc.send(ConsumerControlCode.PLAY_PAUSE)

Documentation

API documentation for this library can be found on Read the Docs.

For information on building library documentation, please check out this guide.

Contributing

Contributions are welcome! Please read our Code of Conduct before contributing to help this project stay welcoming.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

adafruit_circuitpython_hid-6.1.7.tar.gz (36.7 kB view details)

Uploaded Source

Built Distribution

adafruit_circuitpython_hid-6.1.7-py3-none-any.whl (18.5 kB view details)

Uploaded Python 3

File details

Details for the file adafruit_circuitpython_hid-6.1.7.tar.gz.

File metadata

File hashes

Hashes for adafruit_circuitpython_hid-6.1.7.tar.gz
Algorithm Hash digest
SHA256 f0693eefe32cae34a3690376308b96e7df20e2c48434828e82b0cf3838eeea85
MD5 417f9c532973e9960daca0544c2007b9
BLAKE2b-256 59d946deb406ff6375428cbf92ddae320d6c21e81d022cbc3421275a0f781aa8

See more details on using hashes here.

File details

Details for the file adafruit_circuitpython_hid-6.1.7-py3-none-any.whl.

File metadata

File hashes

Hashes for adafruit_circuitpython_hid-6.1.7-py3-none-any.whl
Algorithm Hash digest
SHA256 7d197959b59b28115cadac97215f48f93f76fe69f29c1083d23ba0032f8e118f
MD5 ab50fa1ac8c4d46f5d5b858feb0cceaa
BLAKE2b-256 8228cc0e9e835dcdd185e2ddf709a41c68613a5ec674e17fbda5381a4b87a7e9

See more details on using hashes here.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page