sporq/kmk_firmware
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
7d2d04f070
kmk_firmware/README.md
Scott Shawcroft 74c2f220c9
Correct SAMD chip number
2018-10-10 12:17:12 -07:00

5.9 KiB
Raw Blame History

KMK: Mechanical keyboard firmware for humans (and ARM microcontrollers)

CircleCICLA assistant

KMK is a firmware for (usually mechanical) keyboards, written in MicroPython and CircuitPython, heavily inspired by QMK (and with some additions of our own). Python may not be the fastest thing on the planet, but it's a joy to write, and bringing that ease of maintainership to keyboard firmware (often a world of C and all the crazy error states C can provide) opens up custom keyboards to whole new demographics. KMK currently only supports handwired keyboards (see "Supported Devices" below), but work has begun on both ports to existing keyboards, as well as converter devices to allow existing keyboards with Pro Micro pinouts to use KMK-supported microcontrollers. As always in open-source, KMK is a work in progress, and help is welcome!

This project is currently written and maintained by:

This project also owes a $BEVERAGE_OF_CHOICE to some wonderful people in the ecosystem:

  • Jack Humbert (@jackhumbert), for writing QMK. Without QMK, I'd have never been exposed to the wonderful world of programmable keyboards. He's also just an awesometastic human in general, if you ever catch him on Discord/Reddit/etc.

  • Dan Halbert (@dhalbert), for his amazing and unjudgemental support of two random dudes on Github asking all sorts of bizzare (okay... and occasionally dumb) questions on the MicroPython and CircuitPython Github projects and the Adafruit Discord. Dan, without your help and pointers (even when those pointers are "Remember you're working with a microcontroller with a few MHz of processing speed and a few KB of RAM"), this project would have never gotten off the ground. Thank you, and an extended thanks to Adafruit.

Supported Devices

Board Chipset Python Platform Notes
pyboard v1.1 STM32F405RG (Cortex M4F) MicroPython Our reference board for basic USB keyboards
Adafruit Feather M4 Express Atmel SAMD51 (Cortex M4F) CircuitPython A more economical solution for basic USB keyboards
Adafruit ItsyBitsy M4 Express Atmel SAMD51 (Cortex M4F) CircuitPython An EVEN MORE economical solution for basic USB keyboards

Support Planned/WIP

Board Chipset Python Platform Notes
Seeed nRF52840 Micro Dev Kit nRF52840 CircuitPython This is basically as bleeding edge as it gets. Will support BLE HID to PC as well as BLE split boards
Planck rev6 Keyboard STM32 of some sort MicroPython Requires porting MicroPython to STM32F3, this work has begun but I'm pretty terrible at it.
Proton C Controller? ??? ??? Does not exist yet, the controller from a Planck rev6 in a Pro Micro pin-compat controller chip

Unsupported Devices

If you don't see it in "Supported Devices", it won't work out of the box, it's basically that simple. Pull requests are welcome and encouraged to add support 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.

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 Notes
Adafruit Feather Huzzah ESP8266 CircuitPython Suuuuuper limited on GPIO lanes, Lack of USB HID (HW)
Adafruit HUZZAH32 ESP32 MicroPython In theory this may work as a BLE HID device, or with a GPIO-based USB breakout. Right now, we haven't written the code for this device. Built-in USB port can't run in HID at all.
Adafruit Feather nRF52 BLE Controller nRF52832 CircuitPython Lack of USB HID (HW), but could be fixed with GPIO USB breakout. BLE HID could be possible, but it's considered somewhat unstable. This chip is considered "mostly unsupported" in CircuitPython according to Adafruit Discord, so I've mostly abandoned it for now.
Teensy 3.2 Controller MicroPython Lack of USB HID (SW - MP)

License, Copyright, and Legal

This project, and all source code within (even if the file is missing headers), is licensed GPLv3 - while the tl;dr is linked, the full license text is included in LICENSE.md at the top of this source tree.

When contributing for the first time, you'll need to sign a Contributor Licensing Agreement which is based on the Free Software Foundation's CLA. The CLA is basically a two-way promise that this code is and remains yours, but will be distributed as part of a larger GPLv3 project. If you'd like to get it out of the way early, you can find said CLA here. If you forget, the bots will remind you when you open the pull request, no worries!