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

Updated and linted documentation for peg_rgb_matrix.

Browse Source
This commit is contained in:
Jan Lindblom 2022-08-05 17:51:50 +03:00 committed by Kyle Brown
parent 352bf25c0d
commit 3ab11179e1
1 changed files with 52 additions and 38 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

48
docs/peg_rgb_matrix.md
View File

@ -1,35 +1,47 @@
# Peg RGB Matrix # Peg RGB Matrix
### What you can and cannot do with this extension: ## What you can and cannot do with this extension:
### Can Do
#### Can Do
* Set any key's LED to be any color in a syntax very similar to your keymap * Set any key's LED to be any color in a syntax very similar to your keymap
* Allows specific keys to be set to OFF * Allows specific keys to be set to OFF
* Allows underglow LEDs to be a different color than per-key LEDs * Allows underglow LEDs to be a different color than per-key LEDs
* Allows modifier keys to be set to a different color than alpha keys * Allows modifier keys to be set to a different color than alpha keys
* Full split keyboard support * Full split keyboard support
* Change brightness of LEDs from code or using keycodes
### Cannot Do (currently in progress)
#### Cannot Do (currently in progress)
* Adjust color at runtime. Currently the extension requires changes to main.py in order to make changes to your LEDs. * Adjust color at runtime. Currently the extension requires changes to main.py in order to make changes to your LEDs.
* Animations * Animations
* Change LED color based on current layer * Change LED color based on current layer
### Keycodes ## Keycodes
Currently this extension does not support changing LEDs at runtime, as a result there is only a single keycode available to interact with this extension and that is KC.RGB_TOG. This keycode simply toggles all your LEDs on and off.
Currently this extension does not support changing LEDs at runtime, as a result there are only three keycodes available to interact with this extension,those are:
* `KC.RGB_TOG`. This keycode simply toggles all your LEDs on and off.
* `KC.RGB_BRI`. This keycode increases the brightness of the LEDs.
* `KC.RGB_BRD`. This keycode decreases the brightness of the LEDs.
## Required Libraries ## Required Libraries
The following libraries must be frozen in your CircuitPython distribution or in a 'lib' folder at the root of your drive. The following libraries must be frozen in your CircuitPython distribution or in a 'lib' folder at the root of your drive.
* [Adafruit_CircuitPython_NeoPixel](https://github.com/adafruit/Adafruit_CircuitPython_NeoPixel) * [Adafruit_CircuitPython_NeoPixel](https://github.com/adafruit/Adafruit_CircuitPython_NeoPixel)
* [Download .mpy versions from here](https://github.com/adafruit/Adafruit_CircuitPython_Bundle/releases/download/20220415/adafruit-circuitpython-bundle-7.x-mpy-20220415.zip) * [Download .mpy versions from here](https://github.com/adafruit/Adafruit_CircuitPython_Bundle/releases/download/20220415/adafruit-circuitpython-bundle-7.x-mpy-20220415.zip)
# Required Changes to main.py and kb.py ## Required Changes to main.py and kb.py
In order to use this extension the user must make changes to both their kb.py and main.py files. Below you will find a more comprehensive list of changes required in order to use this extension. In order to use this extension the user must make changes to both their kb.py and main.py files. Below you will find a more comprehensive list of changes required in order to use this extension.
## kb.py ### kb.py
It is possible your chosen board may already have these changes made, if not you will need to make these additions: It is possible your chosen board may already have these changes made, if not you will need to make these additions:
The board's kb.py needs 3 fields: The board's kb.py needs 3 fields:
* LED Key Position `led_key_pos` * LED Key Position `led_key_pos`
* Much like `coord_mapping` this tells the extension where the LEDs are on your board. * Much like `coord_mapping` this tells the extension where the LEDs are on your board.
* Brightness Limit `brightness_limit` * Brightness Limit `brightness_limit`
@ -37,8 +49,7 @@ The board's kb.py needs 3 fields:
* Number of LEDs `num_pixels` * Number of LEDs `num_pixels`
* Used for calculations in order to ensure the LEDs map to the correct keys. * Used for calculations in order to ensure the LEDs map to the correct keys.
#### Non-split Example:
### Non-split Example:
Below shows a simple non-split example for a board containing 48 LEDs total and 38 keys with per-key LEDs. Below shows a simple non-split example for a board containing 48 LEDs total and 38 keys with per-key LEDs.
This means we will have 10 underglow LEDs and 38 per-key LEDs. This means we will have 10 underglow LEDs and 38 per-key LEDs.
@ -62,8 +73,7 @@ Underglow LEDs always appear at the end of the `led_key_pos` array, because the
num_pixels = 48 num_pixels = 48
``` ```
#### Split Example:
### Split Example:
Below shows a 58 key split keyboard's `led_key_pos` array for a board containing 70 LEDs in total. Below shows a 58 key split keyboard's `led_key_pos` array for a board containing 70 LEDs in total.
The board has 58 keys, meaning we are left with 12 underglow LEDs total. The board has 58 keys, meaning we are left with 12 underglow LEDs total.
@ -95,8 +105,8 @@ Underglow LEDs always appear at the end of the `led_key_pos` array, because the
``` ```
### main.py
## main.py
It is possible your chosen board may already have these changes made, if not you will need to make these additions: It is possible your chosen board may already have these changes made, if not you will need to make these additions:
```python ```python
@ -125,10 +135,12 @@ Rgb_matrix:
* This is optional and only serves to make all your LEDs turn on at once instead of animate to their on state. * This is optional and only serves to make all your LEDs turn on at once instead of animate to their on state.
### Colors ### Colors
Colors are RGB and can be provided in one of two ways. Colors are RGB and can be provided in one of two ways.
Colors can be defined as an array of three numbers (0-255) or you can use the `Color` class with its default colors, see example below. Colors can be defined as an array of three numbers (0-255) or you can use the `Color` class with its default colors, see example below.
### Passing RGB Codes #### Passing RGB Codes
```python ```python
Rgb_matrix_data( Rgb_matrix_data(
keys=[[255,55,55],[55,55,55],[55,55,55],[55,55,55],[55,55,55],[55,55,55],"""... rest of colors""" ], keys=[[255,55,55],[55,55,55],[55,55,55],[55,55,55],[55,55,55],[55,55,55],"""... rest of colors""" ],
@ -136,7 +148,8 @@ Rgb_matrix_data(
) )
``` ```
### Using `Color` Class #### Using `Color` Class
```python ```python
Rgb_matrix_data( Rgb_matrix_data(
keys=[Color.RED, Color.GREEN, Color.BLUE, Color.WHITE, Color.YELLOW, Color.ORANGE,"""... rest of colors""" ], keys=[Color.RED, Color.GREEN, Color.BLUE, Color.WHITE, Color.YELLOW, Color.ORANGE,"""... rest of colors""" ],
@ -163,7 +176,8 @@ rgb_ext = Rgb_matrix(ledDisplay=Rgb_matrix_data(
disable_auto_write=True) disable_auto_write=True)
``` ```
### Bonus #### Bonus
Because creating `ledDisplay` can be time consuming, there is a utility avaiable that will generate a basic framework for you. Because creating `ledDisplay` can be time consuming, there is a utility avaiable that will generate a basic framework for you.
```python ```python
@ -173,6 +187,7 @@ Rgb_matrix_data.generate_led_map(58,10,Color.WHITE,Color.BLUE)
Call `Rgb_matrix_data.generate_led_map` before you do any configuration beyond imports and it will print an `Rgb_matrix_data` class to your CircuitPython REPL which you can view by using a tool like "screen" or "PUTTY". Call `Rgb_matrix_data.generate_led_map` before you do any configuration beyond imports and it will print an `Rgb_matrix_data` class to your CircuitPython REPL which you can view by using a tool like "screen" or "PUTTY".
Generate LED Map Arguments: Generate LED Map Arguments:
* Number of Keys * Number of Keys
* Number of Underglow * Number of Underglow
* Key Color * Key Color
@ -184,6 +199,5 @@ Example Using Above Arguments:
Rgb_matrix_data(keys=[[249, 249, 249], [249, 249, 249], [249, 249, 249], [249, 249, 249], [249, 249, 249], [249, 249, 249], [249, 249, 249], [249, 249, 249], [249, 249, 249], [249, 249, 249], [249, 249, 249], [249, 249, 249], [249, 249, 249], [249, 249, 249], [249, 249, 249], [249, 249, 249], [249, 249, 249], [249, 249, 249], [249, 249, 249], [249, 249, 249], [249, 249, 249], [249, 249, 249], [249, 249, 249], [249, 249, 249], [249, 249, 249], [249, 249, 249], [249, 249, 249], [249, 249, 249], [249, 249, 249], [249, 249, 249], [249, 249, 249], [249, 249, 249], [249, 249, 249], [249, 249, 249], [249, 249, 249], [249, 249, 249], [249, 249, 249], [249, 249, 249], [249, 249, 249], [249, 249, 249], [249, 249, 249], [249, 249, 249], [249, 249, 249], [249, 249, 249], [249, 249, 249], [249, 249, 249], [249, 249, 249], [249, 249, 249], [249, 249, 249], [249, 249, 249], [249, 249, 249], [249, 249, 249], [249, 249, 249], [249, 249, 249], [249, 249, 249], [249, 249, 249], [249, 249, 249], [249, 249, 249]], Rgb_matrix_data(keys=[[249, 249, 249], [249, 249, 249], [249, 249, 249], [249, 249, 249], [249, 249, 249], [249, 249, 249], [249, 249, 249], [249, 249, 249], [249, 249, 249], [249, 249, 249], [249, 249, 249], [249, 249, 249], [249, 249, 249], [249, 249, 249], [249, 249, 249], [249, 249, 249], [249, 249, 249], [249, 249, 249], [249, 249, 249], [249, 249, 249], [249, 249, 249], [249, 249, 249], [249, 249, 249], [249, 249, 249], [249, 249, 249], [249, 249, 249], [249, 249, 249], [249, 249, 249], [249, 249, 249], [249, 249, 249], [249, 249, 249], [249, 249, 249], [249, 249, 249], [249, 249, 249], [249, 249, 249], [249, 249, 249], [249, 249, 249], [249, 249, 249], [249, 249, 249], [249, 249, 249], [249, 249, 249], [249, 249, 249], [249, 249, 249], [249, 249, 249], [249, 249, 249], [249, 249, 249], [249, 249, 249], [249, 249, 249], [249, 249, 249], [249, 249, 249], [249, 249, 249], [249, 249, 249], [249, 249, 249], [249, 249, 249], [249, 249, 249], [249, 249, 249], [249, 249, 249], [249, 249, 249]],
underglow=[[0, 0, 255], [0, 0, 255], [0, 0, 255], [0, 0, 255], [0, 0, 255], [0, 0, 255], [0, 0, 255], [0, 0, 255], [0, 0, 255], [0, 0, 255]]) underglow=[[0, 0, 255], [0, 0, 255], [0, 0, 255], [0, 0, 255], [0, 0, 255], [0, 0, 255], [0, 0, 255], [0, 0, 255], [0, 0, 255], [0, 0, 255]])
``` ```
[Connecting to the Serial Console](https://learn.adafruit.com/welcome-to-circuitpython/kattni-connecting-to-the-serial-console) [Connecting to the Serial Console](https://learn.adafruit.com/welcome-to-circuitpython/kattni-connecting-to-the-serial-console)