Merge tag 'v1.8.4' into parse-bytecode

Support for stream decompression in uzlib, and more ESP8266 features

This release includes some bug fixes, code clean-up, updates to the docs,
more tests, and various feature additions.  The uzlib module now supports
efficient stream decompression in the form of the uzlib.DecompIO class.
Freezing of bytecode now supports floats for the ESP8266 port, as well as
complex numbers for all ports.  The stmhal port has ADC working on L4
microcontrollers, fixed initialisation for DAC, and addition of the
machine.WDT class and machine.reset_cause function.

For the ESP8266 port Pin(16) now works as an input pin and the hardware
SPI peripheral is exposed as machine.SPI(1).  The os.umount function is
implemented and the port supports mounting of externally connected SD
cards.  The machine.WDT class is added, wlan.scan() is fixed to return all
access points, and there is support for DS18S20 devices.

py core:
- runtime: factor out exception raising helpers
- runtime: define mp_check_self(pred) helper macro
- objdict: get rid of asserts (remove/replace with mp_check_self())
- get rid of assert() in method argument checking functions
- objtuple: in tuple_cmp_helper, use mp_check_self instead of raising
- objstr: use mp_raise_{Type,Value}Error instead of mp_raise_msg
- obj.h: for obj reprs A,B,C use void* explicitly for mp_obj_t typedef
- mpconfigport.h: remove typedef of machine_ptr_t, it's no longer needed
- sequence: allow to use bignums as indices in slice objects
- stream.c: use mp_obj_get_type in mp_get_stream_raise
- gc: add MICROPY_GC_CONSERVATIVE_CLEAR option to always zero memory
- compile: don't compile assert statements when optimisations enabled
- modstruct: use more compact mp_raise_ValueError function
- emitglue: use more compact mp_raise_ValueError function
- rename struct mp_code_state to mp_code_state_t
- mkrules.mk: allow to override name of libmicropython.a
- mpprint: fail an assertion with unsupported format specifiers
- makeqstrdata.py: compute the qstr hash from bytes, not characters
- if str/bytes hash is 0 then explicitly compute it
- emitglue.c: provide mp_raw_code_load_file for any unix architecture
- add MICROPY_USE_INTERNAL_PRINTF option, defaults to enabled

extmod:
- modwebrepl: set_password(): raise exception for too long password
- uzlib/: update uzlib to v2.0: new API supporting stream decompression
- moduzlib: refactor to new stream-compatible uzlib 2.0 API
- uzlib/: update uzlib to v2.0.1: fixes for pedantic compiler warnings
- uzlib/: update uzlib to v2.0.2: consistently use stdint types
- modbtree: do CHECK_ERROR after __bt_seq()
- modubinascii: implement binascii.crc32
- modubinascii: make crc32() support configurable
- modframebuf: fix pixel accessor to return a 1-bit result
- add machine_spi with generic SPI C-protocol and helper methods
- modframebuf: fix fill and scroll when height not divisible by 8
- moduzlib: implement zlib stream decompressor class, DecompIO
- moduzlib: use mperrno.h for error constants
- modframebuf: include font from stmhal directory explicitly
- moduzlib: support wbits arg to DecompIO
- framebuf: add the xstep!=0 case to scroll() method

lib:
- utils/stdout_helpers: fix function signature to match py/mphal.h
- berkeley-db-1.xx: update to upstream, fixes MacOSX build
- utils/pyexec: qstr_pool_info() requires size_t* parameters

drivers:
- sdcard: port the SDCard driver to new machine API, with backwards
  compatibility for pyboard

tools:
- mpy-tool.py: support freezing float literals with obj-repr C
- mpy-tool.py: store qstr config values in global config object
- mpy-tool.py: compute the hash value for str/bytes objects
- mpy-tool.py: support freezing of complex numbers

tests:
- rename zlibd_decompress.py -> uzlib_decompress.py
- basics: add more tuple tests to improve coverage testing
- basics: add more list tests to improve coverage testing
- misc/non_compliant: add tests to improve coverage testing
- basics: add test for break from within try within a for-loop
- basics: add a test file for overriding special methods
- basics/special_methods: enable tests for extra special methods
- uzlib_decompress: actually test raw DEFLATE stream
- run-tests: disable thread/thread_lock4.py on Travis
- run-tests: disable thread/stress_heap.py when running on Travis
- cmdline: add test for -O option to check optimisation value
- extmod/vfs_fat_ramdisk: add tests for VFS.umount()
- run-tests: disable thread_gc1.py test on Travis
- unix/extra_coverage: add test for str/bytes with invalid hash
- extmod: add test for uzlib.DecompIO
- extmod: add a test for framebuf module, tested by coverage build
- extmod/uzlib_decompio: add zlib bitstream testcases
- extmod/framebuf1: add tests for scrolling in the x-direction
- run-tests: disable thread/stress_recurse.py test on Travis

unix port:
- mpconfigport.h: don't include stdio.h on MacOS
- when find'ing frozen files don't use extra slash, do follow symlinks

qemu-arm port:
- enable MICROPY_PY_ALL_SPECIAL_METHODS

stmhal port:
- boards: update STM32L476 pin defs to include ADC channels
- adc.c: get ADC working on STM32L4 MCUs
- fix timer capture/compare interrupt handling for TIM1 and TIM8
- remove obsolete code for special handling of TIM3 irq settings
- make ADC channel 16 available on L4 MCUs
- update pin print to print new constants
- modusocket: set self->nic to MP_OBJ_NULL after socket close
- update boot.py files to use VCP instead of CDC
- spi: factor out SPI transfer code to a single function
- spi: support new machine SPI methods in legacy SPI object
- add machine.WDT class
- set STM32F7DISC CPU Frequency to 216 MHz
- dac: fix DAC (re-)initialisation by resetting DMA
- wdt: implement keyword args to WDT constructor
- modmachine: implement machine.reset_cause() function, and consts
- machine.POWER_ON is renamed to machine.PWRON_RESET
- when find'ing frozen files don't use extra slash, do follow symlinks

cc3200 port:
- add machine.PWRON_RESET constant (machine.POWER_ON is now deprecated)

teensy port:
- fix execution of frozen boot.py and main.py

esp8266 port:
- fix reading of pin object for GPIO16; Pin(16) now works as an input
- PULL_UP is not supported on Pin(16), so raise an exception in this case
- enable support for all special methods
- modpybhspi: add a HSPI module for hardware SPI support
- modmachinespi: add a factory method for SoftSPI/HSPI
- esp_mphal: no longer disable watchdog on startup
- modpybrtc: use 64-bit arithmetic when computing alarm expiry
- hspi: enable duplex operation of hardware SPI
- modous: add os.umount method to unmount a filesystem
- modmachinewdt: implement machine.WDT class
- modules: split onewire.py into OneWire and DS18X20 driver
- modules/onewire: change onewire.read() to onewire.readinto()
- modules/ds18x20.py: add support for DS18S20 devices
- modpybspi: use generic SPI helper methods to implement SPI
- modpybhspi: simplify HSPI driver by using 1 function for xfers
- modmachinewdt: add .deinit() method
- modmachine: add WDT_RESET and SOFT_RESET constants
- modmachine: don't expose internal SoftSPI and HSPI classes
- modmachine: simplify SPI class implementation multiplexing
- espneopixel: disable IRQs during eps.neopixel_write
- modnetwork: fix wlan.scan() method so it returns all networks
- modmachine: map PWR_ON_RESET to vendor's REASON_DEFAULT_RST
- machine.PWR_ON_RESET is renamed to machine.PWRON_RESET
- when find'ing frozen files don't use extra slash, do follow symlinks

docs:
- esp8266/tutorial/pins: fix typo in commands for pin input mode
- esp8266/intro: add command to install esptool.py 1.0.1 via pip
- library/machine.WDT: add note that WDT is only available on WiPy
- esp8266/quickref: fix and update the SPI docs
- esp8266: update quickref and tutorial for OneWire/DS18X20 driver
- pyboard: update USB mouse tutorial to use VCP instead of CDC
- pyboard: update USB mouse tutorial to use pyb.USB_HID()
- library: add reference for pyb.usb_mode and pyb.USB_HID
- pyboard/quickref: add links to pinouts for other pyboard variants
- pyboard/quickref: add section on "delay and timing" for utime mod
- esp8266/quickref: add internal links to docs for some modules
- esp8266/quickref: update information on SPI classes
- esp8266/quickref: further improvements for SPI subsections
- library/machine.WDT: add that WDT is available on pyboard
- reference/isr_rules.rst: two minor additions to docs for using ISR

misc:
- add *.pyc to .gitignore, because Python 2 doesn't use __pycache__
- build mpy-cross as part of the Travis process

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``.