Low power version release 0.1

Author: peterhinch

fast_io/core.py

@@ -264,6 +264,10 @@ def get_event_loop(runq_len=16, waitq_len=16, ioq_len=0):
         _event_loop = _event_loop_class(runq_len, waitq_len, ioq_len)
     return _event_loop
 
+# Allow user classes to determine prior event loop instantiation.
+def got_event_loop():
+    return _event_loop is not None
+
 def sleep(secs):
     yield int(secs * 1000)
 

lowpower/README.md

@@ -1,26 +1,34 @@
-# An experimental low power usayncio adaptation
+# A low power usayncio adaptation
+
+Release 0.1 25th July 2018
 
 # 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`
+those capable of running the `pyb` module; this 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
+of a limited set of external events, when it behaves similarly to 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`.
+of the time, minimising power consumption while retaining state. 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.
+reduction in power consumption. This tradeoff can be dynamically altered at
+runtime. An application can wait with low power consumption for a trigger such
+as a button push. Or it could periodically self-trigger by issuing
+`await ayncio.sleep(long_time)`. For the duration of running the scheduler
+latency can be reduced to improve performance at the cost of temporarily
+higher power consumption, with the code reverting to low power mode while
+waiting for a new trigger.
 
 Some general notes on low power Pyboard applications may be found
 [here](https://github.com/peterhinch/micropython-micropower).
@@ -30,70 +38,83 @@ Some general notes on low power Pyboard applications may be found
 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`.
 
+## 2.1 Files
+
+ * `rtc_time.py` Low power library.
+ * `lpdemo.py` A basic application which waits for a pushbutton to be pressed
+ before running. A second button press terminates it. While "off" and waiting
+ very low power is consumed. A normally open pushbutton should be connected
+ between `X1` and `Gnd`. This program is intended as a basic template for
+ similar applications.
+ * `lowpower.py` Send and receive messages on UART4, echoing received messages
+ to UART2 at a different baudrate. This consumes about 1.4mA and serves to
+ demonstrate that interrupt-driven devices operate correctly.
+
 The test program `lowpower.py` requires a link between pins X1 and X2 to enable
-UART 4 to operate via a loopback.
+UART 4 to receive data 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
+reasons. Firstly because of its method of I/O polling. In periods when no task
+is ready for execution, it determines the time when the most current task 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.
+`pyb.stop()`. An application-level scheme using `pyb.stop` to conserve power
+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`.
+run through `stop`. Libraries using `uasyncio` will run unmodified, barring any
+timing issues if user code increases scheduler latency.
 
 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
+try:
+    if asyncio.version != 'fast_io':
+        raise AttributeError
+except AttributeError:
+    raise OSError('This requires fast_io fork of uasyncio.')
+import rtc_time
+ # Instantiate event loop with any args before running code that uses it
+loop = asyncio.get_event_loop()
+rtc_time.Latency(100)  # Define latency in ms
 ```
 
-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.
+The `Latency` class has a continuously running loop that executes `pyb.stop`
+before yielding with a zero delay. The duration of the `stop` condition
+(`latency`) can be dynamically varied. If zeroed the scheduler will run at
+full speed. The `yield` allows each pending task to run once before the
+scheduler is again paused (if `latency` > 0).
 
 ### 3.2.1 Consequences of pyb.stop
 
-#### 3.2.1.1 Timing Accuracy
+#### 3.2.1.1 Timing Accuracy and rollover
 
 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)
+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.
+the behaviour of other tasks.
+
+RTC time rollover is at 7 days. The maximum supported `asyncio.sleep()` value
+is 302399999 seconds (3.5 days - 1s).
 
 #### 3.2.1.2 USB
 
@@ -106,41 +127,109 @@ from a separate power source for power measurements.
 Applications can detect which timebase is in use by issuing:
 
 ```python
+try:
+    if asyncio.version != 'fast_io':
+        raise AttributeError
+except AttributeError:
+    raise OSError('This requires fast_io fork of uasyncio.')
 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
+Debugging at low power is facilitated by using `pyb.repl_uart` with an FTDI
+adaptor.
+
+### 3.2.2 Measured results
+
+The `lpdemo.py` script consumes a mean current of 980μA with 100ms latency, and
+730μA with 200ms latency, while awaiting a button press.
+
+The following script consumes about 380μA between wakeups (usb is disabled in
+`boot.py`):
+
+```python
+import pyb
+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)
+rtc = pyb.RTC()
+rtc.wakeup(10000)
+while True:
+    pyb.stop()
+```
+
+This accords with the 500μA maximum specification for `stop`. So current
+consumption can be estimated by `i = ib + n/latency` where `ib` is the stopped
+current (in my case 380μA) and `n` is a factor dependent on the amount of code
+which runs when the latency period expires. A data logging application might
+tolerate latencies of many seconds while waiting for a long delay to expire:
+getting close to `ib` may be practicable for such applications during their
+waiting period.
+
+# 4. The rtc_time module
 
 This provides the following.
 
 Variable:
  * `use_utime` `True` if the `uasyncio` timebase is `utime`, `False` if it is
- the RTC.
+ the RTC. Treat as read-only.
 
 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.  
+timebase. See the `utime` official
+[documentation](http://docs.micropython.org/en/latest/pyboard/library/utime.html)
+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.
+It also exposes `sleep_ms`. This is always a reference to `utime.sleep_ms`. The
+reason is explained in the code comments. It is recommended to use the `utime`
+method explicitly if needed.
+
+Latency Class:  
+ * Constructor: Positional arg `t_ms=100`. Period for which the scheduler
+ enters `stop` i.e. initial latency period.
+ * Method: `value` Arg `val=None`. Controls period for which scheduler stops.
+ It returns the period in ms. If the default `None` is passed the value is
+ unchanged. If 0 is passed the scheduler runs at full speed. A value > 0 sets
+ the stop period in ms.
+
+The higher the value, the greater the latency experienced by other tasks and
+by I/O. Smaller values will result in higher power consumption with other tasks
+being scheduled more frequently.
+
+The class is a singleton consequently there is no need to pass an instance
+around or to make it global. Once instantiated, latency may be changed by
+
+```python
+rtc_time.Latency().value(t)
+```
 
 # 5. Application design
 
 Attention to detail is required to minimise power consumption, both in terms of
-hardware and code.
+hardware and code. The only *required* change to application code is to add
+
+```python
+try:
+    if asyncio.version != 'fast_io':
+        raise AttributeError
+except AttributeError:
+    raise OSError('This requires fast_io fork of uasyncio.')
+ # Do this import before configuring any pins or I/O:
+import rtc_time
+ # Instantiate event loop with any args before running code that uses it:
+loop = asyncio.get_event_loop()
+lp = rtc_time.Latency(100)  # Define latency in ms
+ # Run application code
+```
+
+However optimising the power draw/performance tradeoff benefits from further
+optimisations.
 
 ## 5.1 Hardware
 
@@ -150,24 +239,38 @@ consumption use the onboard flash memory. Peripherals usually consume power
 even when not in use: consider switching their power source under program
 control.
 
+Floating Pyboard I/O pins can consume power. Further there are 4.7KΩ pullups on
+the I2C pins. The `rtc_time` module sets all pins as inputs with internal
+pullups. The application should then reconfigure any pins which are to be used.
+If I2C is to be used there are further implications: see the above reference.
+
 ## 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 Pyboard has only one RTC and the `Latency` class needs sole use of
+`pyb.stop` and `rtc.wakeup`; these functions should not be used in application
+code. Setting the RTC at runtime is likely to be problematic: the effect on
+scheduling can be assumed to be malign. If required, the RTC should be set
+prior to instantiating the event loop.
+
+For short delays use `utime.sleep_ms` or `utime.sleep_us`. Such delays use 
+power and hog execution preventing other tasks from running.
+
+A task only consumes power when it runs: power may be reduced by using larger
+values of `t` in
+
+```python
+await asyncio.sleep(t)
+```
 
-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
+The implications of the time value of the `Latency` instance should be
+considered. During periods when the Pyboard is in a `stop` state, other tasks
 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.
+needs to be determined in conjunction with data rates and the 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
+Long values of latency 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 task will acquire in any period. If latency is 200ms the task
 
 ```python
 async def foo():
@@ -176,8 +279,8 @@ async def foo():
         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
+will execute (at best) at a rate of 5Hz; possibly considerably less frequently
+depending on the behaviour of competing tasks. Likewise
 
 ```python
 async def bar():
@@ -186,5 +289,36 @@ async def bar():
         await asyncio.sleep_ms(10)
 ```
 
-the 10ms sleep may be 200ms or longer, again dependent on other application
-code.
+the 10ms sleep will be >=200ms dependent on other application tasks.
+
+Latency may be changed dynamically by using the `value` method of the `Latency`
+instance. A typical application (as in `lpdemo.py`) might wait on a "Start"
+button with a high latency value, before running the application code with a
+lower (or zero) latency. On completion it could revert to waiting for "Start"
+with high latency to conserve battery.
+
+# 6. Note on the design
+
+The `rtc_time` module represents a compromise designed to minimise changes to
+`uasyncio`. The aim is to have zero effect on the performance of normal
+applications or code running on non-Pyboard hardware.
+
+An alternative approach is to modify the `PollEventLoop` `wait` method to
+invoke `stop` conditions when required. It would have the advantage of removing
+the impact of latency on `sleep_ms` times. It proved rather involved and was
+abandoned on the grounds of its impact on performance of normal applications.
+Despite its name, `.wait` is time-critical in the common case of a zero delay;
+increased code is best avoided.
+
+The approach used ensures that there is always at least one task waiting on a
+zero delay. This guarantees that `PollEventLoop` `wait` is always called with a
+zero delay: consequently `self.poller.ipoll(delay, 1)` will always return
+immediately minimising power consumption. Consequently there is no change to
+the design of the scheduler beyond the use of a different timebase. It does,
+however, rely on the fact that the scheduler algorithm behaves as described
+above.
+
+The `rtc_time` module ensures that `uasyncio` uses `utime` for timing if the
+module is present in the path but is unused. This can occur because of an
+active USB connection or if running on an an incompatible platform. This
+ensures that under such conditions performance is unaffected.