1  
  2  Introduction
  3  ============
  4  
  5  .. image:: https://readthedocs.org/projects/adafruit-circuitpython-hid/badge/?version=latest
  6      :target: https://circuitpython.readthedocs.io/projects/hid/en/latest/
  7      :alt: Documentation Status
  8  
  9  .. image :: https://img.shields.io/discord/327254708534116352.svg
 10      :target: https://adafru.it/discord
 11      :alt: Discord
 12  
 13  .. image:: https://github.com/adafruit/Adafruit_CircuitPython_HID/workflows/Build%20CI/badge.svg
 14      :target: https://github.com/adafruit/Adafruit_CircuitPython_HID/actions/
 15      :alt: Build Status
 16  
 17  
 18  This driver simulates USB HID devices. Currently keyboard and mouse are implemented.
 19  
 20  Dependencies
 21  =============
 22  This driver depends on:
 23  
 24  * `Adafruit CircuitPython <https://github.com/adafruit/circuitpython>`_
 25  
 26  Please ensure all dependencies are available on the CircuitPython filesystem.
 27  This is easily achieved by downloading
 28  `the Adafruit library and driver bundle <https://github.com/adafruit/Adafruit_CircuitPython_Bundle>`_.
 29  
 30  Usage Example
 31  =============
 32  
 33  The ``Keyboard`` class sends keypress reports for a USB keyboard device to the host.
 34  
 35  The ``Keycode`` class defines USB HID keycodes to send using ``Keyboard``.
 36  
 37  .. code-block:: python
 38  
 39      import usb_hid
 40      from adafruit_hid.keyboard import Keyboard
 41      from adafruit_hid.keycode import Keycode
 42  
 43      # Set up a keyboard device.
 44      kbd = Keyboard(usb_hid.devices)
 45  
 46      # Type lowercase 'a'. Presses the 'a' key and releases it.
 47      kbd.send(Keycode.A)
 48  
 49      # Type capital 'A'.
 50      kbd.send(Keycode.SHIFT, Keycode.A)
 51  
 52      # Type control-x.
 53      kbd.send(Keycode.CONTROL, Keycode.X)
 54  
 55      # You can also control press and release actions separately.
 56      kbd.press(Keycode.CONTROL, Keycode.X)
 57      kbd.release_all()
 58  
 59      # Press and hold the shifted '1' key to get '!' (exclamation mark).
 60      kbd.press(Keycode.SHIFT, Keycode.ONE)
 61      # Release the ONE key and send another report.
 62      kbd.release(Keycode.ONE)
 63      # Press shifted '2' to get '@'.
 64      kbd.press(Keycode.TWO)
 65      # Release all keys.
 66      kbd.release_all()
 67  
 68  The ``KeyboardLayoutUS`` sends ASCII characters using keypresses. It assumes
 69  the host is set to accept keypresses from a US keyboard.
 70  
 71  If the host is expecting a non-US keyboard, the character to key mapping provided by
 72  ``KeyboardLayoutUS`` will not always be correct.
 73  Different keypresses will be needed in some cases. For instance, to type an ``'A'`` on
 74  a French keyboard (AZERTY instead of QWERTY), ``Keycode.Q`` should be pressed.
 75  
 76  Currently this package provides only ``KeyboardLayoutUS``. More ``KeyboardLayout``
 77  classes could be added to handle non-US keyboards and the different input methods provided
 78  by various operating systems.
 79  
 80  .. code-block:: python
 81  
 82      import usb_hid
 83      from adafruit_hid.keyboard import Keyboard
 84      from adafruit_hid.keyboard_layout_us import KeyboardLayoutUS
 85  
 86      kbd = Keyboard(usb_hid.devices)
 87      layout = KeyboardLayoutUS(kbd)
 88  
 89      # Type 'abc' followed by Enter (a newline).
 90      layout.write('abc\n')
 91  
 92      # Get the keycodes needed to type a '$'.
 93      # The method will return (Keycode.SHIFT, Keycode.FOUR).
 94      keycodes = layout.keycodes('$')
 95  
 96  The ``Mouse`` class simulates a three-button mouse with a scroll wheel.
 97  
 98  .. code-block:: python
 99  
100      import usb_hid
101      from adafruit_hid.mouse import Mouse
102  
103      m = Mouse(usb_hid.devices)
104  
105      # Click the left mouse button.
106      m.click(Mouse.LEFT_BUTTON)
107  
108      # Move the mouse diagonally to the upper left.
109      m.move(-100, -100, 0)
110  
111      # Roll the mouse wheel away from the user one unit.
112      # Amount scrolled depends on the host.
113      m.move(0, 0, -1)
114  
115      # Keyword arguments may also be used. Omitted arguments default to 0.
116      m.move(x=-100, y=-100)
117      m.move(wheel=-1)
118  
119      # Move the mouse while holding down the left button. (click-drag).
120      m.press(Mouse.LEFT_BUTTON)
121      m.move(x=50, y=20)
122      m.release_all()       # or m.release(Mouse.LEFT_BUTTON)
123  
124  The ``ConsumerControl`` class emulates consumer control devices such as
125  remote controls, or the multimedia keys on certain keyboards.
126  
127  *New in CircuitPython 3.0.*
128  
129  .. code-block:: python
130  
131      import usb_hid
132      from adafruit_hid.consumer_control import ConsumerControl
133      from adafruit_hid.consumer_control_code import ConsumerControlCode
134  
135      cc = ConsumerControl(usb_hid.devices)
136  
137      # Raise volume.
138      cc.send(ConsumerControlCode.VOLUME_INCREMENT)
139  
140      # Pause or resume playback.
141      cc.send(ConsumerControlCode.PLAY_PAUSE)
142  
143  The ``Gamepad`` class emulates a two-joystick gamepad with 16 buttons.
144  
145  *New in CircuitPython 3.0.*
146  
147  .. code-block:: python
148  
149      import usb_hid
150      from adafruit_hid.gamepad import Gamepad
151  
152      gp = Gamepad(usb_hid.devices)
153  
154      # Click gamepad buttons.
155      gp.click_buttons(1, 7)
156  
157      # Move joysticks.
158      gp.move_joysticks(x=2, y=0, z=-20)
159  
160  Contributing
161  ============
162  
163  Contributions are welcome! Please read our `Code of Conduct
164  <https://github.com/adafruit/Adafruit_CircuitPython_hid/blob/master/CODE_OF_CONDUCT.md>`_
165  before contributing to help this project stay welcoming.
166  
167  Documentation
168  =============
169  
170  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>`_.