From a7fbe280d086e0d996faf31117871999469bc92b Mon Sep 17 00:00:00 2001 From: Josh Klar Date: Fri, 14 Sep 2018 12:08:51 -0700 Subject: [PATCH] Update README to reflect new thinking around the project and discoveries --- README.md | 56 +++++++++++++++++++++++++++++++++++++++++++------------ 1 file changed, 44 insertions(+), 12 deletions(-) diff --git a/README.md b/README.md index 684d7f4..a587a9a 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -# kmk_firmware +# KMK Mechanical keyboard firmware for humans (and ARM microcontrollers) @@ -11,14 +11,17 @@ make easy. KMK was heavily inspired by QMK - in fact, KMK was only created because QMK didn't correctly support some hardware I bought, and hacking support in was going to be a heavy uphill battle. -This project is currently written and maintained by @klardotsh and @kdb424. +This project is currently written and maintained by [Josh +Klar](https://github.com/klardotsh) and [Kyle Brown](https://github.com/kdb424). ## Supported Devices -### Officially Supported -- [Adafruit Feather nRF52 BLE Controller](https://www.adafruit.com/product/3406) -- [Teensy 3.2 Controller](https://www.adafruit.com/product/2756) +| Board | Chipset | Python Platform | Notes | +| ----- | ------- | --------------- | ----- | +| [Seeed nRF52840 Micro Dev Kit](https://www.seeedstudio.com/nRF52840-Micro-Development-Kit-p-3079.html) | nRF52840 | TBD, likely CircuitPython | This is basically as bleeding edge as it gets, will likely require upstream patches to uPy/CPY, but it supports everything we need at a hardware level, unlike the nRF52832. | +| [Adafruit HUZZAH32](https://www.adafruit.com/product/3405) | ESP32 | CircuitPython | This is the HUZZAH you actually want to build a keeb with. More lanes, more better. | +| [pyboard v1.1](https://www.adafruit.com/product/2390) | STM32F405RG (Cortex M4F) | MicroPython | | ### Support Planned/WIP - [Planck rev6 Keyboard](https://olkb.com/planck) @@ -35,13 +38,42 @@ for new keyboards. The base requirements for device support are a port of CircuitPython or MicroPython, at least 256KB of flash storage, and USB and/or Bluetooth LE interfaces. -Devices require at least 256KB of flash to run KMK, and that's already pretty -tight. This means that no AVR based microcontrollers are, or will ever be -supported. This extends to Arduino-compatibles, including the Pro Micro. If you -want to run custom firmware on your Pro Micro-equipped keyboard, or for that -matter anything running the ATmega32U4 (Let's Split, Plancks before rev6, -hundreds of others), check out [QMK](https://github.com/qmk/qmk_firmware), the -biggest influence of KMK by far. They're great people. +Here's a list of boards that seem like they should otherwise be supported, but +are currently not, due to some deficiency uncovered in development/testing: + +| Board | Chipset | Python Platform | Reason Unsupported | +| ----- | ------- | --------------- | ------------------ | +| [Adafruit Feather nRF52 BLE Controller](https://www.adafruit.com/product/3406) | nRF52832 | CircuitPython | Lack of USB HID (HW) | +| [Adafruit Feather Huzzah](https://www.adafruit.com/product/2821) | ESP8266 | CircuitPython | Suuuuuper limited on GPIO lanes, Lack of USB HID (HW) | +| [Teensy 3.2 Controller](https://www.adafruit.com/product/2756) | | MicroPython | Lack of USB HID (SW - MP) | + + +## The Great Hackaround + +While it is required that at least the device talking over USB/BLE HID (the +"primary brain") be from the Supported Devices list and running the primary +component of KMK, it will soon be possible to build split keyboards with other, +otherwise unsupported devices (currently this means a Pro Micro), either to +reduce costs or to convert existing QMK boards to KMK. You'll need to flash +"dummy" firmware to each Pro Micro which simply scans a matrix and passes the +values over I2C to the "brain" device, which does the heavy lifting from there +(including actually sending HID events). + +The obvious downsides of this method are increased number of moving parts, +increased number of things to flash (though the Pro Micros only need flashed +when matricies change, which should almost never happen once a board is built), +and all downsides that go with those points (increased power usage, etc.) The +upside is that it can be a _ton_ cheaper to build a split keyboard this way - +cheapo Pro Micro clones can be had for as little as $4 CAD at time of writing, +whereas a HUZZAH32, for example, is closer to $26 CAD, and to build the +"traditional" way, you'd need N of them (where N is the number of split sections +of your keyboard). + +It is also possible to convert many QMK boards through this fashion - while +untested for now, just about anything with a TRRS jack should work (Ergodoxen, +just about anything from keeb.io, etc.) + +This hackaround is almost certainly pointless for non-split boards. ## License, Copyright, and Legal