SwArray: Add keymap bound method.

Author: peterhinch

v3/docs/EVENTS.md

@@ -517,8 +517,8 @@ async def main():
 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).
+ * `rowpins` A list or tuple of initialised open drain output pins.
+ * `colpins` A list or tuple of initialised input pins (pulled up).
 
 Constructor optional keyword only args:
  * `buffer=bytearray(10)` Keyboard buffer.
@@ -554,7 +554,7 @@ async def repeat(tim, uart, ch):  # Send at least one char
 
 async def main():  # Run forever
     rowpins = [Pin(p, Pin.OPEN_DRAIN) for p in range(10, 14)]
-    colpins = [Pin(p, Pin.IN, Pin.PULL_DOWN) for p in range(16, 20)]
+    colpins = [Pin(p, Pin.IN, Pin.PULL_UP) for p in range(16, 20)]
     uart = UART(0, 9600, tx=0, rx=1)
     pad = Keyboard(rowpins, colpins)
     tim = Delay_ms(duration=200)  # 200ms auto repeat timer
@@ -575,6 +575,8 @@ high value. If the capacitance between wires is high, spurious keypresses may be
 registered. To prevent this it is wise to add physical resistors between the
 input pins and 3.3V. A value in the region of 1KΩ to 5KΩ is recommended.
 
+###### [Contents](./EVENTS.md#0-contents)
+
 ## 6.4 SwArray
 ```python
 from primitives import SwArray
@@ -588,8 +590,8 @@ are made. The diodes prevent this.
 ![Image](./isolate.png)
 
 Constructor mandatory args:
- * `rowpins` A list or tuple of initialised output pins.
- * `colpins` A list or tuple of initialised input pins (pulled down).
+ * `rowpins` A list or tuple of initialised open drain output pins.
+ * `colpins` A list or tuple of initialised input pins (pulled up).
  * `cfg` An integer defining conditions requiring a response. See Module
  Constants below.
 
@@ -601,32 +603,40 @@ Constructor optional keyword only args:
  that causes actions after a button press, for example on release or auto-repeat
  while pressed.
 
+ Synchronous bound method:
+ * `keymap()` Return an integer representing a bitmap of the debounced state of
+ all switches in the array. 1 == closed.
+
  Class variables:
- * `debounce_ms = 50`
- * `long_press_ms = 1000`
- * `double_click_ms = 400`
+ * `debounce_ms = 50` Assumed maximum duration of contact bounce.
+ * `long_press_ms = 1000` Threshold for long press detection.
+ * `double_click_ms = 400` Threshold for double-click detection.
 
 Module constants.  
-The `cfg` constructor arg may be defined as the bitwise or of these constants.
-If the `CLOSE` bit is specified, switch closures will be reported
- * `CLOSE = const(1)` Contact closure.
- * `OPEN = const(2)` Contact opening.
- * `LONG = const(4)` Contact closure longer than `long_press_ms`.
- * `DOUBLE = const(8)` Two closures in less than `double_click_ms`.
- * `SUPPRESS = const(16)`  # Disambiguate. For explanation see `EButton`.
-
-The `SwArray` class is subclassed from [Ringbuf queue](./EVENTS.md#7-ringbuf-queue)
-enabling scan codes and event types to be retrieved with an asynchronous iterator.
-
+The folowing constants are provided to simplify defining the `cfg` constructor
+arg. This may be defined as a bitwise or of selected constants. For example if
+the `CLOSE` bit is specified, switch closures will be reported. An omitted event
+will be ignored. Where the array comprises switches it is usual to specify only
+`CLOSE` and/or `OPEN`. This invokes a more efficient mode of operation because
+timing is not required.
+ * `CLOSE` Report contact closure.
+ * `OPEN` Contact opening.
+ * `LONG` Contact closure longer than `long_press_ms`.
+ * `DOUBLE` Two closures in less than `double_click_ms`.
+ * `SUPPRESS` Disambiguate. For explanation see `EButton`.
+
+The `SwArray` class is subclassed from [Ringbuf queue](./EVENTS.md#7-ringbuf-queue).
+This is an asynchronous iterator, enabling scan codes and event types to be
+retrieved as state changes occur with `async for`:
 ```python
 import asyncio
 from primitives.sw_array import SwArray, CLOSE, OPEN, LONG, DOUBLE, SUPPRESS
 from machine import Pin
 rowpins = [Pin(p, Pin.OPEN_DRAIN) for p in range(10, 14)]
 colpins = [Pin(p, Pin.IN, Pin.PULL_UP) for p in range(16, 20)]
+cfg = CLOSE | OPEN  #LONG | DOUBLE | SUPPRESS
 
 async def main():
-    cfg = CLOSE | OPEN  #LONG | DOUBLE | SUPPRESS
     swa = SwArray(rowpins, colpins, cfg)
     async for scan_code, evt in swa:
         print(scan_code, evt)
@@ -635,6 +645,12 @@ async def main():
 
 asyncio.run(main())
 ```
+##### Application note
+
+Scanning of the array occurs rapidly, and built-in pull-up resistors have a
+high value. If the capacitance between wires is high, spurious closures may be
+registered. To prevent this it is wise to add physical resistors between the
+input pins and 3.3V. A value in the region of 1KΩ to 5KΩ is recommended.
 
 ###### [Contents](./EVENTS.md#0-contents)
 

v3/primitives/sw_array.py

@@ -47,10 +47,11 @@ async def scan(self, nkeys, db_delay):
 OPEN = const(2)
 LONG = const(4)
 DOUBLE = const(8)
-SUPPRESS = const(16)  # Disambiguate
+SUPPRESS = const(16)  # Disambiguate: see docs.
 
-# Entries in queue are (scan_code, event) where event is an OR of above constants
-# Tuples/lists of pins. Rows are OUT, cols are IN
+# Entries in queue are (scan_code, event) where event is an OR of above constants.
+# rowpins/colpins are tuples/lists of pins. Rows are OUT, cols are IN.
+# cfg is a logical OR of above constants. If a bit is 0 that state will never be reported.
 class SwArray(RingbufQueue):
     debounce_ms = 50  # Attributes can be varied by user
     long_press_ms = 1000
@@ -60,12 +61,12 @@ def __init__(self, rowpins, colpins, cfg, *, bufsize=10):
         self._rowpins = rowpins
         self._colpins = colpins
         self._cfg = cfg
-        self._state = 0  # State of all keys as bitmap
+        self._state = 0  # State of all buttons as bitmap
         self._flags = 0  # Busy bitmap
         self._basic = not bool(cfg & (SUPPRESS | LONG | DOUBLE))  # Basic mode
         self._suppress = bool(cfg & SUPPRESS)
         for opin in self._rowpins:  # Initialise output pins
-            opin(1)
+            opin(1)  # open circuit
         asyncio.create_task(self._scan(len(rowpins) * len(colpins)))
 
     def __getitem__(self, scan_code):
@@ -96,6 +97,8 @@ async def _finish(self, sc):  # Tidy up. If necessary await a contact open
         self._put(sc, OPEN)
         self._busy(sc, False)
 
+    def keymap(self):  # Return a bitmap of debounced state of all buttons/switches
+        return self._state
     # Handle long, double. Switch has closed.
     async def _defer(self, sc):
         # Wait for contact closure to be registered: let calling loop complete
@@ -123,7 +126,7 @@ async def _defer(self, sc):
     async def _scan(self, nkeys):
         db_delay = SwArray.debounce_ms
         while True:
-            cur = 0  # Current bitmap of logical key states (1 == pressed)
+            cur = 0  # Current bitmap of logical button states (1 == pressed)
             for opin in self._rowpins:
                 opin(0)  # Assert output
                 for ipin in self._colpins:
@@ -133,7 +136,7 @@ async def _scan(self, nkeys):
             curb = cur  # Copy current bitmap
             if changed := (cur ^ self._state):  # 1's are newly canged button(s)
                 for sc in range(nkeys):
-                    if (changed & 1):  # Current key has changed state
+                    if (changed & 1):  # Current button has changed state
                         if self._basic:  # No timed behaviour
                             self._put(sc, CLOSE if cur & 1 else OPEN)
                         elif cur & 1:  # Closed