sporq/kmk_firmware
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Docs added

Browse Source
This commit is contained in:
Kyle Brown
2020-11-02 20:38:52 -08:00
parent 7fe461d537
commit c2c456ce1a
28 changed files with 512 additions and 442 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
Makefile
View File

@@ -96,7 +96,7 @@ fix-formatting: devdeps
@$(PIPENV) run black . @$(PIPENV) run black .
fix-isort: devdeps fix-isort: devdeps
@find kmk/ user_keymaps/ -name "*.py" | xargs $(PIPENV) run isort @find kmk/ user_keymaps/ boards/ -name "*.py" | xargs $(PIPENV) run isort
clean: clean:
@echo "===> Cleaning build artifacts" @echo "===> Cleaning build artifacts"

59
README.md
View File

@@ -41,65 +41,10 @@ file](https://cdn.kmkfw.io/kmk-latest.unoptimized.zip) forms. These follow the
backlights](https://github.com/KMKfw/kmk_firmware/blob/master/docs/led.md) backlights](https://github.com/KMKfw/kmk_firmware/blob/master/docs/led.md)
- One key can turn into many more based on [how many times you tap - One key can turn into many more based on [how many times you tap
it](https://github.com/KMKfw/kmk_firmware/blob/master/docs/tapdance.md) it](https://github.com/KMKfw/kmk_firmware/blob/master/docs/tapdance.md)
- Bluetooth HID and split keyboards. No more wires.
Coming (hopefully) soon: Bluetooth support! Stay tuned.
## Getting Started ## Getting Started
Our getting started guide can be found [here](https://github.com/KMKfw/docs/Getting_Started.md)
- Start by grabbing a supported microcontroller. Broadly speaking, KMK supports
any device CircuitPython does, but KMK requires a decent bit of RAM, and in
general requires a working USB HID stack, which leads us to recommend the
following controllers:
* [Adafruit ItsyBitsy M4 Express](https://www.adafruit.com/product/3800)\*
* [Adafruit Feather M4 Express](https://www.adafruit.com/product/3857)
* [Adafruit Feather nRF52840 Express](https://www.adafruit.com/product/4062)
* [MakerDiary nRF52840 MDK](https://store.makerdiary.com/collections/frontpage/products/nrf52840-mdk-iot-development-kit)
* [SparkFun Pro nRF52840 Mini](https://www.sparkfun.com/products/15025)
> \* The ItsyBitsy M4 Express is the only controller we currently support in
> non-handwired configurations, using our [ItsyBitsy to Pro Micro converter
> PCB](https://github.com/KMKfw/kmk_firmware/tree/master/hardware) designed by
> @siddacious and @kdb424. It is our most-recommended MCU until [the ItsyBitsy is
> updated with an nRF52840
> chip](https://blog.adafruit.com/2019/01/26/comingsoon-itsybitsy-nrf52480-runs-circuitpython-adafruit-circuitpython-adafruit-circuitpython/)
> Some other controllers, such as the [Feather M0 Express](https://www.adafruit.com/product/3403),
> are usable in reduced functionality modes and may require custom hackery.
> For example, @kdb424 uses a ItsyBitsy M0 Express as a barebones matrix scanner
> in a split keyboard configuration
> [here](https://github.com/KMKfw/kmk_firmware/commit/1f84079dc8aadeb9627c4762d9f9fb855292c4a2).
> Use such controllers at your own risk.
- Ensure CircuitPython 4.0.0 or newer is installed on your controller. We
recommend the latest stable version from
[circuitpython.org](https://circuitpython.org/downloads). Flashing
instructions vary by device: all Adafruit boards can be flashed [using their
instructions](https://learn.adafruit.com/welcome-to-circuitpython/installing-circuitpython),
other boards generally have their instructions [in the CircuitPython
repository](https://github.com/adafruit/circuitpython) under the
`ports/atmel-samd/boards/<your board here>` and `ports/nrf/boards/<your board
here>` directories. If all else fails, consult your device's official
documentation.
- [Download the latest KMK release](https://cdn.kmkfw.io/kmk-latest.zip) and
extract the zip to the USB drive exposed by CircuitPython, typically labeled
`CIRCUITPY`. Again, [we'll defer to Adafruit's
documentation](https://learn.adafruit.com/welcome-to-circuitpython/circuitpython-libraries)
on adding libraries to a CircuitPython installation. You should end up with a
folder called `kmk` and a file called `boot.py`, both living at the top of
this USB drive.
- Define your keyboard in a file called `main.py` on this `CIRCUITPY` drive and
get tinkering! Examples of both handwired and ProMicro-\>ItsyBitsy converted
boards exist under the `user_keymaps/` tree, and feel free to submit a pull
request of your own definitions! At this point, you'll want to look through
`docs/` in the source tree to explore the functionality at your disposal.
> Linux, BSD, and MacOS users can also make use of the `Makefile` provided in
> this source tree to flash KMK and a keymap using `rsync`. This is advanced
> functionality outside the scope of this README, but it's documented in the
> `docs/` tree.
## The KMK Team ## The KMK Team

26
boards/crkbd/README.md Normal file
View File

@@ -0,0 +1,26 @@
# Corne Keyboard (CRKBD)
![Crkbd](https://boardsource.imgix.net/a90342e3-caa0-467c-bebd-d17f031d5210.jpg?raw=true)
![Crkbd](https://boardsource.imgix.net/9cbd31b7-3b37-42c6-919e-3be35a2578f6.jpg?raw=true)
A split keyboard with a 3x6 collumnar stagger and 3 thumb keys.
Keyboard Maintainer: [foostan](https://github.com/foostan/) [@foostan](https://twitter.com/foostan)
Hardware Availability: [PCB & Case Source](https://github.com/foostan/crkbd)
Retailers (USA)
Corne
[Boardsource](https://boardsource.xyz/store/5ecc0f81eee64242946c988f)
Corne LP
[Boardsource](https://boardsource.xyz/store/5f2efc462902de7151495057)
Extentions enabled by default
- Layers
- RGB
- BLE_Split
Recommended Extentions
- Split
- Power

3
boards/nice_nano/crkbd.py → boards/crkbd/kb.py
View File

@@ -18,11 +18,10 @@ class KMKKeyboard(_KMKKeyboard):
row_pins = (board.P0_22, board.P0_24, board.P1_00, board.P0_11) row_pins = (board.P0_22, board.P0_24, board.P1_00, board.P0_11)
diode_orientation = DiodeOrientation.COLUMNS diode_orientation = DiodeOrientation.COLUMNS
split_type = 'UART' # TODO add bluetooth support as well split_type = 'UART'
split_flip = True split_flip = True
uart_pin = board.P0_08 uart_pin = board.P0_08
rgb_pixel_pin = board.P0_06 rgb_pixel_pin = board.P0_06
extra_data_pin = board.SDA # TODO This is incorrect. Find better solution
i2c = board.I2C i2c = board.I2C
coord_mapping = [] coord_mapping = []

42
user_keymaps/default/nice_nano/crkbd.py → boards/crkbd/main.py
View File

@@ -1,39 +1,61 @@
from kmk.boards.nice_nano.crkbd import KMKKeyboard from kb import KMKKeyboard, rgb_pixel_pin
from kmk.extensions.ble_split import BLE_Split
from kmk.extensions.rgb import RGB
from kmk.keys import KC from kmk.keys import KC
keyboard = KMKKeyboard() keyboard = KMKKeyboard()
# Cleaner key names
_______ = KC.TRNS _______ = KC.TRNS
XXXXXXX = KC.NO XXXXXXX = KC.NO
LOWER = KC.MO(3) LOWER = KC.MO(1)
RAISE = KC.MO(4) RAISE = KC.MO(2)
ADJUST = KC.MO(5) ADJUST = KC.LT(3, KC.SPC)
RGB_TOG = KC.RGB_TOG
RGB_HUI = KC.RGB_HUI
RGB_HUD = KC.RGB_HUI
RGB_SAI = KC.RGB_SAI
RGB_SAD = KC.RGB_SAD
RGB_VAI = KC.RGB_VAI
RGB_VAD = KC.RGB_VAD
# Adding extentions
rgb_ext = RGB(pixel_pin=rgb_pixel_pin, num_pixels=27, val_limit=100, hue_default=190, sat_default=100, val_default=5)
# TODO Comment one of these on each side
split_side = 'Left'
split_side = 'Right'
split = BLE_Split(split_side=split_side)
keyboard.extensions.append(split, rgb_ext)
keyboard.keymap = [ keyboard.keymap = [
[ #QWERTY [ #QWERTY
KC.TAB, KC.Q, KC.W, KC.E, KC.R, KC.T, KC.Y, KC.U, KC.I, KC.O, KC.P, KC.BSPC,\ KC.TAB, KC.Q, KC.W, KC.E, KC.R, KC.T, KC.Y, KC.U, KC.I, KC.O, KC.P, KC.BSPC,\
KC.LCTL, KC.A, KC.S, KC.D, KC.F, KC.G, KC.H, KC.J, KC.K, KC.L, KC.SCLN, KC.QUOT,\ KC.LCTL, KC.A, KC.S, KC.D, KC.F, KC.G, KC.H, KC.J, KC.K, KC.L, KC.SCLN, KC.QUOT,\
KC.LSFT, KC.Z, KC.X, KC.C, KC.V, KC.B, KC.N, KC.M, KC.COMM, KC.DOT, KC.SLSH, KC.RSFT,\ KC.LSFT, KC.Z, KC.X, KC.C, KC.V, KC.B, KC.N, KC.M, KC.COMM, KC.DOT, KC.SLSH, KC.RSFT,\
KC.LGUI, LOWER, KC.SPC, KC.ENT, RAISE, KC.RALT, KC.LGUI, LOWER, ADJUST, KC.ENT, RAISE, KC.RALT,
], ],
[ #LOWER [ #LOWER
KC.ESC, KC.N1, KC.N2, KC.N3, KC.N4, KC.N5, KC.N6, KC.N7, KC.N8, KC.N9, KC.N0, KC.BSPC,\ KC.ESC, KC.N1, KC.N2, KC.N3, KC.N4, KC.N5, KC.N6, KC.N7, KC.N8, KC.N9, KC.N0, KC.BSPC,\
KC.LCTL, XXXXXXX, XXXXXXX, XXXXXXX, XXXXXXX, XXXXXXX, KC.LEFT, KC.DOWN, KC.UP, KC.RIGHT, XXXXXXX, XXXXXXX,\ KC.LCTL, XXXXXXX, XXXXXXX, XXXXXXX, XXXXXXX, XXXXXXX, KC.LEFT, KC.DOWN, KC.UP, KC.RIGHT, XXXXXXX, XXXXXXX,\
KC.LSFT, XXXXXXX, XXXXXXX, XXXXXXX, XXXXXXX, XXXXXXX, XXXXXXX, XXXXXXX, XXXXXXX, XXXXXXX, XXXXXXX, XXXXXXX,\ KC.LSFT, XXXXXXX, XXXXXXX, XXXXXXX, XXXXXXX, XXXXXXX, XXXXXXX, XXXXXXX, XXXXXXX, XXXXXXX, XXXXXXX, XXXXXXX,\
KC.LGUI, LOWER, KC.SPC, KC.ENT, RAISE, KC.RALT, KC.LGUI, LOWER, ADJUST, KC.ENT, RAISE, KC.RALT,
], ],
[ #RAISE [ #RAISE
KC.ESC, KC.EXLM, KC.AT, KC.HASH, KC.DLR, KC.PERC, KC.CIRC, KC.AMPR, KC.ASTR, KC.LPRN, KC.RPRN, KC.BSPC,\ KC.ESC, KC.EXLM, KC.AT, KC.HASH, KC.DLR, KC.PERC, KC.CIRC, KC.AMPR, KC.ASTR, KC.LPRN, KC.RPRN, KC.BSPC,\
KC.LCTL, XXXXXXX, XXXXXXX, XXXXXXX, XXXXXXX, XXXXXXX, KC.MINS, KC.EQL, KC.LCBR, KC.RCBR, KC.PIPE, KC.GRV,\ KC.LCTL, XXXXXXX, XXXXXXX, XXXXXXX, XXXXXXX, XXXXXXX, KC.MINS, KC.EQL, KC.LCBR, KC.RCBR, KC.PIPE, KC.GRV,\
KC.LSFT, XXXXXXX, XXXXXXX, XXXXXXX, XXXXXXX, XXXXXXX, KC.UNDS, KC.PLUS, KC.LBRC, KC.RBRC, KC.BSLS, KC.TILD,\ KC.LSFT, XXXXXXX, XXXXXXX, XXXXXXX, XXXXXXX, XXXXXXX, KC.UNDS, KC.PLUS, KC.LBRC, KC.RBRC, KC.BSLS, KC.TILD,\
KC.LGUI, LOWER, KC.SPC, KC.ENT, RAISE, KC.RALT, KC.LGUI, LOWER, ADJUST, KC.ENT, RAISE, KC.RALT,
], ],
[ #ADJUST [ #ADJUST
RGB_TOG, RGB_HUI, RGB_SAI, RGB_VAI, XXXXXXX, XXXXXXX, XXXXXXX, XXXXXXX, XXXXXXX, XXXXXXX, XXXXXXX, XXXXXXX,\
XXXXXXX, RGB_HUD, RGB_SAD, RGB_VAD, XXXXXXX, XXXXXXX, XXXXXXX, XXXXXXX, XXXXXXX, XXXXXXX, XXXXXXX, XXXXXXX,\
XXXXXXX, XXXXXXX, XXXXXXX, XXXXXXX, XXXXXXX, XXXXXXX, XXXXXXX, XXXXXXX, XXXXXXX, XXXXXXX, XXXXXXX, XXXXXXX,\ XXXXXXX, XXXXXXX, XXXXXXX, XXXXXXX, XXXXXXX, XXXXXXX, XXXXXXX, XXXXXXX, XXXXXXX, XXXXXXX, XXXXXXX, XXXXXXX,\
XXXXXXX, XXXXXXX, XXXXXXX, XXXXXXX, XXXXXXX, XXXXXXX, XXXXXXX, XXXXXXX, XXXXXXX, XXXXXXX, XXXXXXX, XXXXXXX,\ KC.LGUI, LOWER, ADJUST, KC.ENT, RAISE, KC.RALT,
XXXXXXX, XXXXXXX, XXXXXXX, XXXXXXX, XXXXXXX, XXXXXXX, XXXXXXX, XXXXXXX, XXXXXXX, XXXXXXX, XXXXXXX, XXXXXXX,\
KC.LGUI, LOWER, KC.SPC, KC.ENT, RAISE, KC.RALT,
] ]
] ]

41
docs/Getting_Started.md Normal file
View File

@@ -0,0 +1,41 @@
# Getting Started
## Microcontrollers
KMK will run on most microcontrollers supported by [Circuitpython](https://circuitpython.org/downloads). Our recommended microcontrollers are found [here](Officially_Supported_Microcontrollers.md)
## Firmware
### Circuitpython
Circuitpython is what KMK will run on top of. Make sure that Circuitpython is installed on your
device using the guide [here](https://learn.adafruit.com/welcome-to-circuitpython/installing-circuitpython).
It's recommended to run the latest stable version that is at least 5.0 or higher. Beta versions may work, but expect limited support.
### KMKPython
KMKPython is a fork of Circuitpython, but with libraries for most extensions built in. This saves you from having to get them all
and keep them updated yourself. There may be other features added in the future that are exclusive to KMKPython.
## Getting KMK
You can always find the latest releases on our CDN, in [compiled and optimized](https://cdn.kmkfw.io/kmk-latest.zip) and
[raw, hackable text file](https://cdn.kmkfw.io/kmk-latest.unoptimized.zip) forms. These follow the `master` branch here on GitHub.
Just get the KMK folder and drop this directly in the CIRCUITPYTHON directory (not in a sub folder). Make sure to extract the zip,
and put the `kmk` folder on the root of the CIRCUITPY drive on the microcontroller
## Turning a controller into a keyboard
### Supported keyboards
If your keyboard and microcontroller are officially supported, it's as easy as visiting the page for your files, and dropping them
on the root of the "flash drive". Those pages can be found [here](https://github.com/KMKfw/boards). You will need the `kb.py` and `main.py`. More advanced instructions
can be found [here](config_and_keymap.md)
### Porting a keyboard
If you are porting a board to KMK, check the page [here](porting_to_kmk.md).
### Handwired Keyboard
If you are doing a hand wire, check [here](handwiring.md)
## Additional features
Want to have fun features such as RGB, split keyboards and more? Check out what extensions can do [here](extensions.md)
## Debugging
Debugging help can be found [here](debugging.md)
## Additional help and support
If you need support with KMK or just want to say hi, find us in [#kmkfw:klar.sh on Matrix](https://matrix.to/#/#kmkfw:klar.sh). This channel is bridged to Discord [here](https://discordapp.com/widget?id=493256121075761173&theme=dark) for convenience.

42
docs/Offiially_Supported_Microcontrollers.md Normal file
View File

@@ -0,0 +1,42 @@
# Officially supported microcontrollers
While most Circuitpython devices are great for hand wired keyboards, most keyboards are designed to accept a pro micro. The boards listed below either are, or can be adapted to that pinout to use common keyboards already on the market.
## Nice!Nano
Features include
- Pro-micro pinout
- Both USB HID and Bluetooth support
- Can do bluetooth split keyboards with no wires at all
- Has battery support including charging
Downsides
- \$25 USD per microcontroller at most retailers
Recommended Retailers
[Boardsource](https://boardsource.xyz/store/5f4a1733bbaa5c635b83ed67)
[NiceKeyboards](https://nicekeyboards.com/collections/group-buy/products/nice-nano-v1-0).
## ItsyBitsy M4 Express
Features include
- Affordable at \$15 USD
- Can run most features of KMK including RGB
Downsides
- Needs adapted to work with pro-micro pinout keyboards. Adapter can be found [HERE](https://github.com/KMKfw/kmk_firmware/tree/master/hardware)
Recommended Retailers
[Adafruit](https://www.adafruit.com/product/3800)
## Adafruit ItsyBitsy nRF52840 Express
Features include
- Both USB HID and Bluetooth support
- More affordable than the Nice!Nano at only \$18
Downsides
- Needs adapted to work with pro-micro pinout keyboards. Adapter can be found [HERE](https://github.com/KMKfw/kmk_firmware/tree/master/hardware)
- No battery support without addon board found[HERE](https://www.adafruit.com/product/2124)
## Other microcontrollers
What you'll need to have at minimum
- CircuitPython/KMKpython
- 256KB of flash storage
- HID over USB and/or Bluetooth.

33
docs/config_and_keymap.md
View File

@@ -2,9 +2,10 @@
KMK is configured through a rather large plain-old-Python class called KMK is configured through a rather large plain-old-Python class called
`KMKKeyboard`. Subclasses of this configuration exist which pre-fill defaults `KMKKeyboard`. Subclasses of this configuration exist which pre-fill defaults
for various known keyboards (for example, many Keebio keyboards are supported for various known keyboards (for example, many QMK keyboards are supported
through our ItsyBitsy to ProMicro pinout adapter). This class is the main through our ItsyBitsy to ProMicro pinout adapter, or with a nice!nano).
interface between end users and the inner workings of KMK. Let's dive in! This class is the main interface between end users and the inner workings of KMK.
Let's dive in!
- Edit or create a file called `main.py` on your `CIRCUITPY` drive. You can also - Edit or create a file called `main.py` on your `CIRCUITPY` drive. You can also
keep this file on your computer (perhaps under `user_keymaps` - please feel keep this file on your computer (perhaps under `user_keymaps` - please feel
@@ -17,9 +18,6 @@ interface between end users and the inner workings of KMK. Let's dive in!
corruption bugs, or you might just have bad luck and delete the wrong file corruption bugs, or you might just have bad luck and delete the wrong file
some day. some day.
- Import the `KMKKeyboard` object for your keyboard from `kmk.boards` (or, if
handwiring your keyboard, import `KMKKeyboard` from `kmk.kmk_keyboard`).
- Assign a `KMKKeyboard` instance to a variable (ex. `keyboard = KMKKeyboard()` - note - Assign a `KMKKeyboard` instance to a variable (ex. `keyboard = KMKKeyboard()` - note
the parentheses) the parentheses)
@@ -77,29 +75,10 @@ keyboard.keymap = [[KC.A, KC.B]]
You can further define a bunch of other stuff: You can further define a bunch of other stuff:
- `debug_enabled` which will spew a ton of debugging information to the serial - `keyboard.debug_enabled` which will spew a ton of debugging information to the serial
console. This is very rarely needed, but can provide very valuable information console. This is very rarely needed, but can provide very valuable information
if you need to open an issue. if you need to open an issue.
- `unicode_mode` from `kmk.consts.UnicodeMode`, which defines the default - `beyboard.tap_time` which defines how long `KC.TT` and `KC.LT` will wait before
operating system implementation to use for unicode sequences (see examples
below, or `unicode.md`. This can be changed after boot with a key (see
`keycodes.md`)
- `tap_time` which defines how long `KC.TT` and `KC.LT` will wait before
considering a key "held" (see `keycodes.md`) considering a key "held" (see `keycodes.md`)
- `leader_dictionary`, which defines leader sequences (see `leader.md`), defined
as tuples of keycode objects (or you can use
`kmk.keycodes.generate_leader_dictionary_seq` with a string)
We also support unicode sequences (emojis, emoticons, umlauted letters,
whatever) if your operating system and system setup do! See `unicode.md` for
details.
[Here's a giant example of all the
above](https://github.com/KMKfw/kmk_firmware/blob/master/user_keymaps/klardotsh/klarank_featherm4.py).
This is my personal 4x12 matrix layout running on a Planck Rev6 PCB, with a
Feather M4 Express wired up to the outer matrix pins (in somewhat of a "spider"
setup), utilizing most of the above features - it's one of the "kitchen sink
tester" definitions we use on the KMK Core team.

2
docs/debugging.md
View File

@@ -3,7 +3,7 @@ Debug will output most of the useful state to the console. This can be enable in
by setting this in your keymap. NOTE that it will be slower, so only enable this when you by setting this in your keymap. NOTE that it will be slower, so only enable this when you
need debugging. need debugging.
```python ```python
DEBUG_ENABLE = True keyboard.debug_enabled = True
``` ```
The output can be viewed by connecting to the serial port of the keybord. Please refer to [THIS](https://learn.adafruit.com/welcome-to-circuitpython/kattni-connecting-to-the-serial-console) for The output can be viewed by connecting to the serial port of the keybord. Please refer to [THIS](https://learn.adafruit.com/welcome-to-circuitpython/kattni-connecting-to-the-serial-console) for

16
docs/examples.md
View File

@@ -1,16 +0,0 @@
# Examples
Here you can find some examples of what some users have created in their personal keyboard configs. These are here to
help you understand how some of the tools may be used.
## Changing LED color based on layers
This allows you to create a layer key that also changes colors when pushing a layer key, and restore turn off the lights
when you release the layer key. The example uses the MO though any layer switch keys can be used if imported. Just use the
LAYER_1 key in your keymap, and it's ready to go! You can change animations, colors, or anything in there.
```python
LAYER_1 = KC.MO(1)
LAYER_1.after_press_handler(lambda *args, **kwargs: keyboard.pixels.set_hsv_fill(100, 100, 100))
LAYER_1.after_release_handler(lambda *args, **kwargs: keyboard.pixels.set_hsv_fill(0, 0, 0))
keyboard.keymap = [ ....... LAYER_1 ....... ]
```

17
docs/extensions.md Normal file
View File

@@ -0,0 +1,17 @@
# Extensions
Extensions allow more features to be added ot KMK such as RGB, power saving and more. Extensions
listed on this page are supported on KMK, though it's possible to add your own!
## Core extensions
These extensions are proveded in all builds and can be enabled. Currently offered extensions are
- [BLE-Split](split_keyboards.md): Allows keyboards to be split in 2 with no wires
- [International](international.md): Adds international keycodes
- [Layers](layers.md): Adds layer support (Fn key) to allow many more keys to be put on your keyboard
- [LED](led.md): Adds backlight support. This is for monocolor backlight, not RGB
- [MediaKeys](media_keys.md): Adds support for media keys such as volume
- [ModTap](modtap.md): Adds support for augmented modifier keys to act as one key when tapped, and modifier
when held.
- [Power](power.md): Power saving features. This is mostly useful when on battery power.
- [RGB](rgb.md): RGB lighting for underglow. Will work on most matrix RGB as well treated the same as underglow.
- [Split](split_keyboards.md): This is for wired splits. Only use wired or wireless, not both.

2
docs/flashing.md
View File

@@ -18,7 +18,7 @@ If you get permissions errors here, **don't run make as root or with sudo**. See
`Troubleshooting` below. `Troubleshooting` below.
```sh ```sh
make MOUNTPOINT=/media/CIRCUITPY USER_KEYMAP=user_keymaps/nameofyourkeymap.py make MOUNTPOINT=/media/CIRCUITPY USER_KEYMAP=user_keymaps/nameofyourkeymap.py BOARD=board/nameofyourboar/kb.py
``` ```
# Troubleshooting # Troubleshooting

2
docs/handwiring.md Normal file
View File

@@ -0,0 +1,2 @@
# Handwire keyboards
This guide will not talk about the physical wiring. Check out our [recommended microcontrollers](Offiially_Supported_Microcontrollers.md) and follow the amazing guide for that[here](https://docs.qmk.fm/#/hand_wire). That guide can be followed until you are setting up the firmware. After wiring the keyboard, you can refer to our porting guide [here](porting_to_kmk.md)

35
docs/hardware.md
View File

@@ -1,35 +0,0 @@
## Supported Devices
| Board | Chipset | Python Platform | Notes |
| ----- | ------- | --------------- | ----- |
| [Adafruit Feather M4 Express](https://www.adafruit.com/product/3857) | Atmel SAMD51 (Cortex M4F) | CircuitPython | An economical solution for basic USB keyboards |
| [Adafruit ItsyBitsy M4 Express](https://www.adafruit.com/product/3800) | Atmel SAMD51 (Cortex M4F) | CircuitPython | A smaller solution for basic USB keyboards |
| [Adafruit Feather NRF52840 Express](https://www.adafruit.com/product/4062) | Cortex M4F/nrf52840 | CircuitPython | Supports USB HID and soon BLE (Bluetooth) |
| [Seeed nRF52840 Micro Dev Kit](https://www.seeedstudio.com/nRF52840-Micro-Development-Kit-p-3079.html) | M4F/nrf52840 | CircuitPython | Supports USB HID and soon BLE (Bluetooth) |
## Support Planned/WIP
| Board | Chipset | Python Platform | Notes |
| ----- | ------- | --------------- | ----- |
| [Planck rev6 Keyboard](https://olkb.com/planck) | STM32F303 | CircuitPython | Requires porting CircuitPython to STM32F3. |
| [Proton C Controller?](https://olkb.com/parts/qmk-proton-c) | STM32F303CCT6 | CircuitPython | Requires porting CircuitPython to STM32F3. |
## Porting new devices
Pull requests are welcome and encouraged to add support for new
keyboards/microcontrollers. The base requirements for device support
- CircuitPython
- 256KB of flash storage
- HID over USB and/or Bluetooth.
## Secondary Support
In the future, secondary support for lesser controllers is planned. One of
these cases is the pro micro being used for a slave half of a split keyboard
while all actual work is being done by a supported board. This could also be
used to convert boards that use USB or i2c that run lesser chips to a KMK
board, with a supported board acting as a translation layer. Support for
a converter is planned with the inspiration coming from the [Hasu USB to
USB Controller Converter](https://www.1upkeyboards.com/shop/controllers/usb-to-usb-converter/)
and would allow for conversion to KMK as opposed to TMK or QMK with that board.

34
docs/international.md Normal file
View File

@@ -0,0 +1,34 @@
# International Keycodes
International extention adds keys for non US layouts. It can simply be added to the extentions list.
```python
from kmk.extensions.international import International
keyboard.extensions.append(International())
```
## Keycodes
|Key |Aliases |Description |
|-----------------------|--------------------|-----------------------------------------------|
|`KC.NONUS_HASH` |`KC.NUHS` |Non-US `#` and `~` |
|`KC.NONUS_BSLASH` |`KC.NUBS` |Non-US `\` and <code>&#124;</code> |
|`KC.INT1` |`KC.RO` |JIS `\` and <code>&#124;</code> |
|`KC.INT2` |`KC.KANA` |JIS Katakana/Hiragana |
|`KC.INT3` |`KC.JYEN` |JIS `¥` |
|`KC.INT4` |`KC.HENK` |JIS Henkan |
|`KC.INT5` |`KC.MHEN` |JIS Muhenkan |
|`KC.INT6` | |JIS Numpad `,` |
|`KC.INT7` | |International 7 |
|`KC.INT8` | |International 8 |
|`KC.INT9` | |International 9 |
|`KC.LANG1` |`KC.HAEN` |Hangul/English |
|`KC.LANG2` |`KC.HANJ` |Hanja |
|`KC.LANG3` | |JIS Katakana |
|`KC.LANG4` | |JIS Hiragana |
|`KC.LANG5` | |JIS Zenkaku/Hankaku |
|`KC.LANG6` | |Language 6 |
|`KC.LANG7` | |Language 7 |
|`KC.LANG8` | |Language 8 |
|`KC.LANG9` | |Language 9 |

71
docs/keycodes.md
View File

@@ -52,7 +52,6 @@
|`KC.LBRACKET` |`KC.LBRC` |`[` and `{` | |`KC.LBRACKET` |`KC.LBRC` |`[` and `{` |
|`KC.RBRACKET` |`KC.RBRC` |`]` and `}` | |`KC.RBRACKET` |`KC.RBRC` |`]` and `}` |
|`KC.BSLASH` |`KC.BSLS` |`\` and <code>&#124;</code> | |`KC.BSLASH` |`KC.BSLS` |`\` and <code>&#124;</code> |
|`KC.NONUS_HASH` |`KC.NUHS` |Non-US `#` and `~` |
|`KC.SCOLON` |`KC.SCLN` |`;` and `:` | |`KC.SCOLON` |`KC.SCLN` |`;` and `:` |
|`KC.QUOTE` |`KC.QUOT` |`'` and `"` | |`KC.QUOTE` |`KC.QUOT` |`'` and `"` |
|`KC.GRAVE` |`KC.GRV`, `KC.ZKHK` |<code>&#96;</code> and `~`, JIS Zenkaku/Hankaku| |`KC.GRAVE` |`KC.GRV`, `KC.ZKHK` |<code>&#96;</code> and `~`, JIS Zenkaku/Hankaku|
@@ -102,7 +101,6 @@
|`KC.KP_9` |`KC.P9` |Keypad `9` and Page Up | |`KC.KP_9` |`KC.P9` |Keypad `9` and Page Up |
|`KC.KP_0` |`KC.P0` |Keypad `0` and Insert | |`KC.KP_0` |`KC.P0` |Keypad `0` and Insert |
|`KC.KP_DOT` |`KC.PDOT` |Keypad `.` and Delete | |`KC.KP_DOT` |`KC.PDOT` |Keypad `.` and Delete |
|`KC.NONUS_BSLASH` |`KC.NUBS` |Non-US `\` and <code>&#124;</code> |
|`KC.KP_EQUAL` |`KC.PEQL` |Keypad `=` | |`KC.KP_EQUAL` |`KC.PEQL` |Keypad `=` |
|`KC.F13` | |F13 | |`KC.F13` | |F13 |
|`KC.F14` | |F14 | |`KC.F14` | |F14 |
@@ -121,24 +119,6 @@
|`KC.LOCKING_SCROLL` |`KC.LSCR` |Locking Scroll Lock | |`KC.LOCKING_SCROLL` |`KC.LSCR` |Locking Scroll Lock |
|`KC.KP_COMMA` |`KC.PCMM` |Keypad `,` | |`KC.KP_COMMA` |`KC.PCMM` |Keypad `,` |
|`KC.KP_EQUAL_AS400` | |Keypad `=` on AS/400 keyboards | |`KC.KP_EQUAL_AS400` | |Keypad `=` on AS/400 keyboards |
|`KC.INT1` |`KC.RO` |JIS `\` and <code>&#124;</code> |
|`KC.INT2` |`KC.KANA` |JIS Katakana/Hiragana |
|`KC.INT3` |`KC.JYEN` |JIS `¥` |
|`KC.INT4` |`KC.HENK` |JIS Henkan |
|`KC.INT5` |`KC.MHEN` |JIS Muhenkan |
|`KC.INT6` | |JIS Numpad `,` |
|`KC.INT7` | |International 7 |
|`KC.INT8` | |International 8 |
|`KC.INT9` | |International 9 |
|`KC.LANG1` |`KC.HAEN` |Hangul/English |
|`KC.LANG2` |`KC.HANJ` |Hanja |
|`KC.LANG3` | |JIS Katakana |
|`KC.LANG4` | |JIS Hiragana |
|`KC.LANG5` | |JIS Zenkaku/Hankaku |
|`KC.LANG6` | |Language 6 |
|`KC.LANG7` | |Language 7 |
|`KC.LANG8` | |Language 8 |
|`KC.LANG9` | |Language 9 |
|`KC.LCTRL` |`KC.LCTL` |Left Control | |`KC.LCTRL` |`KC.LCTL` |Left Control |
|`KC.LSHIFT` |`KC.LSFT` |Left Shift | |`KC.LSHIFT` |`KC.LSFT` |Left Shift |
|`KC.LALT` | |Left Alt | |`KC.LALT` | |Left Alt |
@@ -190,11 +170,10 @@
|Key |Description | |Key |Description |
|-----------------------|---------------------------------------------------------------------| |-----------------------|---------------------------------------------------------------------|
|`KC.RESET` |Put the keyboard into DFU mode for flashing | |`KC.RESET` |Restarts the keyboard |
|`KC.DEBUG` |Toggle `debug_enabled`, which enables log spew to serial console | |`KC.DEBUG` |Toggle `debug_enabled`, which enables log spew to serial console |
|`KC.GESC` |Escape when tapped, <code>&#96;</code> when pressed with Shift or GUI| |`KC.GESC` |Escape when tapped, <code>&#96;</code> when pressed with Shift or GUI|
|`KC.BKDL` |Backspace when tapped, Delete when pressed with GUI | |`KC.BKDL` |Backspace when tapped, Delete when pressed with GUI |
|`KC.LEAD` |The [Leader key] |
|`KC.UC_MODE_NOOP` |Sets UnicodeMode to NOOP | |`KC.UC_MODE_NOOP` |Sets UnicodeMode to NOOP |
|`KC.UC_MODE_LINUX` |Sets UnicodeMode to Linux | |`KC.UC_MODE_LINUX` |Sets UnicodeMode to Linux |
|`KC.UC_MODE_MACOS` |Sets UnicodeMode to MocOS | |`KC.UC_MODE_MACOS` |Sets UnicodeMode to MocOS |
@@ -202,19 +181,6 @@
|`KC.MACRO_SLEEP_MS(ms)`|Sleeps in a macro. Check MACROS for more information. | |`KC.MACRO_SLEEP_MS(ms)`|Sleeps in a macro. Check MACROS for more information. |
## [Layer Switching]
|Key |Description |
|-----------------|------------------------------------------------------------------------|
|`KC.DF(layer)` |Switches the default layer |
|`KC.MO(layer)` |Momentarily activates layer, switches off when you let go |
|`KC.LM(layer, mod)` |As `MO(layer)` but with `mod` active |
|`KC.LT(layer, kc)` |Momentarily activates layer if held, sends kc if tapped |
|`KC.TG(layer)` |Toggles the layer (enables it if no active, and vise versa) |
|`KC.TO(layer)` |Activates layer and deactivates all other layers |
|`KC.TT(layer)` |Momentarily activates layer if held, toggles it if tapped repeatedly |
## [Modifiers] ## [Modifiers]
|Key |Description | |Key |Description |
@@ -230,41 +196,6 @@
|`KC.RALT(kc)`|Hold Right Alt and press `kc` | |`KC.RALT(kc)`|Hold Right Alt and press `kc` |
|`KC.RGUI(kc)`|Hold Right GUI and press `kc` | |`KC.RGUI(kc)`|Hold Right GUI and press `kc` |
## [RGB/Underglow]
|Key |Aliases |Description |
|-----------------------------|-------------------|----------------------------|
|`KC.RGB_TOG` | |Toggles RGB |
|`KC.RGB_HUI` | |Increase Hue |
|`KC.RGB_HUD` | |Decrease Hue |
|`KC.RGB_SAI` | |Increase Saturation |
|`KC.RGB_SAD` | |Decrease Saturation |
|`KC.RGB_VAI` | |Increase Value |
|`KC.RGB_VAD` | |Decrease Value |
|`KC.RGB_MODE_PLAIN` |`RGB_M_P` |Static RGB |
|`KC.RGB_MODE_BREATHE` |`RGB_M_B` |Breathing animation |
|`KC.RGB_MODE_RAINBOW` |`RGB_M_R` |Rainbow animation |
|`KC.RGB_MODE_BREATHE_RAINBOW`|`RGB_M_BR` |Breathing rainbow animation |
|`KC.RGB_MODE_KNIGHT` |`RGB_M_K` |Knightrider animation |
## [Mod-Tap Keys]
|New Keycode | Description |
|-------------------------------------------------------|-----------------------------------------------------------------|
|LCTL = KC.MT(KC.SOMETHING, KC.LCTRL) |`LCTRL` if held `kc` if tapped |
|LSFT = KC.MT(KC.SOMETHING, KC.LSFT) |`LSHIFT` if held `kc` if tapped |
|LALT = KC.MT(KC.SOMETHING, KC.LALT) |`LALT` if held `kc` if tapped |
|LGUI = KC.MT(KC.SOMETHING, KC.LGUI) |`LGUI` if held `kc` if tapped |
|RCTL = KC.MT(KC.SOMETHING, KC.RCTRL) |`RCTRL` if held `kc` if tapped |
|RSFT = KC.MT(KC.SOMETHING, KC.RSFT) |`RSHIFT` if held `kc` if tapped |
|RALT = KC.MT(KC.SOMETHING, KC.RALT) |`RALT` if held `kc` if tapped |
|RGUI = KC.MT(KC.SOMETHING, KC.RGUI) |`RGUI` if held `kc` if tapped |
|SGUI = KC.MT(KC.SOMETHING, KC.LSHFT(KC.LGUI)) |`LSHIFT` and `LGUI` if held `kc` if tapped |
|LCA = KC.MT(KC.SOMETHING, KC.LCTRL(KC.LALT)) |`LCTRL` and `LALT` if held `kc` if tapped |
|LCAG = KC.MT(KC.SOMETHING, KC.LCTRL(KC.LALT(KC.LGUI))) |`LCTRL` and `LALT` and `LGUI` if held `kc` if tapped |
|MEH = KC.MT(KC.SOMETHING, KC.LCTRL(KC.LSFT(KC.LALT))) |`CTRL` and `LSHIFT` and `LALT` if held `kc` if tapped |
|HYPR = KC.MT(KC.SOMETHING, KC.HYPR) |`LCTRL` and `LSHIFT` and `LALT` and `LGUI` if held `kc` if tapped|
## [Bluetooth Keys] ## [Bluetooth Keys]

20
docs/layers.md Normal file
View File

@@ -0,0 +1,20 @@
# Layers
Layers extention adds keys for accessing other layers. It can simply be added to the extentions list.
```python
from kmk.extensions.layers import Layers
keyboard.extensions.append(Layers())
```
## Keycodes
|Key |Description |
|-----------------|------------------------------------------------------------------------|
|`KC.DF(layer)` |Switches the default layer |
|`KC.MO(layer)` |Momentarily activates layer, switches off when you let go |
|`KC.LM(layer, mod)` |As `MO(layer)` but with `mod` active |
|`KC.LT(layer, kc)` |Momentarily activates layer if held, sends kc if tapped |
|`KC.TG(layer)` |Toggles the layer (enables it if no active, and vise versa) |
|`KC.TO(layer)` |Activates layer and deactivates all other layers |
|`KC.TT(layer)` |Momentarily activates layer if held, toggles it if tapped repeatedly |

66
docs/leader.md
View File

@@ -3,7 +3,24 @@ The leader key acts as a prefix to a key sequence. These can be used to trigger
without dedicated keys set to each function. For those of you who dislike key combos, such as without dedicated keys set to each function. For those of you who dislike key combos, such as
Ctrl+Shift+Esc, then this feature is for you. This is very much inspired from vim. Ctrl+Shift+Esc, then this feature is for you. This is very much inspired from vim.
Leader key sequences can be as long or short as you like. The action must be a macro, so it ## Keycode
|Key |Description |
|-----------------------|---------------------------------------------------------------------|
|`KC.LEAD` |The [Leader key] |
# Enabling the extention
```python
from kmk.extensions.leader import Leader
from kmk.handlers.sequences import send_string
leader_ext = Leader(}
)
keyboard.extensions.append(leader_ext)
```
Leader key sequences can be as long or short as you like. The action be a keycode, or
can be things like unicode macros, or generic macros. The example below shows how you would can be things like unicode macros, or generic macros. The example below shows how you would
trigger task manager in Windows with a leader sequence. trigger task manager in Windows with a leader sequence.
@@ -15,54 +32,37 @@ from kmk.macros.simple import simple_key_sequence
# ... # ...
keyboard.leader_dictionary = { leader_ext = Leader(
(KC.T, KC.A, KC.S, KC.K): simple_key_sequence([Modifiers.KC_LCTRL(Modifiers.KC_LSHIFT(Common.KC_ESC))]) sequences={
'task': : simple_key_sequence([Modifiers.KC_LCTRL(Modifiers.KC_LSHIFT(Common.KC_ESC))])
} }
)
keymap = [...KC.LEAD,...] keymap = [...KC.LEAD,...]
# ... # ...
``` ```
If defining tuples of keycodes is too obtuse for you, we have a convenience
function available for that, too!
```python
from kmk.keycodes import generate_leader_dictionary_seq as glds
# ...
keyboard.leader_dictionary = {
glds('task'): simple_key_sequence([Modifiers.KC_LCTRL(Modifiers.KC_LSHIFT(Common.KC_ESC))])
}
# ...
```
# Modes # Modes
1. LeaderMode.TIMEOUT (the default) 1. LeaderMode.TIMEOUT (the default)
2. LeaderMode.ENTER 2. LeaderMode.ENTER
### Timeout Mode ### Timeout Mode
Will expire after a timer and trigger the sequence that matches if any. Will expire after a timer and trigger the sequence that matches if any. The default timeout is 1000ms
This can be enabled with
```python
from kmk.consts import LeaderMode
keyboard.leader_mode = LeaderMode.TIMEOUT
```
The timeout can be set like this
```python
keyboard.leader_timeout = 2000 # in milliseconds-ish
```
The timeout defaults to `1000`, which is roughly a second.
### Enter Mode ### Enter Mode
Has no timeout. To end sequence press the enter key, or cancel and do nothing, press escape. Has no timeout. To end sequence press the enter key, or cancel and do nothing, press escape.
This can be enabled with
## Changing defaults
To change the mode or timeout, add them here
```python ```python
from kmk.consts import LeaderMode from kmk.extensions.leader import Leader, LeaderMode
keyboard.leader_mode = LeaderMode.ENTER leader_ext = Leader(
mode=LeaderMode.ENTER,
timeout=1000
sequences={
'hello': send_string('hello world from kmk macros'),
}
)
``` ```

85
docs/led.md
View File

@@ -1,6 +1,16 @@
# LED (Mono color backlight) # LED (Mono color backlight)
Want your keyboard to shine? Add some lights! Want your keyboard to shine? Add some lights!
## Enabling the extention
The only required values that you need to give the LED extention would be the pixel pin, and the number of pixels/LED's. If using a split keyboard, this number is per side, and not the total of both sides.
```python
from kmk.extensions.RGB import RGB
from kb import led_pin # This can be imported or defined manually
led_ext = LED(led_pin=led_pin)
keyboard.extensions.append(led_ext)
```
## [Keycodes] ## [Keycodes]
|Key |Aliases |Description | |Key |Aliases |Description |
@@ -14,69 +24,16 @@ Want your keyboard to shine? Add some lights!
|`KC.LED_MODE_BREATHE` |`LED_M_B` |Breathing animation | |`KC.LED_MODE_BREATHE` |`LED_M_B` |Breathing animation |
## Configuration ## Configuration
|Define |Default |Description | All of these values can be set by default for when the keyboard boots.
|-----------------------------------------|-------------|------------------------------------------------|
|`keyboard.led_config['brightness_step']` |`5` |The number of steps to change the brightness by |
|`keyboard.led_config['brightness_limit']`|`100` |The maximum brightness level in percent |
## Built-in Animation Configuration
|Define |Default |Description |
|-----------------------------------------|-------------|-------------------------------------------------------------------------------------|
|`keyboard.led_config['breath_center']` |`1.5` |Used to calculate the curve for the breathing animation. Anywhere from 1.0 - 2.7 is valid|
## Functions
If you want to create your own animations, or for example, change the lighting in a macro, or a layer switch, here are some functions that are available.
|Function |Description |
|--------------------------------------------|--------------------------------------------------------------------------------------------|
|`keyboard.pixels.increase_brightness(step)` |Increases hue by a given step |
|`keyboard.pixels.decrease_brightness(step)` |Decreases hue by a given step |
|`keyboard.pixels.set_brightness(percent)` |Increases saturation by a given step |
## Direct variable access
|Define |Default |Description |
|-----------------------------------|-----------|--------------------------------------------------------------------------------------------------------|
|`keyboard.led.brightness` |`0` |Sets the brightness by percent 0-100 |
|`keyboard.led.brightness_limit` |`100` |Sets the limit of brightness |
|`keyboard.led.brightness_step` |`5` |Sets the step value to change brightness by |
|`keyboard.led.animation_mode` |`static` |This can be changed to any modes included, or to something custom for user animations. Any string is valid |
|`keyboard.led.animation_speed` |`1` |Increases animation speed of most animations. Recommended 1-5, Maximum 10. |
## User animations
User animations can be created as well. An example of a light show would look like this
```python ```python
from kmk.keys import make_key from kmk.extentions.led import AnimationModes
led_ext = LED(
def start_flicker(*args, **kwargs): led_pin=led_pin,
# Setting mode to user will use the user animation brightness_step=5,
keyboard.led.animation_mode = 'user' brightness_limit=100,
breathe_center=1.5,
animation_mode=AnimationModes.STATIC,
def flicker(self): animation_speed=1,
# This is the code that is run every cycle that can serve as an animation val=100,
# Refer to the kmk/rgb.py for actual examples of what has been done )
if self.brightness == 0:
self.brightness = 100
else:
self.brightness = 0
keyboard.led.set_brightness(self.brightness)
return self
# This is what "gives" your function to KMK so it knows what your animation code is
keyboard.led_config['user_animation'] = flicker
# Makes a key that would start your animation
LS = make_key(on_press=start_flicker())
keymap = [...LS,...]
``` ```
# Troubleshooting
Make sure that your board supports LED backlight by checking for a line with "LED_PIN". If it does not, you can add it to your keymap.
|Define |Description |
|---------------------|---------------------------------------------|
|`keyboard.led_pin` |The pin connected to the data pin of the LEDs|

22
docs/media_keys.md Normal file
View File

@@ -0,0 +1,22 @@
# Media Keys
Media keys extention adds keys for common media control keys. It can simply be added to the extentions list.
```python
from kmk.extensions.media_keys import MediaKeys
keyboard.extensions.append(MediaKeys())
```
## Keycodes
|Key |Aliases |Description |
|-----------------------|--------------------|-----------------------------------------------|
|`KC.AUDIO_MUTE` |`KC.MUTE` |Mute |
|`KC.AUDIO_VOL_UP` |`KC.VOLU` |Volume Up |
|`KC.AUDIO_VOL_DOWN` |`KC.VOLD` |Volume Down |
|`KC.MEDIA_NEXT_TRACK` |`KC.MNXT` |Next Track (Windows) |
|`KC.MEDIA_PREV_TRACK` |`KC.MPRV` |Previous Track (Windows) |
|`KC.MEDIA_STOP` |`KC.MSTP` |Stop Track (Windows) |
|`KC.MEDIA_PLAY_PAUSE` |`KC.MPLY` |Play/Pause Track |
|`KC.MEDIA_EJECT` |`KC.EJCT` |Eject (macOS) |
|`KC.MEDIA_FAST_FORWARD`|`KC.MFFD` |Next Track (macOS) |
|`KC.MEDIA_REWIND` |`KC.MRWD` |Previous Track (macOS) |

17
docs/modtap.md
View File

@@ -1,10 +1,12 @@
# ModTap # ModTap Keycodes
One key if you tap it, one or more modifier keys if you hold it! Enabling ModTap will give you access to the following keycodes and can simply be added to the extentions list.
```python
from kmk.extensions.modtap import ModTap
keyboard.extensions.append(ModTap())
```
## Helpful examples ## Keycodes
Just copy the example from New Keycode above your keymap and change KC.SOMETHING to the key that you want when tapped.
After that, just use the new keycode anywhere in your keymap.
|New Keycode | Description | |New Keycode | Description |
|-------------------------------------------------------|-----------------------------------------------------------------| |-------------------------------------------------------|-----------------------------------------------------------------|
@@ -22,9 +24,4 @@ After that, just use the new keycode anywhere in your keymap.
|MEH = KC.MT(KC.SOMETHING, KC.LCTRL(KC.LSFT(KC.LALT))) |`CTRL` and `LSHIFT` and `LALT` if held `kc` if tapped | |MEH = KC.MT(KC.SOMETHING, KC.LCTRL(KC.LSFT(KC.LALT))) |`CTRL` and `LSHIFT` and `LALT` if held `kc` if tapped |
|HYPR = KC.MT(KC.SOMETHING, KC.HYPR) |`LCTRL` and `LSHIFT` and `LALT` and `LGUI` if held `kc` if tapped| |HYPR = KC.MT(KC.SOMETHING, KC.HYPR) |`LCTRL` and `LSHIFT` and `LALT` and `LGUI` if held `kc` if tapped|
```python
SHFT_HOME = KC.MT(KC.HOME, KC.LSFT)
keyboard.keymap = [[ ...., SHFT_HOME, ....], ....]
```

60
docs/porting_to_kmk.md Normal file
View File

@@ -0,0 +1,60 @@
# Porting to KMK
Porting a board to KMK is quite simple, and follows this base format.
```python
import board
from kmk.kmk_keyboard import KMKKeyboard as _KMKKeyboard
from kmk.matrix import DiodeOrientation
{EXTENTIONS_IMPORT}
class KMKKeyboard(_KMKKeyboard):
{REQUIRED}
extensions = []
```
## REQUIRED
This is designed to be replaced with the defining pins of your keyboard. Rows, colums and the diode direction (if any), should be defined like this
```python
row_pins = [board.p0_31, board.p0_29, board.p0_02, board.p1_15]
col_pins = [board.p0_22, board.p0_24, board.p1_00, board.p0_11, board.p1_04]
diode_orientation = DiodeOrientation.COLUMNS
```
## Additional pins for extentions
KMK includes built in extentions for RGB and split keyboards, and powersave. If these are applicible on your keyboard/microcontroller, the pins should be added here. Refer to the instructions on the respective extentions page on how to add them. If not adding any extentions, leave this as an empty list as shown.
# Coord mapping
If your keyboard is not built electrically as a square (though most are), you can provide a mapping directly. An example of this is the[Corne](https://github.com/foostan/crkbd). That has 12 colums for 3 rows, and 6 colums for the bottom row. Split keyboards count as the total keyboard, not per side. That would look like this
```python
from kmk.matrix import intify_coordinate as ic
coord_mapping = []
coord_mapping.extend(ic(0, x) for x in range(12))
coord_mapping.extend(ic(1, x) for x in range(12))
coord_mapping.extend(ic(2, x) for x in range(12))
# And now, to handle R3, which at this point is down to just six keys
coord_mapping.extend(ic(3, x) for x in range(3, 9))
```
## Keymaps
Keymaps are organized as a list of lists. Keycodes are added for every key on each layer. See [keycodes](keycodes.md) for more details on what keycodes are avaliable. If using layers or other extentions, also refer to the extentions page for additional keycodes.
```python
from kb import KMKKeyboard
from kmk.keys import KC
keyboard = KMKKeyboard()
keyboard.keymap = [
[KC.A, KC.B],
[KC.C, KC.D],
]
if __name__ == '__main__':
keyboard.go()
```
## More information
More information on keymaps can be found [here](config_and_keymap.md)

39
docs/power.md Normal file
View File

@@ -0,0 +1,39 @@
# Power(save)
This extention allows you to save power and is targeted to bluetooth/battery based keyboards.
## Keycodes
|Key |Description |
|-----------------------|-------------------------|
|`KC.PS_TOG ` |Toggles powersave on/off |
|`KC.PS_ON ` |Turns powersave on |
|`KC.PS_OFF ` |Turns powersave off |
# Enabling the extention
To turn on basic power saving, this is all that is required.
```python
from kmk.extensions.power import Power
power = Power()
keyboard.extensions.append(power)
```
## Optional extra power saving
On supported boards, such as the nice!nano, power can be cut on VCC saving extra power if OLEDS or RGBs are installed.
These drain power even when off, so this will prevent them from doing it.
```python
from kmk.extensions.power import Power
# Your kb.py may already have this set. If not, add it like this
# import board
# keyboard.powersave_pin = board.P0_13
power = Power(powersave_pin=keyboard.powersave_pin)
keyboard.extensions.append(power)
```
Make sure that the pin is correct for your microcontroller. The example is for the nice!nano. Not all microcontrollers
have this feature and this can be omitted if not and there will simply be less power saving.

127
docs/rgb.md
View File

@@ -9,7 +9,6 @@ Currently we support the following addressable LEDs:
* WS2811, WS2812, WS2812B, WS2812C, etc. * WS2811, WS2812, WS2812B, WS2812C, etc.
* SK6812, SK6812MINI, SK6805 * SK6812, SK6812MINI, SK6805
* All neopixels
### Color Selection ### Color Selection
@@ -19,6 +18,16 @@ Changing the **Hue** cycles around the circle.
Changing the **Saturation** moves between the inner and outer sections of the wheel, affecting the intensity of the color. Changing the **Saturation** moves between the inner and outer sections of the wheel, affecting the intensity of the color.
Changing the **Value** sets the overall brightness. Changing the **Value** sets the overall brightness.
## Enabling the extention
The only required values that you need to give the RGB extention would be the pixel pin, and the number of pixels/LED's. If using a split keyboard, this number is per side, and not the total of both sides.
```python
from kmk.extensions.RGB import RGB
from kb import rgb_pixel_pin # This can be imported or defined manually
rgb_ext = RGB(pixel_pin=rgb_pixel_pin, num_pixels=27)
keyboard.extensions.append(rgb_ext)
```
## [Keycodes] ## [Keycodes]
|Key |Aliases |Description | |Key |Aliases |Description |
@@ -40,56 +49,27 @@ Changing the **Value** sets the overall brightness.
|`KC.RGB_MODE_SWIRL` |`RGB_M_S` |Swirl animation | |`KC.RGB_MODE_SWIRL` |`RGB_M_S` |Swirl animation |
## Configuration ## Configuration
|Define |Default |Description | All of these values can be set by default for when the keyboard boots.
|-------------------------------------|-------------|-----------------------------------------------------------------------------| ```python
|`keyboard.rgb_config['rgb_order']` |`(1, 0, 2)` |The order of the pixels R G B, and optionally white. Example(1, 0, 2, 3) | from kmk.extentions.rgb import AnimationModes
|`keyboard.rgb_config['hue_step']` |`10` |The number of steps to cycle through the hue by | rgb_ext = RGB(pixel_pin=rgb_pixel_pin,
|`keyboard.rgb_config['sat_step']` |`17` |The number of steps to change the saturation by | num_pixels=27
|`keyboard.rgb_config['val_step']` |`17` |The number of steps to change the brightness by | num_pixels=0,
|`keyboard.rgb_config['hue_default']` |`0` |The default hue when the keyboard boots | val_limit=100,
|`keyboard.rgb_config['sat_default']` |`100` |The default saturation when the keyboard boots | hue_default=0,
|`keyboard.rgb_config['val_default']` |`100` |The default value (brightness) when the keyboard boots | sat_default=100,
|`keyboard.rgb_config['val_limit']` |`255` |The maximum brightness level | rgb_order=(1, 0, 2), # GRB WS2812
val_default=100,
## Built-in Animation Configuration hue_step=5,
|Define |Default |Description | sat_step=5,
|----------------------------------------------|-------------|-------------------------------------------------------------------------------------| val_step=5,
|`keyboard.rgb_config['breathe_center']` |`1.5` |Used to calculate the curve for the breathing animation. Anywhere from 1.0 - 2.7 is valid| animation_speed=1,
|`keyboard.rgb_config['knight_effect_length']` |`4` |The number of LEDs to light up for the "Knight" animation | breathe_center=1, # 1.0-2.7
knight_effect_length=3,
## Functions animation_mode=AnimationModes.STATIC,
reverse_animation=False,
If you want to create your own animations, or for example, change the lighting in a macro, or a layer switch, here are some functions that are available. )
```
|Function |Description |
|--------------------------------------------------|--------------------------------------------------------------------------------------------|
|`keyboard.pixels.set_hsv_fill(hue, sat, val)` |Fills all LED's with HSV values |
|`keyboard.pixels.set_hsv(hue, sat, val, index)` |Sets a single LED with HSV value |
|`keyboard.pixels.set_rgb_fill((r, g, b))` |Fills all LED's with RGB(W) values |
|`keyboard.pixels.set_rgb((r, g, b), index)` |Set's a single LED with RGB(W) values |
|`keyboard.pixels.disable_auto_write(bool)` |When True, disables showing changes. Good for setting multiple LED's before a visible update|
|`keyboard.pixels.increase_hue(step)` |Increases hue by a given step |
|`keyboard.pixels.decrease_hue(step)` |Decreases hue by a given step |
|`keyboard.pixels.increase_sat(step)` |Increases saturation by a given step |
|`keyboard.pixels.decrease_sat(step)` |Decreases saturation by a given step |
|`keyboard.pixels.increase_val(step)` |Increases value (brightness) by a given step |
|`keyboard.pixels.decrease_val(step)` |Decreases value (brightness) by a given step |
|`keyboard.pixels.increase_ani()` |Increases animation speed by 1. Maximum 10 |
|`keyboard.pixels.decrease_ani()` |Decreases animation speed by 1. Minimum 10 |
|`keyboard.pixels.off()` |Turns all LED's off |
|`keyboard.pixels.show()` |Displays all stored configuration for LED's. Useful with disable_auto_write explained below |
|`keyboard.pixels.time_ms()` |Returns a time in ms since the board has booted. Useful for start/stop timers |
## Direct variable access
|Define |Default |Description |
|-----------------------------------|-----------|-----------------------------------------------------------------------------------------------------------|
|`keyboard.pixels.hue` |`0` |Sets the hue from 0-360 |
|`keyboard.pixels.sat` |`100` |Sets the saturation from 0-100 |
|`keyboard.pixels.val` |`80` |Sets the brightness from 1-255 |
|`keyboard.pixels.reverse_animation`|`False` |If true, some animations will run in reverse. Can be safely used in user animations |
|`keyboard.pixels.animation_mode` |`static` |This can be changed to any modes included, or to something custom for user animations. Any string is valid |
|`keyboard.pixels.animation_speed` |`1` |Increases animation speed of most animations. Recommended 1-5, Maximum 10. |
## Hardware Modification ## Hardware Modification
@@ -97,53 +77,10 @@ To add RGB LED's to boards that don't support them directly, you will have to ad
ground, and data pins will need added to an unused pin on your microcontroller unless your keyboard has specific solder points for them. With those 3 wires ground, and data pins will need added to an unused pin on your microcontroller unless your keyboard has specific solder points for them. With those 3 wires
connected, set the pixel_pin as described above, and you are ready to use your RGB LED's/Neopixels. connected, set the pixel_pin as described above, and you are ready to use your RGB LED's/Neopixels.
## ADVANCED USAGE
If you wish to interact with these as you would normal LED's and do not want help from KMK, you can disable all helper functions from working and access the
neopixel object directly like this.
```python
keyboard.pixels.disable_auto_write = True
keyboard.pixels.neopixel() # <-- This is the neopixel object
```
## User animations
User animations can be created as well. An example of a light show would look like this
```python
from kmk.keys import make_key
def start_light_show(*args, **kwargs):
# Setting mode to user will use the user animation
keyboard.pixels.animation_mode = 'user'
def light_show(self):
# This is the code that is run every cycle that can serve as an animation
# Refer to the kmk/rgb.py for actual examples of what has been done
self.hue = (self.hue + 35) % 360
keyboard.pixels.set_hsv_fill(self.hue, self.sat, self.val)
return self
# This is what "gives" your function to KMK so it knows what your animation code is
keyboard.rgb_config['user_animation'] = light_show
# Makes a key that would start your animation
LS = make_key(on_press=start_light_show)
keymap = [...LS,...]
```
## Troubleshooting ## Troubleshooting
### Incorrect colors ### Incorrect colors
If your colors are incorrect, check the pixel order of your specific LED's. Here are some common ones. If your colors are incorrect, check the pixel order of your specific LED's. Here are some common ones.
* WS2811, WS2812, WS2812B, WS2812C are all GRB (1, 0, 2) * WS2811, WS2812, WS2812B, WS2812C are all GRB (1, 0, 2)
* SK6812, SK6812MINI, SK6805 are all GRB (1, 0, 2) * SK6812, SK6812MINI, SK6805 are all GRB (1, 0, 2)
* Neopixels will vary depending on which one you buy. It will be listed on the product page.# Troubleshooting * Neopixels will vary depending on which one you buy. It will be listed on the product page.
### Lights don't turn on
Make sure that your board supports LED backlight by checking for a line with "PIXEL_PIN". If it does not, you can add it to your keymap.
If you added the LED's yourself, you will also need to set num_pixels to the number of installed LED's in total.
|Define |Description |
|---------------------|---------------------------------------------|
|`keyboard.pixel_pin` |The pin connected to the data pin of the LEDs|
|`keyboard.num_pixels`|The number of LEDs connected |

77
docs/split_keyboards.md
View File

@@ -1,35 +1,86 @@
# Split Keyboards # Split Keyboards
Split keyboards are mostly the same as unsplit and very easy to adapt a keymap for. Currently Split keyboards are mostly the same as unsplit. Wired UART and Bluetooth are supported.
UART is supported, though other modes will come later such as Bluetooth and i2c.
## UART ## Wired UART
To enable uart it's as simple as adding this line, of course changing the pin Wired connections can use UART over 1 or 2 wires. With 2 wires, you will be able to syncronize the halves allowing additional features in some extentions.
```python ```python
keyboard.split_type = "UART" import board
keyboard.uart_pin = board.SCL from kmk.extensions.split import Split
uart_pin = board.SOMETHING
split = Split(uart_pin=uart_pin)
keyboard.extensions.append(split)
``` ```
## Config ### Config
Useful config options: Useful config options:
```python ```python
keyboard.split_flip = True # If your boards are identical but one is flipped, this option is for you split = Split(
keyboard.split_offsets = [6, 6, 6, 6] # This is the how many keys are on each column on the "target" half is_target=True, # If this is the side connecting to the computer
extra_data_pin=None, # Second uart pin to allow 2 way communication
split_offset=None, # Default is column pins but allows an override
split_flip=True, # If both halves are the same, but flipped, set this True
split_side=None, # Sets if this is the left or right
split_type=SplitType.UART, # Defaults to UART
target_left=True, # Assumes that left will be the one on USB. Set to folse if it will be the right
uart_flip=True, # Reverses the RX and TX pins if both are provided
uart_pin=None, # The primary uart pin to talk to the secondary device with
uart_timeout=20, # Rarely needed to change, but is avaliable
)
```
## Bluetooth split (aka no TRRS)
Wireless splits are fully featured with 2 way communication allowing all extentions to work 100%.
```python
split_side = 'Left'
split_side = 'Right'
split = BLE_Split(split_side=split_side)
keyboard.extensions.append(split)
```
### Config
Useful config options:
```python
split = BLE_Split(
split_side=split_side, # See EE hands below
uart_interval=30, # Sets the uarts delay. Lower numbers draw more power
hid_type=HIDModes.BLE, # If using USB to connect to a computer, change this appropriately.
)
``` ```
### EE HANDS ### EE HANDS
If you want to plug in on either side, it can be done fairly easily but requires setup. If you want to plug USB in on either side, or are using bluetooth, this is for you. Pick one of the 2 options but not both.
## Renaming CIRCUITPY Drive
The easiest way is to rename your CIRCUITPY drive to something. The left side must end in L, the right must in in R.
The name must be 11 characters or less! This is a limitation of the filesystem. You will receive an error if you choose a
name longer than 11 characters. Instructions on how to do that are [here](https://learn.adafruit.com/welcome-to-circuitpython/the-circuitpy-drive).
For example on NYQUISTL for left and NYQUISTR for the right.
For wired connections you are done. For bluetooth, remove the `split_side` like tihs
```python
split = BLE_Split()
keyboard.extensions.append(split)
```
## Adding an extra file
If you have changed the name of the drive as stated above, do not follow this section.
On each half of your keyboard make a file called kmk_side.py and add one of these lines to the file On each half of your keyboard make a file called kmk_side.py and add one of these lines to the file
depending on where each piece is physically located. depending on where each piece is physically located.
```python ```python
split_target = "Left" split_side = "Left"
OR OR
split_target = "Right" split_side = "Right"
``` ```
and then in your keymap, add the line and then in your keymap, add the line
```python ```python
from kmk_side import split_target from kmk_side import split_side
``` ```

2
docs/tapdance.md
View File

@@ -39,8 +39,6 @@ are planned to be worked around "eventually", but for now are noteworthy:
Here's an example of all this in action: Here's an example of all this in action:
```python ```python
# user_keymaps/some_silly_example.py
from kmk.boards.klarank import KMKKeyboard
from kmk.keycodes import KC from kmk.keycodes import KC
from kmk.macros.simple import send_string from kmk.macros.simple import send_string

1
pyproject.toml
View File

@@ -15,6 +15,7 @@ exclude = '''
| \.pytest_cache | \.pytest_cache
| \.compiled | \.compiled
| dist | dist
| boards
| build | build
| docs | docs
| user_keymaps | user_keymaps

1
setup.cfg
View File

@@ -21,6 +21,7 @@ per-file-ignores =
# Allow misaligned array entries, crazy line lengths, unused variables, and # Allow misaligned array entries, crazy line lengths, unused variables, and
# multiple spaces after commas in lists (for grid alignment) # multiple spaces after commas in lists (for grid alignment)
user_keymaps/**/*.py: E131,F401,E501,E241,E131,BLK100 user_keymaps/**/*.py: E131,F401,E501,E241,E131,BLK100
boards/**/main.py: E131,F401,E501,E241,E131,BLK100
tests/test_data/keymaps/**/*.py: F401,E501 tests/test_data/keymaps/**/*.py: F401,E501
[isort] [isort]