Add Keyboard primitive.

Author: peterhinch

v3/docs/EVENTS.md

@@ -1,15 +1,15 @@
 # Synopsis
 
-Using `Event` instances rather than callbacks in `uasyncio` device drivers can
+Using `Event` instances rather than callbacks in `asyncio` device drivers can
 simplify their design and standardise their APIs. It can also simplify
 application logic.
 
-This document assumes familiarity with `uasyncio`. See [official docs](http://docs.micropython.org/en/latest/library/uasyncio.html) and
+This document assumes familiarity with `asyncio`. See [official docs](http://docs.micropython.org/en/latest/library/asyncio.html) and
 [unofficial tutorial](https://github.com/peterhinch/micropython-async/blob/master/v3/docs/TUTORIAL.md).
 
 # 0. Contents
 
- 1. [An alternative to callbacks in uasyncio code](./EVENTS.md#1-an-alternative-to-callbacks-in-uasyncio-code)  
+ 1. [An alternative to callbacks in asyncio code](./EVENTS.md#1-an-alternative-to-callbacks-in-asyncio-code)  
  2. [Rationale](./EVENTS.md#2-rationale)  
  3. [Device driver design](./EVENTS.md#3-device-driver-design)  
  4. [Primitives](./EVENTS.md#4-primitives) Facilitating Event-based application logic  
@@ -25,10 +25,11 @@ This document assumes familiarity with `uasyncio`. See [official docs](http://do
   6.2 [EButton](./EVENTS.md#62-ebutton) Debounced pushbutton with double and long press events  
        6.2.1 [The suppress constructor argument](./EVENTS.md#621-the-suppress-constructor-argument)  
        6.2.2 [The sense constructor argument](./EVENTS.md#622-the-sense-constructor-argument)  
+  6.3 [Keyboard](./EVENTS.md#63-keyboard) A crosspoint array of pushbuttons.  
  7. [Ringbuf queue](./EVENTS.md#7-ringbuf-queue) A MicroPython optimised queue primitive.  
 [Appendix 1 Polling](./EVENTS.md#100-appendix-1-polling)  
 
-# 1. An alternative to callbacks in uasyncio code
+# 1. An alternative to callbacks in asyncio code
 
 Callbacks have two merits. They are familiar, and they enable an interface
 which allows an asynchronous application to be accessed by synchronous code.
@@ -49,7 +50,7 @@ async def handle_messages(input_stream):
 Callbacks are not a natural fit in this model. Viewing the declaration of a
 synchronous function, it is not evident how the function gets called or in what
 context the code runs. Is it an ISR? Is it called from another thread or core?
-Or is it a callback running in a `uasyncio` context? You cannot tell without
+Or is it a callback running in a `asyncio` context? You cannot tell without
 trawling the code. By contrast, a routine such as the above example is a self
 contained process whose context and intended behaviour are evident.
 
@@ -93,15 +94,15 @@ know to access this driver interface is the name of the bound `Event`.
 This doc aims to demostrate that the event based approach can simplify
 application logic by eliminating the need for callbacks.
 
-The design of `uasyncio` V3 and its `Event` class enables this approach
+The design of `asyncio` V3 and its `Event` class enables this approach
 because:
  1. A task waiting on an `Event` is put on a queue where it consumes no CPU
  cycles until the event is triggered.
- 2. The design of `uasyncio` can support large numbers of tasks (hundreds) on
+ 2. The design of `asyncio` can support large numbers of tasks (hundreds) on
  a typical microcontroller. Proliferation of tasks is not a problem, especially
  where they are small and spend most of the time paused waiting on queues.
 
-This contrasts with other schedulers (such as `uasyncio` V2) where there was no
+This contrasts with other schedulers (such as `asyncio` V2) where there was no
 built-in `Event` class; typical `Event` implementations used
 [polling](./EVENTS.md#100-appendix-1-polling) and were convenience objects
 rather than performance solutions.
@@ -151,7 +152,7 @@ Drivers exposing `Event` instances include:
 
 Applying `Events` to typical logic problems requires two new primitives:
 `WaitAny` and `WaitAll`. Each is an ELO. These primitives may be cancelled or
-subject to a timeout with `uasyncio.wait_for()`, although judicious use of
+subject to a timeout with `asyncio.wait_for()`, although judicious use of
 `Delay_ms` offers greater flexibility than `wait_for`.
 
 ## 4.1 WaitAny
@@ -325,13 +326,16 @@ async def foo():
 
 This document describes drivers for mechanical switches and pushbuttons. These
 have event based interfaces exclusively and support debouncing. The drivers are
-simplified alternatives for 
+simplified alternatives for
 [Switch](https://github.com/peterhinch/micropython-async/blob/master/v3/primitives/switch.py)
 and [Pushbutton](https://github.com/peterhinch/micropython-async/blob/master/v3/primitives/pushbutton.py),
 which also support callbacks.
 
 ## 6.1 ESwitch
 
+```python
+from primitives import ESwitch
+```
 This provides a debounced interface to a switch connected to gnd or to 3V3. A
 pullup or pull down resistor should be supplied to ensure a valid logic level
 when the switch is open. The default constructor arg `lopen=1` is for a switch
@@ -348,7 +352,7 @@ Constructor arguments:
  down as appropriate.
  2. `lopen=1` Electrical level when switch is open circuit i.e. 1 is 3.3V, 0 is
  gnd.
- 
+
 Methods:
 
  1. `__call__` Call syntax e.g. `myswitch()` returns the logical debounced
@@ -363,7 +367,7 @@ Bound objects:
 Application code is responsible for clearing the `Event` instances.  
 Usage example:
 ```python
-import uasyncio as asyncio
+import asyncio
 from machine import Pin
 from primitives import ESwitch
 es = ESwitch(Pin("Y1", Pin.IN, Pin.PULL_UP))
@@ -390,7 +394,11 @@ asyncio.run(main())
 ###### [Contents](./EVENTS.md#0-contents)
 
 ## 6.2 EButton
- 
+
+```python
+from primitives import EButton
+```
+
 This extends the functionality of `ESwitch` to provide additional events for
 long and double presses.
 
@@ -479,12 +487,63 @@ determine whether the button is closed or open.
 
 ###### [Contents](./EVENTS.md#0-contents)
 
+## 6.3 Keyboard
+
+```python
+from primitives import Keyboard
+```
+A `Keyboard` provides an interface to a set of pushbuttons arranged as a
+crosspoint array. If a key is pressed its array index (scan code) is placed on a
+ queue. Keypresses are retrieved with `async for`. The driver operates by
+ polling each row, reading the response of each column. N-key rollover is
+ supported - this is the case where a key is pressed before the prior key has
+ been released.
+
+ Example usage:
+```python
+import asyncio
+from primitives import Keyboard
+from machine import Pin
+rowpins = [Pin(p, Pin.OUT) for p in range(10, 14)]
+colpins = [Pin(p, Pin.IN, Pin.PULL_DOWN) for p in range(16, 20)]
+
+async def main():
+    kp = Keyboard(rowpins, colpins)
+    async for scan_code in kp:
+        print(scan_code)
+        if not scan_code:
+            break  # Quit on key with code 0
+
+asyncio.run(main())
+```
+Constructor mandatory args:
+ * `rowpins` A list or tuple of initialised output pins.
+ * `colpins` A list or tuple of initialised input pins (pulled down).
+Constructor optional keyword only args:
+ * `buffer=bytearray(10)` Keyboard buffer.
+ * `db_delay=50` Debounce delay in ms.
+
+The `Keyboard` class is subclassed from [Ringbuf queue](./EVENTS.md#7-ringbuf-queue)
+enabling scan codes to be retrieved with an asynchronous iterator.
+
+In typical use the scan code would be used as the index into a string of
+keyboard characters ordered to match the physical layout of the keys. If data
+is not removed from the buffer, on overflow the oldest scan code is discarded.
+There is no limit on the number of rows or columns however if more than 256 keys
+are used, the `buffer` arg would need to be adapted to handle scan codes > 255.
+
+###### [Contents](./EVENTS.md#0-contents)
+
 # 7. Ringbuf Queue
 
+```python
+from primitives import RingbufQueue
+```
+
 The API of the `Queue` aims for CPython compatibility. This is at some cost to
 efficiency. As the name suggests, the `RingbufQueue` class uses a pre-allocated
 circular buffer which may be of any mutable type supporting the buffer protocol
-e.g. `list`, `array` or `bytearray`. 
+e.g. `list`, `array` or `bytearray`.
 
 Attributes of `RingbufQueue`:
  1. It is of fixed size, `Queue` can grow to arbitrary size.
@@ -515,7 +574,7 @@ Asynchronous methods:
  block until space is available.
  * `get` Return an object from the queue. If empty, block until an item is
  available.
- 
+
 Retrieving items from the queue:
 
 The `RingbufQueue` is an asynchronous iterator. Results are retrieved using
@@ -539,28 +598,27 @@ def add_item(q, data):
     except IndexError:
         pass
 ```
-
 ###### [Contents](./EVENTS.md#0-contents)
 
 # 100 Appendix 1 Polling
 
 The primitives or drivers referenced here do not use polling with the following
 exceptions:
  1. Switch and pushbutton drivers. These poll the `Pin` instance for electrical
- reasons described below. 
+ reasons described below.
  2. `ThreadSafeFlag` and subclass `Message`: these use the stream mechanism.
 
 Other drivers and primitives are designed such that paused tasks are waiting on
 queues and are therefore using no CPU cycles.
 
 [This reference][1e] states that bouncing contacts can assume invalid logic
-levels for a period. It is a reaonable assumption that `Pin.value()` always
+levels for a period. It is a reasonable assumption that `Pin.value()` always
 returns 0 or 1: the drivers are designed to cope with any sequence of such
 readings. By contrast, the behaviour of IRQ's under such conditions may be
 abnormal. It would be hard to prove that IRQ's could never be missed, across
 all platforms and input conditions.
 
-Pin polling aims to use minimal resources, the main overhead being `uasyncio`'s
+Pin polling aims to use minimal resources, the main overhead being `asyncio`'s
 task switching overhead: typically about 250 μs. The default polling interval
 is 50 ms giving an overhead of ~0.5%.
 

v3/docs/THREADING.md

@@ -38,7 +38,8 @@ $ mpremote mip install github:peterhinch/micropython-async/v3/threadsafe
   1.3 [Threaded code on one core](./THREADING.md#13-threaded-code-on-one-core)  
   1.4 [Threaded code on multiple cores](./THREADING.md#14-threaded-code-on-multiple-cores)  
   1.5 [Globals](./THREADING.md#15-globals)  
-  1.6 [Debugging](./THREADING.md#16-debugging)  
+  1.6 [Allocation](./THREADING.md#16-allocation)  
+  1.7 [Debugging](./THREADING.md#17-debugging)  
  2. [Sharing data](./THREADING.md#2-sharing-data)  
   2.1 [A pool](./THREADING.md#21-a-pool) Sharing a set of variables.  
   2.2 [ThreadSafeQueue](./THREADING.md#22-threadsafequeue)  
@@ -146,7 +147,7 @@ async def foo():
         await process(d)
 ```
 
-## 1.2 Soft Interrupt Service Routines 
+## 1.2 Soft Interrupt Service Routines
 
 This also includes code scheduled by `micropython.schedule()` which is assumed
 to have been called from a hard ISR.
@@ -234,10 +235,20 @@ placeholder) before allowing other contexts to run.
 
 If globals must be created or destroyed dynamically, a lock must be used.
 
-## 1.6 Debugging
+## 1.6 Allocation
+
+Memory allocation must be prevented from occurring while a garbage collection
+(GC) is in progress. Normally this is handled transparently by the GIL; where
+there is no GIL a lock is used. The one exception is the case of a hard ISR. It
+is invalid to have a hard ISR waiting on a lock. Consequently hard ISR's are
+disallowed from allocating and an exception is thrown if this is attempted.
+
+Consequently code running in all other contexts is free to allocate.
+
+## 1.7 Debugging
 
 A key practical point is that coding errors in synchronising threads can be
-hard to locate: consequences can be extremely rare bugs or (in the case of 
+hard to locate: consequences can be extremely rare bugs or (in the case of
 multi-core systems) crashes. It is vital to be careful in the way that
 communication between the contexts is achieved. This doc aims to provide some
 guidelines and code to assist in this task.
@@ -463,7 +474,7 @@ def core_2(getq, putq):  # Run on core 2
             putq.put_sync(x, block=True)  # Wait if queue fills.
         buf.clear()
         sleep_ms(30)
-        
+
 async def sender(to_core2):
     x = 0
     while True:
@@ -648,8 +659,7 @@ again before it is accessed, the first data item will be lost.
 Blocking functions or methods have the potential of stalling the `uasyncio`
 scheduler. Short of rewriting them to work properly the only way to tame them
 is to run them in another thread. Any function to be run in this way must
-conform to the guiedelines above, notably with regard to allocation and side
-effects.
+conform to the guiedelines above, notably with regard to side effects.
 
 ## 4.1 Basic approach
 

v3/primitives/__init__.py

@@ -47,6 +47,7 @@ def _handle_exception(loop, context):
     "ESwitch": "events",
     "EButton": "events",
     "RingbufQueue": "ringbuf_queue",
+    "Keyboard": "events",
 }
 
 # Copied from uasyncio.__init__.py

v3/primitives/events.py

@@ -5,6 +5,7 @@
 
 import uasyncio as asyncio
 from . import Delay_ms
+from . import RingbufQueue
 
 # An Event-like class that can wait on an iterable of Event-like instances.
 # .wait pauses until any passed event is set.
@@ -28,7 +29,7 @@ async def wt(self, event):
         await event.wait()
         self.evt.set()
         self.trig_event = event
- 
+
     def event(self):
         return self.trig_event
 
@@ -140,7 +141,7 @@ async def _ltf(self):  # Long timeout
             await self._ltim.wait()
             self._ltim.clear()  # Clear the event
             self.long.set()  # User event
-            
+
     # Runs if suppress set. Delay response to single press until sure it is a single short pulse.
     async def _dtf(self):
         while True:
@@ -164,3 +165,40 @@ def deinit(self):
             task.cancel()
         for evt in (self.press, self.double, self.long, self.release):
             evt.clear()
+
+# A crosspoint array of pushbuttons
+# Tuples/lists of pins. Rows are OUT, cols are IN
+class Keyboard(RingbufQueue):
+    def __init__(self, rowpins, colpins, *, buffer=bytearray(10), db_delay=50):
+        super().__init__(buffer)
+        self.rowpins = rowpins
+        self.colpins = colpins
+        self.db_delay = db_delay  # Deounce delay in ms
+        for opin in self.rowpins:  # Initialise output pins
+            opin(0)
+        asyncio.create_task(self.scan(len(rowpins) * len(colpins)))
+
+    async def scan(self, nbuttons):
+        prev = 0
+        while True:
+            await asyncio.sleep_ms(0)
+            cur = 0
+            for opin in self.rowpins:
+                opin(1)  # Assert output
+                for ipin in self.colpins:
+                    cur <<= 1
+                    cur |= ipin()
+                opin(0)
+            if cur != prev:  # State change
+                pressed = cur & ~prev
+                prev = cur
+                if pressed:  # Ignore button release
+                    for v in range(nbuttons):  # Find button index
+                        if pressed & 1:
+                            break
+                        pressed >>= 1
+                    try:
+                        self.put_nowait(v)
+                    except IndexError:  # q full. Overwrite oldest
+                        pass
+                    await asyncio.sleep_ms(self.db_delay)  # Wait out bounce