Metadata-Version: 2.1
Name: adafruit-circuitpython-hid
Version: 4.2.0
Summary: CircuitPython helper library for simulating HID devices.
Home-page: https://github.com/adafruit/Adafruit_CircuitPython_HID
Author: Adafruit Industries
Author-email: circuitpython@adafruit.com
License: MIT
Description: 
        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.
        
        *New in CircuitPython 3.0.*
        
        .. 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)
        
        The ``Gamepad`` class emulates a two-joystick gamepad with 16 buttons.
        
        *New in CircuitPython 3.0.*
        
        .. code-block:: python
        
            import usb_hid
            from adafruit_hid.gamepad import Gamepad
        
            gp = Gamepad(usb_hid.devices)
        
            # 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
        <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>`_.
        
Keywords: adafruit hid human interface device keyboard mouse keycode keypadhardware micropython circuitpython
Platform: UNKNOWN
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: System :: Hardware
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.4
Classifier: Programming Language :: Python :: 3.5
Description-Content-Type: text/x-rst
