djsundog
/
circuitpython
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

docs: Add beginnings of troubleshooting doc. 

Fixes #172. Related to #214.
This commit is contained in:
Scott Shawcroft 2017-08-31 14:52:02 -07:00 committed by Scott Shawcroft
parent a0d0b27faf
commit 544f5c3fa4
2 changed files with 44 additions and 3 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

40
docs/troubleshooting.rst Normal file
View File

@ -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.

7
index.rst
View File

@ -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/drivers.rst
docs/common_hal
docs/design_guide
docs/supported_ports.rst
docs/troubleshooting.rst
docs/drivers.rst
docs/design_guide
docs/common_hal
docs/library/index.rst
README
CONTRIBUTING