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

feat(extensions): most of the extensions implementation, by kdb424

Browse Source
This commit is contained in:
Kyle Brown
2020-10-21 12:19:42 -07:00
committed by Josh Klar
parent 9821f7bcc3
commit e72d2b8c34
140 changed files with 3860 additions and 2312 deletions
Download Patch File Download Diff File Expand all files Collapse all files

71
docs/Getting_Started.md Normal file
View File

@@ -0,0 +1,71 @@
# 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
### 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. For the nice!nano, this is highly recommended, and used in place of
Circuitpython.
Notable differences include
- Built in libraries for bluetooth, RGB, and more
- Saves space as builds are optimized for keyboards
- Microcontrollers like the nice!nano will be able to access all features out of
the box.
### Circuitpython
Circuitpython can be installed by following this guide 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.
#### Notable differences include
- Supports more devices
- Less built in libraries. If using RGB, bluetooth, and more, you will have to
add these libraries yourself
- Some devices such as the nice!nano don't have much free space, so not all
features can be installed at the same time
## 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, simply visit 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). If using Curcuitpython and NOT KMKPython, you will
also need [boot.py](https://github.com/KMKfw/kmk_firmware/blob/master/boot.py)
### 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. If you ask for help on chat or open a bug report, if possible
please give us your commit SHA, found by running
`from kmk.consts import KMK_RELEASE; print(KMK_RELEASE)` in the REPL on your
controller.

47
docs/Offiially_Supported_Microcontrollers.md Normal file
View File

@@ -0,0 +1,47 @@
# 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.

31
docs/ble_hid.md Normal file
View File

@@ -0,0 +1,31 @@
# BLE HID
Bluetooth connections help clean up the wire mess!
## Circuitpython
If not running KMKpython, this does require the adafruit_ble library from Adafruit.
This can be downloaded
[here](https://github.com/adafruit/Adafruit_CircuitPython_BLE/tree/master/adafruit_ble).
It is part of the [Adafruit CircuitPython Bundle](https://github.com/adafruit/Adafruit_CircuitPython_Bundle).
Simply put this in the "root" of your circuitpython device. If unsure, it's the folder with main.py in it, and should be the first folder you see when you open the device.
## Enabling BLE
To enable BLE hid, change the keyboard.go(). By default, the advertised name
will be the name of the "flash drive". By default this is CIRCUITPY
```python
if __name__ == '__main__':
keyboard.go(hid_type=HIDModes.BLE)
```
## Changing the advertisee name
There are two ways to change the advertising name. The first would be to
[change the name of the drive](https://learn.adafruit.com/welcome-to-circuitpython/the-circuitpy-drive).
The second would be to change the keyboard.go() like this.
```python
if __name__ == '__main__':
keyboard.go(hid_type=HIDModes.BLE, ble_name='KMKeyboard')
```

35
docs/config_and_keymap.md
View File

@@ -2,9 +2,10 @@
KMK is configured through a rather large plain-old-Python class called
`KMKKeyboard`. Subclasses of this configuration exist which pre-fill defaults
for various known keyboards (for example, many Keebio keyboards are supported
through our ItsyBitsy to ProMicro pinout adapter). This class is the main
interface between end users and the inner workings of KMK. Let's dive in!
for various known keyboards (for example, many QMK, TMK, or ZMK keyboards
are supported with a nice!nano, or through our ItsyBitsy to ProMicro pinout adapter.
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
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
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
the parentheses)
@@ -77,29 +75,10 @@ keyboard.keymap = [[KC.A, KC.B]]
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
if you need to open an issue.
- `unicode_mode` from `kmk.consts.UnicodeMode`, which defines the default
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`)
- `keyboard.tap_time` which defines how long `KC.TT` and `KC.LT` will wait before
considering a key "held" (see `layers.md`)
- `tap_time` which defines how long `KC.TT` and `KC.LT` will wait before
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
need debugging.
```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

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 ....... ]
```

14
docs/extensions.md Normal file
View File

@@ -0,0 +1,14 @@
# Extensions
Extensions add features that change the experience, but not the core features of
the keyboard. They are meant to be easy to add, and create your own. These live in
a sandbox to help prevent any bad code from crashing your keyboard.
## Core Extensions
These extensions are proveded in all builds and can be enabled. Currently offered
extensions are
- [International](international.md): Adds international keycodes
- [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
- [RGB](rgb.md): RGB lighting for underglow. Will work on most matrix RGB as will
be treated the same as underglow.

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.
```sh
make MOUNTPOINT=/media/CIRCUITPY USER_KEYMAP=user_keymaps/nameofyourkeymap.py
make MOUNTPOINT=/media/CIRCUITPY USER_KEYMAP=user_keymaps/nameofyourkeymap.py BOARD=board/nameofyourboard/kb.py
```
# Troubleshooting

6
docs/handwiring.md Normal file
View File

@@ -0,0 +1,6 @@
# 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.

35
docs/international.md Normal file
View File

@@ -0,0 +1,35 @@
# 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.RBRACKET` |`KC.RBRC` |`]` and `}` |
|`KC.BSLASH` |`KC.BSLS` |`\` and <code>&#124;</code> |
|`KC.NONUS_HASH` |`KC.NUHS` |Non-US `#` and `~` |
|`KC.SCOLON` |`KC.SCLN` |`;` and `:` |
|`KC.QUOTE` |`KC.QUOT` |`'` and `"` |
|`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_0` |`KC.P0` |Keypad `0` and Insert |
|`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.F13` | |F13 |
|`KC.F14` | |F14 |
@@ -121,24 +119,6 @@
|`KC.LOCKING_SCROLL` |`KC.LSCR` |Locking Scroll Lock |
|`KC.KP_COMMA` |`KC.PCMM` |Keypad `,` |
|`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.LSHIFT` |`KC.LSFT` |Left Shift |
|`KC.LALT` | |Left Alt |
@@ -190,11 +170,10 @@
|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.GESC` |Escape when tapped, <code>&#96;</code> when pressed with Shift or 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_LINUX` |Sets UnicodeMode to Linux |
|`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. |
## [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]
|Key |Description |
@@ -230,41 +196,6 @@
|`KC.RALT(kc)`|Hold Right Alt 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]

21
docs/layers.md Normal file
View File

@@ -0,0 +1,21 @@
# Layers
Layers module adds keys for accessing other layers. It can simply be added to
the extentions list.
```python
from kmk.modules.layers import Layers
keyboard.modules.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 |

68
docs/leader.md
View File

@@ -1,68 +0,0 @@
# Leader Key
The leader key acts as a prefix to a key sequence. These can be used to trigger macros quickly
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.
Leader key sequences can be as long or short as you like. The action must be a macro, so it
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.
1. Assign a key to KC.LEAD
2. Above your keymap, include a LEADER_DICTIONARY.
```python
from kmk.macros.simple import simple_key_sequence
# ...
keyboard.leader_dictionary = {
(KC.T, KC.A, KC.S, KC.K): simple_key_sequence([Modifiers.KC_LCTRL(Modifiers.KC_LSHIFT(Common.KC_ESC))])
}
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
1. LeaderMode.TIMEOUT (the default)
2. LeaderMode.ENTER
### Timeout Mode
Will expire after a timer and trigger the sequence that matches if any.
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
Has no timeout. To end sequence press the enter key, or cancel and do nothing, press escape.
This can be enabled with
```python
from kmk.consts import LeaderMode
keyboard.leader_mode = LeaderMode.ENTER
```

87
docs/led.md
View File

@@ -1,5 +1,17 @@
# LED (Mono color backlight)
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]
@@ -14,69 +26,16 @@ Want your keyboard to shine? Add some lights!
|`KC.LED_MODE_BREATHE` |`LED_M_B` |Breathing animation |
## Configuration
|Define |Default |Description |
|-----------------------------------------|-------------|------------------------------------------------|
|`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
All of these values can be set by default for when the keyboard boots.
```python
from kmk.keys import make_key
def start_flicker(*args, **kwargs):
# Setting mode to user will use the user animation
keyboard.led.animation_mode = 'user'
def flicker(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
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,...]
from kmk.extentions.led import AnimationModes
led_ext = LED(
led_pin=led_pin,
brightness_step=5,
brightness_limit=100,
breathe_center=1.5,
animation_mode=AnimationModes.STATIC,
animation_speed=1,
val=100,
)
```
# 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|

23
docs/media_keys.md Normal file
View File

@@ -0,0 +1,23 @@
# 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) |

22
docs/modtap.md
View File

@@ -1,10 +1,13 @@
# ModTap
One key if you tap it, one or more modifier keys if you hold it!
## Helpful examples
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.
# ModTap Keycodes
Enabling ModTap will give you access to the following keycodes and can simply be
added to the modules list.
```python
from kmk.modules.modtap import ModTap
keyboard.modules.append(ModTap())
```
## Keycodes
|New Keycode | Description |
|-------------------------------------------------------|-----------------------------------------------------------------|
@@ -22,9 +25,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 |
|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, ....], ....]
```

15
docs/modules.md Normal file
View File

@@ -0,0 +1,15 @@
# Modules
Modules, unlike extensions, change how your keyboard works. These are meant to have
the ability to alter the core code in any way. Unlike extensions, these are not in a
sandbox, and can make massive changes to normal operation.
## Core Modules
These modules are proveded in all builds and can be enabled. Currently offered
modules are
- [Layers](layers.md): Adds layer support (Fn key) to allow many more keys to be
put on your keyboard
- [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.
- [Split](split_keyboards.md): Keyboards split in two. Seems ergonomic!

71
docs/porting_to_kmk.md Normal file
View File

@@ -0,0 +1,71 @@
# 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)

42
docs/power.md Normal file
View File

@@ -0,0 +1,42 @@
# Power(save)
This module 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.modules.power import Power
power = Power()
keyboard.modules.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 so.
```python
from kmk.modules.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.modules.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.

95
docs/rgb.md
View File

@@ -1,16 +1,18 @@
# RGB/Underglow/Neopixel
Want your keyboard to shine? Add some lights!
This does require the neopixel library from Adafruit. This can be downloaded [here](https://github.com/adafruit/Adafruit_CircuitPython_NeoPixel/blob/6e35cd2b40575a20e2904b096508325cef4a71d3/neopixel.py).
It is part of the [Adafruit CircuitPython Bundle](https://github.com/adafruit/Adafruit_CircuitPython_Bundle).
## Circuitpython
If not running KMKpython, this does require the neopixel library from Adafruit.
This can be downloaded
[here](https://github.com/adafruit/Adafruit_CircuitPython_NeoPixel/blob/6e35cd2b40575a20e2904b096508325cef4a71d3/neopixel.py).
It is part of the [Adafruit CircuitPython Bundle](https://github.com/adafruit/Adafruit_CircuitPython_Bundle).
Simply put this in the "root" of your circuitpython device. If unsure, it's the folder with main.py in it, and should be the first folder you see when you open the device.
Currently we support the following addressable LEDs:
* WS2811, WS2812, WS2812B, WS2812C, etc.
* SK6812, SK6812MINI, SK6805
* All neopixels
### Color Selection
KMK uses [Hue, Saturation, and Value](https://en.wikipedia.org/wiki/HSL_and_HSV) to select colors rather than RGB. The color wheel below demonstrates how this works.
@@ -19,6 +21,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 **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]
|Key |Aliases |Description |
@@ -92,55 +104,46 @@ If you want to create your own animations, or for example, change the lighting i
|`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. |
```python
from kmk.extentions.rgb import AnimationModes
rgb_ext = RGB(pixel_pin=rgb_pixel_pin,
num_pixels=27
num_pixels=0,
val_limit=100,
hue_default=0,
sat_default=100,
rgb_order=(1, 0, 2), # GRB WS2812
val_default=100,
hue_step=5,
sat_step=5,
val_step=5,
animation_speed=1,
breathe_center=1, # 1.0-2.7
knight_effect_length=3,
animation_mode=AnimationModes.STATIC,
reverse_animation=False,
)
```
## Hardware Modification
To add RGB LED's to boards that don't support them directly, you will have to add a 3 wires. The power wire will run on 3.3v or 5v (depending on the LED),
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.
## 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,...]
```
To add RGB LED's to boards that don't support them directly, you will have to
add a 3 wires. The power wire will run on 3.3v or 5v (depending on the LED),
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.
## Troubleshooting
### Incorrect colors
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)
* 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.
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.

29
docs/sequences.md
View File

@@ -70,35 +70,6 @@ keymap = [...emoticons.BEER, emoticons.HAND_WAVE...]
> `kmk.types.AttrDict`, which you can think of as a read-only view over a
> dictionary adding attribute-based (dot-notation) access.
Remember from the Leader Mode documentation that leader sequences simply bind to
keys, so extrapolating this example out a bit, you can bind emojis to leader
sequences matching some name or mnemonic representing the sequence you're
looking to send. If you ever wanted to type `<Leader>fire` and see a fire emoji
on your screen, welcome home.
```python
from kmk.handlers.sequences import compile_unicode_string_sequences as cuss
emoticons = cuss({
# Emojis
'BEER': r'🍺',
'BEER_TOAST': r'🍻',
'FACE_THINKING': r'🤔',
'FIRE': r'🔥',
'FLAG_CA': r'🇨🇦',
'FLAG_US': r'🇺🇸',
})
keyboard.leader_dictionary = {
'beer': emoticons.BEER,
'beers': emoticons.BEER_TOAST,
'fire': emoticons.FIRE,
'uhh': emoticons.FACE_THINKING,
'fca': emoticons.FLAG_CA,
'fus': emoticons.FLAG_US,
}
```
Finally, if you need to send arbitrary unicode codepoints in raw form, that's
supported too, through `unicode_codepoint_sequence`.

70
docs/split_keyboards.md
View File

@@ -1,35 +1,63 @@
# Split Keyboards
Split keyboards are mostly the same as unsplit and very easy to adapt a keymap for. Currently
UART is supported, though other modes will come later such as Bluetooth and i2c.
Split keyboards are mostly the same as unsplit. Wired UART and Bluetooth are supported.
## UART
To enable uart it's as simple as adding this line, of course changing the pin
## Wired UART
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
keyboard.split_type = "UART"
keyboard.uart_pin = board.SCL
from kb import data_pin
:from kmk.modules.split import Split, SplitType
split = Split(split_side=SplitSide.LEFT)
keyboard.modules.append(split)
```
## Config
## Bluetooth split (aka no TRRS)
Wireless splits are fully featured with 2 way communication allowing all extentions to work 100%.
```python
from kb import data_pin
from kmk.modules.split import Split, SplitType, Split_Side
split = Split(split_type=Split.BLE, split_side=SplitSide.LEFT)
OR
split = Split(split_type=Split.BLE, split_side=SplitSide.LEFT)
keyboard.modules.append(split)
```
### Config
Useful config options:
```python
keyboard.split_flip = True # If your boards are identical but one is flipped, this option is for you
keyboard.split_offsets = [6, 6, 6, 6] # This is the how many keys are on each column on the "target" half
split = Split(
split_flip=True, # If both halves are the same, but flipped, set this True
split_side=None, # Sets if this is to SplitSide.LEFT or SplitSide.RIGHT, or use EE hands
split_type=SplitType.UART, # Defaults to UART
split_target_left=True, # If you want the right to be the target, change this to false
uart_interval=20, # Sets the uarts delay. Lower numbers draw more power
data_pin=None, # The primary data pin to talk to the secondary device with
data_pin2=None, # Second uart pin to allow 2 way communication
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
)
```
### 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.
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.
Rename your CIRCUITPY drive to something different. The left side must
end in L, the right must is 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 don't need to pass anything. For bluetooth, remove the `split_side` like this
```python
split_target = "Left"
OR
split_target = "Right"
# Wired
split = Split()
# Wireless
split = Split(split_type=Split.BLE)
```
and then in your keymap, add the line
```python
from kmk_side import split_target
```

12
docs/support.md
View File

@@ -1,13 +1,15 @@
# Support
If you are having any issues in installing, configuring, or otherwise issues
with KMK, please reach out to us and our community here.
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.
If you ask for help on chat or open a bug report, if possible please give us
your commit SHA, found by running `from kmk.consts import KMK_RELEASE;
print(KMK_RELEASE)` in the REPL on your controller.
your commit SHA, found by running
```python
from kmk.consts import KMK_RELEASE; print(KMK_RELEASE)
```
in the REPL on your controller.

8
docs/tapdance.md
View File

@@ -15,7 +15,7 @@ quickly, then tapped and held (both actions within the timeout window), the
letter "b" will be held down until the tap dance key is released.
To use this, you may want to define a `tap_time` value in your keyboard
configuration. This is an integer in milliseconds, and defaults to `300`.
configuration. This is an integer in milliseconds, and defaults to `300`.
You'll then want to create a sequence of keys using `KC.TD(KC.SOMETHING,
KC.SOMETHING_ELSE, MAYBE_THIS_IS_A_MACRO, WHATEVER_YO)`, and place it in your
@@ -32,15 +32,9 @@ are planned to be worked around "eventually", but for now are noteworthy:
we strongly recommend avoiding `KC.MO` (or any other layer switch keys that
use momentary switch behavior - `KC.LM`, `KC.LT`, and `KC.TT`)
- Super fancy stuff like sending a keypress only when the leader key is released
(perhaps based on how long the leader key was held) is **unsupported** - an
example use case might be "tap for Home, hold for Shift"
Here's an example of all this in action:
```python
# user_keymaps/some_silly_example.py
from kmk.boards.klarank import KMKKeyboard
from kmk.keycodes import KC
from kmk.macros.simple import send_string