docs: Add beginnings of troubleshooting doc.

tannewt · tannewt · commit 544f5c3fa43f · 2017-09-01T13:54:29.000-07:00
Fixes adafruit#172. Related to adafruit#214.
diff --git a/docs/troubleshooting.rst b/docs/troubleshooting.rst
@@ -0,0 +1,40 @@
+Troubleshooting
+==============================
+
+From time to time, an error occurs when working with CircuitPython. Here are a
+variety of errors that can happen, what they mean and how to fix them.
+
+File system issues
+------------------------------
+
+If your host computer starts complaining that your CIRCUITPY drive is corrupted
+or files cannot be overwritten or deleted, then you will have to erase it completely.
+When CircuitPython restarts it will create a fresh empty CIRCUITPY filesystem.
+
+This often happens on Windows when the CIRCUITPY disk is not safely ejected
+before being reset by the button or being disconnected from USB. This can also
+happen on Linux and Mac OSX but its less likely.
+
+.. danger:: This will erase all your files in CIRCUITPY!
+
+#. Download the appropriate flash erase uf2 from `here <https://github.com/adafruit/Adafruit_SPIFlash/tree/master/examples/flash_erase_express>`_.
+#. Double-click the reset button.
+#. Copy the appropriate .uf2 to the xxxBOOT drive.
+#. The on-board NeoPixel will turn blue, indicating the erase has started.
+#. After about 15 seconds, the NexoPixel will start flashing green. If it flashes red, the erase failed.
+#. Double-click again and load the appropriate `CircuitPython .uf2 <https://github.com/adafruit/circuitpython/releases/latest>`_.
+
+ValueError: Incompatible .mpy file.
+-------------------------------------
+
+This error occurs when importing a module that is stored as a `mpy` binary file
+(rather than a `py` text file) that was generated by a different version of
+CircuitPython than the one its being loaded into. Most versions are compatible
+but, rarely they aren't. In particular, the `mpy` binary format changed between
+CircuitPython versions 1.x and 2.x.
+
+So, if you just upgraded to 2.x from 1.x you'll need to download a newer version
+of the library. They are all available in the
+`Adafruit bundle <https://github.com/adafruit/Adafruit_CircuitPython_Bundle/releases/latest>`_
+and the `Community bundle <https://github.com/adafruit/CircuitPython_Community_Bundle/releases/latest>`_.
+Make sure to download a version with 2.0.0 or higher in the filename.
diff --git a/index.rst b/index.rst
@@ -42,10 +42,11 @@ docs are low-level API docs and may link out to separate getting started guides.
     :maxdepth: 3
 
     shared-bindings/index.rst
+    docs/supported_ports.rst
+    docs/troubleshooting.rst
     docs/drivers.rst
-    docs/common_hal
     docs/design_guide
-    docs/supported_ports.rst
+    docs/common_hal
     docs/library/index.rst
     README
     CONTRIBUTING
