Introduction
============
.. image:: https://readthedocs.org/projects/adafruit-circuitpython-hid/badge/?version=latest
:target: https://docs.circuitpython.org/projects/hid/en/latest/
:alt: Documentation Status
.. image:: https://raw.githubusercontent.com/adafruit/Adafruit_CircuitPython_Bundle/main/badges/adafruit_discord.svg
:target: https://adafru.it/discord
:alt: Discord
.. image:: https://github.com/adafruit/Adafruit_CircuitPython_HID/workflows/Build%20CI/badge.svg
:target: https://github.com/adafruit/Adafruit_CircuitPython_HID/actions/
:alt: Build Status
.. image:: https://img.shields.io/badge/code%20style-black-000000.svg
:target: https://github.com/psf/black
:alt: Code Style: Black
This driver simulates USB HID devices. Currently keyboard and mouse are implemented.
Dependencies
=============
This driver depends on:
* `Adafruit CircuitPython <https://github.com/adafruit/circuitpython>`_
Please ensure all dependencies are available on the CircuitPython filesystem.
This is easily achieved by downloading
`the Adafruit library and driver bundle <https://github.com/adafruit/Adafruit_CircuitPython_Bundle>`_.
Additional Layouts
====================
This library has an en-US layout. Please check out and expand `the library from Neradoc <https://github.com/Neradoc/Circuitpython_Keyboard_Layouts>`_ 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``.
.. code-block:: python
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.
.. code-block:: python
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.
.. code-block:: python
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.
.. code-block:: python
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 <https://docs.circuitpython.org/projects/hid/en/latest/>`_.
For information on building library documentation, please check out `this guide <https://learn.adafruit.com/creating-and-sharing-a-circuitpython-library/sharing-our-docs-on-readthedocs#sphinx-5-1>`_.
Contributing
============
Contributions are welcome! Please read our `Code of Conduct
<https://github.com/adafruit/Adafruit_CircuitPython_hid/blob/main/CODE_OF_CONDUCT.md>`_
before contributing to help this project stay welcoming.
Raw data
{
"_id": null,
"home_page": null,
"name": "adafruit-circuitpython-hid",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": "adafruit, hid, human, interface, device, keyboard, mouse, keycode, keypadhardware, micropython, circuitpython",
"author": null,
"author_email": "Adafruit Industries <circuitpython@adafruit.com>",
"download_url": "https://files.pythonhosted.org/packages/53/95/e8080df551fdc7984bdfcefde38f694b926ad120751f068d91990ee0b9d3/adafruit_circuitpython_hid-6.1.3.tar.gz",
"platform": null,
"description": "\nIntroduction\n============\n\n.. image:: https://readthedocs.org/projects/adafruit-circuitpython-hid/badge/?version=latest\n :target: https://docs.circuitpython.org/projects/hid/en/latest/\n :alt: Documentation Status\n\n.. image:: https://raw.githubusercontent.com/adafruit/Adafruit_CircuitPython_Bundle/main/badges/adafruit_discord.svg\n :target: https://adafru.it/discord\n :alt: Discord\n\n.. image:: https://github.com/adafruit/Adafruit_CircuitPython_HID/workflows/Build%20CI/badge.svg\n :target: https://github.com/adafruit/Adafruit_CircuitPython_HID/actions/\n :alt: Build Status\n\n.. image:: https://img.shields.io/badge/code%20style-black-000000.svg\n :target: https://github.com/psf/black\n :alt: Code Style: Black\n\n\nThis driver simulates USB HID devices. Currently keyboard and mouse are implemented.\n\nDependencies\n=============\nThis driver depends on:\n\n* `Adafruit CircuitPython <https://github.com/adafruit/circuitpython>`_\n\nPlease ensure all dependencies are available on the CircuitPython filesystem.\nThis is easily achieved by downloading\n`the Adafruit library and driver bundle <https://github.com/adafruit/Adafruit_CircuitPython_Bundle>`_.\n\nAdditional Layouts\n====================\nThis library has an en-US layout. Please check out and expand `the library from Neradoc <https://github.com/Neradoc/Circuitpython_Keyboard_Layouts>`_ for additional layouts.\n\nUsage Example\n=============\n\nThe ``Keyboard`` class sends keypress reports for a USB keyboard device to the host.\n\nThe ``Keycode`` class defines USB HID keycodes to send using ``Keyboard``.\n\n.. code-block:: python\n\n import usb_hid\n from adafruit_hid.keyboard import Keyboard\n from adafruit_hid.keycode import Keycode\n\n # Set up a keyboard device.\n kbd = Keyboard(usb_hid.devices)\n\n # Type lowercase 'a'. Presses the 'a' key and releases it.\n kbd.send(Keycode.A)\n\n # Type capital 'A'.\n kbd.send(Keycode.SHIFT, Keycode.A)\n\n # Type control-x.\n kbd.send(Keycode.CONTROL, Keycode.X)\n\n # You can also control press and release actions separately.\n kbd.press(Keycode.CONTROL, Keycode.X)\n kbd.release_all()\n\n # Press and hold the shifted '1' key to get '!' (exclamation mark).\n kbd.press(Keycode.SHIFT, Keycode.ONE)\n # Release the ONE key and send another report.\n kbd.release(Keycode.ONE)\n # Press shifted '2' to get '@'.\n kbd.press(Keycode.TWO)\n # Release all keys.\n kbd.release_all()\n\nThe ``KeyboardLayoutUS`` sends ASCII characters using keypresses. It assumes\nthe host is set to accept keypresses from a US keyboard.\n\nIf the host is expecting a non-US keyboard, the character to key mapping provided by\n``KeyboardLayoutUS`` will not always be correct.\nDifferent keypresses will be needed in some cases. For instance, to type an ``'A'`` on\na French keyboard (AZERTY instead of QWERTY), ``Keycode.Q`` should be pressed.\n\nCurrently this package provides only ``KeyboardLayoutUS``. More ``KeyboardLayout``\nclasses could be added to handle non-US keyboards and the different input methods provided\nby various operating systems.\n\n.. code-block:: python\n\n import usb_hid\n from adafruit_hid.keyboard import Keyboard\n from adafruit_hid.keyboard_layout_us import KeyboardLayoutUS\n\n kbd = Keyboard(usb_hid.devices)\n layout = KeyboardLayoutUS(kbd)\n\n # Type 'abc' followed by Enter (a newline).\n layout.write('abc\\n')\n\n # Get the keycodes needed to type a '$'.\n # The method will return (Keycode.SHIFT, Keycode.FOUR).\n keycodes = layout.keycodes('$')\n\nThe ``Mouse`` class simulates a three-button mouse with a scroll wheel.\n\n.. code-block:: python\n\n import usb_hid\n from adafruit_hid.mouse import Mouse\n\n m = Mouse(usb_hid.devices)\n\n # Click the left mouse button.\n m.click(Mouse.LEFT_BUTTON)\n\n # Move the mouse diagonally to the upper left.\n m.move(-100, -100, 0)\n\n # Roll the mouse wheel away from the user one unit.\n # Amount scrolled depends on the host.\n m.move(0, 0, -1)\n\n # Keyword arguments may also be used. Omitted arguments default to 0.\n m.move(x=-100, y=-100)\n m.move(wheel=-1)\n\n # Move the mouse while holding down the left button. (click-drag).\n m.press(Mouse.LEFT_BUTTON)\n m.move(x=50, y=20)\n m.release_all() # or m.release(Mouse.LEFT_BUTTON)\n\nThe ``ConsumerControl`` class emulates consumer control devices such as\nremote controls, or the multimedia keys on certain keyboards.\n\n.. code-block:: python\n\n import usb_hid\n from adafruit_hid.consumer_control import ConsumerControl\n from adafruit_hid.consumer_control_code import ConsumerControlCode\n\n cc = ConsumerControl(usb_hid.devices)\n\n # Raise volume.\n cc.send(ConsumerControlCode.VOLUME_INCREMENT)\n\n # Pause or resume playback.\n cc.send(ConsumerControlCode.PLAY_PAUSE)\n\nDocumentation\n=============\n\nAPI documentation for this library can be found on `Read the Docs <https://docs.circuitpython.org/projects/hid/en/latest/>`_.\n\nFor information on building library documentation, please check out `this guide <https://learn.adafruit.com/creating-and-sharing-a-circuitpython-library/sharing-our-docs-on-readthedocs#sphinx-5-1>`_.\n\nContributing\n============\n\nContributions are welcome! Please read our `Code of Conduct\n<https://github.com/adafruit/Adafruit_CircuitPython_hid/blob/main/CODE_OF_CONDUCT.md>`_\nbefore contributing to help this project stay welcoming.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "CircuitPython helper library for simulating HID devices.",
"version": "6.1.3",
"project_urls": {
"Homepage": "https://github.com/adafruit/Adafruit_CircuitPython_HID"
},
"split_keywords": [
"adafruit",
" hid",
" human",
" interface",
" device",
" keyboard",
" mouse",
" keycode",
" keypadhardware",
" micropython",
" circuitpython"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "14715639419de74f1b4f3d5794dc456d89e4e900c7317104d2e524f7b850a8da",
"md5": "cec72216a2c25a6c5d055b8bf4a43349",
"sha256": "31ae170b435c6f42f3ef5b3336b2feb06b27af7baac1e7dbcd866a707017688c"
},
"downloads": -1,
"filename": "adafruit_circuitpython_hid-6.1.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "cec72216a2c25a6c5d055b8bf4a43349",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 18634,
"upload_time": "2024-10-07T22:31:11",
"upload_time_iso_8601": "2024-10-07T22:31:11.433874Z",
"url": "https://files.pythonhosted.org/packages/14/71/5639419de74f1b4f3d5794dc456d89e4e900c7317104d2e524f7b850a8da/adafruit_circuitpython_hid-6.1.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "5395e8080df551fdc7984bdfcefde38f694b926ad120751f068d91990ee0b9d3",
"md5": "3af70ab9c5d71c5a2813e7ee19b20a40",
"sha256": "6f483830f98a1dddb3e2ef25300b8bb81f8eab0921c6da7ff8c4cf6d1a5f4e64"
},
"downloads": -1,
"filename": "adafruit_circuitpython_hid-6.1.3.tar.gz",
"has_sig": false,
"md5_digest": "3af70ab9c5d71c5a2813e7ee19b20a40",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 40020,
"upload_time": "2024-10-07T22:31:12",
"upload_time_iso_8601": "2024-10-07T22:31:12.356944Z",
"url": "https://files.pythonhosted.org/packages/53/95/e8080df551fdc7984bdfcefde38f694b926ad120751f068d91990ee0b9d3/adafruit_circuitpython_hid-6.1.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-10-07 22:31:12",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "adafruit",
"github_project": "Adafruit_CircuitPython_HID",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [],
"lcname": "adafruit-circuitpython-hid"
}
JSON
