diff options
Diffstat (limited to 'docs/features')
-rw-r--r-- | docs/features/encoders.md | 36 | ||||
-rw-r--r-- | docs/features/key_overrides.md | 17 | ||||
-rw-r--r-- | docs/features/led_indicators.md | 7 | ||||
-rw-r--r-- | docs/features/led_matrix.md | 188 | ||||
-rw-r--r-- | docs/features/mouse_keys.md | 82 | ||||
-rw-r--r-- | docs/features/repeat_key.md | 8 | ||||
-rw-r--r-- | docs/features/rgb_matrix.md | 558 | ||||
-rw-r--r-- | docs/features/split_keyboard.md | 4 |
8 files changed, 120 insertions, 780 deletions
diff --git a/docs/features/encoders.md b/docs/features/encoders.md index 9157fe67c8..a674eaa4a6 100644 --- a/docs/features/encoders.md +++ b/docs/features/encoders.md @@ -9,15 +9,15 @@ ENCODER_ENABLE = yes and this to your `config.h`: ```c -#define ENCODERS_PAD_A { B12 } -#define ENCODERS_PAD_B { B13 } +#define ENCODER_A_PINS { B12 } +#define ENCODER_B_PINS { B13 } ``` Each PAD_A/B variable defines an array so multiple encoders can be defined, e.g.: ```c -#define ENCODERS_PAD_A { encoder1a, encoder2a } -#define ENCODERS_PAD_B { encoder1b, encoder2b } +#define ENCODER_A_PINS { encoder1a, encoder2a } +#define ENCODER_B_PINS { encoder1b, encoder2b } ``` If your encoder's clockwise directions are incorrect, you can swap the A & B pad definitions. They can also be flipped with a define: @@ -49,8 +49,8 @@ For 4× encoders you also can assign default position if encoder skips pulses wh If you are using different pinouts for the encoders on each half of a split keyboard, you can define the pinout (and optionally, resolutions) for the right half like this: ```c -#define ENCODERS_PAD_A_RIGHT { encoder1a, encoder2a } -#define ENCODERS_PAD_B_RIGHT { encoder1b, encoder2b } +#define ENCODER_A_PINS_RIGHT { encoder1a, encoder2a } +#define ENCODER_B_PINS_RIGHT { encoder1b, encoder2b } #define ENCODER_RESOLUTIONS_RIGHT { 2, 4 } ``` @@ -59,11 +59,11 @@ If the `_RIGHT` definitions aren't specified in your `config.h`, then the non-`_ Additionally, if one side does not have an encoder, you can specify `{}` for the pins/resolution -- for example, a split keyboard with only a right-side encoder: ```c -#define ENCODERS_PAD_A { } -#define ENCODERS_PAD_B { } +#define ENCODER_A_PINS { } +#define ENCODER_B_PINS { } #define ENCODER_RESOLUTIONS { } -#define ENCODERS_PAD_A_RIGHT { B12 } -#define ENCODERS_PAD_B_RIGHT { B13 } +#define ENCODER_A_PINS_RIGHT { B12 } +#define ENCODER_B_PINS_RIGHT { B13 } #define ENCODER_RESOLUTIONS_RIGHT { 4 } ``` @@ -84,10 +84,10 @@ Your `keymap.c` will then need an encoder mapping defined (for four layers and t ```c #if defined(ENCODER_MAP_ENABLE) const uint16_t PROGMEM encoder_map[][NUM_ENCODERS][NUM_DIRECTIONS] = { - [0] = { ENCODER_CCW_CW(KC_MS_WH_UP, KC_MS_WH_DOWN), ENCODER_CCW_CW(KC_VOLD, KC_VOLU) }, - [1] = { ENCODER_CCW_CW(UG_HUED, UG_HUEU), ENCODER_CCW_CW(UG_SATD, UG_SATU) }, - [2] = { ENCODER_CCW_CW(UG_VALD, UG_VALU), ENCODER_CCW_CW(UG_SPDD, UG_SPDU) }, - [3] = { ENCODER_CCW_CW(UG_PREV, UG_NEXT), ENCODER_CCW_CW(KC_RIGHT, KC_LEFT) }, + [0] = { ENCODER_CCW_CW(MS_WHLU, MS_WHLD), ENCODER_CCW_CW(KC_VOLD, KC_VOLU) }, + [1] = { ENCODER_CCW_CW(UG_HUED, UG_HUEU), ENCODER_CCW_CW(UG_SATD, UG_SATU) }, + [2] = { ENCODER_CCW_CW(UG_VALD, UG_VALU), ENCODER_CCW_CW(UG_SPDD, UG_SPDU) }, + [3] = { ENCODER_CCW_CW(UG_PREV, UG_NEXT), ENCODER_CCW_CW(KC_RIGHT, KC_LEFT) }, }; #endif ``` @@ -174,13 +174,13 @@ Multiple encoders may share pins so long as each encoder has a distinct pair of For example you can support two encoders using only 3 pins like this ``` -#define ENCODERS_PAD_A { B1, B1 } -#define ENCODERS_PAD_B { B2, B3 } +#define ENCODER_A_PINS { B1, B1 } +#define ENCODER_B_PINS { B2, B3 } ``` You could even support three encoders using only three pins (one per encoder) however in this configuration, rotating two encoders which share pins simultaneously will often generate incorrect output. For example: ``` -#define ENCODERS_PAD_A { B1, B1, B2 } -#define ENCODERS_PAD_B { B2, B3, B3 } +#define ENCODER_A_PINS { B1, B1, B2 } +#define ENCODER_B_PINS { B2, B3, B3 } ``` Here rotating Encoder 0 `B1 B2` and Encoder 1 `B1 B3` could be interpreted as rotating Encoder 2 `B2 B3` or `B3 B2` depending on the timing. This may still be a useful configuration depending on your use case diff --git a/docs/features/key_overrides.md b/docs/features/key_overrides.md index 4c568f1679..9b6015175c 100644 --- a/docs/features/key_overrides.md +++ b/docs/features/key_overrides.md @@ -14,7 +14,7 @@ You can use key overrides in a similar way to momentary layer/fn keys to activat To enable this feature, you need to add `KEY_OVERRIDE_ENABLE = yes` to your `rules.mk`. -Then, in your `keymap.c` file, you'll need to define the array `key_overrides`, which defines all key overrides to be used. Each override is a value of type `key_override_t`. The array `key_overrides` is `NULL`-terminated and contains pointers to `key_override_t` values (`const key_override_t **`). +Then, in your `keymap.c` file, you'll need to define the array `key_overrides`, which defines all key overrides to be used. Each override is a value of type `key_override_t`. The array `key_overrides`contains pointers to `key_override_t` values (`const key_override_t **`). ## Creating Key Overrides {#creating-key-overrides} @@ -42,9 +42,8 @@ This shows how the mentioned example of sending `delete` when `shift` + `backspa const key_override_t delete_key_override = ko_make_basic(MOD_MASK_SHIFT, KC_BSPC, KC_DEL); // This globally defines all key overrides to be used -const key_override_t **key_overrides = (const key_override_t *[]){ - &delete_key_override, - NULL // Null terminate the array of overrides! +const key_override_t *key_overrides[] = { + &delete_key_override }; ``` @@ -91,14 +90,13 @@ const key_override_t brightness_up_override = ko_make_with_layers_negmods_and_op const key_override_t brightness_down_override = ko_make_basic(MOD_MASK_CSA, KC_MPLY, KC_BRID); // This globally defines all key overrides to be used -const key_override_t **key_overrides = (const key_override_t *[]){ +const key_override_t *key_overrides[] = { &next_track_override, &prev_track_override, &vol_up_override, &vol_down_override, &brightness_up_override, - &brightness_down_override, - NULL + &brightness_down_override }; ``` @@ -112,10 +110,9 @@ const key_override_t tilde_esc_override = ko_make_basic(MOD_MASK_SHIFT, KC_ESC, // GUI + esc = ` const key_override_t grave_esc_override = ko_make_basic(MOD_MASK_GUI, KC_ESC, KC_GRV); -const key_override_t **key_overrides = (const key_override_t *[]){ +const key_override_t *key_overrides[] = { &tilde_esc_override, - &grave_esc_override, - NULL + &grave_esc_override }; ``` diff --git a/docs/features/led_indicators.md b/docs/features/led_indicators.md index 8435c69a55..211fda2581 100644 --- a/docs/features/led_indicators.md +++ b/docs/features/led_indicators.md @@ -21,9 +21,8 @@ There are three ways to get the lock LED state: The `host_keyboard_led_state()` may reflect an updated state before `led_update_user()` is called. ::: -Two deprecated functions that provide the LED state as `uint8_t`: +Deprecated functions that provide the LED state as `uint8_t`: -* `uint8_t led_set_user(uint8_t usb_led)` * `uint8_t host_keyboard_leds()` ## Configuration Options @@ -50,10 +49,6 @@ When the configuration options do not provide enough flexibility, the following Both receives LED state as a struct parameter. Returning `true` in `led_update_user()` will allow the keyboard level code in `led_update_kb()` to run as well. Returning `false` will override the keyboard level code, depending on how the keyboard level function is set up. -::: tip -This boolean return type of `led_update_user` allows for overriding keyboard LED controls, and is thus recommended over the void `led_set_user` function. -::: - ### Example of keyboard LED update implementation This is a template indicator function that can be implemented on keyboard level code: diff --git a/docs/features/led_matrix.md b/docs/features/led_matrix.md index f6587f7b3e..756cc11e2b 100644 --- a/docs/features/led_matrix.md +++ b/docs/features/led_matrix.md @@ -4,176 +4,32 @@ This feature allows you to use LED matrices driven by external drivers. It hooks If you want to use RGB LED's you should use the [RGB Matrix Subsystem](rgb_matrix) instead. -## Driver configuration {#driver-configuration} ---- -### IS31FL3731 {#is31fl3731} - -There is basic support for addressable LED matrix lighting with the I2C IS31FL3731 LED controller. To enable it, add this to your `rules.mk`: +## Driver Configuration {#driver-configuration} + +LED Matrix is an abstraction layer on top of an underlying LED driver API. The list of supported LED drivers is below; see the respective documentation for information on how to configure the driver. + +|Driver |Max LEDs| +|-------------------------------------|--------| +|[IS31FL3218](../drivers/is31fl3218) |18 | +|[IS31FL3236](../drivers/is31fl3236) |36 | +|[IS31FL3729](../drivers/is31fl3729) |135 | +|[IS31FL3731](../drivers/is31fl3731) |144 | +|[IS31FL3733](../drivers/is31fl3733) |192 | +|[IS31FL3736](../drivers/is31fl3736) |96 | +|[IS31FL3737](../drivers/is31fl3737) |144 | +|[IS31FL3741](../drivers/is31fl3741) |351 | +|[IS31FL3742A](../drivers/is31fl3742a)|180 | +|[IS31FL3743A](../drivers/is31fl3743a)|198 | +|[IS31FL3745](../drivers/is31fl3745) |144 | +|[IS31FL3746A](../drivers/is31fl3746a)|72 | +|[SNLED27351](../drivers/snled27351) |192 | + +To assign the LED Matrix driver, add the following to your `rules.mk`, for example: ```make -LED_MATRIX_ENABLE = yes -LED_MATRIX_DRIVER = is31fl3731 -``` - -You can use between 1 and 4 IS31FL3731 IC's. Do not specify `LED_DRIVER_ADDR_<N>` defines for IC's that are not present on your keyboard. You can define the following items in `config.h`: - -| Variable | Description | Default | -|----------|-------------|---------| -| `IS31FL3731_I2C_TIMEOUT` | (Optional) How long to wait for i2c messages, in milliseconds | 100 | -| `IS31FL3731_I2C_PERSISTENCE` | (Optional) Retry failed messages this many times | 0 | -| `LED_MATRIX_LED_COUNT` | (Required) How many LED lights are present across all drivers | | -| `IS31FL3731_I2C_ADDRESS_1` | (Required) Address for the first LED driver | | -| `IS31FL3731_I2C_ADDRESS_2` | (Optional) Address for the second LED driver | | -| `IS31FL3731_I2C_ADDRESS_3` | (Optional) Address for the third LED driver | | -| `IS31FL3731_I2C_ADDRESS_4` | (Optional) Address for the fourth LED driver | | - -Here is an example using 2 drivers. - -```c -// This is a 7-bit address, that gets left-shifted and bit 0 -// set to 0 for write, 1 for read (as per I2C protocol) -// The address will vary depending on your wiring: -// 00 AD <-> GND -// 01 AD <-> SCL -// 10 AD <-> SDA -// 11 AD <-> VCC -// ADDR represents A1:A0 of the 7-bit address. -// The result is: 0b11101(ADDR) -#define IS31FL3731_I2C_ADDRESS_1 IS31FL3731_I2C_ADDRESS_GND -#define IS31FL3731_I2C_ADDRESS_2 IS31FL3731_I2C_ADDRESS_SDA - -#define LED_DRIVER_1_LED_TOTAL 25 -#define LED_DRIVER_2_LED_TOTAL 24 -#define LED_MATRIX_LED_COUNT (LED_DRIVER_1_LED_TOTAL + LED_DRIVER_2_LED_TOTAL) -``` - -::: warning -Note the parentheses, this is so when `LED_MATRIX_LED_COUNT` is used in code and expanded, the values are added together before any additional math is applied to them. As an example, `rand() % (LED_DRIVER_1_LED_TOTAL + LED_DRIVER_2_LED_TOTAL)` will give very different results than `rand() % LED_DRIVER_1_LED_TOTAL + LED_DRIVER_2_LED_TOTAL`. -::: - -For split keyboards using `LED_MATRIX_SPLIT` with an LED driver, you can either have the same driver address or different driver addresses. If using different addresses, use `IS31FL3731_I2C_ADDRESS_1` for one and `IS31FL3731_I2C_ADDRESS_2` for the other one. Then, in `g_is31fl3731_leds`, fill out the correct driver index (0 or 1). If using one address, use `IS31FL3731_I2C_ADDRESS_1` for both, and use index 0 for `g_is31fl3731_leds`. - -Define these arrays listing all the LEDs in your `<keyboard>.c`: - -```c -const is31fl3731_led_t PROGMEM g_is31fl3731_leds[IS31FL3731_LED_COUNT] = { -/* Refer to IS31 manual for these locations - * driver - * | LED address - * | | */ - { 0, C1_1 }, - { 0, C1_15 }, - // ... -} -``` - -Where `Cx_y` is the location of the LED in the matrix defined by [the datasheet](https://www.issi.com/WW/pdf/31FL3731.pdf) and the header file `drivers/led/issi/is31fl3731-mono.h`. The `driver` is the index of the driver you defined in your `config.h` (`0`, `1`, `2`, or `3` ). - ---- -### IS31FLCOMMON {#is31flcommon} - -There is basic support for addressable LED matrix lighting with a selection of I2C ISSI Lumissil LED controllers through a shared common driver. To enable it, add this to your `rules.mk`: - -```makefile -LED_MATRIX_ENABLE = yes -LED_MATRIX_DRIVER = <driver name> +LED_MATRIX_DRIVER = is31fl3218 ``` -Where `<driver name>` is the applicable LED driver chip as below - -| Driver Name | Data Sheet | Capability | -|-------------|------------|------------| -| `IS31FL3742A` | [datasheet](https://www.lumissil.com/assets/pdf/core/IS31FL3742A_DS.pdf) | 180 LED, 30x6 Matrix | -| `IS31FL3743A` | [datasheet](https://www.lumissil.com/assets/pdf/core/IS31FL3743A_DS.pdf) | 198 LED, 18x11 Matrix | -| `IS31FL3745` | [datasheet](https://www.lumissil.com/assets/pdf/core/IS31FL3745_DS.pdf) | 144 LED, 18x8 Matrix | -| `IS31FL3746A` | [datasheet](https://www.lumissil.com/assets/pdf/core/IS31FL3746A_DS.pdf) | 72 LED, 18x4 Matrix | - -You can use between 1 and 4 IC's. Do not specify `DRIVER_ADDR_<N>` define for IC's if not present on your keyboard. The `DRIVER_ADDR_1` default assumes that all Address pins on the controller have been connected to GND. Drivers that have SYNC functionality have the default settings to disable if 1 driver. If more than 1 drivers then `DRIVER_ADDR_1` will be set to Master and the remaiing ones set to Slave. - -Configure the hardware via your `config.h`: - -| Variable | Description | Default | -|----------|-------------|---------| -| `ISSI_TIMEOUT` | (Optional) How long to wait for i2c messages, in milliseconds | 100 | -| `ISSI_PERSISTENCE` | (Optional) Retry failed messages this many times | 0 | -| `LED_MATRIX_LED_COUNT` | (Required) How many LED lights are present across all drivers | | -| `DRIVER_ADDR_1` | (Optional) Address for the first LED driver | | -| `DRIVER_ADDR_<N>` | (Required) Address for the additional LED drivers | | -| `ISSI_SSR_<N>` | (Optional) Configuration for the Spread Spectrum Register | | -| `ISSI_CONFIGURATION` | (Optional) Configuration for the Configuration Register | | -| `ISSI_GLOBALCURRENT` | (Optional) Configuration for the Global Current Register | 0xFF | -| `ISSI_PULLDOWNUP` | (Optional) Configuration for the Pull Up & Pull Down Register | | -| `ISSI_TEMP` | (Optional) Configuration for the Tempature Register | | -| `ISSI_PWM_ENABLE` | (Optional) Configuration for the PWM Enable Register | | -| `ISSI_PWM_SET` | (Optional) Configuration for the PWM Setting Register | | -| `ISSI_SCAL_LED ` | (Optional) Configuration for the LEDs Scaling Registers | 0xFF | -| `ISSI_MANUAL_SCALING` | (Optional) If you wish to configure the Scaling Registers manually | | - - -Defaults - -| Variable | IS31FL3742A | IS31FL3743A | IS31FL3745 | IS31FL3746 | -|----------|-------------|-------------|------------|------------| -| `DRIVER_ADDR_1` | 0b0110000 | 0b0100000 | 0b0100000 | 0b1100000 | -| `ISSI_SSR_1` | 0x00 | 0x00 / 0x60 | 0x00 / 0xC0 | 0x00 | -| `ISSI_SSR_<2-4>` | 0x00 | 0x40 | 0x80 | 0x00 | -| `ISSI_CONFIGURATION` | 0x31 | 0x01 | 0x31 | 0x01 | -| `ISSI_PULLDOWNUP` | 0x55 | 0x33 | 0x33 | 0x33 | -| `ISSI_TEMP` | N/A | 0x00 | 0x00 | 0x00 | -| `ISSI_PWM_ENABLE` | N/A | N/A | N/A | 0x00 | -| `ISSI_PWM_SET` | 0x00 | N/A | N/A | 0x00 | - -Here is an example using 2 drivers. - -```c -#define DRIVER_ADDR_2 0b0100001 - -#define DRIVER_1_LED_TOTAL 66 -#define DRIVER_2_LED_TOTAL 42 -#define LED_MATRIX_LED_COUNT (DRIVER_1_LED_TOTAL + DRIVER_2_LED_TOTAL) -``` -::: warning -Note the parentheses, this is so when `LED_MATRIX_LED_COUNT` is used in code and expanded, the values are added together before any additional math is applied to them. As an example, `rand() % (DRIVER_1_LED_TOTAL + DRIVER_2_LED_TOTAL)` will give very different results than `rand() % DRIVER_1_LED_TOTAL + DRIVER_2_LED_TOTAL`. -::: - -Currently only 4 drivers are supported, but it would be trivial to support for more. Note that using a combination of different drivers is not supported. All drivers must be of the same model. - -Define these arrays listing all the LEDs in your `<keyboard>.c`: - -```c -const is31_led PROGMEM g_is31_leds[LED_MATRIX_LED_COUNT] = { -/* Refer to IS31 manual for these locations - * driver - * | LED address - * | | */ - { 0, SW1_CS1 }, - { 0, SW1_CS2 }, - // ... -} -``` - -Where `CSx_SWx` is the location of the LED in the matrix defined by the datasheet. The `driver` is the index of the driver you defined in your `config.h` (`0`, `1`, `2`, or `3` for now). - -`ISSI_MANUAL_SCALING` is used to override the Scaling for individual LED's. By default they will be set as per `ISSI_SCAL_LED`. In `config.h` set how many LED's you want to manually set scaling for. -Eg `#define ISSI_MANUAL_SCALING 3` - -Then Define the array listing all the LEDs you want to override in your `<keyboard>.c`: - -```c -const is31_led PROGMEM g_is31_scaling[ISSI_MANUAL_SCALING] = { -/* LED Index - * | Scaling - * | | */ - {5, 120}, - {9, 120}, - .... -} -``` - -Where LED Index is the position of the LED in the `g_is31_leds` array. The `scaling` value between 0 and 255 to be written to the Scaling Register. - ---- - ## Common Configuration {#common-configuration} From this point forward the configuration is the same for all the drivers. The `led_config_t` struct provides a key electrical matrix to led index lookup table, what the physical position of each LED is on the board, and what type of key or usage the LED if the LED represents. Here is a brief example: diff --git a/docs/features/mouse_keys.md b/docs/features/mouse_keys.md index c2b3e98f42..4cc06c992a 100644 --- a/docs/features/mouse_keys.md +++ b/docs/features/mouse_keys.md @@ -18,27 +18,27 @@ MOUSEKEY_ENABLE = yes In your keymap you can use the following keycodes to map key presses to mouse actions: -|Key |Aliases |Description | -|----------------|---------|-----------------| -|`KC_MS_UP` |`KC_MS_U`|Move cursor up | -|`KC_MS_DOWN` |`KC_MS_D`|Move cursor down | -|`KC_MS_LEFT` |`KC_MS_L`|Move cursor left | -|`KC_MS_RIGHT` |`KC_MS_R`|Move cursor right| -|`KC_MS_BTN1` |`KC_BTN1`|Press button 1 | -|`KC_MS_BTN2` |`KC_BTN2`|Press button 2 | -|`KC_MS_BTN3` |`KC_BTN3`|Press button 3 | -|`KC_MS_BTN4` |`KC_BTN4`|Press button 4 | -|`KC_MS_BTN5` |`KC_BTN5`|Press button 5 | -|`KC_MS_BTN6` |`KC_BTN6`|Press button 6 | -|`KC_MS_BTN7` |`KC_BTN7`|Press button 7 | -|`KC_MS_BTN8` |`KC_BTN8`|Press button 8 | -|`KC_MS_WH_UP` |`KC_WH_U`|Move wheel up | -|`KC_MS_WH_DOWN` |`KC_WH_D`|Move wheel down | -|`KC_MS_WH_LEFT` |`KC_WH_L`|Move wheel left | -|`KC_MS_WH_RIGHT`|`KC_WH_R`|Move wheel right | -|`KC_MS_ACCEL0` |`KC_ACL0`|Set speed to 0 | -|`KC_MS_ACCEL1` |`KC_ACL1`|Set speed to 1 | -|`KC_MS_ACCEL2` |`KC_ACL2`|Set speed to 2 | +|Key |Aliases |Description | +|-------------------------|---------|---------------------------| +|`QK_MOUSE_CURSOR_UP` |`MS_UP` |Mouse cursor up | +|`QK_MOUSE_CURSOR_DOWN` |`MS_DOWN`|Mouse cursor down | +|`QK_MOUSE_CURSOR_LEFT` |`MS_LEFT`|Mouse cursor left | +|`QK_MOUSE_CURSOR_RIGHT` |`MS_RGHT`|Mouse cursor right | +|`QK_MOUSE_BUTTON_1` |`MS_BTN1`|Mouse button 1 | +|`QK_MOUSE_BUTTON_2` |`MS_BTN2`|Mouse button 2 | +|`QK_MOUSE_BUTTON_3` |`MS_BTN3`|Mouse button 3 | +|`QK_MOUSE_BUTTON_4` |`MS_BTN4`|Mouse button 4 | +|`QK_MOUSE_BUTTON_5` |`MS_BTN5`|Mouse button 5 | +|`QK_MOUSE_BUTTON_6` |`MS_BTN6`|Mouse button 6 | +|`QK_MOUSE_BUTTON_7` |`MS_BTN7`|Mouse button 7 | +|`QK_MOUSE_BUTTON_8` |`MS_BTN8`|Mouse button 8 | +|`QK_MOUSE_WHEEL_UP` |`MS_WHLU`|Mouse wheel up | +|`QK_MOUSE_WHEEL_DOWN` |`MS_WHLD`|Mouse wheel down | +|`QK_MOUSE_WHEEL_LEFT` |`MS_WHLL`|Mouse wheel left | +|`QK_MOUSE_WHEEL_RIGHT` |`MS_WHLR`|Mouse wheel right | +|`QK_MOUSE_ACCELERATION_0`|`MS_ACL0`|Set mouse acceleration to 0| +|`QK_MOUSE_ACCELERATION_1`|`MS_ACL1`|Set mouse acceleration to 1| +|`QK_MOUSE_ACCELERATION_2`|`MS_ACL2`|Set mouse acceleration to 2| ## Configuring mouse keys @@ -106,17 +106,17 @@ Tips: ### Constant mode -In this mode you can define multiple different speeds for both the cursor and the mouse wheel. There is no acceleration. `KC_ACL0`, `KC_ACL1` and `KC_ACL2` change the cursor and scroll speed to their respective setting. +In this mode you can define multiple different speeds for both the cursor and the mouse wheel. There is no acceleration. `MS_ACL0`, `MS_ACL1` and `MS_ACL2` change the cursor and scroll speed to their respective setting. You can choose whether speed selection is momentary or tap-to-select: * **Momentary:** The chosen speed is only active while you hold the respective key. When the key is raised, mouse keys returns to the unmodified speed. -* **Tap-to-select:** The chosen speed is activated when you press the respective key and remains active even after the key has been raised. The default speed is that of `KC_ACL1`. There is no unmodified speed. +* **Tap-to-select:** The chosen speed is activated when you press the respective key and remains active even after the key has been raised. The default speed is that of `MS_ACL1`. There is no unmodified speed. The default speeds from slowest to fastest are as follows: -* **Momentary:** `KC_ACL0` < `KC_ACL1` < *unmodified* < `KC_ACL2` -* **Tap-to-select:** `KC_ACL0` < `KC_ACL1` < `KC_ACL2` +* **Momentary:** `MS_ACL0` < `MS_ACL1` < *unmodified* < `MS_ACL2` +* **Tap-to-select:** `MS_ACL0` < `MS_ACL1` < `MS_ACL2` To use constant speed mode, you must at least define `MK_3_SPEED` in your keymap’s `config.h` file: @@ -138,32 +138,32 @@ Use the following settings if you want to adjust cursor movement or scrolling: |`MK_MOMENTARY_ACCEL` |*Not defined*|Enable momentary speed selection | |`MK_C_OFFSET_UNMOD` |16 |Cursor offset per movement (unmodified) | |`MK_C_INTERVAL_UNMOD`|16 |Time between cursor movements (unmodified) | -|`MK_C_OFFSET_0` |1 |Cursor offset per movement (`KC_ACL0`) | -|`MK_C_INTERVAL_0` |32 |Time between cursor movements (`KC_ACL0`) | -|`MK_C_OFFSET_1` |4 |Cursor offset per movement (`KC_ACL1`) | -|`MK_C_INTERVAL_1` |16 |Time between cursor movements (`KC_ACL1`) | -|`MK_C_OFFSET_2` |32 |Cursor offset per movement (`KC_ACL2`) | -|`MK_C_INTERVAL_2` |16 |Time between cursor movements (`KC_ACL2`) | +|`MK_C_OFFSET_0` |1 |Cursor offset per movement (`MS_ACL0`) | +|`MK_C_INTERVAL_0` |32 |Time between cursor movements (`MS_ACL0`) | +|`MK_C_OFFSET_1` |4 |Cursor offset per movement (`MS_ACL1`) | +|`MK_C_INTERVAL_1` |16 |Time between cursor movements (`MS_ACL1`) | +|`MK_C_OFFSET_2` |32 |Cursor offset per movement (`MS_ACL2`) | +|`MK_C_INTERVAL_2` |16 |Time between cursor movements (`MS_ACL2`) | |`MK_W_OFFSET_UNMOD` |1 |Scroll steps per scroll action (unmodified)| |`MK_W_INTERVAL_UNMOD`|40 |Time between scroll steps (unmodified) | -|`MK_W_OFFSET_0` |1 |Scroll steps per scroll action (`KC_ACL0`) | -|`MK_W_INTERVAL_0` |360 |Time between scroll steps (`KC_ACL0`) | -|`MK_W_OFFSET_1` |1 |Scroll steps per scroll action (`KC_ACL1`) | -|`MK_W_INTERVAL_1` |120 |Time between scroll steps (`KC_ACL1`) | -|`MK_W_OFFSET_2` |1 |Scroll steps per scroll action (`KC_ACL2`) | -|`MK_W_INTERVAL_2` |20 |Time between scroll steps (`KC_ACL2`) | +|`MK_W_OFFSET_0` |1 |Scroll steps per scroll action (`MS_ACL0`) | +|`MK_W_INTERVAL_0` |360 |Time between scroll steps (`MS_ACL0`) | +|`MK_W_OFFSET_1` |1 |Scroll steps per scroll action (`MS_ACL1`) | +|`MK_W_INTERVAL_1` |120 |Time between scroll steps (`MS_ACL1`) | +|`MK_W_OFFSET_2` |1 |Scroll steps per scroll action (`MS_ACL2`) | +|`MK_W_INTERVAL_2` |20 |Time between scroll steps (`MS_ACL2`) | ### Combined mode -This mode functions like **Accelerated** mode, however, you can hold `KC_ACL0`, `KC_ACL1` and `KC_ACL2` +This mode functions like **Accelerated** mode, however, you can hold `MS_ACL0`, `MS_ACL1` and `MS_ACL2` to momentarily (while held) set the cursor and scroll speeds to constant speeds. When no acceleration keys are held, this mode is identical to **Accelerated** mode, and can be modified using all of the relevant settings. -* **KC_ACL0:** This acceleration sets your cursor to the slowest possible speed. This is useful for very +* **MS_ACL0:** This acceleration sets your cursor to the slowest possible speed. This is useful for very small and detailed movements of the cursor. -* **KC_ACL1:** This acceleration sets your cursor to half the maximum (user defined) speed. -* **KC_ACL2:** This acceleration sets your cursor to the maximum (computer defined) speed. This is +* **MS_ACL1:** This acceleration sets your cursor to half the maximum (user defined) speed. +* **MS_ACL2:** This acceleration sets your cursor to the maximum (computer defined) speed. This is useful for moving the cursor large distances without much accuracy. To use combined speed mode, you must at least define `MK_COMBINED` in your keymap’s `config.h` file: diff --git a/docs/features/repeat_key.md b/docs/features/repeat_key.md index 53495e0f4d..7f2bdc44e6 100644 --- a/docs/features/repeat_key.md +++ b/docs/features/repeat_key.md @@ -60,10 +60,10 @@ with mods, like Ctrl + Left ↔ Ctrl + Right Arrow. |`KC_UP` ↔ `KC_DOWN` | Up ↔ Down Arrow | |`KC_HOME` ↔ `KC_END` | Home ↔ End | |`KC_PGUP` ↔ `KC_PGDN` | Page Up ↔ Page Down | -|`KC_MS_L` ↔ `KC_MS_R` | Mouse Cursor Left ↔ Right | -|`KC_MS_U` ↔ `KC_MS_D` | Mouse Cursor Up ↔ Down | -|`KC_WH_L` ↔ `KC_WH_R` | Mouse Wheel Left ↔ Right | -|`KC_WH_U` ↔ `KC_WH_D` | Mouse Wheel Up ↔ Down | +|`MS_LEFT` ↔ `MS_RGHT` | Mouse Cursor Left ↔ Right | +|`MS_UP` ↔ `MS_DOWN` | Mouse Cursor Up ↔ Down | +|`MS_WHLL` ↔ `MS_WHLR` | Mouse Wheel Left ↔ Right | +|`MS_WHLU` ↔ `MS_WHLD` | Mouse Wheel Up ↔ Down | **Misc** diff --git a/docs/features/rgb_matrix.md b/docs/features/rgb_matrix.md index aef766ebd2..bc14bb6277 100644 --- a/docs/features/rgb_matrix.md +++ b/docs/features/rgb_matrix.md @@ -4,543 +4,35 @@ This feature allows you to use RGB LED matrices driven by external drivers. It h If you want to use single color LED's you should use the [LED Matrix Subsystem](led_matrix) instead. -## Driver configuration {#driver-configuration} ---- -### IS31FL3731 {#is31fl3731} - -There is basic support for addressable RGB matrix lighting with the I2C IS31FL3731 RGB controller. To enable it, add this to your `rules.mk`: - -```make -RGB_MATRIX_ENABLE = yes -RGB_MATRIX_DRIVER = is31fl3731 -``` - -You can use between 1 and 4 IS31FL3731 IC's. Do not specify `DRIVER_ADDR_<N>` defines for IC's that are not present on your keyboard. You can define the following items in `config.h`: - -| Variable | Description | Default | -|----------|-------------|---------| -| `IS31FL3731_I2C_TIMEOUT` | (Optional) How long to wait for i2c messages, in milliseconds | 100 | -| `IS31FL3731_I2C_PERSISTENCE` | (Optional) Retry failed messages this many times | 0 | -| `IS31FL3731_DEGHOST` | (Optional) Set this define to enable de-ghosting by halving Vcc during blanking time | | -| `RGB_MATRIX_LED_COUNT` | (Required) How many RGB lights are present across all drivers | | -| `IS31FL3731_I2C_ADDRESS_1` | (Required) Address for the first RGB driver | | -| `IS31FL3731_I2C_ADDRESS_2` | (Optional) Address for the second RGB driver | | -| `IS31FL3731_I2C_ADDRESS_3` | (Optional) Address for the third RGB driver | | -| `IS31FL3731_I2C_ADDRESS_4` | (Optional) Address for the fourth RGB driver | | - -Here is an example using 2 drivers. - -```c -// This is a 7-bit address, that gets left-shifted and bit 0 -// set to 0 for write, 1 for read (as per I2C protocol) -// The address will vary depending on your wiring: -// 00 AD <-> GND -// 01 AD <-> SCL -// 10 AD <-> SDA -// 11 AD <-> VCC -// ADDR represents A1:A0 of the 7-bit address. -// The result is: 0b11101(ADDR) -#define IS31FL3731_I2C_ADDRESS_1 IS31FL3731_I2C_ADDRESS_GND -#define IS31FL3731_I2C_ADDRESS_2 IS31FL3731_I2C_ADDRESS_SDA - -#define DRIVER_1_LED_TOTAL 25 -#define DRIVER_2_LED_TOTAL 24 -#define RGB_MATRIX_LED_COUNT (DRIVER_1_LED_TOTAL + DRIVER_2_LED_TOTAL) -``` - -::: warning -Note the parentheses, this is so when `RGB_MATRIX_LED_COUNT` is used in code and expanded, the values are added together before any additional math is applied to them. As an example, `rand() % (DRIVER_1_LED_TOTAL + DRIVER_2_LED_TOTAL)` will give very different results than `rand() % DRIVER_1_LED_TOTAL + DRIVER_2_LED_TOTAL`. -::: - -For split keyboards using `RGB_MATRIX_SPLIT` with an LED driver, you can either have the same driver address or different driver addresses. If using different addresses, use `IS31FL3731_I2C_ADDRESS_1` for one and `IS31FL3731_I2C_ADDRESS_2` for the other one. Then, in `g_is31fl3731_leds`, fill out the correct driver index (0 or 1). If using one address, use `IS31FL3731_I2C_ADDRESS_1` for both, and use index 0 for `g_is31fl3731_leds`. - -Define these arrays listing all the LEDs in your `<keyboard>.c`: - -```c -const is31fl3731_led_t PROGMEM g_is31fl3731_leds[IS31FL3731_LED_COUNT] = { -/* Refer to IS31 manual for these locations - * driver - * | R location - * | | G location - * | | | B location - * | | | | */ - {0, C1_3, C2_3, C3_3}, - .... -} -``` - -Where `Cx_y` is the location of the LED in the matrix defined by [the datasheet](https://www.issi.com/WW/pdf/31FL3731.pdf) and the header file `drivers/led/issi/is31fl3731.h`. The `driver` is the index of the driver you defined in your `config.h` (`0`, `1`, `2`, or `3`). - ---- -### IS31FL3733 {#is31fl3733} - -There is basic support for addressable RGB matrix lighting with the I2C IS31FL3733 RGB controller. To enable it, add this to your `rules.mk`: - -```make -RGB_MATRIX_ENABLE = yes -RGB_MATRIX_DRIVER = is31fl3733 -``` - -You can use between 1 and 4 IS31FL3733 IC's. Do not specify `DRIVER_ADDR_<N>` defines for IC's that are not present on your keyboard. You can define the following items in `config.h`: - -| Variable | Description | Default | -|----------|-------------|---------| -| `IS31FL3733_I2C_TIMEOUT` | (Optional) How long to wait for i2c messages, in milliseconds | 100 | -| `IS31FL3733_I2C_PERSISTENCE` | (Optional) Retry failed messages this many times | 0 | -| `IS31FL3733_PWM_FREQUENCY` | (Optional) PWM Frequency Setting - IS31FL3733B only | 0 | -| `IS31FL3733_GLOBALCURRENT` | (Optional) Configuration for the Global Current Register | 0xFF | -| `IS31FL3733_SWPULLUP` | (Optional) Set the value of the SWx lines on-chip de-ghosting resistors | PUR_0R (Disabled) | -| `IS31FL3733_CSPULLUP` | (Optional) Set the value of the CSx lines on-chip de-ghosting resistors | PUR_0R (Disabled) | -| `RGB_MATRIX_LED_COUNT` | (Required) How many RGB lights are present across all drivers | | -| `IS31FL3733_I2C_ADDRESS_1` | (Required) Address for the first RGB driver | | -| `IS31FL3733_I2C_ADDRESS_2` | (Optional) Address for the second RGB driver | | -| `IS31FL3733_I2C_ADDRESS_3` | (Optional) Address for the third RGB driver | | -| `IS31FL3733_I2C_ADDRESS_4` | (Optional) Address for the fourth RGB driver | | -| `IS31FL3733_SYNC_1` | (Optional) Sync configuration for the first RGB driver | 0 | -| `IS31FL3733_SYNC_2` | (Optional) Sync configuration for the second RGB driver | 0 | -| `IS31FL3733_SYNC_3` | (Optional) Sync configuration for the third RGB driver | 0 | -| `IS31FL3733_SYNC_4` | (Optional) Sync configuration for the fourth RGB driver | 0 | - -The IS31FL3733 IC's have on-chip resistors that can be enabled to allow for de-ghosting of the RGB matrix. By default these resistors are not enabled (`IS31FL3733_SWPULLUP`/`IS31FL3733_CSPULLUP` are given the value of `IS31FL3733_PUR_0R`), the values that can be set to enable de-ghosting are as follows: - -| `IS31FL3733_SWPULLUP/IS31FL3733_CSPULLUP` | Description | -|----------------------|-------------| -| `IS31FL3733_PUR_0R` | (default) Do not use the on-chip resistors/enable de-ghosting | -| `IS31FL3733_PUR_05KR` | The 0.5k Ohm resistor used during blanking period (t_NOL) | -| `IS31FL3733_PUR_3KR` | The 3k Ohm resistor used at all times | -| `IS31FL3733_PUR_4KR` | The 4k Ohm resistor used at all times | -| `IS31FL3733_PUR_8KR` | The 8k Ohm resistor used at all times | -| `IS31FL3733_PUR_16KR` | The 16k Ohm resistor used at all times | -| `IS31FL3733_PUR_32KR` | The 32k Ohm resistor used during blanking period (t_NOL) | - -Here is an example using 2 drivers. - -```c -// This is a 7-bit address, that gets left-shifted and bit 0 -// set to 0 for write, 1 for read (as per I2C protocol) -// The address will vary depending on your wiring: -// 00 ADDRn <-> GND -// 01 ADDRn <-> SCL -// 10 ADDRn <-> SDA -// 11 ADDRn <-> VCC -// ADDR1 represents A1:A0 of the 7-bit address. -// ADDR2 represents A3:A2 of the 7-bit address. -// The result is: 0b101(ADDR2)(ADDR1) -#define IS31FL3733_I2C_ADDRESS_1 IS31FL3733_I2C_ADDRESS_GND_GND -#define IS31FL3733_I2C_ADDRESS_2 IS31FL3733_I2C_ADDRESS_GND_VCC - -#define DRIVER_1_LED_TOTAL 58 -#define DRIVER_2_LED_TOTAL 10 -#define RGB_MATRIX_LED_COUNT (DRIVER_1_LED_TOTAL + DRIVER_2_LED_TOTAL) -``` - -::: warning -Note the parentheses, this is so when `RGB_MATRIX_LED_COUNT` is used in code and expanded, the values are added together before any additional math is applied to them. As an example, `rand() % (DRIVER_1_LED_TOTAL + DRIVER_2_LED_TOTAL)` will give very different results than `rand() % DRIVER_1_LED_TOTAL + DRIVER_2_LED_TOTAL`. -::: - -Currently only 4 drivers are supported, but it would be trivial to support all 8 combinations. - -Define these arrays listing all the LEDs in your `<keyboard>.c`: - -```c -const is31fl3733_led_t PROGMEM g_is31fl3733_leds[IS31FL3733_LED_COUNT] = { -/* Refer to IS31 manual for these locations - * driver - * | R location - * | | G location - * | | | B location - * | | | | */ - {0, SW1_CS1, SW1_CS2, SW1_CS3}, - .... -} -``` - -Where `SWx_CSy` is the location of the LED in the matrix defined by [the datasheet](https://www.issi.com/WW/pdf/31FL3733.pdf) and the header file `drivers/led/issi/is31fl3733.h`. The `driver` is the index of the driver you defined in your `config.h` (`0`, `1`, `2`, or `3` for now). - ---- -### IS31FL3736 {#is31fl3736} - -There is basic support for addressable RGB matrix lighting with the I2C IS31FL3736 RGB controller. To enable it, add this to your `rules.mk`: - -```make -RGB_MATRIX_ENABLE = yes -RGB_MATRIX_DRIVER = is31fl3736 -``` -You can use between 1 and 4 IS31FL3736 IC's. Do not specify `DRIVER_ADDR_<N>` defines for IC's that are not present on your keyboard. - -Configure the hardware via your `config.h`: - -| Variable | Description | Default | -|----------|-------------|---------| -| `IS31FL3736_I2C_TIMEOUT` | (Optional) How long to wait for i2c messages, in milliseconds | 100 | -| `IS31FL3736_PERSISTENCE` | (Optional) Retry failed messages this many times | 0 | -| `IS31FL3736_PWM_FREQUENCY` | (Optional) PWM Frequency Setting - IS31FL3736B only | 0 | -| `IS31FL3736_GLOBALCURRENT` | (Optional) Configuration for the Global Current Register | 0xFF | -| `IS31FL3736_SWPULLUP` | (Optional) Set the value of the SWx lines on-chip de-ghosting resistors | PUR_0R (Disabled) | -| `IS31FL3736_CSPULLUP` | (Optional) Set the value of the CSx lines on-chip de-ghosting resistors | PUR_0R (Disabled) | -| `RGB_MATRIX_LED_COUNT` | (Required) How many RGB lights are present across all drivers | | -| `IS31FL3736_I2C_ADDRESS_1` | (Required) Address for the first RGB driver | | -| `IS31FL3736_I2C_ADDRESS_2` | (Optional) Address for the second RGB driver | | -| `IS31FL3736_I2C_ADDRESS_3` | (Optional) Address for the third RGB driver | | -| `IS31FL3736_I2C_ADDRESS_4` | (Optional) Address for the fourth RGB driver | | - -The IS31FL3736 IC's have on-chip resistors that can be enabled to allow for de-ghosting of the RGB matrix. By default these resistors are not enabled (`IS31FL3736_SWPULLUP`/`IS31FL3736_CSPULLUP` are given the value of `IS31FL3736_PUR_0R`), the values that can be set to enable de-ghosting are as follows: - -| `IS31FL3736_SWPULLUP/IS31FL3736_CSPULLUP` | Description | -|----------------------|-------------| -| `IS31FL3736_PUR_0R` | (default) Do not use the on-chip resistors/enable de-ghosting | -| `IS31FL3736_PUR_05KR` | The 0.5k Ohm resistor used during blanking period (t_NOL) | -| `IS31FL3736_PUR_1KR` | The 1k Ohm resistor used during blanking period (t_NOL) | -| `IS31FL3736_PUR_2KR` | The 2k Ohm resistor used during blanking period (t_NOL) | -| `IS31FL3736_PUR_4KR` | The 4k Ohm resistor used during blanking period (t_NOL) | -| `IS31FL3736_PUR_8KR` | The 8k Ohm resistor during blanking period (t_NOL) | -| `IS31FL3736_PUR_16KR` | The 16k Ohm resistor during blanking period (t_NOL) | -| `IS31FL3736_PUR_32KR` | The 32k Ohm resistor used during blanking period (t_NOL) | - -Here is an example using 2 drivers. - -```c -// This is a 7-bit address, that gets left-shifted and bit 0 -// set to 0 for write, 1 for read (as per I2C protocol) -// The address will vary depending on your wiring: -// 00 ADDRn <-> GND -// 01 ADDRn <-> SCL -// 10 ADDRn <-> SDA -// 11 ADDRn <-> VCC -// ADDR1 represents A1:A0 of the 7-bit address. -// ADDR2 represents A3:A2 of the 7-bit address. -// The result is: 0b101(ADDR2)(ADDR1) -#define IS31FL3736_I2C_ADDRESS_1 IS31FL3736_I2C_ADDRESS_GND_GND -#define IS31FL3736_I2C_ADDRESS_2 IS31FL3736_I2C_ADDRESS_GND_SCL - -#define DRIVER_1_LED_TOTAL 30 -#define DRIVER_2_LED_TOTAL 32 -#define RGB_MATRIX_LED_COUNT (DRIVER_1_LED_TOTAL + DRIVER_2_LED_TOTAL) -``` -::: warning -Note the parentheses, this is so when `RGB_MATRIX_LED_COUNT` is used in code and expanded, the values are added together before any additional math is applied to them. As an example, `rand() % (DRIVER_1_LED_TOTAL + DRIVER_2_LED_TOTAL)` will give very different results than `rand() % DRIVER_1_LED_TOTAL + DRIVER_2_LED_TOTAL`. -::: - -Define these arrays listing all the LEDs in your `<keyboard>.c`: - -```c -const is31fl3736_led_t PROGMEM g_is31fl3736_leds[IS31FL3736_LED_COUNT] = { -/* Refer to IS31 manual for these locations - * driver - * | R location - * | | G location - * | | | B location - * | | | | */ - {0, SW1_CS1, SW1_CS2, SW1_CS3}, - .... -} -``` -### IS31FL3737 {#is31fl3737} - -There is basic support for addressable RGB matrix lighting with the I2C IS31FL3737 RGB controller. To enable it, add this to your `rules.mk`: - -```make -RGB_MATRIX_ENABLE = yes -RGB_MATRIX_DRIVER = is31fl3737 -``` -You can use between 1 and 4 IS31FL3737 IC's. Do not specify `DRIVER_ADDR_<N>` defines for IC's that are not present on your keyboard. - -Configure the hardware via your `config.h`: - -| Variable | Description | Default | -|----------|-------------|---------| -| `IS31FL3737_I2C_TIMEOUT` | (Optional) How long to wait for i2c messages, in milliseconds | 100 | -| `IS31FL3737_I2C_PERSISTENCE` | (Optional) Retry failed messages this many times | 0 | -| `IS31FL3737_PWM_FREQUENCY` | (Optional) PWM Frequency Setting - IS31FL3737B only | 0 | -| `IS31FL3737_GLOBALCURRENT` | (Optional) Configuration for the Global Current Register | 0xFF | -| `IS31FL3737_SWPULLUP` | (Optional) Set the value of the SWx lines on-chip de-ghosting resistors | PUR_0R (Disabled) | -| `IS31FL3737_CSPULLUP` | (Optional) Set the value of the CSx lines on-chip de-ghosting resistors | PUR_0R (Disabled) | -| `RGB_MATRIX_LED_COUNT` | (Required) How many RGB lights are present across all drivers | | -| `IS31FL3737_I2C_ADDRESS_1` | (Required) Address for the first RGB driver | | -| `IS31FL3737_I2C_ADDRESS_2` | (Optional) Address for the second RGB driver | | -| `IS31FL3737_I2C_ADDRESS_3` | (Optional) Address for the third RGB driver | | -| `IS31FL3737_I2C_ADDRESS_4` | (Optional) Address for the fourth RGB driver | | - -The IS31FL3737 IC's have on-chip resistors that can be enabled to allow for de-ghosting of the RGB matrix. By default these resistors are not enabled (`IS31FL3737_SWPULLUP`/`IS31FL3737_CSPULLUP` are given the value of `IS31FL3737_PUR_0R`), the values that can be set to enable de-ghosting are as follows: - -| `IS31FL3737_SWPULLUP/IS31FL3737_CSPULLUP` | Description | -|----------------------|-------------| -| `IS31FL3737_PUR_0R` | (default) Do not use the on-chip resistors/enable de-ghosting | -| `IS31FL3737_PUR_05KR` | The 0.5k Ohm resistor used during blanking period (t_NOL) | -| `IS31FL3737_PUR_1KR` | The 1k Ohm resistor used during blanking period (t_NOL) | -| `IS31FL3737_PUR_2KR` | The 2k Ohm resistor used during blanking period (t_NOL) | -| `IS31FL3737_PUR_4KR` | The 4k Ohm resistor used during blanking period (t_NOL) | -| `IS31FL3737_PUR_8KR` | The 8k Ohm resistor during blanking period (t_NOL) | -| `IS31FL3737_PUR_16KR` | The 16k Ohm resistor during blanking period (t_NOL) | -| `IS31FL3737_PUR_32KR` | The 32k Ohm resistor used during blanking period (t_NOL) | - -Here is an example using 2 drivers. - -```c -// This is a 7-bit address, that gets left-shifted and bit 0 -// set to 0 for write, 1 for read (as per I2C protocol) -// The address will vary depending on your wiring: -// 0000 ADDR <-> GND -// 0101 ADDR <-> SCL -// 1010 ADDR <-> SDA -// 1111 ADDR <-> VCC -// ADDR represents A3:A0 of the 7-bit address. -// The result is: 0b101(ADDR) -#define IS31FL3737_I2C_ADDRESS_1 IS31FL3737_I2C_ADDRESS_GND -#define IS31FL3737_I2C_ADDRESS_2 IS31FL3737_I2C_ADDRESS_SCL - -#define DRIVER_1_LED_TOTAL 30 -#define DRIVER_2_LED_TOTAL 36 -#define RGB_MATRIX_LED_COUNT (DRIVER_1_LED_TOTAL + DRIVER_2_LED_TOTAL) -``` -::: warning -Note the parentheses, this is so when `RGB_MATRIX_LED_COUNT` is used in code and expanded, the values are added together before any additional math is applied to them. As an example, `rand() % (DRIVER_1_LED_TOTAL + DRIVER_2_LED_TOTAL)` will give very different results than `rand() % DRIVER_1_LED_TOTAL + DRIVER_2_LED_TOTAL`. -::: - -Define these arrays listing all the LEDs in your `<keyboard>.c`: - -```c -const is31fl3737_led_t PROGMEM g_is31fl3737_leds[IS31FL3737_LED_COUNT] = { -/* Refer to IS31 manual for these locations - * driver - * | R location - * | | G location - * | | | B location - * | | | | */ - {0, SW1_CS1, SW1_CS2, SW1_CS3}, - .... -} -``` - -Where `SWx_CSy` is the location of the LED in the matrix defined by [the datasheet](https://www.issi.com/WW/pdf/31FL3737.pdf) and the header file `drivers/led/issi/is31fl3737.h`. The `driver` is the index of the driver you defined in your `config.h` (Only `0`, `1`, `2`, or `3` for now). - ---- -### IS31FLCOMMON {#is31flcommon} - -There is basic support for addressable RGB matrix lighting with a selection of I2C ISSI Lumissil RGB controllers through a shared common driver. To enable it, add this to your `rules.mk`: - -```makefile -RGB_MATRIX_ENABLE = yes -RGB_MATRIX_DRIVER = <driver name> -``` - -Where `<driver name>` is the applicable LED driver chip as below - -| Driver Name | Data Sheet | Capability | -|-------------|------------|------------| -| `IS31FL3742A` | [datasheet](https://www.lumissil.com/assets/pdf/core/IS31FL3742A_DS.pdf) | 60 RGB, 30x6 Matrix | -| `IS31FL3743A` | [datasheet](https://www.lumissil.com/assets/pdf/core/IS31FL3743A_DS.pdf) | 66 RGB, 18x11 Matrix | -| `IS31FL3745` | [datasheet](https://www.lumissil.com/assets/pdf/core/IS31FL3745_DS.pdf) | 48 RGB, 18x8 Matrix | -| `IS31FL3746A` | [datasheet](https://www.lumissil.com/assets/pdf/core/IS31FL3746A_DS.pdf) | 24 RGB, 18x4 Matrix | - -You can use between 1 and 4 IC's. Do not specify `DRIVER_ADDR_<N>` define for IC's if not present on your keyboard. The `DRIVER_ADDR_1` default assumes that all Address pins on the controller have been connected to GND. Drivers that have SYNC functionality have the default settings to disable if 1 driver. If more than 1 drivers then `DRIVER_ADDR_1` will be set to Master and the remaining ones set to Slave. - -Configure the hardware via your `config.h`: - -| Variable | Description | Default | -|----------|-------------|---------| -| `ISSI_TIMEOUT` | (Optional) How long to wait for i2c messages, in milliseconds | 100 | -| `ISSI_PERSISTENCE` | (Optional) Retry failed messages this many times | 0 | -| `RGB_MATRIX_LED_COUNT` | (Required) How many RGB lights are present across all drivers | | -| `DRIVER_ADDR_1` | (Optional) Address for the first RGB driver | | -| `DRIVER_ADDR_<N>` | (Required) Address for the additional RGB drivers | | -| `ISSI_SSR_<N>` | (Optional) Configuration for the Spread Spectrum Register | | -| `ISSI_CONFIGURATION` | (Optional) Configuration for the Configuration Register | | -| `ISSI_GLOBALCURRENT` | (Optional) Configuration for the Global Current Register | 0xFF | -| `ISSI_PULLDOWNUP` | (Optional) Configuration for the Pull Up & Pull Down Register | | -| `ISSI_TEMP` | (Optional) Configuration for the Temperature Register | | -| `ISSI_PWM_ENABLE` | (Optional) Configuration for the PWM Enable Register | | -| `ISSI_PWM_SET` | (Optional) Configuration for the PWM Setting Register | | -| `ISSI_SCAL_RED` | (Optional) Configuration for the RED LEDs in Scaling Registers | 0xFF | -| `ISSI_SCAL_BLUE` | (Optional) Configuration for the BLUE LEDs in Scaling Registers | 0xFF | -| `ISSI_SCAL_GREEN` | (Optional) Configuration for the GREEN LEDs in Scaling Registers | 0xFF | -| `ISSI_MANUAL_SCALING` | (Optional) If you wish to configure the Scaling Registers manually | | - - -Defaults - -| Variable | IS31FL3742A | IS31FL3743A | IS31FL3745 | IS31FL3746 | -|----------|-------------|-------------|------------|------------| -| `DRIVER_ADDR_1` | 0b0110000 | 0b0100000 | 0b0100000 | 0b1100000 | -| `ISSI_SSR_1` | 0x00 | 0x00 / 0x60 | 0x00 / 0xC0 | 0x00 | -| `ISSI_SSR_<2-4>` | 0x00 | 0x40 | 0x80 | 0x00 | -| `ISSI_CONFIGURATION` | 0x31 | 0x01 | 0x31 | 0x01 | -| `ISSI_PULLDOWNUP` | 0x55 | 0x33 | 0x33 | 0x33 | -| `ISSI_TEMP` | N/A | 0x00 | 0x00 | 0x00 | -| `ISSI_PWM_ENABLE` | N/A | N/A | N/A | 0x00 | -| `ISSI_PWM_SET` | 0x00 | N/A | N/A | 0x00 | - -Here is an example using 2 drivers. - -```c -#define DRIVER_ADDR_2 0b0100001 - -#define DRIVER_1_LED_TOTAL 66 -#define DRIVER_2_LED_TOTAL 42 -#define RGB_MATRIX_LED_COUNT (DRIVER_1_LED_TOTAL + DRIVER_2_LED_TOTAL) -``` - -::: warning -Note the parentheses, this is so when `RGB_MATRIX_LED_COUNT` is used in code and expanded, the values are added together before any additional math is applied to them. As an example, `rand() % (DRIVER_1_LED_TOTAL + DRIVER_2_LED_TOTAL)` will give very different results than `rand() % DRIVER_1_LED_TOTAL + DRIVER_2_LED_TOTAL`. -::: - -Currently only 4 drivers are supported, but it would be trivial to support for more. Note that using a combination of different drivers is not supported. All drivers must be of the same model. - -Define these arrays listing all the LEDs in your `<keyboard>.c`: - -```c -const is31_led PROGMEM g_is31_leds[RGB_MATRIX_LED_COUNT] = { -/* Refer to IS31 manual for these locations - * driver - * | R location - * | | G location - * | | | B location - * | | | | */ - {0, SW1_CS1, SW1_CS2, SW1_CS3}, - .... -} -``` - -Where `CSx_SWx` is the location of the LED in the matrix defined by the datasheet. The `driver` is the index of the driver you defined in your `config.h` (`0`, `1`, `2`, or `3` for now). - -`ISSI_MANUAL_SCALING` is used to override the Scaling for individual LED's. By default they will be set as per `ISSI_SCAL_<colour>`. In `config.h` set how many LED's you want to manually set scaling for. -Eg `#define ISSI_MANUAL_SCALING 3` - -Then Define the array listing all the LEDs you want to override in your `<keyboard>.c`: - -```c -const is31_led PROGMEM g_is31_scaling[ISSI_MANUAL_SCALING] = { -/* LED Index - * | R scaling - * | | G scaling - * | | | B scaling - * | | | | */ - {5, 120, 155, 167}, - {9, 120, 155, 167}, - .... -} -``` - -Where LED Index is the position of the LED in the `g_is31_leds` array. The `scaling` value between 0 and 255 to be written to the Scaling Register. - ---- - -### WS2812 {#ws2812} - -There is basic support for addressable RGB matrix lighting with a WS2811/WS2812{a,b,c} addressable LED strand. To enable it, add this to your `rules.mk`: +## Driver Configuration {#driver-configuration} + +RGB Matrix is an abstraction layer on top of an underlying LED driver API. The list of supported LED drivers is below; see the respective documentation for information on how to configure the driver. + +|Driver |Max LEDs| +|-------------------------------------|--------| +|[APA102](../drivers/apa102) |? | +|[AW20216S](../drivers/aw20216s) |72 | +|[IS31FL3218](../drivers/is31fl3218) |6 | +|[IS31FL3236](../drivers/is31fl3236) |12 | +|[IS31FL3729](../drivers/is31fl3729) |45 | +|[IS31FL3731](../drivers/is31fl3731) |48 | +|[IS31FL3733](../drivers/is31fl3733) |64 | +|[IS31FL3736](../drivers/is31fl3736) |32 | +|[IS31FL3737](../drivers/is31fl3737) |48 | +|[IS31FL3741](../drivers/is31fl3741) |117 | +|[IS31FL3742A](../drivers/is31fl3742a)|60 | +|[IS31FL3743A](../drivers/is31fl3743a)|66 | +|[IS31FL3745](../drivers/is31fl3745) |48 | +|[IS31FL3746A](../drivers/is31fl3746a)|24 | +|[SNLED27351](../drivers/snled27351) |64 | +|[WS2812](../drivers/ws2812) |? | + +To assign the RGB Matrix driver, add the following to your `rules.mk`, for example: ```make -RGB_MATRIX_ENABLE = yes -RGB_MATRIX_DRIVER = ws2812 -``` - -Configure the hardware via your `config.h`: - -```c -// The pin connected to the data pin of the LEDs -#define WS2812_DI_PIN D7 -// The number of LEDs connected -#define RGB_MATRIX_LED_COUNT 70 +RGB_MATRIX_DRIVER = is31fl3218 ``` -::: tip -There are additional configuration options for ARM controllers that offer increased performance over the default bitbang driver. Please see [WS2812 Driver](../drivers/ws2812) for more information. -::: - ---- - -### APA102 {#apa102} - -There is basic support for APA102 based addressable LED strands. To enable it, add this to your `rules.mk`: - -```make -RGB_MATRIX_ENABLE = yes -RGB_MATRIX_DRIVER = apa102 -``` - -Configure the hardware via your `config.h`: - -```c -// The pin connected to the data pin of the LEDs -#define APA102_DI_PIN D7 -// The pin connected to the clock pin of the LEDs -#define APA102_CI_PIN D6 -// The number of LEDs connected -#define RGB_MATRIX_LED_COUNT 70 -``` - ---- -### AW20216S {#aw20216s} -There is basic support for addressable RGB matrix lighting with the SPI AW20216S RGB controller. To enable it, add this to your `rules.mk`: - -```make -RGB_MATRIX_ENABLE = yes -RGB_MATRIX_DRIVER = aw20216s -``` - -You can use up to 2 AW20216S IC's. Do not specify `DRIVER_<N>_xxx` defines for IC's that are not present on your keyboard. You can define the following items in `config.h`: - -| Variable | Description | Default | -|----------|-------------|---------| -| `AW20216S_CS_PIN_1` | (Required) MCU pin connected to first RGB driver chip select line | B13 | -| `AW20216S_CS_PIN_2` | (Optional) MCU pin connected to second RGB driver chip select line | | -| `AW20216S_EN_PIN_1` | (Required) MCU pin connected to first RGB driver hardware enable line | C13 | -| `AW20216S_EN_PIN_2` | (Optional) MCU pin connected to second RGB driver hardware enable line | | -| `DRIVER_1_LED_TOTAL` | (Required) How many RGB lights are connected to first RGB driver | | -| `DRIVER_2_LED_TOTAL` | (Optional) How many RGB lights are connected to second RGB driver | | -| `RGB_MATRIX_LED_COUNT` | (Required) How many RGB lights are present across all drivers | | -| `AW20216S_SCALING_MAX` | (Optional) LED current scaling value (0-255, higher values mean LED is brighter at full PWM) | 150 | -| `AW20216S_GLOBAL_CURRENT_MAX` | (Optional) Driver global current limit (0-255, higher values means the driver may consume more power) | 150 | -| `AW20216S_SPI_MODE` | (Optional) Mode for SPI communication (0-3, defines polarity and phase of the clock) | 3 | -| `AW20216S_SPI_DIVISOR` | (Optional) Clock divisor for SPI communication (powers of 2, smaller numbers means faster communication, should not be less than 4) | 4 | - -Here is an example using 2 drivers. - -```c -#define AW20216S_CS_PIN_1 B13 -#define AW20216S_CS_PIN_2 B14 -// Hardware enable lines may be connected to the same pin -#define AW20216S_EN_PIN_1 C13 -#define AW20216S_EN_PIN_2 C13 - -#define DRIVER_1_LED_TOTAL 66 -#define DRIVER_2_LED_TOTAL 32 -#define RGB_MATRIX_LED_COUNT (DRIVER_1_LED_TOTAL + DRIVER_2_LED_TOTAL) -``` - -::: warning -Note the parentheses, this is so when `RGB_MATRIX_LED_COUNT` is used in code and expanded, the values are added together before any additional math is applied to them. As an example, `rand() % (DRIVER_1_LED_TOTAL + DRIVER_2_LED_TOTAL)` will give very different results than `rand() % DRIVER_1_LED_TOTAL + DRIVER_2_LED_TOTAL`. -::: - -Define these arrays listing all the LEDs in your `<keyboard>.c`: - -```c -const aw20216s_led_t PROGMEM g_aw20216s_leds[AW20216S_LED_COUNT] = { -/* Each AW20216S channel is controlled by a register at some offset between 0x00 - * and 0xD7 inclusive. - * See drivers/led/aw20216s.h for the mapping between register offsets and - * driver pin locations. - * driver - * | R location - * | | G location - * | | | B location - * | | | | */ - { 0, SW1_CS1, SW1_CS2, SW1_CS3 }, - { 0, SW1_CS4, SW1_CS5, SW1_CS6 }, - { 0, SW1_CS7, SW1_CS8, SW1_CS9 }, - { 0, SW1_CS10, SW1_CS11, SW1_CS12 }, - { 0, SW1_CS13, SW1_CS14, SW1_CS15 }, - ... - { 1, SW1_CS1, SW1_CS2, SW1_CS3 }, - { 1, SW1_CS13, SW1_CS14, SW1_CS15 }, - { 1, SW1_CS16, SW1_CS17, SW1_CS18 }, - { 1, SW2_CS4, SW2_CS5, SW2_CS6 }, - ... -}; -``` - ---- - ## Common Configuration {#common-configuration} From this point forward the configuration is the same for all the drivers. The `led_config_t` struct provides a key electrical matrix to led index lookup table, what the physical position of each LED is on the board, and what type of key or usage the LED if the LED represents. Here is a brief example: diff --git a/docs/features/split_keyboard.md b/docs/features/split_keyboard.md index 6efa1c2a35..49582c3946 100644 --- a/docs/features/split_keyboard.md +++ b/docs/features/split_keyboard.md @@ -417,8 +417,8 @@ This allows you to specify a different set of pins for the matrix on the right s This allows you to specify a different set of direct pins for the right side. ```c -#define ENCODERS_PAD_A_RIGHT { encoder1a, encoder2a } -#define ENCODERS_PAD_B_RIGHT { encoder1b, encoder2b } +#define ENCODER_A_PINS_RIGHT { encoder1a, encoder2a } +#define ENCODER_B_PINS_RIGHT { encoder1b, encoder2b } ``` This allows you to specify a different set of encoder pins for the right side. |