Low power version added.

Author: peterhinch

FASTPOLL.md

@@ -225,6 +225,14 @@ This behaviour may be desired where short bursts of fast data are handled.
 Otherwise drivers of such hardware should be designed to avoid hogging, using
 techniques like buffering or timing.
 
+The version also supports an `implementation` namedtuple with the following
+fields:
+ * `name` 'fast_io'
+ * `variant` `standard`
+ * `major` 0 Major version no.
+ * `minor` 100 Minor version no. i.e. version = 0.100
+
+The `variant` field can also contain `lowpower` if running that version.
 
 ###### [Contents](./FASTPOLL.md#contents)
 

README.md

@@ -1,6 +1,11 @@
 # 1. The MicroPython uasyncio library
 
-This GitHub repository consists of the following parts:
+This GitHub repository consists of the following parts. Firstly a modified
+`fast_io` version of `uasyncio` offering some benefits over the official
+version.
+
+Secondly the following resources relevant to users of official or `fast_io`
+versions:
  * [A tutorial](./TUTORIAL.md) An introductory tutorial on asynchronous
  programming and the use of the uasyncio library (asyncio subset).
  * [Asynchronous device drivers](./DRIVERS.md). A module providing drivers for
@@ -24,7 +29,7 @@ This GitHub repository consists of the following parts:
  * [Under the hood](./UNDER_THE_HOOD.md) A guide to help understand the
  `uasyncio` code. For scheduler geeks and those wishing to modify `uasyncio`.
 
-## 1.1 A new "priority" version.
+## 1.1 The "fast_io" version.
 
 This repo included `asyncio_priority.py` which is now deprecated. Its primary
 purpose was to provide a means of servicing fast hardware devices by means of
@@ -42,6 +47,13 @@ provides an option for I/O scheduling with much reduced latency. It also fixes
 the bug. It is hoped that these changes will be accepted into mainstream in due
 course.
 
+### 1.1.1 A Pyboard-only low power version
+
+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 the library on battery powered projects.
+
 # 2. Version and installation of uasyncio
 
 The documentation and code in this repository are based on `uasyncio` version

fast_io/__init__.py

@@ -1,9 +1,10 @@
+# uasyncio.__init__ fast_io
+# fork: peterhinch/micropython-lib branch: uasyncio-io-fast-and-rw
 import uerrno
 import uselect as select
 import usocket as _socket
 from uasyncio.core import *
 
-
 DEBUG = 0
 log = None
 

fast_io/core.py

@@ -1,4 +1,10 @@
-import utime as time
+# uasyncio.core fast_io
+# fork: peterhinch/micropython-lib branch: uasyncio-io-fast-and-rw
+version = 'fast_io'
+try:
+    import rtc_time as time # Low power timebase using RTC
+except ImportError:
+    import utime as time
 import utimeq
 import ucollections
 
@@ -46,7 +52,8 @@ def time(self):
 
     def create_task(self, coro):
         # CPython 3.4.2
-        assert not isinstance(coro, type_genf), 'Generator function is not iterable.'  # upy issue #3241
+        assert not isinstance(coro, type_genf), 'Coroutine arg expected.'  # upy issue #3241
+        # create_task with a callable would work, so above assert only traps the easily-made error
         self.call_later_ms(0, coro)
         # CPython asyncio incompatibility: we don't return Task object
 
@@ -158,8 +165,8 @@ def run_forever(self):
                             continue
                         elif isinstance(ret, IOWriteDone):
                             self.remove_writer(arg)
-                            self._call_io(cb, args)  # Next call produces StopIteration. Arguably this is not required
-                            continue  # as awrite produces no return value.
+                            self._call_io(cb, args)  # Next call produces StopIteration: see StreamWriter.aclose
+                            continue 
                         elif isinstance(ret, StopLoop):  # e.g. from run_until_complete. run_forever() terminates
                             return arg
                         else:
@@ -205,7 +212,7 @@ def run_forever(self):
             self.wait(delay)
 
     def run_until_complete(self, coro):
-        assert not isinstance(coro, type_genf), 'Generator function is not iterable.'  # upy issue #3241
+        assert not isinstance(coro, type_genf), 'Coroutine arg expected.'  # upy issue #3241
         def _run_and_stop():
             yield from coro
             yield StopLoop(0)

lowpower/README.md

@@ -0,0 +1,190 @@
+# An experimental low power usayncio adaptation
+
+# 1. Introduction
+
+This adaptation is specific to the Pyboard and compatible platforms, namely
+those capable of running the `pyb` module. This module supports two low power
+modes `standby` and `stop`
+[see docs](http://docs.micropython.org/en/latest/pyboard/library/pyb.html).
+
+Use of `standby` is simple in concept: the application runs and issues
+`standby`. The board goes into a very low power mode until it is woken by one
+of a limited set of external events, when it behaves similarly as after a hard
+reset. In that respect a `uasyncio` application is no different from any other.
+If the application can cope with the fact that execution state is lost during
+the delay, it will correctly resume.
+
+This adaptation modifies `uasyncio` such that it can enter `stop` mode for much
+of the time, reducing power consumption. The two approaches can be combined,
+with a device waking from `shutdown` to run a low power `uasyncio` application
+before again entering `shutdown`.
+
+The adaptation trades a reduction in scheduling performance for a substantial
+reduction in power consumption.
+
+Some general notes on low power Pyboard applications may be found
+[here](https://github.com/peterhinch/micropython-micropower).
+
+# 2. Installation
+
+Ensure that the version of `uasyncio` in this repository is installed and
+tested. Copy the file `rtc_time.py` to the device so that it is on `sys.path`.
+
+The test program `lowpower.py` requires a link between pins X1 and X2 to enable
+UART 4 to operate via a loopback.
+
+# 3 Low power uasyncio operation
+
+## 3.1 The official uasyncio package
+
+The official `uasyncio` library is unsuited to low power operation for two
+reasons. Firstly because of its method of I/O polling. In periods when no coro
+is ready for execution, it determines the time when the most current coro will
+be ready to run. It then calls `select.poll`'s `ipoll` method with a timeout
+calculated on that basis. This consumes power.
+
+The second issue is that it uses `utime`'s millisecond timing utilities for
+timing. This ensures portability across MicroPython platforms. Unfortunately on
+the Pyboard the clock responsible for `utime` stops for the duration of
+`pyb.stop()`. This would cause all `uasyncio` timing to become highly
+inaccurate.
+
+## 3.2 The low power adaptation
+
+If running on a Pyboard the version of `uasyncio` in this repo attempts to
+import the file `rtc_time.py`. If this succeeds and there is no USB connection
+to the board it derives its millisecond timing from the RTC; this continues to
+run through `stop`.
+
+To avoid the power drain caused by `select.poll` the user code must issue the
+following:
+
+```python
+    loop = asyncio.get_event_loop()
+    loop.create_task(rtc_time.lo_power(t))
+```
+
+This coro has a continuously running loop that executes `pyb.stop` before
+yielding with a zero delay:
+
+```python
+    def lo_power(t_ms):
+        rtc.wakeup(t_ms)
+        while True:
+            pyb.stop()
+            yield
+```
+
+The design of the scheduler is such that, if at least one coro is pending with
+a zero delay, polling will occur with a zero delay. This minimises power draw.
+The significance of the `t` argument is detailed below.
+
+### 3.2.1 Consequences of pyb.stop
+
+#### 3.2.1.1 Timing Accuracy
+
+A minor limitation is that the Pyboard RTC cannot resolve times of less than
+4ms so there is a theoretical reduction in the accuracy of delays. In practice,
+as explained in the [tutorial](../TUTORIAL.md), issuing
+
+```python
+    await asyncio.sleep_ms(t)
+```
+
+specifies a minimum delay: the maximum may be substantially higher depending on
+the behaviour of other coroutines. The latency implicit in the `lo_power` coro
+(see section 5.2) makes this issue largely academic.
+
+#### 3.2.1.2 USB
+
+Programs using `pyb.stop` disable the USB connection to the PC. This is
+inconvenient for debugging so `rtc_time.py` detects an active USB connection
+and disables power saving. This enables an application to be developed normally
+via a USB connected PC. The board can then be disconnected from the PC and run
+from a separate power source for power measurements.
+
+Applications can detect which timebase is in use by issuing:
+
+```python
+import rtc_time
+if rtc_time.use_utime:
+    # Timebase is utime: either a USB connection exists or not a Pyboard
+else:
+    # Running on RTC timebase with no USB connection
+```
+
+# 4. rtc_time.py
+
+This provides the following.
+
+Variable:
+ * `use_utime` `True` if the `uasyncio` timebase is `utime`, `False` if it is
+ the RTC.
+
+Functions:  
+If the timebase is `utime` these are references to the corresponding `utime`
+functions. Otherwise they are direct replacements but using the RTC as their
+timebase. See the `utime` official documentation for these.  
+ * `ticks_ms`
+ * `ticks_add`
+ * `ticks_diff`
+ * `sleep_ms` This should not be used if the RTC timebase is in use as its
+ usage of the RTC will conflict with the `lo_power` coro.
+
+Coroutine:  
+ * `lo_power` Argument: `t_ms`. This coro repeatedly issues `pyb.stop`, waking
+ after `t_ms` ms. The higher `t_ms` is, the greater the latency experienced by
+ other coros and by I/O. Smaller values may result in higher power consumption
+ with other coros being scheduled more frequently.
+
+# 5. Application design
+
+Attention to detail is required to minimise power consumption, both in terms of
+hardware and code.
+
+## 5.1 Hardware
+
+Hardware issues are covered [here](https://github.com/peterhinch/micropython-micropower).
+To summarise an SD card consumes on the order of 150μA. For lowest power
+consumption use the onboard flash memory. Peripherals usually consume power
+even when not in use: consider switching their power source under program
+control.
+
+## 5.2 Application Code
+
+Issuing `pyb.stop` directly in code is unwise; also, when using the RTC
+timebase, calling `rtc_time.sleep_ms`. This is because there is only one RTC,
+and hence there is potential conflict with different routines issuing
+`rtc.wakeup`. The coro `rtc_time.lo_power` should be the only one issuing this
+call.
+
+The implications of the `t_ms` argument to `rtc_time.lo_power` should be
+considered. During periods when the Pyboard is in a `stop` state, other coros
+will not be scheduled. I/O from interrupt driven devices such as UARTs will be
+buffered for processing when stream I/O is next scheduled. The size of buffers
+needs to be determined in conjunction with data rates and with this latency
+period.
+
+Long values of `t_ms` will affect the minimum time delays which can be expected
+of `await asyncio.sleep_ms`. Such values will affect the aggregate amount of
+CPU time any coro will acquire. If `t_ms == 200` the coro
+
+```python
+async def foo():
+    while True:
+        # Do some processing
+        await asyncio.sleep(0)
+```
+
+will execute (at best) at a rate of 5Hz. And possibly considerably less
+frequently depending on the behaviour of competing coros. Likewise
+
+```python
+async def bar():
+    while True:
+        # Do some processing
+        await asyncio.sleep_ms(10)
+```
+
+the 10ms sleep may be 200ms or longer, again dependent on other application
+code.

lowpower/lowpower.py

@@ -0,0 +1,56 @@
+# lowpower.py Demo of using uasyncio to reduce Pyboard power consumption
+# Author: Peter Hinch
+# Copyright Peter Hinch 2018 Released under the MIT license
+
+# The file rtc_time.py must be on the path for this to work at low power.
+
+import pyb
+import uasyncio as asyncio
+import rtc_time
+
+# Stop the test after a period
+async def killer(duration):
+    await asyncio.sleep(duration)
+
+# Briefly pulse an LED to save power
+async def pulse(led):
+    led.on()
+    await asyncio.sleep_ms(200)
+    led.off()
+
+# Flash an LED forever
+async def flash(led, ms):
+    while True:
+        await pulse(led)
+        await asyncio.sleep_ms(ms)
+
+# Periodically send text through UART
+async def sender(uart):
+    swriter = asyncio.StreamWriter(uart, {})
+    while True:
+        await swriter.awrite('Hello uart\n')
+        await asyncio.sleep(1.3)
+
+# Each time a message is received pulse the LED
+async def receiver(uart, led):
+    sreader = asyncio.StreamReader(uart)
+    while True:
+        await sreader.readline()
+        await pulse(led)
+
+def test(duration):
+    # For lowest power consumption set unused pins as inputs with pullups.
+    # Note the 4K7 I2C pullups on X9 X10 Y9 Y10.
+    for pin in [p for p in dir(pyb.Pin.board) if p[0] in 'XY']:
+        pin_x = pyb.Pin(pin, pyb.Pin.IN, pyb.Pin.PULL_UP)
+    if rtc_time.use_utime:  # Not running in low power mode
+        pyb.LED(4).on()
+    uart = pyb.UART(4, 115200)
+    loop = asyncio.get_event_loop()
+    loop.create_task(rtc_time.lo_power(100))
+    loop.create_task(flash(pyb.LED(1), 4000))
+    loop.create_task(sender(uart))
+    loop.create_task(receiver(uart, pyb.LED(2)))
+    loop.run_until_complete(killer(duration))
+
+test(60)