56 lines
3.0 KiB
ReStructuredText
56 lines
3.0 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:: To erase and re-create ``CIRCUITPY`` (for example, to correct a corrupted filesystem),
|
|
follow one of the procedures below. It's important to note that **any files stored on the**
|
|
``CIRCUITPY`` **drive will be erased**.
|
|
|
|
**For boards with** ``CIRCUITPY`` **stored on a separate SPI flash chip,
|
|
such as Feather M0 Express, Metro M0 Express and Circuit Playground Express:**
|
|
|
|
|
|
#. Download the appropriate flash .erase uf2 from `the Adafruit_SPIFlash repo <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>`_.
|
|
|
|
**For boards without SPI flash, such as Feather M0 Proto, Gemma M0 and, Trinket M0:**
|
|
|
|
#. Download the appropriate erase .uf2 from `the Learn repo <https://github.com/adafruit/Adafruit_Learning_System_Guides/tree/master/uf2_flash_erasers>`_.
|
|
#. Double-click the reset button.
|
|
#. Copy the appropriate .uf2 to the xxxBOOT drive.
|
|
#. The boot LED will start pulsing again, and the xxxBOOT drive will appear again.
|
|
#. 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, and will change again between 2.x and 3.x.
|
|
|
|
So, for instance, 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.
|