adafruit-circuitpython-hid


Nameadafruit-circuitpython-hid JSON
Version 5.0.1 PyPI version JSON
download
home_pagehttps://github.com/adafruit/Adafruit_CircuitPython_HID
SummaryCircuitPython helper library for simulating HID devices.
upload_time2021-05-31 19:36:15
maintainer
docs_urlNone
authorAdafruit Industries
requires_python
licenseMIT
keywords adafruit hid human interface device keyboard mouse keycode keypadhardware micropython circuitpython
VCS
bugtrack_url
requirements No requirements were recorded.
Travis-CI No Travis.
coveralls test coverage No coveralls.
            Introduction
============

.. image:: https://readthedocs.org/projects/adafruit-circuitpython-hid/badge/?version=latest
    :target: https://circuitpython.readthedocs.io/projects/hid/en/latest/
    :alt: Documentation Status

.. image :: https://img.shields.io/discord/327254708534116352.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


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>`_.

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)

Contributing
============

Contributions are welcome! Please read our `Code of Conduct
<https://github.com/adafruit/Adafruit_CircuitPython_hid/blob/master/CODE_OF_CONDUCT.md>`_
before contributing to help this project stay welcoming.

Documentation
=============

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>`_.
            

Raw data

            {
    "_id": null,
    "home_page": "https://github.com/adafruit/Adafruit_CircuitPython_HID",
    "name": "adafruit-circuitpython-hid",
    "maintainer": "",
    "docs_url": null,
    "requires_python": "",
    "maintainer_email": "",
    "keywords": "adafruit hid human interface device keyboard mouse keycode keypadhardware micropython circuitpython",
    "author": "Adafruit Industries",
    "author_email": "circuitpython@adafruit.com",
    "download_url": "https://files.pythonhosted.org/packages/30/f7/3ae86fb89d6a967890cdb0d6893f25b09b8b55c56cecc53c6ca4f096fb5d/adafruit-circuitpython-hid-5.0.1.tar.gz",
    "platform": "",
    "description": "Introduction\n============\n\n.. image:: https://readthedocs.org/projects/adafruit-circuitpython-hid/badge/?version=latest\n    :target: https://circuitpython.readthedocs.io/projects/hid/en/latest/\n    :alt: Documentation Status\n\n.. image :: https://img.shields.io/discord/327254708534116352.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\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\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\nContributing\n============\n\nContributions are welcome! Please read our `Code of Conduct\n<https://github.com/adafruit/Adafruit_CircuitPython_hid/blob/master/CODE_OF_CONDUCT.md>`_\nbefore contributing to help this project stay welcoming.\n\nDocumentation\n=============\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>`_.",
    "bugtrack_url": null,
    "license": "MIT",
    "summary": "CircuitPython helper library for simulating HID devices.",
    "version": "5.0.1",
    "split_keywords": [
        "adafruit",
        "hid",
        "human",
        "interface",
        "device",
        "keyboard",
        "mouse",
        "keycode",
        "keypadhardware",
        "micropython",
        "circuitpython"
    ],
    "urls": [
        {
            "comment_text": "",
            "digests": {
                "md5": "30c381c4d2e71ab34cb6055e122fcbf9",
                "sha256": "566f9e1e3a7ec25120b7a290ee2c4448aa6e0ab8c857d7bee1fc6d18e7a3b674"
            },
            "downloads": -1,
            "filename": "adafruit-circuitpython-hid-5.0.1.tar.gz",
            "has_sig": false,
            "md5_digest": "30c381c4d2e71ab34cb6055e122fcbf9",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": null,
            "size": 38432,
            "upload_time": "2021-05-31T19:36:15",
            "upload_time_iso_8601": "2021-05-31T19:36:15.897335Z",
            "url": "https://files.pythonhosted.org/packages/30/f7/3ae86fb89d6a967890cdb0d6893f25b09b8b55c56cecc53c6ca4f096fb5d/adafruit-circuitpython-hid-5.0.1.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2021-05-31 19:36:15",
    "github": true,
    "gitlab": false,
    "bitbucket": false,
    "github_user": null,
    "github_project": "adafruit",
    "error": "Could not fetch GitHub repository",
    "lcname": "adafruit-circuitpython-hid"
}
        
Elapsed time: 0.28413s