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(if your system only has Python 2.7 then invoke make with the additional optionPYTHON=python2). 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).

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 MicroPython toanother microcontroller. Additionally the"bare-arm" portis an example of the absolute minimum configuration, and is used to keeptrack of the code size of the core runtime and VM.

In addition, the following ports are provided in this repository:

• cc3200 -- Texas Instruments CC3200 (including PyCom WiPy).
• esp32 -- Espressif ESP32 SoC (including ESP32S2, ESP32S3, ESP32C3, ESP32C6).
• esp8266 -- Espressif ESP8266 SoC.
• mimxrt -- NXP m.iMX RT (including Teensy 4.x).
• nrf -- Nordic Semiconductor nRF51 and nRF52.
• pic16bit -- Microchip PIC 16-bit.
• powerpc -- IBM PowerPC (including Microwatt)
• qemu -- QEMU-based emulated target (for testing)
• renesas-ra -- Renesas RA family.
• rp2 -- Raspberry Pi RP2040 (including Pico and Pico W).
• samd -- Microchip (formerly Atmel) SAMD21 and SAMD51.
• stm32 -- STMicroelectronics STM32 family (including F0, F4, F7, G0, G4, H7, L0, L4, WB)
• webassembly -- Emscripten port targeting browsers and NodeJS.
• zephyr -- Zephyr RTOS.

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.