adafruit/circuitpython

-  The order that files are run and the state that is shared between
   them. CircuitPython's goal is to clarify the role of each file and
   make each file independent from each other.

   -  ``boot.py`` runs only once on start up before
      workflows are initialized. This lays the ground work for configuring USB at
      startup rather than it being fixed. Since serial is not available,
      output is written to ``boot_out.txt``.
   -  ``code.py`` (or ``main.py``) is run after every reload until it
      finishes or is interrupted. After it is done running, the vm and
      hardware is reinitialized. **This means you cannot read state from**
      ``code.py`` **in the REPL anymore, as the REPL is a fresh vm.** CircuitPython's goal for this
      change includes reducing confusion about pins and memory being used.
   -  After the main code is finished the REPL can be entered by pressing any key.
      - If the file ``repl.py`` exists, it is executed before the REPL Prompt is shown
      - In safe mode this functionality is disabled, to ensure the REPL Prompt can always be reached
   -  Autoreload state will be maintained across reload.

-  Adds a safe mode that does not run user code after a hard crash or brown out. This makes it
   possible to fix code that causes nasty crashes by making it available through mass storage after
   the crash. A reset (the button) is needed after it's fixed to get back into normal mode.
-  A 1 second delay is added to the boot process during which time the status LED will flash, and
   resetting the device or pressing the boot button will force the device into safe mode. This delay
   can be removed by a compile time option (``CIRCUITPY_SKIP_SAFE_MODE_WAIT``).
-  Safe mode may be handled programmatically by providing a ``safemode.py``.
   ``safemode.py`` is run if the board has reset due to entering safe mode, unless the safe mode
   initiated by the user by pressing button(s).
   USB is not available so nothing can be printed.
   ``safemode.py`` can determine why the safe mode occurred
   using ``supervisor.runtime.safe_mode_reason``, and take appropriate action. For instance,
   if a hard crash occurred, ``safemode.py`` may do a ``microcontroller.reset()``
   to automatically restart despite the crash.
   If the battery is low, but is being charged, ``safemode.py`` may put the board in deep sleep
   for a while. Or it may simply reset, and have ``code.py`` check the voltage and do the sleep.
-  RGB status LED indicating CircuitPython state.
   - One green flash - code completed without error.
   - Two red flashes - code ended due to an exception.
   - Three yellow flashes - safe mode. May be due to CircuitPython internal error.
-  Re-runs ``code.py`` or other main file after file system writes by a workflow. (Disable with
   ``supervisor.disable_autoreload()``)
-  Autoreload is disabled while the REPL is active.
-  ``code.py`` may also be named ``code.txt``, ``main.py``, or ``main.txt``.
-  ``boot.py`` may also be named ``boot.txt``.
-  ``safemode.py`` may also be named ``safemode.txt``.

API
~~~

-  Unified hardware APIs. Documented on
   `ReadTheDocs <https://circuitpython.readthedocs.io/en/latest/shared-bindings/index.html>`_.
-  API docs are Python stubs within the C files in ``shared-bindings``.
-  No ``machine`` API.

Modules
~~~~~~~

-  No module aliasing. (``uos`` and ``utime`` are not available as
   ``os`` and ``time`` respectively.) Instead ``os``, ``time``, and
   ``random`` are CPython compatible.
-  New ``storage`` module which manages file system mounts.
   (Functionality from ``uos`` in MicroPython.)
-  Modules with a CPython counterpart, such as ``time``, ``os`` and
   ``random``, are strict
   `subsets <https://circuitpython.readthedocs.io/en/latest/shared-bindings/time/__init__.html>`__
   of their `CPython
   version <https://docs.python.org/3.4/library/time.html?highlight=time#module-time>`__.
   Therefore, code from CircuitPython is runnable on CPython but not
   necessarily the reverse.
-  tick count is available as
   `time.monotonic() <https://circuitpython.readthedocs.io/en/latest/shared-bindings/time/__init__.html#time.monotonic>`__

--------------

Project Structure
-----------------

Here is an overview of the top-level source code directories.

Core
~~~~

The core code of
`MicroPython <https://github.com/micropython/micropython>`__ is shared
amongst ports including CircuitPython:

-  ``docs`` High level user documentation in Sphinx reStructuredText
   format.
-  ``drivers`` External device drivers written in Python.
-  ``examples`` A few example Python scripts.
-  ``extmod`` Shared C code used in multiple ports' modules.
-  ``lib`` Shared core C code including externally developed libraries
   such as FATFS.
-  ``logo`` The CircuitPython logo.
-  ``mpy-cross`` A cross compiler that converts Python files to byte
   code prior to being run in MicroPython. Useful for reducing library
   size.
-  ``py`` Core Python implementation, including compiler, runtime, and
   core library.
-  ``shared-bindings`` Shared definition of Python modules, their docs
   and backing C APIs. Ports must implement the C API to support the
   corresponding module.
-  ``shared-module`` Shared implementation of Python modules that may be
   based on ``common-hal``.
-  ``tests`` Test framework and test scripts.
-  ``tools`` Various tools, including the pyboard.py module.

Ports
~~~~~

Ports include the code unique to a microcontroller line.

The following ports are available: ``atmel-samd``, ``cxd56``, ``espressif``, ``litex``, ``mimxrt10xx``, ``nordic``, ``raspberrypi``, ``renode``, ``silabs`` (``efr32``), ``stm``, ``unix``, and ``zephyr-cp``.

However, not all ports are fully functional. Some have limited functionality and known serious bugs.
For details, refer to the **Port status** section in the `latest release <https://github.com/adafruit/circuitpython/releases/latest>`__ notes.

Boards
~~~~~~

-  Each ``port`` has a ``boards`` directory containing boards
   which belong to a specific microcontroller line.
-  A list of native modules supported by a particular board can be found
   `here <https://circuitpython.readthedocs.io/en/latest/shared-bindings/support_matrix.html>`__.

`Back to Top <#circuitpython>`__

.. |Build Status| image:: https://github.com/adafruit/circuitpython/workflows/Build%20CI/badge.svg
   :target: https://github.com/adafruit/circuitpython/actions?query=branch%3Amain
.. |Doc Status| image:: https://readthedocs.org/projects/circuitpython/badge/?version=latest
   :target: http://circuitpython.readthedocs.io/
.. |Discord| image:: https://img.shields.io/discord/327254708534116352.svg
   :target: https://adafru.it/discord
.. |License| image:: https://img.shields.io/badge/License-MIT-brightgreen.svg
   :target: https://choosealicense.com/licenses/mit/
.. |Weblate| image:: https://hosted.weblate.org/widgets/circuitpython/-/svg-badge.svg
   :target: https://hosted.weblate.org/engage/circuitpython/?utm_source=widget