6 files changed, 346 insertions, 25 deletions
diff --git a/docs/wipy/tutorial/blynk.rst b/docs/wipy/tutorial/blynk.rst
new file mode 100644
index 0000000000..a804c67192
--- /dev/null
+++ b/docs/wipy/tutorial/blynk.rst
@@ -0,0 +1,19 @@
+Getting started with Blynk and the WiPy
+---------------------------------------
+
+Blynk is a platform with iOS and Android apps to control
+Arduino, Raspberry Pi and the likes over the Internet.
+You can easily build graphic interfaces for all your
+projects by simply dragging and dropping widgets.
+
+There are several examples available that work out-of-the-box with
+the WiPy. Before anything else, make sure that your WiPy is running
+the latest software, check :ref:`OTA How-To <wipy_firmware_upgrade>` for instructions.
+
+1. Get the `Blynk library <https://github.com/wipy/wipy/blob/master/lib/blynk/BlynkLib.py>`_ and put it in ``/flash/lib/`` via FTP.
+2. Get the `Blynk examples <https://github.com/wipy/wipy/tree/master/examples/blynk>`_ edit the network settings, and afterwards
+   upload them to ``/flash/lib/`` via FTP as well.
+3. Follow the instructions on each example to setup the Blynk dashboard on your smartphone or tablet.
+4. Give it a try, for instance::
+
+   >>> execfile('01_simple.py')
diff --git a/docs/wipy/tutorial/index.rst b/docs/wipy/tutorial/index.rst
index 751d9d7976..90523d0dce 100644
--- a/docs/wipy/tutorial/index.rst
+++ b/docs/wipy/tutorial/index.rst
@@ -3,28 +3,15 @@
 WiPy tutorials and examples
 ===========================
 
-Performing firmware upgrades
-----------------------------
-
-For detalied instructions see :ref:`OTA How-To <wipy_firmware_upgrade>`.
-
-Getting started with Blynk and the WiPy
----------------------------------------
-
-Blynk is a platform with iOS and Android apps to control
-Arduino, Raspberry Pi and the likes over the Internet.
-You can easily build graphic interfaces for all your
-projects by simply dragging and dropping widgets.
-
-There are several examples available that work out-of-the-box with
-the WiPy. Before anything else, make sure that your WiPy is running
-the latest software, check :ref:`OTA How-To <wipy_firmware_upgrade>`.
-
-1. Get the `Blynk library <https://github.com/wipy/wipy/blob/master/lib/blynk/BlynkLib.py>`_ and put it in ``/flash/lib/`` via FTP.
-2. Get the `Blynk examples <https://github.com/wipy/wipy/tree/master/examples/blynk>`_ edit the network settings, and afterwards
-   upload them to ``/flash/lib/`` via FTP as well.
-3. Follow the instructions on each example to setup the Blynk dashboard on your smartphone.
-4. Give it a try, for instance::
-
-   >>> execfile('01_simple.py')
-
+Before starting, make sure that you are running the latest firmware,
+for instrucctions see :ref:`OTA How-To <wipy_firmware_upgrade>`.
+
+.. toctree::
+   :maxdepth: 1
+   :numbered:
+
+   intro.rst
+   repl.rst
+   blynk.rst
+   wlan.rst
+   reset.rst
diff --git a/docs/wipy/tutorial/intro.rst b/docs/wipy/tutorial/intro.rst
new file mode 100644
index 0000000000..a8503302c8
--- /dev/null
+++ b/docs/wipy/tutorial/intro.rst
@@ -0,0 +1,64 @@
+Introduction to the WiPy
+========================
+
+To get the most out of your WiPy, there are a few basic things to
+understand about how it works.
+
+Caring for your WiPy and expansion board
+----------------------------------------
+
+Because the WiPy/expansion board does not have a housing it needs a bit of care:
+
+  - Be gentle when plugging/unplugging the USB cable.  Whilst the USB connector
+    is well soldered and is relatively strong, if it breaks off it can be very
+    difficult to fix.
+
+  - Static electricity can shock the components on the WiPy 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 WiPy.  If your WiPy came
+    in a ESD bag, then this bag is the best way to store and carry the
+    pyboard as it will protect it agains static discharges.
+
+As long as you take care of the hardware, you should be okay.  It's almost
+impossible to break the software on the WiPy, 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 do a safe boot,
+which is explained in detail :ref:`here <wipy_boot_modes>`.
+
+Plugging into the expansion board and powering on
+-------------------------------------------------
+
+The expansion board can power the WiPy via USB. The WiPy comes with a sticker
+on top of the RF shield tha labels all pins, and this should match the label
+numbers on the expansion board headers. When pluggin it in, the WiPy antenna
+will end up on top of the SD card connector of the expansion board. A video
+showing how to do this can be found `here <https://www.youtube.com/watch?v=47D9MZ9zFQw>`_.
+
+Expansion board hardware guide
+------------------------------
+
+The document explaining the hardware details of the expansion board can be found
+`here <https://github.com/wipy/wipy/blob/master/docs/User_manual_exp_board.pdf>`_.
+
+Powering by an external power source
+------------------------------------
+
+The WiPy 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.**
+
+- When powering via ``VIN``:
+
+   **The input voltage must be between 3.6V and 5.5V.**
+
+- When powering via ``3V3``:
+
+   **The input volatge must be exactly 3V3, ripple free and from a supply capable
+   of sourcing at least 300mA of current**
+
+Performing firmware upgrades
+----------------------------
+
+For detalied instructions see :ref:`OTA How-To <wipy_firmware_upgrade>`.
diff --git a/docs/wipy/tutorial/repl.rst b/docs/wipy/tutorial/repl.rst
new file mode 100644
index 0000000000..3ff602aaeb
--- /dev/null
+++ b/docs/wipy/tutorial/repl.rst
@@ -0,0 +1,137 @@
+Getting a MicroPython REPL prompt
+=================================
+
+REPL stands for Read Evaluate Print Loop, and is the name given to the
+interactive MicroPython prompt that you can access on the WiPy.  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 WiPy either via :ref:`telnet <wipy_telnet>`,
+or with a USB to serial converter wired to the one the two UARTs on the
+WiPy. To enable REPL duplication on UART0 (the one accesible via the expansion board)
+do::
+
+   >>> from machine import UART
+   >>> import os
+   >>> uart = UART(0, 115200)
+   >>> o.dupterm(uart)
+
+Place this piece of code inside your `boot.py` so that it's done automatically after
+reset.
+
+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.
+After installing, go back to the Device Manager to find the installed pyboard,
+and see which COM port it is (eg COM4).
+More comprehensive instructions can be found in the
+`Guide for pyboard on Windows (PDF) <http://micropython.org/resources/Micro-Python-Windows-setup.pdf>`_.
+Please consult this guide if you are having problems installing the driver.
+
+The best option is to download the free program PuTTY:
+`putty.exe <http://www.chiark.greenend.org.uk/~sgtatham/putty/download.html>`_.
+
+**In order to get to the telnet REPL:**
+
+Using putty, select ``Telnet`` as connection type, leave the default port (23)
+and enter the IP address of your WiPy (192.168.1.1 when in ``WLAN.AP`` mode),
+then click open.
+
+**In order to get to the REPL UART:**
+
+Using your serial program you must connect to the COM port that you found in the
+previous step.  With PuTTY, click on "Session" in the left-hand panel, then click
+the "Serial" radio button on the right, then enter you COM port (eg COM4) in the
+"Serial Line" box.  Finally, click the "Open" button.
+
+Mac OS X
+--------
+
+Open a terminal and run::
+
+    $ telnet 192.168.1.1
+
+or::
+
+    $ screen /dev/tty.usbmodem* 115200
+    
+When you are finished and want to exit screen, type CTRL-A CTRL-\\.
+
+Linux
+-----
+
+Open a terminal and run::
+
+    $ telnet 192.168.1.1
+
+or::
+
+    $ screen /dev/ttyUSB0 115200
+
+You can also try ``picocom`` or ``minicom`` instead of screen.  You may have to
+use ``/dev/ttyUSB01`` or a higher number for ``ttyUSB``.  And, you may need to give
+yourself the correct permissions to access this devices (eg group ``uucp`` or ``dialout``,
+or use sudo).
+
+Using the REPL prompt
+---------------------
+
+Now let's try running some MicroPython code directly on the WiPy.
+
+With your serial program open (PuTTY, screen, picocom, etc) you may see a blank
+screen with a flashing cursor.  Press Enter and you should be presented with a
+MicroPython prompt, i.e. ``>>>``.  Let's make sure it is working with the obligatory test::
+
+    >>> print("hello WiPy!")
+    hello WiPy!
+
+In the above, you should not type in the ``>>>`` characters.  They are there to
+indicate that you should type the text after it at the prompt.  In the end, once
+you have entered the text ``print("hello pyboard!")`` and pressed Enter, the output
+on your screen should look like it does above.
+
+If you already know some python you can now try some basic commands here. 
+
+If any of this is not working you can try either a hard reset or a soft reset;
+see below.
+
+Go ahead and try typing in some other commands.  For example::
+
+    >>> from machine import Pin
+    >>> import wipy
+    >>> wipy.heartbeat(False)  # disable the heartbeat
+    >>> led = Pin('GP25', mode=Pin.OUT)
+    >>> led(1)
+    >>> led(0)
+    >>> led.toggle()
+    >>> 1 + 2
+    3
+    >>> 4 // 2
+    2
+    >>> 20 * 'py'
+    'pypypypypypypypypypypypypypypypypypypypy'
+
+Resetting the board
+-------------------
+
+If something goes wrong, you can reset the board in two ways. The first is to press CTRL-D
+at the MicroPython prompt, which performs a soft reset.  You will see a message something like::
+
+    >>> 
+    PYB: soft reboot
+    MicroPython v1.4.6-146-g1d8b5e5 on 2015-10-21; WiPy with CC3200
+    Type "help()" for more information.
+    >>>
+
+If that isn't working you can perform a hard reset (turn-it-off-and-on-again) by pressing the
+RST switch (the small black button next to the heartbeat LED). During telnet, this will end
+your session, disconnecting whatever program that you used to connect to the WiPy.
diff --git a/docs/wipy/tutorial/reset.rst b/docs/wipy/tutorial/reset.rst
new file mode 100644
index 0000000000..970f8d1ddc
--- /dev/null
+++ b/docs/wipy/tutorial/reset.rst
@@ -0,0 +1,53 @@
+Reset and boot modes
+====================
+
+There are soft resets and hard resets. 
+
+   - A soft reset simply clears the state of the MicroPython virtual machine, 
+     but leaves hardware peripherals unaffected. To do a soft reset, simply press 
+     **Ctrl+D** on the REPL, or within a script do::
+
+      import sys
+      sys.exit()
+
+   - A hard reset is the same as performing a power cycle to the board. In order to
+     hard reset the WiPy, press the switch on the board or::
+
+        import machine
+        machine.reset()
+
+Safe boot
+---------
+
+If something goes wrong with your WiPy, don't panic!  It is almost
+impossible for you to break the WiPy by programming the wrong thing.
+
+The first thing to try is to boot in safe mode: this temporarily skips
+execution of ``boot.py`` and ``main.py`` and gives default WLAN settings.
+
+If you have problems with the filesystem you can :ref:`format the internal flash
+drive <wipy_factory_reset>`.
+
+To boot in safe mode, follow the detailed instructions described :ref:`here <wipy_boot_modes>`.
+
+In safe mode, the ``boot.py`` and ``main.py`` files are not executed, and so
+the WiPy boots up with default settings.  This means you now have access
+to the filesystem, and you can edit ``boot.py`` and ``main.py`` to fix any problems.
+
+Entering safe mode is temporary, and does not make any changes to the
+files on the WiPy.
+
+.. _wipy_factory_reset:
+
+Factory reset the filesystem
+----------------------------
+
+If you WiPy's filesystem gets corrupted (very unlikely, but possible), you
+can format it very easily byt doing::
+
+   >>> import os
+   >>> os.mkfs('/flash')
+
+Resetting the filesystem deletes all files on the internal WiPy storage
+(not the SD card), and restores the files ``boot.py``, ``main.py``, ``README.txt``
+and ``pybcdc.inf`` back to their original state after the next reset.
diff --git a/docs/wipy/tutorial/wlan.rst b/docs/wipy/tutorial/wlan.rst
new file mode 100644
index 0000000000..15a9bbefe8
--- /dev/null
+++ b/docs/wipy/tutorial/wlan.rst
@@ -0,0 +1,61 @@
+WLAN step by step
+=================
+
+The WLAN is a system feature of the WiPy, therefore it is always enabled
+(even while in ``machine.SLEEP``), except when deepsleep mode is entered.
+
+In order to retrieve the current WLAN instance, do::
+
+   >>> from network import WLAN
+   >>> wlan = WLAN() # we call the constructor without params
+
+You can check the current mode (which is always ``WLAN.AP`` after power up)::
+
+   >>> wlan.mode()
+
+Connecting to your home router
+------------------------------
+
+The WLAN network card always boots in ``WLAN.AP`` mode, so we must first configure
+it as a station::
+
+   from network import WLAN
+   wlan = WLAN(mode=WLAN.STA)
+
+Now you can proceed to scan for networks::
+
+    nets = wlan.scan()
+    for net in nets:
+        if net.ssid == 'mywifi':
+            print('Network found!')
+            wlan.connect(net.ssid, auth=(net.sec, 'mywifikey'), timeout=5000)
+            while not wlan.isconnected():
+                machine.idle() # save power while waiting
+            print('WLAN connection succeeded!)
+            break
+
+Assigning a static IP address when booting
+------------------------------------------
+
+If you want your WiPy to connect to your home router while after boot-up, and with a fixed
+IP address so that you can access it via telnet or FTP, use the following script::
+
+   import machine
+   from network import WLAN
+   wlan = WLAN() # get current object, without changing the mode
+
+   if machine.reset_cause() != machine.SOFT_RESET:
+       wlan.init(WLAN.STA)
+       # configuration below MUST match your home router settings!!
+       wlan.ifconfig(config=('192.168.178.107', '255.255.255.0', '192.168.178.1', '8.8.8.8'))
+
+   if not wlan.isconnected():
+       wlan.connect(net.ssid, auth=(net.sec, 'mywifikey'), timeout=5000)
+       while not wlan.isconnected():
+           machine.idle() # save power while waiting
+       break
+
+.. note::
+
+   Notice how we check for the reset cause and the connection status, this is crucial in order
+   to be able to soft reset the WiPy during a telnet session without breaking the connection.