1 files changed, 62 insertions, 0 deletions
diff --git a/docs/pyboard/general.rst b/docs/pyboard/general.rst
new file mode 100644
index 0000000000..107bae69a7
--- /dev/null
+++ b/docs/pyboard/general.rst
@@ -0,0 +1,62 @@
+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.
+If resetting the filesystem while plugged into your compute doesn't work,
+you can try doing the same procedure while the board is plugged into a USB
+charger, or other USB power supply without data connection.
+
+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.
+