1. The MicroPython uasyncio library
This repository comprises the following parts.
- A modified fast_io version of
uasyncio. This is a "drop in" replacement for the official version providing additional functionality.
- A module enabling the fast_io version to run with very low power draw.
- Resources for users of official or fast_io versions:
- A tutorial An introductory tutorial on asynchronous
programming and the use of the
uasynciolibrary (asyncio subset).
- Asynchronous device drivers. A module providing drivers for devices such as switches and pushbuttons.
- Synchronisation primitives. Provides commonly used synchronisation primitives plus an API for task cancellation and monitoring.
- A driver for an IR remote control This is intended as an example of an asynchronous device driver. It decodes signals received from infra red remote controls using the popular NEC protocol.
- A driver for the HTU21D temperature and humidity sensor. This is intended to be portable across platforms and is another example of an asynchronous device driver.
- A driver for character LCD displays. A simple asynchronous interface to displays based on the Hitachi HD44780 chip.
- A driver for GPS modules Runs a background task to read and decode NMEA sentences, providing constantly updated position, course, altitude and time/date information.
- Communication using I2C slave mode. Enables a Pyboard to to communicate with another MicroPython device using stream I/O. The Pyboard achieves bidirectional communication with targets such as an ESP8266.
- Communication between devices Enables MicroPython boards to communicate without using a UART. This is hardware agnostic but slower than the I2C version.
- Under the hood A guide to help understand the
uasynciocode. For scheduler geeks and those wishing to modify
2. Version and installation of uasyncio
The documentation and code in this repository assume
2.0.x, which is the version on PyPi and in the official micropython-lib. This
requires firmware dated 22nd Feb 2018 or later. Use of the stream I/O mechanism
requires firmware after 17th June 2018.
See tutorial for installation instructions.
3. uasyncio development state
These notes are intended for users familiar with
asyncio under CPython.
The MicroPython language is based on CPython 3.4. The
supports a subset of the CPython 3.4
asyncio library with some V3.5
extensions. In addition there are non-standard extensions to optimise services
such as millisecond level timing and task cancellation. Its design focus is on
high performance and scheduling is performed without RAM allocation.
uasyncio library supports the following Python 3.5 features:
- Awaitable classes (using
- Asynchronous context managers.
- Asynchronous iterators.
- Event loop methods
It supports millisecond level timing with the following:
- Event loop method
uasyncio V2 supports coroutine timeouts and cancellation.
corowith a timeout.
corofor cancellation when it is next scheduled.
Future are not supported.
3.1 Asynchronous I/O
Asynchronous I/O (
StreamWriter classes) support devices
with streaming drivers, such as UARTs and sockets. It is now possible to write
streaming device drivers in Python.
3.2 Time values
For timing asyncio uses floating point values of seconds. The
method accepts floats (including sub-second values) or integers. Note that in
MicroPython the use of floats implies RAM allocation which incurs a performance
penalty. The design of
uasyncio enables allocation-free scheduling. In
applications where performance is an issue, integers should be used and the
millisecond level functions (with integer arguments) employed where necessary.
loop.time method returns an integer number of milliseconds whereas
CPython returns a floating point number of seconds.
call_at follows the
4. The "fast_io" version.
uasyncio suffers from high levels of latency when scheduling I/O in
typical applications. It also has an issue which can cause bidirectional
devices such as UART's to block. The
fast_io version fixes the bug. It also
provides a facility for reducing I/O latency which can substantially improve
the performance of stream I/O drivers. It provides other features aimed at
providing greater control over scheduling behaviour.
To take advantage of the reduced latency device drivers should be written to
employ stream I/O. To operate at low latency they are simply run under the
fast_io version. The tutorial
has details of how to write streaming drivers.
4.1 A Pyboard-only low power module
This is documented here. In essence a Python file is
placed on the device which configures the
fast_io version of
reduce power consumption at times when it is not busy. This provides a means of
uasyncio in battery powered projects.
4.2 Historical note
This repo formerly included
asyncio_priority.py which is obsolete. Its main
purpose was to provide a means of servicing fast hardware devices by means of
coroutines running at a high priority. This was essentially a workround.
The official firmware now includes
this major improvement
which offers a much more efficient way of achieving the same end using stream
I/O and efficient polling using
5. The asyn.py library
It also supports a
Barrier class to facilitate coroutine synchronisation.
Coroutine cancellation is performed in an efficient manner in
asyn library uses this, further enabling the cancelling coro to pause until
cancellation is complete. It also provides a means of checking the 'running'
status of individual coroutines.
A lightweight implementation of
asyncio.gather is provided.