diff --git a/docs/flashing.md b/docs/flashing.md index 2b2d377..121f5f5 100644 --- a/docs/flashing.md +++ b/docs/flashing.md @@ -5,22 +5,39 @@ as appropriate (see [Adafruit's documentation](https://learn.adafruit.com/welcome-to-circuitpython/installing-circuitpython), 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 -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). 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 -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`). +computer most likely. If not, check out the troubleshooting section below. -To "flash" all of KMK, your keymap, and a basic `main.py` that will start -everything up, run `make MOUNTPOINT=/path/to/wherever -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: +# Windows +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. + +# 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 -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. diff --git a/docs/hardware.md b/docs/hardware.md index d7e0c3c..4aed0b1 100644 --- a/docs/hardware.md +++ b/docs/hardware.md @@ -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 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 | Board | Chipset | Python Platform | Notes | @@ -20,7 +16,6 @@ ## Unsupported Devices - Here's a list of problematic, but possibly usable microcontrollers: | Board | Chipset | Python Platform | Notes | @@ -38,7 +33,7 @@ keyboards/microcontrollers. The base requirements for device 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 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 diff --git a/docs/keycodes.md b/docs/keycodes.md index a8d4fa0..4d0a7f3 100644 --- a/docs/keycodes.md +++ b/docs/keycodes.md @@ -230,3 +230,40 @@ |`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] 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 | diff --git a/docs/rgb.md b/docs/rgb.md new file mode 100644 index 0000000..10dbcc3 --- /dev/null +++ b/docs/rgb.md @@ -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. + +HSV Color Wheel + +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 +``` diff --git a/docs/sequences.md b/docs/sequences.md index 3a18523..30b80de 100644 --- a/docs/sequences.md +++ b/docs/sequences.md @@ -1,4 +1,4 @@ -# Sequences +# Sequences/Macros Sequences are used for sending multiple keystrokes in a single action, and can be used for things like unicode characters (even emojis! 🇨🇦), lorei epsum diff --git a/docs/tapdance.md b/docs/tapdance.md index 0f79078..bf73daf 100644 --- a/docs/tapdance.md +++ b/docs/tapdance.md @@ -1,6 +1,6 @@ # 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 "nested" keys or macros through a series of taps of the physical key within a given timeout. diff --git a/kmk/rgb.py b/kmk/rgb.py index 85a0a0a..4257fd7 100644 --- a/kmk/rgb.py +++ b/kmk/rgb.py @@ -19,9 +19,9 @@ class RGB: # Set by config num_pixels = 0 - hue_step = 1 - sat_step = 5 - val_step = 5 + hue_step = 10 + sat_step = 17 + val_step = 17 breath_center = 1.5 # 1.0-2.7 knight_effect_length = 4 val_limit = 255