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

Massive docs update

Browse Source
This commit is contained in:
Kyle Brown 2019-02-23 19:35:00 -08:00
parent 9fbad17ed4
commit 3ae7432de0
7 changed files with 177 additions and 23 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

41
docs/flashing.md
View File

@ -5,22 +5,39 @@ as appropriate (see [Adafruit's
documentation](https://learn.adafruit.com/welcome-to-circuitpython/installing-circuitpython), documentation](https://learn.adafruit.com/welcome-to-circuitpython/installing-circuitpython),
though it doesn't cover all CircuitPython boards - you may need to glance around though it doesn't cover all CircuitPython boards - you may need to glance around
the CircuitPython source or ask on Discord). We primarily target CircuitPython the CircuitPython source or ask on Discord). We primarily target CircuitPython
4.0-alpha1 and above, though many features should work on 3.x. You'll only need 4.0-alpha1 to 4.0-alpha3. You'll only need
to flash CircuitPython once (unless we update our baseline supported version). to flash CircuitPython once (unless we update our baseline supported version).
After CircuitPython has been flashed, a `CIRCUITPY` drive should show up on your After CircuitPython has been flashed, a `CIRCUITPY` drive should show up on your
computer (some Linux/BSD users without drive automounting will want to poke computer most likely. If not, check out the troubleshooting section below.
around `dmesg` to find the drive identifier and mount this drive manually
somewhere - ex. `mkdir -p ~/mnt && sudo mount -o uid=1000,gid=1000 /dev/sdf1
~/mnt`, where `uid` and `gid` are your user ID and primary group ID, as found in
`id -u` and `id -g`). Take note of the path that this is mounted to (for MacOS
users, this will probably look something like `/Volumes/CIRCUITPY`).
To "flash" all of KMK, your keymap, and a basic `main.py` that will start # Windows
everything up, run `make MOUNTPOINT=/path/to/wherever Currently, we do not have an official "flasher" for windows. You can manually install it fairly easily and we recommend coming to the KMK discord/Matrix server if you have any questions. An actual tool is in development. Alternatively, you can flash from any linux like tool set (Cygwin, WSL, ect) using the Linux guide below.
USER_KEYMAP=path/to/keymap.py`. For example, if my `CIRCUITPY` volume is mounted
to `~/mnt`, I might flash my development breadboard with the following: # Mac
Until an interactive installer is created, please follow the linux instructions replacing /mnt with /Volumes
# Linux
While in the directory for kmk, simply run this, changing the mount point and keymap name to whatever is appropriate.
```sh ```sh
make MOUNTPOINT=~/mnt USER_KEYMAP=user_keymaps/klardotsh/itsybitsy_m4_express/threethree.py make MOUNTPOINT=/mnt/CIRCUITPY USER_KEYMAP=user_keymaps/nameofyourkeymap.py
``` ```
# Troubleshooting
## Windows
Please join us on the Discord/Matrix server and we can help you out
## Mac
Please join us on the Discord/Matrix server and we can help you out
## Linux/BSD
Check to see if your drive may have mounted elsewhere with a gui tool. Most will give you the directory in the GUI.
If it's not mounted, you can read up on how to mount a drive manually here. https://wiki.archlinux.org/index.php/File_systems#Mount_a_file_system
It would look something like this
`sudo mount -o uid=1000,gid=1000 /dev/sdf1 ~/mnt`
If you still are having issues, come say hi in the Discord/Matrix servers and we'll help you out.

7
docs/hardware.md
View File

@ -5,10 +5,6 @@
| [Adafruit Feather M4 Express](https://www.adafruit.com/product/3857) | Atmel SAMD51 (Cortex M4F) | CircuitPython | An economical solution for basic USB keyboards | | [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 ItsyBitsy M4 Express](https://www.adafruit.com/product/3800) | Atmel SAMD51 (Cortex M4F) | CircuitPython | A smaller solution for basic USB keyboards |
## Community Supported
| Board | Chipset | Python Platform | Maintainer | Notes |
| ----- | ------- | --------------- | ----- | ----- |
| [pyboard v1.1](https://www.adafruit.com/product/2390) | STM32F405RG (Cortex M4F) | MicroPython | kdb424 | Very large and expensive, and has ram limitations. |
## Support Planned/WIP ## Support Planned/WIP
| Board | Chipset | Python Platform | Notes | | Board | Chipset | Python Platform | Notes |
@ -20,7 +16,6 @@
## Unsupported Devices ## Unsupported Devices
Here's a list of problematic, but possibly usable microcontrollers: Here's a list of problematic, but possibly usable microcontrollers:
| Board | Chipset | Python Platform | Notes | | Board | Chipset | Python Platform | Notes |
@ -38,7 +33,7 @@ keyboards/microcontrollers. The base requirements for device support
## Secondary Support ## Secondary Support
In the future, secondary support for lesser contollers is planned. One of 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 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 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 used to convert boards that use USB or i2c that run lesser chips to a KMK

37
docs/keycodes.md
View File

@ -230,3 +230,40 @@
|`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] NOT IMPLEMENTED AT THIS TIME
|Key |Aliases |Description |
|------------|---------------------------------------|-------------------------------------------------------|
|`LCTL_T(kc)`|`CTL_T(kc)` |Left Control when held, `kc` when tapped |
|`RCTL_T(kc)`| |Right Control when held, `kc` when tapped |
|`LSFT_T(kc)`|`SFT_T(kc)` |Left Shift when held, `kc` when tapped |
|`RSFT_T(kc)`| |Right Shift when held, `kc` when tapped |
|`LALT_T(kc)`|`ALT_T(kc)` |Left Alt when held, `kc` when tapped |
|`RALT_T(kc)`|`ALGR_T(kc)` |Right Alt when held, `kc` when tapped |
|`LGUI_T(kc)`|`LCMD_T(kc)`, `RWIN_T(kc)`, `GUI_T(kc)`|Left GUI when held, `kc` when tapped |
|`RGUI_T(kc)`|`RCMD_T(kc)`, `RWIN_T(kc)` |Right GUI when held, `kc` when tapped |
|`C_S_T(kc)` | |Left Control and Shift when held, `kc` when tapped |
|`MEH_T(kc)` | |Left Control, Shift and Alt when held, `kc` when tapped|
|`LCAG_T(kc)`| |Left Control, Alt and GUI when held, `kc` when tapped |
|`RCAG_T(kc)`| |Right Control, Alt and GUI when held, `kc` when tapped |
|`ALL_T(kc)` | |Left Control, Shift, Alt and GUI when held, `kc` when tapped - more info [here](http://brettterpstra.com/2012/12/08/a-useful-caps-lock-key/)|
|`SGUI_T(kc)`|`SCMD_T(kc)`, `SWIN_T(kc)` |Left Shift and GUI when held, `kc` when tapped |
|`LCA_T(kc)` | |Left Control and Alt when held, `kc` when tapped |

105
docs/rgb.md Normal file
View File

@ -0,0 +1,105 @@
# 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/master/neopixel.py
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
## Usage
At minimum you will need to make sure that these are set in either your keymap ip importing an MCU directly, or it should be included in the predefined boards if they support them.
|Define |Description |
|---------------------|---------------------------------------------|
|`keyboard.pixel_pin` |The pin connected to the data pin of the LEDs|
|`keyboard.num_pixels`|The number of LEDs connected |
Then you should be able to use the keycodes below to change the RGB lighting to your liking.
### 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.
<img src="gitbook/images/color-wheel.svg" alt="HSV Color Wheel" width="250"/>
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.
## [Keycodes]
|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 |
## Configuration
|Define |Default |Description |
|---------------------|-------------|-----------------------------------------------------------------------------|
|`keyboard.hue_step` |`10` |The number of steps to cycle through the hue by |
|`keyboard.sat_step` |`17` |The number of steps to increment the saturation by |
|`keyboard.val_step` |`17` |The number of steps to increment the brightness by |
|`keyboard.val_limit` |`255` |The maximum brightness level |
## 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.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.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.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 |
Other settings that are useful that can be changed.
## Configuration
|Define |Default |Description |
|------------------------------|-------------|---------------------------------------------------------------------------------------------------------|
|`keyboard.hue` |`0` |Sets the hue from 0-360 |
|`keyboard.sat` |`100` |Sets the saturation from 0-100 |
|`keyboard.val` |`80` |Sets the brightness from 1-255 |
|`keyboard.disable_auto_write` |`False` |When True, disables showing changes. Good for setting multiple LED's before a visible update |
|`keyboard.reverse_animation` |`False` |If true, some animations will run in reverse. Can be safely used in user animations |
|`keyboard.animation_mode` |`static` |This can be changed to any modes included, or to something custom for user animations. Any string is valid |
|`keyboard.animation_speed` |`1` |Increases animation speed of most animations. Recommended 1-5 |
## Built-in Animation Configuration
|Define |Default |Description |
|-------------------------------|-------------|-------------------------------------------------------------------------------------|
|`keyboard.breath_center` |`1.5` |Used to calculate the curve for the breathing animation. Anywhere from 1.0 - 2.7 is valid|
|`keyboard.knight_effect_length`|`4` |The number of LEDs to light up for the "Knight" animation |
## Hardware Modification
To add LED's to boards that don't support them, 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 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.disabse_auto_write = True
keyboard.pixels.neopixel() # <-- This is the neopixel object
```

2
docs/sequences.md
View File

@ -1,4 +1,4 @@
# Sequences # Sequences/Macros
Sequences are used for sending multiple keystrokes in a single action, and can Sequences are used for sending multiple keystrokes in a single action, and can
be used for things like unicode characters (even emojis! 🇨🇦), lorei epsum be used for things like unicode characters (even emojis! 🇨🇦), lorei epsum

2
docs/tapdance.md
View File

@ -1,6 +1,6 @@
# Tap Dance # Tap Dance
Tap dance is a way to allow a single physical key to work as multple logical Tap dance is a way to allow a single physical key to work as multiple logical
keys / actions without using layers. With basic tap dance, you can trigger these keys / actions without using layers. With basic tap dance, you can trigger these
"nested" keys or macros through a series of taps of the physical key within a "nested" keys or macros through a series of taps of the physical key within a
given timeout. given timeout.

6
kmk/rgb.py
View File

@ -19,9 +19,9 @@ class RGB:
# Set by config # Set by config
num_pixels = 0 num_pixels = 0
hue_step = 1 hue_step = 10
sat_step = 5 sat_step = 17
val_step = 5 val_step = 17
breath_center = 1.5 # 1.0-2.7 breath_center = 1.5 # 1.0-2.7
knight_effect_length = 4 knight_effect_length = 4
val_limit = 255 val_limit = 255