12 files changed, 161 insertions, 35 deletions
diff --git a/docs/conf.py b/docs/conf.py
index fbc89afc6a..a737e43ef1 100755
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -99,7 +99,7 @@ copyright = '2014-2016, Damien P. George and contributors'
 # The short X.Y version.
 version = '1.8'
 # The full version, including alpha/beta/rc tags.
-release = '1.8.3'
+release = '1.8.4'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
diff --git a/docs/esp8266/quickref.rst b/docs/esp8266/quickref.rst
index 48543dfab6..d06fe5a6f1 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
 
@@ -162,17 +162,18 @@ Use the ``machine.ADC`` class::
     adc = ADC(0)            # create ADC object on ADC pin
     adc.read()              # read value, 0-1024
 
-SPI bus
--------
+Software SPI bus
+----------------
 
-The SPI driver is implemented in software and works on all pins::
+There are two SPI drivers. One is implemented in software (bit-banging)
+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
 
@@ -189,6 +190,21 @@ The SPI driver is implemented in software and works on all pins::
     spi.write_readinto(b'1234', buf) # write to MOSI and read from MISO into the buffer
     spi.write_readinto(buf, buf) # write buf to MOSI and read MISO back into buf
 
+
+Hardware SPI bus
+----------------
+
+The hardware SPI is faster (up to 80Mhz), but only works on following pins:
+``MISO`` is GPIO12, ``MOSI`` is GPIO13, and ``SCK`` is GPIO14. It has the same
+methods as the bitbanging SPI class above, except for the pin parameters for the
+constructor and init (as those are fixed)::
+
+    from machine import Pin, SPI
+
+    hspi = SPI(1, baudrate=80000000, polarity=0, phase=0)
+
+(``SPI(0)`` is used for FlashROM and not available to users.)
+
 I2C bus
 -------
 
@@ -239,15 +255,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/intro.rst b/docs/esp8266/tutorial/intro.rst
index 8c356b913f..32e9326b37 100644
--- a/docs/esp8266/tutorial/intro.rst
+++ b/docs/esp8266/tutorial/intro.rst
@@ -135,6 +135,10 @@ after it, here are troubleshooting recommendations:
   rate may be too high and lead to errors. Try a more common 115200 baud
   rate instead in such cases.
 
+* If lower baud rate didn't help, you may want to try older version of
+  esptool.py, which had a different programming algorithm::
+    pip install esptool==1.0.1
+
 * The ``--flash_size`` option in the commands above is mandatory. Omitting
   it will lead to a corrupted firmware.
 
diff --git a/docs/esp8266/tutorial/onewire.rst b/docs/esp8266/tutorial/onewire.rst
index c90044b7a8..c2cede9e38 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/esp8266/tutorial/pins.rst b/docs/esp8266/tutorial/pins.rst
index 639267d2ee..a44f40d3a7 100644
--- a/docs/esp8266/tutorial/pins.rst
+++ b/docs/esp8266/tutorial/pins.rst
@@ -14,7 +14,7 @@ Here, the "0" is the pin that you want to access.  Usually you want to
 configure the pin to be input or output, and you do this when constructing
 it.  To make an input pin use::
 
-    >>> pin = machine.Pin(0, machine.Pin.OUT, machine.Pin.PULL_UP)
+    >>> pin = machine.Pin(0, machine.Pin.IN, machine.Pin.PULL_UP)
 
 You can either use PULL_UP or None for the input pull-mode.  If it's
 not specified then it defaults to None, which is no pull resistor.
diff --git a/docs/library/machine.WDT.rst b/docs/library/machine.WDT.rst
index d7c801356e..1d79b4c4ed 100644
--- a/docs/library/machine.WDT.rst
+++ b/docs/library/machine.WDT.rst
@@ -14,6 +14,8 @@ Example usage::
     wdt = WDT(timeout=2000)  # enable it with a timeout of 2s
     wdt.feed()
 
+Availability of this class: pyboard, WiPy.
+
 Constructors
 ------------
 
diff --git a/docs/library/machine.rst b/docs/library/machine.rst
index 0f361a7cb7..46d8eea71f 100644
--- a/docs/library/machine.rst
+++ b/docs/library/machine.rst
@@ -125,7 +125,7 @@ Constants
 
     irq wake values
 
-.. data:: machine.POWER_ON
+.. data:: machine.PWRON_RESET
 .. data:: machine.HARD_RESET
 .. data:: machine.WDT_RESET
 .. data:: machine.DEEPSLEEP_RESET
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
diff --git a/docs/pyboard/quickref.rst b/docs/pyboard/quickref.rst
index 2a1429cb05..3d08ae9109 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 ac1de6e275..6f8831edb4 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.
diff --git a/docs/reference/isr_rules.rst b/docs/reference/isr_rules.rst
index b33e4dd6f2..23dcfd01f4 100644
--- a/docs/reference/isr_rules.rst
+++ b/docs/reference/isr_rules.rst
@@ -110,6 +110,19 @@ the flag. The memory allocation occurs in the main program code when the object
 The MicroPython library I/O methods usually provide an option to use a pre-allocated buffer. For
 example ``pyb.i2c.recv()`` can accept a mutable buffer as its first argument: this enables its use in an ISR.
 
+A means of creating an object without employing a class or globals is as follows:
+
+.. code:: python
+
+    def set_volume(t, buf=bytearray(3)):
+        buf[0] = 0xa5
+        buf[1] = t >> 4
+        buf[2] = 0x5a
+        return buf
+
+The compiler instantiates the default ``buf`` argument when the function is
+loaded for the first time (usually when the module it's in is imported).
+
 Use of Python objects
 ~~~~~~~~~~~~~~~~~~~~~
 
@@ -300,3 +313,20 @@ that access to the critical variables is denied. A simple example of a mutex may
 but only for the duration of eight machine instructions: the benefit of this approach is that other interrupts are
 virtually unaffected.
 
+Interrupts and the REPL
+~~~~~~~~~~~~~~~~~~~~~~~
+
+Interrupt handlers, such as those associated with timers, can continue to run
+after a program terminates.  This may produce unexpected results where you might
+have expected the object raising the callback to have gone out of scope.  For
+example on the Pyboard:
+
+.. code:: python
+
+    def bar():
+        foo = pyb.Timer(2, freq=4, callback=lambda t: print('.', end=''))
+
+    bar()
+
+This continues to run until the timer is explicitly disabled or the board is
+reset with ``ctrl D``.