diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/troubleshooting.rst | 40 |
1 files changed, 40 insertions, 0 deletions
diff --git a/docs/troubleshooting.rst b/docs/troubleshooting.rst new file mode 100644 index 000000000..2829cee7b --- /dev/null +++ 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. |