docs/library: Add reference for pyb.usb_mode and pyb.USB_HID.

2 files changed, 57 insertions, 1 deletions

diff --git a/docs/library/pyb.USB_HID.rst b/docs/library/pyb.USB_HID.rst
new file mode 100644
index 0000000000..65fb4014e0
--- /dev/null
+++ b/docs/library/pyb.USB_HID.rst
@@ -0,0 +1,28 @@
+.. currentmodule:: pyb
+
+class USB_HID -- USB Human Interface Device (HID)
+=================================================
+
+The USB_HID class allows creation of an object representing the USB
+Human Interface Device (HID) interface.  It can be used to emulate
+a peripheral such as a mouse or keyboard.
+
+Before you can use this class, you need to use :meth:`pyb.usb_mode()` to set the USB mode to include the HID interface.
+
+Constructors
+------------
+
+.. class:: pyb.USB_HID()
+
+   Create a new USB_HID object.
+
+
+Methods
+-------
+
+.. method:: USB_HID.send(data)
+
+   Send data over the USB HID interface:
+
+     - ``data`` is the data to send (a tuple/list of integers, or a
+       bytearray).
diff --git a/docs/library/pyb.rst b/docs/library/pyb.rst
index 2f3e7d36bd..910b2f45b4 100644
--- a/docs/library/pyb.rst
+++ b/docs/library/pyb.rst
@@ -188,7 +188,7 @@ Miscellaneous functions
        Takes a 4-tuple (or list) and sends it to the USB host (the PC) to
        signal a HID mouse-motion event.
     
-       .. note:: This function is deprecated.  Use pyb.USB_HID().send(...) instead.
+       .. note:: This function is deprecated.  Use :meth:`pyb.USB_HID.send()` instead.
     
     .. function:: info([dump_alloc_table])
     
@@ -254,6 +254,33 @@ Miscellaneous functions
     
        Returns a string of 12 bytes (96 bits), which is the unique ID of the MCU.
 
+.. function:: usb_mode([modestr], vid=0xf055, pid=0x9801, hid=pyb.hid_mouse)
+
+   If called with no arguments, return the current USB mode as a string.
+
+   If called with ``modestr`` provided, attempts to set USB mode.
+   This can only be done when called from ``boot.py`` before
+   :meth:`pyb.main()` has been called.  The following values of
+   ``modestr`` are understood:
+
+   - ``None``: disables USB
+   - ``'VCP'``: enable with VCP (Virtual COM Port) interface
+   - ``'VCP+MSC'``: enable with VCP and MSC (mass storage device class)
+   - ``'VCP+HID'``: enable with VCP and HID (human interface device)
+
+   For backwards compatibility, ``'CDC'`` is understood to mean
+   ``'VCP'`` (and similarly for ``'CDC+MSC'`` and ``'CDC+HID'``).
+
+   The ``vid`` and ``pid`` parameters allow you to specify the VID
+   (vendor id) and PID (product id).
+
+   If enabling HID mode, you may also specify the HID details by
+   passing the ``hid`` keyword parameter.  It takes a tuple of
+   (subclass, protocol, max packet length, polling interval, report
+   descriptor).  By default it will set appropriate values for a USB
+   mouse.  There is also a ``pyb.hid_keyboard`` constant, which is an
+   appropriate tuple for a USB keyboard.
+
 Classes
 -------
 
@@ -277,4 +304,5 @@ Classes
        pyb.Switch.rst
        pyb.Timer.rst
        pyb.UART.rst
+       pyb.USB_HID.rst
        pyb.USB_VCP.rst