1 files changed, 137 insertions, 0 deletions
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.