Home

Welcome to the MicroPython Wiki!

This is the wiki for the MicroPython project, which puts an implementation of Python 3.x on a microcontroller or embedded system.

This wiki complements the official documentation and aims to provide a place for community-edited documentation, tips, tricks, and guides. Anyone with a GitHub account can contribute.

This wiki replaces the former Gollum Wiki on micropython.org and the content from there is being migrated over. In the meantime, you can access it here.

MicroPython: a beginner's guide

The following hints result from problems that have frequently arisen in Discussions and in the former Forum. The notes are intended for those new to microcontroller programming.

1. Learn the basics of Python

It's worth getting familiar with the language before using it in a microcontroller context. This is best done on a PC with an online course or an introductory textbook. With a basic grasp of the language it's a good idea to study its use on microcontrollers (official doc).

2. Choose your hardware with care

Perhaps you want to measure temperature and display it on a screen. Beginners often rush out and buy hardware, then start trying to figure out how to use it. The problem is that hardware devices usually need a device driver. This is a program provding an application program interface (API) for the device. Writing device drivers is not a beginner task; numerous drivers for MicroPython have been written and published. You are advised to seek devices for which a driver already exists.

Platforms to run MicroPython also have different characteristics. If you have special requirements such a battery powered operation or high speed I/O, search discussions and if necessary request help before spending money.

3. Concurrency

Most firmware applications need to do several things at once. You might want to detect a button press while taking regular temperature readings and updating a display.

You've read the adverts which promise these powerful features:

• Timers
• Interrupts
• Threading
• Multi-core (on some boards)

All of these promise concurrency, but using them requires care and some reading.

These features are powerful but require some expertise to deploy effectively in an application; they carry risks of introducing subtle bugs. They are rarely the best way to achieve concurrency. In most cases the best approach is known as cooperative multi-tasking and the Python implementation is a library called asyncio.

Either way you probably have some reading to do. Learn asyncio or learn how to write reliable code using the magic features.

• Asyncio official docs.
• Asyncio unofiicial tutorial.
• Interrupts official guide - also applies to timer callbacks.

Writing code for threading and multi-core is particularly challenging. There is no official guide. This unofficial doc provides some guidance but does assume some MicroPython knowledge.

4. Requesting help

Please post a request in Discussions. Choose a topic appropriate to your query and write a title which summarises your problem. Please indicate when the issue has been resolved. Also avoid spamming multiple root messages about the same issue as it makes it hard to provide a coherent response or for helpers to know if the issue is resolved. Your request will be seen, and if someone has an idea how to fix it they will respond.

5. Bug reports

Please raise issues against MicroPython only if you are convinced that you have found a bug in MicroPython. Examples of bugs are when the same code sample produces a different outcome in MicroPython compared to CPython. Study the list of differences between MicroPython and CPython to be sure this isn't a known isse.

If you're unsure whether something is a bug please ask in discussions before raising an issue: the maintainers are busy and you will probably get a quicker response.

To report a bug provide a minimal code sample that reproduces the bug with details of how it should be run - hardware, firmware build, any necessary wiring. Choose the issue title with care, identfying the hardware platform at the start of the line. For example (fictitious bug)

rp2: RTC runs backwards on 32nd of month.

This will ensure that the report is seen by the appropriate maintainer.