docs: Imported tutorials from previous documentation system.

docs/general.rst

+General information about the pyboard
+=====================================
+
+Local filesystem and SD card
+----------------------------
+
+There is a small internal filesystem (a drive) on the pyboard, called ``/flash``,
+which is stored within the microcontroller's flash memory.  If a micro SD card
+is inserted into the slot, it is available as ``/sd``.
+
+When the pyboard boots up, it needs to choose a filesystem to boot from.  If
+there is no SD card, then it uses the internal filesystem ``/flash`` as the boot
+filesystem, otherwise, it uses the SD card ``/sd``.
+
+(Note that on older versions of the board, ``/flash`` is called ``0:/`` and ``/sd``
+is called ``1:/``).
+
+The boot filesystem is used for 2 things: it is the filesystem from which
+the ``boot.py`` and ``main.py`` files are searched for, and it is the filesystem
+which is made available on your PC over the USB cable.
+
+The filesystem will be available as a USB flash drive on your PC.  You can
+save files to the drive, and edit ``boot.py`` and ``main.py``.
+
+*Remember to eject (on Linux, unmount) the USB drive before you reset your
+pyboard.*
+
+Boot modes
+----------
+
+If you power up normally, or press the reset button, the pyboard will boot
+into standard mode: the ``boot.py`` file will be executed first, then the
+USB will be configured, then ``main.py`` will run.
+
+You can override this boot sequence by holding down the user switch as
+the board is booting up.  Hold down user switch and press reset, and then
+as you continue to hold the user switch, the LEDs will count in binary.
+When the LEDs have reached the mode you want, let go of the user switch,
+the LEDs for the selected mode will flash quickly, and the board will boot.
+
+The modes are:
+
+1. Green LED only, *standard boot*: run ``boot.py`` then ``main.py``.
+2. Orange LED only, *safe boot*: don't run any scripts on boot-up.
+3. Green and orange LED together, *filesystem reset*: resets the flash
+   filesystem to its factory state, then boots in safe mode.
+
+If your filesystem becomes corrupt, boot into mode 3 to fix it.
+
+Errors: flashing LEDs
+---------------------
+
+There are currently 2 kinds of errors that you might see:
+
+1. If the red and green LEDs flash alternatively, then a Python script
+    (eg ``main.py``) has an error.  Use the REPL to debug it.
+2. If all 4 LEDs cycle on and off slowly, then there was a hard fault.
+   This cannot be recovered from and you need to do a hard reset.
+

docs/index.rst

-.. Micro Python documentation master file, created by
-   sphinx-quickstart on Sun Sep 21 11:42:03 2014.
-   You can adapt this file completely to your liking, but it should at least
-   contain the root `toctree` directive.
+.. Micro Python documentation master file
 
-Welcome to Micro Python's documentation!
-========================================
+Micro Python documentation and references
+=========================================
 
-Contents:
+Here you can find documentation for Micro Python and the pyboard.
+
+Software
+--------
 
 .. toctree::
    :maxdepth: 2
 
+   general.rst
+   tutorial/index.rst
+
+.. 
+..  - Reference for the [pyb module](module/pyb/ "pyb module").
+..  - Reference for [all modules](module/ "all modules").
+..  - [Guide for setting up the pyboard on Windows](/static/doc/Micro-Python-Windows-setup.pdf), including DFU programming (PDF).
+
+The pyboard hardware
+--------------------
+
+..  - PYBv1.0 [schematics and layout](/static/doc/PYBv10b.pdf "PYBv1.0") (2.4MiB PDF).
+..  - PYBv1.0 [metric dimensions](/static/doc/PYBv10b-metric-dimensions.pdf "metric dimensions") (360KiB PDF).
+..  - PYBv1.0 [imperial dimensions](/static/doc/PYBv10b-imperial-dimensions.pdf "imperial dimensions") (360KiB PDF).
+
+Datasheets for the components on the pyboard
+--------------------------------------------
+
+..  - The microcontroller: [STM32F405RGT6](http://www.st.com/web/catalog/mmc/FM141/SC1169/SS1577/LN1035/PF252144) (external link).
+..  - The accelerometer: [Freescale MMA7660](/static/doc/MMA7660FC.pdf) (800kiB PDF).
+..  - The LDO voltage regulator: [Microchip MCP1802](/static/doc/MCP1802-22053C.pdf) (400kiB PDF).
 
 
 Indices and tables

docs/tutorial/accel.rst

+The accelerometer
+=================
+
+Here you will learn how to read the accelerometer and signal using LEDs states like tilt left and tilt right.
+
+Using the accelerometer
+-----------------------
+
+The pyboard has an accelerometer (a tiny mass on a tiny spring) that can be used
+to detect the angle of the board and motion. There is a different sensor for
+each of the x, y, z directions. To get the value of the accelerometer, create a
+pyb.Accel() object and then call the x() method. ::
+
+    >>> accel = pyb.Accel()
+    >>> accel.x()
+    7
+
+This returns a signed integer with a value between around -30 and 30. Note that
+the measurement is very noisy, this means that even if you keep the board
+perfectly still there will be some variation in the number that you measure.
+Because of this, you shouldn't use the exact value of the x() method but see if
+it is in a certain range.
+
+We will start by using the accelerometer to turn on a light if it is not flat. ::
+
+    accel = pyb.Accel()
+    light = pyb.LED(3)
+    SENSITIVITY = 3
+
+    while True:
+        x = accel.x()
+        if abs(x) > SENSITIVITY: 
+            light.on()
+        else:
+            light.off()
+
+        pyb.delay(100)
+
+We create Accel and LED objects, then get the value of the x direction of the
+accelerometer. If the magnitude of x is bigger than a certain value ``SENSITIVITY``,
+then the LED turns on, otherwise it turns off. The loop has a small ``pyb.delay()``
+otherwise the LED flashes annoyingly when the value of x is close to
+``SENSITIVITY``. Try running this on the pyboard and tilt the board left and right
+to make the LED turn on and off.
+
+**Exercise: Change the above script so that the blue LED gets brighter the more
+you tilt the pyboard.  HINT: You will need to rescale the values, intensity goes
+from 0-255.**
+
+Making a spirit level
+---------------------
+
+The example above is only sensitive to the angle in the x direction but if we
+use the ``y()`` value and more LEDs we can turn the pyboard into a spirit level. ::
+
+    xlights = (pyb.LED(2), pyb.LED(3))
+    ylights = (pyb.LED(1), pyb.LED(4))
+
+    accel = pyb.Accel()
+    SENSITIVITY = 3
+
+    while True:
+        x = accel.x()
+        if x > SENSITIVITY: 
+            xlights[0].on()
+            xlights[1].off()
+        elif x < -SENSITIVITY:
+            xlights[1].on()
+            xlights[0].off()
+        else:
+            xlights[0].off()
+            xlights[1].off()
+
+        y = accel.y()
+        if y > SENSITIVITY: 
+            ylights[0].on()
+            ylights[1].off()
+        elif y < -SENSITIVITY:
+            ylights[1].on()
+            ylights[0].off()
+        else:
+            ylights[0].off()
+            ylights[1].off()
+
+        pyb.delay(100)
+
+We start by creating a tuple of LED objects for the x and y directions. Tuples
+are immutable objects in python which means they can't be modified once they are
+created. We then proceed as before but turn on a different LED for positive and
+negative x values. We then do the same for the y direction. This isn't
+particularly sophisticated but it does the job. Run this on your pyboard and you
+should see different LEDs turning on depending on how you tilt the board.

docs/tutorial/amp_skin.rst

+The AMP audio skin
+==================
+
+Soldering and using the AMP audio skin.
+
+[<img src="/static/doc/skin-amp-1.jpg" alt="AMP skin" style="width:250px; border:1px solid black; display:inline-block;"/>](/static/doc/skin-amp-1.jpg)
+[<img src="/static/doc/skin-amp-3.jpg" alt="AMP skin" style="width:250px; border:1px solid black; display:inline-block;"/>](/static/doc/skin-amp-3.jpg)
+
+The following video shows how to solder the headers, microphone and speaker onto the AMP skin.
+
+<iframe style="margin-left:3em;" width="560" height="315" src="//www.youtube.com/embed/fjB1DuZRveo?rel=0" frameborder="0" allowfullscreen></iframe>
+
+Example code
+------------
+
+The AMP skin has a speaker which is connected to DAC(1) via a small
+power amplifier.  The volume of the amplifier is controlled by a digital
+potentiometer, which is an I2C device with address 46 on the IC2(1) bus.
+
+To set the volume, define the following function::
+
+    def volume(val):
+        pyb.I2C(1, pyb.I2C.MASTER).mem_write(val, 46, 0)
+
+Then you can do::
+
+    >>> volume(0)   # minimum volume
+    >>> volume(127) # maximum volume
+
+To play a sound, use the ``write_timed`` method of the ``DAC`` object.
+For example::
+
+    import math
+    from pyb import DAC
+
+    # create a buffer containing a sine-wave
+    buf = bytearray(100)
+    for i in range(len(buf)):
+        buf[i] = 128 + int(127 * math.sin(2 * math.pi * i / len(buf)))
+
+    # output the sine-wave at 400Hz
+    dac = DAC(1)
+    dac.write_timed(buf, 400 * len(buf), mode=DAC.CIRCULAR)
+
+You can also play WAV files using the Python ``wave`` module.  You can get
+the wave module [here](/static/doc/examples/wave.py) and you will also need
+the chunk module available [here](/static/doc/examples/chunk.py).  Put these
+on your pyboard (either on the flash or the SD card in the top-level
+directory).  You will need an 8-bit WAV file to play, such as
+[this one](/static/doc/examples/test.wav).  Then you can do::
+
+    >>> import wave
+    >>> from pyb import DAC
+    >>> dac = DAC(1)
+    >>> f = wave.open('test.wav')
+    >>> dac.write_timed(f.readframes(f.getnframes()), f.getframerate())
+
+This should play the WAV file.

docs/tutorial/assembler.rst

+Inline assembler
+================
+
+Here you will learn how to write inline assembler in Micro Python.
+
+**Note**: this is an advanced tutorial, intended for those who already
+know a bit about microcontrollers and assembly language.
+
+Micro Python includes an inline assembler.  It allows you to write
+assembly routines as a Python function, and you can call them as you would
+a normal Python function.
+
+Returning a value
+-----------------
+
+Inline assembler functions are denoted by a special function decorator.
+Let's start with the simplest example::
+
+    @micropython.asm_thumb
+    def fun():
+        movw(r0, 42)
+
+You can enter this in a script or at the REPL.  This function takes no
+arguments and returns the number 42.  ``r0`` is a register, and the value
+in this register when the function returns is the value that is returned.
+Micro Python always interprets the ``r0`` as an integer, and converts it to an
+integer object for the caller.
+
+If you run ``print(fun())`` you will see it print out 42.
+
+Accessing peripherals
+---------------------
+
+For something a bit more complicated, let's turn on an LED::
+
+    @micropython.asm_thumb
+    def led_on():
+        movwt(r0, stm.GPIOA)
+        movw(r1, 1 << 13)
+        strh(r1, [r0, stm.GPIO_BSRRL])
+
+This code uses a few new concepts:
+
+  - ``stm`` is a module which provides a set of constants for easy
+    access to the registers of the pyboard's microcontroller.  Try
+    running ``import stm`` and then ``help(stm)`` at the REPL.  It will
+    give you a list of all the available constants.
+
+  - ``stm.GPIOA`` is the address in memory of the GPIOA peripheral.
+    On the pyboard, the red LED is on port A, pin PA13.
+
+  - ``movwt`` moves a 32-bit number into a register.  It is a convenience
+    function that turns into 2 thumb instructions: ``movw`` followed by ``movt``.
+    The ``movt`` also shifts the immediate value right by 16 bits.
+
+  - ``strh`` stores a half-word (16 bits).  The instruction above stores
+    the lower 16-bits of ``r1`` into the memory location ``r0 + stm.GPIO_BSRRL``.
+    This has the effect of setting high all those pins on port A for which
+    the corresponding bit in ``r0`` is set.  In our example above, the 13th
+    bit in ``r0`` is set, so PA13 is pulled high.  This turns on the red LED.
+
+Accepting arguments
+-------------------
+
+Inline assembler functions can accept up to 3 arguments.  If they are
+used, they must be named ``r0``, ``r1`` and ``r2`` to reflect the registers
+and the calling conventions.
+
+Here is a function that adds its arguments::
+
+    @micropython.asm_thumb
+    def asm_add(r0, r1):
+        add(r0, r0, r1)
+
+This performs the computation ``r0 = r0 + r1``.  Since the result is put
+in ``r0``, that is what is returned.  Try ``asm_add(1, 2)``, it should return
+3.
+
+Loops
+-----
+
+We can assign labels with ``label(my_label)``, and branch to them using
+``b(my_label)``, or a conditional branch like ``bgt(my_label)``.
+
+The following example flashes the green LED.  It flashes it ``r0`` times. ::
+
+    @micropython.asm_thumb
+    def flash_led(r0):
+        # get the GPIOA address in r1
+        movwt(r1, stm.GPIOA)
+
+        # get the bit mask for PA14 (the pin LED #2 is on)
+        movw(r2, 1 << 14)
+
+        b(loop_entry)
+
+        label(loop1)
+
+        # turn LED on
+        strh(r2, [r1, stm.GPIO_BSRRL])
+
+        # delay for a bit
+        movwt(r4, 5599900)
+        label(delay_on)
+        sub(r4, r4, 1)
+        cmp(r4, 0)
+        bgt(delay_on)
+
+        # turn LED off
+        strh(r2, [r1, stm.GPIO_BSRRH])
+
+        # delay for a bit
+        movwt(r4, 5599900)
+        label(delay_off)
+        sub(r4, r4, 1)
+        cmp(r4, 0)
+        bgt(delay_off)
+
+        # loop r0 times
+        sub(r0, r0, 1)
+        label(loop_entry)
+        cmp(r0, 0)
+        bgt(loop1)

docs/tutorial/index.rst

+.. _tutorial-index:
+
+Micro Python tutorial
+=====================
+
+This tutorial is intended to get you started with your pyboard.
+All you need is a pyboard and a micro-USB cable to connect it to
+your PC.  If it is your first time, it is recommended to follow
+the tutorial through in the order below.
+
+.. toctree::
+   :maxdepth: 1
+   :numbered:
+
+   intro.rst
+   script.rst
+   repl.rst
+   leds.rst
+   switch.rst
+   accel.rst
+   reset.rst
+   usb_mouse.rst
+   timer.rst
+   assembler.rst
+
+Tutorials requiring extra components
+------------------------------------
+
+.. toctree::
+   :maxdepth: 1
+   :numbered:
+
+   servo.rst
+   lcd_skin.rst
+   amp_skin.rst

docs/tutorial/intro.rst

+Introduction to the pyboard
+===========================
+
+To get the most out of your pyboard, there are a few basic things to
+understand about how it works.
+
+Caring for your pyboard
+-----------------------
+
+Because the pyboard does not have a housing it needs a bit of care:
+
+  - Be gentle when plugging/unplugging the USB cable.  Whilst the USB connector
+    is soldered through the board and is relatively strong, if it breaks off
+    it can be very difficult to fix.
+
+  - Static electricity can shock the components on the pyboard and destroy them.
+    If you experience a lot of static electricity in your area (eg dry and cold
+    climates), take extra care not to shock the pyboard.  If your pyboard came
+    in a black plastic box, then this box is the best way to store and carry the
+    pyboard as it is an anti-static box (it is made of a conductive plastic, with
+    conductive foam inside).
+
+As long as you take care of the hardware, you should be okay.  It's almost
+impossible to break the software on the pyboard, so feel free to play around
+with writing code as much as you like.  If the filesystem gets corrupt, see
+below on how to reset it.  In the worst case you might need to reflash the
+Micro Python software, but that can be done over USB.
+
+Layout of the pyboard
+---------------------
+
+The micro USB connector is on the top right, the micro SD card slot on
+the top left of the board.  There are 4 LEDs between the SD slot and
+USB connector.  The colours are: red on the bottom, then green, orange,
+and blue on the top.  There are 2 switches: the right one is the reset
+switch, the left is the user switch.
+
+Plugging in and powering on
+---------------------------
+
+The pyboard can be powered via USB.  Connect it to your PC via a micro USB
+cable.  There is only one way that the cable will fit.  Once connected,
+the green LED on the board should flash quickly.
+
+Powering by an external power source
+------------------------------------
+
+The pyboard can be powered by a battery or other external power source.
+
+**Be sure to connect the positive lead of the power supply to VIN, and
+ground to GND.  There is no polarity protection on the pyboard so you
+must be careful when connecting anything to VIN.**
+
+**The input voltage must be between 3.6V and 10V.**

docs/tutorial/lcd_skin.rst

+The LCD and touch-sensor skin
+=============================
+
+Soldering and using the LCD and touch-sensor skin.
+
+[<img src="/static/doc/skin-lcd-3.jpg" alt="pyboard with LCD skin" style="width:250px; border:1px solid black; display:inline-block;"/>](/static/doc/skin-lcd-3.jpg)
+[<img src="/static/doc/skin-lcd-1.jpg" alt="pyboard with LCD skin" style="width:250px; border:1px solid black; display:inline-block;"/>](/static/doc/skin-lcd-1.jpg)
+
+The following video shows how to solder the headers onto the LCD skin.
+At the end of the video, it shows you how to correctly connect the LCD skin to the pyboard.
+
+<iframe style="margin-left:3em;" width="560" height="315" src="//www.youtube.com/embed/PowCzdLYbFM?rel=0" frameborder="0" allowfullscreen></iframe>
+
+Using the LCD
+-------------
+
+To get started using the LCD, try the following at the Micro Python prompt.
+Make sure the LCD skin is attached to the pyboard as pictured at the top of this page. ::
+
+    >>> lcd = pyb.LCD('X')
+    >>> lcd.light(True)
+    >>> lcd.write('Hello uPy!\n')
+
+You can make a simple animation using the code::
+
+    lcd = pyb.LCD('X')
+    lcd.light(True)
+    for x in range(-80, 128):
+        lcd.fill(0)
+        lcd.text('Hello uPy!', x, 10, 1)
+        lcd.show()
+        pyb.delay(25)
+
+Using the touch sensor
+----------------------
+
+To read the touch-sensor data you need to use the I2C bus.  The
+MPR121 capacitive touch sensor has address 90.
+
+To get started, try::
+
+    >>> i2c = pyb.I2C(1, pyb.I2C.MASTER)
+    >>> i2c.mem_write(4, 90, 0x5e)
+    >>> touch = i2c.mem_read(1, 90, 0)[0]
+
+The first line above makes an I2C object, and the second line
+enables the 4 touch sensors.  The third line reads the touch
+status and the ``touch`` variable holds the state of the 4 touch
+buttons (A, B, X, Y).
+
+There is a simple driver [here](/static/doc/examples/mpr121.py)
+which allows you to set the threshold and debounce parameters, and
+easily read the touch status and electrode voltage levels.  Copy
+this script to your pyboard (either flash or SD card, in the top
+directory or ``lib/`` directory) and then try::
+
+    >>> import pyb
+    >>> import mpr121
+    >>> m = mpr121.MPR121(pyb.I2C(1, pyb.I2C.MASTER))
+    >>> for i in range(100):
+    ...   print(m.touch_status())
+    ...   pyb.delay(100)
+    ...
+
+This will continuously print out the touch status of all electrodes.
+Try touching each one in turn.
+
+Note that if you put the LCD skin in the Y-position, then you need to
+initialise the I2C bus using::
+
+    >>> m = mpr121.MPR121(pyb.I2C(2, pyb.I2C.MASTER))
+
+There is also a demo which uses the LCD and the touch sensors together,
+and can be found [here](/static/doc/examples/lcddemo.py).

docs/tutorial/leds.rst

+Turning on LEDs and basic Python concepts
+=========================================
+
+The easiest thing to do on the pyboard is to turn on the LEDs attached to the board. Connect the board, and log in as described in tutorial 1. We will start by turning and LED on in the interpreter, type the following ::
+
+    >>> myled = pyb.LED(1)
+    >>> myled.on()
+    >>> myled.off()
+
+These commands turn the LED on and off.
+
+This is all very well but we would like this process to be automated. Open the file MAIN.PY on the pyboard in your favourite text editor. Write or paste the following lines into the file. If you are new to python, then make sure you get the indentation correct since this matters! ::
+
+    led = pyb.LED(2)
+    while True:
+        led.toggle()
+        pyb.delay(1000)
+
+When you save, the red light on the pyboard should turn on for about a second. To run the script, do a soft reset (CTRL-D). The pyboard will then restart and you should see a green light continuously flashing on and off. Success, the first step on your path to building an army of evil robots! When you are bored of the annoying flashing light then press CTRL-C at your terminal to stop it running.
+ 
+So what does this code do? First we need some terminology. Python is an object-oriented language, almost everything in python is a *class* and when you create an instance of a class you get an *object*. Classes have *methods* associated to them. A method (also called a member function) is used to interact with or control the object.
+
+The first line of code creates an LED object which we have then called led. When we create the object, it takes a single parameter which must be between 1 and 4, corresponding to the 4 LEDs on the board. The pyb.LED class has three important member functions that we will use: on(), off() and toggle(). The other function that we use is pyb.delay() this simply waits for a given time in miliseconds. Once we have created the LED object, the statement while True: creates an infinite loop which toggles the led between on and off and waits for 1 second.
+
+**Exercise: Try changing the time between toggling the led and turning on a different LED.**
+
+**Exercise: Connect to the pyboard directly, create a pyb.LED object and turn it on using the on() method.**
+
+A Disco on your pyboard
+-----------------------
+
+So far we have only used a single LED but the pyboard has 4 available. Let's start by creating an object for each LED so we can control each of them. We do that by creating a list of LEDS with a list comprehension. ::
+
+    leds = [pyb.LED(i) for i in range(1,5)]
+
+If you call pyb.LED() with a number that isn't 1,2,3,4 you will get an error message.
+Next we will set up an infinite loop that cycles through each of the LEDs turning them on and off. ::
+
+    n = 0
+    while True:
+      n = (n + 1) % 4
+      leds[n].toggle()
+      pyb.delay(50)
+
+Here, n keeps track of the current LED and every time the loop is executed we cycle to the next n (the % sign is a modulus operator that keeps n between 0 and 4.) Then we access the nth LED and toggle it. If you run this you should see each of the LEDs turning on then all turning off again in sequence.
+
+One problem you might find is that if you stop the script and then start it again that the LEDs are stuck on from the previous run, ruining our carefully choreographed disco. We can fix this by turning all the LEDs off when we initialise the script and then using a try/finally block. When you press CTRL-C, Micro Python generates a VCPInterrupt exception. Exceptions normally mean something has gone wrong and you can use a try: command to "catch" an exception. In this case it is just the user interrupting the script, so we don't need to catch the error but just tell Micro Python what to do when we exit. The finally block does this, and we use it to make sure all the LEDs are off. The full code is::
+
+    leds = [pyb.LED(i) for i in range(1,5)]
+    for l in leds: 
+        l.off()
+
+    n = 0
+    try:
+       while True:
+          n = (n + 1) % 4
+          leds[n].toggle()
+          pyb.delay(50)
+    finally:
+        for l in leds:
+            l.off()
+
+The Fourth Special LED
+----------------------
+
+The blue LED is special. As well as turning it on and off, you can control the intensity using the intensity() method. This takes a number between 0 and 255 that determines how bright it is. The following script makes the blue LED gradually brighter then turns it off again. ::
+
+    led = pyb.LED(4)
+    intensity = 0
+    while True:
+        intensity = (intensity + 1) % 255
+        led.intensity(intensity)
+        pyb.delay(20)
+
+You can call intensity() on the other LEDs but they can only be off or on. 0 sets them off and any other number up to 255 turns them on.

docs/tutorial/repl.rst

+Getting a Micro Python REPL prompt
+==================================
+
+REPL stands for Read Evaluate Print Loop, and is the name given to the
+interactive Micro Python prompt that you can access on the pyboard.  Using
+the REPL is by far the easiest way to test out your code and run commands.
+You can use the REPL in addition to writing scripts in ``main.py``.
+
+To use the REPL, you must connect to the serial USB device on the pyboard.
+How you do this depends on your operating system.
+
+Windows
+-------
+
+You need to install the pyboard driver to use the serial USB device.
+The driver is on the pyboard's USB flash drive, and is called ``pybcdc.inf``.
+
+To install this driver you need to go to Device Manager
+for your computer, find the pyboard in the list of devices (it should have
+a warning sign next to it because it's not working yet), right click on
+the pyboard device, select Properties, then Install Driver.  You need to
+then select the option to find the driver manually (don't use Windows auto update),
+navigate to the pyboard's USB drive, and select that.  It should then install.