Repository files navigation

CPython supports asynchronous programming via theasyncio library.MicroPython providesuasyncio which is a subset of this, optimised for smallcode size and high performance on bare metal targets. This repository providesdocumentation, tutorial material and code to aid in its effective use.

Damien has completely rewrittenuasyncio which has been released as V3.0. SeePR5332.

There is currently a choice to be made over whether to run V2 or V3. To run V2,ensure your firmware build is official MicroPython V1.12 and follow theuasyncio installation instructions inthe V2 tutorial. ForV3, install the latest daily build which includesuasyncio.

Resources for V3 and an updated tutorial may be found in the v3 directory.

The remainder of this document is for users of V2 and itsfast_io variant.

This repo also contains an optionalfast_io variant ofuasyncio V2. Thisvariant offers high I/O performance and also includes workrounds for many ofthe bugs in V2. (Bugs properly fixed in V3.)

In general I recommend V3, especially for new projects. It is better in everyrespect bar one: thefast_io variant of V2 currently offers superior I/Operformance, relative both to V2 and V3.

The main reason for running official V2 is that many existing libraries havenot yet been ported to V3. Some will run without change, but those using moreadvanced features ofuasyncio may not.

• A tutorial An introductory tutorial on asynchronousprogramming and the use of theuasyncio library.
• Asynchronous device drivers. A module providing drivers fordevices such as switches and pushbuttons.
• Synchronisation primitives. Provides commonly usedsynchronisation primitives plus an API for task cancellation and monitoring.
• A driver for an IR remote control This is intended asan example of an asynchronous device driver. It decodes signals received frominfra red remote controls using the popular NEC protocol.
• A driver for the HTU21D temperature and humiditysensor. This is intended to be portable across platforms and is anotherexample of an asynchronous device driver.
• A driver for character LCD displays. A simpleasynchronous interface to displays based on the Hitachi HD44780 chip.
• A driver for GPS modules Runs a background task to readand decode NMEA sentences, providing constantly updated position, course,altitude and time/date information.
• Communication using I2C slave mode. Enables a Pyboard toto communicate with another MicroPython device using stream I/O. The Pyboardachieves bidirectional communication with targets such as an ESP8266.
• Communication between devices Enables MicroPythonboards to communicate without using a UART. This is hardware agnostic butslower than the I2C version.

This comprises two parts.

1. Thefast_io version ofuasyncio is a "drop in"replacement for the official version 2 providing bug fixes, additionalfunctionality and, in certain respects, higher performance.
2. An optional extension module enabling thefast_io versionto run with very low power draw. This is Pyboard-only including Pyboard D.

Officialuasyncio suffers from high levels of latency when scheduling I/O intypical applications. It also has an issue which can cause bidirectionaldevices such as UART's to block. Thefast_io version fixes the bug. It alsoprovides a facility for reducing I/O latency which can substantially improvethe performance of stream I/O drivers. It provides other features aimed atproviding greater control over scheduling behaviour.

To take advantage of the reduced latency device drivers should be written toemploy stream I/O. To operate at low latency they are simply run under thefast_io version. Thetutorialhas details of how to write streaming drivers.

The currentfast_io version 0.24 fixes an issue with task cancellation andtimeouts. Inuasyncio version 2.0, where a coroutine is waiting on asleep() or on I/O, a timeout or cancellation is deferred until the coroutineis next scheduled. This introduces uncertainty into when the coroutine isstopped.

This is documentedhere. In essence a Python file isplaced on the device which configures thefast_io version ofuasyncio toreduce power consumption at times when it is not busy. This provides a means ofusinguasyncio in battery powered projects. This is decidedly experimental:hopefullyuasyncio V3 will introduce power saving in a less hacky manner.

Under the hood A guide to help understand the V2uasyncio code. For scheduler geeks and those wishing to modifyuasyncio.

All solutions listed below work with stockuasyncio V2 orfast_io.

The CPythonasyncio library supports these synchronisation primitives:

• Lock
• Event
• gather
• Semaphore andBoundedSemaphore.
• Condition.
• Queue. This was implemented by Paul Sokolvsky inuasyncio.queues.

SeeCPython docs.

The fileasyn.py contains implementations of these, also

• Barrier An additional synchronisation primitive.
• Cancellation decorators and classes: these are workrounds for the bug wherein V2 cancellation does not occur promptly.
• Support forgather.

TheEvent class inasyn.py provides a nonstandard option to supply a datavalue to the.set method and to retrieve this with.value. It is also anawaitable class.

The fileaswitch.py provides support for:

• Delay_ms A software retriggerable monostable or watchdog.
• Switch Debounced switch and pushbutton classes with callbacks.
• Pushbutton

These notes are intended for users familiar withasyncio under CPython.

The MicroPython language is based on CPython 3.4. Theuasyncio librarysupports a subset of the CPython 3.4asyncio library with some V3.5extensions. In addition there are non-standard extensions to optimise servicessuch as millisecond level timing and task cancellation. Its design focus is onhigh performance and scheduling is performed without RAM allocation.

Theuasyncio library supports the following Python 3.5 features:

• async def andawait syntax.
• Awaitable classes (using__iter__ rather than__await__).
• Asynchronous context managers.
• Asynchronous iterators.
• Event loop methodscall_soon andcall_later.
• sleep(seconds).

It supports millisecond level timing with the following:

• Event loop methodcall_later_ms
• uasynciosleep_ms(time)

uasyncio V2 supports coroutine timeouts and cancellation.

• wait_for(coro, t_secs) runscoro with a timeout.
• cancel(coro) tagscoro for cancellation when it is next scheduled.

ClassesTask andFuture are not supported.

Asynchronous I/O (StreamReader andStreamWriter classes) support deviceswith streaming drivers, such as UARTs and sockets. It is now possible to writestreaming device drivers in Python.

For timing asyncio uses floating point values of seconds. Theuasyncio.sleepmethod accepts floats (including sub-second values) or integers. Note that inMicroPython the use of floats implies RAM allocation which incurs a performancepenalty. The design ofuasyncio enables allocation-free scheduling. Inapplications where performance is an issue, integers should be used and themillisecond level functions (with integer arguments) employed where necessary.

Theloop.time method returns an integer number of milliseconds whereasCPython returns a floating point number of seconds.call_at follows thesame convention.