A basic 2x2 matrix that can auto-flash to a Feather with a compatible bootloader

.ampy

@@ -0,0 +1,7 @@
+# These values work only for Feathers on Linux hosts
+# right now. If using Docker, requires execution as such:
+#
+# docker run -t kmk_firmware:latest --device /dev/ttyUSB0
+AMPY_PORT=/dev/ttyUSB0
+AMPY_BAUD=115200
+AMPY_DELAY=1.5

.gitmodules

@@ -0,0 +1,3 @@
+[submodule "circuitpython"]
+	path = vendor/circuitpython
+	url = https://github.com/adafruit/circuitpython.git

Makefile

@@ -0,0 +1,54 @@
+.PHONY: build-feather devdeps lint
+
+devdeps: Pipfile.lock
+	pipenv install --dev --ignore-pipfile
+
+lint: devdeps
+	pipenv run flake8
+
+build-feather-test: lint devdeps
+	@echo "===> Pulling dependencies, this may take several minutes"
+	@git submodule update --init --recursive
+	@echo "===> Building circuitpython/mpy-cross"
+	@make -C vendor/circuitpython/mpy-cross
+	@echo "===> Pulling Nordic BLE stack"
+	@cd vendor/circuitpython/ports/nrf && ./drivers/bluetooth/download_ble_stack.sh 2>/dev/null
+	@echo "===> Preparing KMK source for bundling into CircuitPython"
+	@rm -rf vendor/circuitpython/ports/nrf/freeze/kmk
+	@cp -av kmk vendor/circuitpython/ports/nrf/freeze
+	@echo "===> Building CircuitPython with KMK"
+	make -C vendor/circuitpython/ports/nrf BOARD=feather_nrf52832 SERIAL=/dev/ttyUSB0 SD=s132 FROZEN_MPY_DIR=freeze clean dfu-gen dfu-flash
+	@echo "===> Pushing keyboard config"
+	sleep 2
+	-pipenv run ampy rm main.py
+	#pipenv run ampy put boards/klardotsh/twotwo_matrix_feather.py main.py
+	@echo
+	@echo
+	@echo "IT IS NOT SAFE TO AUTOMATICALLY FLASH THIS BOARD IF YOU USE A WHILE TRUE LOOP. YOUR DEVICE CAN BECOME UNRECOVERABLE WITHOUT A JLINK"
+	@echo "TRY RUNNING pipenv run ampy run boards/klardotsh/twotwo_matrix_feather.py AND WATCHING THE SERIAL OUTPUT IN ANOTHER CONSOLE"
+	@echo "THAT IS CURRENTLY ALL THE KEYBOARD YOU CAN ABSOLUTELY SAFELY USE"
+	@echo "I'M DISCUSSING THIS WITH THE ADAFRUIT DEVELOPERS ON DISCORD, HOPEFULLY main.py BECOMES FLASHABLE BY DFU IN THE FUTURE"
+	@echo
+	@echo "Okay, now that the all caps disclaimer is out of the way..."
+	@echo "You can still run pipenv run ampy put boards/klardotsh/twotwo_matrix_feather.py main.py"
+	@echo "Your board will probably work. However, anything depending on the Python REPL (this includes ampy) will not."
+	@echo "If you do get stuck in this purgatory, run 'make oh-god-everything-is-stuck', which will flash a purposefully-failing build to your device"
+	@echo "This workaround ONLY works if your keyboard script tries to import from kmk, which I sure hope it does."
+	@echo "Once that process finishes, you can come back to make build-feather-test safely, or go play in the REPL, or drink."
+
+oh-god-everything-is-stuck: lint devdeps
+	@echo "===> Building a keyboard that explicitly CANNOT import KMK. Assuming your infinite-looping keyboard script imported KMK, it will now fail and be wiped. Cheers!"
+	@echo "===> Pulling dependencies, this may take several minutes"
+	@git submodule update --init --recursive
+	@echo "===> Building circuitpython/mpy-cross"
+	@make -C vendor/circuitpython/mpy-cross
+	@echo "===> Pulling Nordic BLE stack"
+	@cd vendor/circuitpython/ports/nrf && ./drivers/bluetooth/download_ble_stack.sh 2>/dev/null
+	@echo "===> Preparing KMK source for bundling into CircuitPython"
+	@rm -rf vendor/circuitpython/ports/nrf/freeze/kmk
+	@echo "===> Building CircuitPython WITHOUT KMK to induce ImportError"
+	make -C vendor/circuitpython/ports/nrf BOARD=feather_nrf52832 SERIAL=/dev/ttyUSB0 SD=s132 FROZEN_MPY_DIR=freeze clean dfu-gen dfu-flash
+	@echo "===> Wiping keyboard config"
+	sleep 2
+	pipenv run ampy rm main.py
+	@echo "===> Done! Fix your board script and retry flashing the right way"

Pipfile

@@ -0,0 +1,14 @@
+[[source]]
+url = "https://pypi.org/simple"
+verify_ssl = true
+name = "pypi"
+
+[packages]
+
+[dev-packages]
+adafruit-ampy = "*"
+"flake8" = "*"
+"flake8-comprehensions" = "*"
+
+[requires]
+python_version = "3.7"

Pipfile.lock

@@ -0,0 +1,86 @@
+{
+    "_meta": {
+        "hash": {
+            "sha256": "e246783475c5feb51445494a3f30c397ad6ddaed35c45decc9846970d001ad50"
+        },
+        "pipfile-spec": 6,
+        "requires": {
+            "python_version": "3.7"
+        },
+        "sources": [
+            {
+                "name": "pypi",
+                "url": "https://pypi.org/simple",
+                "verify_ssl": true
+            }
+        ]
+    },
+    "default": {},
+    "develop": {
+        "adafruit-ampy": {
+            "hashes": [
+                "sha256:1055827874010f48c7dbd3cde4b1d7c6f6732661fad193b188a398e88961fc62"
+            ],
+            "index": "pypi",
+            "version": "==1.0.5"
+        },
+        "click": {
+            "hashes": [
+                "sha256:29f99fc6125fbc931b758dc053b3114e55c77a6e4c6c3a2674a2dc986016381d",
+                "sha256:f15516df478d5a56180fbf80e68f206010e6d160fc39fa508b65e035fd75130b"
+            ],
+            "version": "==6.7"
+        },
+        "flake8": {
+            "hashes": [
+                "sha256:7253265f7abd8b313e3892944044a365e3f4ac3fcdcfb4298f55ee9ddf188ba0",
+                "sha256:c7841163e2b576d435799169b78703ad6ac1bbb0f199994fc05f700b2a90ea37"
+            ],
+            "index": "pypi",
+            "version": "==3.5.0"
+        },
+        "flake8-comprehensions": {
+            "hashes": [
+                "sha256:b83891fec0e680b07aa1fd92e53eb6993be29a0f3673a09badbe8da307c445e0",
+                "sha256:e4ccf1627f75f192eb7fde640f5edb81c98d04b1390df9d4145ffd7710bb1ef2"
+            ],
+            "index": "pypi",
+            "version": "==1.4.1"
+        },
+        "mccabe": {
+            "hashes": [
+                "sha256:ab8a6258860da4b6677da4bd2fe5dc2c659cff31b3ee4f7f5d64e79735b80d42",
+                "sha256:dd8d182285a0fe56bace7f45b5e7d1a6ebcbf524e8f3bd87eb0f125271b8831f"
+            ],
+            "version": "==0.6.1"
+        },
+        "pycodestyle": {
+            "hashes": [
+                "sha256:682256a5b318149ca0d2a9185d365d8864a768a28db66a84a2ea946bcc426766",
+                "sha256:6c4245ade1edfad79c3446fadfc96b0de2759662dc29d07d80a6f27ad1ca6ba9"
+            ],
+            "version": "==2.3.1"
+        },
+        "pyflakes": {
+            "hashes": [
+                "sha256:08bd6a50edf8cffa9fa09a463063c425ecaaf10d1eb0335a7e8b1401aef89e6f",
+                "sha256:8d616a382f243dbf19b54743f280b80198be0bca3a5396f1d2e1fca6223e8805"
+            ],
+            "version": "==1.6.0"
+        },
+        "pyserial": {
+            "hashes": [
+                "sha256:6e2d401fdee0eab996cf734e67773a0143b932772ca8b42451440cfed942c627",
+                "sha256:e0770fadba80c31013896c7e6ef703f72e7834965954a78e71a3049488d4d7d8"
+            ],
+            "version": "==3.4"
+        },
+        "python-dotenv": {
+            "hashes": [
+                "sha256:122290a38ece9fe4f162dc7c95cae3357b983505830a154d3c98ef7f6c6cea77",
+                "sha256:4a205787bc829233de2a823aa328e44fd9996fedb954989a21f1fc67c13d7a77"
+            ],
+            "version": "==0.9.1"
+        }
+    }
+}

boards/klardotsh/twotwo_matrix_feather.py

@@ -0,0 +1,26 @@
+import board
+import time
+
+from kmk.circuitpython.matrix import MatrixScanner
+from kmk.common.consts import DiodeOrientation
+from kmk.common.keymap import Keymap
+
+
+if __name__ == '__main__':
+    cols = (board.A4, board.A5)
+    rows = (board.D27, board.A6)
+
+    matrix = MatrixScanner(
+        cols=cols, rows=rows,
+        diode_orientation=DiodeOrientation.COLUMNS,
+    )
+
+    keymap = Keymap([
+        ['A', 'B'],
+        ['C', 'D'],
+    ])
+
+    while True:
+        keymap.parse(matrix.raw_scan())
+        # Yield to the controller to allow things like the REPL to take over
+        time.sleep(0.001)

kmk/circuitpython/matrix.py

@@ -0,0 +1,61 @@
+import digitalio
+
+from kmk.common.consts import DiodeOrientation
+
+
+class MatrixScanner:
+    def __init__(self, cols, rows, diode_orientation=DiodeOrientation.COLUMNS):
+        # A pin cannot be both a row and column, detect this by combining the
+        # two tuples into a set and validating that the length did not drop
+        #
+        # repr() hackery is because CircuitPython Pin objects are not hashable
+        unique_pins = {repr(c) for c in cols} | {repr(r) for r in rows}
+        if len(unique_pins) != len(cols) + len(rows):
+            raise ValueError('Cannot use a pin as both a column and row')
+
+        self.cols = [digitalio.DigitalInOut(pin) for pin in cols]
+        self.rows = [digitalio.DigitalInOut(pin) for pin in rows]
+        self.diode_orientation = diode_orientation
+
+        if self.diode_orientation == DiodeOrientation.COLUMNS:
+            self.outputs = self.cols
+            self.inputs = self.rows
+        elif self.diode_orientation == DiodeOrientation.ROWS:
+            self.outputs = self.rows
+            self.inputs = self.cols
+        else:
+            raise ValueError('Invalid DiodeOrientation: {}'.format(
+                self.diode_orientation,
+            ))
+
+        for pin in self.outputs:
+            pin.switch_to_output()
+
+        for pin in self.inputs:
+            pin.switch_to_input(pull=digitalio.Pull.DOWN)
+
+    def _normalize_matrix(self, matrix):
+        '''
+        We always want to internally look at a keyboard as a list of rows,
+        where a "row" is a list of keycodes (columns).
+
+        This will convert DiodeOrientation.COLUMNS matrix scans into a
+        ROWS scan, so we never have to think about these things again.
+        '''
+        if self.diode_orientation == DiodeOrientation.ROWS:
+            return matrix
+
+        return [
+            [col[col_entry] for col in matrix]
+            for col_entry in range(max(len(col) for col in matrix))
+        ]
+
+    def raw_scan(self):
+        matrix = []
+
+        for opin in self.outputs:
+            opin.value = True
+            matrix.append([ipin.value for ipin in self.inputs])
+            opin.value = False
+
+        return self._normalize_matrix(matrix)

kmk/circuitpython/util.py

@@ -0,0 +1,22 @@
+import board
+import digitalio
+import time
+import sys
+
+
+def feather_signal_error_with_led_flash(rate=0.5):
+    '''
+    Flash the red LED for 10 seconds, alternating every $rate
+    Could be useful as an uncaught exception handler later on,
+    but is for now unused
+    '''
+
+    rled = digitalio.DigitalInOut(board.LED1)
+    rled.direction = digitalio.Direction.OUTPUT
+
+    # blink for 5 seconds and exit
+    for cycle in range(10):
+        rled.value = cycle % 2
+        time.sleep(rate)
+
+    sys.exit(1)

kmk/common/consts.py

@@ -0,0 +1,9 @@
+class DiodeOrientation:
+    '''
+    Orientation of diodes on handwired boards. You can think of:
+    COLUMNS = vertical
+    ROWS = horizontal
+    '''
+
+    COLUMNS = 0
+    ROWS = 1

kmk/common/keymap.py

@@ -0,0 +1,18 @@
+class Keymap:
+    def __init__(self, map):
+        self.map = map
+        self.state = [
+            [False for _ in row]
+            for row in self.map
+        ]
+
+    def parse(self, matrix):
+        for ridx, row in enumerate(matrix):
+            for cidx, col in enumerate(row):
+                if col != self.state[ridx][cidx]:
+                    print('{}: {}'.format(
+                        'KEYDOWN' if col else 'KEYUP',
+                        self.map[ridx][cidx],
+                    ))
+
+        self.state = matrix

setup.cfg

@@ -0,0 +1,2 @@
+[flake8]
+exclude = .git,__pycache__,vendor

vendor/circuitpython

@@ -0,0 +1 @@
+Subproject commit 9b98ad779468676c3d5f1efdc06b454aaed7c407