Repository files navigation

This GitHub repository consists of the following parts. Firstly a modifiedfast_io version ofuasyncio offering some benefits over the officialversion.

Secondly the following resources relevant to users of official orfast_ioversions:

• A tutorial An introductory tutorial on asynchronousprogramming and the use of the uasyncio 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 between devices Enables MicroPythonboards to communicate without using a UART. Primarily intended to enable aa Pyboard-like device to achieve bidirectional communication with an ESP8266.
• Under the hood A guide to help understand theuasyncio code. For scheduler geeks and those wishing to modifyuasyncio.

This repo includedasyncio_priority.py which is now deprecated. Its primarypurpose was to provide a means of servicing fast hardware devices by means ofcoroutines running at a high priority. The official firmware now includesthis major improvementwhich offers a much more efficient way of achieving this end. The tutorial hasdetails of how to use this.

The currentuasyncio suffers from high levels of latency when scheduling I/Oin typical applications. It also has an issue which can cause bidirectionaldevices such as UART's to block.

A modified version ofuasyncio is describedhere whichprovides an option for I/O scheduling with much reduced latency. It also fixesthe bug. It is hoped that these changes will be accepted into mainstream in duecourse.

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 ofusing the library on battery powered projects.

The documentation and code in this repository are based onuasyncio version2.0, 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.

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.