docs: Imported tutorials from previous documentation system.

1 files changed, 129 insertions, 0 deletions

diff --git a/docs/tutorial/usb_mouse.rst b/docs/tutorial/usb_mouse.rst
new file mode 100644
index 0000000000..4c3a85e548
--- /dev/null
+++ b/docs/tutorial/usb_mouse.rst
@@ -0,0 +1,129 @@
+Making the pyboard act as a USB mouse
+=====================================
+
+The pyboard is a USB device, and can configured to act as a mouse instead
+of the default USB flash drive.
+
+To do this we must first edit the ``boot.py`` file to change the USB
+configuration.  If you have not yet touched your ``boot.py`` file then it
+will look something like this::
+
+    # boot.py -- run on boot-up
+    # can run arbitrary Python, but best to keep it minimal
+
+    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
+
+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
+
+If you already changed your ``boot.py`` file, then the minimum code it
+needs to work is::
+
+    import pyb
+    pyb.usb_mode('CDC+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.
+
+Eject/unmount the pyboard drive and reset it using the RST switch.
+Your PC should now detect the pyboard as a mouse!
+
+Sending mouse events by hand
+----------------------------
+
+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))
+
+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
+number 10 is telling the PC that the mouse moved 10 pixels in the x direction.
+
+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))
+    ...     pyb.delay(d)
+    ...
+    >>> osc(100, 50)
+
+The first argument to the function ``osc`` is the number of mouse events to send,
+and the second argument is the delay (in milliseconds) between events.  Try
+playing around with different numbers.
+
+**Excercise: make the mouse go around in a circle.**
+
+Making a mouse with the accelerometer
+-------------------------------------
+
+Now lets make the mouse move based on the angle of the pyboard, using the
+accelerometer.  The following code can be typed directly at the REPL prompt,
+or put in the ``main.py`` file.  Here, we'll put in in ``main.py`` because to do
+that we will learn how to go into safe mode.
+
+At the moment the pyboard is acting as a serial USB device and an HID (a mouse).
+So you cannot access the filesystem to edit your ``main.py`` file.
+
+You also can't edit your ``boot.py`` to get out of HID-mode and back to normal
+mode with a USB drive...
+
+To get around this we need to go into *safe mode*.  This was described in
+the [safe mode tutorial](tut-reset), but we repeat the instructions here:
+
+1. Hold down the USR switch.
+2. While still holding down USR, press and release the RST switch.
+3. The LEDs will then cycle green to orange to green+orange and back again.
+4. Keep holding down USR until *only the orange LED is lit*, and then let
+   go of the USR switch.
+5. The orange LED should flash quickly 4 times, and then turn off.  
+6. You are now in safe mode.
+
+In safe mode, the ``boot.py`` and ``main.py`` files are not executed, and so
+the pyboard boots up with default settings.  This means you now have access
+to the filesystem (the USB drive should appear), and you can edit ``main.py``.
+(Leave ``boot.py`` as-is, because we still want to go back to HID-mode after
+we finish editting ``main.py``.)
+
+In ``main.py`` put the following code::
+
+    import pyb
+
+    switch = pyb.Switch()
+    accel = pyb.Accel()
+
+    while not switch():
+        pyb.hid((0, accel.x(), accel.y(), 0))
+        pyb.delay(20)
+
+Save your file, eject/unmount your pyboard drive, and reset it using the RST
+switch.  It should now act as a mouse, and the angle of the board will move
+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.
+
+Restoring your pyboard to normal
+--------------------------------
+
+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::
+
+    #pyb.usb_mode('CDC+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.