82 lines
3.5 KiB
Markdown
82 lines
3.5 KiB
Markdown
# KMK: Clackety Keyboards Powered by Python
|
|
|
|
|
|
|
|
|
|
|
|
|
|
KMK is a feature-rich and beginner-friendly firmware for computer keyboards
|
|
written and configured in
|
|
[CircuitPython](https://github.com/adafruit/circuitpython).
|
|
|
|
## Support
|
|
|
|
For asynchronous support and chatter about KMK, [join our Zulip
|
|
community](https://kmkfw.zulipchat.com)!
|
|
|
|
If you ask for help in chat or open a bug report, if possible
|
|
make sure your copy of KMK is up-to-date.
|
|
In particular, swing by the Zulip chat *before* opening a GitHub Issue about
|
|
configuration, documentation, etc. concerns.
|
|
|
|
> The former Matrix and Discord rooms once linked to in this README are no
|
|
> longer officially supported, please do not use them!
|
|
|
|
## Features
|
|
|
|
- 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
|
|
keyboards](/docs/en/split_keyboards.md)
|
|
are supported
|
|
- [Chainable
|
|
keys](/docs/en/keys.md) such as
|
|
`KC.LWIN(KC.L)` to lock the screen on a Windows PC
|
|
- [Built-in Unicode macros, including
|
|
emojis](/docs/en/sequences.md)
|
|
- [RGB underglow](/docs/en/rgb.md)
|
|
and [LED
|
|
backlights](/docs/en/led.md)
|
|
- One key can turn into many more based on [how many times you tap
|
|
it](/docs/en/tapdance.md)
|
|
- Bluetooth HID and split keyboards. No more wires.
|
|
|
|
## Getting Started
|
|
KMK requires [CircuitPython](https://circuitpython.org/) version 7.0 or higher.
|
|
Our getting started guide can be found
|
|
[here](/docs/en/Getting_Started.md).
|
|
|
|
## 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`).
|
|
|
|
## Tests
|
|
|
|
Unit tests within the `tests` folder mock various CircuitPython modules to allow
|
|
them to be executed in a desktop development environment.
|
|
|
|
Execute tests using the command `python -m unittest`.
|
|
|
|
## License, Copyright, and Legal
|
|
|
|
All software in this repository is licensed under the [GNU Public License,
|
|
version 3](https://tldrlegal.com/license/gnu-general-public-license-v3-(gpl-3)).
|
|
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.
|
|
|
|
**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.**
|