Prior to v3 directory

Author: peterhinch

README.md

@@ -6,20 +6,23 @@ code size and high performance on bare metal targets. This repository provides
 documentation, tutorial material and code to aid in its effective use. It also
 contains an optional `fast_io` variant of `uasyncio`.
 
-Damien has completely rewritten `uasyncio`. Its release is likely to be
-imminent, see
+Damien has completely rewritten `uasyncio`. V3.0 now been released, see
 [PR5332](https://github.com/micropython/micropython/pull/5332) and [below](./README.md#31-the-new-version).
 
-## The fast_io variant
+#### NOTE ON NEW RELEASE
 
-This comprises two parts.  
- 1. The [fast_io](./FASTPOLL.md) version of `uasyncio` is a "drop in"
- replacement for the official version providing bug fixes, additional
- functionality and, in certain respects, higher performance.
- 2. An optional extension module enabling the [fast_io](./FASTPOLL.md) version
- to run with very low power draw. This is Pyboard-only including Pyboard D.
+The material in this repo largely relates to the old version V2.0 and I intend
+a substantial revision. I believe most of the material in the tutorial is still
+valid as it aims to be CPython compatible. I also expect the example scripts to
+work, based on testing with pre-release versions.
+
+There is currently no support for fast I/O scheduling: I/O is scheduled in
+round robin fashion with other tasks. There are situations where this is too
+slow, for example in I2S applications and ones involving multiple fast I/O
+streams. In these applications there is still a use case for the fast_io
+version. I hope that the new version acquires a facility to prioritise I/O.
 
-## Resources for users of all versions
+## Resources
 
  * [A tutorial](./TUTORIAL.md) An introductory tutorial on asynchronous
  programming and the use of the `uasyncio` library.
@@ -44,33 +47,27 @@ This comprises two parts.
  * [Communication between devices](./syncom_as/README.md) Enables MicroPython
  boards to communicate without using a UART. This is hardware agnostic but
  slower than the I2C version.
- * [Under the hood](./UNDER_THE_HOOD.md) A guide to help understand the
- `uasyncio` code. For scheduler geeks and those wishing to modify `uasyncio`.
 
-# 2. Version and installation of uasyncio
+## Resources specific to V2.0
 
-Paul Sokolovsky (`uasyncio` author) has released versions of `uasyncio` which
-supercede the official version. His latest version is that on PyPi and requires
-his [Pycopy](https://github.com/pfalcon/micropython) fork of MicroPython
-firmware. His `uasyncio` code may also be found in
-[his fork of micropython-lib](https://github.com/pfalcon/micropython-lib).
+### The fast_io variant
 
-I support only the official build of MicroPython. The library code guaranteed
-to work with this build is in [micropython-lib](https://github.com/micropython/micropython-lib).
-Most of the resources in here should work with Paul's forks (most work with
-CPython).
+This comprises two parts.  
+ 1. The [fast_io](./FASTPOLL.md) version of `uasyncio` is a "drop in"
+ replacement for the official version 2 providing bug fixes, additional
+ functionality and, in certain respects, higher performance.
+ 2. An optional extension module enabling the [fast_io](./FASTPOLL.md) version
+ to run with very low power draw. This is Pyboard-only including Pyboard D.
 
-Most documentation and code in this repository assumes the current official
-version of `uasyncio`. This is V2.0 from
-[micropython-lib](https://github.com/micropython/micropython-lib).
-It is recommended to use MicroPython firmware V1.11 or later. On many platforms
-`uasyncio` is incorporated and no installation is required.
+### Under the hood
 
-Some examples illustrate features of the `fast_io` fork and therefore require
-this version.
+[Under the hood](./UNDER_THE_HOOD.md) A guide to help understand the V2
+`uasyncio` code. For scheduler geeks and those wishing to modify `uasyncio`.
+ 
+# 2. Version and installation of uasyncio
 
-See [tutorial](./TUTORIAL.md#installing-uasyncio-on-bare-metal) for
-installation instructions where `uasyncio` is not pre-installed.
+The new release of `uasyncio` is pre-installed in current daily firmware 
+builds.
 
 # 3. uasyncio development state
 
@@ -97,12 +94,8 @@ following features will involve minor changes to application code:
 
 It is planned to retain V2 under a different name. The new version fixes bugs
 which have been outstanding for a long time. In my view V2 is best viewed as
-deprecated. I will retain V2-specific code and docs in a separate directory,
-with the rest of this repo being adapted for the new version.
-
-#### 3.1.1.1 Tutorial
-
-This requires only minor changes.
+deprecated. I will support V3 in a separate directory, the resources in this
+directory being retained for existing applications and users of V2 and fast_io.
 
 #### 3.1.1.2 Fast I/O
 

nec_ir/README.md

@@ -10,14 +10,14 @@ The driver and test programs run on the Pyboard and ESP8266.
 
 # Files
 
- 1. ``aremote.py`` The device driver.
- 2. ``art.py`` A test program to characterise a remote.
- 3. ``art1.py`` Control an onboard LED using a remote. The data and addresss
+ 1. `aremote.py` The device driver.
+ 2. `art.py` A test program to characterise a remote.
+ 3. `art1.py` Control an onboard LED using a remote. The data and addresss
  values need changing to match your characterised remote.
 
 # Dependencies
 
-The driver requires the ``uasyncio`` library and the file ``asyn.py`` from this
+The driver requires the `uasyncio` library and the file `asyn.py` from this
 repository.
 
 # Usage
@@ -36,10 +36,10 @@ Data values are 8 bit. Addresses may be 8 or 16 bit depending on whether the
 remote uses extended addressing.
 
 If a button is held down a repeat code is sent. In this event the driver
-returns a data value of ``REPEAT`` and the address associated with the last
+returns a data value of `REPEAT` and the address associated with the last
 valid data block.
 
-To characterise a remote run ``art.py`` and note the data value for each button
+To characterise a remote run `art.py` and note the data value for each button
 which is to be used. If the address is less than 256, extended addressing is
 not in use.
 
@@ -48,7 +48,7 @@ not in use.
 IR reception is inevitably subject to errors, notably if the remote is operated
 near the limit of its range, if it is not pointed at the receiver or if its
 batteries are low. So applications must check for, and usually ignore, errors.
-These are flagged by data values < ``REPEAT``.
+These are flagged by data values < `REPEAT`.
 
 On the ESP8266 there is a further source of errors. This results from the large
 and variable interrupt latency of the device which can exceed the pulse
@@ -62,21 +62,21 @@ Users tend to press the key again if no acknowledgement is received.
 
 The constructor takes the following positional arguments.
 
- 1. ``pin`` A ``Pin`` instance for the decoder chip.
- 2. ``cb`` The user callback function.
- 3. ``extended`` Set ``False`` to enable extra error checking if the remote
+ 1. `pin` A `Pin` instance for the decoder chip.
+ 2. `cb` The user callback function.
+ 3. `extended` Set `False` to enable extra error checking if the remote
  returns an 8 bit address.
  4. Further arguments, if provided, are passed to the callback.
 
 The callback receives the following positional arguments:
 
  1. The data value returned from the remote.
  2. The address value returned from the remote.
- 3. Any further arguments provided to the ``NEC_IR`` constructor.
+ 3. Any further arguments provided to the `NEC_IR` constructor.
 
 Negative data values are used to signal repeat codes and transmission errors.
 
-The test program ``art1.py`` provides an example of a minimal application.
+The test program `art1.py` provides an example of a minimal application.
 
 # How it works
 
@@ -103,7 +103,7 @@ interrupt in a burst sets an event, passing the time of the state change. A
 coroutine waits on the event, yields for the duration of a data burst, then
 decodes the stored data before calling the user-specified callback.
 
-Passing the time to the ``Event`` instance enables the coro to compensate for
+Passing the time to the `Event` instance enables the coro to compensate for
 any asyncio latency when setting its delay period.
 
 The algorithm promotes interrupt handler speed over RAM use: the 276 bytes used
@@ -115,19 +115,19 @@ in the interrupt service routine.
 Data values passed to the callback are normally positive. Negative values
 indicate a repeat code or an error.
 
-``REPEAT`` A repeat code was received.
+`REPEAT` A repeat code was received.
 
-Any data value < ``REPEAT`` denotes an error. In general applications do not
+Any data value < `REPEAT` denotes an error. In general applications do not
 need to decode these, but they may be of use in debugging. For completeness
 they are listed below.
 
-``BADSTART`` A short (<= 4ms) start pulse was received. May occur due to IR
+`BADSTART` A short (<= 4ms) start pulse was received. May occur due to IR
 interference, e.g. from fluorescent lights. The TSOP4838 is prone to producing
 200µs pulses on occasion, especially when using the ESP8266.  
-``BADBLOCK`` A normal data block: too few edges received. Occurs on the ESP8266
+`BADBLOCK` A normal data block: too few edges received. Occurs on the ESP8266
 owing to high interrupt latency.  
-``BADREP`` A repeat block: an incorrect number of edges were received.  
-``OVERRUN`` A normal data block: too many edges received.  
-``BADDATA`` Data did not match check byte.  
-``BADADDR`` Where ``extended`` is ``False`` the 8-bit address is checked
+`BADREP` A repeat block: an incorrect number of edges were received.  
+`OVERRUN` A normal data block: too many edges received.  
+`BADDATA` Data did not match check byte.  
+`BADADDR` Where `extended` is `False` the 8-bit address is checked
 against the check byte. This code is returned on failure.