diff --git a/docs/troubleshooting.rst b/docs/troubleshooting.rst new file mode 100644 index 0000000000000..34ee392d25ae5 --- /dev/null +++ b/docs/troubleshooting.rst @@ -0,0 +1,45 @@ +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 `_. +#. 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 `_. + +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 `_ +and the `Community bundle `_. +Make sure to download a version with 2.0.0 or higher in the filename. diff --git a/index.rst b/index.rst index 8f83c02085aac..9a0096aa4d50c 100644 --- a/index.rst +++ b/index.rst @@ -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/supported_ports.rst + docs/troubleshooting.rst docs/drivers.rst - docs/common_hal docs/design_guide - docs/supported_ports.rst + docs/common_hal docs/library/index.rst README CONTRIBUTING