|
| 1 | +CircuitPython |
| 2 | +============= |
| 3 | + |
| 4 | +.. image:: https://s3.amazonaws.com/adafruit-circuit-python/CircuitPython_Repo_header_logo.png |
| 5 | + |
| 6 | +|Build Status| |Doc Status| |License| |Discord| |Weblate| |
| 7 | + |
| 8 | +`circuitpython.org <https://circuitpython.org>`__ \| `Get CircuitPython <#get-circuitpython>`__ \| |
| 9 | +`Documentation <#documentation>`__ \| `Contributing <#contributing>`__ \| |
| 10 | +`Branding <#branding>`__ \| `Differences from Micropython <#differences-from-micropython>`__ \| |
| 11 | +`Project Structure <#project-structure>`__ |
| 12 | + |
| 13 | +**CircuitPython** is a *beginner friendly*, open source version of Python for tiny, inexpensive |
| 14 | +computers called microcontrollers. Microcontrollers are the brains of many electronics including a |
| 15 | +wide variety of development boards used to build hobby projects and prototypes. CircuitPython in |
| 16 | +electronics is one of the best ways to learn to code because it connects code to reality. Simply |
| 17 | +install CircuitPython on a supported board via drag and drop and then edit a ``code.py`` file on |
| 18 | +the CIRCUITPY drive. The code will automatically reload. No software installs are needed besides a |
| 19 | +text editor (we recommend `Mu <https://codewith.mu/>`_ for beginners.) |
| 20 | + |
| 21 | +CircuitPython features unified Python core APIs and a growing list of 150+ device libraries and |
| 22 | +drivers that work with it. These libraries also work on single board computers with regular |
| 23 | +Python via the `Adafruit Blinka Library <https://github.com/adafruit/Adafruit_Blinka>`_. |
| 24 | + |
| 25 | +CircuitPython is based on `MicroPython <https://micropython.org>`_. See |
| 26 | +`below <#differences-from-micropython>`_ for differences. CircuitPython development is sponsored by |
| 27 | +`Adafruit <https://adafruit.com>`_ and is available on their educational development boards. Please |
| 28 | +support both MicroPython and Adafruit. |
| 29 | + |
| 30 | +Get CircuitPython |
| 31 | +------------------ |
| 32 | + |
| 33 | +Official binaries for all supported boards are available through |
| 34 | +`circuitpython.org/downloads <https://circuitpython.org/downloads>`_. The site includes stable, unstable and |
| 35 | +continuous builds. Full release notes and assets are available through |
| 36 | +`GitHub releases <https://github.com/adafruit/circuitpython/releases>`_ as well. |
| 37 | + |
| 38 | +Documentation |
| 39 | +------------- |
| 40 | + |
| 41 | +Guides and videos are available through the `Adafruit Learning |
| 42 | +System <https://learn.adafruit.com/>`__ under the `CircuitPython |
| 43 | +category <https://learn.adafruit.com/category/circuitpython>`__. An API |
| 44 | +reference is also available on `Read the Docs |
| 45 | +<http://circuitpython.readthedocs.io/en/latest/?>`__. A collection of awesome |
| 46 | +resources can be found at `Awesome CircuitPython <https://github.com/adafruit/awesome-circuitpython>`__. |
| 47 | + |
| 48 | +Specifically useful documentation when starting out: |
| 49 | + |
| 50 | +- `Welcome to CircuitPython <https://learn.adafruit.com/welcome-to-circuitpython>`__ |
| 51 | +- `CircuitPython Essentials <https://learn.adafruit.com/circuitpython-essentials>`__ |
| 52 | +- `Example Code <https://github.com/adafruit/Adafruit_Learning_System_Guides/tree/master/CircuitPython_Essentials>`__ |
| 53 | + |
| 54 | +Code Search |
| 55 | +------------ |
| 56 | +GitHub doesn't currently support code search on forks. Therefore, CircuitPython doesn't have code search through GitHub because it is a fork of MicroPython. Luckily, `SourceGraph <https://sourcegraph.com/github.com/adafruit/circuitpython>`_ has free code search for public repos like CircuitPython. So, visit `sourcegraph.com/github.com/adafruit/circuitpython <https://sourcegraph.com/github.com/adafruit/circuitpython>`_ to search the CircuitPython codebase online. |
| 57 | + |
| 58 | +Contributing |
| 59 | +------------ |
| 60 | + |
| 61 | +See |
| 62 | +`CONTRIBUTING.md <https://github.com/adafruit/circuitpython/blob/main/CONTRIBUTING.md>`__ |
| 63 | +for full guidelines but please be aware that by contributing to this |
| 64 | +project you are agreeing to the `Code of |
| 65 | +Conduct <https://github.com/adafruit/circuitpython/blob/main/CODE_OF_CONDUCT.md>`__. |
| 66 | +Contributors who follow the `Code of |
| 67 | +Conduct <https://github.com/adafruit/circuitpython/blob/main/CODE_OF_CONDUCT.md>`__ |
| 68 | +are welcome to submit pull requests and they will be promptly reviewed |
| 69 | +by project admins. Please join the |
| 70 | +`Discord <https://adafru.it/discord>`__ too. |
| 71 | + |
| 72 | +Branding |
| 73 | +------------ |
| 74 | + |
| 75 | +While we are happy to see CircuitPython forked and modified, we'd appreciate it if forked releases |
| 76 | +not use the name "CircuitPython" or the Blinka logo. "CircuitPython" means something special to |
| 77 | +us and those who learn about it. As a result, we'd like to make sure products referring to it meet a |
| 78 | +common set of requirements. |
| 79 | + |
| 80 | +If you'd like to use the term "CircuitPython" and Blinka for your product here is what we ask: |
| 81 | + |
| 82 | +* Your product is supported by the primary |
| 83 | + `"adafruit/circuitpython" <https://github.com/adafruit/circuitpython>`_ repo. This way we can |
| 84 | + update any custom code as we update the CircuitPython internals. |
| 85 | +* Your product is listed on `circuitpython.org <https://circuitpython.org>`__ (source |
| 86 | + `here <https://github.com/adafruit/circuitpython-org/>`_). This is to ensure that a user of your |
| 87 | + product can always download the latest version of CircuitPython from the standard place. |
| 88 | +* Your product has a user accessible USB plug which appears as a CIRCUITPY drive when plugged in. |
| 89 | + |
| 90 | +If you choose not to meet these requirements, then we ask you call your version of CircuitPython |
| 91 | +something else (for example, SuperDuperPython) and not use the Blinka logo. You can say it is |
| 92 | +"CircuitPython-compatible" if most CircuitPython drivers will work with it. |
| 93 | + |
| 94 | +-------------- |
| 95 | + |
| 96 | +Differences from `MicroPython <https://github.com/micropython/micropython>`__ |
| 97 | +----------------------------------------------------------------------------- |
| 98 | + |
| 99 | +CircuitPython: |
| 100 | + |
| 101 | +- Supports native USB on all boards, allowing file editing without special tools. |
| 102 | +- Floats (aka decimals) are enabled for all builds. |
| 103 | +- Error messages are translated into 10+ languages. |
| 104 | +- Does not support concurrency within Python (including interrupts and threading). Some concurrency |
| 105 | + is achieved with native modules for tasks that require it such as audio file playback. |
| 106 | + |
| 107 | +Behavior |
| 108 | +~~~~~~~~ |
| 109 | + |
| 110 | +- The order that files are run and the state that is shared between |
| 111 | + them. CircuitPython's goal is to clarify the role of each file and |
| 112 | + make each file independent from each other. |
| 113 | +- ``boot.py`` (or ``settings.py``) runs only once on start up before |
| 114 | + USB is initialized. This lays the ground work for configuring USB at |
| 115 | + startup rather than it being fixed. Since serial is not available, |
| 116 | + output is written to ``boot_out.txt``. |
| 117 | +- ``code.py`` (or ``main.py``) is run after every reload until it |
| 118 | + finishes or is interrupted. After it is done running, the vm and |
| 119 | + hardware is reinitialized. **This means you cannot read state from** |
| 120 | + ``code.py`` **in the REPL anymore, as the REPL is a fresh vm.** CircuitPython's goal for this |
| 121 | + change includes reducing confusion about pins and memory being used. |
| 122 | +- After the main code is finished the REPL can be entered by pressing any key. |
| 123 | +- Autoreload state will be maintained across reload. |
| 124 | +- Adds a safe mode that does not run user code after a hard crash or |
| 125 | + brown out. The hope is that this will make it easier to fix code that |
| 126 | + causes nasty crashes by making it available through mass storage |
| 127 | + after the crash. A reset (the button) is needed after it's fixed to |
| 128 | + get back into normal mode. |
| 129 | +- RGB status LED indicating CircuitPython state, and errors through a sequence of colored flashes. |
| 130 | +- Re-runs ``code.py`` or other main file after file system writes over USB mass storage. (Disable with |
| 131 | + ``supervisor.disable_autoreload()``) |
| 132 | +- Autoreload is disabled while the REPL is active. |
| 133 | +- Main is one of these: ``code.txt``, ``code.py``, ``main.py``, |
| 134 | + ``main.txt`` |
| 135 | +- Boot is one of these: ``settings.txt``, ``settings.py``, ``boot.py``, |
| 136 | + ``boot.txt`` |
| 137 | + |
| 138 | +API |
| 139 | +~~~ |
| 140 | + |
| 141 | +- Unified hardware APIs. Documented on |
| 142 | + `ReadTheDocs <https://circuitpython.readthedocs.io/en/latest/shared-bindings/index.html>`_. |
| 143 | +- API docs are rST within the C files in ``shared-bindings``. |
| 144 | +- No ``machine`` API. |
| 145 | + |
| 146 | +Modules |
| 147 | +~~~~~~~ |
| 148 | + |
| 149 | +- No module aliasing. (``uos`` and ``utime`` are not available as |
| 150 | + ``os`` and ``time`` respectively.) Instead ``os``, ``time``, and |
| 151 | + ``random`` are CPython compatible. |
| 152 | +- New ``storage`` module which manages file system mounts. |
| 153 | + (Functionality from ``uos`` in MicroPython.) |
| 154 | +- Modules with a CPython counterpart, such as ``time``, ``os`` and |
| 155 | + ``random``, are strict |
| 156 | + `subsets <https://circuitpython.readthedocs.io/en/latest/shared-bindings/time/__init__.html>`__ |
| 157 | + of their `CPython |
| 158 | + version <https://docs.python.org/3.4/library/time.html?highlight=time#module-time>`__. |
| 159 | + Therefore, code from CircuitPython is runnable on CPython but not |
| 160 | + necessarily the reverse. |
| 161 | +- tick count is available as |
| 162 | + `time.monotonic() <https://circuitpython.readthedocs.io/en/latest/shared-bindings/time/__init__.html#time.monotonic>`__ |
| 163 | + |
| 164 | +-------------- |
| 165 | + |
| 166 | +Project Structure |
| 167 | +----------------- |
| 168 | + |
| 169 | +Here is an overview of the top-level source code directories. |
| 170 | + |
| 171 | +Core |
| 172 | +~~~~ |
| 173 | + |
| 174 | +The core code of |
| 175 | +`MicroPython <https://github.com/micropython/micropython>`__ is shared |
| 176 | +amongst ports including CircuitPython: |
| 177 | + |
| 178 | +- ``docs`` High level user documentation in Sphinx reStructuredText |
| 179 | + format. |
| 180 | +- ``drivers`` External device drivers written in Python. |
| 181 | +- ``examples`` A few example Python scripts. |
| 182 | +- ``extmod`` Shared C code used in multiple ports' modules. |
| 183 | +- ``lib`` Shared core C code including externally developed libraries |
| 184 | + such as FATFS. |
| 185 | +- ``logo`` The CircuitPython logo. |
| 186 | +- ``mpy-cross`` A cross compiler that converts Python files to byte |
| 187 | + code prior to being run in MicroPython. Useful for reducing library |
| 188 | + size. |
| 189 | +- ``py`` Core Python implementation, including compiler, runtime, and |
| 190 | + core library. |
| 191 | +- ``shared-bindings`` Shared definition of Python modules, their docs |
| 192 | + and backing C APIs. Ports must implement the C API to support the |
| 193 | + corresponding module. |
| 194 | +- ``shared-module`` Shared implementation of Python modules that may be |
| 195 | + based on ``common-hal``. |
| 196 | +- ``tests`` Test framework and test scripts. |
| 197 | +- ``tools`` Various tools, including the pyboard.py module. |
| 198 | + |
| 199 | +Ports |
| 200 | +~~~~~ |
| 201 | + |
| 202 | +Ports include the code unique to a microcontroller line. |
| 203 | + |
| 204 | +================ ============================================================ |
| 205 | +Supported Support status |
| 206 | +================ ============================================================ |
| 207 | +atmel-samd ``SAMD21`` stable | ``SAMD51`` stable |
| 208 | +cxd56 stable |
| 209 | +esp32s2 stable |
| 210 | +litex alpha |
| 211 | +mimxrt10xx alpha |
| 212 | +nrf stable |
| 213 | +raspberrypi stable |
| 214 | +stm ``F4`` stable | ``others`` beta |
| 215 | +unix alpha |
| 216 | +================ ============================================================ |
| 217 | + |
| 218 | +- ``stable`` Highly unlikely to have bugs or missing functionality. |
| 219 | +- ``beta`` Being actively improved but may be missing functionality and have bugs. |
| 220 | +- ``alpha`` Will have bugs and missing functionality. |
| 221 | + |
| 222 | +Boards |
| 223 | +~~~~~~ |
| 224 | + |
| 225 | +- Each ``port`` has a ``boards`` directory containing variations of boards |
| 226 | + which belong to a specific microcontroller line. |
| 227 | +- A list of native modules supported by a particular board can be found |
| 228 | + `here <https://circuitpython.readthedocs.io/en/latest/shared-bindings/support_matrix.html>`__. |
| 229 | + |
| 230 | +`Back to Top <#circuitpython>`__ |
| 231 | + |
| 232 | +.. |Build Status| image:: https://github.com/adafruit/circuitpython/workflows/Build%20CI/badge.svg |
| 233 | + :target: https://github.com/adafruit/circuitpython/actions?query=branch%3Amain |
| 234 | +.. |Doc Status| image:: https://readthedocs.org/projects/circuitpython/badge/?version=latest |
| 235 | + :target: http://circuitpython.readthedocs.io/ |
| 236 | +.. |Discord| image:: https://img.shields.io/discord/327254708534116352.svg |
| 237 | + :target: https://adafru.it/discord |
| 238 | +.. |License| image:: https://img.shields.io/badge/License-MIT-brightgreen.svg |
| 239 | + :target: https://choosealicense.com/licenses/mit/ |
| 240 | +.. |Weblate| image:: https://hosted.weblate.org/widgets/circuitpython/-/svg-badge.svg |
| 241 | + :target: https://hosted.weblate.org/engage/circuitpython/?utm_source=widget |
0 commit comments