Move V2 resources to v2 directory.

Author: peterhinch

DRIVERS.md renamed to v2/DRIVERS.md

@@ -0,0 +1,166 @@
+# 1. uasyncio V2
+
+This repo also contains an optional `fast_io` variant of `uasyncio` V2. This
+variant offers high I/O performance and also includes workrounds for many of
+the bugs in V2. (Bugs properly fixed in V3.)
+
+## Reasons for running V2
+
+In general I recommend V3, especially for new projects. It is better in every
+respect bar one: the `fast_io` variant of V2 currently offers superior I/O
+performance, relative both to V2 and V3.
+
+The main reason for running official V2 is that many existing libraries have
+not yet been ported to V3. Some will run without change, but those using more
+advanced features of `uasyncio` may not.
+
+## 1.1 Resources
+
+ * [A tutorial](./TUTORIAL.md) An introductory tutorial on asynchronous
+ programming and the use of the `uasyncio` library.
+ * [Asynchronous device drivers](./DRIVERS.md). A module providing drivers for
+ devices such as switches and pushbuttons.
+ * [Synchronisation primitives](./PRIMITIVES.md). Provides commonly used
+ synchronisation primitives plus an API for task cancellation and monitoring.
+ * [A driver for an IR remote control](./nec_ir/README.md) 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](./htu21d/README.md) 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](./HD44780/README.md). A simple
+ asynchronous interface to displays based on the Hitachi HD44780 chip.
+ * [A driver for GPS modules](./gps/README.md) 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.](./i2c/README.md) 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](./syncom_as/README.md) Enables MicroPython
+ boards to communicate without using a UART. This is hardware agnostic but
+ slower than the I2C version.
+ 
+## 1.2 The fast_io variant
+
+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.
+
+Official `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](./TUTORIAL.md#64-writing-streaming-device-drivers)
+has details of how to write streaming drivers.
+
+The current `fast_io` version 0.24 fixes an issue with task cancellation and
+timeouts. In `uasyncio` version 2.0, where a coroutine is waiting on a
+`sleep()` or on I/O, a timeout or cancellation is deferred until the coroutine
+is next scheduled. This introduces uncertainty into when the coroutine is
+stopped.
+
+## 1.2.1 A Pyboard-only low power module
+
+This is documented [here](./lowpower/README.md). In essence a Python file is
+placed on the device which configures the `fast_io` version of `uasyncio` to
+reduce power consumption at times when it is not busy. This provides a means of
+using `uasyncio` in battery powered projects. This is decidedly experimental:
+hopefully `uasyncio` V3 will introduce power saving in a less hacky manner.
+
+## 1.3 Under the hood
+
+[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`.
+
+## 1.4 Synchronisation Primitives
+
+All solutions listed below work with stock `uasyncio` V2 or `fast_io`.
+
+The CPython `asyncio` library supports these synchronisation primitives:
+ * `Lock`
+ * `Event`
+ * `gather`
+ * `Semaphore` and `BoundedSemaphore`.
+ * `Condition`.
+ * `Queue`. This was implemented by Paul Sokolvsky in `uasyncio.queues`.
+
+See [CPython docs](https://docs.python.org/3/library/asyncio-sync.html).
+
+The file `asyn.py` contains implementations of these, also
+ * `Barrier` An additional synchronisation primitive.
+ * Cancellation decorators and classes: these are workrounds for the bug where
+ in V2 cancellation does not occur promptly.
+ * Support for `gather`.
+
+The `Event` class in `asyn.py` provides a nonstandard option to supply a data
+value to the `.set` method and to retrieve this with `.value`. It is also an
+awaitable class.
+
+#### These are documented [here](./PRIMITIVES.md)
+
+## 1.5 Switches, Pushbuttons and Timeouts
+
+The file `aswitch.py` provides support for:
+ * `Delay_ms` A software retriggerable monostable or watchdog.
+ * `Switch` Debounced switch and pushbutton classes with callbacks.
+ * `Pushbutton`
+
+#### It is documented [here](./DRIVERS.md)
+
+# 2. Version 2.0 usage notes
+
+These notes are intended for users familiar with `asyncio` under CPython.
+
+The MicroPython language is based on CPython 3.4. The `uasyncio` library
+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.
+
+The `uasyncio` library supports the following Python 3.5 features:
+
+ * `async def` and `await` syntax.
+ * Awaitable classes (using `__iter__` rather than `__await__`).
+ * Asynchronous context managers.
+ * Asynchronous iterators.
+ * Event loop methods `call_soon` and `call_later`.
+ * `sleep(seconds)`.
+
+It supports millisecond level timing with the following:
+
+ * Event loop method `call_later_ms`
+ * uasyncio `sleep_ms(time)`
+
+`uasyncio` V2 supports coroutine timeouts and cancellation.
+
+ * `wait_for(coro, t_secs)` runs `coro` with a timeout.
+ * `cancel(coro)` tags `coro` for cancellation when it is next scheduled.
+
+Classes `Task` and `Future` are not supported.
+
+## 2.1 Asynchronous I/O
+
+Asynchronous I/O (`StreamReader` and `StreamWriter` classes) support devices
+with streaming drivers, such as UARTs and sockets. It is now possible to write
+streaming device drivers in Python.
+
+## 2.2 Time values
+
+For timing asyncio uses floating point values of seconds. The `uasyncio.sleep`
+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.
+
+The `loop.time` method returns an integer number of milliseconds whereas
+CPython returns a floating point number of seconds. `call_at` follows the
+same convention.

FASTPOLL.md renamed to v2/FASTPOLL.md

@@ -0,0 +1,231 @@
+# aswitch.py Switch and pushbutton classes for asyncio
+# Delay_ms A retriggerable delay class. Can schedule a coro on timeout.
+# Switch Simple debounced switch class for normally open grounded switch.
+# Pushbutton extend the above to support logical state, long press and
+# double-click events
+# Tested on Pyboard but should run on other microcontroller platforms
+# running MicroPython and uasyncio.
+
+# The MIT License (MIT)
+#
+# Copyright (c) 2017 Peter Hinch
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+# THE SOFTWARE.
+
+import uasyncio as asyncio
+import utime as time
+# Remove dependency on asyn to save RAM:
+# launch: run a callback or initiate a coroutine depending on which is passed.
+async def _g():
+    pass
+type_coro = type(_g())
+
+# If a callback is passed, run it and return.
+# If a coro is passed initiate it and return.
+# coros are passed by name i.e. not using function call syntax.
+def launch(func, tup_args):
+    res = func(*tup_args)
+    if isinstance(res, type_coro):
+        loop = asyncio.get_event_loop()
+        loop.create_task(res)
+
+
+class Delay_ms:
+    verbose = False
+    def __init__(self, func=None, args=(), can_alloc=True, duration=1000):
+        self.func = func
+        self.args = args
+        self.can_alloc = can_alloc
+        self.duration = duration  # Default duration
+        self._tstop = None  # Killer not running
+        self._running = False  # Timer not running
+        self.loop = asyncio.get_event_loop()
+        if not can_alloc:
+            self.loop.create_task(self._run())
+
+    async def _run(self):
+        while True:
+            if not self._running:  # timer not running
+                await asyncio.sleep_ms(0)
+            else:
+                await self._killer()
+
+    def stop(self):
+        self._running = False
+        # If uasyncio is ever fixed we should cancel .killer
+
+    def trigger(self, duration=0):  # Update end time
+        self._running = True
+        if duration <= 0:
+            duration = self.duration
+        tn = time.ticks_add(time.ticks_ms(), duration)  # new end time
+        self.verbose and self._tstop is not None and self._tstop > tn \
+            and print("Warning: can't reduce Delay_ms time.")
+        # Start killer if can allocate and killer is not running
+        sk = self.can_alloc and self._tstop is None
+        # The following indicates ._killer is running: it will be
+        # started either here or in ._run
+        self._tstop = tn
+        if sk:  # ._killer stops the delay when its period has elapsed
+            self.loop.create_task(self._killer())
+
+    def running(self):
+        return self._running
+
+    __call__ = running
+
+    async def _killer(self):
+        twait = time.ticks_diff(self._tstop, time.ticks_ms())
+        while twait > 0:  # Must loop here: might be retriggered
+            await asyncio.sleep_ms(twait)
+            if self._tstop is None:
+                break  # Return if stop() called during wait
+            twait = time.ticks_diff(self._tstop, time.ticks_ms())
+        if self._running and self.func is not None:
+            launch(self.func, self.args)  # Timed out: execute callback
+        self._tstop = None  # killer not running
+        self._running = False  # timer is stopped
+
+class Switch:
+    debounce_ms = 50
+    def __init__(self, pin):
+        self.pin = pin # Should be initialised for input with pullup
+        self._open_func = False
+        self._close_func = False
+        self.switchstate = self.pin.value()  # Get initial state
+        loop = asyncio.get_event_loop()
+        loop.create_task(self.switchcheck())  # Thread runs forever
+
+    def open_func(self, func, args=()):
+        self._open_func = func
+        self._open_args = args
+
+    def close_func(self, func, args=()):
+        self._close_func = func
+        self._close_args = args
+
+    # Return current state of switch (0 = pressed)
+    def __call__(self):
+        return self.switchstate
+
+    async def switchcheck(self):
+        while True:
+            state = self.pin.value()
+            if state != self.switchstate:
+                # State has changed: act on it now.
+                self.switchstate = state
+                if state == 0 and self._close_func:
+                    launch(self._close_func, self._close_args)
+                elif state == 1 and self._open_func:
+                    launch(self._open_func, self._open_args)
+            # Ignore further state changes until switch has settled
+            await asyncio.sleep_ms(Switch.debounce_ms)
+
+# An alternative Pushbutton solution with lower RAM use is available here
+# https://github.com/kevinkk525/pysmartnode/blob/dev/pysmartnode/utils/abutton.py
+class Pushbutton:
+    debounce_ms = 50
+    long_press_ms = 1000
+    double_click_ms = 400
+    def __init__(self, pin, suppress=False):
+        self.pin = pin # Initialise for input
+        self._supp = suppress
+        self._dblpend = False  # Doubleclick waiting for 2nd click
+        self._dblran = False  # Doubleclick executed user function
+        self._tf = False
+        self._ff = False
+        self._df = False
+        self._lf = False
+        self._ld = False  # Delay_ms instance for long press
+        self._dd = False  # Ditto for doubleclick
+        self.sense = pin.value()  # Convert from electrical to logical value
+        self.state = self.rawstate()  # Initial state
+        loop = asyncio.get_event_loop()
+        loop.create_task(self.buttoncheck())  # Thread runs forever
+
+    def press_func(self, func, args=()):
+        self._tf = func
+        self._ta = args
+
+    def release_func(self, func, args=()):
+        self._ff = func
+        self._fa = args
+
+    def double_func(self, func, args=()):
+        self._df = func
+        self._da = args
+
+    def long_func(self, func, args=()):
+        self._lf = func
+        self._la = args
+
+    # Current non-debounced logical button state: True == pressed
+    def rawstate(self):
+        return bool(self.pin.value() ^ self.sense)
+
+    # Current debounced state of button (True == pressed)
+    def __call__(self):
+        return self.state
+
+    def _ddto(self):  # Doubleclick timeout: no doubleclick occurred
+        self._dblpend = False
+        if self._supp and not self.state:
+            if not self._ld or (self._ld and not self._ld()):
+                launch(self._ff, self._fa)
+
+    async def buttoncheck(self):
+        if self._lf:  # Instantiate timers if funcs exist
+            self._ld = Delay_ms(self._lf, self._la)
+        if self._df:
+            self._dd = Delay_ms(self._ddto)
+        while True:
+            state = self.rawstate()
+            # State has changed: act on it now.
+            if state != self.state:
+                self.state = state
+                if state:  # Button pressed: launch pressed func
+                    if self._tf:
+                        launch(self._tf, self._ta)
+                    if self._lf:  # There's a long func: start long press delay
+                        self._ld.trigger(Pushbutton.long_press_ms)
+                    if self._df:
+                        if self._dd():  # Second click: timer running
+                            self._dd.stop()
+                            self._dblpend = False
+                            self._dblran = True  # Prevent suppressed launch on release
+                            launch(self._df, self._da)
+                        else:
+                            # First click: start doubleclick timer
+                            self._dd.trigger(Pushbutton.double_click_ms)
+                            self._dblpend = True  # Prevent suppressed launch on release
+                else:  # Button release. Is there a release func?
+                    if self._ff:
+                        if self._supp:
+                            d = self._ld 
+                            # If long delay exists, is running and doubleclick status is OK
+                            if not self._dblpend and not self._dblran:
+                                if (d and d()) or not d:
+                                    launch(self._ff, self._fa)
+                        else:
+                            launch(self._ff, self._fa)
+                    if self._ld:
+                        self._ld.stop()  # Avoid interpreting a second click as a long push
+                    self._dblran = False
+            # Ignore state changes until switch has settled
+            await asyncio.sleep_ms(Pushbutton.debounce_ms)