CircuitPython helper library for simulating HID devices.
Project description
Introduction
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.
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.
from adafruit_hid.keyboard import Keyboard
from adafruit_hid.keycode import Keycode
# Set up a keyboard device.
kbd = Keyboard()
# 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.
from adafruit_hid.keyboard import Keyboard
from adafruit_hid.keyboard_layout_us import KeyboardLayoutUS
kbd = Keyboard()
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.
from adafruit_hid.mouse import Mouse
m = Mouse()
# 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.
New in CircuitPython 3.0.
from adafruit_hid.consumer_control import ConsumerControl
from adafruit_hid.consumer_control_code import ConsumerControlCode
cc = ConsumerControl()
# Raise volume.
cc.send(ConsumerControlCode.VOLUME_INCREMENT)
# Pause or resume playback.
cc.send(ConsumerControlCode.PLAY_PAUSE)The Gamepad class emulates a two-joystick gamepad with 16 buttons.
New in CircuitPython 3.0.
from adafruit_hid.gamepad import Gamepad
gp = Gamepad()
# Click gamepad buttons.
gp.click_buttons(1, 7)
# Move joysticks.
gp.move_joysticks(x=2, y=0, z=-20)Contributing
Contributions are welcome! Please read our Code of Conduct before contributing to help this project stay welcoming.
Building locally
To build this library locally you’ll need to install the circuitpython-build-tools package.
python3 -m venv .env
source .env/bin/activate
pip install circuitpython-build-toolsOnce installed, make sure you are in the virtual environment:
source .env/bin/activateThen run the build:
circuitpython-build-bundles --filename_prefix adafruit-circuitpython-hid --library_location .Sphinx documentation
Sphinx is used to build the documentation based on rST files and comments in the code. First, install dependencies (feel free to reuse the virtual environment from above):
python3 -m venv .env
source .env/bin/activate
pip install Sphinx sphinx-rtd-themeNow, once you have the virtual environment activated:
cd docs
sphinx-build -E -W -b html . _build/htmlThis will output the documentation to docs/_build/html. Open the index.html in your browser to view them. It will also (due to -W) error out on any warning like Travis will. This is a good way to locally verify it will pass.
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
File details
Details for the file adafruit-circuitpython-hid-3.2.0.tar.gz.
File metadata
- Download URL: adafruit-circuitpython-hid-3.2.0.tar.gz
- Upload date:
- Size: 31.9 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/1.11.0 pkginfo/1.4.2 requests/2.19.1 setuptools/40.0.0 requests-toolbelt/0.8.0 tqdm/4.24.0 CPython/3.6.3
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 | 123e9ed56bbe398651d48aac468e33c17252e28d71f778541907797188ec7893 |
|
| MD5 | 62b4f909dd1a31fd9310532ad7362a26 |
|
| BLAKE2b-256 | 7557e121696176adf89265c496404040903e69c478b2174e98732ca202ef5596 |
