Repository files navigation

This is the MicroPython project, which aims to put an implementationof Python 3.x on microcontrollers and small embedded systems.You can find the official website atmicropython.org.

WARNING: this project is in beta stage and is subject to changes of thecode-base, including project-wide name changes and API changes.

MicroPython implements the entire Python 3.4 syntax (including exceptions,with,yield from, etc., and additionallyasync/await keywords fromPython 3.5 and some select features from later versions). The following coredatatypes are provided:str(including basic Unicode support),bytes,bytearray,tuple,list,dict,set,frozenset,array.array,collections.namedtuple, classes and instances. Builtin modules includeos,sys,time,re, andstruct, etc. Some ports have support for_thread module (multithreading),socket andssl for networking, andasyncio. Note that only a subset of Python 3 functionality is implementedfor the data types and modules.

MicroPython can execute scripts in textual source form (.py files) or fromprecompiled bytecode (.mpy files), in both cases either from an on-devicefilesystem or "frozen" into the MicroPython executable.

MicroPython also provides a set of MicroPython-specific modules to accesshardware-specific functionality and peripherals such as GPIO, Timers, ADC,DAC, PWM, SPI, I2C, CAN, Bluetooth, and USB.

See theonline documentation for the APIreference and information about using MicroPython and information about howit is implemented.

We useGitHub Discussionsas our forum, andDiscord for chat. Theseare great places to ask questions and advice from the community or to discuss yourMicroPython-based projects.

For bugs and feature requests, pleaseraise an issueand follow the templates there.

For information about theMicroPython pyboard,the officially supported board from theoriginal Kickstarter campaign,see theschematics and pinouts anddocumentation.

MicroPython is an open-source project and welcomes contributions. To beproductive, please be sure to follow theContributors' Guidelinesand theCode Conventions.Note that MicroPython is licenced under the MIT license, and all contributionsshould follow this license.

This repository contains the following components:

• py/ -- the core Python implementation, including compiler, runtime, andcore library.
• mpy-cross/ -- the MicroPython cross-compiler which is used to turn scriptsinto precompiled bytecode.
• ports/ -- platform-specific code for the various ports and architectures that MicroPython runs on.
• lib/ -- submodules for external dependencies.
• tests/ -- test framework and test scripts.
• docs/ -- user documentation in Sphinx reStructuredText format. This is used to generate theonline documentation.
• extmod/ -- additional (non-core) modules implemented in C.
• tools/ -- various tools, including the pyboard.py module.
• examples/ -- a few example Python scripts.

"make" is used to build the components, or "gmake" on BSD-based systems.You will also need bash, gcc, and Python 3.3+ available as the commandpython3.Some ports (rp2 and esp32) additionally use CMake.

MicroPython runs on a wide range of microcontrollers, as well as on Unix-like(including Linux, BSD, macOS, WSL) and Windows systems.

Microcontroller targets can be as small as 256kiB flash + 16kiB RAM, althoughdevices with at least 512kiB flash + 128kiB RAM allow a much morefull-featured experience.

TheUnix andWindows ports allow bothdevelopment and testing of MicroPython itself, as well as providinglightweight alternative to CPython on these platforms (in particular onembedded Linux systems).

Over twenty different MicroPython ports are provided in this repository,split across threeMicroPython Support Tiers.

👑 Ports inTier 1are mature and have the most active development, support and testing:

An asterisk indicates that the port has ongoing financial support from the vendor.

✔ Ports inTier 2are less mature and less actively developed and tested than Tier 1, butstill fully supported:

Ports inTier 3are built in CI but not regularly tested by the MicroPython maintainers:

In addition to the above there is a Tier M containing ports that are usedprimarily for maintenance, development and testing:

• The"bare-arm" port is an example of the absolute minimumconfiguration that still includes the compiler, and is used to keep trackof the code size of the core runtime and VM.

• The"minimal" port provides an example of a very basicMicroPython port and can be compiled as both a standalone Linux binary aswell as for ARM Cortex-M4. Start with this if you want to port MicroPythonto another microcontroller.

• Theqemu port is a QEMU-based emulated target for Cortex-A,Cortex-M, RISC-V 32-bit and RISC-V 64-bit architectures.

Most ports require theMicroPython cross-compiler to be builtfirst. This program, called mpy-cross, is used to pre-compile Python scriptsto .mpy files which can then be included (frozen) into thefirmware/executable for a port. To build mpy-cross use:

$ cd mpy-cross$ make

The core MicroPython VM and runtime has no external dependencies, but a givenport might depend on third-party drivers or vendor HALs. This repositoryincludesseveral submodules linking to these external dependencies.Before compiling a given port, use

$ cd ports/name$ make submodules

to ensure that all required submodules are initialised.