59 lines
3.0 KiB
ReStructuredText
59 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.
|
|
|
|
Corruption 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 it's 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. Back up your code if possible before continuing!**
|
|
|
|
REPL Erase Method
|
|
^^^^^^^^^^^^^^^^^
|
|
This is the recommended method of erasing your board. If you are having trouble accessing the
|
|
``CIRCUITPY`` drive or the REPL, consider first putting your board into
|
|
`safe mode <https://learn.adafruit.com/welcome-to-circuitpython/troubleshooting#safe-mode-3105351-22>`_.
|
|
|
|
**To erase any board if you have access to the REPL:**
|
|
|
|
#. Connect to the CircuitPython REPL using a terminal program.
|
|
#. Type ``import storage`` into the REPL.
|
|
#. Then, type ``storage.erase_filesystem()`` into the REPL.
|
|
#. The ``CIRCUITPY`` drive will be erased and the board will restart with an empty ``CIRCUITPY`` drive.
|
|
|
|
Erase File Method
|
|
^^^^^^^^^^^^^^^^^
|
|
**If you do not have access to the REPL, you may still have options to erase your board.**
|
|
|
|
The `Erase CIRCUITPY Without Access to the REPL <https://learn.adafruit.com/welcome-to-circuitpython/troubleshooting#erase-circuitpy-without-access-to-the-repl-3105309-32>`_
|
|
section of the Troubleshooting page in the Welcome to CircuitPython guide covers the non-REPL
|
|
erase process for various boards. Visit the guide, find the process that applies to your board,
|
|
and follow the instructions to erase your board.
|
|
|
|
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 it's 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, 2.x and 3.x, and will change again between 6.x and 7.x.
|
|
|
|
So, for instance, if you just upgraded to CircuitPython 7.x from 6.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 7.0.0 or higher in the filename.
|