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": "",
"name": "quax-circuitpython-hid",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "adafruit,hid,human,interface,device,keyboard,mouse,keycode,keypadhardware,micropython,circuitpython",
"author": "",
"author_email": "quaxalber <pypi@quaxalber.de>, Adafruit Industries <circuitpython@adafruit.com>",
"download_url": "https://files.pythonhosted.org/packages/c3/d8/9ce2f90554ecb9573c5205eceb3eb65327aa64c1925b65af0d813452770d/quax-circuitpython-hid-6.0.2.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.0.2",
"project_urls": {
"Homepage": "https://github.com/quaxalber/Adafruit_CircuitPython_HID"
},
"split_keywords": [
"adafruit",
"hid",
"human",
"interface",
"device",
"keyboard",
"mouse",
"keycode",
"keypadhardware",
"micropython",
"circuitpython"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "32e62600906d01bbb5d6e727d4d99eb22aecc02ddf941627c699b5bd99f57777",
"md5": "606d9318c3587aba3052f8d8d06a53ed",
"sha256": "58974c28a4ac68d6a6f8e790d29add3c01c9d35066bac9241a146c58aed8b143"
},
"downloads": -1,
"filename": "quax_circuitpython_hid-6.0.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "606d9318c3587aba3052f8d8d06a53ed",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 33557,
"upload_time": "2023-12-08T12:18:11",
"upload_time_iso_8601": "2023-12-08T12:18:11.836805Z",
"url": "https://files.pythonhosted.org/packages/32/e6/2600906d01bbb5d6e727d4d99eb22aecc02ddf941627c699b5bd99f57777/quax_circuitpython_hid-6.0.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "c3d89ce2f90554ecb9573c5205eceb3eb65327aa64c1925b65af0d813452770d",
"md5": "741fdced78f3b6bf71cb5f07a215803f",
"sha256": "04794a2e90f73d7b067451c5cbf6c5b175c5725707ba452b888e8f91b01e6149"
},
"downloads": -1,
"filename": "quax-circuitpython-hid-6.0.2.tar.gz",
"has_sig": false,
"md5_digest": "741fdced78f3b6bf71cb5f07a215803f",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 57472,
"upload_time": "2023-12-08T12:18:13",
"upload_time_iso_8601": "2023-12-08T12:18:13.864840Z",
"url": "https://files.pythonhosted.org/packages/c3/d8/9ce2f90554ecb9573c5205eceb3eb65327aa64c1925b65af0d813452770d/quax-circuitpython-hid-6.0.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-12-08 12:18:13",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "quaxalber",
"github_project": "Adafruit_CircuitPython_HID",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [],
"lcname": "quax-circuitpython-hid"
}
JSON
