46 lines
2.3 KiB
ReStructuredText
46 lines
2.3 KiB
ReStructuredText
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.
|
|
|
|
.. caution:: Delete ``CIRCUITPY`` filesystem and reload CircuitPython.
|
|
|
|
To reload CircuitPython (for example, to correct a corrupted filesystem),
|
|
follow the process below. It's important to note that **any files stored on the
|
|
``CIRCUITPY`` drive will be erased**.
|
|
|
|
#. 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 CircuitPython 2.x from 1.x you'll need to download a
|
|
newer version of the library that triggered the error on ``import``. 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.
|