Merge remote-tracking branch 'micropython/master'

6 files changed, 107 insertions, 33 deletions

diff --git a/docs/esp8266/quickref.rst b/docs/esp8266/quickref.rst
index be58f9332..d20987136 100644
--- a/docs/esp8266/quickref.rst
+++ b/docs/esp8266/quickref.rst
@@ -23,14 +23,14 @@ Tab-completion is useful to find out what methods an object has.
 Paste mode (ctrl-E) is useful to paste a large slab of Python code into
 the REPL.
 
-The ``machine`` module::
+The :mod:`machine` module::
 
     import machine
 
     machine.freq()          # get the current frequency of the CPU
     machine.freq(160000000) # set the CPU frequency to 160 MHz
 
-The ``esp`` module::
+The :mod:`esp` module::
 
     import esp
 
@@ -40,7 +40,7 @@ The ``esp`` module::
 Networking
 ----------
 
-The ``network`` module::
+The :mod:`network` module::
 
     import network
 
@@ -69,13 +69,13 @@ A useful function for connecting to your local WiFi network is::
                 pass
         print('network config:', wlan.ifconfig())
 
-Once the network is established the ``socket`` module can be used
+Once the network is established the :mod:`socket <usocket>` module can be used
 to create and use TCP/UDP sockets as usual.
 
 Delay and timing
 ----------------
 
-Use the ``time`` module::
+Use the :mod:`time <utime>` module::
 
     import time
 
@@ -165,14 +165,14 @@ Use the ``machine.ADC`` class::
 SPI bus
 -------
 
-The SPI driver is implemented in software and works on all pins::
+There are two SPI drivers. One is implemented in software and works on all pins::
 
     from machine import Pin, SPI
 
     # construct an SPI bus on the given pins
     # polarity is the idle state of SCK
     # phase=0 means sample on the first edge of SCK, phase=1 means the second
-    spi = SPI(baudrate=100000, polarity=1, phase=0, sck=Pin(0), mosi=Pin(2), miso=Pin(4))
+    spi = SPI(-1, baudrate=100000, polarity=1, phase=0, sck=Pin(0), mosi=Pin(2), miso=Pin(4))
 
     spi.init(baudrate=200000) # set the baudrate
 
@@ -194,13 +194,13 @@ Hardware SPI
 ------------
 
 The hardware SPI is faster (up to 80Mhz), but only works on following pins:
-``MISO`` is gpio2, ``MOSI`` is gpio13, and ``SCK`` is gpio14. It has the same
+``MISO`` is gpio12, ``MOSI`` is gpio13, and ``SCK`` is gpio14. It has the same
 methods as SPI, except for the pin parameters for the constructor and init
 (as those are fixed).
 
-    from machine import Pin, HSPI
+    from machine import Pin, SPI
 
-    hspi = HSPI(baudrate=800000000, polarity=0, phase=0)
+    hspi = SPI(0, baudrate=80000000, polarity=0, phase=0)
 
 
 I2C bus
@@ -253,15 +253,14 @@ The OneWire driver is implemented in software and works on all pins::
     ow.scan()               # return a list of devices on the bus
     ow.reset()              # reset the bus
     ow.readbyte()           # read a byte
-    ow.read(5)              # read 5 bytes
     ow.writebyte(0x12)      # write a byte on the bus
     ow.write('123')         # write bytes on the bus
     ow.select_rom(b'12345678') # select a specific device by its ROM code
 
-There is a specific driver for DS18B20 devices::
+There is a specific driver for DS18S20 and DS18B20 devices::
 
-    import time
-    ds = onewire.DS18B20(ow)
+    import time, ds18x20
+    ds = ds18x20.DS18X20(ow)
     roms = ds.scan()
     ds.convert_temp()
     time.sleep_ms(750)
diff --git a/docs/esp8266/tutorial/onewire.rst b/docs/esp8266/tutorial/onewire.rst
index c90044b7a..c2cede9e3 100644
--- a/docs/esp8266/tutorial/onewire.rst
+++ b/docs/esp8266/tutorial/onewire.rst
@@ -6,19 +6,19 @@ The 1-wire bus is a serial bus that uses just a single wire for communication
 is a very popular 1-wire device, and here we show how to use the onewire module
 to read from such a device.
 
-For the following code to work you need to have at least one DS18B20 temperature
+For the following code to work you need to have at least one DS18S20 or DS18B20 temperature
 sensor with its data line connected to GPIO12.  You must also power the sensors
 and connect a 4.7k Ohm resistor between the data pin and the power pin.  ::
 
     import time
     import machine
-    import onewire
+    import onewire, ds18x20
 
     # the device is on GPIO12
     dat = machine.Pin(12)
 
     # create the onewire object
-    ds = onewire.DS18B20(onewire.OneWire(dat))
+    ds = ds18x20.DS18X20(onewire.OneWire(dat))
 
     # scan for devices on the bus
     roms = ds.scan()
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
diff --git a/docs/pyboard/quickref.rst b/docs/pyboard/quickref.rst
index 2a1429cb0..3d08ae910 100644
--- a/docs/pyboard/quickref.rst
+++ b/docs/pyboard/quickref.rst
@@ -3,6 +3,12 @@
 Quick reference for the pyboard
 ===============================
 
+The below pinout is for PYBv1.0.  You can also view pinouts for
+other versions of the pyboard:
+`PYBv1.1 <http://micropython.org/resources/pybv11-pinout.jpg>`__
+or `PYBLITEv1.0-AC <http://micropython.org/resources/pyblitev10ac-pinout.jpg>`__
+or `PYBLITEv1.0 <http://micropython.org/resources/pyblitev10-pinout.jpg>`__.
+
 .. image:: http://micropython.org/resources/pybv10-pinout.jpg
     :alt: PYBv1.0 pinout
     :width: 700px
@@ -14,14 +20,25 @@ See :mod:`pyb`. ::
 
     import pyb
 
-    pyb.delay(50) # wait 50 milliseconds
-    pyb.millis() # number of milliseconds since bootup
     pyb.repl_uart(pyb.UART(1, 9600)) # duplicate REPL on UART(1)
     pyb.wfi() # pause CPU, waiting for interrupt
     pyb.freq() # get CPU and bus frequencies
     pyb.freq(60000000) # set CPU freq to 60MHz
     pyb.stop() # stop CPU, waiting for external interrupt
 
+Delay and timing
+----------------
+
+Use the :mod:`time <utime>` module::
+
+    import time
+
+    time.sleep(1)           # sleep for 1 second
+    time.sleep_ms(500)      # sleep for 500 milliseconds
+    time.sleep_us(10)       # sleep for 10 microseconds
+    start = time.ticks_ms() # get value of millisecond counter
+    delta = time.ticks_diff(start, time.ticks_ms()) # compute time difference
+
 LEDs
 ----
 
diff --git a/docs/pyboard/tutorial/usb_mouse.rst b/docs/pyboard/tutorial/usb_mouse.rst
index ac1de6e27..6f8831edb 100644
--- a/docs/pyboard/tutorial/usb_mouse.rst
+++ b/docs/pyboard/tutorial/usb_mouse.rst
@@ -13,23 +13,23 @@ will look something like this::
 
     import pyb
     #pyb.main('main.py') # main script to run after this one
-    #pyb.usb_mode('CDC+MSC') # act as a serial and a storage device
-    #pyb.usb_mode('CDC+HID') # act as a serial device and a mouse
+    #pyb.usb_mode('VCP+MSC') # act as a serial and a storage device
+    #pyb.usb_mode('VCP+HID') # act as a serial device and a mouse
 
 To enable the mouse mode, uncomment the last line of the file, to
 make it look like::
 
-    pyb.usb_mode('CDC+HID') # act as a serial device and a mouse
+    pyb.usb_mode('VCP+HID') # act as a serial device and a mouse
 
 If you already changed your ``boot.py`` file, then the minimum code it
 needs to work is::
 
     import pyb
-    pyb.usb_mode('CDC+HID')
+    pyb.usb_mode('VCP+HID')
 
-This tells the pyboard to configure itself as a CDC (serial) and HID
-(human interface device, in our case a mouse) USB device when it boots
-up.
+This tells the pyboard to configure itself as a VCP (Virtual COM Port,
+ie serial port) and HID (human interface device, in our case a mouse)
+USB device when it boots up.
 
 Eject/unmount the pyboard drive and reset it using the RST switch.
 Your PC should now detect the pyboard as a mouse!
@@ -41,7 +41,8 @@ To get the py-mouse to do anything we need to send mouse events to the PC.
 We will first do this manually using the REPL prompt.  Connect to your
 pyboard using your serial program and type the following::
 
-    >>> pyb.hid((0, 10, 0, 0))
+    >>> hid = pyb.USB_HID()
+    >>> hid.send((0, 10, 0, 0))
 
 Your mouse should move 10 pixels to the right!  In the command above you
 are sending 4 pieces of information: button status, x, y and scroll.  The
@@ -52,7 +53,7 @@ Let's make the mouse oscillate left and right::
     >>> import math
     >>> def osc(n, d):
     ...   for i in range(n):
-    ...     pyb.hid((0, int(20 * math.sin(i / 10)), 0, 0))
+    ...     hid.send((0, int(20 * math.sin(i / 10)), 0, 0))
     ...     pyb.delay(d)
     ...
     >>> osc(100, 50)
@@ -100,9 +101,10 @@ In ``main.py`` put the following code::
 
     switch = pyb.Switch()
     accel = pyb.Accel()
+    hid = pyb.USB_HID()
 
     while not switch():
-        pyb.hid((0, accel.x(), accel.y(), 0))
+        hid.send((0, accel.x(), accel.y(), 0))
         pyb.delay(20)
 
 Save your file, eject/unmount your pyboard drive, and reset it using the RST
@@ -112,7 +114,7 @@ the mouse around.  Try it out, and see if you can make the mouse stand still!
 Press the USR switch to stop the mouse motion.
 
 You'll note that the y-axis is inverted.  That's easy to fix: just put a
-minus sign in front of the y-coordinate in the ``pyb.hid()`` line above.
+minus sign in front of the y-coordinate in the ``hid.send()`` line above.
 
 Restoring your pyboard to normal
 --------------------------------
@@ -121,9 +123,9 @@ If you leave your pyboard as-is, it'll behave as a mouse everytime you plug
 it in.  You probably want to change it back to normal.  To do this you need
 to first enter safe mode (see above), and then edit the ``boot.py`` file.
 In the ``boot.py`` file, comment out (put a # in front of) the line with the
-``CDC+HID`` setting, so it looks like::
+``VCP+HID`` setting, so it looks like::
 
-    #pyb.usb_mode('CDC+HID') # act as a serial device and a mouse
+    #pyb.usb_mode('VCP+HID') # act as a serial device and a mouse
 
 Save your file, eject/unmount the drive, and reset the pyboard.  It is now
 back to normal operating mode.