Repository files navigation

This repository comprises the following parts.

1. A modifiedfast_io version ofuasyncio. This is a "dropin" replacement for the official version providing additional functionality.
2. A module enabling thefast_io version to run with very lowpower draw.
3. Resources for users of official orfast_io versions:

• A tutorial An introductory tutorial on asynchronousprogramming and the use of theuasyncio library (asyncio subset).
• 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.
• Under the hood A guide to help understand theuasyncio code. For scheduler geeks and those wishing to modifyuasyncio.

The documentation and code in this repository assumeuasyncio version2.0.x, which is the version on PyPi and in the official micropython-lib. Thisrequires firmware dated 22nd Feb 2018 or later. Use of the stream I/O mechanismrequires firmware after 17th June 2018.

Seetutorial forinstallation instructions.

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.

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.

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 repo formerly includedasyncio_priority.py which is obsolete. Its mainpurpose was to provide a means of servicing fast hardware devices by means ofcoroutines running at a high priority. This was essentially a workround.

The official firmware now includesthis major improvementwhich offers a much more efficient way of achieving the same end using streamI/O and efficient polling usingselect.poll.

This library (docs) provides 'micro' implementations of theasyncio synchronisation primitives.CPython docs

It also supports aBarrier class to facilitate coroutine synchronisation.

Coroutine cancellation is performed in an efficient manner inuasyncio. Theasyn library uses this, further enabling the cancelling coro to pause untilcancellation is complete. It also provides a means of checking the 'running'status of individual coroutines.

A lightweight implementation ofasyncio.gather is provided.