2019-07-18 06:41:17 +02:00
|
|
|
# KMK: Clackety Keyboards Powered by Python
|
2022-06-16 12:19:10 +02:00
|
|
|
|
|
|
|
|
|
2022-09-14 02:06:57 +02:00
|
|
|
[](https://discord.gg/QBHUUpeGUd)
|
2022-06-16 12:19:10 +02:00
|
|
|
|
|
|
|
|
|
|
|
|
|
|
2021-08-14 03:09:08 +02:00
|
|
|
|
2022-06-16 12:19:10 +02:00
|
|
|
Documentation available at [📖 kmkfw.io](http://kmkfw.io/).
|
2019-07-18 06:41:17 +02:00
|
|
|
|
|
|
|
|
KMK is a feature-rich and beginner-friendly firmware for computer keyboards
|
|
|
|
|
written and configured in
|
2021-12-02 07:56:38 +01:00
|
|
|
[CircuitPython](https://github.com/adafruit/circuitpython).
|
2021-07-06 21:53:34 +02:00
|
|
|
|
2021-12-02 07:56:38 +01:00
|
|
|
**KMK is currently looking for maintainers.** If you like keyboards and/or
|
|
|
|
|
Python, and ideally have contributed to KMK in the past, and are interested in
|
|
|
|
|
(co-)maintaining KMK, comment on [the relevant GitHub
|
|
|
|
|
issue](https://github.com/KMKfw/kmk_firmware/issues/196) or drop by the Matrix
|
|
|
|
|
channel below.
|
2019-07-25 06:04:15 +02:00
|
|
|
|
2019-07-18 06:41:17 +02:00
|
|
|
> If you need support with KMK or just want to say hi, find us in
|
2020-03-30 06:48:23 +02:00
|
|
|
> [#kmkfw:klar.sh on Matrix](https://matrix.to/#/#kmkfw:klar.sh). This channel
|
|
|
|
|
> is bridged to Discord
|
2022-01-29 01:06:52 +01:00
|
|
|
> [here](https://discord.gg/QBHUUpeGUd) for
|
2020-03-30 06:48:23 +02:00
|
|
|
> convenience.
|
2019-07-18 06:41:17 +02:00
|
|
|
|
|
|
|
|
## Features
|
|
|
|
|
|
2019-07-25 06:16:26 +02:00
|
|
|
- Fully configured through a single, easy to understand Python file that lives
|
|
|
|
|
on a "flash-drive"-esque space on your microcontroller - edit on the go
|
|
|
|
|
without DFU or other devtooling available!
|
|
|
|
|
- Single-piece or [two-piece split
|
2022-09-11 21:55:11 +02:00
|
|
|
keyboards](/docs/split_keyboards.md)
|
2019-07-25 06:16:26 +02:00
|
|
|
are supported
|
|
|
|
|
- [Chainable
|
2022-09-11 21:55:11 +02:00
|
|
|
keys](/docs/keys.md) such as
|
2019-07-25 06:16:26 +02:00
|
|
|
`KC.LWIN(KC.L)` to lock the screen on a Windows PC
|
2022-04-24 21:33:35 +02:00
|
|
|
- [Built-in Unicode macros, including
|
2022-09-11 21:55:11 +02:00
|
|
|
emojis](/docs/sequences.md)
|
|
|
|
|
- [RGB underglow](/docs/rgb.md)
|
2019-07-25 06:16:26 +02:00
|
|
|
and [LED
|
2022-09-11 21:55:11 +02:00
|
|
|
backlights](/docs/led.md)
|
2019-07-25 06:16:26 +02:00
|
|
|
- One key can turn into many more based on [how many times you tap
|
2022-09-11 21:55:11 +02:00
|
|
|
it](/docs/tapdance.md)
|
2020-10-21 21:19:42 +02:00
|
|
|
- Bluetooth HID and split keyboards. No more wires.
|
2019-07-18 06:41:17 +02:00
|
|
|
|
|
|
|
|
## Getting Started
|
2022-07-02 18:21:06 +02:00
|
|
|
KMK requires [CircuitPython](https://circuitpython.org/) version 7.0 or higher.
|
2021-07-06 21:53:34 +02:00
|
|
|
Our getting started guide can be found
|
2022-09-11 21:55:11 +02:00
|
|
|
[here](/docs/Getting_Started.md).
|
2019-07-18 06:41:17 +02:00
|
|
|
|
|
|
|
|
## The KMK Team
|
|
|
|
|
|
2021-12-02 07:56:38 +01:00
|
|
|
KMK was originally authored by @klardotsh and @kdb424 over the winter of
|
|
|
|
|
2018-19, and has been contributed to by numerous others since. Contributions
|
|
|
|
|
are welcome from all, whether it's in the form of code, documentation, hardware
|
|
|
|
|
designs, feature ideas, or anything else that comes to mind. A list of KMK's
|
|
|
|
|
contributors can be found [on
|
2021-07-06 21:53:34 +02:00
|
|
|
GitHub](https://github.com/KMKfw/kmk_firmware/graphs/contributors).
|
2018-10-25 23:57:02 +02:00
|
|
|
|
2021-07-06 21:53:34 +02:00
|
|
|
> While Adafruit employees and affiliates are occasionally found in the commit
|
|
|
|
|
> log and their help has been crucial to KMK's success, KMK is not an official
|
|
|
|
|
> Adafruit project, and the Core team is not compensated by Adafruit for its
|
|
|
|
|
> development.
|
2018-08-30 22:31:02 +02:00
|
|
|
|
2019-07-25 07:56:10 +02:00
|
|
|
## Code Style
|
|
|
|
|
|
|
|
|
|
KMK uses [Black](https://github.com/psf/black) with a Python 3.6 target and,
|
|
|
|
|
[(controversially?)](https://github.com/psf/black/issues/594) single quotes.
|
|
|
|
|
Further code styling is enforced with isort and flake8 with several plugins.
|
|
|
|
|
`make fix-isort fix-formatting` before a commit is a good idea, and CI will fail
|
|
|
|
|
if inbound code does not adhere to these formatting rules. Some exceptions are
|
|
|
|
|
found in `setup.cfg` loosening the rules in isolated cases, notably
|
|
|
|
|
`user_keymaps` (which is *also* not subject to Black formatting for reasons
|
|
|
|
|
documented in `pyproject.toml`).
|
|
|
|
|
|
2021-12-05 15:24:51 +01:00
|
|
|
## Tests
|
|
|
|
|
|
2022-04-18 11:39:19 +02:00
|
|
|
Unit tests within the `tests` folder mock various CircuitPython modules to allow
|
2021-12-05 15:24:51 +01:00
|
|
|
them to be executed in a desktop development environment.
|
|
|
|
|
|
|
|
|
|
Execute tests using the command `python -m unittest`.
|
|
|
|
|
|
2018-08-30 22:31:02 +02:00
|
|
|
## License, Copyright, and Legal
|
|
|
|
|
|
2019-07-18 06:41:17 +02:00
|
|
|
All software in this repository is licensed under the [GNU Public License,
|
2022-04-18 11:39:19 +02:00
|
|
|
version 3](https://tldrlegal.com/license/gnu-general-public-license-v3-(gpl-3)).
|
2019-07-18 06:41:17 +02:00
|
|
|
All documentation and hardware designs are licensed under the [Creative Commons
|
|
|
|
|
Attribution-ShareAlike 4.0](https://creativecommons.org/licenses/by-sa/4.0/)
|
|
|
|
|
license. Contributions to this repository must use these licenses unless
|
|
|
|
|
otherwise agreed to by the Core team.
|
2022-06-22 21:57:24 +02:00
|
|
|
|
|
|
|
|
**Due to ethical and legal concerns, any works derived from GitHub Copilot or
|
|
|
|
|
similar artificial intelligence tooling are unacceptable for inclusion in any
|
|
|
|
|
first-party KMK repository or other code collection. We further recommend not
|
|
|
|
|
using GitHub Copilot while developing anything KMK-related, regardless of
|
|
|
|
|
intent to submit upstream.**
|
