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

requested changes

Browse Source
This commit is contained in:
Kyle Brown
2020-11-06 01:16:29 -08:00
parent 7a2bed8cdd
commit dea771fd7f
28 changed files with 263 additions and 158 deletions
Download Patch File Download Diff File Expand all files Collapse all files

70
docs/Getting_Started.md
View File

@@ -1,29 +1,52 @@
# 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)
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.
## 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
### 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
## 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)
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).
@@ -32,10 +55,17 @@ If you are porting a board to KMK, check the page [here](porting_to_kmk.md).
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)
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 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.

21
docs/Offiially_Supported_Microcontrollers.md
View File

@@ -1,15 +1,17 @@
# 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.
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
- 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
- $25 USD per microcontroller at most retailers
Recommended Retailers
[Boardsource](https://boardsource.xyz/store/5f4a1733bbaa5c635b83ed67)
@@ -17,11 +19,12 @@ Recommended Retailers
## ItsyBitsy M4 Express
Features include
- Affordable at \$15 USD
- 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)
- 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)
@@ -29,11 +32,13 @@ Recommended Retailers
## Adafruit ItsyBitsy nRF52840 Express
Features include
- Both USB HID and Bluetooth support
- More affordable than the Nice!Nano at only \$18
- 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)
- 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

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')
```

8
docs/config_and_keymap.md
View File

@@ -2,8 +2,8 @@
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 QMK keyboards are supported
through our ItsyBitsy to ProMicro pinout adapter, or with a nice!nano).
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!
@@ -79,6 +79,6 @@ You can further define a bunch of other stuff:
console. This is very rarely needed, but can provide very valuable information
if you need to open an issue.
- `beyboard.tap_time` which defines how long `KC.TT` and `KC.LT` will wait before
considering a key "held" (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`)

18
docs/extensions.md
View File

@@ -1,17 +1,21 @@
# 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!
Extensions allow more features to be added ot KMK such as RGB, power saving and
more. Extensions listed on this page are supported by default 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
These extensions are proveded in all builds and can be enabled. Currently offered
xtensions 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
- [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.
- [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.
- [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.
```sh
make MOUNTPOINT=/media/CIRCUITPY USER_KEYMAP=user_keymaps/nameofyourkeymap.py BOARD=board/nameofyourboar/kb.py
make MOUNTPOINT=/media/CIRCUITPY USER_KEYMAP=user_keymaps/nameofyourkeymap.py BOARD=board/nameofyourboard/kb.py
```
# Troubleshooting

6
docs/handwiring.md
View File

@@ -1,2 +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)
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)

3
docs/international.md
View File

@@ -1,5 +1,6 @@
# International Keycodes
International extention adds keys for non US layouts. It can simply be added to the extentions list.
International extention adds keys for non US layouts. It can simply be added to
the extentions list.
```python
from kmk.extensions.international import International

3
docs/layers.md
View File

@@ -1,5 +1,6 @@
# Layers
Layers extention adds keys for accessing other layers. It can simply be added to the extentions list.
Layers extention adds keys for accessing other layers. It can simply be added to
the extentions list.
```python
from kmk.extensions.layers import Layers

4
docs/led.md
View File

@@ -2,7 +2,9 @@
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.
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

3
docs/media_keys.md
View File

@@ -1,5 +1,6 @@
# Media Keys
Media keys extention adds keys for common media control keys. It can simply be added to the extentions list.
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

3
docs/modtap.md
View File

@@ -1,5 +1,6 @@
# ModTap Keycodes
Enabling ModTap will give you access to the following keycodes and can simply be added to the extentions list.
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

19
docs/porting_to_kmk.md
View File

@@ -15,7 +15,8 @@ class KMKKeyboard(_KMKKeyboard):
```
## 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
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]
@@ -23,10 +24,17 @@ This is designed to be replaced with the defining pins of your keyboard. Rows, c
```
## 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.
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
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
@@ -40,7 +48,10 @@ from kmk.matrix import intify_coordinate as ic
## 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.
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

13
docs/power.md
View File

@@ -1,5 +1,6 @@
# Power(save)
This extention allows you to save power and is targeted to bluetooth/battery based keyboards.
This extention allows you to save power and is targeted to bluetooth/battery
based keyboards.
## Keycodes
|Key |Description |
@@ -20,8 +21,9 @@ 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.
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.extensions.power import Power
@@ -35,5 +37,6 @@ 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.
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.

7
docs/rgb.md
View File

@@ -1,8 +1,11 @@
# 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:

27
docs/split_keyboards.md
View File

@@ -3,7 +3,8 @@ Split keyboards are mostly the same as unsplit. Wired UART and Bluetooth are sup
## 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.
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
import board
from kmk.extensions.split import Split
@@ -21,7 +22,7 @@ Useful config options:
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_side=None, # Sets if this is to 0 if left, 1 if right, or use EE hands
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
@@ -34,8 +35,9 @@ Useful config options:
## 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_side = 0 # Left
OR
split_side = 1 # Right
split = BLE_Split(split_side=split_side)
keyboard.extensions.append(split)
@@ -53,15 +55,18 @@ Useful config options:
```
### EE HANDS
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.
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).
The easiest way is to rename your CIRCUITPY drive to something. 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 are done. For bluetooth, remove the `split_side` like tihs
For wired connections you are done. For bluetooth, remove the `split_side` like this
```python
split = BLE_Split()
@@ -74,9 +79,9 @@ If you have changed the name of the drive as stated above, do not follow this se
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.
```python
split_side = "Left"
split_side = 0 # Left
OR
split_side = "Right"
split_side = 1 # Right
```
and then in your keymap, add the line

9
docs/support.md
View File

@@ -1,6 +1,9 @@
# 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 are having any issues in installing, configuring, or otherwise issues with
KMK, please reach out to us and our community here. 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.
# Matrix
* [Software Support](https://matrix.to/#/#kmk-support:kmkfw.io)
@@ -9,4 +12,4 @@ our community here.
# Discord
* [General support](https://discord.gg/NDUau62)
* [General support](https://discord.gg/NDUau62)