From 0f8b1ba8a2c3588f319f6b426aa07e97d2e17b24 Mon Sep 17 00:00:00 2001
From: Philip Potter <philip.g.potter@gmail.com>
Date: Sun, 28 Aug 2016 18:05:40 +0100
Subject: [PATCH] docs/library: Add reference for pyb.usb_mode and pyb.USB_HID.
---
docs/library/pyb.USB_HID.rst | 28 ++++++++++++++++++++++++++++
docs/library/pyb.rst | 30 +++++++++++++++++++++++++++++-
2 files changed, 57 insertions(+), 1 deletion(-)
create mode 100644 docs/library/pyb.USB_HID.rst
diff --git a/docs/library/pyb.USB_HID.rst b/docs/library/pyb.USB_HID.rst
new file mode 100644
index 000000000..65fb4014e
--- /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 2f3e7d36b..910b2f45b 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
--
GitLab