tools/usb_gadget/keyboard_gadget.py

   1 # Copyright 2014 The Chromium Authors. All rights reserved.
   2 # Use of this source code is governed by a BSD-style license that can be
   3 # found in the LICENSE file.
   4
   5 """Implementation of a USB HID keyboard.
   6
   7 Two classes are provided by this module. The KeyboardFeature class implements
   8 the core functionality of a HID keyboard and can be included in any HID gadget.
   9 The KeyboardGadget class implements an example keyboard gadget.
  10 """
  11
  12 import struct
  13
  14 import hid_constants
  15 import hid_descriptors
  16 import hid_gadget
  17 import usb_constants
  18
  19
  20 class KeyboardFeature(hid_gadget.HidFeature):
  21   """HID feature implementation for a keyboard.
  22
  23   REPORT_DESC provides an example HID report descriptor for a device including
  24   this functionality.
  25   """
  26
  27   REPORT_DESC = hid_descriptors.ReportDescriptor(
  28       hid_descriptors.UsagePage(0x01),  # Generic Desktop
  29       hid_descriptors.Usage(0x06),  # Keyboard
  30       hid_descriptors.Collection(
  31           hid_constants.CollectionType.APPLICATION,
  32           hid_descriptors.UsagePage(0x07),  # Key Codes
  33           hid_descriptors.UsageMinimum(224),
  34           hid_descriptors.UsageMaximum(231),
  35           hid_descriptors.LogicalMinimum(0, force_length=1),
  36           hid_descriptors.LogicalMaximum(1),
  37           hid_descriptors.ReportSize(1),
  38           hid_descriptors.ReportCount(8),
  39           hid_descriptors.Input(hid_descriptors.Data,
  40                                 hid_descriptors.Variable,
  41                                 hid_descriptors.Absolute),
  42           hid_descriptors.ReportCount(1),
  43           hid_descriptors.ReportSize(8),
  44           hid_descriptors.Input(hid_descriptors.Constant),
  45           hid_descriptors.ReportCount(5),
  46           hid_descriptors.ReportSize(1),
  47           hid_descriptors.UsagePage(0x08),  # LEDs
  48           hid_descriptors.UsageMinimum(1),
  49           hid_descriptors.UsageMaximum(5),
  50           hid_descriptors.Output(hid_descriptors.Data,
  51                                  hid_descriptors.Variable,
  52                                  hid_descriptors.Absolute),
  53           hid_descriptors.ReportCount(1),
  54           hid_descriptors.ReportSize(3),
  55           hid_descriptors.Output(hid_descriptors.Constant),
  56           hid_descriptors.ReportCount(6),
  57           hid_descriptors.ReportSize(8),
  58           hid_descriptors.LogicalMinimum(0, force_length=1),
  59           hid_descriptors.LogicalMaximum(101),
  60           hid_descriptors.UsagePage(0x07),  # Key Codes
  61           hid_descriptors.UsageMinimum(0, force_length=1),
  62           hid_descriptors.UsageMaximum(101),
  63           hid_descriptors.Input(hid_descriptors.Data, hid_descriptors.Array)
  64       )
  65   )
  66
  67   def __init__(self):
  68     super(KeyboardFeature, self).__init__()
  69     self._modifiers = 0
  70     self._keys = [0, 0, 0, 0, 0, 0]
  71     self._leds = 0
  72
  73   def ModifierDown(self, modifier):
  74     self._modifiers |= modifier
  75     if self.IsConnected():
  76       self.SendReport(self.GetInputReport())
  77
  78   def ModifierUp(self, modifier):
  79     self._modifiers &= ~modifier
  80     if self.IsConnected():
  81       self.SendReport(self.GetInputReport())
  82
  83   def KeyDown(self, keycode):
  84     free = self._keys.index(0)
  85     self._keys[free] = keycode
  86     if self.IsConnected():
  87       self.SendReport(self.GetInputReport())
  88
  89   def KeyUp(self, keycode):
  90     free = self._keys.index(keycode)
  91     self._keys[free] = 0
  92     if self.IsConnected():
  93       self.SendReport(self.GetInputReport())
  94
  95   def GetInputReport(self):
  96     """Construct an input report.
  97
  98     See Device Class Definition for Human Interface Devices (HID) Version 1.11
  99     Appendix B.1.
 100
 101     Returns:
 102       A packed input report.
 103     """
 104     return struct.pack('BBBBBBBB', self._modifiers, 0, *self._keys)
 105
 106   def GetOutputReport(self):
 107     """Construct an output report.
 108
 109     See Device Class Definition for Human Interface Devices (HID) Version 1.11
 110     Appendix B.1.
 111
 112     Returns:
 113       A packed input report.
 114     """
 115     return struct.pack('B', self._leds)
 116
 117   def SetOutputReport(self, data):
 118     """Handle an output report.
 119
 120     See Device Class Definition for Human Interface Devices (HID) Version 1.11
 121     Appendix B.1.
 122
 123     Args:
 124       data: Report data.
 125
 126     Returns:
 127       True on success, None to stall the pipe.
 128     """
 129     if len(data) >= 1:
 130       self._leds, = struct.unpack('B', data)
 131     return True
 132
 133
 134 class KeyboardGadget(hid_gadget.HidGadget):
 135   """USB gadget implementation of a HID keyboard."""
 136
 137   def __init__(self, vendor_id=0x18D1, product_id=0xFF02):
 138     self._feature = KeyboardFeature()
 139     super(KeyboardGadget, self).__init__(
 140         report_desc=KeyboardFeature.REPORT_DESC,
 141         features={0: self._feature},
 142         packet_size=8,
 143         interval_ms=1,
 144         out_endpoint=True,
 145         vendor_id=usb_constants.VendorID.GOOGLE,
 146         product_id=usb_constants.ProductID.GOOGLE_KEYBOARD_GADGET,
 147         device_version=0x0100)
 148     self.AddStringDescriptor(1, 'Google Inc.')
 149     self.AddStringDescriptor(2, 'Keyboard Gadget')
 150
 151   def ModifierDown(self, modifier):
 152     self._feature.ModifierDown(modifier)
 153
 154   def ModifierUp(self, modifier):
 155     self._feature.ModifierUp(modifier)
 156
 157   def KeyDown(self, keycode):
 158     self._feature.KeyDown(keycode)
 159
 160   def KeyUp(self, keycode):
 161     self._feature.KeyUp(keycode)
 162
 163
 164 def RegisterHandlers():
 165   """Registers web request handlers with the application server."""
 166
 167   from tornado import web
 168
 169   class WebConfigureHandler(web.RequestHandler):
 170
 171     def post(self):
 172       server.SwitchGadget(KeyboardGadget())
 173
 174   class WebTypeHandler(web.RequestHandler):
 175
 176     def post(self):
 177       string = self.get_argument('string')
 178       for char in string:
 179         if char in hid_constants.KEY_CODES:
 180           code = hid_constants.KEY_CODES[char]
 181           server.gadget.KeyDown(code)
 182           server.gadget.KeyUp(code)
 183         elif char in hid_constants.SHIFT_KEY_CODES:
 184           code = hid_constants.SHIFT_KEY_CODES[char]
 185           server.gadget.ModifierDown(hid_constants.ModifierKey.L_SHIFT)
 186           server.gadget.KeyDown(code)
 187           server.gadget.KeyUp(code)
 188           server.gadget.ModifierUp(hid_constants.ModifierKey.L_SHIFT)
 189
 190   class WebPressHandler(web.RequestHandler):
 191
 192     def post(self):
 193       code = hid_constants.KEY_CODES[self.get_argument('key')]
 194       server.gadget.KeyDown(code)
 195       server.gadget.KeyUp(code)
 196
 197   import server
 198   server.app.add_handlers('.*$', [
 199       (r'/keyboard/configure', WebConfigureHandler),
 200       (r'/keyboard/type', WebTypeHandler),
 201       (r'/keyboard/press', WebPressHandler),
 202   ])